entrycompletion: Don't reconnect signals all the time

[~andy/gtk] / gtk / gtkrecentfilter.h

diff --git a/gtk/gtkrecentfilter.h b/gtk/gtkrecentfilter.h
index 3f868e40428aec184471bfdafbf68a6f561b7edc..3501ca8a87f9241400e0debff746348108e9b348 100644 (file)
--- a/gtk/gtkrecentfilter.h
+++ b/gtk/gtkrecentfilter.h
@@ -1,7 +1,7 @@
 /* GTK - The GIMP Toolkit
  * gtkrecentfilter.h - Filter object for recently used resources
  * Copyright (C) 2006, Emmanuele Bassi
- * 
+ *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
@@ -13,18 +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/>.
  */
 
-#if defined(GTK_DISABLE_SINGLE_INCLUDES) && !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
-#error "Only <gtk/gtk.h> can be included directly."
-#endif
-
 #ifndef __GTK_RECENT_FILTER_H__
 #define __GTK_RECENT_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
@@ -36,6 +34,21 @@ G_BEGIN_DECLS
 typedef struct _GtkRecentFilter                GtkRecentFilter;
 typedef struct _GtkRecentFilterInfo    GtkRecentFilterInfo;
 
+/**
+ * GtkRecentFilterFlags:
+ * @GTK_RECENT_FILTER_URI: the URI of the file being tested
+ * @GTK_RECENT_FILTER_DISPLAY_NAME: the string that will be used to
+ *  display the file in the recent chooser
+ * @GTK_RECENT_FILTER_MIME_TYPE: the mime type of the file
+ * @GTK_RECENT_FILTER_APPLICATION: the list of applications that have
+ *  registered the file
+ * @GTK_RECENT_FILTER_GROUP: the groups to which the file belongs to
+ * @GTK_RECENT_FILTER_AGE: the number of days elapsed since the file
+ *  has been registered
+ *
+ * These flags indicate what parts of a #GtkRecentFilterInfo struct
+ * are filled or need to be filled.
+ */
 typedef enum {
   GTK_RECENT_FILTER_URI          = 1 << 0,
   GTK_RECENT_FILTER_DISPLAY_NAME = 1 << 1,
@@ -45,9 +58,27 @@ typedef enum {
   GTK_RECENT_FILTER_AGE          = 1 << 5
 } GtkRecentFilterFlags;
 
+/**
+ * GtkRecentFilterFunc:
+ * @filter_info: a #GtkRecentFilterInfo that is filled according
+ *  to the @needed flags passed to gtk_recent_filter_add_custom()
+ * @user_data: user data passed to gtk_recent_filter_add_custom()
+ *
+ * The type of function that is used with custom filters,
+ * see gtk_recent_filter_add_custom().
+ *
+ * Return value: %TRUE if the file should be displayed
+ */
 typedef gboolean (*GtkRecentFilterFunc) (const GtkRecentFilterInfo *filter_info,
                                         gpointer                   user_data);
 
+
+/**
+ * GtkRecentFilterInfo:
+ *
+ * A GtkRecentFilterInfo struct is used
+ * to pass information about the tested file to gtk_recent_filter_filter().
+ */
 struct _GtkRecentFilterInfo
 {
   GtkRecentFilterFlags contains;
@@ -57,7 +88,7 @@ struct _GtkRecentFilterInfo
   const gchar *mime_type;
   const gchar **applications;
   const gchar **groups;
-  
+
   gint age;
 };
 
@@ -66,7 +97,7 @@ GType                 gtk_recent_filter_get_type (void) G_GNUC_CONST;
 GtkRecentFilter *     gtk_recent_filter_new      (void);
 void                  gtk_recent_filter_set_name (GtkRecentFilter *filter,
                                                  const gchar     *name);
-G_CONST_RETURN gchar *gtk_recent_filter_get_name (GtkRecentFilter *filter);
+const gchar *         gtk_recent_filter_get_name (GtkRecentFilter *filter);
 
 void gtk_recent_filter_add_mime_type      (GtkRecentFilter      *filter,
                                           const gchar          *mime_type);