+1999-09-22 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/tmpl/*.sgml: ran make templates, to fix problems with structs.
+
+ * gtk/gtk-sections.txt: rearranged GtkCombo section.
+
+ * gtk/tmpl/gtkvseparator.sgml:
+ * gtk/tmpl/gtkhseparator.sgml:
+ * gtk/tmpl/gtkgc.sgml:
+ * gtk/tmpl/gtkfeatures.sgml:
+ * gtk/tmpl/gtktipsquery.sgml:
+ * gtk/tmpl/gtkitem.sgml:
+ * gtk/tmpl/gtkinvisible.sgml:
+ * gtk/tmpl/gtkgamma.sgml:
+ * gtk/tmpl/gtkdata.sgml:
+ * gtk/tmpl/gtkcurve.sgml:
+ * gtk/tmpl/gtkcombo.sgml:
+ * gtk/tmpl/gtkaccellabel.sgml: documented.
+
+1999-09-20 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/gtk-docs.sgml: added role="no-toc" to the GTK+ Widgets & Objects
+ chapter since we've created our own special contents page.
+
+1999-09-19 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/tmpl/gtkmarshal.sgml:
+ * gtk/tmpl/gtksignal.sgml: new sections from
+ David Benson <daveb@idealab.com>.
+
+ * gtk/gtk-sections.txt: rearranged signal sections, and made most
+ marshallers private. Moved GtkSignalRunType to signals section.
+
+ * gtk/tmpl/gtkradiobutton.sgml: new section from Lee Mallabone.
+
+1999-09-17 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/gtk-docs.sgml: removed menu factory and debugging sections.
+
+ * gtk/gtk-sections.txt: made menu factory stuff private since it is
+ deprecated. Also made debugging stuff private since it is only useful
+ within GTK+.
+
+1999-09-14 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gtk/tmpl/gtkfilesel.sgml: fixed mismatched parentheses.
+
+1999-09-02 Damon Chaplin <damon@karuna.freeserve.co.uk>
+
+ * gdk/tmpl/event_structs.sgml:
+ * gdk/tmpl/drawing.sgml: minor fixes.
+
1999-09-20 David C. Mason <dcm@redhat.com>
* gtk/tmpl/gtkimage.sgml: first pass at gtkimage... not complete
@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, similar to @angle1.
+@angle2: the end angle of the arc, in the same units as @angle1.
<!-- ##### FUNCTION gdk_draw_polygon ##### -->
@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
@font: a #GdkFont.
-q@gc: a #GdkGC.
+@gc: a #GdkGC.
@x: the x coordinate of the left edge of the text.
@y: the y coordinate of the baseline of the text.
@string: the string of characters to draw.
<para>
Used for button press and button release events. The
<structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
-%GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE.
+%GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
</para>
<para>
Double and treble-clicks result in a sequence of events being received.
@type: the type of the event.
@window: the window which received the event.
@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@time: the time of the event in milliseconds. This wraps around every 50 days.
+@time: the time of the event in milliseconds. This wraps around roughly every
+50 days.
@x: the x coordinate of the mouse relative to the window.
@y: the y coordinate of the mouse relative to the window.
@pressure: the pressure of the button press, intended for input devices such
<!entity gtk-Keyboard-Accelerators SYSTEM "sgml/gtkaccelgroup.sgml">
<!entity gtk-Selections SYSTEM "sgml/gtkselection.sgml">
<!entity gtk-Drag-and-Drop SYSTEM "sgml/gtkdnd.sgml">
-<!entity gtk-Menu-Factory SYSTEM "sgml/gtkmenufactory.sgml">
<!entity gtk-Signals SYSTEM "sgml/gtksignal.sgml">
<!entity gtk-Signal-Marshallers SYSTEM "sgml/gtkmarshal.sgml">
<!entity gtk-Object-Properties SYSTEM "sgml/gtkarg.sgml">
<!entity gtk-Types SYSTEM "sgml/gtktypeutils.sgml">
<!entity gtk-Bindings SYSTEM "sgml/gtkbindings.sgml">
<!entity gtk-Standard-Enumerations SYSTEM "sgml/gtkenums.sgml">
-<!entity gtk-Debugging SYSTEM "sgml/gtkdebug.sgml">
<!entity gtk-Private-Information SYSTEM "sgml/gtkprivate.sgml">
<!entity index-Object-Tree SYSTEM "sgml/tree_index.sgml">
</varlistentry>
</variablelist>
</para>
-
>k-General;
>k-Feature-Test-Macros;
>k-Graphics-Contexts;
>k-Keyboard-Accelerators;
>k-Selections;
>k-Drag-and-Drop;
- >k-Menu-Factory;
>k-Signals;
>k-Signal-Marshallers;
>k-Object-Properties;
>k-Types;
>k-Bindings;
>k-Standard-Enumerations;
- >k-Debugging;
>k-Private-Information;
</chapter>
- <chapter id="gtkobjects">
+ <chapter id="gtkobjects" role="no-toc">
<title>GTK+ Widgets and Objects</title>
&index-Objects-Grouped;
GtkCombo
<TITLE>GtkCombo</TITLE>
gtk_combo_new
+gtk_combo_set_popdown_strings
gtk_combo_set_value_in_list
gtk_combo_set_use_arrows
gtk_combo_set_use_arrows_always
gtk_combo_set_case_sensitive
gtk_combo_set_item_string
-gtk_combo_set_popdown_strings
gtk_combo_disable_activate
<SUBSECTION Standard>
GTK_COMBO
</SECTION>
-<SECTION>
-<FILE>gtkmenufactory</FILE>
-<TITLE>Menu Factory</TITLE>
-GtkMenuCallback
-GtkMenuEntry
-GtkMenuPath
-GtkMenuFactory
-gtk_menu_factory_new
-gtk_menu_factory_destroy
-gtk_menu_factory_add_entries
-gtk_menu_factory_add_subfactory
-gtk_menu_factory_remove_paths
-gtk_menu_factory_remove_entries
-gtk_menu_factory_remove_subfactory
-gtk_menu_factory_find
-</SECTION>
-
<SECTION>
<FILE>gtksignal</FILE>
<TITLE>Signals</TITLE>
GtkSignalDestroy
GtkEmissionHook
GtkSignalQuery
+GtkSignalRunType
gtk_signal_init
gtk_signal_new
gtk_signal_newv
gtk_signal_connect_object
gtk_signal_connect_object_after
gtk_signal_connect_full
-gtk_signal_connect_object_while_alive
gtk_signal_connect_while_alive
+gtk_signal_connect_object_while_alive
gtk_signal_disconnect
gtk_signal_disconnect_by_func
gtk_signal_disconnect_by_data
<FILE>gtkmarshal</FILE>
<TITLE>Signal Marshallers</TITLE>
gtk_signal_default_marshaller
+
+<SUBSECTION Private>
gtk_marshal_BOOL__POINTER_INT_INT_UINT
gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER
gtk_marshal_ENUM__ENUM
GtkDirectionType
GtkJustification
GtkMatchType
-GtkMenuFactoryType
GtkMetricType
GtkOrientation
GtkPackType
GtkPreviewType
GtkReliefStyle
GtkResizeMode
-GtkSignalRunType
GtkScrollType
GtkSelectionMode
GtkShadowType
GtkSortType
</SECTION>
-<SECTION>
-<FILE>gtkdebug</FILE>
-<TITLE>Debugging</TITLE>
-GtkDebugFlag
-gtk_debug_flags
-GTK_NOTE
-</SECTION>
-
<SECTION>
<FILE>gtkprivate</FILE>
<TITLE>Private Information</TITLE>
GTK_WIDGET_IS_OFFSCREEN
GTK_PRIVATE_SET_FLAG
GTK_PRIVATE_UNSET_FLAG
+
+<SUBSECTION Private>
+GtkMenuCallback
+GtkMenuEntry
+GtkMenuPath
+GtkMenuFactory
+GtkMenuFactoryType
+gtk_menu_factory_new
+gtk_menu_factory_destroy
+gtk_menu_factory_add_entries
+gtk_menu_factory_add_subfactory
+gtk_menu_factory_remove_paths
+gtk_menu_factory_remove_entries
+gtk_menu_factory_remove_subfactory
+gtk_menu_factory_find
+
+GtkDebugFlag
+gtk_debug_flags
+GTK_NOTE
</SECTION>
<link linkend="GtkViewport">GtkViewport</link>
<link linkend="GtkEventBox">GtkEventBox</link>
<link linkend="GtkAlignment">GtkAlignment</link>
- <link linkend="GtkInvisible">GtkInvisible</link>
<link linkend="GtkHButtonBox">GtkHButtonBox</link>
<link linkend="GtkVButtonBox">GtkVButtonBox</link>
<link linkend="GtkHPaned">GtkHPaned</link>
<emphasis>Misc. Objects</emphasis>
<link linkend="GtkAdjustment">GtkAdjustment</link>
<link linkend="GtkItemFactory">GtkItemFactory</link>
+ <link linkend="GtkInvisible">GtkInvisible</link>
</literallayout></entry>
</row>
</tbody></tgroup></informaltable>
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Title ##### -->
+Menu Factory
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### STRUCT GtkMenuFactory ##### -->
+<para>
+
+</para>
+
+@path:
+@type:
+@accel_group:
+@widget:
+@subfactories:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_menu_factory_find ##### -->
+<para>
+
+</para>
+
+@factory:
+@path:
+@Returns:
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM GtkMenuFactoryType ##### -->
+<para>
+
+</para>
+
+@GTK_MENU_FACTORY_MENU:
+@GTK_MENU_FACTORY_MENU_BAR:
+@GTK_MENU_FACTORY_OPTION_MENU:
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_add_entries ##### -->
+<para>
+
+</para>
+
+@factory:
+@entries:
+@nentries:
+
+<!-- ##### STRUCT GtkMenuPath ##### -->
+<para>
+
+</para>
+
+@path:
+@widget:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
<!-- ##### ARG GtkPreview:expand ##### -->
<para>
Determines the way that the the preview widget behaves
</para>
+<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_paths ##### -->
+<para>
+
+</para>
+
+@factory:
+@paths:
+@npaths:
+
+<!-- ##### FUNCTION gtk_menu_factory_destroy ##### -->
+<para>
+
+</para>
+
+@factory:
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO GTK_NOTE ##### -->
+<para>
+
+</para>
+
+@type:
+@action:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM GtkDebugFlag ##### -->
+<para>
+
+</para>
+
+@GTK_DEBUG_OBJECTS:
+@GTK_DEBUG_MISC:
+@GTK_DEBUG_SIGNALS:
+@GTK_DEBUG_DND:
+@GTK_DEBUG_PLUGSOCKET:
+
<!-- ##### ARG GtkHandleBox:snap_edge ##### -->
<para>
Determines the snap edge of a handlebox. The snap edge is
</para>
+<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_menu_factory_new ##### -->
+<para>
+
+</para>
+
+@type:
+@Returns:
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_entries ##### -->
+<para>
+
+</para>
+
+@factory:
+@entries:
+@nentries:
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### USER_FUNCTION GtkMenuCallback ##### -->
+<para>
+
+</para>
+
+@widget:
+@user_data:
+
+<!-- ##### VARIABLE gtk_debug_flags ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_subfactory ##### -->
+<para>
+
+</para>
+
+@factory:
+@subfactory:
+@path:
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Title ##### -->
+Debugging
+
+
+<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
+<para>
+
+</para>
+
+@object:
+@func:
+@func_data:
+@args:
+
+<!-- ##### FUNCTION gtk_menu_factory_add_subfactory ##### -->
+<para>
+
+</para>
+
+@factory:
+@subfactory:
+@path:
+
+<!-- ##### STRUCT GtkMenuEntry ##### -->
+<para>
+
+</para>
+
+@path:
+@accelerator:
+@callback:
+@callback_data:
+@widget:
+
+<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
GtkAccelLabel
<!-- ##### SECTION Short_Description ##### -->
-
+a label which displays an accelerator key on the right of the text.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an
+accelerator key on the right of the label text, e.g. 'Ctl+S'.
+It is commonly used in menus to show the keyboard short-cuts for commands.
+</para>
+<para>
+The accelerator key to display is not set explicitly.
+Instead, the #GtkAccelLabel displays the accelerators which have been added to
+a particular widget. This widget is set by calling
+gtk_accel_label_set_accel_widget().
+</para>
+<para>
+For example, a #GtkMenuItem widget may have an accelerator added to emit the
+"activate" signal when the 'Ctl+S' key combination is pressed.
+A #GtkAccelLabel is created and added to the #GtkMenuItem, and
+gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the
+second argument. The #GtkAccelLabel will now display 'Ctl+S' after its label.
</para>
+<para>
+Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or
+one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem)
+automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls
+gtk_accel_label_set_accel_widget() to set it up for you.
+</para>
+<para>
+A #GtkAccelLabel will only display accelerators which have GTK_ACCEL_VISIBLE
+set (see #GtkAccelFlags).
+A #GtkAccelLabel can display multiple accelerators and even signal names,
+though it is almost always used to display just one accelerator key.
+</para>
+
+<example>
+<title>Creating a simple menu item with an accelerator key.</title>
+<programlisting>
+ GtkWidget *save_item;
+ GtkAccelGroup *accel_group;
+
+ /* Create a #GtkAccelGroup and add it to the window. */
+ accel_group = gtk_accel_group_new ();
+ gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
+
+ /* Create the menu item using the convenience function. */
+ save_item = gtk_menu_item_new_with_label ("Save");
+ gtk_widget_show (save_item);
+ gtk_container_add (GTK_CONTAINER (menu), save_item);
+
+ /* Now add the accelerator to the #GtkMenuItem. Note that since we called
+ gtk_menu_item_new_with_label() to create the #GtkMenuItem the
+ #GtkAccelLabel is automatically set up to display the #GtkMenuItem
+ accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
+ gtk_widget_add_accelerator (save_item, "activate", accel_group,
+ GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
+</programlisting>
+</example>
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+<varlistentry>
+<term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
+</term>
+<listitem><para>installing and using keyboard short-cuts.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GtkItemFactory</term>
+<listitem><para>an easier way to create menus.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GtkAccelLabel ##### -->
<para>
-
+The #GtkAccelLabel-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@label:
-@queue_id:
-@accel_padding:
-@accel_widget:
-@accel_string:
-@accel_string_width:
<!-- ##### FUNCTION gtk_accel_label_new ##### -->
<para>
-
+Creates a new #GtkAccelLabel.
</para>
-@string:
-@Returns:
+@string: the label string.
+@Returns: a new #GtkAccelLabel.
<!-- ##### FUNCTION gtk_accel_label_set_accel_widget ##### -->
<para>
-
+Sets the widget whose accelerators are to be shown.
</para>
-@accel_label:
-@accel_widget:
+@accel_label: a #GtkAccelLabel.
+@accel_widget: the widget whose accelerators are to be displayed.
<!-- ##### FUNCTION gtk_accel_label_get_accel_width ##### -->
<para>
-
+Returns the width needed to display the accelerator key(s).
+This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't
+be needed by applications.
</para>
-@accel_label:
+@accel_label: a #GtkAccelLabel.
@Returns:
<!-- ##### FUNCTION gtk_accel_label_refetch ##### -->
<para>
-
+Recreates the string representing the accelerator keys.
+This should not be needed since the string is automatically updated whenever
+accelerators are added or removed from the associated widget.
</para>
-@accel_label:
-@Returns:
+@accel_label: a #GtkAccelLabel.
+@Returns: always returns FALSE.
<!-- ##### ARG GtkAccelLabel:accel_widget ##### -->
<para>
-
+The widget whose accelerators are to be shown by the #GtkAccelLabel.
</para>
</para>
-@data:
-@lower:
-@upper:
-@value:
-@step_increment:
-@page_increment:
-@page_size:
<!-- ##### FUNCTION gtk_adjustment_new ##### -->
<para>
be accessed using the functions below.
</para>
-@bin:
-@xalign:
-@yalign:
-@xscale:
-@yscale:
<!-- ##### FUNCTION gtk_alignment_new ##### -->
<para>
</tbody></tgroup></informaltable>\r
</para>
-@misc:
-@arrow_type:
-@shadow_type:
<!-- ##### FUNCTION gtk_arrow_new ##### -->
<para>\r
</para>
-@frame:
-@xalign:
-@yalign:
-@ratio:
-@obey_child:
-@center_allocation:
<!-- ##### FUNCTION gtk_aspect_frame_new ##### -->
<para>
-<!-- ##### SECTION Title ##### -->\r
-GtkButtonBox\r
-\r
-<!-- ##### SECTION Short_Description ##### -->\r
-Base class for #GtkHButtonBox and #GtkVButtonBox\r
-\r
-<!-- ##### SECTION Long_Description ##### -->\r
+<!-- ##### SECTION Title ##### -->
+GtkButtonBox
+
+<!-- ##### SECTION Short_Description ##### -->
+Base class for #GtkHButtonBox and #GtkVButtonBox
+
+<!-- ##### SECTION Long_Description ##### -->
<para>\r
The primary purpose of this class is to keep track of the various properties\r
of #GtkHButtonBox and #GtkVButtonBox widgets.\r
\r
<para>\r
\r
-</para>\r
-\r
-<!-- ##### SECTION See_Also ##### -->\r
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
<para>\r
<variablelist>\r
<varlistentry>\r
<listitem><para>Horizontal sub-class of #GtkButtonBox.</para></listitem>\r
</varlistentry>\r
</variablelist>\r
-</para>\r
-\r
-<!-- ##### STRUCT GtkButtonBox ##### -->\r
+</para>
+
+<!-- ##### STRUCT GtkButtonBox ##### -->
<para>\r
This is a read-only struct; no members should be modified directly.\r
-</para>\r
-\r
-\r
-<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->\r
+</para>
+
+
+<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->
<para>\r
Used internally only.\r
-</para>\r
-\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->\r
+</para>
+
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
<para>\r
Retrieves the default minimum width and height for all button boxes, and\r
places the values in @min_width and @min_height, respectively.\r
-</para>\r
-\r
-@min_width: the default minimum width of a child widget.\r
-@min_height: the default minimum height of a child widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->\r
+</para>
+
+@min_width: the default minimum width of a child widget.
+@min_height: the default minimum height of a child widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
<para>\r
The internal padding of a button is the amount of space between the outside\r
of the button and the widget it contains. This function gets the default\r
amount of horizontal and vertical padding, placing the results in @ipad_x\r
and @ipad_y, respectively.\r
-</para>\r
-\r
-@ipad_x: the default horizontal internal button padding.\r
-@ipad_y: the default vertical internal button padding.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->\r
+</para>
+
+@ipad_x: the default horizontal internal button padding.
+@ipad_y: the default vertical internal button padding.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
<para>\r
Sets the default size of child buttons.\r
-</para>\r
-\r
-@min_width: minimum default width for child buttons.\r
-@min_height: minimum default height for child buttons.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->\r
+</para>
+
+@min_width: minimum default width for child buttons.
+@min_height: minimum default height for child buttons.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
<para>\r
Sets the default number of pixels that pad each button in every button box.\r
-</para>\r
-\r
-@ipad_x: new default horizontal padding.\r
-@ipad_y: new default vertical padding.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->\r
+</para>
+
+@ipad_x: new default horizontal padding.
+@ipad_y: new default vertical padding.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->
<para>\r
Retrieves how much space a button box is placing between each child button.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@Returns: the current spacing applied to the buttons in @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@Returns: the current spacing applied to the buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->
<para>\r
Retrieves the method being used to arrange the buttons in a button box.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@Returns: the method used to layout buttons in @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@Returns: the method used to layout buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->
<para>\r
Retrieves the current width and height of all child widgets in a button box.\r
@min_width and @min_height are filled with those values, respectively.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@min_width: the width of the buttons contained by @widget.\r
-@min_height: the height of the buttons contained by @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@min_width: the width of the buttons contained by @widget.
+@min_height: the height of the buttons contained by @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->
<para>\r
Gets the default number of pixels that pad the buttons in a given button box.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@ipad_x: the horizontal padding used by buttons in @widget.\r
-@ipad_y: the vertical padding used by buttons in @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@ipad_x: the horizontal padding used by buttons in @widget.
+@ipad_y: the vertical padding used by buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->
<para>\r
Sets the amount of spacing between buttons in a given button box.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@spacing: the number of pixels of spacing.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@spacing: the number of pixels of spacing.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->
<para>\r
Changes the way buttons are arranged in their container.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@layout_style: the new layout style.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@layout_style: the new layout style.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->
<para>\r
Sets a new default size for the children of a given button box.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@min_width: a default width for buttons in @widget.\r
-@min_height: a default height for buttons in @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@min_width: a default width for buttons in @widget.
+@min_height: a default height for buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->
<para>\r
Changes the amount of internal padding used by all buttons in a given button\r
box.\r
-</para>\r
-\r
-@widget: a #GtkButtonBox.\r
-@ipad_x: the horizontal padding that should be used by each button in @widget.\r
-@ipad_y: the vertical padding that should be used by each button in @widget.\r
-\r
-\r
-<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->\r
+</para>
+
+@widget: a #GtkButtonBox.
+@ipad_x: the horizontal padding that should be used by each button in @widget.
+@ipad_y: the vertical padding that should be used by each button in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
<para>\r
This is an internally used function and should never be called from an\r
application.\r
-</para>\r
+</para>
+
+@widget:
+@nvis_children:
+@width:
+@height:
+
+
</para>
-@container:
-@child:
</tbody></tgroup></informaltable>
</para>
-@container:
-@children:
-@spacing:
-@homogeneous:
<!-- ##### STRUCT GtkBoxChild ##### -->
<para>\r
This should not be accessed directly. Use the accessor functions below.\r
</para>
-@bin:
-@child:
-@in_button:
-@button_down:
-@relief:
<!-- ##### FUNCTION gtk_button_new ##### -->
<para>\r
struct should only be modified using the functions provided below.
</para>
-@widget:
-@header_style:
-@label_style:
-@month:
-@year:
-@selected_day:
-@day_month:
-@day:
-@num_marked_dates:
-@marked_date:
-@display_flags:
-@marked_date_color:
-@gc:
-@xor_gc:
-@focus_row:
-@focus_col:
-@highlight_row:
-@highlight_col:
-@private_data:
-@grow_space:
<!-- ##### ENUM GtkCalendarDisplayOptions ##### -->
<para>
<structfield>toggle_button</structfield> is a #GtkToggleButton representing the actual toggle button that composes the check button.
</para>
-@toggle_button:
<!-- ##### FUNCTION gtk_check_button_new ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@menu_item:
-@active:
-@always_show_toggle:
<!-- ##### FUNCTION gtk_check_menu_item_new ##### -->
<para>
</para>
-@container:
-@flags:
-@row_mem_chunk:
-@cell_mem_chunk:
-@freeze_count:
-@internal_allocation:
-@rows:
-@row_center_offset:
-@row_height:
-@row_list:
-@row_list_end:
-@columns:
-@column_title_area:
-@title_window:
-@column:
-@clist_window:
-@clist_window_width:
-@clist_window_height:
-@hoffset:
-@voffset:
-@shadow_type:
-@selection_mode:
-@selection:
-@selection_end:
-@undo_selection:
-@undo_unselection:
-@undo_anchor:
-@button_actions:
-@drag_button:
-@click_cell:
-@hadjustment:
-@vadjustment:
-@xor_gc:
-@fg_gc:
-@bg_gc:
-@cursor_drag:
-@x_drag:
-@focus_row:
-@anchor:
-@anchor_state:
-@drag_pos:
-@htimer:
-@vtimer:
-@sort_type:
-@compare:
-@sort_column:
<!-- ##### ENUM GtkCellType ##### -->
<para>
</para>
-@vbox:
-@wheel_area:
-@value_area:
-@sample_area:
-@sample_area_eb:
-@scales:
-@entries:
-@opacity_label:
-@wheel_gc:
-@value_gc:
-@sample_gc:
-@policy:
-@use_opacity:
-@timer_active:
-@timer_tag:
-@values:
-@old_values:
-@wheel_buf:
-@value_buf:
-@sample_buf:
<!-- ##### FUNCTION gtk_color_selection_new ##### -->
<para>
</para>
-@window:
-@colorsel:
-@main_vbox:
-@ok_button:
-@reset_button:
-@cancel_button:
-@help_button:
<!-- ##### FUNCTION gtk_color_selection_dialog_new ##### -->
<para>
GtkCombo
<!-- ##### SECTION Short_Description ##### -->
-
+a text entry field with a dropdown list.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkCombo widget consists of a single-line text entry field and a drop-down
+list. The drop-down list is displayed when the user clicks on a small arrow
+button to the right of the entry field.
+</para>
+<para>
+The drop-down list is a #GtkList widget and can be accessed using the
+<structfield>list</structfield> member of the #GtkCombo-struct.
+List elements can contain arbitrary widgets, but if an element is not a
+plain label, then you must use the gtk_list_set_item_string() function.
+This sets the string which will be placed in the text entry field when the
+item is selected.
+</para>
+<para>
+By default, the user can step through the items in the list using the
+arrow (cursor) keys, though this behaviour can be turned off with
+gtk_combo_set_use_arrows().
</para>
+<para>
+Normally the arrow keys are only active when the contents of the text entry
+field matches one of the items in the list. If the contents of the entry field
+do not match any of the list items, then pressing the arrow keys does nothing.
+However, by calling gtk_combo_set_use_arrows_always() you can specify that the
+arrow keys are always active. If the contents of the entry field does not match
+any of the items in the list, then pressing the up or down arrow key will set
+the entry field to the last or first item in the list, respectively.
+</para>
+
+<example id="gtkcombo-simple-example">
+<title>Creating a #GtkCombo widget with simple text items.</title>
+<programlisting>
+ GtkWidget *combo;
+ GList *items = NULL;
+
+ items = g_list_append (items, "First Item");
+ items = g_list_append (items, "Second Item");
+ items = g_list_append (items, "Third Item");
+ items = g_list_append (items, "Fourth Item");
+ items = g_list_append (items, "Fifth Item");
+
+ combo = gtk_combo_new ();
+ gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
+</programlisting>
+</example>
+
+<example>
+<title>Creating a #GtkCombo widget with a complex item.</title>
+<programlisting>
+ GtkWidget *combo, *item, *hbox, *arrow, *label;
+
+ combo = gtk_combo_new ();
+
+ item = gtk_list_item_new ();
+ gtk_widget_show (item);
+
+ /* You can put almost anything into the GtkListItem widget. Here we will use
+ a horizontal box with an arrow and a label in it. */
+ hbox = gtk_hbox_new (FALSE, 3);
+ gtk_container_add (GTK_CONTAINER (item), hbox);
+ gtk_widget_show (hbox);
+
+ arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
+ gtk_widget_show (arrow);
+ gtk_box_pack_start (GTK_BOX (hbox), pixmap, FALSE, FALSE, 0);
+
+ label = gtk_label_new ("First Item");
+ gtk_widget_show (label);
+ gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
+
+ /* You must set the string to display in the entry field when the item is
+ selected. */
+ gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
+
+ /* Now we simply add the item to the combo's list. */
+ gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
+</programlisting>
+</example>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GtkCombo ##### -->
<para>
+The #GtkFixedChild-struct struct contains the following fields.
+(These fields should be considered read-only. They should never be set by
+an application.)
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#GtkWidget *entry;</entry>
+<entry>the text entry field.</entry>
+</row>
+<row>
+<entry>#GtkWidget *list;</entry>
+<entry>the list shown in the drop-down window.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
-@hbox:
-@entry:
-@button:
-@popup:
-@popwin:
-@list:
-@entry_change_id:
-@list_change_id:
-@value_in_list:
-@ok_if_empty:
-@case_sensitive:
-@use_arrows:
-@use_arrows_always:
-@current_button:
-@activate_id:
<!-- ##### FUNCTION gtk_combo_new ##### -->
<para>
+Creates a new #GtkCombo.
+</para>
+@Returns: a new #GtkCombo.
+
+
+<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
+<para>
+Convenience function to set all of the items in the popup list.
+(See the <link linkend="gtkcombo-simple-example">example</link> above.)
</para>
-@Returns:
+@combo: a #GtkCombo.
+@strings: a list of strings.
<!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
<para>
-
+Specifies whether the value entered in the text entry field must match one of
+the values in the list. If this is set then the user will not be able to
+perform any other action until a valid value has been entered.
+</para>
+<para>
+If an empty field is acceptable, the @ok_if_empty parameter should be TRUE.
</para>
-@combo:
-@val:
-@ok_if_empty:
+@combo: a #GtkCombo.
+@val: TRUE if the value entered must match one of the values in the list.
+@ok_if_empty: TRUE if an empty value is considered valid.
<!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
<para>
-
+Specifies if the arrow (cursor) keys can be used to step through the items in
+the list. This is on by default.
</para>
-@combo:
-@val:
+@combo: a #GtkCombo.
+@val: TRUE if the arrow keys can be used to step through the items in the list.
<!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
<para>
-
+Specifies if the arrow keys will still work even if the current contents of the
+#GtkEntry field do not match any of the list items.
</para>
-@combo:
+@combo: a #GtkCombo.
@val:
<!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
<para>
-
+Specifies whether the text entered into the #GtkEntry field and the text in
+the list items is case sensitive.
</para>
-
-@combo:
-@val:
-
-
-<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
<para>
-
+This may be useful, for example, when you have called
+gtk_combo_set_value_in_list() to limit the values entered, but you are not
+worried about differences in case.
</para>
-@combo:
-@item:
-@item_value:
+@combo: a #GtkCombo.
+@val:
-<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
+<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
<para>
-
+Sets the string to place in the #GtkEntry field when a particular list item is
+selected. This is needed if the list item is not a simple label.
</para>
-@combo:
-@strings:
+@combo: a #GtkCombo.
+@item: a #GtkItem which
+@item_value: the string to place in the #GtkEntry when @item is selected.
<!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
<para>
-
+Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
+emits the "activate" signal, i.e. when the Return key is pressed.
+This may be useful if, for example. you want the Return key to close a dialog
+instead.
</para>
-@combo:
+@combo: a #GtkCombo.
</para>
-@widget:
-@focus_child:
-@border_width:
-@need_resize:
-@resize_mode:
-@resize_widgets:
<!-- ##### MACRO GTK_IS_RESIZE_CONTAINER ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@clist:
-@lines_gc:
-@tree_indent:
-@tree_spacing:
-@tree_column:
-@line_style:
-@expander_style:
-@show_stub:
-@drag_compare:
<!-- ##### MACRO GTK_CTREE_ROW ##### -->
<para>
GtkCurve
<!-- ##### SECTION Short_Description ##### -->
-
+allows direct editing of a curve.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkCurve widget allows the user to edit a curve covering a range of
+values. It is typically used to fine-tune color balances in graphics
+applications like the Gimp.
+</para>
+<para>
+The #GtkCurve widget has 3 modes of operation - spline, linear and free.
+In spline mode the user places points on the curve which are automatically
+connected together into a smooth curve. In linear mode the user places points
+on the curve which are connected by straight lines. In free mode the user can
+draw the points of the curve freely, and they are not connected at all.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+<varlistentry>
+<term>#GtkGammaCurve</term>
+<listitem><para>a subclass for editing gamma curves.
+</listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkCurve ##### -->
<para>
-
+The #GtkCurve-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@graph:
-@cursor_type:
-@min_x:
-@max_x:
-@min_y:
-@max_y:
-@pixmap:
-@curve_type:
-@height:
-@grab_point:
-@last:
-@num_points:
-@point:
-@num_ctlpoints:
<!-- ##### FUNCTION gtk_curve_new ##### -->
<para>
-
+Creates a new #GtkCurve.
</para>
-@Returns:
+@Returns: a new #GtkCurve.
<!-- ##### FUNCTION gtk_curve_reset ##### -->
<para>
-
+Resets the curve to a straight line from the minimum x & y values to the
+maximum x & y values (i.e. from the bottom-left to the top-right corners).
+The curve type is not changed.
</para>
-@curve:
+@curve: a #GtkCurve.
<!-- ##### FUNCTION gtk_curve_set_gamma ##### -->
<para>
-
+Recomputes the entire curve using the given gamma value.
+A gamma value of 1 results in a straight line. Values greater than 1 result
+in a curve above the straight line. Values less than 1 result in a curve
+below the straight line. The curve type is changed to %GTK_CURVE_TYPE_FREE.
+FIXME: Needs a more precise definition of gamma.
</para>
-@curve:
-@gamma:
+@curve: a #GtkCurve.
+@gamma: the gamma value.
<!-- ##### FUNCTION gtk_curve_set_range ##### -->
<para>
-
+Sets the minimum and maximum x & y values of the curve.
+The curve is also reset with a call to gtk_curve_reset().
</para>
-@curve:
-@min_x:
-@max_x:
-@min_y:
-@max_y:
+@curve: a #GtkCurve.
+@min_x: the minimum x value.
+@max_x: the maximum x value.
+@min_y: the minimum y value.
+@max_y: the maximum y value.
<!-- ##### FUNCTION gtk_curve_get_vector ##### -->
<para>
-
+Returns a vector of points representing the curve.
</para>
-@curve:
-@veclen:
-@vector:
+@curve: a #GtkCurve.
+@veclen: the number of points to calculate.
+@vector: returns the points.
<!-- ##### FUNCTION gtk_curve_set_vector ##### -->
<para>
-
+Sets the vector of points on the curve.
+The curve type is set to %GTK_CURVE_TYPE_FREE.
</para>
-@curve:
-@veclen:
-@vector:
+@curve: a #GtkCurve.
+@veclen: the number of points.
+@vector: the points on the curve.
<!-- ##### FUNCTION gtk_curve_set_curve_type ##### -->
<para>
-
+Sets the type of the curve. The curve will remain unchanged except when
+changing from a free curve to a linear or spline curve, in which case the
+curve will be changed as little as possible.
</para>
-@curve:
-@type:
+@curve: a #GtkCurve.
+@type: the type of the curve.
<!-- ##### SIGNAL GtkCurve::curve-type-changed ##### -->
<para>
-
+Emitted when the curve type has been changed.
+The curve type can be changed explicitly with a call to
+gtk_curve_set_curve_type(). It is also changed as a side-effect of
+calling gtk_curve_reset() or gtk_curve_set_gamma().
</para>
@curve: the object which received the signal.
GtkData
<!-- ##### SECTION Short_Description ##### -->
-
+abstract base class for objects containing data.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkData object is a very simple object intended to be used as a base
+class for objects which contain data (i.e. the 'Model' in the object-oriented
+Model/View/Controller framework).
+</para>
+<para>
+Currently it is not very useful since all it provides is a "disconnect" signal.
+This signal could be emitted by a #GtkData subclass to notify any 'Views'
+that they should disconnect from the #GtkData (the 'Model'), possibly just
+before the #GtkData is destroyed.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkData ##### -->
<para>
-
+The #GtkData-struct struct contains no public fields.
</para>
-@object:
<!-- ##### SIGNAL GtkData::disconnect ##### -->
<para>
-
+Emitted to notify any views on the #GtkData object to disconnect from it,
+possibly because the #GtkData object is about to be destroyed.
</para>
@data: the object which received the signal.
<structfield>action_area</structfield> is a #GtkHBox packed below the dividing #GtkHSeparator in the dialog. It is treated exactly the same as any other #GtkHBox.
</para>
-@window:
-@vbox:
-@action_area:
<!-- ##### STRUCT GtkDialogButton ##### -->
<para>
should be accessed using the functions below.
</para>
-@widget:
-@draw_data:
<!-- ##### FUNCTION gtk_drawing_area_new ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@widget:
@current_pos:
@selection_start_pos:
@selection_end_pos:
@has_selection:
-@editable:
-@visible:
-@ic:
-@ic_attr:
-@clipboard_text:
<!-- ##### USER_FUNCTION GtkTextFunction ##### -->
<para>
The #GtkEntry-struct struct contains only private data.
</para>
-@editable:
-@text_area:
-@backing_pixmap:
-@cursor:
-@text:
-@text_size:
-@text_length:
-@text_max_length:
-@scroll_offset:
-@visible:
-@timer:
-@button:
-@char_offset:
-@text_mb:
-@text_mb_dirty:
-@use_wchar:
<!-- ##### FUNCTION gtk_entry_new ##### -->
<para>
@GTK_MATCH_EXACT:
@GTK_MATCH_LAST:
-<!-- ##### ENUM GtkMenuFactoryType ##### -->
-<para>
-
-</para>
-
-@GTK_MENU_FACTORY_MENU:
-@GTK_MENU_FACTORY_MENU_BAR:
-@GTK_MENU_FACTORY_OPTION_MENU:
-
<!-- ##### ENUM GtkMetricType ##### -->
<para>
@GTK_RESIZE_QUEUE:
@GTK_RESIZE_IMMEDIATE:
-<!-- ##### ENUM GtkSignalRunType ##### -->
-<para>
-
-</para>
-
-@GTK_RUN_FIRST:
-@GTK_RUN_LAST:
-@GTK_RUN_BOTH:
-@GTK_RUN_NO_RECURSE:
-@GTK_RUN_ACTION:
-@GTK_RUN_NO_HOOKS:
-
<!-- ##### ENUM GtkScrollType ##### -->
<para>
should be accessed using the functions below.
</para>
-@bin:
<!-- ##### FUNCTION gtk_event_box_new ##### -->
<para>
<!-- ##### SECTION Title ##### -->
-Feature Test Macros
+Version Information
<!-- ##### SECTION Short_Description ##### -->
-
+variables and functions to check the GTK+ version.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes the variables and functions available to test the
+version of the GTK+ library in use.
+FIXME: probably merge with other general stuff.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### VARIABLE gtk_major_version ##### -->
<para>
-
+The major version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 1.)
</para>
<!-- ##### VARIABLE gtk_minor_version ##### -->
<para>
-
+The minor version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 2.)
</para>
<!-- ##### VARIABLE gtk_micro_version ##### -->
<para>
-
+The micro version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 5.)
</para>
<!-- ##### FUNCTION gtk_check_version ##### -->
<para>
-
+Checks that the GTK+ library in use is compatable with the given version.
</para>
-@required_major:
-@required_minor:
-@required_micro:
-@Returns:
+@required_major: the required major version.
+@required_minor: the required major version.
+@required_micro: the required major version.
+@Returns: NULL if the GTK+ library is compatable with the given version, or
+a string describing the version mismatch.
file_selector = gtk_file_selection_new("Please select a file for editing.");
- gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button)),
+ gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
"clicked", GTK_SIGNAL_FUNC (store_filename), NULL);
/* Ensure that the dialog box is destroyed when the user clicks a button. */
- gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button)),
+ gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
"clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
(gpointer) file_selector);
- gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button)),
+ gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button),
"clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
(gpointer) file_selector);
</para>
-@window:
-@dir_list:
-@file_list:
-@selection_entry:
-@selection_text:
-@main_vbox:
-@ok_button:
-@cancel_button:
-@help_button:
-@history_pulldown:
-@history_menu:
-@history_list:
-@fileop_dialog:
-@fileop_entry:
-@fileop_file:
-@cmpl_state:
-@fileop_c_dir:
-@fileop_del_file:
-@fileop_ren_file:
-@button_area:
-@action_area:
<!-- ##### FUNCTION gtk_file_selection_new ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@container:
-@children:
<!-- ##### STRUCT GtkFixedChild ##### -->
<para>
only be accessed using the functions below.
</para>
-@notebook:
-@main_vbox:
-@font_label:
-@font_entry:
-@font_clist:
-@font_style_entry:
-@font_style_clist:
-@size_entry:
-@size_clist:
-@pixels_button:
-@points_button:
-@filter_button:
-@preview_entry:
-@message_label:
-@info_vbox:
-@info_clist:
-@requested_font_name:
-@actual_font_name:
-@filter_vbox:
-@type_bitmaps_button:
-@type_scalable_button:
-@type_scaled_bitmaps_button:
-@filter_clists:
-@font:
-@font_index:
-@style:
-@metric:
-@size:
-@selected_size:
-@property_values:
-@filters:
<!-- ##### FUNCTION gtk_font_selection_new ##### -->
<para>
only be accessed using the functions below.
</para>
-@window:
-@fontsel:
-@main_vbox:
-@action_area:
-@ok_button:
-@apply_button:
-@cancel_button:
-@dialog_width:
-@auto_resize:
<!-- ##### FUNCTION gtk_font_selection_dialog_new ##### -->
<para>
</para>
-@bin:
-@label:
-@shadow_type:
-@label_width:
-@label_height:
-@label_xalign:
-@label_yalign:
<!-- ##### FUNCTION gtk_frame_new ##### -->
<para>
GtkGammaCurve
<!-- ##### SECTION Short_Description ##### -->
-
+a subclass of #GtkCurve for editing gamma curves.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for
+editing gamma curves, which are used in graphics applications such as the
+Gimp.
+</para>
+<para>
+The #GammaCurve widget shows a curve which the user can edit with the mouse
+just like a #GtkCurve widget. On the right of the curve it also displays
+5 buttons, 3 of which change between the 3 curve modes (spline, linear and
+free), and the other 2 set the curve to a particular gamma value, or reset it
+to a straight line.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkGammaCurve ##### -->
<para>
-
+The #GtkGammaCurve-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@vbox:
-@table:
-@curve:
-@button:
-@gamma:
-@gamma_dialog:
-@gamma_text:
<!-- ##### FUNCTION gtk_gamma_curve_new ##### -->
<para>
-
+Creates a new #GtkGammaCurve.
</para>
-@Returns:
+@Returns: a new #GtkGammaCurve.
Graphics Contexts
<!-- ##### SECTION Short_Description ##### -->
-
+provides access to a shared pool of #GdkGC objects.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions provide access to a shared pool of #GdkGC objects.
+When a new #GdkGC is needed, gtk_gc_get() is called with the required depth,
+colormap and #GdkGCValues. If a #GdkGC with the required properties already
+exists then that is returned. If not, a new #GdkGC is created.
+When the #GdkGC is no longer needed, gtk_gc_release() is called.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION gtk_gc_get ##### -->
<para>
-
+Gets a #GdkGC with the given depth, colormap and #GdkGCValues.
+If a #GdkGC with the given properties already exists then it is returned,
+otherwise a new #GdkGC is created.
+The returned #GdkGC should be released with gtk_gc_release() when it is no
+longer needed.
</para>
-@depth:
-@colormap:
-@values:
-@values_mask:
-@Returns:
+@depth: the depth of the #GdkGC to create.
+@colormap: the #GdkColormap (FIXME: I don't know why this is needed).
+@values: a #GdkGCValues struct containing settings for the #GdkGC.
+@values_mask: a set of flags indicating which of the fields in @values has
+been set.
+@Returns: a #GdkGC.
<!-- ##### FUNCTION gtk_gc_release ##### -->
<para>
-
+Releases a #GdkGC allocated using gtk_gc_get().
</para>
-@gc:
+@gc: a #GdkGC.
</para>
-@bin:
-@bin_window:
-@float_window:
-@shadow_type:
-@handle_position:
-@float_window_mapped:
-@child_detached:
-@in_drag:
-@shrink_on_detach:
-@snap_edge:
-@deskoff_x:
-@deskoff_y:
-@attach_allocation:
-@float_allocation:
<!-- ##### FUNCTION gtk_handle_box_new ##### -->
<para>
should not be modified directly.
</para>
-@button_box:
<!-- ##### FUNCTION gtk_hbutton_box_new ##### -->
<para>
<!-- ##### STRUCT GtkHBox ##### -->
-@box:
<!-- ##### FUNCTION gtk_hbox_new ##### -->
<para>\r
<para>
</para>
-@paned:
<!-- ##### FUNCTION gtk_hpaned_new ##### -->
<para>
</para>
-
<!-- ##### STRUCT GtkHRuler ##### -->
<para>
The #GtkHRuler struct contains private data and should be accessed
with the functions below.
</para>
-@ruler:
<!-- ##### FUNCTION gtk_hruler_new ##### -->
<para>
should be accessed using the functions below.
</para>
-@scale:
<!-- ##### FUNCTION gtk_hscale_new ##### -->
<para>
</para>
-
<!-- ##### STRUCT GtkHScrollbar ##### -->
<para>
The #GtkHScrollbar struct contains private data and should be accessed
unsing the functions below.
</para>
-@scrollbar:
<!-- ##### FUNCTION gtk_hscrollbar_new ##### -->
<para>
GtkHSeparator
<!-- ##### SECTION Short_Description ##### -->
-
+a horizontal separator.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkHSeparator widget is a horizontal separator, used to group the
+widgets within a window. It displays a horizontal line with a shadow to
+make it appear sunken into the interface.
+</para>
+<note>
+<para>
+The #GtkHSeparator widget is not used as a separator within menus.
+To create a separator in a menu create an empty #GtkMenuItem widget using
+gtk_menu_item_new() and add it to the menu with gtk_menu_append().
</para>
+</note>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkVSeparator</term>
+<listitem><para>a vertical separator.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkHSeparator ##### -->
<para>
-
+The #GtkHSeparator-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@separator:
<!-- ##### FUNCTION gtk_hseparator_new ##### -->
<para>
-
+Creates a new #GtkHSeparator.
</para>
-@Returns:
+@Returns: a new #GtkHSeparator.
below.
</para>
-@misc:
-@image:
-@mask:
<!-- ##### FUNCTION gtk_image_new ##### -->
<para>
<para>
</para>
-@dialog:
-@axis_list:
-@axis_listbox:
-@mode_optionmenu:
-@close_button:
-@save_button:
-@axis_items:
-@current_device:
-@keys_list:
-@keys_listbox:
<!-- ##### FUNCTION gtk_input_dialog_new ##### -->
<para>
GtkInvisible
<!-- ##### SECTION Short_Description ##### -->
-
+internally-used widget which is not displayed.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkInvisible widget is used internally in GTK+, and is probably not useful
+for application developers.
+</para>
+<para>
+It is used for reliable pointer grabs and selection handling in the code
+for drag-and-drop.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkInvisible ##### -->
<para>
-
+The #GtkInvisible-struct struct contains no public fields.
</para>
-@bin:
<!-- ##### FUNCTION gtk_invisible_new ##### -->
<para>
-
+Creates a new #GtkInvisible.
</para>
-@Returns:
+@Returns: a new #GtkInvisible.
GtkItem
<!-- ##### SECTION Short_Description ##### -->
-
+abstract base class for #GtkMenuItem, #GtkListItem and #GtkTreeItem.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkItem widget is an abstract base class for #GtkMenuItem, #GtkListItem
+and #GtkTreeItem.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GtkItem ##### -->
<para>
-
+The #GtkItem-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@bin:
<!-- ##### FUNCTION gtk_item_select ##### -->
<para>
-
+Emits the "select" signal on the given item.
</para>
-@item:
+@item: a #GtkItem.
<!-- ##### FUNCTION gtk_item_deselect ##### -->
<para>
-
+Emits the "deselect" signal on the given item.
</para>
-@item:
+@item: a #GtkItem.
<!-- ##### FUNCTION gtk_item_toggle ##### -->
<para>
-
+Emits the "toggle" signal on the given item.
</para>
-@item:
+@item: a #GtkItem.
<!-- ##### SIGNAL GtkItem::select ##### -->
<para>
-
+Emitted when the item is selected.
</para>
@item: the object which received the signal.
<!-- ##### SIGNAL GtkItem::deselect ##### -->
<para>
-
+Emitted when the item is deselected.
</para>
@item: the object which received the signal.
<!-- ##### SIGNAL GtkItem::toggle ##### -->
<para>
-
+Emitted when the item is toggled.
</para>
@item: the object which received the signal.
</para>
-@object:
-@path:
-@accel_group:
-@widget:
-@items:
-@translate_func:
-@translate_data:
-@translate_notify:
<!-- ##### USER_FUNCTION GtkPrintFunc ##### -->
<para>
described below.\r
</para>
-@misc:
-@label:
-@label_wc:
-@pattern:
-@words:
-@max_width:
-@jtype:
-@wrap:
<!-- ##### STRUCT GtkLabelWord ##### -->
<para>\r
</para>
-@container:
-@children:
-@width:
-@height:
-@xoffset:
-@yoffset:
-@hadjustment:
-@vadjustment:
-@bin_window:
-@visibility:
-@configure_serial:
-@scroll_x:
-@scroll_y:
-@freeze_count:
<!-- ##### FUNCTION gtk_layout_new ##### -->
<para>
</para>
-@container:
-@children:
-@selection:
-@undo_selection:
-@undo_unselection:
-@last_focus_child:
-@undo_focus_child:
-@htimer:
-@vtimer:
-@anchor:
-@drag_pos:
-@anchor_state:
-@selection_mode:
-@drag_selection:
-@add_mode:
<!-- ##### FUNCTION gtk_list_new ##### -->
<para>
</para>
-@item:
<!-- ##### FUNCTION gtk_list_item_new ##### -->
<para>
Signal Marshallers
<!-- ##### SECTION Short_Description ##### -->
-
+Functions to adapt C structures to native calling convention.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
+<refsect2>
+<title>What are Signal Marshallers?</title>
+<para>
+Marshals are functions which all have the same prototype:
+they take a #GtkObject, a #GtkSignalFunc, a #gpointer,
+and an array of argument values.
+The functions are names gtk_marshall_RETURNTYPE__PARAMTYPE1_PARAMTYPE2....
+</para>
+<para>
+They then call a native function: the GtkObject is the first
+parameter passed in. The arguments are passed in the native
+calling convention: chars, shorts, ints, longs may be packed
+on the stack, or tucked in registers: it doesn't matter
+because the same calling convention will be generated
+inside the gtkmarshal code as is expected where you define
+your handlers.
+</para>
+<para>
+So the function named:
+<programlisting>
+gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*);
+</programlisting>
+will call the #GtkSignalFunc assuming it was a function with signature:
+<programlisting>
+gboolean sigfunc(gpointer,gint,gint,guint);
+</programlisting>
+</para>
+</refsect2>
+<refsect2>
+<title>Writing Custom Marshals</title>
+<para>
+Marshals are primarily used as arguments to gtk_signal_new().
+Sometimes, you may find that a marshaller you need isn't available
+in the standard list. Then you have to write your own.
+</para>
+<para>
+If you wish to define a signal with a new type of argument list.
+Suppose you want 2 pointers and 2 integers.
+You would write:
+<programlisting>
+typedef int (*GtkSignal_INT__POINTER_POINTER_INT_INT)(
+ gpointer, gpointer, gint, gint
+);
+
+void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object,
+ GtkSignalFunc func,
+ gpointer func_data,
+ GtkArg* args)
+{
+ GtkSignal_NONE__POINTER_POINTER_INT_INT rfunc;
+ gint* return_val;
+ return_val = GTK_RETLOC_INT(args[4]);
+ rfunc = (GtkSignal_INT__POINTER_POINTER_INT_INT)func;
+ *return_val = (*rfunc)(object,
+ GTK_VALUE_POINTER(args[0]),
+ GTK_VALUE_POINTER(args[1]),
+ GTK_VALUE_INT(args[2]),
+ GTK_VALUE_INT(args[3]),
+ func_data);
+}
+</programlisting>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
-</para>
-
-<!-- ##### MACRO gtk_signal_default_marshaller ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
-<para>
+<varlistentry>
+<term>#GtkSignal</term>
+<listitem><para>The signal handling functions (of which marshallers are
+really an implementation detail).</para></listitem>
+</varlistentry>
+</variablelist>
</para>
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object:
-@func:
-@func_data:
-@args:
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<!-- ##### MACRO gtk_signal_default_marshaller ##### -->
<para>
-
+A marshaller that returns void and takes no extra parameters.
</para>
-@object:
-@func:
-@func_data:
-@args:
should be accessed using the functions below.
</para>
-@menu_shell:
-@parent_menu_item:
-@old_active_menu_item:
-@accel_group:
-@position_func:
-@position_func_data:
-@toplevel:
-@tearoff_window:
-@torn_off:
<!-- ##### FUNCTION gtk_menu_new ##### -->
<para>
The #GtkMenuBar struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.)
</para>
-@menu_shell: the #GtkMenuShell container
-@shadow_type: the GtkShadowType to use
-
<!-- ##### FUNCTION gtk_menu_bar_new ##### -->
<para>
Creates the new #GtkMenuBar
</para>
-@item:
-@submenu:
-@accelerator_signal:
-@toggle_size:
-@accelerator_width:
-@show_toggle_indicator:
-@show_submenu_indicator:
-@submenu_placement:
-@submenu_direction:
-@right_justify:
-@timer:
<!-- ##### FUNCTION gtk_menu_item_new ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@container:
-@children:
-@active_menu_item:
-@parent_menu_shell:
-@active:
-@have_grab:
-@have_xgrab:
-@button:
-@ignore_leave:
-@menu_flag:
-@ignore_enter:
-@activate_time:
<!-- ##### FUNCTION gtk_menu_shell_append ##### -->
<para>
</tbody></tgroup></informaltable>
</para>
-@widget:
-@xalign:
-@yalign:
-@xpad:
-@ypad:
<!-- ##### FUNCTION gtk_misc_set_alignment ##### -->
<para>
</para>
-@container:
-@cur_page:
-@children:
-@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>
</para>
-@klass:
-@flags:
-@ref_count:
-@object_data:
<!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
<para>
should be accessed using the functions below.
</para>
-@button:
-@menu:
-@menu_item:
-@width:
-@height:
<!-- ##### FUNCTION gtk_option_menu_new ##### -->
<para>
</para>
-@parent:
-@children:
-@spacing:
-@default_border_width:
-@default_pad_x:
-@default_pad_y:
-@default_i_pad_x:
-@default_i_pad_y:
<!-- ##### ENUM GtkPackerOptions ##### -->
<para>
<para>
</para>
-@container:
-@child1:
-@child2:
-@handle:
-@groove_rectangle:
-@xor_gc:
@handle_size:
@gutter_size:
-@child1_size:
-@last_allocation:
-@min_position:
-@max_position:
-@position_set:
-@in_drag:
-@child1_shrink:
-@child1_resize:
-@child2_shrink:
-@child2_resize:
-@handle_xpos:
-@handle_ypos:
<!-- ##### FUNCTION gtk_paned_add1 ##### -->
<para>
should be accessed using the functions below.
</para>
-@misc:
-@pixmap:
-@mask:
-@pixmap_insensitive:
-@build_insensitive:
<!-- ##### FUNCTION gtk_pixmap_new ##### -->
<para>
</para>
-@window:
-@socket_window:
-@same_app:
<!-- ##### FUNCTION gtk_plug_construct ##### -->
<para>
should be accessed using the functions below.
</para>
-@widget:
-@buffer:
-@buffer_width:
-@buffer_height:
-@bpp:
-@rowstride:
-@dither:
-@type:
-@expand:
<!-- ##### STRUCT GtkPreviewInfo ##### -->
<para>
</para>
-@widget:
-@adjustment:
-@offscreen_pixmap:
-@format:
-@x_align:
-@y_align:
-@show_text:
-@activity_mode:
<!-- ##### FUNCTION gtk_progress_set_show_text ##### -->
<para>
</para>
-@progress:
-@bar_style:
-@orientation:
-@blocks:
-@in_block:
-@activity_pos:
-@activity_step:
-@activity_blocks:
-@activity_dir:
<!-- ##### ENUM GtkProgressBarStyle ##### -->
<para>
GtkRadioButton
<!-- ##### SECTION Short_Description ##### -->
-
+A choice from multiple check buttons.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A single radio button performs the same basic function as a #GtkCheckButton,
+as it's position in the object hierarchy reflects. It is only when multiple
+radio buttons are grouped together that they become a different user
+interface component in their own right.</para>
+<para>
+Every radio button is a member of some group of radio buttons. When one is selected, all other
+radio buttons in the same group are deselected. A #GtkRadioButton is one way
+of giving the user a choice from many options.
+</para>
+<para>
+Radio button widgets are created with gtk_radio_button_new(), passing NULL
+as the argument if this is the first radio button in a group. In subsequent
+calls, the group you wish to add this button to should be passed as an
+argument. Optionally, gtk_radio_button_new_with_label() can be used if you
+want a text label on the radio button.
+</para>
+<para>
+Alternatively, when adding widgets to an existing group of radio buttons,
+use gtk_radio_button_new_from_widget() with a #GtkRadioButton that already
+has a group assigned to it. The convenience function
+gtk_radio_button_new_with_label_from_widget() is also provided.
+</para>
+<para>
+To retrieve the group a #GtkRadioButton is assigned to, use
+gtk_radio_button_group().
+</para>
+<para>
+To remove a #GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_group().
+</para>
+<para>
+<example>
+<title>How to create a group of two radio buttons.</title>
+<programlisting>
+
+void create_radio_buttons(void) {
+
+ GtkWidget *window, *radio1, *radio2, *box, *entry;
+ window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+ box = gtk_vbox_new(TRUE, 2);
+
+ /* Create a radio button with a #GtkEntry widget */
+ radio1 = gtk_radio_button_new(NULL);
+ entry = gtk_entry_new();
+ gtk_container_add(GTK_CONTAINER(radio1), entry);
+
+
+ /* Create a radio button with a label */
+ radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON(radio1),
+ "I'm the second radio button.");
+
+ /* Pack them into a box, then show all the widgets */
+ gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
+ gtk_box_pack_start(GTK_BOX(box), radio2, TRUE, TRUE, 2);
+ gtk_container_add(GTK_CONTAINER(window), box);
+ gtk_widget_show_all (window);
+ return;
+}
+
+</programlisting>
+</example>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+<varlistentry>
+<term>#GtkOptionMenu</term>
+<listitem><para>Another way of offering the user a single choice from
+many.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkRadioButton ##### -->
<para>
-
+Contains only private data that should be read and manipulated using the
+functions below.
</para>
-@check_button:
-@group:
<!-- ##### FUNCTION gtk_radio_button_new ##### -->
<para>
-
+Creates a new #GtkRadioButton. To be of any practical value, a widget should
+then be packed into the radio button.
</para>
-@group:
-@Returns:
+@group: an existing radio button group, or NULL if you are creating a new group.
+@Returns: a new radio button.
<!-- ##### FUNCTION gtk_radio_button_new_from_widget ##### -->
<para>
-
+Creates a new #GtkRadioButton, adding it to the same group as @group. As
+with gtk_radio_button_new(), a widget should be packed into the radio button.
</para>
-@group:
-@Returns:
+@group: an existing #GtkRadioButton.
+@Returns: a new radio button.
<!-- ##### FUNCTION gtk_radio_button_new_with_label ##### -->
<para>
-
+Creates a new #GtkRadioButton with a text label.
</para>
-@group:
-@label:
-@Returns:
+@group: an existing radio button group, or NULL if you are creating a new
+group.
+@label: the text label to display next to the radio button.
+@Returns: a new radio button.
<!-- ##### FUNCTION gtk_radio_button_new_with_label_from_widget ##### -->
<para>
-
+Creates a new #GtkRadioButton with a text label, adding it to the same group
+as @group.
</para>
-@group:
-@label:
-@Returns:
+@group: an existing #GtkRadioButton.
+@label: a text string to display next to the radio button.
+@Returns: a new radio button.
<!-- ##### FUNCTION gtk_radio_button_group ##### -->
<para>
-
+Retrieves the group assigned to a radio button.
</para>
-@radio_button:
-@Returns:
+@radio_button: a #GtkRadioButton.
+@Returns: a linked list containing all the radio buttons in the same group
+as @radio_button.
<!-- ##### FUNCTION gtk_radio_button_set_group ##### -->
<para>
-
+Sets a #GtkRadioButton's group. It should be noted that this does not change
+the layout of your interface in any way, so if you are changing the group,
+it is likely you will need to re-arrange the user interface to reflect these
+changes.
</para>
-@radio_button:
-@group:
+@radio_button: a #GtkRadioButton.
+@group: an existing radio button group, such as one returned from
+gtk_radio_button_group().
<!-- ##### ARG GtkRadioButton:group ##### -->
<para>
-
+Sets a new group for a radio button.
</para>
</para>
-@check_menu_item:
-@group:
<!-- ##### FUNCTION gtk_radio_menu_item_new ##### -->
<para>
</para>
-@widget:
-@trough:
-@slider:
-@step_forw:
-@step_back:
-@x_click_point:
-@y_click_point:
-@button:
-@digits:
-@policy:
-@scroll_type:
-@in_child:
-@click_child:
-@need_timer:
-@timer:
-@old_value:
-@old_lower:
-@old_upper:
-@old_page_size:
-@adjustment:
<!-- ##### FUNCTION gtk_range_get_adjustment ##### -->
<para>
points are really 1/72.27 in.)
</para>
-@widget:
-@backing_store:
-@non_gr_exp_gc:
-@metric:
-@xsrc:
-@ysrc:
-@slider_size:
-@lower:
-@upper:
-@position:
-@max_size:
<!-- ##### STRUCT GtkRulerMetric ##### -->
<para>
</para>
@ruler: the gtkruler
-@lower:the upper limit of the ruler
-@upper:the lower limit of the ruler
-@position:the mark on the ruler
-@max_size:the maximum size of the ruler
-
-
-<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
-<para>
-
-</para>
-
-@ruler: the gtkruler
-
-
-<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
-<para>
-
-</para>
-
-@ruler: the gtkruler
+@lower: the upper limit of the ruler
+@upper: the lower limit of the ruler
+@position: the mark on the ruler
+@max_size: the maximum size of the ruler
</tbody></tgroup></informaltable>
</para>
-@range:
-@draw_value:
-@value_pos:
<!-- ##### FUNCTION gtk_scale_set_digits ##### -->
<para>
only be accessed using the functions below.\r
</para>
-@container:
-@hscrollbar:
-@vscrollbar:
-@hscrollbar_policy:
-@vscrollbar_policy:
-@hscrollbar_visible:
-@vscrollbar_visible:
-@window_placement:
<!-- ##### FUNCTION gtk_scrolled_window_new ##### -->
<para>\r
The #GtkSeparator-struct struct contains private data only.
</para>
-@widget:
Signals
<!-- ##### SECTION Short_Description ##### -->
-
+Object methods and callbacks.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+<refsect2>\r
+<title>What are signals?</title>\r
+<para>\r
+Signals are a way to get notification when something happens\r
+and to customize object behavior according to the\r
+user's needs.\r
+Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,\r
+"class_name::signal_name", where signal_name might be something like\r
+"clicked" and class_name might be "GtkButton". Note that some other class\r
+may also define a "clicked" callback, so long as it doesn't derive from\r
+#GtkButton.\r
+</para>\r
+<para>\r
+When they are created, they are also assigned a unique positive integer,\r
+the signal id (1 is the first signal id- 0 is used to flag an error).\r
+Each is also tied to an array of types that describes\r
+the prototype of the function pointer(s) (handlers) you may\r
+connect to the signal. Finally, every signal has\r
+a default handler that is given by a function pointer\r
+in its class structure: it is run by default whenever the\r
+signal is emitted. (It is possible that a signal will\r
+be emitted and a user-defined handler will prevent the default handler\r
+from being run.)\r
+</para>\r
+<para>\r
+Signals are used by everyone, but they are only\r
+created on a per class basis-- so you should call\r
+call gtk_signal_new() unless you are writing\r
+a new #GtkObject type. However, if you want to make a new signal\r
+for an existing type, you may use gtk_object_class_user_signal_new()\r
+to create a signal that doesn't correspond to a class's builtin\r
+methods.\r
+</para>\r
+</refsect2>\r
+<refsect2>\r
+<title>How are signals used?</title>\r
+<para>\r
+There are two basic actions in the signal handling game.\r
+If you want notification of an event, you must <Emphasis>connect</Emphasis>\r
+a function pointer and a data pointer to that signal; the data pointer\r
+will be passed as the last argument to the function (so long as you\r
+are using the default marshalling functions).\r
+You will receive a connection id, a unique positive integer\r
+corresponding to that attachment.\r
+</para>\r
+<para>\r
+Functions that want to notify the user of certain actions,\r
+<Emphasis>emit</Emphasis> signals.\r
+</para>\r
+</refsect2>\r
+<refsect2>\r
+<title>Basic Terminology</title>\r
+<variablelist>\r
+\r
+<varlistentry>\r
+<term>signal</term>\r
+<listitem><para>A class method, e.g. GtkButton::clicked.\r
+More precisely it is a unique class-branch/signal-name pair.\r
+This means you may not define a signal handler for a class which\r
+derives from GtkButton that is called clicked,\r
+but it is okay to share signals names if they are separate in\r
+the class tree.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>default handler</term>\r
+<listitem><para>The object's internal method which is invoked\r
+when the signal is emitted.</para>\r
+</listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>user-defined handler</term>\r
+<listitem><para>A function pointer and data connected\r
+to a signal (for a particular object).</para>\r
+<para>There are really two types: those which are connected\r
+normally, and those which are connected by one \r
+of the connect_after functions. The connect_after handlers\r
+are always run after the default handler.</para>\r
+<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>\r
+</listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>emission</term>\r
+<listitem><para>the whole process of emitting a signal,\r
+including the invocation of all\r
+the different handler types mentioned above.</para>\r
+</listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>signal id</term>\r
+<listitem><para>The unique positive (nonzero) integer\r
+used to identify a signal. It can be used instead of \r
+a name to many functions for a slight performance\r
+improvement.</para>\r
+</listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>connection id</term>\r
+<listitem><para>The unique positive (nonzero) integer\r
+used to identify the connection of a user-defined handler\r
+to a signal. Notice that it is allowed to connect the\r
+same function-pointer/user-data pair twice, so\r
+there is no guarantee that a function-pointer/user-data\r
+maps to a unique connection id.\r
+</para>\r
+</listitem>\r
+</varlistentry>\r
+\r
+</variablelist>\r
+</refsect2>\r
+\r
+<refsect2><title>A brief note on how they work.</title>\r
+<para>\r
+The functions responsible for translating an array of #GtkArgs\r
+to your C compiler's normal semantics are called Marshallers.\r
+They are identified by\r
+gtk_marshal_return_value__parameter_list()\r
+for example a C function returning a gboolean and taking a gint\r
+can be invoked by using gtk_marshal_BOOL__INT().\r
+Not all possibly combinations of return/params are available,\r
+of course, so if you are writing a #GtkObject with parameters\r
+you might have to write a marshaller.\r
+</para>\r
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
+<para>\r
+<variablelist>\r
+\r
+<varlistentry>\r
+<term>#GtkObject</term>\r
+<listitem><para>The base class for things which emit signals.</para></listitem>\r
+</varlistentry>\r
+\r
+</variablelist>\r
</para>
<!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
<!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
-<para>
-
+<para>\r
+This is currently a hack left in for a scheme wrapper library.\r
+It may be removed.\r
+</para>\r
+<para>\r
+Don't use it.\r
</para>
-@object:
-@data:
-@nparams:
-@args:
-@arg_types:
-@return_type:
+@object: The object which emits the signal.
+@data: The user data associated with the hook.
+@nparams: The number of parameters to the function.
+@args: The actual values of the arguments.
+@arg_types: The types of the arguments.
+@return_type: The type of the return value from the function\r
+or #GTK_TYPE_NONE for no return value.
<!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
-<para>
-
+<para>\r
+A function which you can use to clean up when the\r
+signal handler is destroyed.\r
+</para>\r
+<para>\r
+For example, if your handler requires a few variables\r
+that you made into a struct and allocated (using g_new()\r
+or something), then you will probably want to free\r
+it as soon as the hook is destroyed. This will\r
+allow you to do that. (For this in particular\r
+it is convenient to pass g_free() as a #GtkSignalDestroy\r
+function).\r
</para>
-@data:
+@data: The user data associated with the hook that is being\r
+destroyed.
<!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
-<para>
-
-</para>
-
-@object:
-@signal_id:
-@n_params:
-@params:
-@data:
-@Returns:
+<para>\r
+A simple function pointer to get invoked when the\r
+signal is emitted. This allows you tie a hook to the signal type,\r
+so that it will trap all emissions of that signal, from any object.\r
+</para>\r
+<para>\r
+You may not attach these to signals created with the\r
+#GTK_RUN_NO_HOOKS flag.\r
+</para>
+
+@object: the object which emits the signal.
+@signal_id: the unique integer identify the signal type.
+@n_params: the number of parameters to the function,\r
+not including return value.
+@params: the parameters to the function. A pointer to\r
+the return value is passed as a last element.
+@data: the user data associated with the hook.
+@Returns: whether it wished to be removed. If it returns\r
+TRUE, the signal hook is disconnected (and destroyed).
<!-- ##### STRUCT GtkSignalQuery ##### -->
-<para>
-
+<para>\r
+This structure contains all the information about a particular\r
+signal: its name, the type it affects, the signature of the handlers,\r
+and its unique identifying integer.\r
</para>
@object_type:
@nparams:
@params:
+<!-- ##### ENUM GtkSignalRunType ##### -->
+<para>\r
+These configure the signal's emission. They control\r
+whether the signal can be emitted recursively on an object\r
+and\r
+whether to run the default method before or after the user-defined handlers.\r
+</para>\r
+\r
+<variablelist>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_FIRST</term>\r
+<listitem><para>Run the default handler before the connected user-defined\r
+handlers.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_LAST</term>\r
+<listitem><para>Run the default handler after the connected\r
+user-defined handlers.\r
+(Handlers registered as "after" always run after the default handler though)\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_BOTH</term>\r
+<listitem><para>Run the default handler twice,\r
+once before the user-defined handlers,\r
+and\r
+once after.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_NO_RECURSE</term>\r
+<listitem><para>Whether to prevent a handler or hook\r
+from reemitting the signal from within itself.\r
+Attempts to\r
+emit the signal while it is running will result in the signal\r
+emission being restarted once it is done with the current processing.\r
+</para><para>\r
+You must be\r
+careful to avoid having two handlers endlessly reemitting signals,\r
+gtk_signal_n_emissions() can be helpful.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_ACTION</term>\r
+<listitem><para>The signal is an action you can \r
+invoke without any particular setup or cleanup.\r
+The signal is treated no differently, but some\r
+other code can determine if the signal is appropriate to\r
+delegate to user control. For example, key binding sets\r
+only allow bindings of ACTION signals to keystrokes.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+<varlistentry>\r
+<term>GTK_RUN_NO_HOOKS</term>\r
+<listitem><para>This prevents the connection of emission hooks\r
+to the signal.\r
+</para></listitem>\r
+</varlistentry>\r
+\r
+</variablelist>
+
+@GTK_RUN_FIRST:
+@GTK_RUN_LAST:
+@GTK_RUN_BOTH:
+@GTK_RUN_NO_RECURSE:
+@GTK_RUN_ACTION:
+@GTK_RUN_NO_HOOKS:
+
<!-- ##### FUNCTION gtk_signal_init ##### -->
<para>
<!-- ##### FUNCTION gtk_signal_new ##### -->
-<para>
-
-</para>
-
-@name:
-@signal_flags:
-@object_type:
-@function_offset:
-@marshaller:
-@return_val:
-@nparams:
-@Varargs:
-@Returns:
+<para>\r
+Create a new signal type. (This is usually done in the\r
+class initializer.)\r
+</para>
+
+@name: the event name for the signal, e.g. "clicked".
+@signal_flags: a combination of GTK_RUN flags\r
+specifying detail of when the default handler is to be invoked.\r
+You should at least specify #GTK_RUN_FIRST\r
+or #GTK_RUN_LAST.
+@object_type: the type of object this signal pertains to.\r
+It will also pertain to derivers of this type automatically.
+@function_offset: How many bytes the function pointer is in\r
+the class structure for this type. Used to invoke a class\r
+method generically.
+@marshaller: the function to translate between an array\r
+of GtkArgs and the native calling convention. Usually they\r
+are identified just by the type of arguments they take:\r
+for example, gtk_marshal_BOOL__STRING() describes a marshaller\r
+which takes a string and returns a boolean value.
+@return_val: the type of return value, or GTK_TYPE_NONE for a signal\r
+without a return value.
+@nparams: the number of parameter the handlers may take.
+@Varargs: a list of GTK_TYPE_*, one for each parameter.
+@Returns: the signal id.
<!-- ##### FUNCTION gtk_signal_newv ##### -->
-<para>
-
-</para>
-
-@name:
-@signal_flags:
-@object_type:
-@function_offset:
+<para>\r
+Create a new signal type. (This is usually done in a\r
+class initializer.)\r
+</para>\r
+<para>\r
+This function take the types as an array, instead of a list\r
+following the arguments. Otherwise the same as gtk_signal_new().\r
+</para>
+
+@name: the name of the signal to create.
+@signal_flags: see gtk_signal_new().
+@object_type: the type of GtkObject to associate the signal with.
+@function_offset: how many bytes the function pointer is in\r
+the class structure for this type.
@marshaller:
-@return_val:
-@nparams:
-@params:
-@Returns:
+@return_val: the type of the return value, or GTK_TYPE_NONE if\r
+you don't want a return value.
+@nparams: the number of parameters to the user-defined handlers.
+@params: an array of GtkTypes, describing the prototype to\r
+the callbacks.
+@Returns: the signal id.
<!-- ##### FUNCTION gtk_signal_lookup ##### -->
-<para>
-
+<para>\r
+Given the name of the signal and the type of object it connects\r
+to, get the signal's identifying integer. Emitting the signal\r
+by number is somewhat faster than using the name each time.\r
+</para>\r
+<para>\r
+It also tries the ancestors of the given type.\r
</para>
-@name:
-@object_type:
-@Returns:
+@name: the signal's name, e.g. clicked.
+@object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.
+@Returns: the signal's identifying number, or 0 if no signal was found.
<!-- ##### FUNCTION gtk_signal_name ##### -->
-<para>
-
+<para>\r
+Given the signal's identifier, find its name.\r
+</para>\r
+<para>\r
+Two different signals may have the same name, if they have differing types.\r
</para>
-@signal_id:
-@Returns:
+@signal_id: the signal's identifying number.
+@Returns: the signal name, or NULL if the signal number was invalid.
<!-- ##### FUNCTION gtk_signal_emit ##### -->
-<para>
-
-</para>
-
-@object:
-@signal_id:
-@Varargs:
+<para>\r
+Emit a signal. This causes the default handler and user-defined\r
+handlers to be run.\r
+</para>\r
+<para>\r
+Here is what gtk_signal_emit() does:\r
+</para>\r
+<para>\r
+1. Calls the default handler and the user-connected handlers.\r
+The default handler will be called first if\r
+GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.\r
+</para>\r
+<para>\r
+2. Calls all handlers connected with the "after" flag set.\r
+</para>
+
+@object: the object that emits the signal.
+@signal_id: the signal identifier.
+@Varargs: the parameters to the function, followed\r
+by a pointer to the return type, if any.
<!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
-<para>
-
+<para>\r
+Emit a signal. This causes the default handler and user-connected\r
+handlers to be run.\r
</para>
-@object:
-@name:
-@Varargs:
+@object: the object that emits the signal.
+@name: the name of the signal.
+@Varargs: the parameters to the function, followed\r
+by a pointer to the return type, if any.
<!-- ##### FUNCTION gtk_signal_emitv ##### -->
-<para>
-
+<para>\r
+Emit a signal. This causes the default handler and user-connected\r
+handlers to be run. This differs from gtk_signal_emit() by taking\r
+an array of GtkArgs instead of using C's varargs mechanism.\r
</para>
-@object:
-@signal_id:
-@params:
+@object: the object to emit the signal to.
+@signal_id: the signal identifier.
+@params: an array of GtkArgs, one for each parameter,\r
+followed by one which is a pointer to the return type.
<!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
-<para>
-
+<para>\r
+Emit a signal by name. This causes the default handler and user-connected\r
+handlers to be run. This differs from gtk_signal_emit() by taking\r
+an array of GtkArgs instead of using C's varargs mechanism.\r
</para>
-@object:
-@name:
-@params:
+@object: the object to emit the signal to.
+@name: the name of the signal.
+@params: an array of GtkArgs, one for each parameter,\r
+followed by one which is a pointer to the return type.
<!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
-<para>
-
+<para>\r
+Find out the recursion depth of emissions for a particular type\r
+of signal and object. (So it will\r
+always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified)\r
+This is a way to avoid recursion: you can see if\r
+you are currently running in that signal handler and emit it only\r
+if you are.\r
+</para>\r
+<para>Another way to look at it is that this number increases\r
+by one when #gtk_signal_emit(), et al, are called,\r
+and decreases by one when #gtk_signal_emit() returns.\r
</para>
-@object:
-@signal_id:
-@Returns:
+@object: the object with the signal handler.
+@signal_id: the signal id.
+@Returns: the recursion depth of emissions of this signal for this\r
+object.
<!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
-<para>
-
+<para>\r
+Find out the recursion depth of emissions for a particular type\r
+of signal and object. Just like gtk_signal_n_emissions()\r
+except it will lookup the signal id for you.\r
</para>
-@object:
-@name:
-@Returns:
+@object: the object with the signal handler.
+@name: the signal name.
+@Returns: the recursion depth of emissions of this signal for this\r
+object.
<!-- ##### FUNCTION gtk_signal_emit_stop ##### -->
-<para>
-
+<para>\r
+This function aborts a signal's current emission.\r
+</para>\r
+<para>\r
+It will prevent the default method from running,\r
+if the signal was #GTK_RUN_LAST and you connected\r
+normally (i.e. without the "after" flag).\r
+<para>\r
+It will print a warning if used on a signal which\r
+isn't being emitted.\r
</para>
-@object:
-@signal_id:
+@object: the object whose signal handlers you wish to stop.
+@signal_id: the signal identifier, as returned by gtk_signal_lookup().
<!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
-<para>
-
+<para>\r
+This function aborts a signal's current emission.\r
+</para>\r
+<para>It is just like\r
+gtk_signal_emit_stop()\r
+except it will lookup the signal id for you.\r
</para>
-@object:
-@name:
+@object: the object whose signal handlers you wish to stop.
+@name: the name of the signal you wish to stop.
<!-- ##### FUNCTION gtk_signal_connect ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@func:
-@func_data:
-@Returns:
+<para>\r
+Attach a function pointer and user data to a signal for\r
+a particular object.\r
+</para>\r
+<para>\r
+The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.\r
+It will be the same object as the one you're connecting\r
+the hook to. The func_data will be passed as the last parameter\r
+to the hook.\r
+</para>\r
+<para>\r
+All else being equal, signal handlers are invoked in the order \r
+connected (see gtk_signal_emit() for the other details of\r
+which order things are called in).\r
+</para>\r
+<para>\r
+Here is how one passes an integer as user data,\r
+for when you just want to specify a constant int\r
+as parameter to your function:\r
+<informalexample>\r
+<programlisting>\r
+static void button_clicked_int(GtkButton* button, gpointer func_data)\r
+{\r
+ g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));\r
+}\r
+\r
+/* By calling this function, you will make the g_print above\r
+ * execute, printing the number passed as `to_print'. */\r
+static void attach_print_signal(GtkButton* button, gint to_print)\r
+{\r
+ gtk_signal_connect(GTK_OBJECT(button), "clicked",\r
+ GTK_SIGNAL_FUNC(button_clicked_int),\r
+ GINT_TO_POINTER(to_print));\r
+}\r
+</programlisting>\r
+</informalexample>
+
+@object: the object associated with the signal, e.g. if a button\r
+is getting pressed, this is that button.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@func_data: value to pass as to your function (through the marshaller).
+@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_after ##### -->
-<para>
-
+<para>\r
+Attach a function pointer and user data to a signal\r
+so that this handler will be called after the other handlers.\r
</para>
-@object:
-@name:
-@func:
-@func_data:
-@Returns:
+@object: the object associated with the signal.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@func_data: value to pass as to your function (through the marshaller).
+@Returns: the unique identifier for this attachment: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_object ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@func:
-@slot_object:
-@Returns:
+<para>\r
+This function is for registering a callback that will\r
+call another object's callback. That is,\r
+instead of passing the object which is responsible\r
+for the event as the first parameter of the callback,\r
+it is switched with the user data (so the object which emits\r
+the signal will be the last parameter, which is where the\r
+user data usually is).\r
+</para>\r
+<para>\r
+This is useful for passing a standard function in as a callback.\r
+For example, if you wanted a button's press to gtk_widget_show()\r
+some widget, you could write:\r
+</para>\r
+<informalexample>\r
+<programlisting>\r
+gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);\r
+</programlisting>\r
+</informalexample>
+
+@object: the object which emits the signal.
+@name: the name of the signal.
+@func: the function to callback.
+@slot_object: the object to pass as the first parameter to func.\r
+(Though it pretends to take an object, you can\r
+really pass any gpointer as the #slot_object .)
+@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_object_after ##### -->
-<para>
-
+<para>\r
+Attach a signal hook to a signal, passing in an alternate\r
+object as the first parameter, and guaranteeing \r
+that the default handler and all normal\r
+handlers are called first.\r
</para>
-@object:
-@name:
-@func:
-@slot_object:
-@Returns:
+@object: the object associated with the signal.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@slot_object: the object to pass as the first parameter to #func.
+@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_full ##### -->
-<para>
-
-</para>
-
-@object:
-@name:
-@func:
-@marshal:
-@data:
-@destroy_func:
-@object_signal:
-@after:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
-<para>
-
-</para>
-
-@object:
-@signal:
-@func:
-@alive_object:
+<para>\r
+Attach a function pointer and user data to a signal with\r
+more control.\r
+</para>
+
+@object: the object which emits the signal. For example, a button\r
+in the button press signal.
+@name: the name of the signal.
+@func: function pointer to attach to the signal.
+@marshal: the function marshal, see the gtkmarshall documentation for\r
+more details, but briefly: the marshaller is a function which takes\r
+the #GtkObject which emits the signal, the user data, the number of the\r
+arguments, and the array of arguments. It is responsible for\r
+calling the function in the appropriate calling convention.\r
+gtk_signal_default_marshaller is usually fine.\r
+(This shows up, for example, when worrying about matching\r
+c++ or other languages' calling conventions.)
+@data: the user data associated with the function.
+@destroy_func: function to call when this particular hook is \r
+disconnected.
+@object_signal: whether this is an object signal-- basically an "object\r
+signal" is one that wants its user_data and object fields switched,\r
+which is useful for calling functions which operate on another\r
+object primarily.
+@after: whether to invoke the user-defined handler after the signal, or to let \r
+the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST\r
+and #GTK_RUN_LAST).
+@Returns: the connection id.
<!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
-<para>
+<para>\r
+Attach a function pointer and another GtkObject to a signal.\r
+</para>\r
+<para>\r
+This function takes an object whose "destroy" signal\r
+should be trapped.\r
+That way, you don't have to clean up the\r
+signal handler when you destroy the object.\r
+It is a little less efficient though.\r
+</para>\r
+<para>\r
+(Instead you may call gtk_signal_disconnect_by_data(), if you want\r
+to explicitly delete all attachments to this object. This\r
+is perhaps not recommended since it could be confused\r
+with an integer masquerading as a pointer (through GINT_AS_POINTER).)\r
+</para>
+
+@object: the object that emits the signal.
+@signal:
+@func: function pointer to attach to the signal.
+@func_data: pointer to pass to func.
+@alive_object: object whose death should cause the handler connection\r
+to be destroyed.
+<!-- # Unused Parameters # -->
+@name: name of the signal.
-</para>
-@object:
+<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
+<para>\r
+These signal connectors are for signals which refer to objects,\r
+so they must not be called after the object is deleted.\r
+</para>\r
+<para>\r
+Unlike gtk_signal_connect_while_alive(),\r
+this swaps the object and user data, making it suitable for\r
+use with functions which primarily operate on the user data.\r
+</para>\r
+<para>\r
+This function acts just like gtk_signal_connect_object() except\r
+it traps the "destroy" signal to prevent you from having to\r
+clean up the handler.\r
+</para>
+
+@object: the object associated with the signal.
@signal:
-@func:
-@func_data:
-@alive_object:
+@func: function pointer to attach to the signal.
+@alive_object: the user data, which must be an object, whose destruction\r
+should signal the removal of this signal.
+<!-- # Unused Parameters # -->
+@name: name of the signal.
<!-- ##### FUNCTION gtk_signal_disconnect ##### -->
-<para>
-
+<para>\r
+Destroy a user-defined handler connection.\r
</para>
-@object:
-@handler_id:
+@object: the object which the handler pertains to.
+@handler_id: the connection id.
<!-- ##### FUNCTION gtk_signal_disconnect_by_func ##### -->
-<para>
-
+<para>\r
+Destroy all connections for a particular object, with\r
+the given function-pointer and user-data.\r
</para>
-@object:
-@func:
-@data:
+@object: the object which emits the signal.
+@func: the function pointer to search for.
+@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_disconnect_by_data ##### -->
-<para>
-
+<para>\r
+Destroy all connections for a particular object, with\r
+the given user-data.\r
</para>
-@object:
-@data:
+@object: the object which emits the signal.
+@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_block ##### -->
-<para>
-
+<para>\r
+Prevent an user-defined handler from being invoked. All other\r
+signal processing will go on as normal, but this particular\r
+handler will ignore it.\r
</para>
-@object:
-@handler_id:
+@object: the object which emits the signal to block.
+@handler_id: the connection id.
<!-- ##### FUNCTION gtk_signal_handler_block_by_func ##### -->
-<para>
-
+<para>\r
+Prevent a user-defined handler from being invoked, by reference to\r
+the user-defined handler's function pointer and user data. (It may result in\r
+multiple hooks being blocked, if you've called connect multiple times.)\r
</para>
-@object:
-@func:
-@data:
+@object: the object which emits the signal to block.
+@func: the function pointer of the handler to block.
+@data: the user data of the handler to block.
<!-- ##### FUNCTION gtk_signal_handler_block_by_data ##### -->
-<para>
-
+<para>\r
+Prevent all user-defined handlers with a certain user data from being invoked.\r
</para>
-@object:
-@data:
+@object: the object which emits the signal we want to block.
+@data: the user data of the handlers to block.
<!-- ##### FUNCTION gtk_signal_handler_unblock ##### -->
-<para>
-
+<para>\r
+Undo a block, by connection id. Note that undoing a block doesn't\r
+necessarily make the hook callable, because if you block a\r
+hook twice, you must unblock it twice.\r
</para>
-@object:
-@handler_id:
+@object: the object which emits the signal we want to unblock.
+@handler_id: the emission handler identifier, as returned by\r
+gtk_signal_connect(), etc.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_func ##### -->
-<para>
-
+<para>\r
+Undo a block, by function pointer and data.\r
+Note that undoing a block doesn't\r
+necessarily make the hook callable, because if you block a\r
+hook twice, you must unblock it twice.\r
</para>
-@object:
-@func:
-@data:
+@object: the object which emits the signal we want to unblock.
+@func: the function pointer to search for.
+@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_data ##### -->
-<para>
-
+<para>\r
+Undo block(s), to all signals for a particular object\r
+with a particular user-data pointer\r
</para>
-@object:
-@data:
+@object: the object which emits the signal we want to unblock.
+@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_pending ##### -->
-<para>
-
+<para>\r
+Returns a connection id corresponding to a given signal id and object.\r
+</para>\r
+<para>\r
+One example of when you might use this is when the arguments\r
+to the signal are difficult to compute. A class implementor\r
+may opt to not emit the signal if no one is attached anyway,\r
+thus saving the cost of building the arguments.\r
</para>
-@object:
-@signal_id:
-@may_be_blocked:
-@Returns:
+@object: the object to search for the desired user-defined handler.
+@signal_id: the number of the signal to search for.
+@may_be_blocked: whether it is acceptable to return a blocked\r
+handler.
+@Returns: the connection id, if a connection was found. 0 otherwise.
<!-- ##### FUNCTION gtk_signal_handler_pending_by_func ##### -->
-<para>
-
+<para>\r
+Returns a connection id corresponding to a given signal id, object, function\r
+pointer and user data.\r
</para>
-@object:
-@signal_id:
-@may_be_blocked:
-@func:
-@data:
-@Returns:
+@object: the object to search for the desired handler.
+@signal_id: the number of the signal to search for.
+@may_be_blocked: whether it is acceptable to return a blocked\r
+handler.
+@func: the function pointer to search for.
+@data: the user data to search for.
+@Returns: the connection id, if a handler was found. 0 otherwise.
<!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
-<para>
-
+<para>\r
+Returns whether a connection id is valid (and optionally not blocked).\r
</para>
-@object:
-@handler_id:
-@may_be_blocked:
-@Returns:
+@object: the object to search for the desired handler.
+@handler_id: the connection id.
+@may_be_blocked: whether it is acceptable to return a blocked\r
+handler.
+@Returns: TRUE if the signal exists and wasn't blocked,\r
+unless #may_be_blocked was specified. FALSE otherwise.
<!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
-<para>
-
+<para>\r
+Destroy all the signal handlers connected to an object.\r
+This is done automatically when the object is destroyed.\r
+</para>\r
+<para>\r
+This function is labeled private.\r
</para>
-@object:
+@object: the object whose signal handlers should be destroyed.
<!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
-<para>
-
+<para>\r
+These set default functions to call when the user didn't\r
+supply a function when connecting. (These are rarely\r
+used, and probably only for language bindings)\r
+</para>\r
+<para>\r
+By default, there are no such functions.\r
</para>
-@marshal_func:
-@destroy_func:
+@marshal_func: the function to invoke on every handlers for which there\r
+isn't a function pointer. May be NULL.
+@destroy_func: the function to invoke when each hook is destroyed.\r
+May be NULL.
<!-- ##### FUNCTION gtk_signal_query ##### -->
-<para>
-
+<para>\r
+Obtain information about a signal.\r
</para>
-@signal_id:
-@Returns:
+@signal_id: the signal type identifier.
+@Returns: a pointer to a GtkSignalQuery structure\r
+which contains all the information, or NULL.\r
+The pointer is allocated just for you: you must g_free() it.
<!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
-<para>
-
+<para>\r
+Add an emission hook for a type of signal, for any object.\r
</para>
-@signal_id:
-@hook_func:
-@data:
-@Returns:
+@signal_id: the type of signal to hook for.
+@hook_func: the function to invoke to handle the emission hook.
+@data: the user data passed in to hook_func.
+@Returns: the id (that you may pass as a parameter\r
+to gtk_signal_remove_emission_hook()).
<!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
-<para>
-
+<para>\r
+Add an emission hook for a type of signal, for any object.\r
+(with control of what happens when the hook is\r
+destroyed).\r
</para>
-@signal_id:
-@hook_func:
-@data:
-@destroy:
-@Returns:
+@signal_id: the type of signal add the hook for.
+@hook_func: the function to invoke to handle the hook.
+@data: the user data passed in to hook_func.
+@destroy: a function to invoke when the hook is destroyed,\r
+to clean up any allocation done just for this\r
+signal handler.
+@Returns: the id (that you may pass as a parameter\r
+to gtk_signal_remove_emission_hook()).
<!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
-<para>
-
+<para>\r
+Delete an emission hook. (see gtk_signal_add_emission_hook())\r
</para>
-@signal_id:
-@hook_id:
+@signal_id: the id of the signal type.
+@hook_id: the id of the emission handler, returned by add_emission_hook().
</tbody></tgroup></informaltable>
</para>
-@container:
-@request_width:
-@request_height:
-@current_width:
-@current_height:
-@plug_window:
-@same_app:
-@focus_in:
-@have_size:
-@need_map:
<!-- ##### FUNCTION gtk_socket_new ##### -->
<para>
<structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton widget, and can be used accordingly. All other fields contain private data and should only be modified using the functions below.
</para>
-@entry:
-@adjustment:
-@panel:
-@shadow_type:
-@timer:
-@ev_time:
-@climb_rate:
-@timer_step:
-@update_policy:
-@in_child:
-@click_child:
-@button:
-@need_timer:
-@timer_calls:
-@digits:
-@numeric:
-@wrap:
-@snap_to_ticks:
<!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
<para>
Contains private data that should be modified with the functions described below.
</para>
-@parent_widget:
-@frame:
-@label:
-@messages:
-@keys:
-@seq_context_id:
-@seq_message_id:
<!-- ##### STRUCT GtkStatusbarMsg ##### -->
<para>
<structfield>nrows</structfield> and <structfield>ncols</structfield> are 16bit integers storing the number of rows and columns the table has.
</para>
-@container:
-@children:
-@rows:
-@cols:
-@nrows:
-@ncols:
-@column_spacing:
-@row_spacing:
-@homogeneous:
<!-- ##### STRUCT GtkTableChild ##### -->
<para>
should be accessed using the functions below.
</para>
-@menu_item:
-@torn_off:
<!-- ##### FUNCTION gtk_tearoff_menu_item_new ##### -->
<para>
\r
</para>
-@editable:
-@text_area:
-@hadj:
-@vadj:
-@gc:
-@line_wrap_bitmap:
-@line_arrow_bitmap:
<!-- ##### STRUCT GtkTextFont ##### -->
<para>\r
GtkTipsQuery
<!-- ##### SECTION Short_Description ##### -->
-
+displays help about widgets in the user interface.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkTipsQuery widget is a subclass of #GtkLabel which is used to display
+help about widgets in a user interface.
+</para>
+<para>
+A query is started with a call to gtk_tips_query_start_query(), usually
+when some kind of 'Help' button is pressed. The #GtkTipsQuery then grabs all
+events, stopping the user interface from functioning normally.
+Then as the user moves the mouse over the widgets, the #GtkTipsQuery displays
+each widget's tooltip text.
+</para>
+<para>
+By connecting to the "widget-entered" or "widget-selected" signals, it is
+possible to customize the #GtkTipsQuery to perform other actions when widgets
+are entered or selected. For example, a help browser could be opened with
+documentation on the widget selected.
+</para>
+<para>
+At some point a call to gtk_tips_query_stop_query() must be made in order to
+stop the query and return the interface to its normal state.
+The gtk_tips_query_set_caller() function can be used to specify a widget
+which the user can select to stop the query (often the same button used to
+start the query).
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkTooltips</term>
+<listitem><para>the object which handles tooltips.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkTipsQuery ##### -->
<para>
-
+The #GtkTipsQuery-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@label:
-@emit_always:
-@in_query:
-@label_inactive:
-@label_no_tip:
-@caller:
-@last_crossed:
-@query_cursor:
<!-- ##### FUNCTION gtk_tips_query_new ##### -->
<para>
-
+Creates a new #GtkTipsQuery.
</para>
-@Returns:
+@Returns: a new #GtkTipsQuery.
<!-- ##### FUNCTION gtk_tips_query_start_query ##### -->
<para>
-
+Starts a query.
+The #GtkTipsQuery widget will take control of the mouse and as the mouse
+moves it will display the tooltip of the widget beneath the mouse.
</para>
-@tips_query:
+@tips_query: a #GtkTipsQuery.
<!-- ##### FUNCTION gtk_tips_query_stop_query ##### -->
<para>
-
+Stops a query.
</para>
-@tips_query:
+@tips_query: a #GtkTipsQuery.
<!-- ##### FUNCTION gtk_tips_query_set_caller ##### -->
<para>
-
+Sets the widget which initiates the query, usually a button.
+If the @caller is selected while the query is running, the query is
+automatically stopped.
</para>
-@tips_query:
-@caller:
+@tips_query: a #GtkTipsQuery.
+@caller: the widget which initiates the query.
<!-- ##### FUNCTION gtk_tips_query_set_labels ##### -->
<para>
-
+Sets the text to display when the query is not in effect,
+and the text to display when the query is in effect but the widget beneath
+the pointer has no tooltip.
</para>
-@tips_query:
-@label_inactive:
-@label_no_tip:
+@tips_query: a #GtkTipsQuery.
+@label_inactive: the text to display when the query is not running.
+@label_no_tip: the text to display when the query is running but the widget
+beneath the pointer has no tooltip.
<!-- ##### SIGNAL GtkTipsQuery::start-query ##### -->
<para>
-
+Emitted when the query is started.
</para>
@tipsquery: the object which received the signal.
<!-- ##### SIGNAL GtkTipsQuery::stop-query ##### -->
<para>
-
+Emitted when the query is stopped.
</para>
@tipsquery: the object which received the signal.
<!-- ##### SIGNAL GtkTipsQuery::widget-entered ##### -->
<para>
-
+Emitted when a widget is entered by the pointer while the query is in effect.
</para>
@tipsquery: the object which received the signal.
-@widget:
-@tip_text:
-@tip_private:
+@widget: the widget that was entered by the pointer.
+@tip_text: the widget's tooltip.
+@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
<!-- ##### SIGNAL GtkTipsQuery::widget-selected ##### -->
<para>
-
+Emitted when a widget is selected during a query.
</para>
@tipsquery: the object which received the signal.
-@widget:
-@tip_text:
-@tip_private:
-@event:
-@Returns:
+@widget: the widget that was selected.
+@tip_text: the widget's tooltip.
+@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
+@event: the button press or button release event.
+@Returns: TRUE if the query should be stopped.
<!-- ##### ARG GtkTipsQuery:emit_always ##### -->
<para>
-
+TRUE if the widget-entered and widget-selected signals are emitted even when
+the widget has no tooltip set.
</para>
<!-- ##### ARG GtkTipsQuery:caller ##### -->
<para>
-
+The widget that starts the tips query, usually a button.
+If it is selected while the query is in effect the query is automatically
+stopped.
</para>
<!-- ##### ARG GtkTipsQuery:label_inactive ##### -->
<para>
-
+The text to display in the #GtkTipsQuery widget when the query is not in
+effect.
</para>
<!-- ##### ARG GtkTipsQuery:label_no_tip ##### -->
<para>
-
+The text to display in the #GtkTipsQuery widget when the query is running
+and the widget that the pointer is over has no tooltip.
</para>
The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below.
</para>
-@button:
-@active:
-@draw_indicator:
-@event_window:
<!-- ##### FUNCTION gtk_toggle_button_new ##### -->
<para>
<structfield>orientation</structfield>
</para>
-@container:
-@num_children:
-@children:
-@orientation:
-@style:
-@space_size:
-@space_style:
-@tooltips:
-@button_maxw:
-@button_maxh:
-@relief:
<!-- ##### ENUM GtkToolbarChildType ##### -->
<para>
<para>Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members.
</para>
-@data:
-@tip_window:
-@active_tips_data:
-@tips_data_list:
-@gc:
-@foreground:
-@background:
-@delay:
-@enabled:
-@timer_tag:
<!-- ##### STRUCT GtkTooltipsData ##### -->
<para>
</programlisting>
</para>
-@container:
-@children:
-@root_tree:
-@tree_owner:
-@selection:
-@level:
-@indent_value:
-@current_indent:
-@selection_mode:
-@view_mode:
-@view_line:
<!-- ##### MACRO GTK_IS_ROOT_TREE ##### -->
<para>
</para>
-@item:
-@subtree:
-@pixmaps_box:
-@pixmaps:
-@expanded:
<!-- ##### MACRO GTK_TREE_ITEM_SUBTREE ##### -->
<para>
</para>
-@button_box:
<!-- ##### FUNCTION gtk_vbutton_box_new ##### -->
<para>
<!-- ##### STRUCT GtkVBox ##### -->
-@box:
<!-- ##### FUNCTION gtk_vbox_new ##### -->
<para>\r
</para>
-@bin:
-@shadow_type:
-@view_window:
-@bin_window:
-@hadjustment:
-@vadjustment:
<!-- ##### FUNCTION gtk_viewport_new ##### -->
<para>
<para>
</para>
-@paned:
<!-- ##### FUNCTION gtk_vpaned_new ##### -->
<para>
</para>
-
<!-- ##### STRUCT GtkVRuler ##### -->
<para>
The #GtkVRuler struct contains private data and should be accessed
using the functions below.
</para>
-@ruler:
<!-- ##### FUNCTION gtk_vruler_new ##### -->
<para>
should be accessed using the functions below.
</para>
-@scale:
<!-- ##### FUNCTION gtk_vscale_new ##### -->
<para>
</para>
-
<!-- ##### STRUCT GtkVScrollbar ##### -->
<para>
The #GtkVScrollbar struct contains private data and should be accessed
using the functions below.
</para>
-@scrollbar:
<!-- ##### FUNCTION gtk_vscrollbar_new ##### -->
<para>
GtkVSeparator
<!-- ##### SECTION Short_Description ##### -->
-
+a vertical separator.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GtkVSeparator widget is a vertical separator, used to group the
+widgets within a window. It displays a vertical line with a shadow to
+make it appear sunken into the interface.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkHSeparator</term>
+<listitem><para>a horizontal separator.</para></listitem>
+</varlistentry>
+</variablelist>
</para>
<!-- ##### STRUCT GtkVSeparator ##### -->
<para>
-
+The #GtkVSeparator-struct struct contains private data only, and
+should be accessed using the functions below.
</para>
-@separator:
<!-- ##### FUNCTION gtk_vseparator_new ##### -->
<para>
-
+Creates a new #GtkVSeparator.
</para>
-@Returns:
+@Returns: a new #GtkVSeparator.
</para>
-@object:
-@private_flags:
-@state:
-@saved_state:
-@name:
-@style:
-@requisition:
-@allocation:
-@window:
-@parent:
<!-- ##### ENUM GtkWidgetFlags ##### -->
<para>
</para>
-@bin:
-@title:
-@wmclass_name:
-@wmclass_class:
-@type:
-@focus_widget:
-@default_widget:
-@transient_parent:
-@resize_count:
-@allow_shrink:
-@allow_grow:
-@auto_shrink:
-@handling_resize:
-@position:
-@use_uposition:
-@modal:
<!-- ##### FUNCTION gtk_window_new ##### -->
<para>
projects / ~andy / gtk / commitdiff