+1999-11-16 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/tmpl/gtkmenubar.sgml: fixed minor error - using <em>.
+
+ * gtk/tmpl/gtknotebook.sgml:
+ * gtk/tmpl/gtklist.sgml: new sections from
+ Nicolas George <george@clipper.ens.fr>, with help from
+ "Bob Springett" <bobspringett@claranet.fr>.
+
+ * gtk/tmpl/gtkobject.sgml:
+ * gtk/tmpl/gtkarg.sgml: new sections from
+ David Benson <daveb@idealab.com>.
+
+ * gtk/tmpl/gtkvbox.sgml:
+ * gtk/tmpl/gtkhbox.sgml: fixed line endings.
+
+ * gtk/tmpl/gtkvbbox.sgml: update from Lee Mallabone
+ <lee0@callnetuk.com>
+
+ * gdk/tmpl/drawing.sgml: fixed error in gdk_draw_arc() @angle2 param
+ - it is relative to @angle1 rather than from the 3 o'clock position.
+
+ * gtk/tmpl/gtkfontseldlg.sgml: changed enums to use @ fields.
+
+ * gtk/tmpl/gtkcolorsel.sgml:
+ * gtk/tmpl/gtkcolorseldlg.sgml:
+ * gtk/tmpl/gtkprogress.sgml:
+ * gtk/tmpl/gtkprogressbar.sgml: new sections from Tom Martone
+ <tom@martoneconsulting.com>
+
+ * gtk/tmpl/gtkclist.sgml: partially written documentation from
+ Paul Schifferer <isengard@geocities.com> who won't be able to finish it
+
1999-09-22 Martin Norbäck <d95mback@dtek.chalmers.se>
* gtk/tmpl/gtkclist.sgml: Added information about the sorting functions
@height: the height of the bounding rectangle.
@angle1: the start angle of the arc, relative to the 3 o'clock position,
counter-clockwise, in 1/64ths of a degree.
-@angle2: the end angle of the arc, in the same units as @angle1.
+@angle2: the end angle of the arc, relative to @angle1, in 1/64ths of a degree.
<!-- ##### FUNCTION gdk_draw_polygon ##### -->
-<!-- ##### SECTION Title ##### -->
-Object Properties
-
-<!-- ##### SECTION Short_Description ##### -->
-
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkArgInfo ##### -->
-<para>
-
-</para>
-
-@class_type:
-@name:
-@type:
-@arg_flags:
-@full_name:
-@arg_id:
-@seq_id:
-
-<!-- ##### FUNCTION gtk_arg_new ##### -->
-<para>
-
-</para>
-
-@arg_type:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_copy ##### -->
-<para>
-
-</para>
-
-@src_arg:
-@dest_arg:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_free ##### -->
-<para>
-
-</para>
-
-@arg:
-@free_contents:
-
-
-<!-- ##### FUNCTION gtk_args_collect ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_info_hash_table:
-@arg_list_p:
-@info_list_p:
-@first_arg_name:
-@var_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->
-<para>
-
-</para>
-
-@arg_list:
-@info_list:
-
-
-<!-- ##### FUNCTION gtk_arg_get_info ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_info_hash_table:
-@arg_name:
-@info_p:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->
-<para>
-
-</para>
-
-@base_class_type:
-@arg_name:
-@class_n_args_offset:
-@arg_info_hash_table:
-@arg_type:
-@arg_flags:
-@arg_id:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_args_query ##### -->
-<para>
-
-</para>
-
-@class_type:
-@arg_info_hash_table:
-@arg_flags:
-@n_args_p:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->
-<para>
-
-</para>
-
-@arg_name:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_info_equal ##### -->
-<para>
-
-</para>
-
-@arg_info_1:
-@arg_info_2:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_arg_info_hash ##### -->
-<para>
-
-</para>
-
-@arg_info:
-@Returns:
-
-
+<!-- ##### SECTION Title ##### -->\r
+Implementation of Object Properties\r
+\r
+<!-- ##### SECTION Short_Description ##### -->\r
+Utility function to manipulate lists of named, typed arguments.\r
+\r
+<!-- ##### SECTION Long_Description ##### -->\r
+<para>\r
+All the functions in here are marked a Non-public.\r
+We describe it anyway because it is occasionally useful\r
+to understand how the work is done.\r
+</para>\r
+<para>\r
+Arguments are a way of describing a named parameter to a function.\r
+They have two important roles within gtk+:\r
+<itemizedlist>\r
+<listitem>\r
+<para>\r
+they describe <wordasword>object properties</wordasword>.\r
+This means that they present an interface to get and set a named-type\r
+for any type of object in a consistent way.\r
+(All the relevant functions to do this start with gtk_object_set\r
+or gtk_object_get).\r
+</para>\r
+</listitem>\r
+<listitem>\r
+<para>\r
+they describe <wordasword>signal arguments</wordasword>.\r
+This is a lot less often needed but still useful.\r
+Usually if you are just emitting or creating a particular signal\r
+it is more convenient to just use gtk_signal_emit() or gtk_signal_new().\r
+However if you are writing a function to emit or create an arbitrary\r
+signal, you must use gtk_signal_emitv() or gtk_signal_newv().\r
+</para>\r
+</listitem>\r
+</itemizedlist>\r
+\r
+\r
+<!-- ##### SECTION See_Also ##### -->\r
+<para>\r
+#GtkObject.\r
+</para>\r
+\r
+<!-- ##### STRUCT GtkArgInfo ##### -->\r
+<para>\r
+A structure containing information about the argument.\r
+Returned by gtk_arg_get_info().\r
+</para>\r
+\r
+@class_type: if the argument is an object, this is the object class type.\r
+@name: the name of the argument.\r
+@type: the type of the argument; it may be an object's type\r
+or a fundamental type.\r
+@arg_flags: flags applicable to the argument (i.e. readable, writable,\r
+and whether it needs to be constructed).\r
+@full_name: the object name and argument name separated by ::,\r
+e.g. "GtkObject::user_data" or "GtkButton::label".\r
+@arg_id: the unique argument identified.\r
+@seq_id: ???\r
+\r
+<!-- ##### FUNCTION gtk_arg_new ##### -->\r
+<para>\r
+Creates a new argument of a certain type, set to 0 or NULL.\r
+</para>\r
+\r
+@arg_type: the type of the argument.\r
+@Returns: the newly created #GtkArg.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_copy ##### -->\r
+<para>\r
+It will either copy data into an existing argument or allocate a new argument\r
+and copy the data. Strings are duplicated. All other pointers and\r
+values are copied (shallowly-- that is the pointers themselves are\r
+copied, not the data they point to.)\r
+</para>\r
+<para>\r
+You should call gtk_arg_reset() on dest_arg before calling this\r
+if the argument may contain string data that you want freed.\r
+</para>\r
+\r
+@src_arg: the argument to duplicate.\r
+@dest_arg: the argument to copy over (or NULL to create a new #GtkArg).\r
+@Returns: the new #GtkArg (or dest_arg, if it was not NULL).\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_free ##### -->\r
+<para>\r
+Frees the argument, and optionally its contents.\r
+</para>\r
+\r
+@arg: the argument to free.\r
+@free_contents: whether to free the string, if it is a string.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_args_collect ##### -->\r
+<para>\r
+Private: given a hashtable of argument information it takes a vararg\r
+list and parses it into arguments (in the form of lists of #GtkArgs\r
+and lists of #GtkArgInfos.\r
+</para>\r
+<para>\r
+The list of arguments starts with first_arg_name then the first argument's\r
+value. Followed by any number of additional name/argument pairs,\r
+terminated with NULL.\r
+</para>\r
+\r
+@object_type: the type of object we are collecting arguments for.\r
+@arg_info_hash_table: a hashtable mapping from names of arguments\r
+to their #GtkArgInfos.\r
+@arg_list_p: a returned list of arguments obtained from parsing the\r
+varargs.\r
+@info_list_p: a returned list of the #GtkArgInfos.\r
+@first_arg_name: the name of the first argument.\r
+@var_args: a va_list containing the value of the first argument,\r
+followed by name/value pairs, followed by NULL.\r
+@Returns: an error message on failure, or NULL otherwise.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_args_collect_cleanup ##### -->\r
+<para>\r
+Private: erase lists of arguments returned from gtk_args_collect().\r
+</para>\r
+\r
+@arg_list: arg_list_p returned from gtk_args_collect().\r
+@info_list: info_list_p returned from gtk_args_collect().\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_get_info ##### -->\r
+<para>\r
+Private: get information about an argument.\r
+</para>\r
+\r
+@object_type: the type of object.\r
+@arg_info_hash_table: the hashtable of #GtkArgInfos.\r
+@arg_name: the name of the argument to lookup.\r
+@info_p: the argument info.\r
+@Returns: an error message on failure, or NULL otherwise.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_type_new_static ##### -->\r
+<para>\r
+Create a new argument registered with a class.\r
+</para>\r
+\r
+@base_class_type: the basic type having the arguments, almost alway\r
+GTK_TYPE_OBJECT, except if your defining a different type argument\r
+that gets a different namespace. #GtkContainer does this to define\r
+per-child arguments of the container.\r
+@arg_name: name of the argument to create. (must be a static constant string)\r
+@class_n_args_offset: offset into the base class structure that tells\r
+the number of arguments.\r
+@arg_info_hash_table: hashtable of #GtkArgInfos.\r
+@arg_type: type of the argument.\r
+@arg_flags: flags of the argument.\r
+@arg_id: ???\r
+@Returns: the new #GtkArgInfo.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_args_query ##### -->\r
+<para>\r
+Private: from a class type and its arginfo hashtable,\r
+get an array of #GtkArgs that this object accepts.\r
+</para>\r
+\r
+@class_type: the class type.\r
+@arg_info_hash_table: the hashtable of #GtkArgInfos.\r
+@arg_flags: returned array of argument flags.\r
+@n_args_p: the number of arguments this object accepts.\r
+@Returns: the array of arguments (or NULL on error).\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_name_strip_type ##### -->\r
+<para>\r
+Given a fully qualified argument name (e.g. "GtkButton::label")\r
+it returns just the argument name (e.g. "label") unless\r
+the argument name was invalid, in which case it returns NULL.\r
+</para>\r
+\r
+@arg_name: the fully-qualified argument name.\r
+@Returns: the base argument name.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_info_equal ##### -->\r
+<para>\r
+A #GCompareFunc for hashing #GtkArgInfos.\r
+</para>\r
+\r
+@arg_info_1: a #GtkArgInfo.\r
+@arg_info_2: a #GtkArgInfo.\r
+@Returns: whether the arguments are the same.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_arg_info_hash ##### -->\r
+<para>\r
+A #GHashFunc for hashing #GtkArgInfos.\r
+</para>\r
+\r
+@arg_info: a #GtkArgInfo.\r
+@Returns: a hash value for that #GtkArgInfo.\r
+\r
+\r
GtkColorSelection
<!-- ##### SECTION Short_Description ##### -->
-
+a widget used to select a color.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkColorSelection is a widget that is used to select
+a color. It consists of a color wheel and number of sliders
+and entry boxes for color parameters such as hue, saturation,
+value, red, green, blue, and opacity. It is found on the standard
+color selection dialog box #GtkColorSelectionDialog.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkColorSelection ##### -->
<para>
-
+The #GtkColorSelection-struct struct contains private data only,
+and should be accessed using the functions below.
</para>
<!-- ##### FUNCTION gtk_color_selection_new ##### -->
<para>
-
+Create a new #GtkColorSelection.
</para>
-@Returns:
+@Returns: a #GtkColorSelection.
<!-- ##### FUNCTION gtk_color_selection_set_update_policy ##### -->
<para>
-
+Sets the policy controlling when the color_changed signals are emitted.
+The available policies are:
+<itemizedlist>
+<listitem>
+<para>
+%GTK_UPDATE_CONTINUOUS - signals are sent continuously as the color
+selection changes.
+</para>
+<listitem>
+<para>
+%GTK_UPDATE_DISCONTINUOUS - signals are sent only when the mouse
+button is released.
+</para>
+<listitem>
+<para>
+%GTK_UPDATE_DELAYED - signals are sent when the mouse button is
+released or when the mouse has been motionless for a period of
+time.
+</para>
+</itemizedlist>
</para>
-@colorsel:
-@policy:
+@colorsel: a #GtkColorSelection.
+@policy: a #GtkUpdateType value indicating the desired policy.
<!-- ##### FUNCTION gtk_color_selection_set_opacity ##### -->
<para>
-
+Controls whether opacity can be set with the #GtkColorSelection.
+If this functionality is enabled, the necessary additional widgets
+are added to the #GtkColorSelection and the opacity value can be
+retrieved via the fourth value in the color array returned by
+the gtk_color_selection_get_color() function.
</para>
-@colorsel:
-@use_opacity:
+@colorsel: a #GtkColorSelection.
+@use_opacity: a boolean indicating whether the opacity selection
+is enabled.
<!-- ##### FUNCTION gtk_color_selection_set_color ##### -->
<para>
-
+Sets the color in the #GtkColorSelection. The widgets are updated
+to reflect the new color.
</para>
-@colorsel:
-@color:
+@colorsel: a #GtkColorSelection.
+@color: a color array consisting of 4 gfloat values for red, green,
+blue, and opacity.
<!-- ##### FUNCTION gtk_color_selection_get_color ##### -->
<para>
-
+Retrieve the currently selected color value.
</para>
-@colorsel:
-@color:
+@colorsel: a #GtkColorSelection
+@color: a color array consisting of 4 gfloat values for red, green,
+blue, and opacity.
<!-- ##### SIGNAL GtkColorSelection::color-changed ##### -->
<para>
-
+This signal is emitted when the color changes in the #GtkColorSelection
+according to its update policy.
</para>
@colorselection: the object which received the signal.
GtkColorSelectionDialog
<!-- ##### SECTION Short_Description ##### -->
-
+a standard dialog box for selecting a color.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkColorSelectionDialog provides a standard dialog which
+allows the user to select a color much like the #GtkFileSelection
+provides a standard dialog for file selection.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkColorSelectionDialog ##### -->
<para>
+The #GtkColorSelectionDialog-struct struct contains the following fields.
+(These fields should be considered read-only. They should never be set by
+an application.)
-</para>
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+<row>
+<entry>#GtkWidget *colorsel;</entry>
+<entry>The #GtkColorSelection widget contained within the
+dialog. Use this widget and its gtk_color_selection_get_color()
+function to gain access to the selected color. Connect a handler
+for this widget's color_changed signal to be notified when the
+color changes.
+</entry>
+</row>
-<!-- ##### FUNCTION gtk_color_selection_dialog_new ##### -->
-<para>
+<row>
+<entry>#GtkWidget *ok_button;</entry>
+<entry>The OK button widget contained within the dialog.
+Connect a handler for the clicked event.
+</entry>
+</row>
+<row>
+<entry>#GtkWidget *cancel_button;</entry>
+<entry>The cancel button widget contained within the dialog.
+Connect a handler for the clicked event.
+</entry>
+</row>
+
+<row>
+<entry>#GtkWidget *help_button;</entry>
+<entry>The help button widget contained within the dialog.
+Connect a handler for the clicked event.
+</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
-@title:
-@Returns:
+<!-- ##### FUNCTION gtk_color_selection_dialog_new ##### -->
+<para>
+Creates a new #GtkColorSelectionDialog.
+</para>
+@title: a string containing the title text for the dialog.
+@Returns: a #GtkColorSelectionDialog.
A set of bit flags used to specify the type of fonts shown
when calling gtk_font_selection_dialog_set_filter() or
gtk_font_selection_set_filter().
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GTK_FONT_BITMAP</entry>
-<entry>bitmap fonts.</entry>
-</row>
-
-<row>
-<entry>GTK_FONT_SCALABLE</entry>
-<entry>scalable fonts.</entry>
-</row>
-
-<row>
-<entry>GTK_FONT_SCALED_BITMAP</entry>
-<entry>scaled bitmap fonts.</entry>
-</row>
-
-<row>
-<entry>GTK_FONT_ALL</entry>
-<entry>a bitwise combination of all of the above.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
</para>
-@GTK_FONT_BITMAP:
-@GTK_FONT_SCALABLE:
-@GTK_FONT_SCALABLE_BITMAP:
-@GTK_FONT_ALL:
+@GTK_FONT_BITMAP: bitmap fonts.
+@GTK_FONT_SCALABLE: scalable fonts.
+@GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
+@GTK_FONT_ALL: a bitwise combination of all of the above.
<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
A set of bit flags used to specify the filter being set
when calling gtk_font_selection_dialog_set_filter() or
gtk_font_selection_set_filter().
-
-<informaltable pgwide=1 frame="none" role="enum">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>GTK_FONT_FILTER_BASE</entry>
-<entry>the base filter, which can't be changed by the user.</entry>
-</row>
-
-<row>
-<entry>GTK_FONT_FILTER_USER</entry>
-<entry>the user filter, which can be changed from within the 'Filter' page
-of the #GtkFontSelection widget.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
</para>
-@GTK_FONT_FILTER_BASE:
-@GTK_FONT_FILTER_USER:
+@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
+@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
+'Filter' page of the #GtkFontSelection widget.
horizontal container box
<!-- ##### SECTION Long_Description ##### -->
-<para>\r
-GtkHBox is a container that organizes child widgets into a single row.\r
-</para>\r
-\r
-<para>\r
-Use the #GtkBox packing interface to determine the arrangement,\r
-spacing, width, and alignment of GtkHBox children.\r
-</para>\r
-\r
-<para>\r
-All children are allocated the same height.\r
+<para>
+GtkHBox is a container that organizes child widgets into a single row.
+</para>
+
+<para>
+Use the #GtkBox packing interface to determine the arrangement,
+spacing, width, and alignment of GtkHBox children.
+</para>
+
+<para>
+All children are allocated the same height.
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>#GtkVBox</term>\r
-<listitem><para>a sister class that organizes widgets into a column.</para></listitem>\r
-</varlistentry>\r
-\r
-</variablelist>\r
+<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkVBox</term>
+<listitem><para>a sister class that organizes widgets into a column.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GtkHBox ##### -->
<!-- ##### FUNCTION gtk_hbox_new ##### -->
-<para>\r
-Creates a new GtkHBox.\r
+<para>
+Creates a new GtkHBox.
</para>
@homogeneous: %TRUE if all children are to be given equal space allotments.
GtkList
<!-- ##### SECTION Short_Description ##### -->
-
+Widget for packing a list of selectable items.
<!-- ##### SECTION Long_Description ##### -->
<para>
+The GtkList widget is a container whose children are displayed
+vertically in order, and can be selected.
+The list has many selection modes, which are programmer selective and
+depend on how many elements are able to be selected at the same time.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkContainer</term>
+<listitem><para>For functions that apply to every #GtkContainer
+(like #GtkList).</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>#GtkListitem</term>
+<listitem><para>Children of a #GtkList widget must be of this
+type.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkList ##### -->
</para>
+@container: the parent class object
+@children: a GList with the children of the list; belonging to #GtkListitem
+@selection: a GList with selected items of the list
+@undo_selection:
+@undo_unselection:
+@last_focus_child:
+@undo_focus_child:
+@htimer:
+@vtimer:
+@anchor:
+@drag_pos:
+@anchor_state:
+@selection_mode: the selection mode of the list
+@drag_selection:
+@add_mode:
<!-- ##### FUNCTION gtk_list_new ##### -->
<para>
-
+Creates a new #GtkList.
</para>
-@Returns:
+@Returns: the newly created #GtkList
<!-- ##### FUNCTION gtk_list_insert_items ##### -->
<para>
-
+Inserts @items into the @list at the position @position. The @GList items
+must not be freed after.
</para>
-@list:
-@items:
-@position:
+@list: the list widget.
+@items: the items.
+@position: the position to insert @items, starting at 0.
<!-- ##### FUNCTION gtk_list_append_items ##### -->
<para>
-
+Adds @items to the end of the @list.
</para>
-@list:
-@items:
+@list: the list widget.
+@items: the items.
<!-- ##### FUNCTION gtk_list_prepend_items ##### -->
<para>
-
+Inserts @items at the beginning of the @list.
</para>
-@list:
-@items:
+@list: the list widget.
+@items: the items.
<!-- ##### FUNCTION gtk_list_remove_items ##### -->
<para>
-
+Removes the @items from the @list.
</para>
-@list:
-@items:
+@list: the list widget.
+@items: the items to remove.
<!-- ##### FUNCTION gtk_list_remove_items_no_unref ##### -->
<para>
-
+Removes the @items from the @list, without unreferencing them. It
+may be useful if you want to move the items from one list to another.
</para>
-@list:
-@items:
+@list: the list widget.
+@items: the items.
<!-- ##### FUNCTION gtk_list_clear_items ##### -->
<para>
-
+Removes the items between index @start (included) and @end (excluded)
+from the @list. If @end is negative, or greater than the number of
+children of @list, it's assumed to be exactly the number of
+elements. If @start is greater than or equal to @end, nothing is
+done.
</para>
-@list:
-@start:
-@end:
+@list: the list widget.
+@start: the index of the first item to remove.
+@end: the index of the lest item to remove plus one.
<!-- ##### FUNCTION gtk_list_select_item ##### -->
<para>
-
+Selects the child number @item of the @list. Nothing happens if @item
+is out of bounds. The signal GtkList::select-child will be emitted.
</para>
-@list:
-@item:
+@list: the list widget.
+@item: the index of the child to select.
<!-- ##### FUNCTION gtk_list_unselect_item ##### -->
<para>
-
+Unselects the child number @item of the @list. Nothing happens if
+@item is out of bounds. The signal GtkList::unselect-child will be
+emitted.
</para>
-@list:
-@item:
+@list: the list widget.
+@item: the index of the child to unselect.
<!-- ##### FUNCTION gtk_list_select_child ##### -->
<para>
-
+Selects the given @child. The signal GtkList::select-child will be
+emitted.
</para>
-@list:
-@child:
+@list: the list widget
+@child: the child to select.
<!-- ##### FUNCTION gtk_list_unselect_child ##### -->
<para>
-
+Unselects the given @child. The signal GtkList::unselect-child will be
+emitted.
</para>
-@list:
-@child:
+@list: the list widget.
+@child: the child to unselect.
<!-- ##### FUNCTION gtk_list_child_position ##### -->
<para>
-
+Searches the children of @list for the index of @child.
</para>
-@list:
-@child:
-@Returns:
+@list: the list widget.
+@child: the child to look for.
+@Returns: the index of the child, -1 if not found.
<!-- ##### FUNCTION gtk_list_set_selection_mode ##### -->
<para>
-
+Set the list selection mode. The selection mode can be any value in
+#GtkSelectionMode:
+<variablelist>
+<varlistentry>
+<term>#GTK_SELECTION_SINGLE</term>
+<listitem><para>
+Zero or one element may be selected.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GTK_SELECTION_BROWSE</term>
+<listitem><para>
+Exactly one element is always selected (this can be false after you have
+changed the selection mode).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GTK_SELECTION_MULTIPLE</term>
+<listitem><para>
+Any number of elements may be selected. Clicks toggle the state of an
+item.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GTK_SELECTION_EXTENDED</term>
+<listitem><para>
+Any number of elements may be selected. Click-drag selects a range of
+elements; the Ctrl key may be used to enlarge the selection, and
+Shift key to select between the focus and the child pointed to.
+</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-@list:
-@mode:
+@list: the list widget.
+@mode: the new selection mode.
<!-- ##### FUNCTION gtk_list_extend_selection ##### -->
<para>
-
+Extends the selection by moving the anchor according to @scroll_type. Only
+in #GTK_SELECTION_EXTENDED.
</para>
-@list:
-@scroll_type:
-@position:
-@auto_start_selection:
+@list: the list widget.
+@scroll_type: the direction and length.
+@position: the position if @scroll_type is #GTK_SCROLL_JUMP.
+@auto_start_selection: if #TRUE, gtk_list_start_selection is automatically
+carried out before extending the selection.
<!-- ##### FUNCTION gtk_list_start_selection ##### -->
<para>
-
+Starts a selection (or part of selection) at the focused child. Only in
+#GTK_SELECTION_EXTENDED mode.
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_end_selection ##### -->
<para>
-
+Ends the selection. Used with #gtk_list_extend_selection and
+#gtk_list_start_selection. Only in #GTK_SELECTION_EXTENDED.
</para>
@list:
<!-- ##### FUNCTION gtk_list_select_all ##### -->
<para>
-
+Selects all children of @list. A signal will be emitted for each
+newly selected child.
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_unselect_all ##### -->
<para>
-
+Unselects all children of @list. A signal will be emitted for each
+newly unselected child.
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_scroll_horizontal ##### -->
<para>
-
+Scrolls @list horizontaly. This supposes that the list is packed into a
+scrolled window or something similar, and adjustments are well
+set. Step and page increment are those from the horizontal adjustment
+of @list. Backward means to the left, and forward to the
+right. Out of bounds values are truncated.
+@scroll_type may be any valid #GtkScrollType. If @scroll_type is
+#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
+scrolls to the ratio @position: 0 is full left, 1 is full right.
</para>
-@list:
-@scroll_type:
-@position:
+@list: the list widget.
+@scroll_type: the scrolling type.
+@position: the position if @scroll_type is #GTK_SCROLL_JUMP
<!-- ##### FUNCTION gtk_list_scroll_vertical ##### -->
<para>
-
+Scrolls @list vertically. This supposes that the list is packed into a
+scrolled window or something similar, and adjustments are well
+set. Step and page increment are those from the vertical adjustment
+of @list. Backward means up, and forward down. Out of bounds values are
+truncated.
+@scroll_type may be any valid #GtkScrollType. If @scroll_type is
+#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
+scrolls to the ratio @position: 0 is top, 1 is bottom.
</para>
-@list:
-@scroll_type:
-@position:
+@list: the list widget.
+@scroll_type: the scrolling type.
+@position: the position if @scroll_type is #GTK_SCROLL_JUMP
<!-- ##### FUNCTION gtk_list_toggle_add_mode ##### -->
<para>
-
+Toggles between adding to the selection and beginning a new selection. Only
+in #GTK_SELECTION_EXTENDED. Useful with #gtk_list_extend_selection.
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_toggle_focus_row ##### -->
<para>
-
+Toggles the focus row. If the focus row is selected, it's
+unselected. If the focus row is unselected, it's selected. If the
+selection mode of @list is #GTK_SELECTION_BROWSE, this has no effect,
+as the selection is always at the focus row.
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_toggle_row ##### -->
<para>
-
+Toggles the child @item of list. If the selection mode of @list is
+#GTK_SELECTION_BROWSE, the item is selected, and the others are
+unselected.
</para>
-@list:
-@item:
+@list: the list widget.
+@item: the child to toggle.
<!-- ##### FUNCTION gtk_list_undo_selection ##### -->
<para>
-
+Restores the selection in the last state, only if selection mode is
+#GTK_SELECTION_EXTENDED. If this function is called twice, the selection is
+cleared. This function sometimes gives stranges "last states".
</para>
-@list:
+@list: the list widget.
<!-- ##### FUNCTION gtk_list_end_drag_selection ##### -->
<para>
-
+Stops the drag selection mode and ungrabs the pointer. This has no
+effect if a drag selection is not active.
</para>
-@list:
+@list: the list widget.
<!-- ##### SIGNAL GtkList::selection-changed ##### -->
<para>
-
+The selection of the widget has just changed.
</para>
@list: the object which received the signal.
<!-- ##### SIGNAL GtkList::select-child ##### -->
<para>
-
+The child @widget has just been selected.
</para>
@list: the object which received the signal.
-@widget:
+@widget: the newly selected child.
<!-- ##### SIGNAL GtkList::unselect-child ##### -->
<para>
-
+The child @widget has just been unselected.
</para>
@list: the object which received the signal.
-@widget:
+@widget: the newly unselected child.
Adds a new #GtkMenuItem to the beginning of the GtkMenuBar
</para>
-@menu_bar: a #GtkMenuBa
+@menu_bar: a #GtkMenuBar
@child: the #GtkMenuItem to add
@menu_bar: a #GtkMenuBar
@child: the #GtkMenuItem to add
-@position: the position in the item list where the <em>child</em> is added.
+@position: the position in the item list where the @child is added.
<!-- ##### FUNCTION gtk_menu_bar_set_shadow_type ##### -->
GTK_SHADOW_NONE, GTK_SHADOW_IN, GTK_SHADOW_OUT, GTK_SHADOW_ETCHED_IN, and GTK_SHADOW_ETCHED_OUT
</para>
-@menu_bar: a #GtkMenuBa
+@menu_bar: a #GtkMenuBar
@type: the GtkShadowtype
GtkNotebook
<!-- ##### SECTION Short_Description ##### -->
-
+Set of pages with bookmarks.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkNotebook widget is a #GtkContainer whose children are pages that
+can be accessed through bookmarks. The pages are displayed all at the same
+place. <!-- TODO: talk about the menu -->
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkContainer</term>
+<listitem><para>For functions that apply to every #GtkContainer
+(like #GtkList).</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkNotebook ##### -->
</para>
+@container: the parent class object
+@cur_page: the currently displayed page
+@children: a GList with the children of the notebook; belonging to
+#GtkNotebookPage
+@first_tab:
+@focus_tab:
+@menu:
+@panel:
+@timer:
+@tab_hborder:
+@tab_vborder:
+@show_tabs:
+@homogeneous:
+@show_border:
+@tab_pos:
+@scrollable:
+@in_child:
+@click_child:
+@button:
+@need_timer:
+@child_has_focus:
+@have_visible_child:
<!-- ##### MACRO GTK_NOTEBOOK_PAGE ##### -->
<para>
-
+Extracts the contents of the current element of #GList @_glist_ as a
+#GtkNotebookPage.
</para>
@_glist_:
<!-- ##### STRUCT GtkNotebookPage ##### -->
<para>
-
+The #GtkNotebookPage structure is used to store the pages of a notebook. It
+is not an object.
</para>
-@child:
-@tab_label:
-@menu_label:
+@child: the contents of the page
+@tab_label: the label shown in the bookmark
+@menu_label: the label shown in the popup menu
@default_menu:
@default_tab:
@expand:
<!-- ##### FUNCTION gtk_notebook_new ##### -->
<para>
-
+Creates a new #GtkNotebook widget
</para>
-@Returns:
+@Returns: the newly created G=#GtkNotebook
<!-- ##### FUNCTION gtk_notebook_append_page ##### -->
<para>
-
+Appends to @notebook a page whose content is @child, and whose bookmark is
+@tab_label.
</para>
-@notebook:
-@child:
-@tab_label:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark for the page
<!-- ##### FUNCTION gtk_notebook_append_page_menu ##### -->
<para>
-
+Appends to @notebook a page whose content is @child, whose bookmark is
+@tab_label, and whose menu label is @menu_label.
</para>
-@notebook:
-@child:
-@tab_label:
-@menu_label:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark of the page
+@menu_label: the menu label of the page
<!-- ##### FUNCTION gtk_notebook_prepend_page ##### -->
<para>
-
+Prepends to @notebook a page whose content is @child, whose bookmark is
+@tab_label, and whose menu label is @menu_label.
</para>
-@notebook:
-@child:
-@tab_label:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark of the page
<!-- ##### FUNCTION gtk_notebook_prepend_page_menu ##### -->
<para>
-
+Appends to @notebook a page whose content is @child, whose bookmark is
+@tab_label, and whose menu label is @menu_label.
</para>
-@notebook:
-@child:
-@tab_label:
-@menu_label:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark of the page
+@menu_label: the menu label of the page
<!-- ##### FUNCTION gtk_notebook_insert_page ##### -->
<para>
-
+Inserts in @notebook a new page whose content is @child, and whose
+bookmark is @tab_label. The page is inserted just
+before the page number @position, starting with 0. If @position is out of
+bounds, it is assumed to be the current number of pages.
</para>
-@notebook:
-@child:
-@tab_label:
-@position:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark of the page
+@position: the position to insert the page
<!-- ##### FUNCTION gtk_notebook_insert_page_menu ##### -->
<para>
-
+Inserts in @notebook a new page whose content is @child, whose bookmark is
+@tab_label, and whose menu label is @menu_label. The page is inserted just
+before the page number @position, starting with 0. If @position is out of
+bounds, it is assumed to be the current number of pages.
</para>
-@notebook:
-@child:
-@tab_label:
-@menu_label:
-@position:
+@notebook: the notebook widget
+@child: the content of the new page
+@tab_label: the bookmark of the page
+@menu_label: the menu label of the page
+@position: the position to insert the page
<!-- ##### FUNCTION gtk_notebook_remove_page ##### -->
<para>
-
+Removes the page @page_num form @notebook. Pages are numbered starting at
+zero. Negative values stand for the last page; too large values are
+ignored.
</para>
-@notebook:
-@page_num:
+@notebook: the notebook widget
+@page_num: the page number
<!-- ##### MACRO gtk_notebook_current_page ##### -->
<para>
-
+??? I don't see such a macro in gtknotebook.h (v1.2.3).
</para>
<!-- ##### FUNCTION gtk_notebook_page_num ##### -->
<para>
-
+Returns the page number of @child in @notebook.
</para>
-@notebook:
-@child:
-@Returns:
+@notebook: the notebook widget
+@child: the child
+@Returns: the page number, or -1 if @child is not in @notebook
<!-- ##### FUNCTION gtk_notebook_set_page ##### -->
<para>
-
+Switches to the page number @page_num. Negative values stand for the last
+page; too large values are ignored.
</para>
-@notebook:
-@page_num:
+@notebook: the notebook widget
+@page_num: the page number
<!-- ##### FUNCTION gtk_notebook_next_page ##### -->
<para>
-
+Switches to the next page. Nothing happens if the current page is the last
+page.
</para>
-@notebook:
+@notebook: the notebook widget.
<!-- ##### FUNCTION gtk_notebook_prev_page ##### -->
<para>
-
+Switches to the previous page. Nothing happens if the current page is the
+first page.
</para>
-@notebook:
+@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_reorder_child ##### -->
<para>
-
+Moves the page @child, so that it appears in position @position. Out of
+bounds @position will be clamped.
</para>
-@notebook:
-@child:
-@position:
+@notebook: the notebook widget
+@child: the child to deplace
+@position: the new position
<!-- ##### FUNCTION gtk_notebook_set_tab_pos ##### -->
<para>
-
+Sets the position of the bookmarks.
</para>
-@notebook:
-@pos:
+@notebook: the notebook widget
+@pos: the position
<!-- ##### FUNCTION gtk_notebook_set_show_tabs ##### -->
<para>
-
+Sets whether to show the bookmarks or not.
</para>
-@notebook:
-@show_tabs:
+@notebook: the notebook widget
+@show_tabs: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_show_border ##### -->
<para>
-
+Sets whether to show the border of the notebook or not. Bookmarks are in the
+border.
</para>
-@notebook:
-@show_border:
+@notebook: the notebook widget
+@show_border: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_scrollable ##### -->
<para>
-
+Sets whether the bookmarks area may be scrollable or not if there are too
+many bookmarks to fit in the allocated area.
</para>
-@notebook:
-@scrollable:
+@notebook: the notebook widget
+@scrollable: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_tab_border ##### -->
<para>
+Sets whether there should be a border around the bookmarks or not.
+</para>
+
+@notebook: the notebook widget
+@border_width: a boolean value
+
+
+<!-- ##### FUNCTION gtk_notebook_set_tab_hborder ##### -->
+<para>
+Sets whether the tabs should have a horizontal border.
+</para>
+@notebook: the notebook widget
+@tab_hborder: a boolean value
+
+
+<!-- ##### FUNCTION gtk_notebook_set_tab_vborder ##### -->
+<para>
+Sets whether the tabs should have a vertical border.
</para>
-@notebook:
-@border_width:
+@notebook: the notebook widget
+@tab_vborder: a boolean value
<!-- ##### FUNCTION gtk_notebook_popup_enable ##### -->
<para>
-
+Enables the popup menu: if the user clicks with the right mouse button on
+the bookmarks, a menu with all the pages will be popped up.
</para>
-@notebook:
+@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_popup_disable ##### -->
<para>
-
+Disables the popup menu
</para>
-@notebook:
+@notebook: the notebook widget
<!-- ##### FUNCTION gtk_notebook_get_current_page ##### -->
<para>
-
+Returns the page number of the current page.
</para>
-@notebook:
-@Returns:
+@notebook: the notebook widget
+@Returns: the page number
<!-- ##### FUNCTION gtk_notebook_get_menu_label ##### -->
<para>
-
+Returns the menu label of the page @child. NULL is returned if @child is not
+in @notebook or NULL if it has the default menu label.
</para>
-@notebook:
-@child:
-@Returns:
+@notebook: the notebook widget
+@child: the page
+@Returns: the menu label
<!-- ##### FUNCTION gtk_notebook_get_nth_page ##### -->
<para>
-
+Returns the content of the page number @page_num, or NULL if @page_num is
+out of bounds.
</para>
-@notebook:
-@page_num:
-@Returns:
+@notebook: the notebook widget
+@page_num: the page number
+@Returns: the content of the page
<!-- ##### FUNCTION gtk_notebook_get_tab_label ##### -->
<para>
-
+Returns the menu tab of the page @child. NULL is returned if @child is not
+in @notebook or NULL if it has the default tab label.
</para>
-@notebook:
-@child:
-@Returns:
+@notebook: the notebook widget
+@child: the page
+@Returns: the tab label
<!-- ##### FUNCTION gtk_notebook_query_tab_label_packing ##### -->
<para>
-
+Looks for the packing attributes of the bookmarks of @child.
</para>
-@notebook:
-@child:
-@expand:
-@fill:
-@pack_type:
+@notebook: the notebook widget
+@child: the page
+@expand: a pointer to return the expand value (or NULL)
+@fill: a pointer to return the fill value (or NULL)
+@pack_type: a pointer to return the pack_type (or NULL)
<!-- ##### FUNCTION gtk_notebook_set_homogeneous_tabs ##### -->
<para>
-
+Sets whether the tabs must have all the same size or not.
</para>
-@notebook:
-@homogeneous:
+@notebook: the notebook widget
+@homogeneous: a boolean value
<!-- ##### FUNCTION gtk_notebook_set_menu_label ##### -->
<para>
-
+Changes the menu label of @child. Nothing happens if @child is not in
+@notebook.
</para>
-@notebook:
-@child:
-@menu_label:
+@notebook: the notebook widget
+@child: the page
+@menu_label: the menu label, or NULL for default
<!-- ##### FUNCTION gtk_notebook_set_menu_label_text ##### -->
<para>
-
+Creates a new label and sets it as the menu label of @child.
</para>
-@notebook:
-@child:
-@menu_text:
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_hborder ##### -->
-<para>
-
-</para>
-
-@notebook:
-@tab_hborder:
+@notebook: the notebook widget
+@child: the page
+@menu_text: the label text
<!-- ##### FUNCTION gtk_notebook_set_tab_label ##### -->
<para>
-
+Changes the bookmark label of @child. Nothing happens if @child is not in
+@notebook.
</para>
-@notebook:
-@child:
-@tab_label:
+@notebook: the notebook widget
+@child: the page
+@tab_label: the bookmark label, or NULL for default
<!-- ##### FUNCTION gtk_notebook_set_tab_label_packing ##### -->
<para>
-
+Sets the packing parameters for the bookmark of @child. See
+#GtkBoxPackStart for the exact meanings.
</para>
-@notebook:
-@child:
-@expand:
-@fill:
-@pack_type:
+@notebook: the notebook widget
+@child: the child widget
+@expand: whether to expand the bookmark or not
+@fill: whether the bookmark should fill the allocated area or not
+@pack_type: the position of the bookmark
<!-- ##### FUNCTION gtk_notebook_set_tab_label_text ##### -->
<para>
-
+Creates a new label and sets it as the bookmark label of @child.
</para>
-@notebook:
-@child:
-@tab_text:
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_vborder ##### -->
-<para>
-
-</para>
-
-@notebook:
-@tab_vborder:
+@notebook: the notebook widget
+@child: the page
+@tab_text: the label text
<!-- ##### SIGNAL GtkNotebook::switch-page ##### -->
<para>
-
+Emitted when the user or a function changes the current page.
</para>
@notebook: the object which received the signal.
-@page:
-@page_num:
+@page: the new current page
+@page_num: the index of the page
<!-- ##### ARG GtkNotebook:page ##### -->
<para>
-
+The current page
</para>
<!-- ##### ARG GtkNotebook:tab_pos ##### -->
<para>
-
+The position of the bookmarks
</para>
<!-- ##### ARG GtkNotebook:tab_border ##### -->
<para>
-
+Whether the bookmarks have a border or not
</para>
<!-- ##### ARG GtkNotebook:tab_hborder ##### -->
<para>
-
+Whether the bookmarks have a horizontal border or not
</para>
<!-- ##### ARG GtkNotebook:tab_vborder ##### -->
<para>
-
+Whether the bookmarks have a vertical border or not
</para>
<!-- ##### ARG GtkNotebook:show_tabs ##### -->
<para>
-
+Whether to show the bookmarks or not
</para>
<!-- ##### ARG GtkNotebook:show_border ##### -->
<para>
-
+Whether to show the border or not
</para>
<!-- ##### ARG GtkNotebook:scrollable ##### -->
<para>
-
+Whether the bookmarks should be scrollable or not
</para>
<!-- ##### ARG GtkNotebook:enable_popup ##### -->
<para>
-
+Whether the popup menu is enabled or not
</para>
-<!-- ##### SECTION Title ##### -->
-GtkObject
-
-<!-- ##### SECTION Short_Description ##### -->
-
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkObject ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### ENUM GtkObjectFlags ##### -->
-<para>
-
-</para>
-
-@GTK_DESTROYED:
-@GTK_FLOATING:
-@GTK_CONNECTED:
-@GTK_CONSTRUCTED:
-
-<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
-<para>
-
-</para>
-
-@obj:
-
-
-<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-@flag:
-
-
-<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
-<para>
-
-</para>
-
-@obj:
-@flag:
-
-
-<!-- ##### ENUM GtkArgFlags ##### -->
-<para>
-
-</para>
-
-@GTK_ARG_READABLE:
-@GTK_ARG_WRITABLE:
-@GTK_ARG_CONSTRUCT:
-@GTK_ARG_CONSTRUCT_ONLY:
-@GTK_ARG_CHILD_ARG:
-@GTK_ARG_MASK:
-@GTK_ARG_READWRITE:
-
-<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
-<para>
-
-</para>
-
-@klass:
-@name:
-@signal_flags:
-@marshaller:
-@return_val:
-@nparams:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
-<para>
-
-</para>
-
-@klass:
-@name:
-@signal_flags:
-@marshaller:
-@return_val:
-@nparams:
-@params:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_new ##### -->
-<para>
-
-</para>
-
-@type:
-@first_arg_name:
-@Varargs:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_newv ##### -->
-<para>
-
-</para>
-
-@object_type:
-@n_args:
-@args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_constructed ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_default_construct ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_sink ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_ref ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_unref ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_weakref ##### -->
-<para>
-
-</para>
-
-@object:
-@notify:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_weakunref ##### -->
-<para>
-
-</para>
-
-@object:
-@notify:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_destroy ##### -->
-<para>
-
-</para>
-
-@object:
-
-
-<!-- ##### FUNCTION gtk_object_getv ##### -->
-<para>
-
-</para>
-
-@object:
-@n_args:
-@args:
-
-
-<!-- ##### FUNCTION gtk_object_set ##### -->
-<para>
-
-</para>
-
-@object:
-@first_arg_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_object_setv ##### -->
-<para>
-
-</para>
-
-@object:
-@n_args:
-@args:
-
-
-<!-- ##### FUNCTION gtk_object_query_args ##### -->
-<para>
-
-</para>
-
-@class_type:
-@arg_flags:
-@n_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_set_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_full ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@data:
-@destroy:
-
-
-<!-- ##### FUNCTION gtk_object_remove_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-
-
-<!-- ##### FUNCTION gtk_object_get_data ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
-<para>
-
-</para>
-
-@object:
-@key:
-
-
-<!-- ##### FUNCTION gtk_object_set_user_data ##### -->
-<para>
-
-</para>
-
-@object:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_get_user_data ##### -->
-<para>
-
-</para>
-
-@object:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
-<para>
-
-</para>
-
-@klass:
-@signals:
-@nsignals:
-
-
-<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
-<para>
-
-</para>
-
-@arg_name:
-@arg_type:
-@arg_flags:
-@arg_id:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@data:
-
-
-<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@data:
-@destroy:
-
-
-<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@data_id:
-
-
-<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
-<para>
-
-</para>
-
-@object:
-@key_id:
-
-
-<!-- ##### MACRO gtk_object_data_try_key ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_object_data_force_id ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_object_arg_set ##### -->
-<para>
-
-</para>
-
-@object:
-@arg:
-@info:
-
-
-<!-- ##### FUNCTION gtk_object_arg_get ##### -->
-<para>
-
-</para>
-
-@object:
-@arg:
-@info:
-
-
-<!-- ##### FUNCTION gtk_object_args_collect ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_list_p:
-@info_list_p:
-@first_arg_name:
-@var_args:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
-<para>
-
-</para>
-
-@object_type:
-@arg_name:
-@info_p:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_trace_referencing ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@dummy:
-@line:
-@do_ref:
-
-
-<!-- ##### SIGNAL GtkObject::destroy ##### -->
-<para>
-
-</para>
-
-@object: the object which received the signal.
-
-<!-- ##### ARG GtkObject:user_data ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:signal ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:signal_after ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:object_signal ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkObject:object_signal_after ##### -->
-<para>
-
-</para>
-
+<!-- ##### SECTION Title ##### -->\r
+GtkObject\r
+\r
+<!-- ##### SECTION Short_Description ##### -->\r
+The base class of the Gtk type hierarchy.\r
+\r
+<!-- ##### SECTION Long_Description ##### -->\r
+<refsect2>\r
+<title>Description</title>\r
+<para>\r
+GtkObject is the root of the gtk+ type hierarchy. It serves\r
+a similar roles as java's Object class. It is used \r
+by the type-casting system to represent the base composite type.\r
+</para>\r
+<para>\r
+Objects have <wordasword>arguments</wordasword> that are\r
+name/typed-value pairs. \r
+They may be readable or writable (or both or neither).\r
+The special handlers in every object are responsible for\r
+setting and getting these parameters.\r
+If the handler for a given argument <emphasis>must</emphasis>\r
+be called before the object may be used, be sure the\r
+#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags\r
+are set; otherwise they are set only when the user does so.\r
+</para>\r
+<para>\r
+Object also store a simpler association table, sometimes\r
+called the object_data. This is just an efficient mapping from\r
+a fixed set of strings to a gpointer. This can be used as\r
+arbitrary extra members. Notice that each new field name\r
+allocates a new quark, so it is probably best only to use\r
+this for fields with fixed names.\r
+</para>\r
+<para>\r
+The primary difference between object_data and arguments is that\r
+the object defines two functions which set and get each type of argument.\r
+The object just has a table to store its object data in: it does not\r
+receive notice when data changes.\r
+</para>\r
+<para>\r
+Objects are reference counted; this means that we maintain\r
+a count of how many references (usually in the form of a pointer)\r
+are being held to this object.\r
+To indicate that you reference an object, call gtk_object_ref().\r
+The object will not be freed until everyone calls \r
+gtk_object_unref().\r
+</para>\r
+<para>\r
+In order to reduce the chances of a memory leak, gtk+ defines\r
+"floating objects". All objects created with gtk_object_new()\r
+start out floating with a reference count of 1.\r
+In order to reduce that initial reference count you should gtk_object_sink()\r
+them, but usually the parent widget you add the child to will\r
+sink the object. \r
+</para>\r
+<para>So, because gtk_widget_set_parent() sinks the object from\r
+gtk_container_add(), there are no memory leaks in this code:\r
+<informalexample>\r
+<programlisting>\r
+ button = gtk_button_new_with_label("Hi Mom!");\r
+ gtk_container_add(GTK_CONTAINER(window), button);\r
+ /* Button may not be used anymore since we don't retain a reference\r
+ * to it. */\r
+</programlisting>\r
+</informalexample>\r
+Likewise, the following code attaches the same adjustment to two\r
+ranges:\r
+<informalexample>\r
+<programlisting>\r
+ adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);\r
+ gtk_range_set_adjustment(range1, adjustment);\r
+ gtk_range_set_adjustment(range2, adjustment);\r
+</programlisting>\r
+</informalexample>\r
+Note that we could put as many set_adjustments as we like: cleanup is easy\r
+because they all retain a reference but only one sinks the initial reference\r
+count. If it is possible for "range1" to stop retaining its reference\r
+then we need to enclose the lines using "adjustment" with ref/unref\r
+to guarantee the the object won't be deleted:\r
+<informalexample>\r
+<programlisting>\r
+ adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0);\r
+ gtk_object_ref(GTK_OBJECT(adjustment));\r
+ gtk_range_set_adjustment(range1, adjustment);\r
+ gtk_range_set_adjustment(range1, another_adjustment);\r
+ /* With the initial reference, `adjustment' would have\r
+ * been deleted as `range1' lost its reference to it. */\r
+ gtk_range_set_adjustment(range2, adjustment);\r
+ gtk_object_unref(GTK_OBJECT(adjustment));\r
+</programlisting>\r
+</informalexample>\r
+</para>\r
+<para>\r
+Be careful with reference counting: if two objects reference eachother\r
+then they will always have at least reference count 1, even if\r
+there are no other pointers to them. This means that they\r
+will never be freed. More precisely, you must be certain that\r
+your references <emphasis>never</emphasis> can form cycles.\r
+</para>\r
+<para>\r
+If you find yourself forming cyclic references, perhaps you\r
+can convert some of them to <wordasword>weak-references</wordasword>.\r
+A weak-reference is one that holds a pointer to an object,\r
+but doesn't increase the reference count. To insure\r
+the object is valid when the referer tries to use it,\r
+the referer registers a callback that will be invoked\r
+after the object has been destroyed (but before its memory is actually\r
+deallocated). This callback must prevent the weak-reference from\r
+being used again.\r
+</para>\r
+</refsect2>\r
+<refsect2>\r
+<title>Brief Glossary</title>\r
+<variablelist>\r
+\r
+<varlistentry>\r
+<term>argument</term>\r
+<listitem><para>\r
+A typed-variable identified by ObjectType::argument_name. It may be\r
+readable, writable, both or none. For example,\r
+"GtkButton::label" is a read/write string-valued argument.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>constructed</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>destroyed</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>finalization</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>floating</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>object data</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>reference count</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>weak-reference</term>\r
+<listitem><para>\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+</variablelist>\r
+</refsect2>\r
+\r
+<!-- ##### SECTION See_Also ##### -->\r
+<para>\r
+GtkType, GtkArg, gtk-signals.\r
+</para>\r
+\r
+<!-- ##### STRUCT GtkObject ##### -->\r
+<para>\r
+The object itself. You should never use these members directly-\r
+instead you the accessing macros.\r
+</para>\r
+\r
+@klass: a pointer to the GtkObjectClass (or deriver) which contains \r
+the methods defined by this object.\r
+@flags: the state of the object: whether it has been constructed\r
+or destroyed, for example.\r
+@ref_count: a reference count. It is incremented when new\r
+pointers to this object are made, and decremented when the\r
+pointers are deleted. When the reference count\r
+returns to 0, the object is deleted. By default, objects\r
+have reference count 0 when created.\r
+@object_data: \r
+\r
+<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->\r
+<para>\r
+Get the type of an object.\r
+</para>\r
+\r
+@obj: the object whose type we wish to get.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->\r
+<para>\r
+Get the array of signals defined for this object.\r
+</para>\r
+\r
+@obj: the object to fetch the signals from.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->\r
+<para>\r
+Get the number of signals defined by this object.\r
+</para>\r
+\r
+@obj: the object to query.\r
+\r
+\r
+<!-- ##### ENUM GtkObjectFlags ##### -->\r
+<para>\r
+Tells about the state of the object.\r
+</para>\r
+\r
+@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it\r
+and is processing the shutdown callback.\r
+@GTK_FLOATING: whether the object is orphaned. Objects that take\r
+strong hold of an object may gtk_object_sink() it, after obtaining\r
+there own references, if they believe they are nearly primary\r
+ownership of the object.\r
+GTK_CONNECTED: refers to whether are signals are connected to this\r
+object.\r
+@GTK_CONSTRUCTED: refers to whether the arguments for this object are\r
+ready.\r
+\r
+<!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->\r
+<para>\r
+Get the #GtkObjectFlags for an object without directly\r
+accessing its members.\r
+</para>\r
+\r
+@obj: the object whose flags are returned.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_DESTROYED ##### -->\r
+<para>\r
+Test whether a GtkObject has had gtk_object_destroyed() invoked on it.\r
+</para>\r
+\r
+@obj: the object to examine.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->\r
+<para>\r
+When an object is created, it has an initial reference count\r
+of 1 and is floating. <wordasword>Sinking</wordasword> the object \r
+refers to decrementing that original reference count.\r
+</para>\r
+\r
+@obj: the object to examine.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->\r
+<para>\r
+Test whether a GtkObject has had a signal connected to it.\r
+</para>\r
+\r
+@obj: the object to examine.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->\r
+<para>\r
+Test whether a GtkObject's arguments have been prepared.\r
+</para>\r
+\r
+@obj: the object to examine.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->\r
+<para>\r
+Turn on certain object flags. (Private)\r
+</para>\r
+\r
+@obj: the object to affect.\r
+@flag: the flags to set.\r
+\r
+\r
+<!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->\r
+<para>\r
+Turn off certain object flags. (Private)\r
+</para>\r
+\r
+@obj: the object to affect.\r
+@flag: the flags to unset.\r
+\r
+\r
+<!-- ##### ENUM GtkArgFlags ##### -->\r
+<para>\r
+Possible flags indicating how an argument should be treated.\r
+</para>\r
+\r
+@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)\r
+@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)\r
+@GTK_ARG_CONSTRUCT: the argument needs construction.\r
+@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will\r
+be set once during object creation), but is otherwise cannot be\r
+set. Hence this flag is not allowed with #GTK_ARG_WRITABLE,\r
+and is redundant with #GTK_ARG_CONSTRUCT.\r
+@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)\r
+each child. Used by #GtkContainer.\r
+@GTK_ARG_MASK: the bitwise-OR of all the flags.\r
+@GTK_ARG_READWRITE: the argument is readable and writable.\r
+\r
+<!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->\r
+<para>\r
+Define a signal-handler for a new signal on an already defined\r
+object.\r
+</para>\r
+<para>\r
+See the signal documentation for more general information.\r
+</para>\r
+\r
+@klass: the object class to define the signal for.\r
+@name: the name of the signal.\r
+@signal_flags: the default emission behavior for the signal.\r
+See gtk_signal_new().\r
+@marshaller: a function that will take an array of GtkArgs\r
+and invoke the appropriate handler with the normal calling\r
+conventions.\r
+@return_val: specify the return-value type for the signal\r
+(or GTK_TYPE_NONE for no return-value).\r
+@nparams: specify the number of parameters the signal\r
+receives from the caller of gtk_signal_emit().\r
+@Varargs: list of nparams #GtkTypes to pass to the signal handlers.\r
+@Returns: the signal id. (See #GtkSignals)\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->\r
+<para>\r
+Define a signal-handler for a new signal on an already defined\r
+object.\r
+</para>\r
+\r
+@klass: the object class to define the signal for.\r
+@name: the name of the signal.\r
+@signal_flags: the default emission behavior for the signal.\r
+See gtk_signal_new().\r
+@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array\r
+of arguments, and invokes the function using the appropriate\r
+calling conventions. Usually just select a function\r
+out of gtkmarshal.h.\r
+@return_val: specify the return-value type for the signal (possibly\r
+#GTK_TYPE_NONE).\r
+@nparams: specify the number of parameters the signal\r
+receives from the caller of gtk_signal_emit().\r
+@params: array of #GtkTypes the signal handlers for this signal\r
+should have in their prototype (of length nparams).\r
+@Returns: the signal id. (See #GtkSignals)\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_new ##### -->\r
+<para>\r
+Construct an object given its arguments, enumerated in the call to the\r
+function.\r
+</para>\r
+\r
+@type: the type identifying this object. Returned by gtk_type_unique()\r
+although (for a properly-written object it should be accessible through\r
+#GTK_TYPE_FOO.)\r
+@first_arg_name: name of the first argument to set when constructing\r
+the object.\r
+@Varargs: the first argument's value, followed by any number of\r
+name/argument-value pairs, terminated with NULL.\r
+@Returns: the new GtkObject.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_newv ##### -->\r
+<para>\r
+Construct an object with an array of arguments.\r
+</para>\r
+\r
+@object_type: the type of the object to create.\r
+@n_args: the number of arguments to set.\r
+@args: an array of n_args arguments (which are name and value pairs).\r
+@Returns: the new GtkObject.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_constructed ##### -->\r
+<para>\r
+Mark an allocated object as constructed.\r
+This is used for situations\r
+that require precise control of the construction process.\r
+</para>\r
+<para>\r
+This is done when gtk_object_default_construct() is inadequate.\r
+In #GtkCList the need arises because #GtkCList does construction work that\r
+must happen <emphasis>after</emphasis> its derivers. This work\r
+cannot be done in an initializer function, so an alternate\r
+constructor is mandatory. It calls gtk_object_constructed() to\r
+indicate it has done its job, so that no other constructor will\r
+be invoked.\r
+</para>\r
+<para>\r
+Normally this function is just automatically run from\r
+gtk_object_default_construct().\r
+</para>\r
+\r
+@object: object which has been constructed. This is usually\r
+done automatically by gtk_object_new() and gtk_object_newv().\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_default_construct ##### -->\r
+<para>\r
+This function is called to construct arguments that haven't been initialized\r
+but have the #GTK_ARG_CONSTRUCT flag set.\r
+</para>\r
+<para>\r
+All number arguments are set to 0. All pointers and strings\r
+are set to NULL.\r
+</para>\r
+<para>\r
+Normally invoked by gtk_object_new() automatically; gtk_type_new() can\r
+be used to bypass it.\r
+</para>\r
+\r
+@object: the object to initialize.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_sink ##### -->\r
+<para>\r
+Decrement the initial count given to the object.\r
+Additional invocations have no effect.\r
+</para>\r
+<para>\r
+This is designed to free the user from worrying about\r
+dereferencing an object that they have just created.\r
+So long as the object is sunk at some point, the reference count\r
+will be set properly.\r
+</para>\r
+<para>\r
+furthermore it may be sunk multiple times.\r
+Only the first time will actually dereference.\r
+</para>\r
+<para>\r
+The basic outline is: when you create an object it is floating.\r
+Setting its parent causes it to be sunk, however its parent\r
+has obtained a reference, so its reference count is one.\r
+</para>\r
+\r
+@object: the object to sink.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_ref ##### -->\r
+<para>\r
+Increase the reference count of the object.\r
+</para>\r
+\r
+@object: the object to reference.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_unref ##### -->\r
+<para>\r
+Decrease the reference count of an object. When its reference\r
+count drops to 0, the object is deleted.\r
+</para>\r
+<para>\r
+If it was not already destroyed, it will be, with gtk_object_destroy(),\r
+then weak links are notified, then the object-data is freed\r
+and the memory for the object itself is freed using gtk_type_free().\r
+</para>\r
+\r
+@object: the object to dereference.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_weakref ##### -->\r
+<para>\r
+Adds a weak reference callback to an object.\r
+</para>\r
+<para>\r
+Weak references are a mechanism to safely keep a pointer to\r
+an object without using the reference counting\r
+mechansim. They use a callback function to receive\r
+notice that the object is about to be freed (aka finalized).\r
+This happens <emphasis>after</emphasis> the destroy\r
+callback has been run.\r
+</para>\r
+\r
+@object: object to weakly reference.\r
+@notify: callback to invoke before the object is freed.\r
+@data: extra data to pass to #notify.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_weakunref ##### -->\r
+<para>\r
+Removes a weak reference callback to an object.\r
+</para>\r
+\r
+@object: object stop weakly referencing.\r
+@notify: callback to search for.\r
+@data: data to search for.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_destroy ##### -->\r
+<para>\r
+Calls the object's shutdown handler.\r
+</para>\r
+<para>\r
+The memory for the object itself won't be deleted until\r
+its reference count drops to 0, though.\r
+See gtk_object_unref().\r
+</para>\r
+\r
+@object: the object to destroy.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_getv ##### -->\r
+<para>\r
+Gets an array of argument values from an object.\r
+</para>\r
+\r
+@object: the object to get arguments from.\r
+@n_args: the number of arguments to query.\r
+@args: the arguments to fill in.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set ##### -->\r
+<para>\r
+This function sets multiple arguments of an object.\r
+</para>\r
+<para>\r
+It takes an object, then a list of name/value pairs\r
+in a list, followed by NULL.\r
+</para>\r
+<para>\r
+<informalexample>\r
+<programlisting>\r
+void set_box_properties(GtkBox* box)\r
+{\r
+ gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,\r
+ "spacing", 8,\r
+ NULL);\r
+}\r
+</programlisting>\r
+</informalexample>\r
+</para>\r
+\r
+\r
+@object: the object whose arguments should be set.\r
+@first_arg_name: the name of the first argument to set.\r
+@Varargs: the value of the first argument, followed optionally\r
+by more name/value pairs, followed by NULL.\r
+\r
+<!-- ##### FUNCTION gtk_object_setv ##### -->\r
+<para>\r
+Set an array of arguments.\r
+</para>\r
+\r
+@object: the object whose arguments should be set.\r
+@n_args: the number of arguments to set.\r
+@args: the desired values, as an array of #GtkArgs (which contain \r
+the names, types, and values of the arguments).\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_query_args ##### -->\r
+<para>\r
+Get all the arguments that may be used for a given type.\r
+</para>\r
+<para>\r
+In Java, this type of mechanism is called \r
+<wordasword>introspection</wordasword>. It is used by applications\r
+like Glade, that have to determine what can be done to an object\r
+at run-time.\r
+</para>\r
+\r
+@class_type: the GtkType of the ObjectClass\r
+(returned from GTK_OBJECT_CLASS(class)->type for example).\r
+@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to\r
+each argument. You must g_free() this if you request it.\r
+@n_args: the number of arguments is returned in this field.\r
+@Returns: an array of arguments, that you must deallocate with g_free().\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set_data ##### -->\r
+<para>\r
+Each object carries around a table of associations from\r
+strings to pointers. This function lets you set an association.\r
+</para>\r
+<para>\r
+If the object already had an association with that name,\r
+the old association will be destroyed.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@key: name of the key.\r
+@data: data to associate with that key.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set_data_full ##### -->\r
+<para>\r
+Like gtk_object_set_data() except it adds notification\r
+for when the association is destroyed, either by\r
+gtk_object_remove_data() or when the object is destroyed.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@key: name of the key.\r
+@data: data to associate with that key.\r
+@destroy: function to call when the association is destroyed.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_remove_data ##### -->\r
+<para>\r
+Remove a specified datum from the object's data associations (the object_data).\r
+Subsequent calls to gtk_object_get_data() will return NULL.\r
+</para>\r
+<para>\r
+If you specified a destroy handler with gtk_object_set_data_full(),\r
+it will be invoked.\r
+</para>\r
+\r
+\r
+@object: the object maintaining the association.\r
+@key: name of the key for that association.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_get_data ##### -->\r
+<para>\r
+Get a named field from the object's table of associations (the object_data).\r
+</para>\r
+\r
+@object: the object maintaining the associations.\r
+@key: name of the key for that association.\r
+@Returns: the data if found, or NULL if no such data exists.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->\r
+<para>\r
+Remove a specified datum from the object's data associations (the object_data),\r
+without invoking the association's destroy handler.\r
+</para>\r
+<para>\r
+Just like gtk_object_remove_data() except that any destroy handler\r
+will be ignored.\r
+Therefore this only affects data set using gtk_object_set_data_full().\r
+</para>\r
+\r
+@object: the object maintaining the association.\r
+@key: name of the key for that association.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set_user_data ##### -->\r
+<para>\r
+For convenience, every object offers a generic user data\r
+pointer. The function set it.\r
+</para>\r
+<para>\r
+This function is equivalent to:\r
+<informalexample>\r
+<programlisting>\r
+ gtk_object_set_data(object, "user_data", data);\r
+</programlisting>\r
+</informalexample>\r
+</para>\r
+\r
+@object: the object whose user data should be set.\r
+@data: the new value for the user data.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_get_user_data ##### -->\r
+<para>\r
+Get the object's user data pointer.\r
+</para>\r
+<para>\r
+This is intended to be a pointer for your convenience in\r
+writing applications.\r
+</para>\r
+\r
+@object: the object.\r
+@Returns: the user data field for object.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_class_add_signals ##### -->\r
+<para>\r
+Add an array of signals to a #GtkObjectClass.\r
+Usually this is called when registering a new type of object.\r
+</para>\r
+\r
+@klass: the object class to append signals to.\r
+@signals: the signals to append.\r
+@nsignals: the number of signals being appended.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_add_arg_type ##### -->\r
+<para>\r
+Add a new type of argument to an object class.\r
+Usually this is called when registering a new type of object.\r
+</para>\r
+\r
+@arg_name: fully qualify object name, for example GtkObject::user_data.\r
+@arg_type: type of the argument.\r
+@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is\r
+settable or gettable, whether it is set when the object is constructed.)\r
+@arg_id: an internal number, passed in from here to the "set_arg" and\r
+"get_arg" handlers of the object.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->\r
+<para>\r
+Just like gtk_object_set_data() except that it takes\r
+a #GQuark instead of a string, so it is slightly faster.\r
+</para>\r
+<para>\r
+Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
+to get an id from a string.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@data_id: quark of the key.\r
+@data: data to associate with that key.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->\r
+<para>\r
+Just like gtk_object_set_data_full() except that it takes\r
+a #GQuark instead of a string, so it is slightly faster.\r
+</para>\r
+<para>\r
+Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
+to get an id from a string.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@data_id: quark of the key.\r
+@data: data to associate with that key.\r
+@destroy: function to call when the association is destroyed.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->\r
+<para>\r
+Just like gtk_object_get_data() except that it takes\r
+a #GQuark instead of a string, so it is slightly faster.\r
+</para>\r
+<para>\r
+Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
+to get an id from a string.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@data_id: quark of the key.\r
+@Returns: the data if found, or NULL if no such data exists.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->\r
+<para>\r
+Just like gtk_object_remove_data() except that it takes\r
+a #GQuark instead of a string, so it is slightly faster.\r
+</para>\r
+<para>\r
+Remove a specified datum from the object's data associations.\r
+Subsequent calls to gtk_object_get_data() will return NULL.\r
+</para>\r
+<para>\r
+Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
+to get an id from a string.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@data_id: quark of the key.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->\r
+<para>\r
+Just like gtk_object_remove_no_notify() except that it takes\r
+a #GQuark instead of a string, so it is slightly faster.\r
+</para>\r
+<para>\r
+Use gtk_object_data_try_key() and gtk_object_data_force_id()\r
+to get an id from a string.\r
+</para>\r
+\r
+@object: object containing the associations.\r
+@data_id: quark of the key.\r
+\r
+\r
+<!-- ##### MACRO gtk_object_data_try_key ##### -->\r
+<para>\r
+Sees whether a certain quark exists.\r
+Returns that quark if so.\r
+</para>\r
+<para>\r
+Although this is currently the same as g_quark_try_string(),\r
+it might someday be different, for example, if GQuarks\r
+and object data are converted to separate mechanisms,\r
+so it is good to use this macro.\r
+</para>\r
+\r
+\r
+\r
+<!-- ##### MACRO gtk_object_data_force_id ##### -->\r
+<para>\r
+Makes a quark from a string, possibly allocating a new quark.\r
+</para>\r
+<para>\r
+Although this is currently the same as g_quark_from_string(),\r
+it might someday be different, for example, if GQuarks\r
+and object data are converted to separate mechanisms,\r
+so it is good to use this macro.\r
+</para>\r
+\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_arg_set ##### -->\r
+<para>\r
+Private function to set an argument and argument info to an object.\r
+</para>\r
+\r
+@object: the object whose argument should be set.\r
+@arg: the argument.\r
+@info: infomation about this type of argument in general.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_arg_get ##### -->\r
+<para>\r
+Private function to get an argument and argument info from an object.\r
+</para>\r
+\r
+@object: the object whose argument should be retrieved.\r
+@arg: the argument, for the name on input, the rest is filled on output.\r
+@info: a #GtkArgInfo structure to optionally fill in.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_args_collect ##### -->\r
+<para>\r
+Private: Gets an array of #GtkArgs from a va_list C structure.\r
+</para>\r
+<para>\r
+\r
+@object_type: the type of object to collect arguments for.\r
+@arg_list_p: pointer to be filled in with a list of parsed arguments.\r
+@info_list_p: optional pointer for a returned list #GtkArgInfos.\r
+@first_arg_name: name of first argument.\r
+@var_args: value of first argument, followed by more key/value pairs,\r
+terminated by NULL.\r
+@Returns: an error message, or NULL on success.\r
+It is the caller's responsibility to call g_free() in the event of error.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_object_arg_get_info ##### -->\r
+<para>\r
+Query information about an argument type.\r
+</para>\r
+\r
+@object_type: type of object to query about.\r
+@arg_name: name of the argument.\r
+@info_p: pointer to be filled in with a pointer to the GtkArgInfo.\r
+@Returns: an error message, or NULL on success.\r
+It is the caller's responsibility to call g_free() in the event of error.\r
+\r
+\r
+<!-- ##### FUNCTION gtk_trace_referencing ##### -->\r
+<para>\r
+Private: print debugging information while doing a gtk_object_ref() or \r
+a gtk_object_unref().\r
+</para>\r
+\r
+@object: object to reference or unreference.\r
+@func: name of caller's function to print (used within macros).\r
+@dummy: unused.\r
+@line: line number (used within macros).\r
+@do_ref: whether to reference or unreference.\r
+\r
+\r
+<!-- ##### SIGNAL GtkObject::destroy ##### -->\r
+<para>\r
+Indicates that an object is being destroyed.\r
+</para>\r
+\r
+@object: the object which received the signal.\r
+\r
+<!-- ##### ARG GtkObject:user_data ##### -->\r
+<para>\r
+A pointer for convenience when programming applications.\r
+</para>\r
+\r
+<!-- ##### ARG GtkObject:signal ##### -->\r
+<para>\r
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
+the signal to the object.\r
+</para>\r
+\r
+<!-- ##### ARG GtkObject:signal_after ##### -->\r
+<para>\r
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
+the signal to the object, so that the signal is always run\r
+after other user handlers and the default handler.\r
+</para>\r
+\r
+<!-- ##### ARG GtkObject:object_signal ##### -->\r
+<para>\r
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
+the signal to the object, so that the user data and objects\r
+and swapped when the signal handler is invoked.\r
+</para>\r
+<para>\r
+This is useful for handlers that are primarily notifying\r
+other objects and could just invoke an already existing function\r
+if the parameters were swapped.\r
+See gtk_signal_connect_object() for more details.\r
+</para>\r
+\r
+<!-- ##### ARG GtkObject:object_signal_after ##### -->\r
+<para>\r
+Setting this with a GtkType of GTK_TYPE_SIGNAL connects\r
+the signal to the object, so that the user data and objects\r
+and swapped when the signal handler is invoked,\r
+and so that the handler is invoked after all others.\r
+</para>\r
+<para>\r
+See gtk_signal_connect_object_after() for more details.\r
+</para>\r
+\r
GtkProgress
<!-- ##### SECTION Short_Description ##### -->
-
+the base class for #GtkProgressBar.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GtkProgress is the abstract base class used to derive
+a #GtkProgressBar which provides a visual representation of
+the progress of a long running operation.
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GtkProgress ##### -->
<para>
-
+The #GtkProgress-struct struct contains private data only.
+and should be accessed using the functions below.
</para>
-
<!-- ##### FUNCTION gtk_progress_set_show_text ##### -->
<para>
-
+Controls whether progress text is shown.
</para>
-@progress:
-@show_text:
-
+@progress: a #GtkProgress.
+@show_text: a boolean indicating whether the progress text
+is shown.
<!-- ##### FUNCTION gtk_progress_set_text_alignment ##### -->
<para>
-
+Controls the alignment of the text within the progress bar area.
</para>
-@progress:
-@x_align:
-@y_align:
+@progress: a #GtkProgress.
+@x_align: a number between 0.0 and 1.0 indicating the horizontal
+alignment of the progress text within the #GtkProgress.
+@y_align: a number between 0.0 and 1.0 indicating the vertical
+alignment of the progress text within the #GtkProgress.
<!-- ##### FUNCTION gtk_progress_set_format_string ##### -->
<para>
+Sets a format string used to display text indicating the
+current progress. The string can contain the following substitution characters:
+<itemizedlist>
+<listitem>
+<para>
+%%v - the current progress value.
+</para>
+<listitem>
+<para>
+%%l - the lower bound for the progress value.
+</para>
+<listitem>
+<para>
+%%u - the upper bound for the progress value.
+</para>
+<listitem>
+<para>
+%%p - the current progress percentage.
+</para>
+</itemizedlist>
</para>
-@progress:
-@format:
+@progress: a #GtkProgress.
+@format: a string used to display progress text.
<!-- ##### FUNCTION gtk_progress_set_adjustment ##### -->
<para>
-
+Associates a #GtkAdjustment with the #GtkProgress. A #GtkAdjustment
+is used to represent the upper and lower bounds and the step interval
+of the underlying value for which progress is shown.
</para>
-@progress:
-@adjustment:
+@progress: a #GtkProgress.
+@adjustment: the #GtkAdjustment to be associated with the #GtkProgress.
<!-- ##### FUNCTION gtk_progress_set_percentage ##### -->
<para>
-
+Sets the current percentage completion for the #GtkProgress.
</para>
-@progress:
-@percentage:
+@progress: a #GtkProgress.
+@percentage: the percentage complete which must be between 0.0
+and 1.0.
<!-- ##### FUNCTION gtk_progress_set_value ##### -->
<para>
-
+Sets the value within the #GtkProgress to an absolute value.
+The value must be within the valid range of values for the
+underlying #GtkAdjustment.
</para>
-@progress:
-@value:
+@progress: a #GtkProgress.
+@value: the value indicating the current completed amount.
<!-- ##### FUNCTION gtk_progress_get_value ##### -->
<para>
-
+Returns the current progress complete value.
</para>
-@progress:
-@Returns:
+@progress: a #GtkProgress.
+@Returns: the current progress complete value.
<!-- ##### FUNCTION gtk_progress_set_activity_mode ##### -->
<para>
-
+A #GtkProgress can be in one of two different modes: percentage
+mode (the default) and activity mode. In activity mode, the
+progress is simply indicated as activity rather than as a percentage
+complete.
</para>
-@progress:
-@activity_mode:
+@progress: a #GtkProgress.
+@activity_mode: a boolean, TRUE for activity mode.
<!-- ##### FUNCTION gtk_progress_get_current_text ##### -->
<para>
-
+Returns the current text associated with the #GtkProgress. This
+text is the based on the underlying format string after any substitutions
+are made.
</para>
-@progress:
-@Returns:
+@progress: a #GtkProgress.
+@Returns: the text indicating the current progress.
<!-- ##### FUNCTION gtk_progress_get_text_from_value ##### -->
<para>
-
+Returns the text indicating the progress based on the supplied value.
+The current value for the #GtkProgress remains unchanged.
</para>
-@progress:
-@value:
-@Returns:
+@progress: a #GtkProgress.
+@value: an absolute progress value to use when formatting the progress text.
+@Returns: a string indicating the progress.
<!-- ##### FUNCTION gtk_progress_get_current_percentage ##### -->
<para>
-
+Returns the current progress as a percentage.
</para>
-@progress:
-@Returns:
+@progress: a #GtkProgress.
+@Returns: a number between 0.0 and 1.0 indicating the percentage complete.
<!-- ##### FUNCTION gtk_progress_get_percentage_from_value ##### -->
<para>
-
+Returns the progress as a percentage calculated from the supplied
+absolute progress value.
</para>
-@progress:
-@value:
-@Returns:
+@progress: a #GtkProgress.
+@value: an absolute progress value.
+@Returns: a number between 0.0 and 1.0 indicating the percentage complete
+represented by @value.
<!-- ##### FUNCTION gtk_progress_configure ##### -->
<para>
-
+Allows the configuration of the minimum, maximum, and current values for
+the #GtkProgress.
</para>
-@progress:
-@value:
-@min:
-@max:
+@progress: a #GtkProgress.
+@value: the current progress value.
+@min: the minimum progress value.
+@max: the maximum progress value.
<!-- ##### ARG GtkProgress:activity_mode ##### -->
<para>
-
+A boolean indicating whether activity mode is enabled.
</para>
<!-- ##### ARG GtkProgress:show_text ##### -->
<para>
-
+A boolean indicating whether the progress is shown as text.
</para>
<!-- ##### ARG GtkProgress:text_xalign ##### -->
<para>
-
+A number between 0.0 and 1.0 specifying the horizontal alignment.
</para>
<!-- ##### ARG GtkProgress:text_yalign ##### -->
<para>
-
+A number between 0.0 and 1.0 specifying the vertical alignment.
</para>
-
GtkProgressBar
<!-- ##### SECTION Short_Description ##### -->
-
+a widget which indicates progress visually.
<!-- ##### SECTION Long_Description ##### -->
<para>
+The #GtkProgressBar is typically used to display the progress of a long
+running operation. It provides a visual clue that processing
+is underway. The #GtkProgressBar can be used in two different
+modes: percentage mode and activity mode.
+</para>
+
+<para>
+When an application can determine how much work needs to take place
+(e.g. read a fixed number of bytes from a file) and can monitor its
+progress, it can use the #GtkProgressBar in percentage mode and the user
+sees a growing bar indicating the percentage of the work that has
+been completed. In this mode, the application is required to call
+either the gtk_progress_set_percentage() or gtk_progress_set_value()
+functions periodically to update the progress bar.
+</para>
+<para>
+When an application has no accurate way of knowing the amount of work
+to do, it can use the #GtkProgressBar in activity mode. In this mode
+the progress bar shows activity by a block moving back and forth within
+the progress area.
+</para>
+
+<para>
+There is quite a bit of flexibility provided to control the appearance
+of the #GtkProgressBar. Functions are provided to control the
+orientation of the bar, optional text which can be displayed along with
+the bar, and the style in which the bar grows.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkProgressBar ##### -->
<para>
-
+The #GtkProgressBar-struct struct contains private data only,
+and should be accessed using the functions below.
</para>
<!-- ##### ENUM GtkProgressBarStyle ##### -->
<para>
+An enumeration representing the styles for drawing the progress bar.
-</para>
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GTK_PROGRESS_CONTINUOUS</entry>
+<entry>The progress bar grows in a smooth, continuous manner.</entry>
+</row>
+
+<row>
+<entry>GTK_PROGRESS_DISCRETE</entry>
+<entry>The progress bar grows in discrete, visible blocks.</entry>
+</row>
-@GTK_PROGRESS_CONTINUOUS:
-@GTK_PROGRESS_DISCRETE:
+</tbody></tgroup></informaltable>
+</para>
<!-- ##### ENUM GtkProgressBarOrientation ##### -->
<para>
+An enumeration representing possible orientations and growth
+directions for the visible progress bar.
-</para>
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>GTK_PROGRESS_LEFT_TO_RIGHT</entry>
+<entry>A horizontal progress bar growing from left to right.</entry>
+</row>
+
+<row>
+<entry>GTK_PROGRESS_RIGHT_TO_LEFT</entry>
+<entry>A horizontal progress bar growing from right to left.</entry>
+</row>
-@GTK_PROGRESS_LEFT_TO_RIGHT:
-@GTK_PROGRESS_RIGHT_TO_LEFT:
-@GTK_PROGRESS_BOTTOM_TO_TOP:
-@GTK_PROGRESS_TOP_TO_BOTTOM:
+<row>
+<entry>GTK_PROGRESS_BOTTOM_TO_TOP</entry>
+<entry>A vertical progress bar growing from bottom to top.</entry>
+</row>
+
+<row>
+<entry>GTK_PROGRESS_TOP_TO_BOTTOM</entry>
+<entry>A vertical progress bar growing from top to bottom.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
<!-- ##### FUNCTION gtk_progress_bar_new ##### -->
<para>
-
+Creates a new #GtkProgressBar.
</para>
-@Returns:
+@Returns: a #GtkProgressBar.
<!-- ##### FUNCTION gtk_progress_bar_new_with_adjustment ##### -->
<para>
-
+Creates a new #GtkProgressBar with an associated #GtkAdjustment.
</para>
-@adjustment:
-@Returns:
+@adjustment: a #GtkAdjustment.
+@Returns: a #GtkProgressBar.
<!-- ##### FUNCTION gtk_progress_bar_set_bar_style ##### -->
<para>
-
+Sets the style of the #GtkProgressBar. The default style is
+%GTK_PROGRESS_CONTINUOUS.
</para>
-@pbar:
-@style:
+@pbar: a #GtkProgressBar.
+@style: a #GtkProgressBarStyle value indicating the desired style.
<!-- ##### FUNCTION gtk_progress_bar_set_discrete_blocks ##### -->
<para>
-
+Sets the number of blocks that the progress bar is divided into
+when the style is %GTK_PROGRESS_DISCRETE.
</para>
-@pbar:
-@blocks:
+@pbar: a #GtkProgressBar.
+@blocks: number of individual blocks making up the bar.
<!-- ##### FUNCTION gtk_progress_bar_set_activity_step ##### -->
<para>
-
+Sets the step value used when the progress bar is in activity
+mode. The step is the amount by which the progress is incremented
+each iteration.
</para>
-@pbar:
-@step:
+@pbar: a #GtkProgressBar.
+@step: the amount which the progress is incremented in activity
+mode.
<!-- ##### FUNCTION gtk_progress_bar_set_activity_blocks ##### -->
<para>
-
+Sets the number of blocks used when the progress bar is in activity
+mode. Larger numbers make the visible block smaller.
</para>
-@pbar:
-@blocks:
+@pbar: a #GtkProgressBar.
+@blocks: number of blocks which can fit within the progress bar area.
<!-- ##### FUNCTION gtk_progress_bar_set_orientation ##### -->
<para>
-
+Sets the orientation of the progress bar. This controls whether
+the bar is horizontal or vertical and the direction in which it
+grows.
</para>
-@pbar:
-@orientation:
+@pbar: a #GtkProgressBar.
+@orientation: a #GtkProgressBarOrientation value which specifies the
+orientation and growth direction of the bar.
<!-- ##### FUNCTION gtk_progress_bar_update ##### -->
<para>
-
+This function is deprecated. Please use gtk_progress_set_value() or
+gtk_progress_set_percentage() instead.
</para>
-@pbar:
-@percentage:
+@pbar: a #GtkProgressBar.
+@percentage: the new percent complete value.
<!-- ##### ARG GtkProgressBar:adjustment ##### -->
<para>
-
+a #GtkAdjustment to be used with the #GtkProgressBar.
</para>
<!-- ##### ARG GtkProgressBar:orientation ##### -->
<para>
-
+a #GtkProgressBarOrientation value which specifies the
+orientation and growth direction of the bar.
</para>
<!-- ##### ARG GtkProgressBar:bar_style ##### -->
<para>
-
+a #GtkProgressBarStyle value which specifies the
+visual style of the bar in percentage mode.
</para>
<!-- ##### ARG GtkProgressBar:activity_step ##### -->
<para>
-
+The increment used for each iteration in activity mode.
</para>
<!-- ##### ARG GtkProgressBar:activity_blocks ##### -->
<para>
-
+The number of blocks which can fit in the progress bar
+area in activity mode.
</para>
<!-- ##### ARG GtkProgressBar:discrete_blocks ##### -->
<para>
-
+The number of blocks which which make up progress bar
+when it is shown in %GTK_PROGRESS_DISCRETE style.
</para>
GtkVButtonBox
<!-- ##### SECTION Short_Description ##### -->
-
+a container for arranging buttons vertically.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A button box should be used to provide a consistent layout of buttons
+throughout your application. There is one default layout and a default
+spacing value that are persistant across all #VButtonBox widgets.
+</para>
+<para>
+The layout/spacing can then be altered by the programmer, or if desired, by
+the user to alter the 'feel' of a program to a small degree.
+</para>
+<para>
+A #VButtonBox is created with gtk_vbutton_box_new(). Buttons are packed into
+a button box the same way as any other box, using gtk_box_pack_start() or
+gtk_box_pack_end().
+</para>
+<para>
+The default spacing between buttons can be set with
+gtk_vbutton_box_set_spacing_default() and queried with
+gtk_vbutton_box_get_spacing_default().
+</para>
+<para>
+The arrangement and layout of the buttons can be changed using
+gtk_vbutton_box_set_layout_default() and queried with
+gtk_vbutton_box_get_layout_default().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkBox</term>
+<listitem><para>Used to pack widgets into button boxes.</para></listitem>
+</varlistentry><varlistentry>
+<term>#GtkButtonBox</term>
+<listitem><para>Provides functions for controlling button boxes.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>#GtkHButtonBox</term>
+<listitem><para>Pack buttons horizontally.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkVButtonBox ##### -->
</para>
+@button_box: the #GtkButtonBox that this class is derived from.
<!-- ##### FUNCTION gtk_vbutton_box_new ##### -->
<para>
-
+Creates a new vertical button box.
</para>
-@Returns:
+@Returns: a new button box #GtkWidget.
<!-- ##### FUNCTION gtk_vbutton_box_get_spacing_default ##### -->
<para>
-
+Retrieves the current default spacing for vertical button boxes. This is the number of pixels
+to be placed between the buttons when they are arranged.
</para>
-@Returns:
+@Returns: the default number of pixels between buttons.
<!-- ##### FUNCTION gtk_vbutton_box_set_spacing_default ##### -->
<para>
-
+Changes the default spacing that is placed between widgets in an
+vertical button box.
</para>
-@spacing:
+@spacing: an integer value.
<!-- ##### FUNCTION gtk_vbutton_box_get_layout_default ##### -->
<para>
-
+Retrieves the current layout used to arrange buttons in button box widgets.
</para>
-@Returns:
+@Returns: the current #GtkButtonBoxStyle.
<!-- ##### FUNCTION gtk_vbutton_box_set_layout_default ##### -->
<para>
-
+Sets a new layout mode that will be used by all button boxes.
</para>
-@layout:
-
-
+@layout: a new #GtkButtonBoxStyle.
vertical container box
<!-- ##### SECTION Long_Description ##### -->
-<para>\r
-GtkVBox is a container that organizes child widgets into a single column.\r
-</para>\r
-\r
-<para>\r
-Use the #GtkBox packing interface to determine the arrangement,\r
-spacing, height, and alignment of GtkVBox children.\r
-</para>\r
-\r
-<para>\r
-All children are allocated the same width.\r
+<para>
+GtkVBox is a container that organizes child widgets into a single column.
+</para>
+
+<para>
+Use the #GtkBox packing interface to determine the arrangement,
+spacing, height, and alignment of GtkVBox children.
+</para>
+
+<para>
+All children are allocated the same width.
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>\r
-<variablelist>\r
-\r
-<varlistentry>\r
-<term>#GtkHBox</term>\r
-<listitem><para>a sister class that organizes widgets into a row.</para></listitem>\r
-</varlistentry>\r
-\r
-</variablelist>\r
+<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkHBox</term>
+<listitem><para>a sister class that organizes widgets into a row.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GtkVBox ##### -->
<!-- ##### FUNCTION gtk_vbox_new ##### -->
-<para>\r
-Creates a new GtkVBox.\r
+<para>
+Creates a new GtkVBox.
</para>
@homogeneous: %TRUE if all children are to be given equal space allotments.
projects / ~andy / gtk / commitdiff