Commit dee05966 authored by Matthias Clasen's avatar Matthias Clasen

Documentation.

        * gtk/gtkitemfactory.c: Documentation.

        * gtk/tmpl/gtkrc.sgml: Minor fixes.
parent 55529223
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
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
......
......@@ -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
......
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment