Documentation.

* gtk/gtkitemfactory.c: Documentation.

        * gtk/tmpl/gtkrc.sgml: Minor fixes.

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2002-01-14  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/tmpl/gtkrc.sgml: Minor fixes.
+
 2002-01-11  Havoc Pennington  <hp@pobox.com>
 
 	* gtk/running.sgml: sgml fixes

docs/reference/gtk/tmpl/gtkrc.sgml

@@ -134,7 +134,7 @@ The possible toplevel declarations are:
     </listitem>
   </varlistentry>
   <varlistentry>
-    <term><literal>module_path <replaceable>path></replaceable></literal></term>
+    <term><literal>module_path <replaceable>path</replaceable></literal></term>
     <listitem>
       <para>Sets a path (a list of directories separated
       by colons) that will be searched for theme engines referenced in
@@ -142,7 +142,7 @@ The possible toplevel declarations are:
     </listitem>
   </varlistentry>
   <varlistentry>
-    <term><literal>pixmap_path <replaceable>path></replaceable></literal></term>
+    <term><literal>pixmap_path <replaceable>path</replaceable></literal></term>
     <listitem>
       <para>Sets a path (a list of directories separated
       by colons) that will be searched for pixmaps referenced in
@@ -244,9 +244,9 @@ elements are:
          Sets a background pixmap to be used in place of
          the <literal>bg</literal> color (or for #GtkText,
          in place of the <literal>base</literal> color. The special
-         value "&lt;parent&gt;" may be used to indicate that the widget should
+         value <literal>"&lt;parent&gt;"</literal> may be used to indicate that the widget should
          use the same background pixmap as its parent. The special value
-         "&lt;none&gt;" may be used to indicate no background pixmap.
+         <literal>"&lt;none&gt;"</literal> may be used to indicate no background pixmap.
        </para>
      </listitem>
   </varlistentry>
@@ -336,14 +336,19 @@ state of the widget. The states are:
 </variablelist>
 </para>
 
-<para>
-Colors can be specified as a string <literal>"&hash;rrrrggggbbbb"</literal>,
-<literal>"&hash;rrrgggbbb"</literal>, <literal>"&hash;rrggbb"</literal>,
-or <literal>"&hash;rgb"</literal>, where <literal>r</literal>
-<literal>g</literal>, and <literal>b</literal> are
-hex digits, or they can be specified as a triplet of floats
+<para id="color-format">
+Colors can be specified as a string containing a color name (GTK+ knows
+all names from the X color database 
+<filename>/usr/lib/X11/rgb.txt</filename>),  
+in one of the hexadecimal forms <literal>&hash;rrrrggggbbbb</literal>,
+<literal>&hash;rrrgggbbb</literal>, <literal>&hash;rrggbb</literal>,
+or <literal>&hash;rgb</literal>, where <literal>r</literal>,
+<literal>g</literal> and <literal>b</literal> are
+hex digits, or they can be specified as a triplet 
 <literal>{ <replaceable>r</replaceable>, <replaceable>g</replaceable>,
-<replaceable>b</replaceable>}</literal>.
+<replaceable>b</replaceable>}</literal>, where <literal>r</literal>,
+<literal>g</literal> and <literal>b</literal> are either integers in 
+the range 0-65635 or floats in the range 0.0-1.0.
 </para>
 
 <para>
@@ -470,16 +475,19 @@ and only then by order of specification. (Later
 overrides earlier). The priorities that can
 be specified are (highest to lowest):
 <simplelist>
-<member><literal>HIGHEST</literal></member>
-<member><literal>RC</literal></member>
-<member><literal>APPLICATION</literal></member>
-<member><literal>GTK</literal></member>
-<member><literal>LOWEST</literal></member>
+<member><literal>highest</literal></member>
+<member><literal>rc</literal></member>
+<member><literal>theme</literal></member>
+<member><literal>application</literal></member>
+<member><literal>gtk</literal></member>
+<member><literal>lowest</literal></member>
 </simplelist>
-<literal>RC</literal> is the default for bindings
-read from an RC file, <literal>APPLICATION</literal>
+<literal>rc</literal> is the default for bindings
+read from an RC file, <literal>theme</literal>
+is the default for bindings read from theme RC files,
+<literal>application</literal> 
 should be used for bindings an application sets
-up, and <literal>GTK</literal> is used for bindings
+up, and <literal>gtk</literal> is used for bindings
 that GTK+ creates internally.
 </para>
 </refsect2>
@@ -699,7 +707,7 @@ Parses resource information directly from a string.
 
 <!-- ##### FUNCTION gtk_rc_parse_color ##### -->
 <para>
-Parses a color in the format expected in a RC file.
+Parses a color in the <link linkend="color-format">format</link> expected in a RC file.
 </para>
 
 @scanner: a #GtkScanner

gtk/gtkitemfactory.c

@@ -196,6 +196,17 @@ gtk_item_factory_init (GtkItemFactory	    *ifactory)
   ifactory->translate_notify = NULL;
 }
 
+/**
+ * gtk_item_factory_new:
+ * @container_type: the kind of menu to create; can be
+ *    #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU
+ * @path: the path of the menu, a string of the form "<name>"
+ * @accel_group: a #GtkAccelGroup to which the accelerators for the
+ *    menu items will be added, or %NULL to create a new one
+ * @returns: a new #GtkItemFactory
+ * 
+ * Creates a new #GtkItemFactory.
+ */
 GtkItemFactory*
 gtk_item_factory_new (GtkType	     container_type,
 		      const gchar   *path,
@@ -377,6 +388,17 @@ gtk_item_factory_add_item (GtkItemFactory		*ifactory,
     ifactory->items = g_slist_prepend (ifactory->items, item);
 }
 
+/**
+ * gtk_item_factory_construct:
+ * @ifactory: a #GtkItemFactory
+ * @container_type: the kind of menu to create; can be
+ *    #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU
+ * @path: the path of the menu, a string of the form "<name>"
+ * @accel_group: a #GtkAccelGroup to which the accelerators for the
+ *    menu items will be added, or %NULL to create a new one
+ * 
+ * Initializes an item factory.
+ */  
 void
 gtk_item_factory_construct (GtkItemFactory	*ifactory,
 			    GtkType		 container_type,
@@ -421,6 +443,13 @@ gtk_item_factory_construct (GtkItemFactory	*ifactory,
 			     ifactory->widget);
 }
 
+/**
+ * gtk_item_factory_from_path:
+ * @path: a string starting with a factory path of the form <literal>"&lt;name&gt;"</literal>
+ * @returns: the #GtkItemFactory created for the given factory path, or %NULL 
+ *
+ * Finds an item factory which has been constructed using the <literal>"&lt;name&gt;"</literal> prefix of @path as the @path argument for gtk_item_factory_new().
+ */
 GtkItemFactory*
 gtk_item_factory_from_path (const gchar      *path)
 {
@@ -515,6 +544,13 @@ gtk_item_factory_finalize (GObject *object)
   G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * gtk_item_factory_from_widget:
+ * @widget: a widget
+ * @returns: the item factory from which @widget was created, or %NULL
+ *
+ * Obtains the item factory from which a widget was created.
+ */
 GtkItemFactory*
 gtk_item_factory_from_widget (GtkWidget	       *widget)
 {
@@ -523,6 +559,17 @@ gtk_item_factory_from_widget (GtkWidget	       *widget)
   return gtk_object_get_data_by_id (GTK_OBJECT (widget), quark_item_factory);
 }
 
+/**
+ * gtk_item_factory_path_from_widget:
+ * @widget: a widget
+ * @returns: the full path to @widget if it been created by an item factory, 
+ *   %NULL otherwise 
+ * 
+ * If @widget has been created by an item factory, returns the full path
+ * to it. (The full path of a widget is the concatenation of the factory 
+ * path specified in gtk_item_factory_new() with the path specified in the 
+ * #GtkItemFactoryEntry from which the widget was created.)
+ */
 gchar*
 gtk_item_factory_path_from_widget (GtkWidget	    *widget)
 {
@@ -531,6 +578,16 @@ gtk_item_factory_path_from_widget (GtkWidget	    *widget)
   return gtk_object_get_data_by_id (GTK_OBJECT (widget), quark_item_path);
 }
 
+/**
+ * gtk_item_factory_create_items:
+ * @ifactory: a #GtkItemFactory
+ * @n_entries: the length of @entries
+ * @entries: an array of #GtkItemFactoryEntry<!>s whose @callback members
+ *    must by of type #GtkItemFactoryCallback1
+ * @callback_data: data passed to the callback functions of all entries
+ *
+ * Creates the menu items from the @entries.
+ */
 void
 gtk_item_factory_create_items (GtkItemFactory	   *ifactory,
 			       guint		    n_entries,
@@ -540,6 +597,17 @@ gtk_item_factory_create_items (GtkItemFactory	   *ifactory,
   gtk_item_factory_create_items_ac (ifactory, n_entries, entries, callback_data, 1);
 }
 
+/**
+ * gtk_item_factory_create_items_ac:
+ * @ifactory: a #GtkItemFactory
+ * @n_entries: the length of @entries
+ * @entries: an array of #GtkItemFactoryEntry<!>s 
+ * @callback_data: data passed to the callback functions of all entries
+ * @callback_data: 1 if the callback functions in @entries are of type
+ *    #GtkItemFactoryCallback1, 2 if they are of type #GtkItemFactoryCallback2 
+ *
+ * Creates the menu items from the @entries.
+ */
 void
 gtk_item_factory_create_items_ac (GtkItemFactory      *ifactory,
 				  guint		       n_entries,
@@ -561,6 +629,19 @@ gtk_item_factory_create_items_ac (GtkItemFactory      *ifactory,
     gtk_item_factory_create_item (ifactory, entries + i, callback_data, callback_type);
 }
 
+/**
+ * gtk_item_factory_get_widget:
+ * @ifactory: a #GtkItemFactory
+ * @path: the path to the widget
+ * @returns: the widget for the given path, or %NULL if @path doesn't lead
+ *   to a widget
+ *
+ * Obtains the widget which corresponds to @path. 
+ *
+ * If the widget corresponding to @path is a menu item which opens a 
+ * submenu, then the submenu is returned. If you are interested in the menu 
+ * item, use gtk_item_factory_get_item() instead.
+ */
 GtkWidget*
 gtk_item_factory_get_widget (GtkItemFactory *ifactory,
 			     const gchar    *path)
@@ -598,6 +679,17 @@ gtk_item_factory_get_widget (GtkItemFactory *ifactory,
   return NULL;
 }
 
+/**
+ * gtk_item_factory_get_widget_by_action:
+ * @ifactory: a #GtkItemFactory
+ * @action: an action as specified in the @callback_action field
+ *   of #GtkItemFactoryEntry
+ * @returns: the widget which corresponds to the given action, or %NULL
+ *   if no widget was found
+ *
+ * Obtains the widget which was constructed from the first #GtkItemFactoryEntry
+ * with the given @action.
+ */
 GtkWidget*
 gtk_item_factory_get_widget_by_action (GtkItemFactory *ifactory,
 				       guint	       action)
@@ -620,6 +712,19 @@ gtk_item_factory_get_widget_by_action (GtkItemFactory *ifactory,
   return NULL;
 }
 
+/** 
+ * gtk_item_factory_get_item:
+ * @ifactory: a #GtkItemFactory
+ * @path: the path to the menu item
+ * @returns: the menu item for the given path, or %NULL if @path doesn't
+ *   lead to a menu item
+ *
+ * Obtains the menu item which corresponds to @path. 
+ *
+ * If the widget corresponding to @path is a menu item which opens a 
+ * submenu, then the item is returned. If you are interested in the submenu, 
+ * use gtk_item_factory_get_widget() instead.
+ */
 GtkWidget*
 gtk_item_factory_get_item (GtkItemFactory *ifactory,
 			   const gchar    *path)
@@ -637,6 +742,18 @@ gtk_item_factory_get_item (GtkItemFactory *ifactory,
   return GTK_IS_ITEM (widget) ? widget : NULL;
 }
 
+
+/**
+ * gtk_item_factory_get_item_by_action:
+ * @ifactory: a #GtkItemFactory
+ * @action: an action as specified in the @callback_action field
+ *   of #GtkItemFactoryEntry
+ * @returns: the menu item which corresponds to the given action, or %NULL
+ *   if no menu item was found
+ *
+ * Obtains the menu item which was constructed from the first 
+ * #GtkItemFactoryEntry with the given @action.
+ */
 GtkWidget*
 gtk_item_factory_get_item_by_action (GtkItemFactory *ifactory,
 				     guint	     action)
@@ -763,6 +880,16 @@ gtk_item_factory_parse_path (GtkItemFactory *ifactory,
   return TRUE;
 }
 
+/**
+ * gtk_item_factory_create_item:
+ * @ifactory: a #GtkItemFactory
+ * @entry: the #GtkItemFactoryEntry to create an item for
+ * @callback_data: data passed to the callback function of @entry
+ * @callback_data: 1 if the callback function of @entry is of type
+ *    #GtkItemFactoryCallback1, 2 if it is of type #GtkItemFactoryCallback2 
+ *
+ * Creates an item for @entry.
+ */
 void
 gtk_item_factory_create_item (GtkItemFactory	     *ifactory,
 			      GtkItemFactoryEntry    *entry,
@@ -988,6 +1115,13 @@ gtk_item_factory_create_item (GtkItemFactory	     *ifactory,
   g_free (path);
 }
 
+/**
+ * gtk_item_factory_create_menu_entries:
+ * @n_entries: the length of @entries
+ * @entries: an array of #GtkMenuEntry<!>s 
+ *
+ * Creates the menu items from the @entries.
+ */
 void
 gtk_item_factory_create_menu_entries (guint              n_entries,
 				      GtkMenuEntry      *entries)
@@ -1064,6 +1198,14 @@ gtk_item_factory_create_menu_entries (guint              n_entries,
     }
 }
 
+/**
+ * gtk_item_factories_path_delete:
+ * @ifactory_path: a factory path to prepend to @path. May be %NULL if @path
+ *   starts with a factory path
+ * @path: a path 
+ * 
+ * Deletes all widgets constructed from the specified path.
+ */
 void
 gtk_item_factories_path_delete (const gchar *ifactory_path,
 				const gchar *path)
@@ -1115,6 +1257,14 @@ gtk_item_factories_path_delete (const gchar *ifactory_path,
     }
 }
 
+/**
+ * gtk_item_factory_delete_item:
+ * @ifactory: a #GtkItemFactory
+ * @path: a path
+ *
+ * Deletes the menu item which was created for @path by the given
+ * item factory.
+ */
 void
 gtk_item_factory_delete_item (GtkItemFactory         *ifactory,
 			      const gchar            *path)
@@ -1138,6 +1288,14 @@ gtk_item_factory_delete_item (GtkItemFactory         *ifactory,
     }
 }
 
+/**
+ * gtk_item_factory_delete_entry:
+ * @ifactory: a #GtkItemFactory
+ * @entry: a #GtkItemFactoryEntry
+ *
+ * Deletes the menu item which was created from @entry by the given
+ * item factory.
+ */
 void
 gtk_item_factory_delete_entry (GtkItemFactory         *ifactory,
 			       GtkItemFactoryEntry    *entry)
@@ -1148,6 +1306,14 @@ gtk_item_factory_delete_entry (GtkItemFactory         *ifactory,
   gtk_item_factory_delete_item (ifactory, entry->path);
 }
 
+/**
+ * gtk_item_factory_delete_entries:
+ * @n_entries: the length of @entries
+ * @entries: an array of #GtkItemFactoryEntry<!>s 
+ *
+ * Deletes the menu items which were created from the @entries by the given
+ * item factory.
+ */
 void
 gtk_item_factory_delete_entries (GtkItemFactory         *ifactory,
 				 guint                   n_entries,
@@ -1182,6 +1348,17 @@ gtk_item_factory_menu_pos (GtkMenu  *menu,
   *y = mpos->y;
 }
 
+/**
+ * gtk_item_factory_popup_data_from_widget:
+ * @widget a widget
+ * @returns: @popup_data associated with the item factory from
+ *   which @widget was created, or %NULL if @widget wasn't created
+ *   by an item factory
+ *
+ * Obtains the @popup_data which was passed to 
+ * gtk_item_factory_popup_with_data(). This data is available until the menu
+ * is popped down again.
+ */
 gpointer
 gtk_item_factory_popup_data_from_widget (GtkWidget     *widget)
 {
@@ -1196,6 +1373,15 @@ gtk_item_factory_popup_data_from_widget (GtkWidget     *widget)
   return NULL;
 }
 
+/**
+ * gtk_item_factory_popup_data:
+ * @ifactory: a #GtkItemFactory
+ * @returns: @popup_data associated with @ifactory
+ *
+ * Obtains the @popup_data which was passed to 
+ * gtk_item_factory_popup_with_data(). This data is available until the menu
+ * is popped down again.
+ */
 gpointer
 gtk_item_factory_popup_data (GtkItemFactory *ifactory)
 {
@@ -1214,6 +1400,16 @@ ifactory_delete_popup_data (GtkObject	   *object,
   gtk_object_remove_data_by_id (GTK_OBJECT (ifactory), quark_popup_data);
 }
 
+/**
+ * gtk_item_factory_popup:
+ * @ifactory: a #GtkItemFactory
+ * @x: the x position 
+ * @y: the y position
+ * @mouse_button: the mouse button which was pressed to initiate this action
+ * @time: a timestamp for this action
+ *
+ * Pops up the menu constructed from the item factory at (@x, @y).
+ */
 void
 gtk_item_factory_popup (GtkItemFactory		*ifactory,
 			guint			 x,
@@ -1224,6 +1420,21 @@ gtk_item_factory_popup (GtkItemFactory		*ifactory,
   gtk_item_factory_popup_with_data (ifactory, NULL, NULL, x, y, mouse_button, time);
 }
 
+/**
+ * gtk_item_factory_popup_with_data:
+ * @ifactory: a #GtkItemFactory
+ * @popup_data: data available for callbacks while the menu is posted
+ * @destroy: a #GtkDestroyNotify function to be called on @popup_data when
+ *  the menu is unposted
+ * @x: the x position 
+ * @y: the y position
+ * @mouse_button: the mouse button which was pressed to initiate this action
+ * @time: a timestamp for this action
+ *
+ * Pops up the menu constructed from the item factory at (@x, @y). Callbacks
+ * can access the @popup_data while the menu is posted via 
+ * gtk_item_factory_popup_data() and gtk_item_factory_popup_data_from_widget().
+ */
 void
 gtk_item_factory_popup_with_data (GtkItemFactory	*ifactory,
 				  gpointer		 popup_data,
@@ -1270,6 +1481,17 @@ gtk_item_factory_popup_with_data (GtkItemFactory	*ifactory,
 		  mouse_button, time);
 }
 
+/**
+ * gtk_item_factory_set_translate_func:
+ * @ifactory: a #GtkItemFactory
+ * @func: the #GtkTranslateFunc function to be used to translate path elements 
+ * @data: data to pass to @func and @notify
+ * @notify: a #GtkDestroyNotify function to be called @ifactory is destroyed 
+ *   and when the translation function is changed again
+ * 
+ * Sets a function to be use for translating the path elements before they
+ * are displayed. 
+ */ 
 void
 gtk_item_factory_set_translate_func (GtkItemFactory      *ifactory,
 				     GtkTranslateFunc     func,