diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 7f56930c8d..a474648f9b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,55 @@ +1999-09-22 Damon Chaplin + + * 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 + + * 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 + + * gtk/tmpl/gtkmarshal.sgml: + * gtk/tmpl/gtksignal.sgml: new sections from + David Benson . + + * 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 + + * 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 + + * gtk/tmpl/gtkfilesel.sgml: fixed mismatched parentheses. + +1999-09-02 Damon Chaplin + + * gdk/tmpl/event_structs.sgml: + * gdk/tmpl/drawing.sgml: minor fixes. + 1999-09-20 David C. Mason * gtk/tmpl/gtkimage.sgml: first pass at gtkimage... not complete diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml index d57db7b25a..83ab876aa0 100644 --- a/docs/reference/gdk/tmpl/drawing.sgml +++ b/docs/reference/gdk/tmpl/drawing.sgml @@ -160,7 +160,7 @@ the ellipse to be drawn. @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. @@ -184,7 +184,7 @@ Draws a string of characters in the given font or fontset. @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. diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml index 5a4370bc1e..ce5ba37aab 100644 --- a/docs/reference/gdk/tmpl/event_structs.sgml +++ b/docs/reference/gdk/tmpl/event_structs.sgml @@ -94,7 +94,7 @@ Any event can safely be cast to a #GdkEventAny to access these fields. Used for button press and button release events. The type 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. Double and treble-clicks result in a sequence of events being received. @@ -128,7 +128,8 @@ is inserted after the third click. The order of the events is: @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 diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 97afce3121..6042de1911 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -102,14 +102,12 @@ - - @@ -168,7 +166,6 @@ An advanced widget set. - >k-General; >k-Feature-Test-Macros; >k-Graphics-Contexts; @@ -178,18 +175,16 @@ An advanced widget set. >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; - + GTK+ Widgets and Objects &index-Objects-Grouped; diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index 4924885361..fe99b4d45b 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -378,12 +378,12 @@ GTK_COLOR_SELECTION_DIALOG_CLASS GtkCombo GtkCombo 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 GTK_COMBO @@ -2504,23 +2504,6 @@ gtk_drag_dest_handle_event -
-gtkmenufactory -Menu Factory -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 -
-
gtksignal Signals @@ -2529,6 +2512,7 @@ GtkSignalMarshal GtkSignalDestroy GtkEmissionHook GtkSignalQuery +GtkSignalRunType gtk_signal_init gtk_signal_new gtk_signal_newv @@ -2547,8 +2531,8 @@ gtk_signal_connect_after 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 @@ -2573,6 +2557,8 @@ gtk_signal_remove_emission_hook gtkmarshal Signal Marshallers gtk_signal_default_marshaller + + gtk_marshal_BOOL__POINTER_INT_INT_UINT gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER gtk_marshal_ENUM__ENUM @@ -2902,7 +2888,6 @@ GtkCurveType GtkDirectionType GtkJustification GtkMatchType -GtkMenuFactoryType GtkMetricType GtkOrientation GtkPackType @@ -2913,7 +2898,6 @@ GtkPositionType GtkPreviewType GtkReliefStyle GtkResizeMode -GtkSignalRunType GtkScrollType GtkSelectionMode GtkShadowType @@ -2929,14 +2913,6 @@ GtkWindowType GtkSortType
-
-gtkdebug -Debugging -GtkDebugFlag -gtk_debug_flags -GTK_NOTE -
-
gtkprivate Private Information @@ -2952,5 +2928,24 @@ GTK_WIDGET_IN_REPARENT GTK_WIDGET_IS_OFFSCREEN GTK_PRIVATE_SET_FLAG GTK_PRIVATE_UNSET_FLAG + + +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
diff --git a/docs/reference/gtk/objects_grouped.sgml b/docs/reference/gtk/objects_grouped.sgml index da6e073e02..3b546dc9c3 100644 --- a/docs/reference/gtk/objects_grouped.sgml +++ b/docs/reference/gtk/objects_grouped.sgml @@ -30,7 +30,6 @@ GtkViewport GtkEventBox GtkAlignment - GtkInvisible GtkHButtonBox GtkVButtonBox GtkHPaned @@ -125,6 +124,7 @@ Misc. Objects GtkAdjustment GtkItemFactory + GtkInvisible diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 3e32cdde96..8cd00ccc29 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -1,3 +1,209 @@ + +Menu Factory + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@path: +@type: +@accel_group: +@widget: +@subfactories: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@factory: +@path: +@Returns: + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@GTK_MENU_FACTORY_MENU: +@GTK_MENU_FACTORY_MENU_BAR: +@GTK_MENU_FACTORY_OPTION_MENU: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@factory: +@entries: +@nentries: + + + + + + +@path: +@widget: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + Determines the way that the the preview widget behaves @@ -6,6 +212,215 @@ size. See gtk_preview_set_expand(). + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@factory: +@paths: +@npaths: + + + + + + +@factory: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@type: +@action: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@GTK_DEBUG_OBJECTS: +@GTK_DEBUG_MISC: +@GTK_DEBUG_SIGNALS: +@GTK_DEBUG_DND: +@GTK_DEBUG_PLUGSOCKET: + Determines the snap edge of a handlebox. The snap edge is @@ -22,3 +437,193 @@ Determines the side of the handlebox where the handle is drawn. + + + + + + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@type: +@Returns: + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@factory: +@entries: +@nentries: + + + + + + + + + + + + +@widget: +@user_data: + + + + + + + + + + + + +@factory: +@subfactory: +@path: + + +Debugging + + + + + + + +@ruler: the gtkruler + + + + + + + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@factory: +@subfactory: +@path: + + + + + + +@path: +@accelerator: +@callback: +@callback_data: +@widget: + + + + + + +@ruler: the gtkruler + + + + + + + diff --git a/docs/reference/gtk/tmpl/gtkaccellabel.sgml b/docs/reference/gtk/tmpl/gtkaccellabel.sgml index bd1c8c05a4..7676b5c705 100644 --- a/docs/reference/gtk/tmpl/gtkaccellabel.sgml +++ b/docs/reference/gtk/tmpl/gtkaccellabel.sgml @@ -2,68 +2,131 @@ GtkAccelLabel - +a label which displays an accelerator key on the right of the text. - +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. + +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(). + + +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. + + +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. + + +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. + + + +Creating a simple menu item with an accelerator key. + + 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); + + + + +Keyboard Accelerators + +installing and using keyboard short-cuts. + + + +#GtkItemFactory +an easier way to create menus. + + + - +The #GtkAccelLabel-struct struct contains private data only, and +should be accessed using the functions below. -@label: -@queue_id: -@accel_padding: -@accel_widget: -@accel_string: -@accel_string_width: - +Creates a new #GtkAccelLabel. -@string: -@Returns: +@string: the label string. +@Returns: a new #GtkAccelLabel. - +Sets the widget whose accelerators are to be shown. -@accel_label: -@accel_widget: +@accel_label: a #GtkAccelLabel. +@accel_widget: the widget whose accelerators are to be displayed. - +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. -@accel_label: +@accel_label: a #GtkAccelLabel. @Returns: - +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. -@accel_label: -@Returns: +@accel_label: a #GtkAccelLabel. +@Returns: always returns FALSE. - +The widget whose accelerators are to be shown by the #GtkAccelLabel. diff --git a/docs/reference/gtk/tmpl/gtkadjustment.sgml b/docs/reference/gtk/tmpl/gtkadjustment.sgml index 4d8540ad42..bef7149651 100644 --- a/docs/reference/gtk/tmpl/gtkadjustment.sgml +++ b/docs/reference/gtk/tmpl/gtkadjustment.sgml @@ -78,13 +78,6 @@ In a #GtkScrollbar this is the size of the area which is currently visible. -@data: -@lower: -@upper: -@value: -@step_increment: -@page_increment: -@page_size: diff --git a/docs/reference/gtk/tmpl/gtkalignment.sgml b/docs/reference/gtk/tmpl/gtkalignment.sgml index 5a2b5b51a8..39338e9bb0 100644 --- a/docs/reference/gtk/tmpl/gtkalignment.sgml +++ b/docs/reference/gtk/tmpl/gtkalignment.sgml @@ -33,11 +33,6 @@ The #GtkAlignment-struct struct contains private data only, and should be accessed using the functions below. -@bin: -@xalign: -@yalign: -@xscale: -@yscale: diff --git a/docs/reference/gtk/tmpl/gtkarrow.sgml b/docs/reference/gtk/tmpl/gtkarrow.sgml index 4aef9526a0..dd3eaf25bb 100644 --- a/docs/reference/gtk/tmpl/gtkarrow.sgml +++ b/docs/reference/gtk/tmpl/gtkarrow.sgml @@ -56,9 +56,6 @@ an application.) -@misc: -@arrow_type: -@shadow_type: diff --git a/docs/reference/gtk/tmpl/gtkaspectframe.sgml b/docs/reference/gtk/tmpl/gtkaspectframe.sgml index 868a488684..4abe32b7c7 100644 --- a/docs/reference/gtk/tmpl/gtkaspectframe.sgml +++ b/docs/reference/gtk/tmpl/gtkaspectframe.sgml @@ -25,12 +25,6 @@ a frame around the child. The frame will be -@frame: -@xalign: -@yalign: -@ratio: -@obey_child: -@center_allocation: diff --git a/docs/reference/gtk/tmpl/gtkbbox.sgml b/docs/reference/gtk/tmpl/gtkbbox.sgml index 4d77c5b258..a73be12568 100644 --- a/docs/reference/gtk/tmpl/gtkbbox.sgml +++ b/docs/reference/gtk/tmpl/gtkbbox.sgml @@ -1,10 +1,10 @@ - -GtkButtonBox - - -Base class for #GtkHButtonBox and #GtkVButtonBox - - + +GtkButtonBox + + +Base class for #GtkHButtonBox and #GtkVButtonBox + + The primary purpose of this class is to keep track of the various properties of #GtkHButtonBox and #GtkVButtonBox widgets. @@ -41,9 +41,9 @@ used to spread the buttons in a button box across the container, respectively. - - - + + + @@ -55,141 +55,148 @@ used to spread the buttons in a button box across the container, respectively. Horizontal sub-class of #GtkButtonBox. - - - + + + This is a read-only struct; no members should be modified directly. - - - - + + + + Used internally only. - - - - - + + + + + Retrieves the default minimum width and height for all button boxes, and places the values in @min_width and @min_height, respectively. - - -@min_width: the default minimum width of a child widget. -@min_height: the default minimum height of a child widget. - - - + + +@min_width: the default minimum width of a child widget. +@min_height: the default minimum height of a child widget. + + + The internal padding of a button is the amount of space between the outside of the button and the widget it contains. This function gets the default amount of horizontal and vertical padding, placing the results in @ipad_x and @ipad_y, respectively. - - -@ipad_x: the default horizontal internal button padding. -@ipad_y: the default vertical internal button padding. - - - + + +@ipad_x: the default horizontal internal button padding. +@ipad_y: the default vertical internal button padding. + + + Sets the default size of child buttons. - - -@min_width: minimum default width for child buttons. -@min_height: minimum default height for child buttons. - - - + + +@min_width: minimum default width for child buttons. +@min_height: minimum default height for child buttons. + + + Sets the default number of pixels that pad each button in every button box. - - -@ipad_x: new default horizontal padding. -@ipad_y: new default vertical padding. - - - + + +@ipad_x: new default horizontal padding. +@ipad_y: new default vertical padding. + + + Retrieves how much space a button box is placing between each child button. - - -@widget: a #GtkButtonBox. -@Returns: the current spacing applied to the buttons in @widget. - - - + + +@widget: a #GtkButtonBox. +@Returns: the current spacing applied to the buttons in @widget. + + + Retrieves the method being used to arrange the buttons in a button box. - - -@widget: a #GtkButtonBox. -@Returns: the method used to layout buttons in @widget. - - - + + +@widget: a #GtkButtonBox. +@Returns: the method used to layout buttons in @widget. + + + Retrieves the current width and height of all child widgets in a button box. @min_width and @min_height are filled with those values, respectively. - - -@widget: a #GtkButtonBox. -@min_width: the width of the buttons contained by @widget. -@min_height: the height of the buttons contained by @widget. - - - + + +@widget: a #GtkButtonBox. +@min_width: the width of the buttons contained by @widget. +@min_height: the height of the buttons contained by @widget. + + + Gets the default number of pixels that pad the buttons in a given button box. - - -@widget: a #GtkButtonBox. -@ipad_x: the horizontal padding used by buttons in @widget. -@ipad_y: the vertical padding used by buttons in @widget. - - - + + +@widget: a #GtkButtonBox. +@ipad_x: the horizontal padding used by buttons in @widget. +@ipad_y: the vertical padding used by buttons in @widget. + + + Sets the amount of spacing between buttons in a given button box. - - -@widget: a #GtkButtonBox. -@spacing: the number of pixels of spacing. - - - + + +@widget: a #GtkButtonBox. +@spacing: the number of pixels of spacing. + + + Changes the way buttons are arranged in their container. - - -@widget: a #GtkButtonBox. -@layout_style: the new layout style. - - - + + +@widget: a #GtkButtonBox. +@layout_style: the new layout style. + + + Sets a new default size for the children of a given button box. - - -@widget: a #GtkButtonBox. -@min_width: a default width for buttons in @widget. -@min_height: a default height for buttons in @widget. - - - + + +@widget: a #GtkButtonBox. +@min_width: a default width for buttons in @widget. +@min_height: a default height for buttons in @widget. + + + Changes the amount of internal padding used by all buttons in a given button box. - - -@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. - - - + + +@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. + + + This is an internally used function and should never be called from an application. - + + +@widget: +@nvis_children: +@width: +@height: + + diff --git a/docs/reference/gtk/tmpl/gtkbin.sgml b/docs/reference/gtk/tmpl/gtkbin.sgml index 1aa48ce5a2..400fc8e2b7 100644 --- a/docs/reference/gtk/tmpl/gtkbin.sgml +++ b/docs/reference/gtk/tmpl/gtkbin.sgml @@ -39,6 +39,4 @@ an application.) -@container: -@child: diff --git a/docs/reference/gtk/tmpl/gtkbox.sgml b/docs/reference/gtk/tmpl/gtkbox.sgml index 191b7a963d..442da31201 100644 --- a/docs/reference/gtk/tmpl/gtkbox.sgml +++ b/docs/reference/gtk/tmpl/gtkbox.sgml @@ -131,10 +131,6 @@ field. -@container: -@children: -@spacing: -@homogeneous: diff --git a/docs/reference/gtk/tmpl/gtkbutton.sgml b/docs/reference/gtk/tmpl/gtkbutton.sgml index 32a88b5c4a..7438cf40c7 100644 --- a/docs/reference/gtk/tmpl/gtkbutton.sgml +++ b/docs/reference/gtk/tmpl/gtkbutton.sgml @@ -26,11 +26,6 @@ the #GtkLabel. This should not be accessed directly. Use the accessor functions below. -@bin: -@child: -@in_button: -@button_down: -@relief: diff --git a/docs/reference/gtk/tmpl/gtkcalendar.sgml b/docs/reference/gtk/tmpl/gtkcalendar.sgml index 4ca84c2837..b7bc326498 100644 --- a/docs/reference/gtk/tmpl/gtkcalendar.sgml +++ b/docs/reference/gtk/tmpl/gtkcalendar.sgml @@ -57,26 +57,6 @@ All of these fields should be considered read only, and everything in this struct should only be modified using the functions provided below. -@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: diff --git a/docs/reference/gtk/tmpl/gtkcheckbutton.sgml b/docs/reference/gtk/tmpl/gtkcheckbutton.sgml index bdbbbf7ab3..cf2929b1d6 100644 --- a/docs/reference/gtk/tmpl/gtkcheckbutton.sgml +++ b/docs/reference/gtk/tmpl/gtkcheckbutton.sgml @@ -39,7 +39,6 @@ The important signal ('toggled') is also inherited from #GtkToggleButton. toggle_button is a #GtkToggleButton representing the actual toggle button that composes the check button. -@toggle_button: diff --git a/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml b/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml index 451e0cf7ac..0cbac1879e 100644 --- a/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml +++ b/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml @@ -40,9 +40,6 @@ an application.) -@menu_item: -@active: -@always_show_toggle: diff --git a/docs/reference/gtk/tmpl/gtkclist.sgml b/docs/reference/gtk/tmpl/gtkclist.sgml index 6c6d8a4a2e..0c5263ce87 100644 --- a/docs/reference/gtk/tmpl/gtkclist.sgml +++ b/docs/reference/gtk/tmpl/gtkclist.sgml @@ -19,52 +19,6 @@ GtkCList -@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: diff --git a/docs/reference/gtk/tmpl/gtkcolorsel.sgml b/docs/reference/gtk/tmpl/gtkcolorsel.sgml index 819a072de3..e6e059f914 100644 --- a/docs/reference/gtk/tmpl/gtkcolorsel.sgml +++ b/docs/reference/gtk/tmpl/gtkcolorsel.sgml @@ -19,26 +19,6 @@ GtkColorSelection -@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: diff --git a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml index 2dc847a654..8a2f819634 100644 --- a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml +++ b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml @@ -19,13 +19,6 @@ GtkColorSelectionDialog -@window: -@colorsel: -@main_vbox: -@ok_button: -@reset_button: -@cancel_button: -@help_button: diff --git a/docs/reference/gtk/tmpl/gtkcombo.sgml b/docs/reference/gtk/tmpl/gtkcombo.sgml index ce8e542db2..7113bbe6e4 100644 --- a/docs/reference/gtk/tmpl/gtkcombo.sgml +++ b/docs/reference/gtk/tmpl/gtkcombo.sgml @@ -2,12 +2,86 @@ GtkCombo - +a text entry field with a dropdown list. - +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. + +The drop-down list is a #GtkList widget and can be accessed using the +list 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. + + +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(). + + +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. + + + +Creating a #GtkCombo widget with simple text items. + + 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); + + + + +Creating a #GtkCombo widget with a complex item. + + 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); + + @@ -16,94 +90,115 @@ GtkCombo +The #GtkFixedChild-struct struct contains the following fields. +(These fields should be considered read-only. They should never be set by +an application.) + + + + + +#GtkWidget *entry; +the text entry field. + + + +#GtkWidget *list; +the list shown in the drop-down window. + + + -@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: - +Creates a new #GtkCombo. -@Returns: +@Returns: a new #GtkCombo. + + + + +Convenience function to set all of the items in the popup list. +(See the example above.) + + +@combo: a #GtkCombo. +@strings: a list of strings. - +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. + + +If an empty field is acceptable, the @ok_if_empty parameter should be TRUE. -@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. - +Specifies if the arrow (cursor) keys can be used to step through the items in +the list. This is on by default. -@combo: -@val: +@combo: a #GtkCombo. +@val: TRUE if the arrow keys can be used to step through the items in the list. - +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. -@combo: +@combo: a #GtkCombo. @val: - +Specifies whether the text entered into the #GtkEntry field and the text in +the list items is case sensitive. + + +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. -@combo: +@combo: a #GtkCombo. @val: - +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. -@combo: -@item: -@item_value: - - - - - - - -@combo: -@strings: +@combo: a #GtkCombo. +@item: a #GtkItem which +@item_value: the string to place in the #GtkEntry when @item is selected. - +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. -@combo: +@combo: a #GtkCombo. diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml index 3786dce30c..d6782383c4 100644 --- a/docs/reference/gtk/tmpl/gtkcontainer.sgml +++ b/docs/reference/gtk/tmpl/gtkcontainer.sgml @@ -19,12 +19,6 @@ GtkContainer -@widget: -@focus_child: -@border_width: -@need_resize: -@resize_mode: -@resize_widgets: diff --git a/docs/reference/gtk/tmpl/gtkctree.sgml b/docs/reference/gtk/tmpl/gtkctree.sgml index 32de3679e4..1979f30d3b 100644 --- a/docs/reference/gtk/tmpl/gtkctree.sgml +++ b/docs/reference/gtk/tmpl/gtkctree.sgml @@ -74,15 +74,6 @@ node. -@clist: -@lines_gc: -@tree_indent: -@tree_spacing: -@tree_column: -@line_style: -@expander_style: -@show_stub: -@drag_compare: diff --git a/docs/reference/gtk/tmpl/gtkcurve.sgml b/docs/reference/gtk/tmpl/gtkcurve.sgml index b8119415b4..a056d270d7 100644 --- a/docs/reference/gtk/tmpl/gtkcurve.sgml +++ b/docs/reference/gtk/tmpl/gtkcurve.sgml @@ -2,107 +2,123 @@ GtkCurve - +allows direct editing of a curve. - +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. + + +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. + + +#GtkGammaCurve +a subclass for editing gamma curves. + + + - +The #GtkCurve-struct struct contains private data only, and +should be accessed using the functions below. -@graph: -@cursor_type: -@min_x: -@max_x: -@min_y: -@max_y: -@pixmap: -@curve_type: -@height: -@grab_point: -@last: -@num_points: -@point: -@num_ctlpoints: - +Creates a new #GtkCurve. -@Returns: +@Returns: a new #GtkCurve. - +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. -@curve: +@curve: a #GtkCurve. - +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. -@curve: -@gamma: +@curve: a #GtkCurve. +@gamma: the gamma value. - +Sets the minimum and maximum x & y values of the curve. +The curve is also reset with a call to gtk_curve_reset(). -@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. - +Returns a vector of points representing the curve. -@curve: -@veclen: -@vector: +@curve: a #GtkCurve. +@veclen: the number of points to calculate. +@vector: returns the points. - +Sets the vector of points on the curve. +The curve type is set to %GTK_CURVE_TYPE_FREE. -@curve: -@veclen: -@vector: +@curve: a #GtkCurve. +@veclen: the number of points. +@vector: the points on the curve. - +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. -@curve: -@type: +@curve: a #GtkCurve. +@type: the type of the curve. - +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(). @curve: the object which received the signal. diff --git a/docs/reference/gtk/tmpl/gtkdata.sgml b/docs/reference/gtk/tmpl/gtkdata.sgml index 2da64638d0..e24459d5d2 100644 --- a/docs/reference/gtk/tmpl/gtkdata.sgml +++ b/docs/reference/gtk/tmpl/gtkdata.sgml @@ -2,11 +2,19 @@ GtkData - +abstract base class for objects containing data. - +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). + + +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. @@ -16,14 +24,14 @@ GtkData - +The #GtkData-struct struct contains no public fields. -@object: - +Emitted to notify any views on the #GtkData object to disconnect from it, +possibly because the #GtkData object is about to be destroyed. @data: the object which received the signal. diff --git a/docs/reference/gtk/tmpl/gtkdialog.sgml b/docs/reference/gtk/tmpl/gtkdialog.sgml index 2ce5355409..9c0b709470 100644 --- a/docs/reference/gtk/tmpl/gtkdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkdialog.sgml @@ -101,9 +101,6 @@ gtk_window_set_title(). See the #GtkWindow section for more). action_area is a #GtkHBox packed below the dividing #GtkHSeparator in the dialog. It is treated exactly the same as any other #GtkHBox. -@window: -@vbox: -@action_area: diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml index cc9800dec9..94cf07e042 100644 --- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml +++ b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml @@ -85,8 +85,6 @@ The #GtkDrawingArea-struct struct contains private data only, and should be accessed using the functions below. -@widget: -@draw_data: diff --git a/docs/reference/gtk/tmpl/gtkeditable.sgml b/docs/reference/gtk/tmpl/gtkeditable.sgml index f822b3bfe0..0d292c9e50 100644 --- a/docs/reference/gtk/tmpl/gtkeditable.sgml +++ b/docs/reference/gtk/tmpl/gtkeditable.sgml @@ -91,16 +91,10 @@ editable by the user. -@widget: @current_pos: @selection_start_pos: @selection_end_pos: @has_selection: -@editable: -@visible: -@ic: -@ic_attr: -@clipboard_text: diff --git a/docs/reference/gtk/tmpl/gtkentry.sgml b/docs/reference/gtk/tmpl/gtkentry.sgml index 0552539a33..73d3b22735 100644 --- a/docs/reference/gtk/tmpl/gtkentry.sgml +++ b/docs/reference/gtk/tmpl/gtkentry.sgml @@ -30,22 +30,6 @@ position is visible. The #GtkEntry-struct struct contains only private data. -@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: diff --git a/docs/reference/gtk/tmpl/gtkenums.sgml b/docs/reference/gtk/tmpl/gtkenums.sgml index 5b8b1ede8f..33ffe7f812 100644 --- a/docs/reference/gtk/tmpl/gtkenums.sgml +++ b/docs/reference/gtk/tmpl/gtkenums.sgml @@ -107,15 +107,6 @@ Standard Enumerations @GTK_MATCH_EXACT: @GTK_MATCH_LAST: - - - - - -@GTK_MENU_FACTORY_MENU: -@GTK_MENU_FACTORY_MENU_BAR: -@GTK_MENU_FACTORY_OPTION_MENU: - @@ -224,18 +215,6 @@ contains grayscale or red-green-blue data. @GTK_RESIZE_QUEUE: @GTK_RESIZE_IMMEDIATE: - - - - - -@GTK_RUN_FIRST: -@GTK_RUN_LAST: -@GTK_RUN_BOTH: -@GTK_RUN_NO_RECURSE: -@GTK_RUN_ACTION: -@GTK_RUN_NO_HOOKS: - diff --git a/docs/reference/gtk/tmpl/gtkeventbox.sgml b/docs/reference/gtk/tmpl/gtkeventbox.sgml index 463a9f9963..8dc8fbcd93 100644 --- a/docs/reference/gtk/tmpl/gtkeventbox.sgml +++ b/docs/reference/gtk/tmpl/gtkeventbox.sgml @@ -22,7 +22,6 @@ The #GtkEventBox-struct struct contains private data only, and should be accessed using the functions below. -@bin: diff --git a/docs/reference/gtk/tmpl/gtkfeatures.sgml b/docs/reference/gtk/tmpl/gtkfeatures.sgml index bf85207886..b1d62c4771 100644 --- a/docs/reference/gtk/tmpl/gtkfeatures.sgml +++ b/docs/reference/gtk/tmpl/gtkfeatures.sgml @@ -1,12 +1,14 @@ -Feature Test Macros +Version Information - +variables and functions to check the GTK+ version. - +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. @@ -16,19 +18,22 @@ Feature Test Macros - +The major version number of the GTK+ library. +(e.g. in GTK+ version 1.2.5 this is 1.) - +The minor version number of the GTK+ library. +(e.g. in GTK+ version 1.2.5 this is 2.) - +The micro version number of the GTK+ library. +(e.g. in GTK+ version 1.2.5 this is 5.) @@ -46,12 +51,13 @@ Feature Test Macros - +Checks that the GTK+ library in use is compatable with the given version. -@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. diff --git a/docs/reference/gtk/tmpl/gtkfilesel.sgml b/docs/reference/gtk/tmpl/gtkfilesel.sgml index 6a36d803b2..9ac71c75c9 100644 --- a/docs/reference/gtk/tmpl/gtkfilesel.sgml +++ b/docs/reference/gtk/tmpl/gtkfilesel.sgml @@ -40,16 +40,16 @@ void create_file_selection(void) { 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); @@ -110,27 +110,6 @@ The #GtkFileSelection struct contains the following #GtkWidget fields: -@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: diff --git a/docs/reference/gtk/tmpl/gtkfixed.sgml b/docs/reference/gtk/tmpl/gtkfixed.sgml index 20f6c085a9..c72b4e743c 100644 --- a/docs/reference/gtk/tmpl/gtkfixed.sgml +++ b/docs/reference/gtk/tmpl/gtkfixed.sgml @@ -35,8 +35,6 @@ their positions. -@container: -@children: diff --git a/docs/reference/gtk/tmpl/gtkfontsel.sgml b/docs/reference/gtk/tmpl/gtkfontsel.sgml index caf3f88471..d888b18f10 100644 --- a/docs/reference/gtk/tmpl/gtkfontsel.sgml +++ b/docs/reference/gtk/tmpl/gtkfontsel.sgml @@ -51,37 +51,6 @@ The #GtkFontSelection struct contains private data only, and should only be accessed using the functions below. -@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: diff --git a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml index 8c32d89a27..03d6b7b1fc 100644 --- a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml +++ b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml @@ -71,15 +71,6 @@ The #GtkFontSelectionDialog struct contains private data only, and should only be accessed using the functions below. -@window: -@fontsel: -@main_vbox: -@action_area: -@ok_button: -@apply_button: -@cancel_button: -@dialog_width: -@auto_resize: diff --git a/docs/reference/gtk/tmpl/gtkframe.sgml b/docs/reference/gtk/tmpl/gtkframe.sgml index 492ceefc31..a675fc909b 100644 --- a/docs/reference/gtk/tmpl/gtkframe.sgml +++ b/docs/reference/gtk/tmpl/gtkframe.sgml @@ -23,13 +23,6 @@ label can be controlled with gtk_frame_set_label_align(). -@bin: -@label: -@shadow_type: -@label_width: -@label_height: -@label_xalign: -@label_yalign: diff --git a/docs/reference/gtk/tmpl/gtkgamma.sgml b/docs/reference/gtk/tmpl/gtkgamma.sgml index 114c74548a..28f392d5c1 100644 --- a/docs/reference/gtk/tmpl/gtkgamma.sgml +++ b/docs/reference/gtk/tmpl/gtkgamma.sgml @@ -2,11 +2,20 @@ GtkGammaCurve - +a subclass of #GtkCurve for editing gamma curves. - +The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for +editing gamma curves, which are used in graphics applications such as the +Gimp. + + +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. @@ -16,22 +25,16 @@ GtkGammaCurve - +The #GtkGammaCurve-struct struct contains private data only, and +should be accessed using the functions below. -@vbox: -@table: -@curve: -@button: -@gamma: -@gamma_dialog: -@gamma_text: - +Creates a new #GtkGammaCurve. -@Returns: +@Returns: a new #GtkGammaCurve. diff --git a/docs/reference/gtk/tmpl/gtkgc.sgml b/docs/reference/gtk/tmpl/gtkgc.sgml index e1cd99b423..7304c49122 100644 --- a/docs/reference/gtk/tmpl/gtkgc.sgml +++ b/docs/reference/gtk/tmpl/gtkgc.sgml @@ -2,11 +2,15 @@ Graphics Contexts - +provides access to a shared pool of #GdkGC objects. - +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. @@ -16,21 +20,26 @@ Graphics Contexts - +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. -@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. - +Releases a #GdkGC allocated using gtk_gc_get(). -@gc: +@gc: a #GdkGC. diff --git a/docs/reference/gtk/tmpl/gtkhandlebox.sgml b/docs/reference/gtk/tmpl/gtkhandlebox.sgml index 4257f5876c..e823a7a563 100644 --- a/docs/reference/gtk/tmpl/gtkhandlebox.sgml +++ b/docs/reference/gtk/tmpl/gtkhandlebox.sgml @@ -76,20 +76,6 @@ child is attached or detached. -@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: diff --git a/docs/reference/gtk/tmpl/gtkhbbox.sgml b/docs/reference/gtk/tmpl/gtkhbbox.sgml index 0a67e4445d..889f2cf039 100644 --- a/docs/reference/gtk/tmpl/gtkhbbox.sgml +++ b/docs/reference/gtk/tmpl/gtkhbbox.sgml @@ -53,7 +53,6 @@ gtk_hbutton_box_get_layout_default(). should not be modified directly. -@button_box: diff --git a/docs/reference/gtk/tmpl/gtkhbox.sgml b/docs/reference/gtk/tmpl/gtkhbox.sgml index 0fd5acff22..2259380f1b 100644 --- a/docs/reference/gtk/tmpl/gtkhbox.sgml +++ b/docs/reference/gtk/tmpl/gtkhbox.sgml @@ -33,7 +33,6 @@ All children are allocated the same height. -@box: diff --git a/docs/reference/gtk/tmpl/gtkhpaned.sgml b/docs/reference/gtk/tmpl/gtkhpaned.sgml index 369a0beaf3..19f42a4101 100644 --- a/docs/reference/gtk/tmpl/gtkhpaned.sgml +++ b/docs/reference/gtk/tmpl/gtkhpaned.sgml @@ -21,7 +21,6 @@ a handle. See #GtkPaned for details. -@paned: diff --git a/docs/reference/gtk/tmpl/gtkhruler.sgml b/docs/reference/gtk/tmpl/gtkhruler.sgml index 21658d405b..e6ceadc291 100644 --- a/docs/reference/gtk/tmpl/gtkhruler.sgml +++ b/docs/reference/gtk/tmpl/gtkhruler.sgml @@ -19,14 +19,12 @@ rulers. - The #GtkHRuler struct contains private data and should be accessed with the functions below. -@ruler: diff --git a/docs/reference/gtk/tmpl/gtkhscale.sgml b/docs/reference/gtk/tmpl/gtkhscale.sgml index 9c9803d84b..e23b095834 100644 --- a/docs/reference/gtk/tmpl/gtkhscale.sgml +++ b/docs/reference/gtk/tmpl/gtkhscale.sgml @@ -27,7 +27,6 @@ The #GtkHScale-struct struct contains private data only, and should be accessed using the functions below. -@scale: diff --git a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml index fa0a60b6a9..5317f3eae9 100644 --- a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml +++ b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml @@ -17,14 +17,12 @@ case one will be created you. See #GtkAdjustment for details. - The #GtkHScrollbar struct contains private data and should be accessed unsing the functions below. -@scrollbar: diff --git a/docs/reference/gtk/tmpl/gtkhseparator.sgml b/docs/reference/gtk/tmpl/gtkhseparator.sgml index 4c3dc810d3..6eaa96a747 100644 --- a/docs/reference/gtk/tmpl/gtkhseparator.sgml +++ b/docs/reference/gtk/tmpl/gtkhseparator.sgml @@ -2,30 +2,44 @@ GtkHSeparator - +a horizontal separator. - +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. + + +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(). + + - + + +#GtkVSeparator +a vertical separator. + + - +The #GtkHSeparator-struct struct contains private data only, and +should be accessed using the functions below. -@separator: - +Creates a new #GtkHSeparator. -@Returns: +@Returns: a new #GtkHSeparator. diff --git a/docs/reference/gtk/tmpl/gtkimage.sgml b/docs/reference/gtk/tmpl/gtkimage.sgml index 1934acf483..c9ba6f1a37 100644 --- a/docs/reference/gtk/tmpl/gtkimage.sgml +++ b/docs/reference/gtk/tmpl/gtkimage.sgml @@ -27,9 +27,6 @@ This struct contain private data only and should be accessed by the functions below. -@misc: -@image: -@mask: diff --git a/docs/reference/gtk/tmpl/gtkinputdialog.sgml b/docs/reference/gtk/tmpl/gtkinputdialog.sgml index 065889214a..691cd1e5a5 100644 --- a/docs/reference/gtk/tmpl/gtkinputdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkinputdialog.sgml @@ -32,16 +32,6 @@ immediately. -@dialog: -@axis_list: -@axis_listbox: -@mode_optionmenu: -@close_button: -@save_button: -@axis_items: -@current_device: -@keys_list: -@keys_listbox: diff --git a/docs/reference/gtk/tmpl/gtkinvisible.sgml b/docs/reference/gtk/tmpl/gtkinvisible.sgml index 692e4138c9..50d2f76aab 100644 --- a/docs/reference/gtk/tmpl/gtkinvisible.sgml +++ b/docs/reference/gtk/tmpl/gtkinvisible.sgml @@ -2,11 +2,16 @@ GtkInvisible - +internally-used widget which is not displayed. - +The #GtkInvisible widget is used internally in GTK+, and is probably not useful +for application developers. + + +It is used for reliable pointer grabs and selection handling in the code +for drag-and-drop. @@ -16,16 +21,15 @@ GtkInvisible - +The #GtkInvisible-struct struct contains no public fields. -@bin: - +Creates a new #GtkInvisible. -@Returns: +@Returns: a new #GtkInvisible. diff --git a/docs/reference/gtk/tmpl/gtkitem.sgml b/docs/reference/gtk/tmpl/gtkitem.sgml index 42461654d4..eec61acc59 100644 --- a/docs/reference/gtk/tmpl/gtkitem.sgml +++ b/docs/reference/gtk/tmpl/gtkitem.sgml @@ -2,11 +2,12 @@ GtkItem - +abstract base class for #GtkMenuItem, #GtkListItem and #GtkTreeItem. - +The #GtkItem widget is an abstract base class for #GtkMenuItem, #GtkListItem +and #GtkTreeItem. @@ -16,52 +17,52 @@ GtkItem - +The #GtkItem-struct struct contains private data only, and +should be accessed using the functions below. -@bin: - +Emits the "select" signal on the given item. -@item: +@item: a #GtkItem. - +Emits the "deselect" signal on the given item. -@item: +@item: a #GtkItem. - +Emits the "toggle" signal on the given item. -@item: +@item: a #GtkItem. - +Emitted when the item is selected. @item: the object which received the signal. - +Emitted when the item is deselected. @item: the object which received the signal. - +Emitted when the item is toggled. @item: the object which received the signal. diff --git a/docs/reference/gtk/tmpl/gtkitemfactory.sgml b/docs/reference/gtk/tmpl/gtkitemfactory.sgml index 9eb4b7a368..bbe4ac0fec 100644 --- a/docs/reference/gtk/tmpl/gtkitemfactory.sgml +++ b/docs/reference/gtk/tmpl/gtkitemfactory.sgml @@ -19,14 +19,6 @@ GtkItemFactory -@object: -@path: -@accel_group: -@widget: -@items: -@translate_func: -@translate_data: -@translate_notify: diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml index 6d5c308352..5511322ca8 100644 --- a/docs/reference/gtk/tmpl/gtklabel.sgml +++ b/docs/reference/gtk/tmpl/gtklabel.sgml @@ -23,14 +23,6 @@ This should not be accessed directly. Use the accessor functions as described below. -@misc: -@label: -@label_wc: -@pattern: -@words: -@max_width: -@jtype: -@wrap: diff --git a/docs/reference/gtk/tmpl/gtklayout.sgml b/docs/reference/gtk/tmpl/gtklayout.sgml index dc058a3e6d..ded7a594cc 100644 --- a/docs/reference/gtk/tmpl/gtklayout.sgml +++ b/docs/reference/gtk/tmpl/gtklayout.sgml @@ -19,20 +19,6 @@ GtkLayout -@container: -@children: -@width: -@height: -@xoffset: -@yoffset: -@hadjustment: -@vadjustment: -@bin_window: -@visibility: -@configure_serial: -@scroll_x: -@scroll_y: -@freeze_count: diff --git a/docs/reference/gtk/tmpl/gtklist.sgml b/docs/reference/gtk/tmpl/gtklist.sgml index a640713ca3..5b50f0de66 100644 --- a/docs/reference/gtk/tmpl/gtklist.sgml +++ b/docs/reference/gtk/tmpl/gtklist.sgml @@ -19,21 +19,6 @@ GtkList -@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: diff --git a/docs/reference/gtk/tmpl/gtklistitem.sgml b/docs/reference/gtk/tmpl/gtklistitem.sgml index f4b7585568..f2e778412e 100644 --- a/docs/reference/gtk/tmpl/gtklistitem.sgml +++ b/docs/reference/gtk/tmpl/gtklistitem.sgml @@ -19,7 +19,6 @@ GtkListItem -@item: diff --git a/docs/reference/gtk/tmpl/gtkmarshal.sgml b/docs/reference/gtk/tmpl/gtkmarshal.sgml index 288a5cb459..92d29caf1b 100644 --- a/docs/reference/gtk/tmpl/gtkmarshal.sgml +++ b/docs/reference/gtk/tmpl/gtkmarshal.sgml @@ -2,481 +2,89 @@ Signal Marshallers - +Functions to adapt C structures to native calling convention. + +What are Signal Marshallers? +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.... + + +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. + + +So the function named: + +gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*); + +will call the #GtkSignalFunc assuming it was a function with signature: + +gboolean sigfunc(gpointer,gint,gint,guint); + + + + +Writing Custom Marshals + +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. + + +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: + +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); +} + + + +#GtkSignal +The signal handling functions (of which marshallers are +really an implementation detail). + + + - +A marshaller that returns void and takes no extra parameters. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - -@object: -@func: -@func_data: -@args: - - diff --git a/docs/reference/gtk/tmpl/gtkmenu.sgml b/docs/reference/gtk/tmpl/gtkmenu.sgml index 7411912cbc..8e3a4a48a5 100644 --- a/docs/reference/gtk/tmpl/gtkmenu.sgml +++ b/docs/reference/gtk/tmpl/gtkmenu.sgml @@ -82,15 +82,6 @@ The #GtkMenu-struct struct contains private data only, and should be accessed using the functions below. -@menu_shell: -@parent_menu_item: -@old_active_menu_item: -@accel_group: -@position_func: -@position_func_data: -@toplevel: -@tearoff_window: -@torn_off: diff --git a/docs/reference/gtk/tmpl/gtkmenubar.sgml b/docs/reference/gtk/tmpl/gtkmenubar.sgml index 384affdc56..c1c63280ed 100644 --- a/docs/reference/gtk/tmpl/gtkmenubar.sgml +++ b/docs/reference/gtk/tmpl/gtkmenubar.sgml @@ -19,9 +19,6 @@ The #GtkMenuBar is a subclass of #GtkMenuShell which contains one to many #GtkMe The #GtkMenuBar struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.) -@menu_shell: the #GtkMenuShell container -@shadow_type: the GtkShadowType to use - Creates the new #GtkMenuBar diff --git a/docs/reference/gtk/tmpl/gtkmenuitem.sgml b/docs/reference/gtk/tmpl/gtkmenuitem.sgml index 2eed9a2436..e75da30f74 100644 --- a/docs/reference/gtk/tmpl/gtkmenuitem.sgml +++ b/docs/reference/gtk/tmpl/gtkmenuitem.sgml @@ -19,17 +19,6 @@ GtkMenuItem -@item: -@submenu: -@accelerator_signal: -@toggle_size: -@accelerator_width: -@show_toggle_indicator: -@show_submenu_indicator: -@submenu_placement: -@submenu_direction: -@right_justify: -@timer: diff --git a/docs/reference/gtk/tmpl/gtkmenushell.sgml b/docs/reference/gtk/tmpl/gtkmenushell.sgml index cad3bdefe2..4c00a7a7a3 100644 --- a/docs/reference/gtk/tmpl/gtkmenushell.sgml +++ b/docs/reference/gtk/tmpl/gtkmenushell.sgml @@ -40,18 +40,6 @@ an application.) -@container: -@children: -@active_menu_item: -@parent_menu_shell: -@active: -@have_grab: -@have_xgrab: -@button: -@ignore_leave: -@menu_flag: -@ignore_enter: -@activate_time: diff --git a/docs/reference/gtk/tmpl/gtkmisc.sgml b/docs/reference/gtk/tmpl/gtkmisc.sgml index 8052c87120..861f363324 100644 --- a/docs/reference/gtk/tmpl/gtkmisc.sgml +++ b/docs/reference/gtk/tmpl/gtkmisc.sgml @@ -59,11 +59,6 @@ in pixels. -@widget: -@xalign: -@yalign: -@xpad: -@ypad: diff --git a/docs/reference/gtk/tmpl/gtknotebook.sgml b/docs/reference/gtk/tmpl/gtknotebook.sgml index dc6014b070..e4930dbb8a 100644 --- a/docs/reference/gtk/tmpl/gtknotebook.sgml +++ b/docs/reference/gtk/tmpl/gtknotebook.sgml @@ -19,27 +19,6 @@ GtkNotebook -@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: diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml index c4d5a576e1..ff77d78817 100644 --- a/docs/reference/gtk/tmpl/gtkobject.sgml +++ b/docs/reference/gtk/tmpl/gtkobject.sgml @@ -19,10 +19,6 @@ GtkObject -@klass: -@flags: -@ref_count: -@object_data: diff --git a/docs/reference/gtk/tmpl/gtkoptionmenu.sgml b/docs/reference/gtk/tmpl/gtkoptionmenu.sgml index 429a319f48..9bc5aab887 100644 --- a/docs/reference/gtk/tmpl/gtkoptionmenu.sgml +++ b/docs/reference/gtk/tmpl/gtkoptionmenu.sgml @@ -21,11 +21,6 @@ The #GtkOptionMenu-struct struct contains private data only, and should be accessed using the functions below. -@button: -@menu: -@menu_item: -@width: -@height: diff --git a/docs/reference/gtk/tmpl/gtkpacker.sgml b/docs/reference/gtk/tmpl/gtkpacker.sgml index d9a0fdde06..3302b5d06f 100644 --- a/docs/reference/gtk/tmpl/gtkpacker.sgml +++ b/docs/reference/gtk/tmpl/gtkpacker.sgml @@ -19,14 +19,6 @@ GtkPacker -@parent: -@children: -@spacing: -@default_border_width: -@default_pad_x: -@default_pad_y: -@default_i_pad_x: -@default_i_pad_y: diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml index 7d3fabda3e..db7f80bd36 100644 --- a/docs/reference/gtk/tmpl/gtkpaned.sgml +++ b/docs/reference/gtk/tmpl/gtkpaned.sgml @@ -72,26 +72,8 @@ gtk_widget_set_usize (frame1, 50, -1); -@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: diff --git a/docs/reference/gtk/tmpl/gtkpixmap.sgml b/docs/reference/gtk/tmpl/gtkpixmap.sgml index 57444d8279..6a3fca54ad 100644 --- a/docs/reference/gtk/tmpl/gtkpixmap.sgml +++ b/docs/reference/gtk/tmpl/gtkpixmap.sgml @@ -29,11 +29,6 @@ The #GtkPixmap-struct struct contains private data only, and should be accessed using the functions below. -@misc: -@pixmap: -@mask: -@pixmap_insensitive: -@build_insensitive: diff --git a/docs/reference/gtk/tmpl/gtkplug.sgml b/docs/reference/gtk/tmpl/gtkplug.sgml index 1f71fb5dc9..74fa49ee2f 100644 --- a/docs/reference/gtk/tmpl/gtkplug.sgml +++ b/docs/reference/gtk/tmpl/gtkplug.sgml @@ -33,9 +33,6 @@ inside the first applications window. -@window: -@socket_window: -@same_app: diff --git a/docs/reference/gtk/tmpl/gtkpreview.sgml b/docs/reference/gtk/tmpl/gtkpreview.sgml index d5448de0bd..8ab4dbb3da 100644 --- a/docs/reference/gtk/tmpl/gtkpreview.sgml +++ b/docs/reference/gtk/tmpl/gtkpreview.sgml @@ -28,15 +28,6 @@ The #GtkPreview-struct struct contains private data only, and should be accessed using the functions below. -@widget: -@buffer: -@buffer_width: -@buffer_height: -@bpp: -@rowstride: -@dither: -@type: -@expand: diff --git a/docs/reference/gtk/tmpl/gtkprogress.sgml b/docs/reference/gtk/tmpl/gtkprogress.sgml index f977ff9913..35a02d40d8 100644 --- a/docs/reference/gtk/tmpl/gtkprogress.sgml +++ b/docs/reference/gtk/tmpl/gtkprogress.sgml @@ -19,14 +19,6 @@ GtkProgress -@widget: -@adjustment: -@offscreen_pixmap: -@format: -@x_align: -@y_align: -@show_text: -@activity_mode: diff --git a/docs/reference/gtk/tmpl/gtkprogressbar.sgml b/docs/reference/gtk/tmpl/gtkprogressbar.sgml index 5838aba506..2e59e2dc94 100644 --- a/docs/reference/gtk/tmpl/gtkprogressbar.sgml +++ b/docs/reference/gtk/tmpl/gtkprogressbar.sgml @@ -19,15 +19,6 @@ GtkProgressBar -@progress: -@bar_style: -@orientation: -@blocks: -@in_block: -@activity_pos: -@activity_step: -@activity_blocks: -@activity_dir: diff --git a/docs/reference/gtk/tmpl/gtkradiobutton.sgml b/docs/reference/gtk/tmpl/gtkradiobutton.sgml index 681ceec23f..2419f64d90 100644 --- a/docs/reference/gtk/tmpl/gtkradiobutton.sgml +++ b/docs/reference/gtk/tmpl/gtkradiobutton.sgml @@ -2,84 +2,158 @@ GtkRadioButton - +A choice from multiple check buttons. +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. + +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. + + +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. + + +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. + + +To retrieve the group a #GtkRadioButton is assigned to, use +gtk_radio_button_group(). + + +To remove a #GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_group(). + + + +How to create a group of two radio buttons. + +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; +} + + + + + +#GtkOptionMenu +Another way of offering the user a single choice from +many. + + - +Contains only private data that should be read and manipulated using the +functions below. -@check_button: -@group: - +Creates a new #GtkRadioButton. To be of any practical value, a widget should +then be packed into the radio button. -@group: -@Returns: +@group: an existing radio button group, or NULL if you are creating a new group. +@Returns: a new radio button. - +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. -@group: -@Returns: +@group: an existing #GtkRadioButton. +@Returns: a new radio button. - +Creates a new #GtkRadioButton with a text label. -@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. - +Creates a new #GtkRadioButton with a text label, adding it to the same group +as @group. -@group: -@label: -@Returns: +@group: an existing #GtkRadioButton. +@label: a text string to display next to the radio button. +@Returns: a new radio button. - +Retrieves the group assigned to a radio button. -@radio_button: -@Returns: +@radio_button: a #GtkRadioButton. +@Returns: a linked list containing all the radio buttons in the same group +as @radio_button. - +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. -@radio_button: -@group: +@radio_button: a #GtkRadioButton. +@group: an existing radio button group, such as one returned from +gtk_radio_button_group(). - +Sets a new group for a radio button. diff --git a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml index 58d7fa5afe..3d6ed3fe9b 100644 --- a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml +++ b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml @@ -19,8 +19,6 @@ GtkRadioMenuItem -@check_menu_item: -@group: diff --git a/docs/reference/gtk/tmpl/gtkrange.sgml b/docs/reference/gtk/tmpl/gtkrange.sgml index 2908bce5a0..fcf22cdc60 100644 --- a/docs/reference/gtk/tmpl/gtkrange.sgml +++ b/docs/reference/gtk/tmpl/gtkrange.sgml @@ -19,26 +19,6 @@ GtkRange -@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: diff --git a/docs/reference/gtk/tmpl/gtkruler.sgml b/docs/reference/gtk/tmpl/gtkruler.sgml index 3f32ee75ee..7f9330de31 100644 --- a/docs/reference/gtk/tmpl/gtkruler.sgml +++ b/docs/reference/gtk/tmpl/gtkruler.sgml @@ -25,17 +25,6 @@ All distances are in 1/72nd's of an inch. (According to Adobe thats a point, but points are really 1/72.27 in.) -@widget: -@backing_store: -@non_gr_exp_gc: -@metric: -@xsrc: -@ysrc: -@slider_size: -@lower: -@upper: -@position: -@max_size: @@ -65,25 +54,9 @@ This sets the range of the ruler using gfloat lower, gfloat upper, gfloat positi @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 - - - - - - - -@ruler: the gtkruler - - - - - - - -@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 diff --git a/docs/reference/gtk/tmpl/gtkscale.sgml b/docs/reference/gtk/tmpl/gtkscale.sgml index 8eaf201008..e34f3e25e3 100644 --- a/docs/reference/gtk/tmpl/gtkscale.sgml +++ b/docs/reference/gtk/tmpl/gtkscale.sgml @@ -40,9 +40,6 @@ slider. -@range: -@draw_value: -@value_pos: diff --git a/docs/reference/gtk/tmpl/gtkscrollbar.sgml b/docs/reference/gtk/tmpl/gtkscrollbar.sgml index a459493b09..1996709c7e 100644 --- a/docs/reference/gtk/tmpl/gtkscrollbar.sgml +++ b/docs/reference/gtk/tmpl/gtkscrollbar.sgml @@ -19,5 +19,4 @@ GtkScrollbar -@range: diff --git a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml b/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml index 02163acd9c..92c6db77f4 100644 --- a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml +++ b/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml @@ -49,14 +49,6 @@ There are no public fields in the #GtkScrolledWindow struct; it should only be accessed using the functions below. -@container: -@hscrollbar: -@vscrollbar: -@hscrollbar_policy: -@vscrollbar_policy: -@hscrollbar_visible: -@vscrollbar_visible: -@window_placement: diff --git a/docs/reference/gtk/tmpl/gtkseparator.sgml b/docs/reference/gtk/tmpl/gtkseparator.sgml index 1f116c1d4e..997fd31fe2 100644 --- a/docs/reference/gtk/tmpl/gtkseparator.sgml +++ b/docs/reference/gtk/tmpl/gtkseparator.sgml @@ -20,5 +20,4 @@ subclasses #GtkHSeparator and #GtkVSeparator. The #GtkSeparator-struct struct contains private data only. -@widget: diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml index 3a450f3246..de67e84bf9 100644 --- a/docs/reference/gtk/tmpl/gtksignal.sgml +++ b/docs/reference/gtk/tmpl/gtksignal.sgml @@ -2,16 +2,149 @@ Signals - +Object methods and callbacks. - - - + +What are signals? + +Signals are a way to get notification when something happens +and to customize object behavior according to the +user's needs. +Every signal is uniquely identified by a name, +"class_name::signal_name", where signal_name might be something like +"clicked" and class_name might be "GtkButton". Note that some other class +may also define a "clicked" callback, so long as it doesn't derive from +#GtkButton. + + +When they are created, they are also assigned a unique positive integer, +the signal id (1 is the first signal id- 0 is used to flag an error). +Each is also tied to an array of types that describes +the prototype of the function pointer(s) (handlers) you may +connect to the signal. Finally, every signal has +a default handler that is given by a function pointer +in its class structure: it is run by default whenever the +signal is emitted. (It is possible that a signal will +be emitted and a user-defined handler will prevent the default handler +from being run.) + + +Signals are used by everyone, but they are only +created on a per class basis-- so you should call +call gtk_signal_new() unless you are writing +a new #GtkObject type. However, if you want to make a new signal +for an existing type, you may use gtk_object_class_user_signal_new() +to create a signal that doesn't correspond to a class's builtin +methods. + + + +How are signals used? + +There are two basic actions in the signal handling game. +If you want notification of an event, you must connect +a function pointer and a data pointer to that signal; the data pointer +will be passed as the last argument to the function (so long as you +are using the default marshalling functions). +You will receive a connection id, a unique positive integer +corresponding to that attachment. + + +Functions that want to notify the user of certain actions, +emit signals. + + + +Basic Terminology + + + +signal +A class method, e.g. GtkButton::clicked. +More precisely it is a unique class-branch/signal-name pair. +This means you may not define a signal handler for a class which +derives from GtkButton that is called clicked, +but it is okay to share signals names if they are separate in +the class tree. + + + + +default handler +The object's internal method which is invoked +when the signal is emitted. + + + + +user-defined handler +A function pointer and data connected +to a signal (for a particular object). +There are really two types: those which are connected +normally, and those which are connected by one +of the connect_after functions. The connect_after handlers +are always run after the default handler. +Many toolkits refer to these as callbacks. + + + + +emission +the whole process of emitting a signal, +including the invocation of all +the different handler types mentioned above. + + + + +signal id +The unique positive (nonzero) integer +used to identify a signal. It can be used instead of +a name to many functions for a slight performance +improvement. + + + + +connection id +The unique positive (nonzero) integer +used to identify the connection of a user-defined handler +to a signal. Notice that it is allowed to connect the +same function-pointer/user-data pair twice, so +there is no guarantee that a function-pointer/user-data +maps to a unique connection id. + + + + + + + +A brief note on how they work. + +The functions responsible for translating an array of #GtkArgs +to your C compiler's normal semantics are called Marshallers. +They are identified by +gtk_marshal_return_value__parameter_list() +for example a C function returning a gboolean and taking a gint +can be invoked by using gtk_marshal_BOOL__INT(). +Not all possibly combinations of return/params are available, +of course, so if you are writing a #GtkObject with parameters +you might have to write a marshaller. + + - - + + + + +#GtkObject +The base class for things which emit signals. + + + @@ -24,42 +157,69 @@ Signals - - + +This is currently a hack left in for a scheme wrapper library. +It may be removed. + + +Don't use it. -@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 +or #GTK_TYPE_NONE for no return value. - - + +A function which you can use to clean up when the +signal handler is destroyed. + + +For example, if your handler requires a few variables +that you made into a struct and allocated (using g_new() +or something), then you will probably want to free +it as soon as the hook is destroyed. This will +allow you to do that. (For this in particular +it is convenient to pass g_free() as a #GtkSignalDestroy +function). -@data: +@data: The user data associated with the hook that is being +destroyed. - - + +A simple function pointer to get invoked when the +signal is emitted. This allows you tie a hook to the signal type, +so that it will trap all emissions of that signal, from any object. + + +You may not attach these to signals created with the +#GTK_RUN_NO_HOOKS flag. -@object: -@signal_id: -@n_params: -@params: -@data: -@Returns: +@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, +not including return value. +@params: the parameters to the function. A pointer to +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 +TRUE, the signal hook is disconnected (and destroyed). - - + +This structure contains all the information about a particular +signal: its name, the type it affects, the signature of the handlers, +and its unique identifying integer. @object_type: @@ -71,6 +231,81 @@ Signals @nparams: @params: + + +These configure the signal's emission. They control +whether the signal can be emitted recursively on an object +and +whether to run the default method before or after the user-defined handlers. + + + + + +GTK_RUN_FIRST +Run the default handler before the connected user-defined +handlers. + + + + +GTK_RUN_LAST +Run the default handler after the connected +user-defined handlers. +(Handlers registered as "after" always run after the default handler though) + + + + +GTK_RUN_BOTH +Run the default handler twice, +once before the user-defined handlers, +and +once after. + + + + +GTK_RUN_NO_RECURSE +Whether to prevent a handler or hook +from reemitting the signal from within itself. +Attempts to +emit the signal while it is running will result in the signal +emission being restarted once it is done with the current processing. + +You must be +careful to avoid having two handlers endlessly reemitting signals, +gtk_signal_n_emissions() can be helpful. + + + + +GTK_RUN_ACTION +The signal is an action you can +invoke without any particular setup or cleanup. +The signal is treated no differently, but some +other code can determine if the signal is appropriate to +delegate to user control. For example, key binding sets +only allow bindings of ACTION signals to keystrokes. + + + + +GTK_RUN_NO_HOOKS +This prevents the connection of emission hooks +to the signal. + + + + + +@GTK_RUN_FIRST: +@GTK_RUN_LAST: +@GTK_RUN_BOTH: +@GTK_RUN_NO_RECURSE: +@GTK_RUN_ACTION: +@GTK_RUN_NO_HOOKS: + @@ -79,395 +314,613 @@ Signals - - + +Create a new signal type. (This is usually done in the +class initializer.) -@name: -@signal_flags: -@object_type: -@function_offset: -@marshaller: -@return_val: -@nparams: -@Varargs: -@Returns: +@name: the event name for the signal, e.g. "clicked". +@signal_flags: a combination of GTK_RUN flags +specifying detail of when the default handler is to be invoked. +You should at least specify #GTK_RUN_FIRST +or #GTK_RUN_LAST. +@object_type: the type of object this signal pertains to. +It will also pertain to derivers of this type automatically. +@function_offset: How many bytes the function pointer is in +the class structure for this type. Used to invoke a class +method generically. +@marshaller: the function to translate between an array +of GtkArgs and the native calling convention. Usually they +are identified just by the type of arguments they take: +for example, gtk_marshal_BOOL__STRING() describes a marshaller +which takes a string and returns a boolean value. +@return_val: the type of return value, or GTK_TYPE_NONE for a signal +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. - - + +Create a new signal type. (This is usually done in a +class initializer.) + + +This function take the types as an array, instead of a list +following the arguments. Otherwise the same as gtk_signal_new(). -@name: -@signal_flags: -@object_type: -@function_offset: +@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 +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 +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 +the callbacks. +@Returns: the signal id. - - + +Given the name of the signal and the type of object it connects +to, get the signal's identifying integer. Emitting the signal +by number is somewhat faster than using the name each time. + + +It also tries the ancestors of the given type. -@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. - - + +Given the signal's identifier, find its name. + + +Two different signals may have the same name, if they have differing types. -@signal_id: -@Returns: +@signal_id: the signal's identifying number. +@Returns: the signal name, or NULL if the signal number was invalid. - - + +Emit a signal. This causes the default handler and user-defined +handlers to be run. + + +Here is what gtk_signal_emit() does: + + +1. Calls the default handler and the user-connected handlers. +The default handler will be called first if +GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set. + + +2. Calls all handlers connected with the "after" flag set. -@object: -@signal_id: -@Varargs: +@object: the object that emits the signal. +@signal_id: the signal identifier. +@Varargs: the parameters to the function, followed +by a pointer to the return type, if any. - - + +Emit a signal. This causes the default handler and user-connected +handlers to be run. -@object: -@name: -@Varargs: +@object: the object that emits the signal. +@name: the name of the signal. +@Varargs: the parameters to the function, followed +by a pointer to the return type, if any. - - + +Emit a signal. This causes the default handler and user-connected +handlers to be run. This differs from gtk_signal_emit() by taking +an array of GtkArgs instead of using C's varargs mechanism. -@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, +followed by one which is a pointer to the return type. - - + +Emit a signal by name. This causes the default handler and user-connected +handlers to be run. This differs from gtk_signal_emit() by taking +an array of GtkArgs instead of using C's varargs mechanism. -@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, +followed by one which is a pointer to the return type. - - + +Find out the recursion depth of emissions for a particular type +of signal and object. (So it will +always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified) +This is a way to avoid recursion: you can see if +you are currently running in that signal handler and emit it only +if you are. + +Another way to look at it is that this number increases +by one when #gtk_signal_emit(), et al, are called, +and decreases by one when #gtk_signal_emit() returns. -@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 +object. - - + +Find out the recursion depth of emissions for a particular type +of signal and object. Just like gtk_signal_n_emissions() +except it will lookup the signal id for you. -@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 +object. - - + +This function aborts a signal's current emission. + + +It will prevent the default method from running, +if the signal was #GTK_RUN_LAST and you connected +normally (i.e. without the "after" flag). + +It will print a warning if used on a signal which +isn't being emitted. -@object: -@signal_id: +@object: the object whose signal handlers you wish to stop. +@signal_id: the signal identifier, as returned by gtk_signal_lookup(). - - + +This function aborts a signal's current emission. + +It is just like +gtk_signal_emit_stop() +except it will lookup the signal id for you. -@object: -@name: +@object: the object whose signal handlers you wish to stop. +@name: the name of the signal you wish to stop. - + +Attach a function pointer and user data to a signal for +a particular object. + + +The GtkSignalFunction takes a GtkObject as its first parameter. +It will be the same object as the one you're connecting +the hook to. The func_data will be passed as the last parameter +to the hook. + + +All else being equal, signal handlers are invoked in the order +connected (see gtk_signal_emit() for the other details of +which order things are called in). + + +Here is how one passes an integer as user data, +for when you just want to specify a constant int +as parameter to your function: + + +static void button_clicked_int(GtkButton* button, gpointer func_data) +{ + g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data)); +} + +/* By calling this function, you will make the g_print above + * execute, printing the number passed as `to_print'. */ +static void attach_print_signal(GtkButton* button, gint to_print) +{ + gtk_signal_connect(GTK_OBJECT(button), "clicked", + GTK_SIGNAL_FUNC(button_clicked_int), + GINT_TO_POINTER(to_print)); +} + + - - -@object: -@name: -@func: -@func_data: -@Returns: +@object: the object associated with the signal, e.g. if a button +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. - - + +Attach a function pointer and user data to a signal +so that this handler will be called after the other handlers. -@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. - + +This function is for registering a callback that will +call another object's callback. That is, +instead of passing the object which is responsible +for the event as the first parameter of the callback, +it is switched with the user data (so the object which emits +the signal will be the last parameter, which is where the +user data usually is). + + +This is useful for passing a standard function in as a callback. +For example, if you wanted a button's press to gtk_widget_show() +some widget, you could write: + + + +gtk_signal_connect_object(button, "clicked", gtk_widget_show, window); + + - - -@object: -@name: -@func: -@slot_object: -@Returns: +@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. +(Though it pretends to take an object, you can +really pass any gpointer as the #slot_object .) +@Returns: the connection id. - - + +Attach a signal hook to a signal, passing in an alternate +object as the first parameter, and guaranteeing +that the default handler and all normal +handlers are called first. -@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. - - + +Attach a function pointer and user data to a signal with +more control. -@object: -@name: -@func: -@marshal: -@data: -@destroy_func: -@object_signal: -@after: -@Returns: - - - - - - - -@object: -@signal: -@func: -@alive_object: +@object: the object which emits the signal. For example, a button +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 +more details, but briefly: the marshaller is a function which takes +the #GtkObject which emits the signal, the user data, the number of the +arguments, and the array of arguments. It is responsible for +calling the function in the appropriate calling convention. +gtk_signal_default_marshaller is usually fine. +(This shows up, for example, when worrying about matching +c++ or other languages' calling conventions.) +@data: the user data associated with the function. +@destroy_func: function to call when this particular hook is +disconnected. +@object_signal: whether this is an object signal-- basically an "object +signal" is one that wants its user_data and object fields switched, +which is useful for calling functions which operate on another +object primarily. +@after: whether to invoke the user-defined handler after the signal, or to let +the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST +and #GTK_RUN_LAST). +@Returns: the connection id. - - + +Attach a function pointer and another GtkObject to a signal. + + +This function takes an object whose "destroy" signal +should be trapped. +That way, you don't have to clean up the +signal handler when you destroy the object. +It is a little less efficient though. + + +(Instead you may call gtk_signal_disconnect_by_data(), if you want +to explicitly delete all attachments to this object. This +is perhaps not recommended since it could be confused +with an integer masquerading as a pointer (through GINT_AS_POINTER).) -@object: +@object: the object that emits the signal. @signal: -@func: -@func_data: -@alive_object: +@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 +to be destroyed. + +@name: name of the signal. + + + + +These signal connectors are for signals which refer to objects, +so they must not be called after the object is deleted. + + +Unlike gtk_signal_connect_while_alive(), +this swaps the object and user data, making it suitable for +use with functions which primarily operate on the user data. + + +This function acts just like gtk_signal_connect_object() except +it traps the "destroy" signal to prevent you from having to +clean up the handler. + + +@object: the object associated with the signal. +@signal: +@func: function pointer to attach to the signal. +@alive_object: the user data, which must be an object, whose destruction +should signal the removal of this signal. + +@name: name of the signal. - - + +Destroy a user-defined handler connection. -@object: -@handler_id: +@object: the object which the handler pertains to. +@handler_id: the connection id. - - + +Destroy all connections for a particular object, with +the given function-pointer and user-data. -@object: -@func: -@data: +@object: the object which emits the signal. +@func: the function pointer to search for. +@data: the user data to search for. - - + +Destroy all connections for a particular object, with +the given user-data. -@object: -@data: +@object: the object which emits the signal. +@data: the user data to search for. - - + +Prevent an user-defined handler from being invoked. All other +signal processing will go on as normal, but this particular +handler will ignore it. -@object: -@handler_id: +@object: the object which emits the signal to block. +@handler_id: the connection id. - - + +Prevent a user-defined handler from being invoked, by reference to +the user-defined handler's function pointer and user data. (It may result in +multiple hooks being blocked, if you've called connect multiple times.) -@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. - - + +Prevent all user-defined handlers with a certain user data from being invoked. -@object: -@data: +@object: the object which emits the signal we want to block. +@data: the user data of the handlers to block. - - + +Undo a block, by connection id. Note that undoing a block doesn't +necessarily make the hook callable, because if you block a +hook twice, you must unblock it twice. -@object: -@handler_id: +@object: the object which emits the signal we want to unblock. +@handler_id: the emission handler identifier, as returned by +gtk_signal_connect(), etc. - - + +Undo a block, by function pointer and data. +Note that undoing a block doesn't +necessarily make the hook callable, because if you block a +hook twice, you must unblock it twice. -@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. - - + +Undo block(s), to all signals for a particular object +with a particular user-data pointer -@object: -@data: +@object: the object which emits the signal we want to unblock. +@data: the user data to search for. - - + +Returns a connection id corresponding to a given signal id and object. + + +One example of when you might use this is when the arguments +to the signal are difficult to compute. A class implementor +may opt to not emit the signal if no one is attached anyway, +thus saving the cost of building the arguments. -@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 +handler. +@Returns: the connection id, if a connection was found. 0 otherwise. - - + +Returns a connection id corresponding to a given signal id, object, function +pointer and user data. -@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 +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. - - + +Returns whether a connection id is valid (and optionally not blocked). -@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 +handler. +@Returns: TRUE if the signal exists and wasn't blocked, +unless #may_be_blocked was specified. FALSE otherwise. - - + +Destroy all the signal handlers connected to an object. +This is done automatically when the object is destroyed. + + +This function is labeled private. -@object: +@object: the object whose signal handlers should be destroyed. - - + +These set default functions to call when the user didn't +supply a function when connecting. (These are rarely +used, and probably only for language bindings) + + +By default, there are no such functions. -@marshal_func: -@destroy_func: +@marshal_func: the function to invoke on every handlers for which there +isn't a function pointer. May be NULL. +@destroy_func: the function to invoke when each hook is destroyed. +May be NULL. - - + +Obtain information about a signal. -@signal_id: -@Returns: +@signal_id: the signal type identifier. +@Returns: a pointer to a GtkSignalQuery structure +which contains all the information, or NULL. +The pointer is allocated just for you: you must g_free() it. - - + +Add an emission hook for a type of signal, for any object. -@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 +to gtk_signal_remove_emission_hook()). - - + +Add an emission hook for a type of signal, for any object. +(with control of what happens when the hook is +destroyed). -@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, +to clean up any allocation done just for this +signal handler. +@Returns: the id (that you may pass as a parameter +to gtk_signal_remove_emission_hook()). - - + +Delete an emission hook. (see gtk_signal_add_emission_hook()) -@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(). diff --git a/docs/reference/gtk/tmpl/gtksocket.sgml b/docs/reference/gtk/tmpl/gtksocket.sgml index ae9ea670f2..6023b10441 100644 --- a/docs/reference/gtk/tmpl/gtksocket.sgml +++ b/docs/reference/gtk/tmpl/gtksocket.sgml @@ -101,16 +101,6 @@ never be set by an application.) -@container: -@request_width: -@request_height: -@current_width: -@current_height: -@plug_window: -@same_app: -@focus_in: -@have_size: -@need_map: diff --git a/docs/reference/gtk/tmpl/gtkspinbutton.sgml b/docs/reference/gtk/tmpl/gtkspinbutton.sgml index 661ea26e1c..6bed4c17f9 100644 --- a/docs/reference/gtk/tmpl/gtkspinbutton.sgml +++ b/docs/reference/gtk/tmpl/gtkspinbutton.sgml @@ -127,24 +127,6 @@ void create_floating_spin_button(void) { entry 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. -@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: diff --git a/docs/reference/gtk/tmpl/gtkstatusbar.sgml b/docs/reference/gtk/tmpl/gtkstatusbar.sgml index 13fa228c75..f751cd051e 100644 --- a/docs/reference/gtk/tmpl/gtkstatusbar.sgml +++ b/docs/reference/gtk/tmpl/gtkstatusbar.sgml @@ -49,13 +49,6 @@ The message at the top of the stack can be removed using gtk_statusbar_pop(). A Contains private data that should be modified with the functions described below. -@parent_widget: -@frame: -@label: -@messages: -@keys: -@seq_context_id: -@seq_message_id: diff --git a/docs/reference/gtk/tmpl/gtktable.sgml b/docs/reference/gtk/tmpl/gtktable.sgml index 0ba1ce02e0..74fe50b426 100644 --- a/docs/reference/gtk/tmpl/gtktable.sgml +++ b/docs/reference/gtk/tmpl/gtktable.sgml @@ -54,15 +54,6 @@ The GtkTable structure holds the data for the actual table itself. nrows and ncols are 16bit integers storing the number of rows and columns the table has. -@container: -@children: -@rows: -@cols: -@nrows: -@ncols: -@column_spacing: -@row_spacing: -@homogeneous: diff --git a/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml b/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml index a065298e81..b155db59cc 100644 --- a/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml +++ b/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml @@ -42,8 +42,6 @@ The #GtkTearoffMenuItem-struct struct contains private data only, and should be accessed using the functions below. -@menu_item: -@torn_off: diff --git a/docs/reference/gtk/tmpl/gtktext.sgml b/docs/reference/gtk/tmpl/gtktext.sgml index 73cd8f0039..968a3e2864 100644 --- a/docs/reference/gtk/tmpl/gtktext.sgml +++ b/docs/reference/gtk/tmpl/gtktext.sgml @@ -42,13 +42,6 @@ at widget creation. -@editable: -@text_area: -@hadj: -@vadj: -@gc: -@line_wrap_bitmap: -@line_arrow_bitmap: diff --git a/docs/reference/gtk/tmpl/gtktipsquery.sgml b/docs/reference/gtk/tmpl/gtktipsquery.sgml index 0bc6abfaac..7f7949a1db 100644 --- a/docs/reference/gtk/tmpl/gtktipsquery.sgml +++ b/docs/reference/gtk/tmpl/gtktipsquery.sgml @@ -2,128 +2,159 @@ GtkTipsQuery - +displays help about widgets in the user interface. - +The #GtkTipsQuery widget is a subclass of #GtkLabel which is used to display +help about widgets in a user interface. + + +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. + + +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. + + +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). - + + +#GtkTooltips +the object which handles tooltips. + + - +The #GtkTipsQuery-struct struct contains private data only, and +should be accessed using the functions below. -@label: -@emit_always: -@in_query: -@label_inactive: -@label_no_tip: -@caller: -@last_crossed: -@query_cursor: - +Creates a new #GtkTipsQuery. -@Returns: +@Returns: a new #GtkTipsQuery. - +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. -@tips_query: +@tips_query: a #GtkTipsQuery. - +Stops a query. -@tips_query: +@tips_query: a #GtkTipsQuery. - +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. -@tips_query: -@caller: +@tips_query: a #GtkTipsQuery. +@caller: the widget which initiates the query. - +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. -@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. - +Emitted when the query is started. @tipsquery: the object which received the signal. - +Emitted when the query is stopped. @tipsquery: the object which received the signal. - +Emitted when a widget is entered by the pointer while the query is in effect. @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()). - +Emitted when a widget is selected during a query. @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. - +TRUE if the widget-entered and widget-selected signals are emitted even when +the widget has no tooltip set. - +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. - +The text to display in the #GtkTipsQuery widget when the query is not in +effect. - +The text to display in the #GtkTipsQuery widget when the query is running +and the widget that the pointer is over has no tooltip. diff --git a/docs/reference/gtk/tmpl/gtktogglebutton.sgml b/docs/reference/gtk/tmpl/gtktogglebutton.sgml index 3ba8121c48..83dd4acbb1 100644 --- a/docs/reference/gtk/tmpl/gtktogglebutton.sgml +++ b/docs/reference/gtk/tmpl/gtktogglebutton.sgml @@ -78,10 +78,6 @@ void make_toggles(void) { The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below. -@button: -@active: -@draw_indicator: -@event_window: diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml index 7debeba9f7..3ed9166ad8 100644 --- a/docs/reference/gtk/tmpl/gtktoolbar.sgml +++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml @@ -40,17 +40,6 @@ Widgets can be visibily grouped by adding gaps between widgets using gtk_toolbar orientation -@container: -@num_children: -@children: -@orientation: -@style: -@space_size: -@space_style: -@tooltips: -@button_maxw: -@button_maxh: -@relief: diff --git a/docs/reference/gtk/tmpl/gtktooltips.sgml b/docs/reference/gtk/tmpl/gtktooltips.sgml index fba097eb9f..a78350fc02 100644 --- a/docs/reference/gtk/tmpl/gtktooltips.sgml +++ b/docs/reference/gtk/tmpl/gtktooltips.sgml @@ -78,16 +78,6 @@ Information about the tooltip (if any) associated with an arbitrary widget can b Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members. -@data: -@tip_window: -@active_tips_data: -@tips_data_list: -@gc: -@foreground: -@background: -@delay: -@enabled: -@timer_tag: diff --git a/docs/reference/gtk/tmpl/gtktree.sgml b/docs/reference/gtk/tmpl/gtktree.sgml index 84be04bd2a..b42794aec5 100644 --- a/docs/reference/gtk/tmpl/gtktree.sgml +++ b/docs/reference/gtk/tmpl/gtktree.sgml @@ -37,17 +37,6 @@ struct _GtkTree -@container: -@children: -@root_tree: -@tree_owner: -@selection: -@level: -@indent_value: -@current_indent: -@selection_mode: -@view_mode: -@view_line: diff --git a/docs/reference/gtk/tmpl/gtktreeitem.sgml b/docs/reference/gtk/tmpl/gtktreeitem.sgml index fd745a7293..8c39ed77fa 100644 --- a/docs/reference/gtk/tmpl/gtktreeitem.sgml +++ b/docs/reference/gtk/tmpl/gtktreeitem.sgml @@ -19,11 +19,6 @@ GtkTreeItem -@item: -@subtree: -@pixmaps_box: -@pixmaps: -@expanded: diff --git a/docs/reference/gtk/tmpl/gtkvbbox.sgml b/docs/reference/gtk/tmpl/gtkvbbox.sgml index d0fe4c8652..9ebcd7ed0c 100644 --- a/docs/reference/gtk/tmpl/gtkvbbox.sgml +++ b/docs/reference/gtk/tmpl/gtkvbbox.sgml @@ -19,7 +19,6 @@ GtkVButtonBox -@button_box: diff --git a/docs/reference/gtk/tmpl/gtkvbox.sgml b/docs/reference/gtk/tmpl/gtkvbox.sgml index 306f685abe..2f317fa4b3 100644 --- a/docs/reference/gtk/tmpl/gtkvbox.sgml +++ b/docs/reference/gtk/tmpl/gtkvbox.sgml @@ -33,7 +33,6 @@ All children are allocated the same width. -@box: diff --git a/docs/reference/gtk/tmpl/gtkviewport.sgml b/docs/reference/gtk/tmpl/gtkviewport.sgml index a43582f0c7..6ce665c5fe 100644 --- a/docs/reference/gtk/tmpl/gtkviewport.sgml +++ b/docs/reference/gtk/tmpl/gtkviewport.sgml @@ -19,12 +19,6 @@ GtkViewport -@bin: -@shadow_type: -@view_window: -@bin_window: -@hadjustment: -@vadjustment: diff --git a/docs/reference/gtk/tmpl/gtkvpaned.sgml b/docs/reference/gtk/tmpl/gtkvpaned.sgml index f6d41bc5a6..edcff3251e 100644 --- a/docs/reference/gtk/tmpl/gtkvpaned.sgml +++ b/docs/reference/gtk/tmpl/gtkvpaned.sgml @@ -21,7 +21,6 @@ a handle. See #GtkPaned for details. -@paned: diff --git a/docs/reference/gtk/tmpl/gtkvruler.sgml b/docs/reference/gtk/tmpl/gtkvruler.sgml index 789cd16ce8..aad5d12e25 100644 --- a/docs/reference/gtk/tmpl/gtkvruler.sgml +++ b/docs/reference/gtk/tmpl/gtkvruler.sgml @@ -19,14 +19,12 @@ rulers. - The #GtkVRuler struct contains private data and should be accessed using the functions below. -@ruler: diff --git a/docs/reference/gtk/tmpl/gtkvscale.sgml b/docs/reference/gtk/tmpl/gtkvscale.sgml index 0b0e0171d1..81a6ffa294 100644 --- a/docs/reference/gtk/tmpl/gtkvscale.sgml +++ b/docs/reference/gtk/tmpl/gtkvscale.sgml @@ -27,7 +27,6 @@ The #GtkVScale-struct struct contains private data only, and should be accessed using the functions below. -@scale: diff --git a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml index ecff50a5b0..758fd43349 100644 --- a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml +++ b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml @@ -17,14 +17,12 @@ will be created you. See #GtkAdjustment for details. - The #GtkVScrollbar struct contains private data and should be accessed using the functions below. -@scrollbar: diff --git a/docs/reference/gtk/tmpl/gtkvseparator.sgml b/docs/reference/gtk/tmpl/gtkvseparator.sgml index 6e4b7047c3..dd4606d37e 100644 --- a/docs/reference/gtk/tmpl/gtkvseparator.sgml +++ b/docs/reference/gtk/tmpl/gtkvseparator.sgml @@ -2,30 +2,37 @@ GtkVSeparator - +a vertical separator. - +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. - + + +#GtkHSeparator +a horizontal separator. + + - +The #GtkVSeparator-struct struct contains private data only, and +should be accessed using the functions below. -@separator: - +Creates a new #GtkVSeparator. -@Returns: +@Returns: a new #GtkVSeparator. diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 3ecc84727b..515a535e50 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -19,16 +19,6 @@ GtkWidget -@object: -@private_flags: -@state: -@saved_state: -@name: -@style: -@requisition: -@allocation: -@window: -@parent: diff --git a/docs/reference/gtk/tmpl/gtkwindow.sgml b/docs/reference/gtk/tmpl/gtkwindow.sgml index abb94a3fa6..34cb93790f 100644 --- a/docs/reference/gtk/tmpl/gtkwindow.sgml +++ b/docs/reference/gtk/tmpl/gtkwindow.sgml @@ -19,22 +19,6 @@ GtkWindow -@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: