diff options
Update reference manual for AutoarPref
-rw-r--r-- | gnome-autoar/autoar-pref.c | 247 | ||||
-rw-r--r-- | gnome-autoar/autoar-pref.h | 7 |
2 files changed, 254 insertions, 0 deletions
diff --git a/gnome-autoar/autoar-pref.c b/gnome-autoar/autoar-pref.c index ae353ab..fab2150 100644 --- a/gnome-autoar/autoar-pref.c +++ b/gnome-autoar/autoar-pref.c @@ -32,6 +32,30 @@ #include <glib.h> #include <string.h> +/** + * SECTION:autoar-pref + * @Short_description: Prefrences related to archives + * @Title: AutoarPref + * @Include: gnome-autoar/autoar.h + * + * The #AutoarPref is used to store the user preferences related to archives. + * It is a required argument to create an #AutoarCreate or #AutoarExtract + * object. It also provides some convenient methods to read and write settings + * with #GSettings, or check whether a file should be regarded as an archive. + * An #AutoarPref can be used multiple times, so you can use the same + * #AutoarPref object to create many #AutoarCreate or #AutoarExtract objects. + * + * In order to allow applications to override user preferences, no binding is + * created between the #AutoarPref object and the #GSettings object in order + * to prevent unnecesssary writes. #AutoarPref holds no reference to the + * #GSettings object, too. Additionally, there are modification + * flags for each property inside the #AutoarPref object, so + * autoar_pref_write_gsettings() only writes settings which are changed + * since the last call to autoar_pref_read_gsettings(). + * If you do not like this behavior, there are also methods + * provided to override it. + **/ + G_DEFINE_TYPE (AutoarPref, autoar_pref, G_TYPE_OBJECT) #define AUTOAR_PREF_GET_PRIVATE(o) \ @@ -154,6 +178,14 @@ autoar_pref_set_property (GObject *object, } } +/** + * autoar_pref_get_default_format: + * @arpref: an #AutoarPref + * + * Gets the default format for new archives. + * + * Returns: an #AutoarFormat + **/ AutoarFormat autoar_pref_get_default_format (AutoarPref *arpref) { @@ -161,6 +193,14 @@ autoar_pref_get_default_format (AutoarPref *arpref) return arpref->priv->default_format; } +/** + * autoar_pref_get_default_filter: + * @arpref: an #AutoarPref + * + * Gets the default filter for new archives. + * + * Returns: an #AutoarFilter + **/ AutoarFilter autoar_pref_get_default_filter (AutoarPref *arpref) { @@ -168,6 +208,14 @@ autoar_pref_get_default_filter (AutoarPref *arpref) return arpref->priv->default_filter; } +/** + * autoar_pref_get_file_name_suffix: + * @arpref: an #AutoarPref + * + * Gets the list of file name extensions which should be regarded as archives. + * + * Returns: (transfer none): a %NULL-terminated array of strings + **/ const char** autoar_pref_get_file_name_suffix (AutoarPref *arpref) { @@ -175,6 +223,14 @@ autoar_pref_get_file_name_suffix (AutoarPref *arpref) return (const char**)(arpref->priv->file_name_suffix); } +/** + * autoar_pref_get_file_mime_type: + * @arpref: an #AutoarPref + * + * Gets the list of MIME types which should be regarded as archives. + * + * Returns: (transfer none): a %NULL-terminated array of strings + **/ const char** autoar_pref_get_file_mime_type (AutoarPref *arpref) { @@ -182,6 +238,16 @@ autoar_pref_get_file_mime_type (AutoarPref *arpref) return (const char**)(arpref->priv->file_mime_type); } +/** + * autoar_pref_get_pattern_to_ignore: + * @arpref: an #AutoarPref + * + * Gets the list of filename patterns which will be ignored when extracting + * archives. That is, a file will not be extracted from the archive if its + * name matches any patterns in the list. + * + * Returns: (transfer none): a %NULL-terminated array of strings + **/ const char** autoar_pref_get_pattern_to_ignore (AutoarPref *arpref) { @@ -189,6 +255,15 @@ autoar_pref_get_pattern_to_ignore (AutoarPref *arpref) return (const char**)(arpref->priv->pattern_to_ignore); } +/** + * autoar_pref_get_delete_if_succeed: + * @arpref: an #AutoarPref + * + * Gets whether the source archive will be deleted after it is successfully + * extracted. + * + * Returns: %TRUE if the source archive should be deleted + **/ gboolean autoar_pref_get_delete_if_succeed (AutoarPref *arpref) { @@ -196,6 +271,13 @@ autoar_pref_get_delete_if_succeed (AutoarPref *arpref) return arpref->priv->delete_if_succeed; } +/** + * autoar_pref_set_default_format: + * @arpref: an #AutoarPref + * @format: a valid #AutoarFormat + * + * See autoar_pref_get_default_format(). + **/ void autoar_pref_set_default_format (AutoarPref *arpref, AutoarFormat format) @@ -207,6 +289,13 @@ autoar_pref_set_default_format (AutoarPref *arpref, arpref->priv->default_format = format; } +/** + * autoar_pref_set_default_filter: + * @arpref: an #AutoarPref + * @filter: a valid #AutoarFilter + * + * See autoar_pref_get_default_filter(). + **/ void autoar_pref_set_default_filter (AutoarPref *arpref, AutoarFilter filter) @@ -218,6 +307,13 @@ autoar_pref_set_default_filter (AutoarPref *arpref, arpref->priv->default_filter = filter; } +/** + * autoar_pref_set_file_name_suffix: + * @arpref: an #AutoarPref + * @strv: a %NULL-terminated array of strings + * + * See autoar_pref_get_file_name_suffix(). + **/ void autoar_pref_set_file_name_suffix (AutoarPref *arpref, const char **strv) @@ -230,6 +326,13 @@ autoar_pref_set_file_name_suffix (AutoarPref *arpref, arpref->priv->file_name_suffix = g_strdupv ((char**)strv); } +/** + * autoar_pref_set_file_mime_type: + * @arpref: an #AutoarPref + * @strv: a %NULL-terminated array of strings + * + * See autoar_pref_get_file_mime_type(). + **/ void autoar_pref_set_file_mime_type (AutoarPref *arpref, const char **strv) @@ -242,6 +345,13 @@ autoar_pref_set_file_mime_type (AutoarPref *arpref, arpref->priv->file_mime_type = g_strdupv ((char**)strv); } +/** + * autoar_pref_set_pattern_to_ignore: + * @arpref: an #AutoarPref + * @strv: a %NULL-terminated array of strings + * + * See autoar_pref_get_pattern_to_ignore(). + **/ void autoar_pref_set_pattern_to_ignore (AutoarPref *arpref, const char **strv) @@ -254,6 +364,13 @@ autoar_pref_set_pattern_to_ignore (AutoarPref *arpref, arpref->priv->pattern_to_ignore = g_strdupv ((char**)strv); } +/** + * autoar_pref_set_delete_if_succeed: + * @arpref: an #AutoarPref + * @delete_yes: %TRUE if the source archive should be deleted + * + * See autoar_pref_get_delete_if_succeed(). + **/ void autoar_pref_set_delete_if_succeed (AutoarPref *arpref, gboolean delete_yes) @@ -378,12 +495,29 @@ autoar_pref_init (AutoarPref *arpref) priv->delete_if_succeed = TRUE; } +/** + * autoar_pref_new: + * + * Create a new #AutoarPref object. All strings will be initialized as %NULL. + * + * Returns: (transfer full): a new #AutoarPref object + **/ AutoarPref* autoar_pref_new (void) { return g_object_new (AUTOAR_TYPE_PREF, NULL); } +/** + * autoar_pref_new_with_gsettings: + * @settings: a #GSettings object to read settings from + * + * Create a new #AutoarPref object and read settings from @settings. Calling + * this function is equivalent to calling autoar_pref_read_gsettings() on + * the object returned by autoar_pref_new(). + * + * Returns: (transfer full): a new #AutoarPref object + **/ AutoarPref* autoar_pref_new_with_gsettings (GSettings *settings) { @@ -393,6 +527,13 @@ autoar_pref_new_with_gsettings (GSettings *settings) return arpref; } +/** + * autoar_pref_read_gsettings: + * @arpref: an #AutoarPref object + * @settings: a #GSettings object to read settings from + * + * Read settings from @settings. + **/ void autoar_pref_read_gsettings (AutoarPref *arpref, GSettings *settings) @@ -416,6 +557,22 @@ autoar_pref_read_gsettings (AutoarPref *arpref, arpref->priv->modification_flags = MODIFIED_NONE; } +/** + * autoar_pref_write_gsettings: + * @arpref: an #AutoarPref object + * @settings: a #GSettings object to write settings to + * + * Write settings to @settings. If you do not read from #GSettings before + * calling this functions, it will be the same as calling + * autoar_pref_write_gsettings_force(). If autoar_pref_read_gsettings() + * has called on @arpref, or @arpref is created using + * autoar_pref_new_with_gsettings(), only settings changed since the last + * time reading from #GSettings will be written. + * + * It is allowed to write to a #GSettings object which is different from the + * object you read from. However, #AutoarPref cannot detect this situation, + * and you may want to call autoar_pref_write_gsettings_force() instead. + **/ void autoar_pref_write_gsettings (AutoarPref *arpref, GSettings *settings) @@ -453,6 +610,15 @@ autoar_pref_write_gsettings (AutoarPref *arpref, } } +/** + * autoar_pref_write_gsettings_force: + * @arpref: an #AutoarPref object + * @settings: a #GSettings object to write settings to + * + * Write settings to @settings, ignoring the internal modification flags of + * #AutoarPref. All properties will be written even if it is not changed, and + * modification flags are not cleared after calling this function. + **/ void autoar_pref_write_gsettings_force (AutoarPref *arpref, GSettings *settings) @@ -468,6 +634,15 @@ autoar_pref_write_gsettings_force (AutoarPref *arpref, g_settings_set_boolean (settings, KEY_DELETE_IF_SUCCEED, arpref->priv->delete_if_succeed); } +/** + * autoar_pref_has_changes: + * @arpref: an #AutoarPref object + * + * Gets whether there are changes to properties which are not written. + * + * Returns: %TRUE if there are changes since the last reading from #GSettings. + * %FALSE if there is no change or you have not read from #GSettings. + **/ gboolean autoar_pref_has_changes (AutoarPref *arpref) { @@ -475,6 +650,14 @@ autoar_pref_has_changes (AutoarPref *arpref) return (arpref->priv->modification_enabled && arpref->priv->modification_flags); } +/** + * autoar_pref_forget_changes: + * @arpref: an #AutoarPref object + * + * Clear the modification flags, so the next call to + * autoar_pref_write_gsettings() will write nothing if you have read from + * #GSettings before calling it. + **/ void autoar_pref_forget_changes (AutoarPref *arpref) { @@ -482,6 +665,17 @@ autoar_pref_forget_changes (AutoarPref *arpref) arpref->priv->modification_flags = MODIFIED_NONE; } +/** + * autoar_pref_check_file_name: + * @arpref: an #AutoarPref object + * @filepath: the filename or the path of the file + * + * Checks whether the file @filepath has the suffix listed in + * #AutoarPref:file-name-suffix. This function does not do any + * I/O operation. + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_file_name (AutoarPref *arpref, const char *filepath) @@ -498,6 +692,17 @@ autoar_pref_check_file_name (AutoarPref *arpref, return autoar_pref_check_file_name_d (arpref, dot_location + 1); } +/** + * autoar_pref_check_file_name_file: + * @arpref: an #AutoarPref object + * @file: a #GFile object + * + * Checks whether the file @file has the suffix listed in + * #AutoarPref:file-name-suffix. This function does not do any + * I/O operation. + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_file_name_file (AutoarPref *arpref, GFile *file) @@ -515,6 +720,17 @@ autoar_pref_check_file_name_file (AutoarPref *arpref, return result; } +/** + * autoar_pref_check_file_name_d: + * @arpref: an #AutoarPref object + * @extension: a file name extension + * + * Checks whether @extension is listed in #AutoarPref:file-name-suffix. + * This function is the same as comparing @extension with strings using + * strcmp(). + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_file_name_d (AutoarPref *arpref, const char *extension) @@ -532,6 +748,16 @@ autoar_pref_check_file_name_d (AutoarPref *arpref, return FALSE; } +/** + * autoar_pref_check_mime_type: + * @arpref: an #AutoarPref object + * @filepath: the filename or the path of the file + * + * Checks whether the MIME type of @filepath is listed in + * #AutoarPref:file-mime-type. + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_mime_type (AutoarPref *arpref, const char *filepath) @@ -549,6 +775,16 @@ autoar_pref_check_mime_type (AutoarPref *arpref, return result; } +/** + * autoar_pref_check_mime_type_file: + * @arpref: an #AutoarPref object + * @file: a #GFile object + * + * Checks whether the MIME type of @file is listed in + * #AutoarPref:file-mime-type. + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_mime_type_file (AutoarPref *arpref, GFile *file) @@ -583,6 +819,17 @@ autoar_pref_check_mime_type_file (AutoarPref *arpref, return result; } +/** + * autoar_pref_check_mime_type_d: + * @arpref: an #AutoarPref object + * @mime_type: a MIME type + * + * Checks whether @mime_type is listed in #AutoarPref:file-mime-type. + * This function is the same as comparing @mime_type with strings using + * strcmp(). + * + * Returns: %TRUE if it is matched + **/ gboolean autoar_pref_check_mime_type_d (AutoarPref *arpref, const char *mime_type) diff --git a/gnome-autoar/autoar-pref.h b/gnome-autoar/autoar-pref.h index 0aadaa3..500954e 100644 --- a/gnome-autoar/autoar-pref.h +++ b/gnome-autoar/autoar-pref.h @@ -33,6 +33,13 @@ G_BEGIN_DECLS +/** + * AUTOAR_PREF_DEFAULT_GSCHEMA_ID: + * + * Default #GSettings schema ID for storing and retrieving user preferences + * in the #AutoarPref object. If you want to share preferences related to + * archives with other applications, you should use this schema ID. + **/ #define AUTOAR_PREF_DEFAULT_GSCHEMA_ID "org.gnome.desktop.archives" #define AUTOAR_TYPE_PREF autoar_pref_get_type () |