diff --git a/ChangeLog b/ChangeLog index 6c7bc4d74b..9bde465457 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2007-05-26 Matthias Clasen + + * configure.in: Require gtk-doc 1.6, for signal and property links. + * gtk/gtkbox.c: + * gtk/gtkbutton.c: + * gtk/gtkcontainer.c: + * gtk/gtkdialog.c: + * gtk/gtkentry.c: + * gtk/gtkimage.c: + * gtk/gtklabel.c: + * gtk/gtkmisc.c: + * gtk/gtksettings.c: + * gtk/gtkwidget.c: Documentation improvements, link signals + and properties where it makes sense. + 2007-05-25 Matthias Clasen * gtk/gtktextmark.c: diff --git a/configure.in b/configure.in index 72f7928c63..6669a8cff7 100644 --- a/configure.in +++ b/configure.in @@ -1623,7 +1623,7 @@ fi # Checks for gtk-doc and docbook-tools ################################################## -GTK_DOC_CHECK([1.4]) +GTK_DOC_CHECK([1.6]) AC_CHECK_PROG(DB2HTML, db2html, true, false) AM_CONDITIONAL(HAVE_DOCBOOK, $DB2HTML) diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c index f80a7d09a9..7f8f23d4db 100644 --- a/gtk/gtkbox.c +++ b/gtk/gtkbox.c @@ -432,7 +432,7 @@ gtk_box_set_homogeneous (GtkBox *box, * @box: a #GtkBox * * Returns whether the box is homogeneous (all children are the - * same size). See gtk_box_set_homogeneous (). + * same size). See gtk_box_set_homogeneous(). * * Return value: %TRUE if the box is homogeneous. **/ diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c index c2729c0432..1b7db3921f 100644 --- a/gtk/gtkbutton.c +++ b/gtk/gtkbutton.c @@ -309,7 +309,7 @@ gtk_button_class_init (GtkButtonClass *klass) * * Emitted when the button is pressed. * - * @Deprecated: Use the GtkWidget::button-press-event signal. + * @Deprecated: Use the #GtkWidget::button-press-event signal. */ button_signals[PRESSED] = g_signal_new (I_("pressed"), @@ -326,7 +326,7 @@ gtk_button_class_init (GtkButtonClass *klass) * * Emitted when the button is released. * - * @Deprecated: Use the GtkWidget::button-release-event signal. + * @Deprecated: Use the #GtkWidget::button-release-event signal. */ button_signals[RELEASED] = g_signal_new (I_("released"), @@ -358,7 +358,7 @@ gtk_button_class_init (GtkButtonClass *klass) * * Emitted when the pointer enters the button. * - * @Deprecated: Use the GtkWidget::enter-notify-event signal. + * @Deprecated: Use the #GtkWidget::enter-notify-event signal. */ button_signals[ENTER] = g_signal_new (I_("enter"), @@ -375,7 +375,7 @@ gtk_button_class_init (GtkButtonClass *klass) * * Emitted when the pointer leaves the button. * - * @Deprecated: Use the GtkWidget::leave-notify-event signal. + * @Deprecated: Use the #GtkWidget::leave-notify-event signal. */ button_signals[LEAVE] = g_signal_new (I_("leave"), @@ -390,10 +390,10 @@ gtk_button_class_init (GtkButtonClass *klass) * GtkButton::activate: * @widget: the object which received the signal. * - * The "activate" signal on GtkButton is an action signal and + * The ::activate signal on GtkButton is an action signal and * emitting it causes the button to animate press then release. * Applications should never connect to this signal, but use the - * "clicked" signal. + * #GtkButton::clicked signal. */ button_signals[ACTIVATE] = g_signal_new (I_("activate"), @@ -438,8 +438,8 @@ gtk_button_class_init (GtkButtonClass *klass) /** * GtkButton:displace-focus: * - * Whether the child_displacement_x/child_displacement_y properties should also - * affect the focus rectangle. + * Whether the child_displacement_x/child_displacement_y properties + * should also affect the focus rectangle. * * Since: 2.6 */ @@ -1651,7 +1651,7 @@ gtk_button_get_use_underline (GtkButton *button) * @button: a #GtkButton * @use_stock: %TRUE if the button should use a stock item * - * If true, the label set on the button is used as a + * If %TRUE, the label set on the button is used as a * stock id to select the stock item for the button. */ void @@ -1953,7 +1953,7 @@ gtk_button_grab_notify (GtkWidget *widget, * @image: a widget to set as the image for the button * * Set the image of @button to the given widget. Note that - * it depends on the gtk-button-images setting whether the + * it depends on the #GtkSettings:gtk-button-images setting whether the * image will be displayed or not, you don't have to call * gtk_widget_show() on @image yourself. * diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 6c11502806..2040503d95 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -262,7 +262,7 @@ gtk_container_class_init (GtkContainerClass *class) /** * gtk_container_child_type: - * @container: a #GtkContainer. + * @container: a #GtkContainer * * Returns the type of the children supported by the container. * @@ -487,7 +487,7 @@ gtk_container_child_get_property (GtkContainer *container, * @child: a widget which is a child of @container * @first_property_name: the name of the first property to set * @var_args: a %NULL-terminated list of property names and values, starting - * with @first_prop_name. + * with @first_prop_name * * Sets one or more child properties for @child and @container. **/ @@ -610,7 +610,7 @@ gtk_container_child_set_property (GtkContainer *container, * @widget: a widget to be placed inside @container * @first_prop_name: the name of the first child property to set * @Varargs: a %NULL-terminated list of property names and values, starting - * with @first_prop_name. + * with @first_prop_name * * Adds @widget to @container, setting child properties at the same time. * See gtk_container_add() and gtk_container_child_set() for more details. @@ -650,7 +650,7 @@ gtk_container_add_with_properties (GtkContainer *container, * @child: a widget which is a child of @container * @first_prop_name: the name of the first property to set * @Varargs: a %NULL-terminated list of property names and values, starting - * with @first_prop_name. + * with @first_prop_name * * Sets one or more child properties for @child and @container. **/ @@ -677,7 +677,7 @@ gtk_container_child_set (GtkContainer *container, * @child: a widget which is a child of @container * @first_prop_name: the name of the first property to get * @Varargs: a %NULL-terminated list of property names and #GValue*, - * starting with @first_prop_name. + * starting with @first_prop_name * * Gets the values of one or more child properties for @child and @container. **/ @@ -878,8 +878,8 @@ gtk_container_get_property (GObject *object, /** * gtk_container_set_border_width: * @container: a #GtkContainer - * @border_width: amount of blank space to leave outside the container. - * Valid values are in the range 0-65535 pixels. + * @border_width: amount of blank space to leave outside + * the container. Valid values are in the range 0-65535 pixels. * * Sets the border width of the container. * @@ -1003,8 +1003,8 @@ _gtk_container_dequeue_resize_handler (GtkContainer *container) /** * gtk_container_set_resize_mode: - * @container: a #GtkContainer. - * @resize_mode: the new resize mode. + * @container: a #GtkContainer + * @resize_mode: the new resize mode * * Sets the resize mode for the container. * @@ -1053,8 +1053,8 @@ gtk_container_get_resize_mode (GtkContainer *container) /** * gtk_container_set_reallocate_redraws: - * @container: a #GtkContainer. - * @needs_redraws: the new value for the container's @reallocate_redraws flag. + * @container: a #GtkContainer + * @needs_redraws: the new value for the container's @reallocate_redraws flag * * Sets the @reallocate_redraws flag of the container to the given value. * @@ -1263,7 +1263,7 @@ gtk_container_forall (GtkContainer *container, * @callback: a callback * @callback_data: callback user data * - * Invokes @callback on each non-internal child of @container. See + * Invokes @callback on each non-internal child of @container. See * gtk_container_forall() for details on what constitutes an * "internal" child. Most applications should use * gtk_container_foreach(), rather than gtk_container_forall(). @@ -1354,7 +1354,7 @@ gtk_container_set_focus_child (GtkContainer *container, /** * gtk_container_get_children: - * @container: a #GtkContainer. + * @container: a #GtkContainer * * Returns the container's non-internal children. See * gtk_container_forall() for details on what constitutes an "internal" child. @@ -1950,13 +1950,13 @@ gtk_container_focus_sort_left_right (GtkContainer *container, * gtk_container_focus_sort: * @container: a #GtkContainer * @children: a list of descendents of @container (they don't - * have to be direct children. + * have to be direct children) * @direction: focus direction * @old_focus: widget to use for the starting position, or %NULL * to determine this automatically. - * [ Note, this argument isn't used for GTK_DIR_TAB_*, - * which is the only @direction we use currently, - * so perhaps this argument should be removed ] + * (Note, this argument isn't used for GTK_DIR_TAB_*, + * which is the only @direction we use currently, + * so perhaps this argument should be removed) * * Sorts @children in the correct order for focusing with * direction type @direction. @@ -2073,8 +2073,8 @@ chain_widget_destroyed (GtkWidget *widget, /** * gtk_container_set_focus_chain: - * @container: a #GtkContainer. - * @focusable_widgets: the new focus chain. + * @container: a #GtkContainer + * @focusable_widgets: the new focus chain * * Sets a focus chain, overriding the one computed automatically by GTK+. * @@ -2165,7 +2165,7 @@ gtk_container_get_focus_chain (GtkContainer *container, /** * gtk_container_unset_focus_chain: - * @container: a #GtkContainer. + * @container: a #GtkContainer * * Removes a focus chain explicitly set with gtk_container_set_focus_chain(). **/ @@ -2204,17 +2204,18 @@ gtk_container_unset_focus_chain (GtkContainer *container) /** * gtk_container_set_focus_vadjustment: * @container: a #GtkContainer - * @adjustment: an adjustment which should be adjusted when the focus is moved among the - * descendents of @container + * @adjustment: an adjustment which should be adjusted when the focus + * is moved among the descendents of @container * - * Hooks up an adjustment to focus handling in a container, so when a child of the - * container is focused, the adjustment is scrolled to show that widget. This function - * sets the vertical alignment. See gtk_scrolled_window_get_vadjustment() for a typical - * way of obtaining the adjustment and gtk_container_set_focus_hadjustment() for setting + * Hooks up an adjustment to focus handling in a container, so when a + * child of the container is focused, the adjustment is scrolled to + * show that widget. This function sets the vertical alignment. See + * gtk_scrolled_window_get_vadjustment() for a typical way of obtaining + * the adjustment and gtk_container_set_focus_hadjustment() for setting * the horizontal adjustment. * - * The adjustments have to be in pixel units and in the same coordinate system as the - * allocation for immediate children of the container. + * The adjustments have to be in pixel units and in the same coordinate + * system as the allocation for immediate children of the container. */ void gtk_container_set_focus_vadjustment (GtkContainer *container, @@ -2238,7 +2239,7 @@ gtk_container_set_focus_vadjustment (GtkContainer *container, * @container: a #GtkContainer * * Retrieves the vertical focus adjustment for the container. See - * gtk_container_set_focus_vadjustment (). + * gtk_container_set_focus_vadjustment(). * * Return value: the vertical focus adjustment, or %NULL if * none has been set. @@ -2258,17 +2259,18 @@ gtk_container_get_focus_vadjustment (GtkContainer *container) /** * gtk_container_set_focus_hadjustment: * @container: a #GtkContainer - * @adjustment: an adjustment which should be adjusted when the focus is moved among the - * descendents of @container + * @adjustment: an adjustment which should be adjusted when the focus is + * moved among the descendents of @container * - * Hooks up an adjustment to focus handling in a container, so when a child of the - * container is focused, the adjustment is scrolled to show that widget. This function - * sets the horizontal alignment. See gtk_scrolled_window_get_hadjustment() for a typical - * way of obtaining the adjustment and gtk_container_set_focus_vadjustment() for setting + * Hooks up an adjustment to focus handling in a container, so when a child + * of the container is focused, the adjustment is scrolled to show that + * widget. This function sets the horizontal alignment. See gt + * k_scrolled_window_get_hadjustment() for a typical way of obtaining the + * adjustment and gtk_container_set_focus_vadjustment() for setting * the vertical adjustment. * - * The adjustments have to be in pixel units and in the same coordinate system as the - * allocation for immediate children of the container. + * The adjustments have to be in pixel units and in the same coordinate + * system as the allocation for immediate children of the container. */ void gtk_container_set_focus_hadjustment (GtkContainer *container, @@ -2426,7 +2428,7 @@ gtk_container_unmap (GtkWidget *widget) * the event's area with the child area, and sending the event. * * In most cases, a container can simply either simply inherit the - * ::expose implementation from #GtkContainer, or, do some drawing + * #GtkWidget::expose implementation from #GtkContainer, or, do some drawing * and then chain to the ::expose implementation from #GtkContainer. **/ void diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c index 8129de9018..93c6ce70f9 100644 --- a/gtk/gtkdialog.c +++ b/gtk/gtkdialog.c @@ -450,15 +450,15 @@ gtk_dialog_new_empty (const gchar *title, * (#GTK_DIALOG_DESTROY_WITH_PARENT). After @flags, button * text/response ID pairs should be listed, with a %NULL pointer ending * the list. Button text can be either a stock ID such as - * #GTK_STOCK_OK, or some arbitrary text. A response ID can be + * #GTK_STOCK_OK, or some arbitrary text. A response ID can be * any positive number, or one of the values in the #GtkResponseType * enumeration. If the user clicks one of these dialog buttons, - * #GtkDialog will emit the "response" signal with the corresponding - * response ID. If a #GtkDialog receives the "delete_event" signal, it - * will emit "response" with a response ID of #GTK_RESPONSE_DELETE_EVENT. - * However, destroying a dialog does not emit the "response" signal; - * so be careful relying on "response" when using - * the #GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, + * #GtkDialog will emit the #GtkDialog::response signal with the corresponding + * response ID. If a #GtkDialog receives the #GtkWidget::delete-event signal, + * it will emit ::response with a response ID of #GTK_RESPONSE_DELETE_EVENT. + * However, destroying a dialog does not emit the ::response signal; + * so be careful relying on ::response when using the + * #GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, * so the first button in the list will be the leftmost button in the dialog. * * Here's a simple example: @@ -541,11 +541,11 @@ action_widget_activated (GtkWidget *widget, GtkDialog *dialog) * @response_id: response ID for @child * * Adds an activatable widget to the action area of a #GtkDialog, - * connecting a signal handler that will emit the "response" signal on - * the dialog when the widget is activated. The widget is appended to - * the end of the dialog's action area. If you want to add a - * non-activatable widget, simply pack it into the - * action_area field of the #GtkDialog struct. + * connecting a signal handler that will emit the #GtkDialog::response + * signal on the dialog when the widget is activated. The widget is + * appended to the end of the dialog's action area. If you want to add a + * non-activatable widget, simply pack it into the @action_area field + * of the #GtkDialog struct. **/ void gtk_dialog_add_action_widget (GtkDialog *dialog, @@ -598,9 +598,9 @@ gtk_dialog_add_action_widget (GtkDialog *dialog, * * Adds a button with the given text (or a stock button, if @button_text is a * stock ID) and sets things up so that clicking the button will emit the - * "response" signal with the given @response_id. The button is appended to the - * end of the dialog's action area. The button widget is returned, but usually - * you don't need it. + * #GtkDialog::response signal with the given @response_id. The button is + * appended to the end of the dialog's action area. The button widget is + * returned, but usually you don't need it. * * Return value: the button widget that was added **/ @@ -821,10 +821,10 @@ gtk_dialog_get_has_separator (GtkDialog *dialog) * @dialog: a #GtkDialog * @response_id: response ID * - * Emits the "response" signal with the given response ID. Used to - * indicate that the user has responded to the dialog in some way; + * Emits the #GtkDialog::response signal with the given response ID. + * Used to indicate that the user has responded to the dialog in some way; * typically either you or gtk_dialog_run() will be monitoring the - * "response" signal and take appropriate action. + * ::response signal and take appropriate action. **/ void gtk_dialog_response (GtkDialog *dialog, @@ -902,22 +902,23 @@ run_destroy_handler (GtkDialog *dialog, gpointer data) * @dialog: a #GtkDialog * * Blocks in a recursive main loop until the @dialog either emits the - * response signal, or is destroyed. If the dialog is destroyed during the call - * to gtk_dialog_run(), gtk_dialog_returns #GTK_RESPONSE_NONE. - * Otherwise, it returns the response ID from the "response" signal emission. + * #GtkDialog::response signal, or is destroyed. If the dialog is + * destroyed during the call to gtk_dialog_run(), gtk_dialog_run() returns + * #GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the + * ::response signal emission. + * * Before entering the recursive main loop, gtk_dialog_run() calls * gtk_widget_show() on the dialog for you. Note that you still * need to show any children of the dialog yourself. * - * During gtk_dialog_run(), the default behavior of "delete_event" is - * disabled; if the dialog receives "delete_event", it will not be + * During gtk_dialog_run(), the default behavior of #GtkWidget::delete-event + * is disabled; if the dialog receives ::delete_event, it will not be * destroyed as windows usually are, and gtk_dialog_run() will return - * #GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog will be - * modal. You can force gtk_dialog_run() to return at any time by - * calling gtk_dialog_response() to emit the "response" - * signal. Destroying the dialog during gtk_dialog_run() is a very bad - * idea, because your post-run code won't know whether the dialog was - * destroyed or not. + * #GTK_RESPONSE_DELETE_EVENT. Also, during gtk_dialog_run() the dialog + * will be modal. You can force gtk_dialog_run() to return at any time by + * calling gtk_dialog_response() to emit the ::response signal. Destroying + * the dialog during gtk_dialog_run() is a very bad idea, because your + * post-run code won't know whether the dialog was destroyed or not. * * After gtk_dialog_run() returns, you are responsible for hiding or * destroying the dialog if you wish to do so. @@ -1115,9 +1116,10 @@ gtk_dialog_set_alternative_button_order_valist (GtkDialog *dialog, * @first_response_id: a response id used by one @dialog's buttons * @Varargs: a list of more response ids of @dialog's buttons, terminated by -1 * - * Sets an alternative button order. If the gtk-alternative-button-order - * setting is set to %TRUE, the dialog buttons are reordered according to - * the order of the response ids passed to this function. + * Sets an alternative button order. If the + * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, + * the dialog buttons are reordered according to the order of the + * response ids passed to this function. * * By default, GTK+ dialogs use the button order advocated by the Gnome * Human @@ -1179,9 +1181,10 @@ gtk_dialog_set_alternative_button_order (GtkDialog *dialog, * @n_params: the number of response ids in @new_order * @new_order: an array of response ids of @dialog's buttons * - * Sets an alternative button order. If the gtk-alternative-button-order - * setting is set to %TRUE, the dialog buttons are reordered according to - * the order of the response ids in @new_order. + * Sets an alternative button order. If the + * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE, + * the dialog buttons are reordered according to the order of the + * response ids in @new_order. * * See gtk_dialog_set_alternative_button_order() for more information. * diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c index da5e1905c4..17cfa78188 100644 --- a/gtk/gtkentry.c +++ b/gtk/gtkentry.c @@ -611,7 +611,8 @@ gtk_entry_class_init (GtkEntryClass *class) /** * GtkEntry:shadow-type: * - * Which kind of shadow to draw around the entry when has-frame is set. + * Which kind of shadow to draw around the entry when + * #GtkEntry:has-frame is set to %TRUE. * * Since: 2.12 */ @@ -880,7 +881,7 @@ gtk_entry_class_init (GtkEntryClass *class) /** * GtkEntry:inner-border: * - * Sets the text area's border between the text and the frame + * Sets the text area's border between the text and the frame. * * Since: 2.10 */ @@ -4439,7 +4440,6 @@ gtk_entry_get_visibility (GtkEntry *entry) * invisible char is an asterisk ('*'). If you set the invisible char * to 0, then the user will get no feedback at all; there will be * no text on the screen as they type. - * **/ void gtk_entry_set_invisible_char (GtkEntry *entry, @@ -4460,7 +4460,7 @@ gtk_entry_set_invisible_char (GtkEntry *entry, * @entry: a #GtkEntry * * Retrieves the character displayed in place of the real characters - * for entries with visisbility set to false. See gtk_entry_set_invisible_char(). + * for entries with visibility set to false. See gtk_entry_set_invisible_char(). * * Return value: the current invisible char, or 0, if the entry does not * show invisible text at all. @@ -4490,7 +4490,7 @@ gtk_entry_set_editable (GtkEntry *entry, * See also gtk_editable_get_chars(). * * Return value: a pointer to the contents of the widget as a - * string. This string points to internally allocated + * string. This string points to internally allocated * storage in the widget and must not be freed, modified or * stored. **/ @@ -4512,7 +4512,7 @@ gtk_entry_select_region (GtkEntry *entry, /** * gtk_entry_set_max_length: - * @entry: a #GtkEntry. + * @entry: a #GtkEntry * @max: the maximum length of the entry, or 0 for no maximum. * (other than the maximum length of entries.) The value passed in will * be clamped to the range 0-65536. @@ -4566,8 +4566,7 @@ gtk_entry_get_max_length (GtkEntry *entry) * * (For experts: if @setting is %TRUE, the entry calls * gtk_window_activate_default() on the window containing the entry, in - * the default handler for the "activate" signal.) - * + * the default handler for the #GtkWidget::activate signal.) **/ void gtk_entry_set_activates_default (GtkEntry *entry, @@ -4609,7 +4608,6 @@ gtk_entry_get_activates_default (GtkEntry *entry) * request, the size can still be affected by * how you pack the widget into containers. If @n_chars is -1, the * size reverts to the default entry size. - * **/ void gtk_entry_set_width_chars (GtkEntry *entry, @@ -4718,7 +4716,7 @@ gtk_entry_set_inner_border (GtkEntry *entry, * gtk_entry_get_inner_border: * @entry: a #GtkEntry * - * This function returns the entry's inner-border property. See + * This function returns the entry's #GtkEntry:inner-border property. See * gtk_entry_set_inner_border() for more information. * * Return value: the entry's #GtkBorder, or %NULL if none was set. @@ -4856,7 +4854,6 @@ gtk_entry_text_index_to_layout_index (GtkEntry *entry, * gtk_entry_layout_index_to_text_index() and * gtk_entry_text_index_to_layout_index() are needed to convert byte * indices in the layout to byte indices in the entry contents. - * **/ void gtk_entry_get_layout_offsets (GtkEntry *entry, @@ -6027,8 +6024,8 @@ connect_completion_signals (GtkEntry *entry, /** * gtk_entry_set_completion: - * @entry: A #GtkEntry. - * @completion: The #GtkEntryCompletion or %NULL. + * @entry: A #GtkEntry + * @completion: The #GtkEntryCompletion or %NULL * * Sets @completion to be the auxiliary completion object to use with @entry. * All further configuration of the completion mechanism is done on @@ -6084,7 +6081,7 @@ gtk_entry_set_completion (GtkEntry *entry, /** * gtk_entry_get_completion: - * @entry: A #GtkEntry. + * @entry: A #GtkEntry * * Returns the auxiliary completion object currently in use by @entry. * @@ -6108,8 +6105,8 @@ gtk_entry_get_completion (GtkEntry *entry) /** * gtk_entry_set_cursor_hadjustment: * @entry: a #GtkEntry - * @adjustment: an adjustment which should be adjusted when the cursor is moved, - * or %NULL + * @adjustment: an adjustment which should be adjusted when the cursor + * is moved, or %NULL * * Hooks up an adjustment to the cursor position in an entry, so that when * the cursor is moved, the adjustment is scrolled to show that position. diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c index 04953d7026..a4012b90e5 100644 --- a/gtk/gtkimage.c +++ b/gtk/gtkimage.c @@ -192,8 +192,8 @@ gtk_image_class_init (GtkImageClass *class) /** * GtkImage:pixel-size: * - * The :pixel-size property can be used to specify a fixed size - * overriding the :icon-size property for images of type + * The "pixel-size" property can be used to specify a fixed size + * overriding the #GtkImage:icon-size property for images of type * %GTK_IMAGE_ICON_NAME. * * Since: 2.6 @@ -218,7 +218,7 @@ gtk_image_class_init (GtkImageClass *class) /** * GtkImage:icon-name: * - * The name of the icon in the icon theme. If the icon theme is + * The name of the icon in the icon theme. If the icon theme is * changed, the image will be updated automatically. * * Since: 2.6 @@ -489,8 +489,7 @@ gtk_image_new_from_pixmap (GdkPixmap *pixmap, * * Creates a #GtkImage widget displaying a @image with a @mask. * A #GdkImage is a client-side image buffer in the pixel format of the - * current display. - * The #GtkImage does not assume a reference to the + * current display. The #GtkImage does not assume a reference to the * image or mask; you still need to unref them if you own references. * #GtkImage will add its own reference rather than adopting yours. * @@ -553,9 +552,9 @@ gtk_image_new_from_file (const gchar *filename) * pixbuf; you still need to unref it if you own references. * #GtkImage will add its own reference rather than adopting yours. * - * Note that this function just creates an #GtkImage from the pixbuf. The - * #GtkImage created will not react to state changes. Should you want that, you - * should use gtk_image_new_from_icon_set(). + * Note that this function just creates an #GtkImage from the pixbuf. The + * #GtkImage created will not react to state changes. Should you want that, + * you should use gtk_image_new_from_icon_set(). * * Return value: a new #GtkImage **/ @@ -615,7 +614,6 @@ gtk_image_new_from_stock (const gchar *stock_id, * icon set; you still need to unref it if you own references. * #GtkImage will add its own reference rather than adopting yours. * - * * Return value: a new #GtkImage **/ GtkWidget* @@ -695,7 +693,6 @@ gtk_image_new_from_icon_name (const gchar *icon_name, * @mask: a #GdkBitmap or %NULL * * See gtk_image_new_from_pixmap() for details. - * **/ void gtk_image_set_from_pixmap (GtkImage *image, @@ -747,7 +744,6 @@ gtk_image_set_from_pixmap (GtkImage *image, * @mask: a #GdkBitmap or %NULL * * See gtk_image_new_from_image() for details. - * **/ void gtk_image_set_from_image (GtkImage *image, @@ -798,7 +794,6 @@ gtk_image_set_from_image (GtkImage *image, * @filename: a filename or %NULL * * See gtk_image_new_from_file() for details. - * **/ void gtk_image_set_from_file (GtkImage *image, @@ -855,7 +850,6 @@ gtk_image_set_from_file (GtkImage *image, * @pixbuf: a #GdkPixbuf or %NULL * * See gtk_image_new_from_pixbuf() for details. - * **/ void gtk_image_set_from_pixbuf (GtkImage *image, @@ -895,7 +889,6 @@ gtk_image_set_from_pixbuf (GtkImage *image, * @size: a stock icon size * * See gtk_image_new_from_stock() for details. - * **/ void gtk_image_set_from_stock (GtkImage *image, @@ -939,7 +932,6 @@ gtk_image_set_from_stock (GtkImage *image, * @size: a stock icon size * * See gtk_image_new_from_icon_set() for details. - * **/ void gtk_image_set_from_icon_set (GtkImage *image, @@ -1088,7 +1080,6 @@ gtk_image_get_storage_type (GtkImage *image) * %GTK_IMAGE_PIXMAP (see gtk_image_get_storage_type()). * The caller of this function does not own a reference to the * returned pixmap and mask. - * **/ void gtk_image_get_pixmap (GtkImage *image, @@ -1138,7 +1129,6 @@ gtk_image_get_image (GtkImage *image, * gtk_image_get_pixbuf: * @image: a #GtkImage * - * * Gets the #GdkPixbuf being displayed by the #GtkImage. * The storage type of the image must be %GTK_IMAGE_EMPTY or * %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()). @@ -1171,7 +1161,6 @@ gtk_image_get_pixbuf (GtkImage *image) * %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()). * The returned string is owned by the #GtkImage and should not * be freed. - * **/ void gtk_image_get_stock (GtkImage *image, @@ -1201,7 +1190,6 @@ gtk_image_get_stock (GtkImage *image, * Gets the icon set and size being displayed by the #GtkImage. * The storage type of the image must be %GTK_IMAGE_EMPTY or * %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()). - * **/ void gtk_image_get_icon_set (GtkImage *image, @@ -1223,7 +1211,6 @@ gtk_image_get_icon_set (GtkImage *image, * gtk_image_get_animation: * @image: a #GtkImage * - * * Gets the #GdkPixbufAnimation being displayed by the #GtkImage. * The storage type of the image must be %GTK_IMAGE_EMPTY or * %GTK_IMAGE_ANIMATION (see gtk_image_get_storage_type()). diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index 0cf9cf7399..e1693b0b0f 100644 --- a/gtk/gtklabel.c +++ b/gtk/gtklabel.c @@ -347,9 +347,9 @@ gtk_label_class_init (GtkLabelClass *class) /** * GtkLabel:wrap-mode: * - * If line wrapping is on (see the wrap property) this controls how - * the line wrapping is done. The default is %PANGO_WRAP_WORD which means - * wrap on word boundaries. + * If line wrapping is on (see the #GtkLabel:wrap property) this controls + * how the line wrapping is done. The default is %PANGO_WRAP_WORD, which + * means wrap on word boundaries. * * Since: 2.10 */ @@ -409,15 +409,17 @@ gtk_label_class_init (GtkLabelClass *class) /** * GtkLabel:ellipsize: * - * The preferred place to ellipsize the string, if the label does not have - * enough room to display the entire string, specified as a #PangoEllisizeMode. + * The preferred place to ellipsize the string, if the label does + * not have enough room to display the entire string, specified as a + * #PangoEllisizeMode. * - * Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE - * has the side-effect that the label requests only enough space to display the - * ellipsis "...". In particular, this means that ellipsizing labels don't - * work well in notebook tabs, unless the tab's ::tab-expand property is set - * to %TRUE. Other means to set a label's width are - * gtk_widget_set_size_request() and gtk_label_set_width_chars(). + * Note that setting this property to a value other than + * %PANGO_ELLIPSIZE_NONE has the side-effect that the label requests + * only enough space to display the ellipsis "...". In particular, this + * means that ellipsizing labels do not work well in notebook tabs, unless + * the tab's #GtkNotebook:tab-expand property is set to %TRUE. Other ways + * to set a label's width are gtk_widget_set_size_request() and + * gtk_label_set_width_chars(). * * Since: 2.6 */ @@ -436,8 +438,8 @@ gtk_label_class_init (GtkLabelClass *class) * The desired width of the label, in characters. If this property is set to * -1, the width will be calculated automatically, otherwise the label will * request either 3 characters or the property value, whichever is greater. - * If the width-chars property is set to a positive value, then the - * max-width-chars property is ignored. + * If the "width-chars" property is set to a positive value, then the + * #GtkLabel:max-width-chars property is ignored. * * Since: 2.6 **/ @@ -496,8 +498,8 @@ gtk_label_class_init (GtkLabelClass *class) * The desired maximum width of the label, in characters. If this property * is set to -1, the width will be calculated automatically, otherwise the * label will request space for no more than the requested number of - * characters. If the width-chars property is set to a positive value, - * then the max-width-chars property is ignored. + * characters. If the #GtkLabel:width-chars property is set to a positive + * value, then the "max-width-chars" property is ignored. * * Since: 2.6 **/ @@ -844,12 +846,11 @@ gtk_label_new (const gchar *str) * to activate another widget, chosen automatically, or explicitly using * gtk_label_set_mnemonic_widget(). * - * If gtk_label_set_mnemonic_widget() - * is not called, then the first activatable ancestor of the #GtkLabel - * will be chosen as the mnemonic widget. For instance, if the - * label is inside a button or menu item, the button or menu item will - * automatically become the mnemonic widget and be activated by - * the mnemonic. + * If gtk_label_set_mnemonic_widget() is not called, then the first + * activatable ancestor of the #GtkLabel will be chosen as the mnemonic + * widget. For instance, if the label is inside a button or menu item, + * the button or menu item will automatically become the mnemonic widget + * and be activated by the mnemonic. * * Return value: the new #GtkLabel **/ @@ -1056,7 +1057,7 @@ label_mnemonic_widget_weak_notify (gpointer data, * @widget: the target #GtkWidget * * If the label has been set so that it has an mnemonic key (using - * i.e. gtk_label_set_markup_with_mnemonic(), + * i.e. gtk_label_set_markup_with_mnemonic(), * gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic() * or the "use_underline" property) the label can be associated with a * widget that is the target of the mnemonic. When the label is inside @@ -1065,9 +1066,10 @@ label_mnemonic_widget_weak_notify (gpointer data, * (i.e. when the target is a #GtkEntry next to the label) you need to * set it explicitly using this function. * - * The target widget will be accelerated by emitting "mnemonic_activate" on it. - * The default handler for this signal will activate the widget if there are no - * mnemonic collisions and toggle focus between the colliding widgets otherwise. + * The target widget will be accelerated by emitting the + * GtkWidget::mnemonic-activate signal on it. The default handler for + * this signal will activate the widget if there are no mnemonic collisions + * and toggle focus between the colliding widgets otherwise. **/ void gtk_label_set_mnemonic_widget (GtkLabel *label, @@ -1101,7 +1103,7 @@ gtk_label_set_mnemonic_widget (GtkLabel *label, * @label: a #GtkLabel * * Retrieves the target of the mnemonic (keyboard shortcut) of this - * label. See gtk_label_set_mnemonic_widget (). + * label. See gtk_label_set_mnemonic_widget(). * * Return value: the target of the label's mnemonic, or %NULL if none * has been set and the default algorithm will be used. @@ -1242,9 +1244,9 @@ gtk_label_recalculate (GtkLabel *label) /** * gtk_label_set_text: * @label: a #GtkLabel - * @str: The text you want to set. + * @str: The text you want to set * - * Sets the text within the #GtkLabel widget. It overwrites any text that + * Sets the text within the #GtkLabel widget. It overwrites any text that * was there before. * * This will also clear any previously set mnemonic accelerators. @@ -1273,8 +1275,8 @@ gtk_label_set_text (GtkLabel *label, * * Sets a #PangoAttrList; the attributes in the list are applied to the * label text. The attributes set with this function will be ignored - * if the "use_underline" property or the "use_markup" property - * is %TRUE. + * if the #GtkLabel:use-underline" or #GtkLabel:use-markup properties + * are set to %TRUE. **/ void gtk_label_set_attributes (GtkLabel *label, @@ -1316,7 +1318,8 @@ gtk_label_get_attributes (GtkLabel *label) * * Sets the text of the label. The label is interpreted as * including embedded underlines and/or Pango markup depending - * on the values of label->use_underline and label->use_markup. + * on the values of the #GtkLabel:use-underline" and + * #GtkLabel:use-markup properties. **/ void gtk_label_set_label (GtkLabel *label, @@ -1341,7 +1344,7 @@ gtk_label_set_label (GtkLabel *label, * * Fetches the text from a label widget including any embedded * underlines indicating mnemonics and Pango markup. (See - * gtk_label_get_text ()). + * gtk_label_get_text()). * * Return value: the text of the label widget. This string is * owned by the widget and must not be modified or freed. @@ -1401,7 +1404,7 @@ set_markup (GtkLabel *label, * * Parses @str which is marked up with the Pango text markup language, setting the - * label's text and attribute list based on the parse results. If the @str is + * label's text and attribute list based on the parse results. If the @str is * external data, you may need to escape it with g_markup_escape_text() or * g_markup_printf_escaped(): * @@ -1439,8 +1442,8 @@ gtk_label_set_markup (GtkLabel *label, * If characters in @str are preceded by an underscore, they are underlined * indicating that they represent a keyboard accelerator called a mnemonic. * - * The mnemonic key can be used to activate another widget, chosen automatically, - * or explicitly using gtk_label_set_mnemonic_widget(). + * The mnemonic key can be used to activate another widget, chosen + * automatically, or explicitly using gtk_label_set_mnemonic_widget(). **/ void gtk_label_set_markup_with_mnemonic (GtkLabel *label, @@ -1563,7 +1566,7 @@ gtk_label_set_pattern (GtkLabel *label, * @jtype: a #GtkJustification * * Sets the alignment of the lines in the text of the label relative to - * each other. %GTK_JUSTIFY_LEFT is the default value when the + * each other. %GTK_JUSTIFY_LEFT is the default value when the * widget is first created with gtk_label_new(). If you instead want * to set the alignment of the label as a whole, use * gtk_misc_set_alignment() instead. gtk_label_set_justify() has no @@ -1592,7 +1595,7 @@ gtk_label_set_justify (GtkLabel *label, * gtk_label_get_justify: * @label: a #GtkLabel * - * Returns the justification of the label. See gtk_label_set_justify (). + * Returns the justification of the label. See gtk_label_set_justify(). * * Return value: #GtkJustification **/ @@ -1609,8 +1612,8 @@ gtk_label_get_justify (GtkLabel *label) * @label: a #GtkLabel * @mode: a #PangoEllipsizeMode * - * Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there - * is not enough space to render the entire string. + * Sets the mode used to ellipsize (add an ellipsis: "...") to the text + * if there is not enough space to render the entire string. * * Since: 2.6 **/ @@ -1751,8 +1754,8 @@ gtk_label_get_max_width_chars (GtkLabel *label) * @label: a #GtkLabel * @wrap: the setting * - * Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break - * lines if text exceeds the widget's size. %FALSE lets the text get cut off + * Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break + * lines if text exceeds the widget's size. %FALSE lets the text get cut off * by the edge of the widget if it exceeds the widget size. * * Note that setting line wrapping to %TRUE does not make the label @@ -1783,7 +1786,8 @@ gtk_label_set_line_wrap (GtkLabel *label, * gtk_label_get_line_wrap: * @label: a #GtkLabel * - * Returns whether lines in the label are automatically wrapped. See gtk_label_set_line_wrap (). + * Returns whether lines in the label are automatically wrapped. + * See gtk_label_set_line_wrap(). * * Return value: %TRUE if the lines of the label are automatically wrapped. */ @@ -1825,7 +1829,7 @@ gtk_label_set_line_wrap_mode (GtkLabel *label, * gtk_label_get_line_wrap_mode: * @label: a #GtkLabel * - * Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode (). + * Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode(). * * Return value: %TRUE if the lines of the label are automatically wrapped. * @@ -2685,8 +2689,8 @@ gtk_label_parse_uline (GtkLabel *label, * Sets the label's text from the string @str. * If characters in @str are preceded by an underscore, they are underlined * indicating that they represent a keyboard accelerator called a mnemonic. - * The mnemonic key can be used to activate another widget, chosen automatically, - * or explicitly using gtk_label_set_mnemonic_widget(). + * The mnemonic key can be used to activate another widget, chosen + * automatically, or explicitly using gtk_label_set_mnemonic_widget(). **/ void gtk_label_set_text_with_mnemonic (GtkLabel *label, @@ -3181,7 +3185,6 @@ gtk_label_destroy_window (GtkLabel *label) * * Selectable labels allow the user to select text from the label, for * copy-and-paste. - * **/ void gtk_label_set_selectable (GtkLabel *label, @@ -3315,7 +3318,7 @@ gtk_label_set_angle (GtkLabel *label, * @label: a #GtkLabel * * Gets the angle of rotation for the label. See - * gtk_label_set_angle. + * gtk_label_set_angle(). * * Return value: the angle of rotation for the label * @@ -3463,7 +3466,6 @@ gtk_label_select_region_index (GtkLabel *label, * See gtk_label_set_selectable(). If the label is not selectable, * this function has no effect. If @start_offset or * @end_offset are -1, then the end of the label will be substituted. - * **/ void gtk_label_select_region (GtkLabel *label, @@ -3590,7 +3592,6 @@ gtk_label_get_layout (GtkLabel *label) * inside it, since labels are a #GTK_NO_WINDOW widget. Remember * when using the #PangoLayout functions you need to convert to * and from pixels using PANGO_PIXELS() or #PANGO_SCALE. - * **/ void gtk_label_get_layout_offsets (GtkLabel *label, @@ -3664,7 +3665,7 @@ gtk_label_set_use_underline (GtkLabel *label, * @label: a #GtkLabel * * Returns whether an embedded underline in the label indicates a - * mnemonic. See gtk_label_set_use_underline (). + * mnemonic. See gtk_label_set_use_underline(). * * Return value: %TRUE whether an embedded underline in the label indicates * the mnemonic accelerator keys. diff --git a/gtk/gtkmisc.c b/gtk/gtkmisc.c index 591091dc65..71a84fb2d5 100644 --- a/gtk/gtkmisc.c +++ b/gtk/gtkmisc.c @@ -225,8 +225,8 @@ gtk_misc_set_alignment (GtkMisc *misc, * @xalign: location to store X alignment of @misc, or %NULL * @yalign: location to store Y alignment of @misc, or %NULL * - * Gets the X and Y alignment of the widget within its allocation. See - * gtk_misc_set_alignment(). + * Gets the X and Y alignment of the widget within its allocation. + * See gtk_misc_set_alignment(). **/ void gtk_misc_get_alignment (GtkMisc *misc, @@ -286,7 +286,8 @@ gtk_misc_set_padding (GtkMisc *misc, * @xpad: location to store padding in the X direction, or %NULL * @ypad: location to store padding in the Y direction, or %NULL * - * Gets the padding in the X and Y directions of the widget. See gtk_misc_set_padding(). + * Gets the padding in the X and Y directions of the widget. + * See gtk_misc_set_padding(). **/ void gtk_misc_get_padding (GtkMisc *misc, diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c index 4b898ad028..f7e43a9f56 100644 --- a/gtk/gtksettings.c +++ b/gtk/gtksettings.c @@ -220,8 +220,8 @@ gtk_settings_class_init (GtkSettingsClass *class) * * Whether the cursor should blink. * - * Also see the gtk-cursor-blink-timeout setting, which allows - * more flexible control over cursor blinking. + * Also see the #GtkSettings:gtk-cursor-blink-timeout setting, + * which allows more flexible control over cursor blinking. */ result = settings_install_property_parser (class, g_param_spec_boolean ("gtk-cursor-blink", @@ -247,7 +247,7 @@ gtk_settings_class_init (GtkSettingsClass *class) * The timer is reset after each user interaction. * * Setting this to zero has the same effect as setting - * gtk-cursor-blinks to %FALSE. + * #GtkSettings:gtk-cursor-blinks to %FALSE. * * Since: 2.12 */ @@ -432,8 +432,8 @@ gtk_settings_class_init (GtkSettingsClass *class) * GtkSettings:gtk-alternative-sort-arrows: * * Controls the direction of the sort indicators in sorted list and tree - * views. By default an arrow pointing down means the column is sorted - * in ascending order. When set to %TRUE, this order will be inverted. + * views. By default an arrow pointing down means the column is sorted + * in ascending order. When set to %TRUE, this order will be inverted. * * Since: 2.12 */ @@ -585,10 +585,10 @@ gtk_settings_class_init (GtkSettingsClass *class) * browse mode is enabled, in milliseconds. * * Browse mode is enabled when the mouse pointer moves off an object - * where a tooltip was currently being displayed. If the mouse pointer + * where a tooltip was currently being displayed. If the mouse pointer * hits another object before the browse mode timeout expires (see - * gtk-tooltip-browse-mode-timeout), it will take the amount of - * milliseconds specified by this setting to popup the tooltip + * #GtkSettings:gtk-tooltip-browse-mode-timeout), it will take the + * amount of milliseconds specified by this setting to popup the tooltip * for the new object. * * Since: 2.12 @@ -610,7 +610,7 @@ gtk_settings_class_init (GtkSettingsClass *class) * Amount of time, in milliseconds, after which the browse mode * will be disabled. * - * See GtkSettings:gtk-tooltip-browse-timeout for more information + * See #GtkSettings:gtk-tooltip-browse-timeout for more information * about browse mode. * * Since: 2.12 @@ -687,8 +687,8 @@ gtk_settings_class_init (GtkSettingsClass *class) /** * GtkSettings:color-hash: * - * Holds a hash table representation of the gtk-color-scheme setting, - * mapping color names to #GdkColors. + * Holds a hash table representation of the #GtkSettings:gtk-color-scheme + * setting, mapping color names to #GdkColors. * * Since: 2.10 */ diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 31a8c5c07f..dd7631c4c1 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -571,9 +571,9 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:has-tooltip: * - * Enables or disables the emission of GtkWidget::query-tooltip on @widget. A - * value of %TRUE indicates that @widget can have a tooltip, in this case - * the widget will be queried using GtkWidget::query-tooltip to determine + * Enables or disables the emission of #GtkWidget::query-tooltip on @widget. + * A value of %TRUE indicates that @widget can have a tooltip, in this case + * the widget will be queried using #GtkWidget::query-tooltip to determine * whether it will provide a tooltip or not. * * Since: 2.12 @@ -594,9 +594,9 @@ gtk_widget_class_init (GtkWidgetClass *klass) * Also see gtk_tooltip_set_markup(). * * This is a convenience property which will take care of getting the - * tooltip shown if the given string is not %NULL: GtkWidget:has-tooltip + * tooltip shown if the given string is not %NULL: #GtkWidget:has-tooltip * will automatically be set to %TRUE and there will be taken care of - * GtkWidget::query-tooltip in the default signal handler. + * #GtkWidget::query-tooltip in the default signal handler. * * Since: 2.12 */ @@ -690,8 +690,8 @@ gtk_widget_class_init (GtkWidgetClass *klass) * @old_parent: the previous parent, or %NULL if the widget * just got its initial parent. * - * The parent-set signal is emitted when a new parent has been set - * on a widget. + * The ::parent-set signal is emitted when a new parent + * has been set on a widget. */ widget_signals[PARENT_SET] = g_signal_new (I_("parent_set"), @@ -717,7 +717,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) * @previous_style: the previous style, or %NULL if the widget * just got its initial style * - * The style-set signal is emitted when a new style has been set + * The ::style-set signal is emitted when a new style has been set * on a widget. Note that style-modifying functions like * gtk_widget_modify_base() also cause this signal to be emitted. */ @@ -767,10 +767,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::child-notify: - * @widget: the object which received the signal. - * @pspec: the #GParamSpec of the changed child property. + * @widget: the object which received the signal + * @pspec: the #GParamSpec of the changed child property * - * The ::child-notify signal is emitted for each child property that has + * The ::child-notify signal is emitted for each + * child property that has * changed on an object. The signal's detail holds the property name. */ widget_signals[CHILD_NOTIFY] = @@ -873,9 +874,10 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::keynav-failed: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @direction: the direction of movement * + * Gets emitted if keyboard navigation fails. * See gtk_widget_keynav_failed() for details. * * Returns: %TRUE if stopping keyboard navigation is fine, %FALSE @@ -896,7 +898,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::delete-event: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @event: the event which triggered this signal * * The ::delete-event signal is emitted if a user requests that @@ -1114,8 +1116,8 @@ gtk_widget_class_init (GtkWidgetClass *klass) * * The ::drag-leave signal is emitted on the drop site when the cursor * leaves the widget. A typical reason to connect to this signal is to - * undo things done in ::drag-motion, e.g. undo highlighting with - * gtk_drag_unhighlight() + * undo things done in #GtkWidget::drag-motion, e.g. undo highlighting + * with gtk_drag_unhighlight() */ widget_signals[DRAG_LEAVE] = g_signal_new (I_("drag_leave"), @@ -1130,12 +1132,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-begin: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * - * The ::drag-begin signal is emitted on the drag source when a drag is started. - * A typical reason to connect to this signal is to set up a custom drag icon with - * gtk_drag_source_set_icon(). + * The ::drag-begin signal is emitted on the drag source when a drag is + * started. A typical reason to connect to this signal is to set up a + * custom drag icon with gtk_drag_source_set_icon(). */ widget_signals[DRAG_BEGIN] = g_signal_new (I_("drag_begin"), @@ -1149,11 +1151,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-end: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * - * The ::drag-end signal is emitted on the drag source when a drag is finished. - * A typical reason to connect to this signal is to undo things done in ::drag-begin. + * The ::drag-end signal is emitted on the drag source when a drag is + * finished. A typical reason to connect to this signal is to undo + * things done in #GtkWidget::drag-begin. */ widget_signals[DRAG_END] = g_signal_new (I_("drag_end"), @@ -1167,13 +1170,13 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-data-delete: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * * The ::drag-data-delete signal is emitted on the drag source when a drag * with the action %GDK_ACTION_MOVE is successfully completed. The signal * handler is responsible for deleting the data that has been dropped. What - * "delete" means, depends on the context of the drag operation. + * "delete" means depends on the context of the drag operation. */ widget_signals[DRAG_DATA_DELETE] = g_signal_new (I_("drag_data_delete"), @@ -1187,9 +1190,9 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-failed: - * @widget: the object which received the signal. - * @drag_context: the drag context. - * @result: the result of the drag operation. + * @widget: the object which received the signal + * @drag_context: the drag context + * @result: the result of the drag operation * * The ::drag-failed signal is emitted on the drag source when a drag has * failed. The signal handler may hook custom code to handle a failed DND @@ -1213,7 +1216,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-motion: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * @x: the x coordinate of the current cursor position * @y: the y coordinate of the current cursor position @@ -1230,13 +1233,13 @@ gtk_widget_class_init (GtkWidgetClass *klass) * decision whether the drop will be accepted or rejected can't be made * based solely on the cursor position and the type of the data, the handler * may inspect the dragged data by calling gtk_drag_get_data() and defer the - * gdk_drag_status() call to the ::drag-data-received handler. + * gdk_drag_status() call to the #GtkWidget::drag-data-received handler. * - * Note that there is no ::drag-enter signal. The drag receiver has to keep - * track of whether he has received any ::drag-motion signals since the last - * ::drag-leave and if not, treat the ::drag-motion signal as an "enter" signal. - * Upon an "enter", the handler will typically highlight the drop site with - * gtk_drag_highlight(). + * Note that there is no drag-enter signal. The drag receiver has to keep + * track of whether he has received any drag-motion signals since the last + * #GtkWidget::drag-leave and if not, treat the drag-motion signal as an + * "enter" signal. Upon an "enter", the handler will typically highlight + * the drop site with gtk_drag_highlight(). * * * static void @@ -1316,22 +1319,23 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-drop: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * @x: the x coordinate of the current cursor position * @y: the y coordinate of the current cursor position * @time: the timestamp of the motion event * @returns: whether the cursor position is in a drop zone * - * The ::drag-drop signal is emitted on the drop site when the user drops the - * data onto the widget. The signal handler must determine whether the cursor - * position is in a drop zone or not. If it is not in a drop zone, it returns - * %FALSE and no further processing is necessary. Otherwise, the handler returns - * %TRUE. In this case, the handler must ensure that gtk_drag_finish() is called - * to let the source know that the drop is done. The call to gtk_drag_finish() - * can be done either directly or in a ::drag-data-received handler which gets - * triggered by calling gtk_drag_get_data() to receive the data for one or more - * of the supported targets. + * The ::drag-drop signal is emitted on the drop site when the user drops + * the data onto the widget. The signal handler must determine whether + * the cursor position is in a drop zone or not. If it is not in a drop + * zone, it returns %FALSE and no further processing is necessary. + * Otherwise, the handler returns %TRUE. In this case, the handler must + * ensure that gtk_drag_finish() is called to let the source know that + * the drop is done. The call to gtk_drag_finish() can be done either + * directly or in a #GtkWidget::drag-data-received handler which gets + * triggered by calling gtk_drag_get_data() to receive the data for one + * or more of the supported targets. */ widget_signals[DRAG_DROP] = g_signal_new (I_("drag_drop"), @@ -1348,16 +1352,18 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-data-get: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * @data: the #GtkSelectionData to be filled with the dragged data - * @info: the info that has been registered with the target in the #GtkTargetList. + * @info: the info that has been registered with the target in the + * #GtkTargetList * @time: the timestamp at which the data was requested * - * The ::drag-data-get signal is emitted on the drag source when the drop site - * requests the data which is dragged. It is the responsibility of the signal - * handler to fill @data with the data in the format which is indicated by @info. - * See gtk_selection_data_set() and gtk_selection_data_set_text(). + * The ::drag-data-get signal is emitted on the drag source when the drop + * site requests the data which is dragged. It is the responsibility of + * the signal handler to fill @data with the data in the format which + * is indicated by @info. See gtk_selection_data_set() and + * gtk_selection_data_set_text(). */ widget_signals[DRAG_DATA_GET] = g_signal_new (I_("drag_data_get"), @@ -1374,26 +1380,27 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::drag-data-received: - * @widget: the object which received the signal. + * @widget: the object which received the signal * @drag_context: the drag context * @x: where the drop happened * @y: where the drop happened * @data: the received data - * @info: the info that has been registered with the target in the #GtkTargetList. + * @info: the info that has been registered with the target in the + * #GtkTargetList * @time: the timestamp at which the data was received * * The ::drag-data-received signal is emitted on the drop site when the dragged - * data has been received. If the data was received in order to determine whether - * the drop will be accepted, the handler is expected to call gdk_drag_status() - * and not finish the drag. If the data was received in - * response to a ::drag-drop signal (and this is the last target to be received), - * the handler for this signal is expected to process the received data and then - * call gtk_drag_finish(), setting the @success parameter depending on whether - * the data was processed successfully. + * data has been received. If the data was received in order to determine + * whether the drop will be accepted, the handler is expected to call + * gdk_drag_status() and not finish the drag. If the + * data was received in response to a #GtkWidget::drag-drop signal (and this + * is the last target to be received), the handler for this signal is expected + * to process the received data and then call gtk_drag_finish(), setting the + * @success parameter depending on whether the data was processed successfully. * * The handler may inspect and modify @drag_context->action before calling - * gtk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as shown in the following - * example: + * gtk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as shown in the + * following example: * * void * drag_data_received (GtkWidget *widget, @@ -1514,18 +1521,18 @@ gtk_widget_class_init (GtkWidgetClass *klass) * GtkWidget::query-tooltip: * @widget: the object which received the signal * @x: the x coordinate of the cursor position where the request has been - * emitted, relative to widget->window + * emitted, relative to @widget->window * @y: the y coordinate of the cursor position where the request has been - * emitted, relative to widget->window + * emitted, relative to @widget->window * @keyboard_mode: %TRUE if the tooltip was trigged using the keyboard * @tooltip: a #GtkTooltip * - * Emitted when the gtk-tooltip-timeout has expired with the cursor - * hovering "above" @widget; or emitted when @widget got focus in - * keyboard mode. + * Emitted when the #GtkSettings:gtk-tooltip-timeout has expired with + * the cursor hovering "above" @widget; or emitted when @widget got + * focus in keyboard mode. * * Using the given coordinates, the signal handler should determine - * whether a tooltip should be shown for @widget. If this is the case + * whether a tooltip should be shown for @widget. If this is the case * %TRUE should be returned, %FALSE otherwise. Note that if * @keyboard_mode is %TRUE, the values of @x and @y are undefined and * should not be used. @@ -1552,14 +1559,14 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget::popup-menu * @widget: the object which received the signal - * @returns: TRUE if a menu was activated + * @returns: %TRUE if a menu was activated * - * This signal gets emitted whenever a widget should pop up a context-sensitive - * menu. This usually happens through the standard key binding mechanism; by + * This signal gets emitted whenever a widget should pop up a context menu. + * This usually happens through the standard key binding mechanism; by * pressing a certain key while a widget is focused, the user can cause the - * widget to pop up a menu. For example, the #GtkEntry widget creates a menu - * with clipboard commands. See for an - * example of how to use this signal. + * widget to pop up a menu. For example, the #GtkEntry widget creates a + * menu with clipboard commands. See + * for an example of how to use this signal. */ widget_signals[POPUP_MENU] = g_signal_new (I_("popup_menu"), @@ -1687,7 +1694,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:draw-border: * - * The "draw-border" property defines the size of areas outside + * The "draw-border" style property defines the size of areas outside * the widget's allocation to draw. * * Since: 2.8 @@ -1702,7 +1709,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:link-color: * - * The "link-color" property defines the color of unvisited links. + * The "link-color" style property defines the color of unvisited links. * * Since: 2.10 */ @@ -1716,7 +1723,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:visited-link-color: * - * The "visited-link-color" property defines the color of visited links. + * The "visited-link-color" style property defines the color of visited links. * * Since: 2.10 */ @@ -1730,7 +1737,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:wide-separators: * - * The "wide-separators" property defines whether separators have + * The "wide-separators" style property defines whether separators have * configurable width and should be drawn using a box instead of a line. * * Since: 2.10 @@ -1745,8 +1752,8 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:separator-width: * - * The "separator-width" property defines the width of separators. - * This property only takes effect if "wide-separators" is %TRUE. + * The "separator-width" style property defines the width of separators. + * This property only takes effect if #GtkWidget:wide-separators is %TRUE. * * Since: 2.10 */ @@ -1760,8 +1767,8 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:separator-height: * - * The "separator-height" property defines the height of separators. - * This property only takes effect if "wide-separators" is %TRUE. + * The "separator-height" style property defines the height of separators. + * This property only takes effect if #GtkWidget:wide-separators is %TRUE. * * Since: 2.10 */ @@ -1775,7 +1782,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:scroll-arrow-hlength: * - * The "scroll-arrow-hlength" property defines the length of + * The "scroll-arrow-hlength" style property defines the length of * horizontal scroll arrows. * * Since: 2.10 @@ -1790,7 +1797,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) /** * GtkWidget:scroll-arrow-vlength: * - * The "scroll-arrow-vlength" property defines the length of + * The "scroll-arrow-vlength" style property defines the length of * vertical scroll arrows. * * Since: 2.10 @@ -2075,8 +2082,9 @@ gtk_widget_dispatch_child_properties_changed (GtkWidget *widget, * gtk_widget_freeze_child_notify: * @widget: a #GtkWidget * - * Stops emission of "child-notify" signals on @widget. The signals are - * queued until gtk_widget_thaw_child_notify() is called on @widget. + * Stops emission of #GtkWidget::child-notify signals on @widget. The + * signals are queued until gtk_widget_thaw_child_notify() is called + * on @widget. * * This is the analogue of g_object_freeze_notify() for child properties. **/ @@ -2097,9 +2105,9 @@ gtk_widget_freeze_child_notify (GtkWidget *widget) * gtk_widget_child_notify: * @widget: a #GtkWidget * @child_property: the name of a child property installed on the - * class of @widget's parent. + * class of @widget's parent * - * Emits a "child-notify" signal for the + * Emits a #GtkWidget::child-notify signal for the * child property @child_property * on @widget. * @@ -2141,7 +2149,8 @@ gtk_widget_child_notify (GtkWidget *widget, * @widget: a #GtkWidget * * Reverts the effect of a previous call to gtk_widget_freeze_child_notify(). - * This causes all queued "child-notify" signals on @widget to be emitted. + * This causes all queued #GtkWidget::child-notify signals on @widget to be + * emitted. */ void gtk_widget_thaw_child_notify (GtkWidget *widget) @@ -2168,7 +2177,8 @@ gtk_widget_thaw_child_notify (GtkWidget *widget) * gtk_widget_new: * @type: type ID of the widget to create * @first_property_name: name of first property to set - * @Varargs: value of first property, followed by more properties, %NULL-terminated + * @Varargs: value of first property, followed by more properties, + * %NULL-terminated * * This is a convenience function for creating a widget and setting * its properties in one go. For example you might write: @@ -2200,10 +2210,12 @@ gtk_widget_new (GType type, * gtk_widget_set: * @widget: a #GtkWidget * @first_property_name: name of first property to set - * @Varargs: value of first property, followed by more properties, %NULL-terminated + * @Varargs: value of first property, followed by more properties, + * %NULL-terminated * - * Like g_object_set() - there's no reason to use this instead of - * g_object_set(). + * Precursor of g_object_set(). + * + * Deprecated: Use g_object_set() instead. **/ void gtk_widget_set (GtkWidget *widget, @@ -2333,7 +2345,6 @@ gtk_widget_unparent (GtkWidget *widget) * In most cases, only toplevel widgets (windows) require explicit * destruction, because when you destroy a toplevel its children will * be destroyed as well. - * **/ void gtk_widget_destroy (GtkWidget *widget) @@ -2355,7 +2366,6 @@ gtk_widget_destroy (GtkWidget *widget) * as user data. Then when the widget is destroyed, the variable will * be set to %NULL. Useful for example to avoid multiple copies * of the same dialog. - * **/ void gtk_widget_destroyed (GtkWidget *widget, @@ -2384,7 +2394,6 @@ gtk_widget_destroyed (GtkWidget *widget, * When a toplevel container is shown, it is immediately realized and * mapped; other shown widgets are realized and mapped when their * toplevel container is realized and mapped. - * **/ void gtk_widget_show (GtkWidget *widget) @@ -2504,18 +2513,18 @@ gtk_widget_real_hide (GtkWidget *widget) * gtk_widget_hide_on_delete: * @widget: a #GtkWidget * - * Utility function; intended to be connected to the "delete_event" + * Utility function; intended to be connected to the #GtkWidget::delete-event * signal on a #GtkWindow. The function calls gtk_widget_hide() on its - * argument, then returns %TRUE. If connected to "delete_event", the + * argument, then returns %TRUE. If connected to ::delete-event, the * result is that clicking the close button for a window (on the * window frame, top right corner usually) will hide but not destroy - * the window. By default, GTK+ destroys windows when "delete_event" + * the window. By default, GTK+ destroys windows when ::delete-event * is received. * * Return value: %TRUE **/ gboolean -gtk_widget_hide_on_delete (GtkWidget *widget) +gtk_widget_hide_on_delete (GtkWidget *widget) { g_return_val_if_fail (GTK_IS_WIDGET (widget), FALSE); @@ -2575,7 +2584,6 @@ gtk_widget_hide_all (GtkWidget *widget) * * This function is only for use in widget implementations. Causes * a widget to be mapped if it isn't already. - * **/ void gtk_widget_map (GtkWidget *widget) @@ -2602,7 +2610,6 @@ gtk_widget_map (GtkWidget *widget) * * This function is only for use in widget implementations. Causes * a widget to be unmapped if it's currently mapped. - * **/ void gtk_widget_unmap (GtkWidget *widget) @@ -2683,9 +2690,8 @@ gtk_widget_set_extension_events_internal (GtkWidget *widget, * isn't very useful otherwise. Many times when you think you might * need it, a better approach is to connect to a signal that will be * called after the widget is realized automatically, such as - * "expose_event". Or simply g_signal_connect_after() to the - * "realize" signal. - * + * GtkWidget::expose-event. Or simply g_signal_connect_after() to the + * GtkWidget::realize signal. **/ void gtk_widget_realize (GtkWidget *widget) @@ -2748,7 +2754,6 @@ gtk_widget_realize (GtkWidget *widget) * This function is only useful in widget implementations. * Causes a widget to be unrealized (frees all GDK resources * associated with the widget, such as @widget->window). - * **/ void gtk_widget_unrealize (GtkWidget *widget) @@ -2785,7 +2790,7 @@ gtk_widget_unrealize (GtkWidget *widget) * * Invalidates the rectangular area of @widget defined by @x, @y, * @width and @height by calling gdk_window_invalidate_rect() on the - * widget's window and all its child windows. Once the main loop + * widget's window and all its child windows. Once the main loop * becomes idle (after the current batch of events has been processed, * roughly), the window will receive expose events for the union of * all regions that have been invalidated. @@ -2803,7 +2808,6 @@ gtk_widget_unrealize (GtkWidget *widget) * The advantage of adding to the invalidated region compared to * simply drawing immediately is efficiency; using an invalid region * ensures that you only have to redraw one time. - * **/ void gtk_widget_queue_draw_area (GtkWidget *widget, @@ -2925,7 +2929,6 @@ gtk_widget_get_draw_rectangle (GtkWidget *widget, * * Equivalent to calling gtk_widget_queue_draw_area() for the * entire area of a widget. - * **/ void gtk_widget_queue_draw (GtkWidget *widget) @@ -2960,7 +2963,7 @@ gtk_widget_queue_draw (GtkWidget *widget) * gtk_widget_queue_draw_area() would not. Now both functions ensure * the background will be redrawn. * - * @Deprecated: Use gtk_widget_queue_draw_area() instead. + * Deprecated: Use gtk_widget_queue_draw_area() instead. **/ void gtk_widget_queue_clear_area (GtkWidget *widget, @@ -2980,7 +2983,7 @@ gtk_widget_queue_clear_area (GtkWidget *widget, * * This function does the same as gtk_widget_queue_draw(). * - * @Deprecated: Use gtk_widget_queue_draw() instead. + * Deprecated: Use gtk_widget_queue_draw() instead. **/ void gtk_widget_queue_clear (GtkWidget *widget) @@ -3015,8 +3018,8 @@ gtk_widget_queue_resize (GtkWidget *widget) * gtk_widget_queue_resize_no_redraw: * @widget: a #GtkWidget * - * This function works like gtk_widget_queue_resize(), except that the - * widget is not invalidated. + * This function works like gtk_widget_queue_resize(), + * except that the widget is not invalidated. * * Since: 2.4 **/ @@ -3041,7 +3044,6 @@ gtk_widget_queue_resize_no_redraw (GtkWidget *widget) * Usually you don't want to update the region immediately for * performance reasons, so in general gtk_widget_queue_draw_area() is * a better choice if you want to draw a region of a widget. - * **/ void gtk_widget_draw (GtkWidget *widget, @@ -3205,7 +3207,6 @@ gtk_widget_queue_shallow_draw (GtkWidget *widget) * * This function is only used by #GtkContainer subclasses, to assign a size * and position to their child widgets. - * **/ void gtk_widget_size_allocate (GtkWidget *widget, @@ -3512,7 +3513,7 @@ gtk_widget_real_can_activate_accel (GtkWidget *widget, * * Determines whether an accelerator that activates the signal * identified by @signal_id can currently be activated. - * This is done by emitting the GtkWidget::can-activate-accel + * This is done by emitting the #GtkWidget::can-activate-accel * signal on @widget; if the signal isn't overridden by a * handler or in a derived widget, then the default check is * that the widget must be sensitive, and the widget and all @@ -3776,11 +3777,11 @@ destroy_accel_path (gpointer data) * to be saved for future use. (See gtk_accel_map_save().) * * This function is a low level function that would most likely - * be used by a menu creation system like #GtkItemFactory. If you - * use #GtkItemFactory, setting up accelerator paths will be done + * be used by a menu creation system like #GtkUIManager. If you + * use #GtkUIManager, setting up accelerator paths will be done * automatically. * - * Even when you you aren't using #GtkItemFactory, if you only want to + * Even when you you aren't using #GtkUIManager, if you only want to * set up accelerators on menu items gtk_menu_item_set_accel_path() * provides a somewhat more convenient interface. **/ @@ -3917,7 +3918,8 @@ gtk_widget_real_focus_out_event (GtkWidget *widget, * use gdk_window_invalidate_rect() to invalidate a region of the * window. * - * Return value: return from the event signal emission (%TRUE if the event was handled) + * Return value: return from the event signal emission (%TRUE if + * the event was handled) **/ gboolean gtk_widget_event (GtkWidget *widget, @@ -3954,7 +3956,8 @@ gtk_widget_event (GtkWidget *widget, * To cause the redraw to be done immediately, follow that call * with a call to gdk_window_process_updates(). * - * Return value: return from the event signal emission (%TRUE if the event was handled) + * Return value: return from the event signal emission (%TRUE if + * the event was handled) **/ gint gtk_widget_send_expose (GtkWidget *widget, @@ -4289,7 +4292,6 @@ gtk_widget_reparent_fixup_child (GtkWidget *widget, * * Moves a widget from one #GtkContainer to another, handling reference * count issues to avoid destroying the widget. - * **/ void gtk_widget_reparent (GtkWidget *widget, @@ -4408,7 +4410,7 @@ gtk_widget_region_intersect (GtkWidget *widget, * @widget: a #GtkWidget * @was_grabbed: whether a grab is now in effect * - * Emits the signal "grab_notify" on @widget. + * Emits the #GtkWidget::grab-notify signal on @widget. * * Since: 2.6 **/ @@ -4427,7 +4429,6 @@ _gtk_widget_grab_notify (GtkWidget *widget, * inside. @widget must be a focusable widget, such as a #GtkEntry; * something like #GtkFrame won't work. (More precisely, it must have the * %GTK_CAN_FOCUS flag set.) - * **/ void gtk_widget_grab_focus (GtkWidget *widget) @@ -4638,10 +4639,9 @@ gtk_widget_is_focus (GtkWidget *widget) * Causes @widget to become the default widget. @widget must have the * %GTK_CAN_DEFAULT flag set; typically you have to set this flag * yourself by calling GTK_WIDGET_SET_FLAGS (@widget, - * GTK_CAN_DEFAULT). The default widget is activated when the user - * presses Enter in a window. Default widgets must be activatable, - * that is, gtk_widget_activate() should affect them. - * + * GTK_CAN_DEFAULT). The default widget is activated when + * the user presses Enter in a window. Default widgets must be + * activatable, that is, gtk_widget_activate() should affect them. **/ void gtk_widget_grab_default (GtkWidget *widget) @@ -4718,7 +4718,6 @@ gtk_widget_get_name (GtkWidget *widget) * This function is for use in widget implementations. Sets the state * of a widget (insensitive, prelighted, etc.) Usually you should set * the state using wrapper functions such as gtk_widget_set_sensitive(). - * **/ void gtk_widget_set_state (GtkWidget *widget, @@ -4757,7 +4756,7 @@ gtk_widget_set_state (GtkWidget *widget, * @app_paintable: %TRUE if the application will paint on the widget * * Sets whether the application intends to draw on the widget in - * an ::expose-event handler. + * an #GtkWidget::expose-event handler. * * This is a hint to the widget and does not affect the behavior of * the GTK+ core; many widgets ignore this flag entirely. For widgets @@ -4820,7 +4819,6 @@ gtk_widget_set_app_paintable (GtkWidget *widget, * expose events, since even the clearing to the background color or * pixmap will not happen automatically (as it is done in * gdk_window_begin_paint()). - * **/ void gtk_widget_set_double_buffered (GtkWidget *widget, @@ -4877,7 +4875,6 @@ gtk_widget_set_redraw_on_allocate (GtkWidget *widget, * can interact with it. Insensitive widgets are "grayed out" and the * user can't interact with them. Insensitive widgets are known as * "inactive", "disabled", or "ghosted" in some other toolkits. - * **/ void gtk_widget_set_sensitive (GtkWidget *widget, @@ -4922,12 +4919,12 @@ gtk_widget_set_sensitive (GtkWidget *widget, * @widget: a #GtkWidget * @parent: parent container * - * This function is useful only when implementing subclasses of #GtkContainer. + * This function is useful only when implementing subclasses of + * #GtkContainer. * Sets the container as the parent of @widget, and takes care of * some details such as updating the state and style of the child * to reflect its new location. The opposite function is * gtk_widget_unparent(). - * **/ void gtk_widget_set_parent (GtkWidget *widget, @@ -5019,7 +5016,6 @@ gtk_widget_get_parent (GtkWidget *widget) * want to use this function; it interacts badly with themes, because * themes work by replacing the #GtkStyle. Instead, use * gtk_widget_modify_style(). - * **/ void gtk_widget_set_style (GtkWidget *widget, @@ -5053,7 +5049,6 @@ gtk_widget_set_style (GtkWidget *widget, * function; most of the time, if you want the style, the widget is * realized, and realized widgets are guaranteed to have a style * already. - * **/ void gtk_widget_ensure_style (GtkWidget *widget) @@ -5227,14 +5222,14 @@ gtk_widget_modify_color_component (GtkWidget *widget, /** * gtk_widget_modify_fg: - * @widget: a #GtkWidget. - * @state: the state for which to set the foreground color. + * @widget: a #GtkWidget + * @state: the state for which to set the foreground color * @color: the color to assign (does not need to be allocated), * or %NULL to undo the effect of previous calls to * of gtk_widget_modify_fg(). * - * Sets the foreground color for a widget in a particular state. All - * other style values are left untouched. See also + * Sets the foreground color for a widget in a particular state. + * All other style values are left untouched. See also * gtk_widget_modify_style(). **/ void @@ -5250,22 +5245,23 @@ gtk_widget_modify_fg (GtkWidget *widget, /** * gtk_widget_modify_bg: - * @widget: a #GtkWidget. - * @state: the state for which to set the background color. + * @widget: a #GtkWidget + * @state: the state for which to set the background color * @color: the color to assign (does not need to be allocated), * or %NULL to undo the effect of previous calls to * of gtk_widget_modify_bg(). * - * Sets the background color for a widget in a particular state. All - * other style values are left untouched. See also + * Sets the background color for a widget in a particular state. + * All other style values are left untouched. See also * gtk_widget_modify_style(). * * Note that "no window" widgets (which have the %GTK_NO_WINDOW flag set) - * draw on their parent container's window and thus may not draw any background - * themselves. This is the case for e.g. #GtkLabel. To modify the background - * of such widgets, you have to set the background color on their parent; if you want - * to set the background of a rectangular area around a label, try placing the - * label in a #GtkEventBox widget and setting the background color on that. + * draw on their parent container's window and thus may not draw any + * background themselves. This is the case for e.g. #GtkLabel. To modify + * the background of such widgets, you have to set the background color + * on their parent; if you want to set the background of a rectangular + * area around a label, try placing the label in a #GtkEventBox widget + * and setting the background color on that. **/ void gtk_widget_modify_bg (GtkWidget *widget, @@ -5280,8 +5276,8 @@ gtk_widget_modify_bg (GtkWidget *widget, /** * gtk_widget_modify_text: - * @widget: a #GtkWidget. - * @state: the state for which to set the text color. + * @widget: a #GtkWidget + * @state: the state for which to set the text color * @color: the color to assign (does not need to be allocated), * or %NULL to undo the effect of previous calls to * of gtk_widget_modify_text(). @@ -5305,8 +5301,8 @@ gtk_widget_modify_text (GtkWidget *widget, /** * gtk_widget_modify_base: - * @widget: a #GtkWidget. - * @state: the state for which to set the base color. + * @widget: a #GtkWidget + * @state: the state for which to set the base color * @color: the color to assign (does not need to be allocated), * or %NULL to undo the effect of previous calls to * of gtk_widget_modify_base(). @@ -5318,11 +5314,12 @@ gtk_widget_modify_text (GtkWidget *widget, * and #GtkTextView. See also gtk_widget_modify_style(). * * Note that "no window" widgets (which have the %GTK_NO_WINDOW flag set) - * draw on their parent container's window and thus may not draw any background - * themselves. This is the case for e.g. #GtkLabel. To modify the background - * of such widgets, you have to set the base color on their parent; if you want - * to set the background of a rectangular area around a label, try placing the - * label in a #GtkEventBox widget and setting the base color on that. + * draw on their parent container's window and thus may not draw any + * background themselves. This is the case for e.g. #GtkLabel. To modify + * the background of such widgets, you have to set the base color on their + * parent; if you want to set the background of a rectangular area around + * a label, try placing the label in a #GtkEventBox widget and setting + * the base color on that. **/ void gtk_widget_modify_base (GtkWidget *widget, @@ -5492,7 +5489,7 @@ gtk_widget_propagate_hierarchy_changed_recurse (GtkWidget *widget, * * Propagates changes in the anchored state to a widget and all * children, unsetting or setting the %ANCHORED flag, and - * emitting ::hierarchy_changed. + * emitting #GtkWidget::hierarchy-changed. **/ void _gtk_widget_propagate_hierarchy_changed (GtkWidget *widget, @@ -5546,7 +5543,7 @@ gtk_widget_propagate_screen_changed_recurse (GtkWidget *widget, * * Whether @widget can rely on having its alpha channel * drawn correctly. On X11 this function returns whether a - * compositing manager is running for @widget's screen + * compositing manager is running for @widget's screen. * * Return value: %TRUE if the widget can rely on its alpha * channel being drawn correctly. @@ -5591,7 +5588,7 @@ _gtk_widget_propagate_composited_changed (GtkWidget *widget) * @previous_screen: Previous screen * * Propagates changes in the screen for a widget to all - * children, emitting ::screen_changed. + * children, emitting #GtkWidget::screen-changed. **/ void _gtk_widget_propagate_screen_changed (GtkWidget *widget, @@ -5636,8 +5633,8 @@ gtk_widget_reset_rc_styles (GtkWidget *widget) * * Returns the default style used by all widgets initially. * - * Returns: the default style. This #GtkStyle object is owned by GTK+ and - * should not be modified or freed. + * Returns: the default style. This #GtkStyle object is owned + * by GTK+ and should not be modified or freed. */ GtkStyle* gtk_widget_get_default_style (void) @@ -5670,8 +5667,8 @@ gtk_widget_peek_pango_context (GtkWidget *widget) * * If you create and keep a #PangoLayout using this context, you must * deal with changes to the context by calling pango_layout_context_changed() - * on the layout in response to the ::style-set and ::direction-changed signals - * for the widget. + * on the layout in response to the #GtkWidget::style-set and + * #GtkWidget::direction-changed signals for the widget. * * Return value: the #PangoContext for the widget. **/ @@ -5765,7 +5762,7 @@ gtk_widget_create_pango_context (GtkWidget *widget) /** * gtk_widget_create_pango_layout: * @widget: a #GtkWidget - * @text: text to set on the layout (can be %NULL) + * @text: text to set on the layout (can be %NULL) * * Creates a new #PangoLayout with the appropriate font map, * font description, and base direction for drawing text for @@ -5774,7 +5771,8 @@ gtk_widget_create_pango_context (GtkWidget *widget) * If you keep a #PangoLayout created in this way around, in order to * notify the layout of changes to the base direction or font of this * widget, you must call pango_layout_context_changed() in response to - * the ::style-set and ::direction-changed signals for the widget. + * the #GtkWidget::style-set and #GtkWidget::direction-changed signals + * for the widget. * * Return value: the new #PangoLayout **/ @@ -6123,23 +6121,22 @@ gtk_widget_get_parent_window (GtkWidget *widget) * gtk_widget_child_focus() is called by containers as the user moves * around the window using keyboard shortcuts. @direction indicates * what kind of motion is taking place (up, down, left, right, tab - * forward, tab backward). gtk_widget_child_focus() invokes the - * "focus" signal on #GtkWidget; widgets override the default handler + * forward, tab backward). gtk_widget_child_focus() emits the + * #GtkWidget::focus" signal; widgets override the default handler * for this signal in order to implement appropriate focus behavior. * - * The "focus" default handler for a widget should return %TRUE if + * The default ::focus handler for a widget should return %TRUE if * moving in @direction left the focus on a focusable location inside * that widget, and %FALSE if moving in @direction moved the focus * outside the widget. If returning %TRUE, widgets normally * call gtk_widget_grab_focus() to place the focus accordingly; * if returning %FALSE, they don't modify the current focus location. * - * This function replaces gtk_container_focus() from GTK+ 1.2. It was - * necessary to check that the child was visible, sensitive, and - * focusable before calling - * gtk_container_focus(). gtk_widget_child_focus() returns %FALSE if - * the widget is not currently in a focusable state, so there's no - * need for those checks. + * This function replaces gtk_container_focus() from GTK+ 1.2. + * It was necessary to check that the child was visible, sensitive, + * and focusable before calling gtk_container_focus(). + * gtk_widget_child_focus() returns %FALSE if the widget is not + * currently in a focusable state, so there's no need for those checks. * * Return value: %TRUE if focus ended up inside @widget **/ @@ -6172,13 +6169,13 @@ gtk_widget_child_focus (GtkWidget *widget, /** * gtk_widget_keynav_failed: - * @widget: a #GtkWidget + * @widget: a #GtkWidget * @direction: direction of focus movement * * This function should be called whenever keyboard navigation within * a single widget hits a boundary. The function emits the - * "keynav-changed" signal on the widget and its return value should - * be interpreted in a way similar to the return value of + * #GtkWidget::keynav-changed signal on the widget and its return + * value should be interpreted in a way similar to the return value of * gtk_widget_child_focus(): * * When %TRUE is returned, stay in the widget, the failed keyboard @@ -6189,23 +6186,23 @@ gtk_widget_child_focus (GtkWidget *widget, * navigation outside the widget, e.g. by calling * gtk_widget_child_focus() on the widget's toplevel. * - * The default implementation for the "keynav-failed" signal is to - * return %TRUE for %GTK_DIR_TAB_FORWARD and - * %GTK_DIR_TAB_BACKWARD. For the other values of #GtkDirectionType, - * it looks at the "gtk-keynav-cursor-only" settings property and - * returns %FALSE if the setting is %TRUE. This way the entire GUI + * The default ::keynav-failed handler returns %TRUE for + * %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other + * values of #GtkDirectionType, it looks at the + * #GtkSettings:gtk-keynav-cursor-only" setting and returns %FALSE + * if the setting is %TRUE. This way the entire user interface * becomes cursor-navigatable on input devices such as mobile phones * which only have cursor keys but no tab key. * - * Whenever the default implementation returns %TRUE, it also calls + * Whenever the default handler returns %TRUE, it also calls * gtk_widget_error_bell() to notify the user of the failed keyboard * navigation. * - * A use case for providing an own implementation of keynav-failed (by - * either connecting to it or by overriding it) would be a row of + * A use case for providing an own implementation of ::keynav-failed + * (either by connecting to it or by overriding it) would be a row of * #GtkEntry widgets where the user should be able to navigate the - * entire row with the cursor keys, as e.g. known from GUIs that - * require entering license keys. + * entire row with the cursor keys, as e.g. known from user interfaces + * that require entering license keys. * * Return value: %TRUE if stopping keyboard navigation is fine, %FALSE * if the emitting widget should try to handle the keyboard @@ -6231,8 +6228,8 @@ gtk_widget_keynav_failed (GtkWidget *widget, * gtk_widget_error_bell: * @widget: a #GtkWidget * - * Notifies the user about an input-related error on this widget. If - * the gtk-error-bell settings property is %TRUE, it calls + * Notifies the user about an input-related error on this widget. + * If the #GtkSettings:gtk-error-bell setting is %TRUE, it calls * gdk_window_beep(), otherwise it does nothing. * * Note that the effect of gdk_window_beep() can be configured in many @@ -6381,7 +6378,7 @@ gtk_widget_set_usize_internal (GtkWidget *widget, * basically impossible to hardcode a size that will always be * correct. * - * @Deprecated: Use gtk_widget_set_size_request() instead. + * Deprecated: Use gtk_widget_set_size_request() instead. **/ void gtk_widget_set_usize (GtkWidget *widget, @@ -6454,7 +6451,7 @@ gtk_widget_set_size_request (GtkWidget *widget, * @height: return location for height, or %NULL * * Gets the size request that was explicitly set for the widget using - * gtk_widget_set_size_request(). A value of -1 stored in @width or + * gtk_widget_set_size_request(). A value of -1 stored in @width or * @height indicates that that dimension has not been set explicitly * and the natural requisition of the widget will be used intead. See * gtk_widget_set_size_request(). To get the size a widget will @@ -6556,7 +6553,6 @@ gtk_widget_add_events_internal (GtkWidget *widget, * * Adds the events in the bitfield @events to the event mask for * @widget. See gtk_widget_set_events() for details. - * **/ void gtk_widget_add_events (GtkWidget *widget, @@ -6660,7 +6656,8 @@ gtk_widget_set_extension_events (GtkWidget *widget, * } * * - * Return value: the topmost ancestor of @widget, or @widget itself if there's no ancestor. + * Return value: the topmost ancestor of @widget, or @widget itself + * if there's no ancestor. **/ GtkWidget* gtk_widget_get_toplevel (GtkWidget *widget) @@ -6679,11 +6676,11 @@ gtk_widget_get_toplevel (GtkWidget *widget) * @widget_type: ancestor type * * Gets the first ancestor of @widget with type @widget_type. For example, - * gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the - * first #GtkBox that's - * an ancestor of @widget. No reference will be added to the returned widget; - * it should not be unreferenced. See note about checking for a toplevel - * #GtkWindow in the docs for gtk_widget_get_toplevel(). + * gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets + * the first #GtkBox that's an ancestor of @widget. No reference will be + * added to the returned widget; it should not be unreferenced. See note + * about checking for a toplevel #GtkWindow in the docs for + * gtk_widget_get_toplevel(). * * Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() * considers @widget to be an ancestor of itself. @@ -6789,7 +6786,6 @@ gtk_widget_get_settings (GtkWidget *widget) * have been previously realized. This probably should only be used * from an init() function (i.e. from the constructor * for the widget). - * **/ void gtk_widget_set_colormap (GtkWidget *widget, @@ -6865,7 +6861,6 @@ gtk_widget_get_extension_events (GtkWidget *widget) * defined as @widget->window coordinates for widgets that are not * #GTK_NO_WINDOW widgets, and are relative to @widget->allocation.x, * @widget->allocation.y for widgets that are #GTK_NO_WINDOW widgets. - * **/ void gtk_widget_get_pointer (GtkWidget *widget, @@ -6901,7 +6896,8 @@ gtk_widget_get_pointer (GtkWidget *widget, * Determines whether @widget is somewhere inside @ancestor, possibly with * intermediate containers. * - * Return value: %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc. + * Return value: %TRUE if @ancestor contains @widget as a child, + * grandchild, great grandchild, etc. **/ gboolean gtk_widget_is_ancestor (GtkWidget *widget, @@ -6925,7 +6921,7 @@ static GQuark quark_composite_name = 0; /** * gtk_widget_set_composite_name: * @widget: a #GtkWidget. - * @name: the name to set. + * @name: the name to set * * Sets a widgets composite name. The widget must be * a composite child of its parent; see gtk_widget_push_composite_child(). @@ -6949,7 +6945,7 @@ gtk_widget_set_composite_name (GtkWidget *widget, /** * gtk_widget_get_composite_name: - * @widget: a #GtkWidget. + * @widget: a #GtkWidget * @returns: the composite name of @widget, or %NULL if @widget is not * a composite child. The string should not be freed when it is no * longer needed. @@ -7017,7 +7013,6 @@ gtk_widget_pop_composite_child (void) * colormap on the stack will be used to create all widgets. * Remove @cmap with gtk_widget_pop_colormap(). There's little * reason to use this function. - * **/ void gtk_widget_push_colormap (GdkColormap *cmap) @@ -7031,7 +7026,6 @@ gtk_widget_push_colormap (GdkColormap *cmap) * gtk_widget_pop_colormap: * * Removes a colormap pushed with gtk_widget_push_colormap(). - * **/ void gtk_widget_pop_colormap (void) @@ -7568,10 +7562,10 @@ gtk_widget_shape_info_destroy (GtkWidgetShapeInfo *info) /** * gtk_widget_shape_combine_mask: - * @widget: a #GtkWidget. - * @shape_mask: shape to be added, or %NULL to remove an existing shape. - * @offset_x: X position of shape mask with respect to @window. - * @offset_y: Y position of shape mask with respect to @window. + * @widget: a #GtkWidget + * @shape_mask: shape to be added, or %NULL to remove an existing shape + * @offset_x: X position of shape mask with respect to @window + * @offset_y: Y position of shape mask with respect to @window * * Sets a shape for this widget's GDK window. This allows for * transparent windows etc., see gdk_window_shape_combine_mask() @@ -7621,10 +7615,10 @@ gtk_widget_shape_combine_mask (GtkWidget *widget, /** * gtk_widget_input_shape_combine_mask: - * @widget: a #GtkWidget. - * @shape_mask: shape to be added, or %NULL to remove an existing shape. - * @offset_x: X position of shape mask with respect to @window. - * @offset_y: Y position of shape mask with respect to @window. + * @widget: a #GtkWidget + * @shape_mask: shape to be added, or %NULL to remove an existing shape + * @offset_x: X position of shape mask with respect to @window + * @offset_y: Y position of shape mask with respect to @window * * Sets an input shape for this widget's GDK window. This allows for * windows which react to mouse click in a nonrectangular region, see @@ -7690,7 +7684,7 @@ gtk_reset_shapes_recurse (GtkWidget *widget, /** * gtk_widget_reset_shapes: - * @widget: a #GtkWidget. + * @widget: a #GtkWidget * * Recursively resets the shape on this widget and its descendants. **/ @@ -7714,6 +7708,8 @@ gtk_widget_reset_shapes (GtkWidget *widget) * to a #GObject, it saves a small amount of typing. * * Return value: the widget that was referenced + * + * Deprecated: Use g_object_ref() instead. **/ GtkWidget* gtk_widget_ref (GtkWidget *widget) @@ -7729,6 +7725,7 @@ gtk_widget_ref (GtkWidget *widget) * * Inverse of gtk_widget_ref(). Equivalent to g_object_unref(). * + * Deprecated: Use g_object_unref() instead. **/ void gtk_widget_unref (GtkWidget *widget) @@ -7822,7 +7819,8 @@ gtk_widget_class_find_style_property (GtkWidgetClass *klass, * gtk_widget_class_list_style_properties: * @klass: a #GtkWidgetClass * @n_properties: location to return the number of style properties found - * @returns: an newly allocated array of #GParamSpec*. The array must be freed with g_free(). + * @returns: an newly allocated array of #GParamSpec*. The array must + * be freed with g_free(). * * Returns all style properties of a widget class. * @@ -7993,15 +7991,14 @@ gtk_widget_style_get (GtkWidget *widget, * widget and all its parents in the container hierarchy, separated by * periods. The name of a widget comes from * gtk_widget_get_name(). Paths are used to apply styles to a widget - * in gtkrc configuration files. Widget names are the type of the + * in gtkrc configuration files. Widget names are the type of the * widget by default (e.g. "GtkButton") or can be set to an - * application-specific value with gtk_widget_set_name(). By setting + * application-specific value with gtk_widget_set_name(). By setting * the name of a widget, you allow users or theme authors to apply * styles to that specific widget in their gtkrc * file. @path_reversed_p fills in the path in reverse order, * i.e. starting with @widget's name instead of starting with the name * of @widget's outermost ancestor. - * **/ void gtk_widget_path (GtkWidget *widget, @@ -8061,7 +8058,8 @@ gtk_widget_path (GtkWidget *widget, * @widget: a #GtkWidget * @path_length: location to store the length of the class path, or %NULL * @path: location to store the class path as an allocated string, or %NULL - * @path_reversed: location to store the reverse class path as an allocated string, or %NULL + * @path_reversed: location to store the reverse class path as an allocated + * string, or %NULL * * Same as gtk_widget_path(), but always uses the name of a widget's type, * never uses a custom name set with gtk_widget_set_name(). @@ -8122,10 +8120,11 @@ gtk_widget_class_path (GtkWidget *widget, /** * gtk_requisition_copy: - * @requisition: a #GtkRequisition. - * @returns: a copy of @requisition. + * @requisition: a #GtkRequisition * * Copies a #GtkRequisition. + * + * Returns: a copy of @requisition **/ GtkRequisition * gtk_requisition_copy (const GtkRequisition *requisition) @@ -8135,7 +8134,7 @@ gtk_requisition_copy (const GtkRequisition *requisition) /** * gtk_requisition_free: - * @requisition: a #GtkRequisition. + * @requisition: a #GtkRequisition * * Frees a #GtkRequisition. **/ @@ -8305,14 +8304,14 @@ gtk_widget_list_mnemonic_labels (GtkWidget *widget) /** * gtk_widget_add_mnemonic_label: * @widget: a #GtkWidget - * @label: a #GtkWidget that acts as a mnemonic label for @widget. + * @label: a #GtkWidget that acts as a mnemonic label for @widget * * Adds a widget to the list of mnemonic labels for * this widget. (See gtk_widget_list_mnemonic_labels()). Note the * list of mnemonic labels for the widget is cleared when the * widget is destroyed, so the caller must make sure to update * its internal state at this point as well, by using a connection - * to the ::destroy signal or a weak notifier. + * to the #GtkWidget::destroy signal or a weak notifier. * * Since: 2.4 **/ @@ -8366,11 +8365,11 @@ gtk_widget_remove_mnemonic_label (GtkWidget *widget, * gtk_widget_get_no_show_all: * @widget: a #GtkWidget * - * Returns the current value of the "no_show_all" property, which determines - * whether calls to gtk_widget_show_all() and gtk_widget_hide_all() - * will affect this widget. + * Returns the current value of the GtkWidget:no-show-all property, + * which determines whether calls to gtk_widget_show_all() and + * gtk_widget_hide_all() will affect this widget. * - * Return value: the current value of the "no_show_all" property. + * Return value: the current value of the "no-show-all" property. * * Since: 2.4 **/ @@ -8385,10 +8384,11 @@ gtk_widget_get_no_show_all (GtkWidget *widget) /** * gtk_widget_set_no_show_all: * @widget: a #GtkWidget - * @no_show_all: the new value for the "no_show_all" property + * @no_show_all: the new value for the "no-show-all" property * - * Sets the "no_show_all" property, which determines whether calls to - * gtk_widget_show_all() and gtk_widget_hide_all() will affect this widget. + * Sets the #GtkWidget:no-show-all property, which determines whether + * calls to gtk_widget_show_all() and gtk_widget_hide_all() will affect + * this widget. * * This is mostly for use in constructing widget hierarchies with externally * controlled visibility, see #GtkUIManager. @@ -8456,9 +8456,9 @@ gtk_widget_set_has_tooltip (GtkWidget *widget, * @custom_window: a #GtkWindow, or %NULL * * Replaces the default, usually yellow, window used for displaying - * tooltips with @custom_window. GTK+ will take care of showing and + * tooltips with @custom_window. GTK+ will take care of showing and * hiding @custom_window at the right moment, to behave likewise as - * the default tooltip window. If @custom_window is %NULL, the default + * the default tooltip window. If @custom_window is %NULL, the default * tooltip window will be used. * * Since: 2.12 @@ -8496,7 +8496,7 @@ gtk_widget_set_tooltip_window (GtkWidget *widget, * gtk_widget_get_tooltip_window: * @widget: a #GtkWidget * - * Returns the #GtkWindow of the current tooltip. This can be the + * Returns the #GtkWindow of the current tooltip. This can be the * GtkWindow created by default, or the custom tooltip window set * using gtk_widget_set_tooltip_window(). * @@ -8517,7 +8517,7 @@ gtk_widget_get_tooltip_window (GtkWidget *widget) * @widget: a #GtkWidget * * Triggers a tooltip query on the display where the toplevel of @widget - * is located. See gtk_tooltip_trigger_tooltip_query() for more + * is located. See gtk_tooltip_trigger_tooltip_query() for more * information. * * Since: 2.12