Add documentation for properties and fix the deprecation marker for the

2007-07-29  Emmanuele Bassi  <ebassi@gnome.org>

	* gtk/gtkrecentchooser.c: Add documentation for properties
	and fix the deprecation marker for the show-numbers
	accessor functions (Murray Cumming).

	* gtk/gtkrecentchooser.h: Add deprecation guards around
	gtk_recent_chooser_set_show_numbers() and
	gtk_recent_chooser_get_show_numbers(), as promised during
	last development cycle.

svn path=/trunk/; revision=18556

diff --git a/ChangeLog b/ChangeLog
index 46acb05080be22bb876d0ac0d70a2e69b40013bd..cef22d4c0486f20763d3ec19a068ff030415e8ed 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2007-07-29  Emmanuele Bassi  <ebassi@gnome.org>
+
+       * gtk/gtkrecentchooser.c: Add documentation for properties
+       and fix the deprecation marker for the show-numbers
+       accessor functions (Murray Cumming).
+
+       * gtk/gtkrecentchooser.h: Add deprecation guards around
+       gtk_recent_chooser_set_show_numbers() and
+       gtk_recent_chooser_get_show_numbers(), as promised during
+       last development cycle.
+
 2007-07-27  Attilio Fiandrotti  <attilio.fiandrotti@gmail.com>
 
         * gdk/directfb/gdkcursor-directfb.c: Attempts to load

diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml
index dbe311bd669aedd312b99232457b4577973be798..3e134f8ec08765dcc08bd86b075b34ad65441a12 100644 (file)
--- a/docs/reference/gtk/tmpl/gtk-unused.sgml
+++ b/docs/reference/gtk/tmpl/gtk-unused.sgml
@@ -925,78 +925,12 @@ You may not attach these to signals created with the
 </para>
 
 
-<!-- ##### ARG GtkFileChooser:action ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### ARG GtkFileChooser:file-system ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:filter ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:local-only ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### ENUM GtkFontFilterType ##### -->
 <para>
 A set of bit flags used to specify the filter being set
@@ -1278,66 +1212,6 @@ after other user handlers and the default handler.
 </para>
 
 
-<!-- ##### ARG GtkRecentChooser:filter ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:limit ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:local-only ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:recent-manager ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:select-multiple ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-icons ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-not-found ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-private ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-tips ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:sort-type ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### ARG GtkScrolledWindow:shadow ##### -->
 <para>
 

diff --git a/docs/reference/gtk/tmpl/gtkfilechooser.sgml b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
index ef7f17a2fc4fe842de9dc4eb917f3f654b5d5a2a..a24691a9126686a3fc75258c867ae26e0b4d4924 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkfilechooser.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilechooser.sgml
@@ -672,6 +672,61 @@ gtk_widget_destroy (chooser);
 
 @filechooser: the object which received the signal.
 
+<!-- ##### ARG GtkFileChooser:action ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:filter ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:local-only ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
+<para>
+
+</para>
+
 <!-- ##### ENUM GtkFileChooserAction ##### -->
     <para>
       Describes whether a #GtkFileChooser is being used to open

diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml
index ba13035ad97ff3f0b0043032ec143748ef18a55d..4316b4f755732b1c9de592b84212f5b8d59d4067 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkobject.sgml
+++ b/docs/reference/gtk/tmpl/gtkobject.sgml
@@ -134,6 +134,8 @@ Tells about the state of the object.
 
 @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used 
   internally by GTK+ to prevent reinvokations during destruction.
+@GTK_FLOATING: 
+@GTK_RESERVED_1: 
 @GTK_RESERVED_2: reserved for future use
 
 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->

diff --git a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml
index 7464b866901bc87519cc3e25590d972e9f15863e..85013ba6f80ee4bbad8adcf6858e2721be5e1958 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkrecentchooser.sgml
+++ b/docs/reference/gtk/tmpl/gtkrecentchooser.sgml
@@ -45,6 +45,56 @@ Recently used files are supported since GTK+ 2.10.
 
 @recentchooser: the object which received the signal.
 
+<!-- ##### ARG GtkRecentChooser:filter ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:limit ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:local-only ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:recent-manager ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:select-multiple ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-icons ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-not-found ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-private ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-tips ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:sort-type ##### -->
+<para>
+
+</para>
+
 <!-- ##### STRUCT GtkRecentChooserIface ##### -->
 <para>
 

diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 030855ee964790ead9736c066b045c6f1dc9da1f..d0e7df52bc6456dc4eb2969e4adf730794bb38de 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -52,6 +52,8 @@ accessed through the function described below.
 @orientation: 
 @style: 
 @icon_size: 
+@tooltips: 
+@_tooltips: 
 
 <!-- ##### SIGNAL GtkToolbar::focus-home-or-end ##### -->
 <para>

diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c
index ef16d777669204965b4dadc90e606122198e4e35..a3a5e9acb4798cd723fef880b978e04c176e1996 100644 (file)
--- a/gtk/gtkrecentchooser.c
+++ b/gtk/gtkrecentchooser.c
@@ -106,49 +106,117 @@ gtk_recent_chooser_class_init (gpointer g_iface)
                  NULL, NULL,
                  g_cclosure_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
- 
+
+  /**
+   * GtkRecentChooser:recent-manager:
+   *
+   * The #GtkRecentManager instance used by the #GtkRecentChooser to
+   * display the list of recently used resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_object ("recent-manager",
                                                            P_("Recent Manager"),
                                                            P_("The RecentManager object to use"),
                                                            GTK_TYPE_RECENT_MANAGER,
                                                            GTK_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
+  /**
+   * GtkRecentManager:show-private:
+   *
+   * Whether this #GtkRecentChooser should display recently used resources
+   * marked with the "private" flag. Such resources should be considered
+   * private to the applications and groups that have added them.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("show-private",
                                                             P_("Show Private"),
                                                             P_("Whether the private items should be displayed"),
                                                             FALSE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:show-tips:
+   *
+   * Whether this #GtkRecentChooser should display a tooltip containing the
+   * full path of the recently used resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("show-tips",
                                                             P_("Show Tooltips"),
                                                             P_("Whether there should be a tooltip on the item"),
                                                             FALSE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:show-icons:
+   *
+   * Whether this #GtkRecentChooser should display an icon near the item.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("show-icons",
                                                             P_("Show Icons"),
                                                             P_("Whether there should be an icon near the item"),
                                                             TRUE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:show-not-found:
+   *
+   * Whether this #GtkRecentChooser should display the recently used resources
+   * even if not present anymore. Setting this to %FALSE will perform a
+   * potentially expensive check on every local resource (every remote
+   * resource will always be displayed).
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("show-not-found",
                                                             P_("Show Not Found"),
                                                             P_("Whether the items pointing to unavailable resources should be displayed"),
                                                             FALSE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:select-multiple:
+   *
+   * Allow the user to select multiple resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("select-multiple",
                                                             P_("Select Multiple"),
                                                             P_("Whether to allow multiple items to be selected"),
                                                             FALSE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:local-only:
+   *
+   * Whether this #GtkRecentChooser should display only local (file:)
+   * resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_boolean ("local-only",
                                                             P_("Local only"),
                                                             P_("Whether the selected resource(s) should be limited to local file: URIs"),
                                                             TRUE,
                                                             GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:limit:
+   *
+   * The maximum number of recently used resources to be displayed,
+   * or -1 to display all items. By default, the
+   * GtkSetting:gtk-recent-files-limit setting is respected: you can
+   * override that limit on a particular instance of #GtkRecentChooser
+   * by setting this property.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_int ("limit",
                                                         P_("Limit"),
@@ -157,6 +225,13 @@ gtk_recent_chooser_class_init (gpointer g_iface)
                                                         G_MAXINT,
                                                         -1,
                                                         GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:sort-type:
+   *
+   * Sorting order to be used when displaying the recently used resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_enum ("sort-type",
                                                          P_("Sort Type"),
@@ -164,6 +239,14 @@ gtk_recent_chooser_class_init (gpointer g_iface)
                                                          GTK_TYPE_RECENT_SORT_TYPE,
                                                          GTK_RECENT_SORT_NONE,
                                                          GTK_PARAM_READWRITE));
+  /**
+   * GtkRecentChooser:filter:
+   *
+   * The #GtkRecentFilter object to be used when displaying
+   * the recently used resources.
+   *
+   * Since: 2.10
+   */
   g_object_interface_install_property (g_iface,
                                       g_param_spec_object ("filter",
                                                            P_("Filter"),
@@ -454,7 +537,8 @@ gtk_recent_chooser_get_limit (GtkRecentChooser *chooser)
  * @chooser: a #GtkRecentChooser
  * @show_tips: %TRUE if tooltips should be shown
  *
- * Sets whether to show a tooltips on the widget.
+ * Sets whether to show a tooltips containing the full path of each
+ * recently used resource in a #GtkRecentChooser widget.
  *
  * Since: 2.10
  */
@@ -471,7 +555,8 @@ gtk_recent_chooser_set_show_tips (GtkRecentChooser *chooser,
  * gtk_recent_chooser_get_show_tips:
  * @chooser: a #GtkRecentChooser
  *
- * Gets whether @chooser should display tooltips.
+ * Gets whether @chooser should display tooltips containing the full path
+ * of a recently user resource.
  *
  * Return value: %TRUE if the recent chooser should show tooltips,
  *   %FALSE otherwise.
@@ -497,8 +582,7 @@ gtk_recent_chooser_get_show_tips (GtkRecentChooser *chooser)
  *
  * Whether to show recently used resources prepended by a unique number.
  *
- * Do not use this function: use gtk_recent_chooser_menu_set_show_numbers()
- * instead.
+ * Deprecated: 2.12: Use gtk_recent_chooser_menu_set_show_numbers() instead.
  *
  * Since: 2.10
  */
@@ -538,8 +622,7 @@ gtk_recent_chooser_set_show_numbers (GtkRecentChooser *chooser,
  * Returns whether @chooser should display recently used resources
  * prepended by a unique number.
  *
- * Do not use this function: use gtk_recent_chooser_menu_get_show_numbers()
- * instead.
+ * Deprecated: 2.12: use gtk_recent_chooser_menu_get_show_numbers() instead.
  *
  * Return value: %TRUE if the recent chooser should show display numbers,
  *   %FALSE otherwise.

diff --git a/gtk/gtkrecentchooser.h b/gtk/gtkrecentchooser.h
index 2362667a959a8e2df0e8ad967372a2756d418eba..738a9b676a6314cb000d27c838f20f88ed64eb31 100644 (file)
--- a/gtk/gtkrecentchooser.h
+++ b/gtk/gtkrecentchooser.h
@@ -135,9 +135,11 @@ gboolean          gtk_recent_chooser_get_local_only      (GtkRecentChooser  *cho
 void              gtk_recent_chooser_set_show_tips       (GtkRecentChooser  *chooser,
                                                          gboolean           show_tips);
 gboolean          gtk_recent_chooser_get_show_tips       (GtkRecentChooser  *chooser);
+#ifndef GTK_DISABLE_DEPRECATED
 void              gtk_recent_chooser_set_show_numbers    (GtkRecentChooser  *chooser,
                                                          gboolean           show_numbers);
 gboolean          gtk_recent_chooser_get_show_numbers    (GtkRecentChooser  *chooser);
+#endif /* GTK_DISABLE_DEPRECATED */
 void              gtk_recent_chooser_set_show_icons      (GtkRecentChooser  *chooser,
                                                          gboolean           show_icons);
 gboolean          gtk_recent_chooser_get_show_icons      (GtkRecentChooser  *chooser);