From 09d395f629381b33dc9ec520a0393a709b5f6df8 Mon Sep 17 00:00:00 2001 From: Pavel Holejsovsky Date: Sat, 15 Jan 2011 14:50:50 +0100 Subject: [PATCH] Move GtkFileFilter docs inline --- docs/reference/gtk/tmpl/.gitignore | 1 + docs/reference/gtk/tmpl/gtkfilefilter.sgml | 170 --------------------- gtk/gtkfilefilter.c | 24 +++ gtk/gtkfilefilter.h | 35 +++++ 4 files changed, 60 insertions(+), 170 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkfilefilter.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 1758fee30a..e7c14a5afa 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -27,6 +27,7 @@ gtkeventbox.sgml gtkexpander.sgml gtkfeatures.sgml gtkfixed.sgml +gtkfilefilter.sgml gtkhbox.sgml gtkiconview.sgml gtkimcontextsimple.sgml diff --git a/docs/reference/gtk/tmpl/gtkfilefilter.sgml b/docs/reference/gtk/tmpl/gtkfilefilter.sgml deleted file mode 100644 index 4f22a3cca7..0000000000 --- a/docs/reference/gtk/tmpl/gtkfilefilter.sgml +++ /dev/null @@ -1,170 +0,0 @@ - -GtkFileFilter - - -A filter for selecting a file subset - - - -A GtkFileFilter can be used to restrict the files being shown -in a #GtkFileChooser. Files can be filtered based on their name -(with gtk_file_filter_add_pattern()), on their mime type (with -gtk_file_filter_add_mime_type()), or by a custom filter function -(with gtk_file_filter_add_custom()). - - - -Filtering by mime types handles aliasing and subclassing of mime -types; e.g. a filter for text/plain also matches a file with mime -type application/rtf, since application/rtf is a subclass of -text/plain. Note that #GtkFileFilter allows wildcards for the -subtype of a mime type, so you can e.g. filter for image/*. - - - -Normally, filters are used by adding them to a #GtkFileChooser, -see gtk_file_chooser_add_filter(), but it is also possible -to manually use a filter on a file with gtk_file_filter_filter(). - - - - -#GtkFileChooser - - - - - - - - - - -The GtkFileFilter struct contains -only private fields and should not be directly accessed. - - - - - -A GtkFileFilterInfo struct is used -to pass information about the tested file to -gtk_file_filter_filter(). - - -@contains: Flags indicating which of the following fields need - are filled -@filename: the filename of the file being tested -@uri: the URI for the file being tested -@display_name: the string that will be used to display the file - in the file chooser -@mime_type: the mime type of the file - - - -These flags indicate what parts of a #GtkFileFilterInfo struct -are filled or need to be filled. - - -@GTK_FILE_FILTER_FILENAME: the filename of the file being tested -@GTK_FILE_FILTER_URI: the URI for the file being tested -@GTK_FILE_FILTER_DISPLAY_NAME: the string that will be used to - display the file in the file chooser -@GTK_FILE_FILTER_MIME_TYPE: the mime type of the file - - - -The type of function that is used with custom filters, -see gtk_file_filter_add_custom(). - - -@filter_info: a #GtkFileFilterInfo that is filled according - to the @needed flags passed to gtk_file_filter_add_custom() -@data: user data passed to gtk_file_filter_add_custom() -@Returns: %TRUE if the file should be displayed - - - - - - - -@void: -@Returns: - - - - - - - -@filter: -@name: - - - - - - - -@filter: -@Returns: - - - - - - - -@filter: -@mime_type: - - - - - - - -@filter: -@pattern: - - - - - - - -@filter: - - - - - - - -@filter: -@needed: -@func: -@data: -@notify: - - - - - - - -@filter: -@Returns: - - - - - - - -@filter: -@filter_info: -@Returns: - - diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c index 04f3c55cf7..cdfb6cbedf 100644 --- a/gtk/gtkfilefilter.c +++ b/gtk/gtkfilefilter.c @@ -18,6 +18,30 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtkfilefilter + * @Short_description: A filter for selecting a file subset + * @Title: GtkFileFilter + * + * A GtkFileFilter can be used to restrict the files being shown in a + * #GtkFileChooser. Files can be filtered based on their name (with + * gtk_file_filter_add_pattern()), on their mime type (with + * gtk_file_filter_add_mime_type()), or by a custom filter function + * (with gtk_file_filter_add_custom()). + * + * Filtering by mime types handles aliasing and subclassing of mime + * types; e.g. a filter for text/plain also matches a file with mime + * type application/rtf, since application/rtf is a subclass of + * text/plain. Note that #GtkFileFilter allows wildcards for the + * subtype of a mime type, so you can e.g. filter for image/*. + * + * Normally, filters are used by adding them to a #GtkFileChooser, + * see gtk_file_chooser_add_filter(), but it is also possible + * to manually use a filter on a file with gtk_file_filter_filter(). + * + * @see_also: #GtkFileChooser + */ + #include "config.h" #include diff --git a/gtk/gtkfilefilter.h b/gtk/gtkfilefilter.h index 7a848e51a5..c566ef17a8 100644 --- a/gtk/gtkfilefilter.h +++ b/gtk/gtkfilefilter.h @@ -36,6 +36,17 @@ G_BEGIN_DECLS typedef struct _GtkFileFilter GtkFileFilter; typedef struct _GtkFileFilterInfo GtkFileFilterInfo; +/** + * GtkFileFilterFlags: + * @GTK_FILE_FILTER_FILENAME: the filename of the file being tested + * @GTK_FILE_FILTER_URI: the URI for the file being tested + * @GTK_FILE_FILTER_DISPLAY_NAME: the string that will be used to + * display the file in the file chooser + * @GTK_FILE_FILTER_MIME_TYPE: the mime type of the file + * + * These flags indicate what parts of a #GtkFileFilterInfo struct + * are filled or need to be filled. + */ typedef enum { GTK_FILE_FILTER_FILENAME = 1 << 0, GTK_FILE_FILTER_URI = 1 << 1, @@ -43,9 +54,33 @@ typedef enum { GTK_FILE_FILTER_MIME_TYPE = 1 << 3 } GtkFileFilterFlags; +/** + * GtkFileFilterFunc: + * @filter_info: a #GtkFileFilterInfo that is filled according + * to the @needed flags passed to gtk_file_filter_add_custom() + * @data: user data passed to gtk_file_filter_add_custom() + * + * The type of function that is used with custom filters, see + * gtk_file_filter_add_custom(). + * + * @Returns: %TRUE if the file should be displayed + */ typedef gboolean (*GtkFileFilterFunc) (const GtkFileFilterInfo *filter_info, gpointer data); +/** + * GtkFileFilterInfo: + * @contains: Flags indicating which of the following fields need + * are filled + * @filename: the filename of the file being tested + * @uri: the URI for the file being tested + * @display_name: the string that will be used to display the file + * in the file chooser + * @mime_type: the mime type of the file + * + * A #GtkFileFilterInfo struct is used to pass information about the + * tested file to gtk_file_filter_filter(). + */ struct _GtkFileFilterInfo { GtkFileFilterFlags contains;