X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkfilefilter.h;h=ab952dee7ef4e07f11be88fe084a15e87d1820d9;hb=563eb60666d9f72c38d7542b0ab37841e6aac488;hp=a4b909b0a4355353887ebbcf06101988354c7551;hpb=7a08ab25a676c665455d5f4c3a74872aa5be31d4;p=~andy%2Fgtk

diff --git a/gtk/gtkfilefilter.h b/gtk/gtkfilefilter.h
index a4b909b0a..ab952dee7 100644
--- a/gtk/gtkfilefilter.h
+++ b/gtk/gtkfilefilter.h
@@ -13,14 +13,16 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef __GTK_FILE_FILTER_H__
 #define __GTK_FILE_FILTER_H__
 
+#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
+#error "Only <gtk/gtk.h> can be included directly."
+#endif
+
 #include <glib-object.h>
 
 G_BEGIN_DECLS
@@ -32,6 +34,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,
@@ -39,25 +52,49 @@ 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: (closure): 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;
-  
+
   const gchar *filename;
   const gchar *uri;
   const gchar *display_name;
   const gchar *mime_type;
 };
 
-GType gtk_file_filter_get_type (void);
+GType gtk_file_filter_get_type (void) G_GNUC_CONST;
 
 GtkFileFilter *       gtk_file_filter_new      (void);
 void                  gtk_file_filter_set_name (GtkFileFilter *filter,
 						const gchar   *name);
-G_CONST_RETURN gchar *gtk_file_filter_get_name (GtkFileFilter *filter);
+const gchar *         gtk_file_filter_get_name (GtkFileFilter *filter);
 
 void gtk_file_filter_add_mime_type      (GtkFileFilter      *filter,
 					 const gchar        *mime_type);