From 6529c07614ebfbfac73f526efb057d8a8e3a7354 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 10 Dec 2009 08:23:40 -0200 Subject: [PATCH] [introspection] Merge in Gtk-custom.c annotations The Gtk-custom.c file in gir-repository contained a number of introspection annotations. Merge those into the GTK source files. Some documentation was moved from the tmpl/ files to accomodate the addition of annotations. --- docs/reference/gtk/tmpl/gtkprogressbar.sgml | 6 - docs/reference/gtk/tmpl/gtkradiobutton.sgml | 9 +- docs/reference/gtk/tmpl/gtkradiomenuitem.sgml | 8 - docs/reference/gtk/tmpl/gtkspinbutton.sgml | 9 +- docs/reference/gtk/tmpl/gtkstyle.sgml | 9 - docs/reference/gtk/tmpl/gtktooltips.sgml | 10 - gtk/gtkaboutdialog.c | 18 +- gtk/gtkaccelgroup.c | 5 +- gtk/gtkaction.c | 8 +- gtk/gtkactiongroup.c | 16 +- gtk/gtkassistant.c | 8 +- gtk/gtkbin.c | 4 +- gtk/gtkbuilder.c | 2 +- gtk/gtkcelllayout.c | 4 +- gtk/gtkcellview.c | 8 +- gtk/gtkclipboard.c | 11 +- gtk/gtkclist.c | 4 + gtk/gtkcombobox.c | 8 +- gtk/gtkcontainer.c | 13 +- gtk/gtkctree.c | 43 ++++- gtk/gtkdialog.c | 16 +- gtk/gtkdnd.c | 6 +- gtk/gtkeditable.c | 14 +- gtk/gtkentry.c | 14 +- gtk/gtkentrycompletion.c | 2 +- gtk/gtkexpander.c | 8 +- gtk/gtkfilechooser.c | 24 +-- gtk/gtkframe.c | 4 +- gtk/gtkiconfactory.c | 6 +- gtk/gtkicontheme.c | 18 +- gtk/gtkiconview.c | 16 +- gtk/gtkimage.c | 30 +-- gtk/gtkimagemenuitem.c | 4 +- gtk/gtkitemfactory.c | 6 +- gtk/gtklabel.c | 6 +- gtk/gtklayout.c | 4 +- gtk/gtklinkbutton.c | 4 +- gtk/gtkliststore.c | 18 +- gtk/gtkmain.c | 24 +-- gtk/gtkmenu.c | 13 +- gtk/gtkmenuitem.c | 2 +- gtk/gtkmenutoolbutton.c | 4 +- gtk/gtkmessagedialog.c | 10 +- gtk/gtknotebook.c | 40 ++-- gtk/gtkpapersize.c | 12 +- gtk/gtkpixmap.c | 4 + gtk/gtkprintbackend.c | 10 + gtk/gtkprinter.c | 4 +- gtk/gtkprinteroptionset.c | 5 + gtk/gtkprintoperation-unix.c | 10 +- gtk/gtkprintoperation.c | 12 +- gtk/gtkprintsettings.c | 10 +- gtk/gtkprogressbar.c | 8 + gtk/gtkradioaction.c | 2 +- gtk/gtkradiobutton.c | 12 ++ gtk/gtkradiomenuitem.c | 10 + gtk/gtkrc.c | 6 +- gtk/gtkrecentchooser.c | 6 +- gtk/gtkrecentmanager.c | 25 +-- gtk/gtkscrolledwindow.c | 10 +- gtk/gtkselection.c | 11 +- gtk/gtksettings.c | 4 +- gtk/gtksizegroup.c | 4 +- gtk/gtkspinbutton.c | 10 + gtk/gtkstatusicon.c | 20 +- gtk/gtkstock.c | 4 +- gtk/gtkstyle.c | 177 ++++++++++-------- gtk/gtktextbuffer.c | 14 +- gtk/gtktextbufferrichtext.c | 4 +- gtk/gtktextchild.c | 6 +- gtk/gtktextiter.c | 42 ++--- gtk/gtktextlayout.c | 10 + gtk/gtktextmark.c | 4 +- gtk/gtktextview.c | 6 +- gtk/gtktoolbar.c | 26 +-- gtk/gtktoolbutton.c | 28 +-- gtk/gtktoolitem.c | 12 +- gtk/gtktooltips.c | 11 ++ gtk/gtktreemodel.c | 10 +- gtk/gtktreemodelfilter.c | 2 +- gtk/gtktreeselection.c | 8 +- gtk/gtktreestore.c | 4 +- gtk/gtktreeview.c | 24 +-- gtk/gtktreeviewcolumn.c | 4 +- gtk/gtkuimanager.c | 21 ++- gtk/gtkviewport.c | 8 +- gtk/gtkwidget.c | 150 +++++++-------- gtk/gtkwindow.c | 51 ++--- 88 files changed, 710 insertions(+), 607 deletions(-) diff --git a/docs/reference/gtk/tmpl/gtkprogressbar.sgml b/docs/reference/gtk/tmpl/gtkprogressbar.sgml index e397cfba63..c05dbd595b 100644 --- a/docs/reference/gtk/tmpl/gtkprogressbar.sgml +++ b/docs/reference/gtk/tmpl/gtkprogressbar.sgml @@ -264,12 +264,6 @@ directions for the visible progress bar. - -Creates a new #GtkProgressBar with an associated #GtkAdjustment. - - -@adjustment: a #GtkAdjustment. -@Returns: a #GtkProgressBar. diff --git a/docs/reference/gtk/tmpl/gtkradiobutton.sgml b/docs/reference/gtk/tmpl/gtkradiobutton.sgml index c6c55c1ef2..69dd718e3a 100644 --- a/docs/reference/gtk/tmpl/gtkradiobutton.sgml +++ b/docs/reference/gtk/tmpl/gtkradiobutton.sgml @@ -197,13 +197,6 @@ gtk_radio_button_get_group(). - -Retrieves the group assigned to a radio button. - - -@radio_button: a #GtkRadioButton. -@Returns: a linked list containing all the radio buttons in the same group -as @radio_button. The returned list is owned by the radio button -and must not be modified or freed. + diff --git a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml index a9373ccc65..0c25162a0a 100644 --- a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml +++ b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml @@ -80,14 +80,6 @@ Creates a new #GtkRadioMenuItem. - -Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel. - - -@group: the group to which the radio menu item is to be attached -@label: the text for the label -@Returns: a new #GtkRadioMenuItem - diff --git a/docs/reference/gtk/tmpl/gtkspinbutton.sgml b/docs/reference/gtk/tmpl/gtkspinbutton.sgml index 8ddd7a20f7..67efd898ac 100644 --- a/docs/reference/gtk/tmpl/gtkspinbutton.sgml +++ b/docs/reference/gtk/tmpl/gtkspinbutton.sgml @@ -246,13 +246,12 @@ GTK_SPIN_END -Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call. + -@spin_button: a #GtkSpinButton. -@adjustment: a #GtkAdjustment. -@climb_rate: the new climb rate. -@digits: the number of decimal places to display in the spin button. + +@adjustment: + diff --git a/docs/reference/gtk/tmpl/gtkstyle.sgml b/docs/reference/gtk/tmpl/gtkstyle.sgml index a6c944d8a6..5e13cbf679 100644 --- a/docs/reference/gtk/tmpl/gtkstyle.sgml +++ b/docs/reference/gtk/tmpl/gtkstyle.sgml @@ -136,15 +136,6 @@ Returns whether the style is attached to a window. -@style: -@window: -@set_bg: -@state_type: -@area: -@x: -@y: -@width: -@height: diff --git a/docs/reference/gtk/tmpl/gtktooltips.sgml b/docs/reference/gtk/tmpl/gtktooltips.sgml index 41ce78e567..4c9a759fa4 100644 --- a/docs/reference/gtk/tmpl/gtktooltips.sgml +++ b/docs/reference/gtk/tmpl/gtktooltips.sgml @@ -146,16 +146,6 @@ Sets the time between the user moving the mouse over a widget and the widget's t - -Adds a tooltip containing the message @tip_text to the specified #GtkWidget. - - -@tooltips: a #GtkTooltips. -@widget: the #GtkWidget you wish to associate the tip with. -@tip_text: a string containing the tip itself. -@tip_private: a string of any further information that may be useful if the user gets stuck. -@Deprecated: 2.12: - diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c index 92aad3db66..346b89403d 100644 --- a/gtk/gtkaboutdialog.c +++ b/gtk/gtkaboutdialog.c @@ -933,7 +933,7 @@ update_name_version (GtkAboutDialog *about) /** * gtk_about_dialog_set_name: * @about: a #GtkAboutDialog - * @name: the program name + * @name: (allow-none): the program name * * Sets the name to display in the about dialog. * If this is not set, it defaults to g_get_application_name(). @@ -1005,7 +1005,7 @@ gtk_about_dialog_get_version (GtkAboutDialog *about) /** * gtk_about_dialog_set_version: * @about: a #GtkAboutDialog - * @version: the version string + * @version: (allow-none): the version string * * Sets the version string to display in the about dialog. * @@ -1057,7 +1057,7 @@ gtk_about_dialog_get_copyright (GtkAboutDialog *about) /** * gtk_about_dialog_set_copyright: * @about: a #GtkAboutDialog - * @copyright: the copyright string + * @copyright: (allow-none) the copyright string * * Sets the copyright string to display in the about dialog. * This should be a short string of one or two lines. @@ -1120,7 +1120,7 @@ gtk_about_dialog_get_comments (GtkAboutDialog *about) /** * gtk_about_dialog_set_comments: * @about: a #GtkAboutDialog - * @comments: a comments string + * @comments: (allow-none): a comments string * * Sets the comments string to display in the about dialog. * This should be a short string of one or two lines. @@ -1181,7 +1181,7 @@ gtk_about_dialog_get_license (GtkAboutDialog *about) /** * gtk_about_dialog_set_license: * @about: a #GtkAboutDialog - * @license: the license information or %NULL + * @license: (allow-none): the license information or %NULL * * Sets the license information to be displayed in the secondary * license dialog. If @license is %NULL, the license button is @@ -1295,7 +1295,7 @@ gtk_about_dialog_get_website (GtkAboutDialog *about) /** * gtk_about_dialog_set_website: * @about: a #GtkAboutDialog - * @website: a URL string starting with "http://" + * @website: (allow-none): a URL string starting with "http://" * * Sets the URL to use for the website link. * @@ -1587,7 +1587,7 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about) /** * gtk_about_dialog_set_translator_credits: * @about: a #GtkAboutDialog - * @translator_credits: the translator credits + * @translator_credits: (allow-none): the translator credits * * Sets the translator credits string which is displayed in * the translators tab of the secondary credits dialog. @@ -1674,7 +1674,7 @@ icon_set_new_from_pixbufs (GList *pixbufs) /** * gtk_about_dialog_set_logo: * @about: a #GtkAboutDialog - * @logo: a #GdkPixbuf, or %NULL + * @logo: (allow-none): a #GdkPixbuf, or %NULL * * Sets the pixbuf to be displayed as logo in the about dialog. * If it is %NULL, the default window icon set with @@ -1751,7 +1751,7 @@ gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about) /** * gtk_about_dialog_set_logo_icon_name: * @about: a #GtkAboutDialog - * @icon_name: an icon name, or %NULL + * @icon_name: (allow-none): an icon name, or %NULL * * Sets the pixbuf to be displayed as logo in the about dialog. * If it is %NULL, the default window icon set with diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c index 29e34eb3f3..4d760b5880 100644 --- a/gtk/gtkaccelgroup.c +++ b/gtk/gtkaccelgroup.c @@ -351,10 +351,11 @@ _gtk_accel_group_detach (GtkAccelGroup *accel_group, /** * gtk_accel_groups_from_object: - * @object: a #GObject, usually a #GtkWindow - * @returns: a list of all accel groups which are attached to @object + * @object: a #GObject, usually a #GtkWindow * * Gets a list of all accel groups which are attached to @object. + * + * Returns: (element-type GtkAccelGroup) (transfer none): a list of all accel groups which are attached to @object */ GSList* gtk_accel_groups_from_object (GObject *object) diff --git a/gtk/gtkaction.c b/gtk/gtkaction.c index 6e9dfa2557..48417a2bfc 100644 --- a/gtk/gtkaction.c +++ b/gtk/gtkaction.c @@ -978,8 +978,8 @@ gtk_action_disconnect_proxy (GtkAction *action, * * Returns the proxy widgets for an action. * See also gtk_widget_get_action(). - * - * Return value: a #GSList of proxy widgets. The list is owned by GTK+ + * + * Return value: (element-type GtkWidget) (transfer none): a #GSList of proxy widgets. The list is owned by GTK+ * and must not be modified. * * Since: 2.4 @@ -1811,8 +1811,8 @@ gtk_action_get_accel_closure (GtkAction *action) /** * gtk_action_set_accel_group: * @action: the action object - * @accel_group: a #GtkAccelGroup or %NULL - * + * @accel_group: (allow-none): a #GtkAccelGroup or %NULL + * * Sets the #GtkAccelGroup in which the accelerator for this action * will be installed. * diff --git a/gtk/gtkactiongroup.c b/gtk/gtkactiongroup.c index 2fd87e0969..a8003803c1 100644 --- a/gtk/gtkactiongroup.c +++ b/gtk/gtkactiongroup.c @@ -731,7 +731,7 @@ gtk_action_group_set_visible (GtkActionGroup *action_group, * * Looks up an action in the action group by name. * - * Returns: the action, or %NULL if no action by that name exists + * Returns: (transfer-none): the action, or %NULL if no action by that name exists * * Since: 2.4 */ @@ -805,11 +805,11 @@ gtk_action_group_add_action (GtkActionGroup *action_group, /** * gtk_action_group_add_action_with_accel: - * @action_group: the action group - * @action: the action to add - * @accelerator: the accelerator for the action, in - * the format understood by gtk_accelerator_parse(), or "" for no accelerator, or - * %NULL to use the stock accelerator + * @action_group: the action group + * @action: the action to add + * @accelerator: (allow-none): the accelerator for the action, in + * the format understood by gtk_accelerator_parse(), or "" for no accelerator, or + * %NULL to use the stock accelerator * * Adds an action object to the action group and sets up the accelerator. * @@ -920,8 +920,8 @@ add_single_action (gpointer key, * * Lists the actions in the action group. * - * Returns: an allocated list of the action objects in the action group - * + * Returns: (element-type GtkAction) (transfer container): an allocated list of the action objects in the action group + * * Since: 2.4 */ GList * diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c index 452d0b4fa3..f43193e68c 100644 --- a/gtk/gtkassistant.c +++ b/gtk/gtkassistant.c @@ -1980,8 +1980,8 @@ gtk_assistant_get_page_type (GtkAssistant *assistant, * gtk_assistant_set_page_header_image: * @assistant: a #GtkAssistant * @page: a page of @assistant - * @pixbuf: the new header image @page - * + * @pixbuf: (allow-none): the new header image @page + * * Sets a header image for @page. This image is displayed in the header * area of the assistant when @page is the current page. * @@ -2060,8 +2060,8 @@ gtk_assistant_get_page_header_image (GtkAssistant *assistant, * gtk_assistant_set_page_side_image: * @assistant: a #GtkAssistant * @page: a page of @assistant - * @pixbuf: the new header image @page - * + * @pixbuf: (allow-none): the new header image @page + * * Sets a header image for @page. This image is displayed in the side * area of the assistant when @page is the current page. * diff --git a/gtk/gtkbin.c b/gtk/gtkbin.c index e8138137cc..e025994718 100644 --- a/gtk/gtkbin.c +++ b/gtk/gtkbin.c @@ -135,8 +135,8 @@ gtk_bin_forall (GtkContainer *container, * Gets the child of the #GtkBin, or %NULL if the bin contains * no child widget. The returned widget does not have a reference * added, so you do not need to unref it. - * - * Return value: pointer to child of the #GtkBin + * + * Return value: (transfer none): pointer to child of the #GtkBin **/ GtkWidget* gtk_bin_get_child (GtkBin *bin) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index 9dff20e38a..a692b751e4 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -888,7 +888,7 @@ object_add_to_list (gchar *object_id, * this function does not increment the reference counts of the returned * objects. * - * Return value: a newly-allocated #GSList containing all the objects + * Return value: (element-type GObject) (transfer container): a newly-allocated #GSList containing all the objects * constructed by the #GtkBuilder instance. It should be freed by * g_slist_free() * diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c index 2783ce8b50..2fa3c2d320 100644 --- a/gtk/gtkcelllayout.c +++ b/gtk/gtkcelllayout.c @@ -292,10 +292,10 @@ gtk_cell_layout_reorder (GtkCellLayout *cell_layout, * * Returns the cell renderers which have been added to @cell_layout. * - * Return value: a list of cell renderers. The list, but not the + * Return value: (element-type GtkCellRenderer) (transfer container): a list of cell renderers. The list, but not the * renderers has been newly allocated and should be freed with * g_list_free() when no longer needed. - * + * * Since: 2.12 */ GList * diff --git a/gtk/gtkcellview.c b/gtk/gtkcellview.c index 5f8fe39574..7704495fbc 100644 --- a/gtk/gtkcellview.c +++ b/gtk/gtkcellview.c @@ -857,10 +857,10 @@ gtk_cell_view_set_value (GtkCellView *cell_view, /** * gtk_cell_view_set_model: * @cell_view: a #GtkCellView - * @model: a #GtkTreeModel + * @model: (allow-none): a #GtkTreeModel * * Sets the model for @cell_view. If @cell_view already has a model - * set, it will remove it before setting the new model. If @model is + * set, it will remove it before setting the new model. If @model is * %NULL, then it will unset the old model. * * Since: 2.6 @@ -910,8 +910,8 @@ gtk_cell_view_get_model (GtkCellView *cell_view) /** * gtk_cell_view_set_displayed_row: * @cell_view: a #GtkCellView - * @path: a #GtkTreePath or %NULL to unset. - * + * @path: (allow-none): a #GtkTreePath or %NULL to unset. + * * Sets the row of the model that is currently displayed * by the #GtkCellView. If the path is unset, then the * contents of the cellview "stick" at their last value; diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c index c964b60d77..a8972127aa 100644 --- a/gtk/gtkclipboard.c +++ b/gtk/gtkclipboard.c @@ -1526,12 +1526,13 @@ clipboard_uris_received_func (GtkClipboard *clipboard, * Requests the contents of the clipboard as URIs. This function waits * for the data to be received using the main loop, so events, * timeouts, etc, may be dispatched during the wait. - * - * Return value: a newly-allocated %NULL-terminated array of strings which must + * + * Return value: (array zero-terminated=1) (element-type utf8) (transfer full): a newly-allocated + * %NULL-terminated array of strings which must * be freed with g_strfreev(), or %NULL if - * retrieving the selection data failed. (This - * could happen for various reasons, in particular - * if the clipboard was empty or if the contents of + * retrieving the selection data failed. (This + * could happen for various reasons, in particular + * if the clipboard was empty or if the contents of * the clipboard could not be converted into URI form.) * * Since: 2.14 diff --git a/gtk/gtkclist.c b/gtk/gtkclist.c index 9117f8c781..7d7aec55b4 100644 --- a/gtk/gtkclist.c +++ b/gtk/gtkclist.c @@ -2274,6 +2274,10 @@ gtk_clist_get_text (GtkCList *clist, return 1; } +/** + * gtk_clist_set_pixmap: + * @mask: (allow-none): + */ void gtk_clist_set_pixmap (GtkCList *clist, gint row, diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c index 666cb7fb00..8df31ed239 100644 --- a/gtk/gtkcombobox.c +++ b/gtk/gtkcombobox.c @@ -5020,9 +5020,9 @@ gtk_combo_box_set_active_iter (GtkComboBox *combo_box, /** * gtk_combo_box_set_model: * @combo_box: A #GtkComboBox - * @model: A #GtkTreeModel + * @model: (allow-none): A #GtkTreeModel * - * Sets the model used by @combo_box to be @model. Will unset a previously set + * Sets the model used by @combo_box to be @model. Will unset a previously set * model (if applicable). If model is %NULL, then it will unset the model. * * Note that this function does not clear the cell renderers, you have to @@ -5104,7 +5104,7 @@ out: * * Returns the #GtkTreeModel which is acting as data source for @combo_box. * - * Return value: A #GtkTreeModel which was passed during construction. + * Return value: (transfer none): A #GtkTreeModel which was passed during construction. * * Since: 2.4 */ @@ -5129,7 +5129,7 @@ gtk_combo_box_get_model (GtkComboBox *combo_box) * gtk_combo_box_insert_text(), gtk_combo_box_prepend_text() and * gtk_combo_box_remove_text(). * - * Return value: A new text combo box. + * Return value: (transfer none): A new text combo box. * * Since: 2.4 */ diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 8b721d0282..d997cf78ba 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -1586,7 +1586,7 @@ gtk_container_foreach_full (GtkContainer *container, /** * gtk_container_set_focus_child: * @container: a #GtkContainer - * @child: a #GtkWidget, or %NULL + * @child: (allow-none): a #GtkWidget, or %NULL * * Sets, or unsets if @child is %NULL, the focused child of @container. * @@ -1629,9 +1629,9 @@ gtk_container_get_focus_child (GtkContainer *container) * @container: a #GtkContainer * * Returns the container's non-internal children. See - * gtk_container_forall() for details on what constitutes an "internal" child. + * gtk_container_forall() for details on what constitutes an "internal" child. * - * Return value: a newly-allocated list of the container's non-internal children. + * Return value: (element-type GtkWidget) (transfer container): a newly-allocated list of the container's non-internal children. **/ GList* gtk_container_get_children (GtkContainer *container) @@ -2403,7 +2403,8 @@ gtk_container_set_focus_chain (GtkContainer *container, /** * gtk_container_get_focus_chain: * @container: a #GtkContainer - * @focusable_widgets: location to store the focus chain of the + * @focusable_widgets: (element-type GtkWidget) (out) (transfer container): location + * to store the focus chain of the * container, or %NULL. You should free this list * using g_list_free() when you are done with it, however * no additional reference count is added to the @@ -2513,7 +2514,7 @@ gtk_container_set_focus_vadjustment (GtkContainer *container, * Retrieves the vertical focus adjustment for the container. See * gtk_container_set_focus_vadjustment(). * - * Return value: the vertical focus adjustment, or %NULL if + * Return value: (transfer none): the vertical focus adjustment, or %NULL if * none has been set. **/ GtkAdjustment * @@ -2568,7 +2569,7 @@ gtk_container_set_focus_hadjustment (GtkContainer *container, * Retrieves the horizontal focus adjustment for the container. See * gtk_container_set_focus_hadjustment (). * - * Return value: the horizontal focus adjustment, or %NULL if + * Return value: (transfer none): the horizontal focus adjustment, or %NULL if * none has been set. **/ GtkAdjustment * diff --git a/gtk/gtkctree.c b/gtk/gtkctree.c index a396db543a..48511e3ce6 100644 --- a/gtk/gtkctree.c +++ b/gtk/gtkctree.c @@ -3626,9 +3626,17 @@ real_insert_row (GtkCList *clist, return row; } -GtkCTreeNode * + +/** + * gtk_ctree_insert_node: + * @pixmap_closed: (allow-none): + * @mask_closed: (allow-none): + * @pixmap_opened: (allow-none): + * @mask_opened: (allow-none): + */ +GtkCTreeNode * gtk_ctree_insert_node (GtkCTree *ctree, - GtkCTreeNode *parent, + GtkCTreeNode *parent, GtkCTreeNode *sibling, gchar *text[], guint8 spacing, @@ -4286,10 +4294,15 @@ gtk_ctree_is_hot_spot (GtkCTree *ctree, ***********************************************************/ +/** + * gtk_ctree_move: + * @new_parent: (allow-none): + * @new_sibling: (allow-none): + */ void gtk_ctree_move (GtkCTree *ctree, GtkCTreeNode *node, - GtkCTreeNode *new_parent, + GtkCTreeNode *new_parent, GtkCTreeNode *new_sibling) { g_return_if_fail (GTK_IS_CTREE (ctree)); @@ -4599,7 +4612,12 @@ gtk_ctree_node_set_text (GtkCTree *ctree, tree_draw_node (ctree, node); } -void + +/** + * gtk_ctree_node_set_pixmap: + * @mask: (allow-none): + */ +void gtk_ctree_node_set_pixmap (GtkCTree *ctree, GtkCTreeNode *node, gint column, @@ -4628,7 +4646,12 @@ gtk_ctree_node_set_pixmap (GtkCTree *ctree, tree_draw_node (ctree, node); } -void + +/** + * gtk_ctree_node_set_pixtext: + * @mask: (allow-none): + */ +void gtk_ctree_node_set_pixtext (GtkCTree *ctree, GtkCTreeNode *node, gint column, @@ -4662,7 +4685,15 @@ gtk_ctree_node_set_pixtext (GtkCTree *ctree, tree_draw_node (ctree, node); } -void + +/** + * gtk_ctree_set_node_info: + * @pixmap_closed: (allow-none): + * @mask_closed: (allow-none): + * @pixmap_opened: (allow-none): + * @mask_opened: (allow-none): + */ +void gtk_ctree_set_node_info (GtkCTree *ctree, GtkCTreeNode *node, const gchar *text, diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c index eb25f5224b..8d9dfe3fd7 100644 --- a/gtk/gtkdialog.c +++ b/gtk/gtkdialog.c @@ -529,12 +529,12 @@ gtk_dialog_new_empty (const gchar *title, /** * gtk_dialog_new_with_buttons: - * @title: Title of the dialog, or %NULL - * @parent: Transient parent of the dialog, or %NULL + * @title: (allow-none): Title of the dialog, or %NULL + * @parent: (allow-none): Transient parent of the dialog, or %NULL * @flags: from #GtkDialogFlags - * @first_button_text: stock ID or text to go in first button, or %NULL + * @first_button_text: (allow-none): stock ID or text to go in first button, or %NULL * @Varargs: response ID for first button, then additional buttons, ending with %NULL - * + * * Creates a new #GtkDialog with title @title (or %NULL for the default * title; see gtk_window_set_title()) and transient parent @parent (or * %NULL for none; see gtk_window_set_transient_for()). The @flags @@ -1191,10 +1191,10 @@ gtk_dialog_get_response_for_widget (GtkDialog *dialog, /** * gtk_alternative_dialog_button_order: - * @screen: a #GdkScreen, or %NULL to use the default screen + * @screen: (allow-none): a #GdkScreen, or %NULL to use the default screen * * Returns %TRUE if dialogs are expected to use an alternative - * button order on the screen @screen. See + * button order on the screen @screen. See * gtk_dialog_set_alternative_button_order() for more details * about alternative button order. * @@ -1519,7 +1519,7 @@ gtk_dialog_buildable_custom_finished (GtkBuildable *buildable, * * Returns the action area of @dialog. * - * Returns: the action area. + * Returns: (transfer none): the action area. * * Since: 2.14 **/ @@ -1537,7 +1537,7 @@ gtk_dialog_get_action_area (GtkDialog *dialog) * * Returns the content area of @dialog. * - * Returns: the content area #GtkVBox. + * Returns: (transfer none): the content area #GtkVBox. * * Since: 2.14 **/ diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c index c3a95d8432..3b300e16f1 100644 --- a/gtk/gtkdnd.c +++ b/gtk/gtkdnd.c @@ -2831,10 +2831,10 @@ gtk_drag_source_unset_icon (GtkDragSourceSite *site) * @widget: a #GtkWidget * @colormap: the colormap of the icon * @pixmap: the image data for the icon - * @mask: the transparency mask for an image. - * + * @mask: (allow-none): the transparency mask for an image. + * * Sets the icon that will be used for drags from a particular widget - * from a pixmap/mask. GTK+ retains references for the arguments, and + * from a pixmap/mask. GTK+ retains references for the arguments, and * will release them when they are no longer needed. * Use gtk_drag_source_set_icon_pixbuf() instead. **/ diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c index 8887b8ef62..4fc7b744a0 100644 --- a/gtk/gtkeditable.c +++ b/gtk/gtkeditable.c @@ -149,10 +149,10 @@ gtk_editable_base_init (gpointer g_class) * @editable: a #GtkEditable * @new_text: the text to append * @new_text_length: the length of the text in bytes, or -1 - * @position: location of the position text will be inserted at + * @position: (in-out): location of the position text will be inserted at * - * Inserts @new_text_length bytes of @new_text into the contents of the - * widget, at position @position. + * Inserts @new_text_length bytes of @new_text into the contents of the + * widget, at position @position. * * Note that the position is in characters, not in bytes. * The function updates @position to point after the newly inserted text. @@ -266,12 +266,12 @@ gtk_editable_get_position (GtkEditable *editable) /** * gtk_editable_get_selection_bounds: * @editable: a #GtkEditable - * @start_pos: location to store the starting position, or %NULL - * @end_pos: location to store the end position, or %NULL + * @start_pos: (out) (allow-none): location to store the starting position, or %NULL + * @end_pos: (out) (allow-none): location to store the end position, or %NULL * * Retrieves the selection bound of the editable. start_pos will be filled - * with the start of the selection and @end_pos with end. If no text was - * selected both will be identical and %FALSE will be returned. + * with the start of the selection and @end_pos with end. If no text was + * selected both will be identical and %FALSE will be returned. * * Note that positions are specified in characters, not bytes. * diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c index 9c885ca54d..962fd41b98 100644 --- a/gtk/gtkentry.c +++ b/gtk/gtkentry.c @@ -7238,7 +7238,7 @@ gtk_entry_get_has_frame (GtkEntry *entry) /** * gtk_entry_set_inner_border: * @entry: a #GtkEntry - * @border: a #GtkBorder, or %NULL + * @border: (allow-none): a #GtkBorder, or %NULL * * Sets %entry's inner-border property to %border, or clears it if %NULL * is passed. The inner-border is the area around the entry's text, but @@ -7276,7 +7276,7 @@ gtk_entry_set_inner_border (GtkEntry *entry, * 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. + * Return value: (transfer none): the entry's #GtkBorder, or %NULL if none was set. * * Since: 2.10 **/ @@ -7302,8 +7302,8 @@ gtk_entry_get_inner_border (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. - * - * Return value: the #PangoLayout for this entry + * + * Return value: (transfer none): the #PangoLayout for this entry **/ PangoLayout* gtk_entry_get_layout (GtkEntry *entry) @@ -9626,7 +9626,7 @@ connect_completion_signals (GtkEntry *entry, /** * gtk_entry_set_completion: * @entry: A #GtkEntry - * @completion: The #GtkEntryCompletion or %NULL + * @completion: (allow-none): 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 @@ -9743,9 +9743,9 @@ gtk_entry_set_cursor_hadjustment (GtkEntry *entry, * Retrieves the horizontal cursor adjustment for the entry. * See gtk_entry_set_cursor_hadjustment(). * - * Return value: the horizontal cursor adjustment, or %NULL + * Return value: (transfer none): the horizontal cursor adjustment, or %NULL * if none has been set. - * + * * Since: 2.12 */ GtkAdjustment* diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c index a3a01be9ff..bb5dda8b2e 100644 --- a/gtk/gtkentrycompletion.c +++ b/gtk/gtkentrycompletion.c @@ -1013,7 +1013,7 @@ gtk_entry_completion_get_entry (GtkEntryCompletion *completion) /** * gtk_entry_completion_set_model: * @completion: A #GtkEntryCompletion. - * @model: The #GtkTreeModel. + * @model: (allow-none): The #GtkTreeModel. * * Sets the model for a #GtkEntryCompletion. If @completion already has * a model set, it will remove it before setting the new model. diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c index 6866f982c9..2341123017 100644 --- a/gtk/gtkexpander.c +++ b/gtk/gtkexpander.c @@ -1288,9 +1288,9 @@ gtk_expander_new (const gchar *label) /** * gtk_expander_new_with_mnemonic: - * @label: the text of the label with an underscore in front of the + * @label: (allow-none): the text of the label with an underscore in front of the * mnemonic character - * + * * Creates a new expander using @label as the text of the label. * If characters in @label are preceded by an underscore, they are underlined. * If you need a literal underscore character in a label, use '__' (two @@ -1495,7 +1495,7 @@ gtk_expander_get_spacing (GtkExpander *expander) /** * gtk_expander_set_label: * @expander: a #GtkExpander - * @label: a string + * @label: (allow-none): a string * * Sets the text of the label of the expander to @label. * @@ -1674,7 +1674,7 @@ gtk_expander_get_use_markup (GtkExpander *expander) /** * gtk_expander_set_label_widget: * @expander: a #GtkExpander - * @label_widget: the new label widget + * @label_widget: (allow-none): the new label widget * * Set the label widget for the expander. This is the widget * that will appear embedded alongside the expander arrow. diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c index 6c7de57225..760c24ce78 100644 --- a/gtk/gtkfilechooser.c +++ b/gtk/gtkfilechooser.c @@ -660,8 +660,8 @@ files_to_strings (GSList *files, * @chooser. The returned names are full absolute paths. If files in the current * folder cannot be represented as local filenames they will be ignored. (See * gtk_file_chooser_get_uris()) - * - * Return value: a #GSList containing the filenames of all selected + * + * Return value: (element-type utf8) (transfer full): a #GSList containing the filenames of all selected * files and subfolders in the current folder. Free the returned list * with g_slist_free(), and the filenames with g_free(). * @@ -964,8 +964,8 @@ gtk_file_chooser_unselect_all (GtkFileChooser *chooser) * * Lists all the selected files and subfolders in the current folder of * @chooser. The returned names are full absolute URIs. - * - * Return value: a #GSList containing the URIs of all selected + * + * Return value: (element-type utf8) (transfer full): a #GSList containing the URIs of all selected * files and subfolders in the current folder. Free the returned list * with g_slist_free(), and the filenames with g_free(). * @@ -1155,8 +1155,8 @@ gtk_file_chooser_unselect_file (GtkFileChooser *chooser, * * Lists all the selected files and subfolders in the current folder of @chooser * as #GFile. An internal function, see gtk_file_chooser_get_uris(). - * - * Return value: a #GSList containing a #GFile for each selected + * + * Return value: (element-type utf8) (transfer full): a #GSList containing a #GFile for each selected * file and subfolder in the current folder. Free the returned list * with g_slist_free(), and the files with g_object_unref(). * @@ -1665,8 +1665,8 @@ gtk_file_chooser_remove_filter (GtkFileChooser *chooser, * * Lists the current set of user-selectable filters; see * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter(). - * - * Return value: a #GSList containing the current set of + * + * Return value: (element-type utf8) (transfer container): a #GSList containing the current set of * user selectable filters. The contents of the list are * owned by GTK+, but you must free the list itself with * g_slist_free() when you are done with it. @@ -1806,8 +1806,8 @@ gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser, * * Queries the list of shortcut folders in the file chooser, as set by * gtk_file_chooser_add_shortcut_folder(). - * - * Return value: A list of folder filenames, or %NULL if there are no shortcut + * + * Return value: (element-type utf8) (transfer full): A list of folder filenames, or %NULL if there are no shortcut * folders. Free the returned list with g_slist_free(), and the filenames with * g_free(). * @@ -1903,8 +1903,8 @@ gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser, * * Queries the list of shortcut folders in the file chooser, as set by * gtk_file_chooser_add_shortcut_folder_uri(). - * - * Return value: A list of folder URIs, or %NULL if there are no shortcut + * + * Return value: (element-type utf8) (transfer full): A list of folder URIs, or %NULL if there are no shortcut * folders. Free the returned list with g_slist_free(), and the URIs with * g_free(). * diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c index c76745572b..eba0fd9c4d 100644 --- a/gtk/gtkframe.c +++ b/gtk/gtkframe.c @@ -306,8 +306,8 @@ gtk_frame_forall (GtkContainer *container, /** * gtk_frame_set_label: * @frame: a #GtkFrame - * @label: the text to use as the label of the frame - * + * @label: (allow-none): the text to use as the label of the frame + * * Sets the text of the label. If @label is %NULL, * the current label is removed. **/ diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c index 145d935e8e..906a757656 100644 --- a/gtk/gtkiconfactory.c +++ b/gtk/gtkiconfactory.c @@ -1620,7 +1620,7 @@ render_fallback_image (GtkStyle *style, /** * gtk_icon_set_render_icon: * @icon_set: a #GtkIconSet - * @style: a #GtkStyle associated with @widget, or %NULL + * @style: (allow-none): a #GtkStyle associated with @widget, or %NULL * @direction: text direction * @state: widget state * @size: icon size. A size of (GtkIconSize)-1 @@ -1762,7 +1762,7 @@ gtk_icon_set_add_source (GtkIconSet *icon_set, /** * gtk_icon_set_get_sizes: * @icon_set: a #GtkIconSet - * @sizes: return location for array of sizes + * @sizes: (array length=n_sizes) (out): return location for array of sizes * @n_sizes: location to store number of elements in returned array * * Obtains a list of icon sizes this icon set can render. The returned @@ -2033,7 +2033,7 @@ gtk_icon_source_set_filename (GtkIconSource *source, /** * gtk_icon_source_set_icon_name * @source: a #GtkIconSource - * @icon_name: name of icon to use + * @icon_name: (allow-none): name of icon to use * * Sets the name of an icon to look up in the current icon theme * to use as a base image when creating icon variants for #GtkIconSet. diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c index c4196cde1b..bb678d0b75 100644 --- a/gtk/gtkicontheme.c +++ b/gtk/gtkicontheme.c @@ -275,8 +275,8 @@ gtk_icon_theme_new (void) * * Gets the icon theme for the default screen. See * gtk_icon_theme_get_for_screen(). - * - * Return value: A unique #GtkIconTheme associated with + * + * Return value: (transfer none): A unique #GtkIconTheme associated with * the default screen. This icon theme is associated with * the screen and can be used as long as the screen * is open. Do not ref or unref it. @@ -301,8 +301,8 @@ gtk_icon_theme_get_default (void) * is usually a better choice than calling than gtk_icon_theme_new() * and setting the screen yourself; by using this function * a single icon theme object will be shared between users. - * - * Return value: A unique #GtkIconTheme associated with + * + * Return value: (transfer none): A unique #GtkIconTheme associated with * the given screen. This icon theme is associated with * the screen and can be used as long as the screen * is open. Do not ref or unref it. @@ -1738,8 +1738,8 @@ add_key_to_list (gpointer key, * The set of values for the context string is system dependent, * but will typically include such values as "Applications" and * "MimeTypes". - * - * Return value: a #GList list holding the names of all the + * + * Return value: (element-type utf8) (transfer none): a #GList list holding the names of all the * icons in the theme. You must first free each element * in the list with g_free(), then free the list itself * with g_list_free(). @@ -1801,7 +1801,7 @@ gtk_icon_theme_list_icons (GtkIconTheme *icon_theme, * Gets the list of contexts available within the current * hierarchy of icon themes * - * Return value: a #GList list holding the names of all the + * Return value: (element-type utf8) (transfer full): a #GList list holding the names of all the * contexts in the theme. You must first free each element * in the list with g_free(), then free the list itself * with g_list_free(). @@ -2749,8 +2749,8 @@ gtk_icon_info_get_filename (GtkIconInfo *icon_info) * GTK+ to use built in icon images, you must pass the * %GTK_ICON_LOOKUP_USE_BUILTIN to * gtk_icon_theme_lookup_icon(). - * - * Return value: the built-in image pixbuf, or %NULL. No + * + * Return value: (transfer none): the built-in image pixbuf, or %NULL. No * extra reference is added to the returned pixbuf, so if * you want to keep it around, you must use g_object_ref(). * The returned image must not be modified. diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c index 14ee4891c4..14a574ce03 100644 --- a/gtk/gtkiconview.c +++ b/gtk/gtkiconview.c @@ -1992,11 +1992,11 @@ gtk_icon_view_stop_editing (GtkIconView *icon_view, * gtk_icon_view_set_cursor: * @icon_view: A #GtkIconView * @path: A #GtkTreePath - * @cell: One of the cell renderers of @icon_view, or %NULL + * @cell: (allow-none): One of the cell renderers of @icon_view, or %NULL * @start_editing: %TRUE if the specified cell should start being edited. * * Sets the current keyboard focus to be at @path, and selects it. This is - * useful when you want to focus the user's attention on a particular item. + * useful when you want to focus the user's attention on a particular item. * If @cell is not %NULL, then focus is given to the cell specified by * it. Additionally, if @start_editing is %TRUE, then editing should be * started in the specified cell. @@ -5266,10 +5266,10 @@ gtk_icon_view_get_selection_mode (GtkIconView *icon_view) /** * gtk_icon_view_set_model: * @icon_view: A #GtkIconView. - * @model: The model. + * @model: (allow-none): The model. * - * Sets the model for a #GtkIconView. - * If the @icon_view already has a model set, it will remove + * Sets the model for a #GtkIconView. + * If the @icon_view already has a model set, it will remove * it before setting the new model. If @model is %NULL, then * it will unset the old model. * @@ -5798,7 +5798,7 @@ gtk_icon_view_unselect_path (GtkIconView *icon_view, * g_list_free (list); * ]| * - * Return value: A #GList containing a #GtkTreePath for each selected row. + * Return value: (element-type GtkTreePath) (transfer full): A #GList containing a #GtkTreePath for each selected row. * * Since: 2.6 **/ @@ -7199,9 +7199,9 @@ gtk_icon_view_unset_model_drag_dest (GtkIconView *icon_view) /** * gtk_icon_view_set_drag_dest_item: * @icon_view: a #GtkIconView - * @path: The path of the item to highlight, or %NULL. + * @path: (allow-none): The path of the item to highlight, or %NULL. * @pos: Specifies where to drop, relative to the item - * + * * Sets the item that is highlighted for feedback. * * Since: 2.8 diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c index 6c53d30721..5f3e7145ad 100644 --- a/gtk/gtkimage.c +++ b/gtk/gtkimage.c @@ -492,9 +492,9 @@ gtk_image_get_property (GObject *object, /** * gtk_image_new_from_pixmap: - * @pixmap: a #GdkPixmap, or %NULL - * @mask: a #GdkBitmap, or %NULL - * + * @pixmap: (allow-none): a #GdkPixmap, or %NULL + * @mask: (allow-none): a #GdkBitmap, or %NULL + * * Creates a #GtkImage widget displaying @pixmap with a @mask. * A #GdkPixmap is a server-side image buffer in the pixel format of the * current display. The #GtkImage does not assume a reference to the @@ -518,9 +518,9 @@ gtk_image_new_from_pixmap (GdkPixmap *pixmap, /** * gtk_image_new_from_image: - * @image: a #GdkImage, or %NULL - * @mask: a #GdkBitmap, or %NULL - * + * @image: (allow-none): a #GdkImage, or %NULL + * @mask: (allow-none): a #GdkBitmap, or %NULL + * * 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 @@ -579,8 +579,8 @@ gtk_image_new_from_file (const gchar *filename) /** * gtk_image_new_from_pixbuf: - * @pixbuf: a #GdkPixbuf, or %NULL - * + * @pixbuf: (allow-none): a #GdkPixbuf, or %NULL + * * Creates a new #GtkImage displaying @pixbuf. * The #GtkImage does not assume a reference to the * pixbuf; you still need to unref it if you own references. @@ -750,8 +750,8 @@ gtk_image_new_from_gicon (GIcon *icon, /** * gtk_image_set_from_pixmap: * @image: a #GtkImage - * @pixmap: a #GdkPixmap or %NULL - * @mask: a #GdkBitmap or %NULL + * @pixmap: (allow-none): a #GdkPixmap or %NULL + * @mask: (allow-none): a #GdkBitmap or %NULL * * See gtk_image_new_from_pixmap() for details. **/ @@ -801,8 +801,8 @@ gtk_image_set_from_pixmap (GtkImage *image, /** * gtk_image_set_from_image: * @image: a #GtkImage - * @gdk_image: a #GdkImage or %NULL - * @mask: a #GdkBitmap or %NULL + * @gdk_image: (allow-none): a #GdkImage or %NULL + * @mask: (allow-none): a #GdkBitmap or %NULL * * See gtk_image_new_from_image() for details. **/ @@ -852,7 +852,7 @@ gtk_image_set_from_image (GtkImage *image, /** * gtk_image_set_from_file: * @image: a #GtkImage - * @filename: a filename or %NULL + * @filename: (allow-none): a filename or %NULL * * See gtk_image_new_from_file() for details. **/ @@ -908,9 +908,9 @@ gtk_image_set_from_file (GtkImage *image, /** * gtk_image_set_from_pixbuf: * @image: a #GtkImage - * @pixbuf: a #GdkPixbuf or %NULL + * @pixbuf: (allow-none): a #GdkPixbuf or %NULL * - * See gtk_image_new_from_pixbuf() for details. + * See gtk_image_new_from_pixbuf() for details. **/ void gtk_image_set_from_pixbuf (GtkImage *image, diff --git a/gtk/gtkimagemenuitem.c b/gtk/gtkimagemenuitem.c index 9116a4840e..4441145051 100644 --- a/gtk/gtkimagemenuitem.c +++ b/gtk/gtkimagemenuitem.c @@ -916,8 +916,8 @@ gtk_image_menu_item_set_accel_group (GtkImageMenuItem *image_menu_item, /** * gtk_image_menu_item_set_image: * @image_menu_item: a #GtkImageMenuItem. - * @image: a widget to set as the image for the menu item. - * + * @image: (allow-none): a widget to set as the image for the menu item. + * * Sets the image of @image_menu_item to the given widget. * Note that it depends on the show-menu-images setting whether * the image will be displayed or not. diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c index 70c01a6223..2eab969869 100644 --- a/gtk/gtkitemfactory.c +++ b/gtk/gtkitemfactory.c @@ -147,12 +147,12 @@ gtk_item_factory_init (GtkItemFactory *ifactory) * gtk_item_factory_new: * @container_type: the kind of menu to create; can be * #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU - * @path: the factory path of the new item factory, a string of the form + * @path: the factory path of the new item factory, a string of the form * "<name>" - * @accel_group: a #GtkAccelGroup to which the accelerators for the + * @accel_group: (allow-none): a #GtkAccelGroup to which the accelerators for the * menu items will be added, or %NULL to create a new one * @returns: a new #GtkItemFactory - * + * * Creates a new #GtkItemFactory. * * Beware that the returned object does not have a floating reference. diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index c3df84a2dc..73fa93a35b 100644 --- a/gtk/gtklabel.c +++ b/gtk/gtklabel.c @@ -1610,7 +1610,7 @@ label_mnemonic_widget_weak_notify (gpointer data, /** * gtk_label_set_mnemonic_widget: * @label: a #GtkLabel - * @widget: the target #GtkWidget + * @widget: (allow-none): 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(), @@ -4850,8 +4850,8 @@ gtk_label_get_selection_bounds (GtkLabel *label, * pixel positions, in combination with gtk_label_get_layout_offsets(). * The returned layout is owned by the label so need not be * freed by the caller. - * - * Return value: the #PangoLayout for this label + * + * Return value: (transfer none): the #PangoLayout for this label **/ PangoLayout* gtk_label_get_layout (GtkLabel *label) diff --git a/gtk/gtklayout.c b/gtk/gtklayout.c index 153a2dfca4..0a11f48112 100644 --- a/gtk/gtklayout.c +++ b/gtk/gtklayout.c @@ -285,7 +285,7 @@ gtk_layout_finalize (GObject *object) /** * gtk_layout_set_hadjustment: * @layout: a #GtkLayout - * @adjustment: new scroll adjustment + * @adjustment: (allow-none): new scroll adjustment * * Sets the horizontal scroll adjustment for the layout. * @@ -305,7 +305,7 @@ gtk_layout_set_hadjustment (GtkLayout *layout, /** * gtk_layout_set_vadjustment: * @layout: a #GtkLayout - * @adjustment: new scroll adjustment + * @adjustment: (allow-none): new scroll adjustment * * Sets the vertical scroll adjustment for the layout. * diff --git a/gtk/gtklinkbutton.c b/gtk/gtklinkbutton.c index 60ce24a8e2..eaa6678dc2 100644 --- a/gtk/gtklinkbutton.c +++ b/gtk/gtklinkbutton.c @@ -600,11 +600,11 @@ gtk_link_button_new (const gchar *uri) /** * gtk_link_button_new_with_label: * @uri: a valid URI - * @label: the text of the button + * @label: (allow-none): the text of the button * * Creates a new #GtkLinkButton containing a label. * - * Return value: a new link button widget. + * Return value: (transfer none): a new link button widget. * * Since: 2.10 */ diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index 8ab1f18fbf..71ceb1cad0 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -267,11 +267,11 @@ gtk_list_store_new (gint n_columns, /** * gtk_list_store_newv: * @n_columns: number of columns in the list store - * @types: an array of #GType types for the columns, from first to last + * @types: (array length=n_columns): an array of #GType types for the columns, from first to last * * Non-vararg creation function. Used primarily by language bindings. * - * Return value: a new #GtkListStore + * Return value: (transfer none): a new #GtkListStore **/ GtkListStore * gtk_list_store_newv (gint n_columns, @@ -304,8 +304,8 @@ gtk_list_store_newv (gint n_columns, * gtk_list_store_set_column_types: * @list_store: A #GtkListStore * @n_columns: Number of columns for the list store - * @types: An array length n of #GTypes - * + * @types: (array length=n_columns): An array length n of #GTypes + * * This function is meant primarily for #GObjects that inherit from #GtkListStore, * and should only be used when constructing a new #GtkListStore. It will not * function after a row has been added, or a method on the #GtkTreeModel @@ -832,10 +832,10 @@ gtk_list_store_set_valist_internal (GtkListStore *list_store, * gtk_list_store_set_valuesv: * @list_store: A #GtkListStore * @iter: A valid #GtkTreeIter for the row being modified - * @columns: an array of column numbers - * @values: an array of GValues + * @columns: (array length=n_values): an array of column numbers + * @values: (array length=n_values): an array of GValues * @n_values: the length of the @columns and @values arrays - * + * * A variant of gtk_list_store_set_valist() which * takes the columns and values as two arrays, instead of * varargs. This function is mainly intended for @@ -1579,7 +1579,7 @@ gtk_list_store_move_to (GtkListStore *store, * gtk_list_store_move_before: * @store: A #GtkListStore. * @iter: A #GtkTreeIter. - * @position: A #GtkTreeIter, or %NULL. + * @position: (allow-none): A #GtkTreeIter, or %NULL. * * Moves @iter in @store to the position before @position. Note that this * function only works with unsorted stores. If @position is %NULL, @iter @@ -1612,7 +1612,7 @@ gtk_list_store_move_before (GtkListStore *store, * gtk_list_store_move_after: * @store: A #GtkListStore. * @iter: A #GtkTreeIter. - * @position: A #GtkTreeIter or %NULL. + * @position: (allow-none): A #GtkTreeIter or %NULL. * * Moves @iter in @store to the position after @position. Note that this * function only works with unsorted stores. If @position is %NULL, @iter diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c index 5a8a0ef1fc..581403b541 100644 --- a/gtk/gtkmain.c +++ b/gtk/gtkmain.c @@ -882,9 +882,9 @@ gtk_init_with_args (int *argc, /** * gtk_parse_args: - * @argc: a pointer to the number of command line arguments. - * @argv: a pointer to the array of command line arguments. - * + * @argc: (inout): a pointer to the number of command line arguments. + * @argv: (array) (inout): a pointer to the array of command line arguments. + * * Parses command line arguments, and initializes global * attributes of GTK+, but does not actually open a connection * to a display. (See gdk_display_open(), gdk_get_display_arg_name()) @@ -935,13 +935,13 @@ gtk_parse_args (int *argc, /** * gtk_init_check: - * @argc: Address of the argc parameter of your + * @argc: (inout): Address of the argc parameter of your * main() function. Changed if any arguments were handled. - * @argv: Address of the argv parameter of main(). + * @argv: (array length=argc) (inout) (allow-none): Address of the argv parameter of main(). * Any parameters understood by gtk_init() are stripped before return. - * - * This function does the same work as gtk_init() with only - * a single change: It does not terminate the program if the GUI can't be + * + * This function does the same work as gtk_init() with only + * a single change: It does not terminate the program if the GUI can't be * initialized. Instead it returns %FALSE on failure. * * This way the application can fall back to some other means of communication @@ -966,13 +966,13 @@ gtk_init_check (int *argc, /** * gtk_init: - * @argc: Address of the argc parameter of your + * @argc: (inout): Address of the argc parameter of your * main() function. Changed if any arguments were handled. - * @argv: Address of the argv parameter of main(). + * @argv: (array length=argc) (inout) (allow-none): Address of the argv parameter of main(). * Any parameters understood by gtk_init() are stripped before return. - * + * * Call this function before using any other GTK+ functions in your GUI - * applications. It will initialize everything needed to operate the + * applications. It will initialize everything needed to operate the * toolkit and parses some standard command line options. @argc and * @argv are adjusted accordingly so your own code will * never see those standard arguments. diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c index 0bdf1dea76..e8813c9f0d 100644 --- a/gtk/gtkmenu.c +++ b/gtk/gtkmenu.c @@ -1747,6 +1747,11 @@ gtk_menu_set_active (GtkMenu *menu, } } + +/** + * gtk_menu_set_accel_group: + * @accel_group: (allow-none): + */ void gtk_menu_set_accel_group (GtkMenu *menu, GtkAccelGroup *accel_group) @@ -1793,7 +1798,7 @@ gtk_menu_real_can_activate_accel (GtkWidget *widget, /** * gtk_menu_set_accel_path * @menu: a valid #GtkMenu - * @accel_path: a valid accelerator path + * @accel_path: (allow-none): a valid accelerator path * * Sets an accelerator path for this menu from which accelerator paths * for its immediate children, its menu items, can be constructed. @@ -4810,11 +4815,11 @@ gtk_menu_hide_all (GtkWidget *widget) /** * gtk_menu_set_screen: * @menu: a #GtkMenu. - * @screen: a #GdkScreen, or %NULL if the screen should be + * @screen: (allow-none): a #GdkScreen, or %NULL if the screen should be * determined by the widget the menu is attached to. * * Sets the #GdkScreen on which the menu will be displayed. - * + * * Since: 2.2 **/ void @@ -5282,7 +5287,7 @@ gtk_menu_get_monitor (GtkMenu *menu) * Returns a list of the menus which are attached to this widget. * This list is owned by GTK+ and must not be modified. * - * Return value: the list of menus attached to his widget. + * Return value: (element-type GtkWidget) (transfer none): the list of menus attached to his widget. * * Since: 2.6 **/ diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c index 1ab96b00a2..13db059bd4 100644 --- a/gtk/gtkmenuitem.c +++ b/gtk/gtkmenuitem.c @@ -2001,7 +2001,7 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem *menu_item, /** * gtk_menu_item_set_accel_path * @menu_item: a valid #GtkMenuItem - * @accel_path: accelerator path, corresponding to this menu item's + * @accel_path: (allow-none): accelerator path, corresponding to this menu item's * functionality, or %NULL to unset the current path. * * Set the accelerator path on @menu_item, through which runtime changes of the diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c index bc6e5cb6a8..c0022fe0f5 100644 --- a/gtk/gtkmenutoolbutton.c +++ b/gtk/gtkmenutoolbutton.c @@ -596,8 +596,8 @@ gtk_menu_tool_button_get_menu (GtkMenuToolButton *button) * gtk_menu_tool_button_set_arrow_tooltip: * @button: a #GtkMenuToolButton * @tooltips: the #GtkTooltips object to be used - * @tip_text: text to be used as tooltip text for tool_item - * @tip_private: text to be used as private tooltip text + * @tip_text: (allow-none): text to be used as tooltip text for tool_item + * @tip_private: (allow-none): text to be used as private tooltip text * * Sets the #GtkTooltips object to be used for arrow button which * pops up the menu. See gtk_tool_item_set_tooltip() for setting diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c index ecae119220..b721aded36 100644 --- a/gtk/gtkmessagedialog.c +++ b/gtk/gtkmessagedialog.c @@ -475,20 +475,20 @@ gtk_message_dialog_get_property (GObject *object, /** * gtk_message_dialog_new: - * @parent: transient parent, or %NULL for none + * @parent: (allow-none): transient parent, or %NULL for none * @flags: flags * @type: type of message * @buttons: set of buttons to use - * @message_format: printf()-style format string, or %NULL + * @message_format: (allow-none): printf()-style format string, or %NULL * @Varargs: arguments for @message_format - * + * * Creates a new message dialog, which is a simple dialog with an icon * indicating the dialog type (error, warning, etc.) and some text the * user may want to see. When the user clicks a button a "response" * signal is emitted with response IDs from #GtkResponseType. See * #GtkDialog for more details. - * - * Return value: a new #GtkMessageDialog + * + * Return value: (transfer none): a new #GtkMessageDialog **/ GtkWidget* gtk_message_dialog_new (GtkWindow *parent, diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c index b51388cca4..ed48977ec4 100644 --- a/gtk/gtknotebook.c +++ b/gtk/gtknotebook.c @@ -6384,9 +6384,9 @@ gtk_notebook_set_tab_vborder_internal (GtkNotebook *notebook, * gtk_notebook_append_page: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. - * + * * Appends a page to @notebook. * * Return value: the index (starting from 0) of the appended @@ -6408,9 +6408,9 @@ gtk_notebook_append_page (GtkNotebook *notebook, * gtk_notebook_append_page_menu: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. - * @menu_label: the widget to use as a label for the page-switch + * @menu_label: (allow-none): the widget to use as a label for the page-switch * menu, if that is enabled. If %NULL, and @tab_label * is a #GtkLabel or %NULL, then the menu label will be * a newly created label with the same text as @tab_label; @@ -6441,7 +6441,7 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook, * gtk_notebook_prepend_page: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. * * Prepends a page to @notebook. @@ -6465,9 +6465,9 @@ gtk_notebook_prepend_page (GtkNotebook *notebook, * gtk_notebook_prepend_page_menu: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. - * @menu_label: the widget to use as a label for the page-switch + * @menu_label: (allow-none): the widget to use as a label for the page-switch * menu, if that is enabled. If %NULL, and @tab_label * is a #GtkLabel or %NULL, then the menu label will be * a newly created label with the same text as @tab_label; @@ -6498,11 +6498,11 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook, * gtk_notebook_insert_page: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. * @position: the index (starting at 0) at which to insert the page, * or -1 to append the page after all other pages. - * + * * Insert a page into @notebook at the given position. * * Return value: the index (starting from 0) of the inserted @@ -6555,9 +6555,9 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child, * gtk_notebook_insert_page_menu: * @notebook: a #GtkNotebook * @child: the #GtkWidget to use as the contents of the page. - * @tab_label: the #GtkWidget to be used as the label for the page, + * @tab_label: (allow-none): the #GtkWidget to be used as the label for the page, * or %NULL to use the default label, 'page N'. - * @menu_label: the widget to use as a label for the page-switch + * @menu_label: (allow-none): the widget to use as a label for the page-switch * menu, if that is enabled. If %NULL, and @tab_label * is a #GtkLabel or %NULL, then the menu label will be * a newly created label with the same text as @tab_label; @@ -6654,8 +6654,8 @@ gtk_notebook_get_current_page (GtkNotebook *notebook) * to get the last page. * * Returns the child widget contained in page number @page_num. - * - * Return value: the child widget, or %NULL if @page_num is + * + * Return value: (transfer none): the child widget, or %NULL if @page_num is * out of bounds. **/ GtkWidget* @@ -7173,8 +7173,8 @@ gtk_notebook_popup_disable (GtkNotebook *notebook) * Returns the tab label widget for the page @child. %NULL is returned * if @child is not in @notebook or if no tab label has specifically * been set for @child. - * - * Return value: the tab label + * + * Return value: (transfer none): the tab label **/ GtkWidget * gtk_notebook_get_tab_label (GtkNotebook *notebook, @@ -7199,9 +7199,9 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook, * gtk_notebook_set_tab_label: * @notebook: a #GtkNotebook * @child: the page - * @tab_label: the tab label widget to use, or %NULL for default tab + * @tab_label: (allow-none): the tab label widget to use, or %NULL for default tab * label. - * + * * Changes the tab label for @child. If %NULL is specified * for @tab_label, then the page will have the label 'page N'. **/ @@ -7358,9 +7358,9 @@ gtk_notebook_get_menu_label (GtkNotebook *notebook, * gtk_notebook_set_menu_label: * @notebook: a #GtkNotebook * @child: the child widget - * @menu_label: the menu label, or NULL for default - * - * Changes the menu label for the page containing @child. + * @menu_label: (allow-none): the menu label, or NULL for default + * + * Changes the menu label for the page containing @child. **/ void gtk_notebook_set_menu_label (GtkNotebook *notebook, diff --git a/gtk/gtkpapersize.c b/gtk/gtkpapersize.c index a806ae8d95..f24b15f0b2 100644 --- a/gtk/gtkpapersize.c +++ b/gtk/gtkpapersize.c @@ -191,11 +191,11 @@ gtk_paper_size_new_from_info (const PaperInfo *info) /** * gtk_paper_size_new: - * @name: a paper size name, or %NULL - * - * Creates a new #GtkPaperSize object by parsing a + * @name: (allow-none): a paper size name, or %NULL + * + * Creates a new #GtkPaperSize object by parsing a * PWG 5101.1-2002 - * paper name. + * paper name. * * If @name is %NULL, the default paper size is returned, * see gtk_paper_size_get_default(). @@ -443,8 +443,8 @@ GList * _gtk_load_custom_papers (void); * as defined in the page setup dialog * * Creates a list of known paper sizes. - * - * Return value: a newly allocated list of newly + * + * Return value: (element-type GtkPaperSize) (transfer full): a newly allocated list of newly * allocated #GtkPaperSize objects * * Since: 2.12 diff --git a/gtk/gtkpixmap.c b/gtk/gtkpixmap.c index 74a05aa5a4..60e4bd0ed8 100644 --- a/gtk/gtkpixmap.c +++ b/gtk/gtkpixmap.c @@ -69,6 +69,10 @@ gtk_pixmap_init (GtkPixmap *pixmap) pixmap->mask = NULL; } +/** + * gtk_pixmap_new: + * @mask: (allow-none): + */ GtkWidget* gtk_pixmap_new (GdkPixmap *val, GdkBitmap *mask) diff --git a/gtk/gtkprintbackend.c b/gtk/gtkprintbackend.c index 648a47248c..9e310226b2 100644 --- a/gtk/gtkprintbackend.c +++ b/gtk/gtkprintbackend.c @@ -304,6 +304,11 @@ _gtk_print_backend_create (const gchar *backend_name) return pb; } +/** + * gtk_printer_backend_load_modules: + * + * Return value: (element-type GtkPrintBackend) (transfer container): + */ GList * gtk_print_backend_load_modules (void) { @@ -587,6 +592,11 @@ gtk_print_backend_set_list_done (GtkPrintBackend *backend) } +/** + * gtk_print_backend_get_printer_list: + * + * Return value: (element-type GtkPrinter) (transfer container): + */ GList * gtk_print_backend_get_printer_list (GtkPrintBackend *backend) { diff --git a/gtk/gtkprinter.c b/gtk/gtkprinter.c index 3ad30ccad6..9ef7dc892d 100644 --- a/gtk/gtkprinter.c +++ b/gtk/gtkprinter.c @@ -932,8 +932,8 @@ _gtk_printer_create_cairo_surface (GtkPrinter *printer, * Lists all the paper sizes @printer supports. * This will return and empty list unless the printer's details are * available, see gtk_printer_has_details() and gtk_printer_request_details(). - * - * Return value: a newly allocated list of newly allocated #GtkPageSetup s. + * + * Return value: (element-type GtkPageSetup) (transfer full): a newly allocated list of newly allocated #GtkPageSetup s. * * Since: 2.12 */ diff --git a/gtk/gtkprinteroptionset.c b/gtk/gtkprinteroptionset.c index eb84a3448e..391e5a6548 100644 --- a/gtk/gtkprinteroptionset.c +++ b/gtk/gtkprinteroptionset.c @@ -155,6 +155,11 @@ safe_strcmp (const char *a, const char *b) return strcmp (a, b); } +/** + * gtk_printer_option_set_get_groups: + * + * Return value: (element-type utf8) (transfer full): + */ GList * gtk_printer_option_set_get_groups (GtkPrinterOptionSet *set) { diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c index fb3b51adc0..4ac60de879 100644 --- a/gtk/gtkprintoperation-unix.c +++ b/gtk/gtkprintoperation-unix.c @@ -967,12 +967,12 @@ get_page_setup_dialog (GtkWindow *parent, /** * gtk_print_run_page_setup_dialog: - * @parent: transient parent, or %NULL - * @page_setup: an existing #GtkPageSetup, or %NULL + * @parent: (allow-none): transient parent + * @page_setup: (allow-none): an existing #GtkPageSetup * @settings: a #GtkPrintSettings - * - * Runs a page setup dialog, letting the user modify the values from - * @page_setup. If the user cancels the dialog, the returned #GtkPageSetup + * + * Runs a page setup dialog, letting the user modify the values from + * @page_setup. If the user cancels the dialog, the returned #GtkPageSetup * is identical to the passed in @page_setup, otherwise it contains the * modifications done in the dialog. * diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c index 9e7b58137c..bc1b27f57d 100644 --- a/gtk/gtkprintoperation.c +++ b/gtk/gtkprintoperation.c @@ -1361,8 +1361,8 @@ gtk_print_operation_new (void) /** * gtk_print_operation_set_default_page_setup: * @op: a #GtkPrintOperation - * @default_page_setup: a #GtkPageSetup, or %NULL - * + * @default_page_setup: (allow-none): a #GtkPageSetup, or %NULL + * * Makes @default_page_setup the default page setup for @op. * * This page setup will be used by gtk_print_operation_run(), @@ -1420,8 +1420,8 @@ gtk_print_operation_get_default_page_setup (GtkPrintOperation *op) /** * gtk_print_operation_set_print_settings: * @op: a #GtkPrintOperation - * @print_settings: #GtkPrintSettings, or %NULL - * + * @print_settings: (allow-none): #GtkPrintSettings + * * Sets the print settings for @op. This is typically used to * re-establish print settings from a previous print operation, * see gtk_print_operation_run(). @@ -2992,9 +2992,9 @@ gtk_print_operation_get_error (GtkPrintOperation *op, * gtk_print_operation_run: * @op: a #GtkPrintOperation * @action: the action to start - * @parent: Transient parent of the dialog, or %NULL + * @parent: (allow-none): Transient parent of the dialog * @error: Return location for errors, or %NULL - * + * * Runs the print operation, by first letting the user modify * print settings in the print dialog, and then print the document. * diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c index ee7d6c69d2..748c6ee0d0 100644 --- a/gtk/gtkprintsettings.c +++ b/gtk/gtkprintsettings.c @@ -155,11 +155,11 @@ gtk_print_settings_get (GtkPrintSettings *settings, * gtk_print_settings_set: * @settings: a #GtkPrintSettings * @key: a key - * @value: a string value, or %NULL - * + * @value: (allow-none): a string value, or %NULL + * * Associates @value with @key. * - * Since: 2.10 + * Since: 2.10 */ void gtk_print_settings_set (GtkPrintSettings *settings, @@ -473,9 +473,9 @@ gtk_print_settings_set_int (GtkPrintSettings *settings, /** * gtk_print_settings_foreach: * @settings: a #GtkPrintSettings - * @func: the function to call + * @func: (scope call) the function to call * @user_data: user data for @func - * + * * Calls @func for each key-value pair of @settings. * * Since: 2.10 diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c index 96b316748a..f2c51d8d69 100644 --- a/gtk/gtkprogressbar.c +++ b/gtk/gtkprogressbar.c @@ -398,6 +398,14 @@ gtk_progress_bar_new (void) return pbar; } +/** + * gtk_progress_bar_new_with_adjustment: + * @adjustment: (allow-none): + * + * Creates a new #GtkProgressBar with an associated #GtkAdjustment. + * + * Returns: (transfer none): a #GtkProgressBar. + */ GtkWidget* gtk_progress_bar_new_with_adjustment (GtkAdjustment *adjustment) { diff --git a/gtk/gtkradioaction.c b/gtk/gtkradioaction.c index 48784c40d8..1d9cfc56e6 100644 --- a/gtk/gtkradioaction.c +++ b/gtk/gtkradioaction.c @@ -395,7 +395,7 @@ create_menu_item (GtkAction *action) * } * ]| * - * Returns: the list representing the radio group for this object + * Returns: (element-type GtkAction) (transfer none): the list representing the radio group for this object * * Since: 2.4 */ diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c index f07113fe22..cef0bb216b 100644 --- a/gtk/gtkradiobutton.c +++ b/gtk/gtkradiobutton.c @@ -341,6 +341,18 @@ gtk_radio_button_new_with_mnemonic_from_widget (GtkRadioButton *radio_group_memb return gtk_radio_button_new_with_mnemonic (l, label); } + +/** + * gtk_radio_button_get_group: + * @radio_button: a #GtkRadioButton. + * + * Retrieves the group assigned to a radio button. + * + * Return value: (element-type GtkRadioButton) (transfer none): a linked list + * containing all the radio buttons in the same group + * as @radio_button. The returned list is owned by the radio button + * and must not be modified or freed. + */ GSList* gtk_radio_button_get_group (GtkRadioButton *radio_button) { diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c index f17b5ed2b7..9bb5c112fd 100644 --- a/gtk/gtkradiomenuitem.c +++ b/gtk/gtkradiomenuitem.c @@ -180,6 +180,16 @@ gtk_radio_menu_item_set_group (GtkRadioMenuItem *radio_menu_item, g_object_unref (radio_menu_item); } + +/** + * gtk_radio_menu_item_new_with_label: + * @group: (element-type GtkRadioMenuItem) (transfer full): + * @label: the text for the label + * + * Creates a new #GtkRadioMenuItem whose child is a simple #GtkLabel. + * + * Returns: (transfer none): A new #GtkRadioMenuItem + */ GtkWidget* gtk_radio_menu_item_new_with_label (GSList *group, const gchar *label) diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c index 70540a3130..691cbf1049 100644 --- a/gtk/gtkrc.c +++ b/gtk/gtkrc.c @@ -2028,13 +2028,13 @@ gtk_rc_get_style (GtkWidget *widget) /** * gtk_rc_get_style_by_paths: * @settings: a #GtkSettings object - * @widget_path: the widget path to use when looking up the style, or %NULL + * @widget_path: (allow-none): the widget path to use when looking up the style, or %NULL * if no matching against the widget path should be done - * @class_path: the class path to use when looking up the style, or %NULL + * @class_path: (allow-none): the class path to use when looking up the style, or %NULL * if no matching against the class path should be done. * @type: a type that will be used along with parent types of this type * when matching against class styles, or #G_TYPE_NONE - * + * * Creates up a #GtkStyle from styles defined in a RC file by providing * the raw components used in matching. This function may be useful * when creating pseudo-widgets that should be themed like widgets but diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c index 5975353b2f..a69b1c21fb 100644 --- a/gtk/gtkrecentchooser.c +++ b/gtk/gtkrecentchooser.c @@ -898,7 +898,8 @@ gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser) * The return value of this function is affected by the "sort-type" and * "limit" properties of @chooser. * - * Return value: A newly allocated list of #GtkRecentInfo objects. You should + * Return value: (element-type GtkRecentInfo) (transfer full): A newly allocated + * list of #GtkRecentInfo objects. You should * use gtk_recent_info_unref() on every item of the list, and then free * the list itself using g_list_free(). * @@ -1014,7 +1015,8 @@ gtk_recent_chooser_remove_filter (GtkRecentChooser *chooser, * * Gets the #GtkRecentFilter objects held by @chooser. * - * Return value: A singly linked list of #GtkRecentFilter objects. You + * Return value: (element-type GtkRecentFilter) (transfer container): A singly linked list + * of #GtkRecentFilter objects. You * should just free the returned list using g_slist_free(). * * Since: 2.10 diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c index 5cedaa0e54..3fd7d34fee 100644 --- a/gtk/gtkrecentmanager.c +++ b/gtk/gtkrecentmanager.c @@ -627,7 +627,7 @@ gtk_recent_manager_new (void) * in your application without caring about memory management. The * returned instance will be freed when you application terminates. * - * Return value: A unique #GtkRecentManager. Do not ref or unref it. + * Return value: (transfer none): A unique #GtkRecentManager. Do not ref or unref it. * * Since: 2.10 */ @@ -1273,7 +1273,8 @@ gtk_recent_manager_move_item (GtkRecentManager *recent_manager, * * Gets the list of recently used resources. * - * Return value: a list of newly allocated #GtkRecentInfo objects. Use + * Return value: (element-type GtkRecentInfo) (transfer full): a list of + * newly allocated #GtkRecentInfo objects. Use * gtk_recent_info_unref() on each item inside the list, and then * free the list itself using g_list_free(). * @@ -1723,9 +1724,9 @@ recent_app_info_free (RecentAppInfo *app_info) * gtk_recent_info_get_application_info: * @info: a #GtkRecentInfo * @app_name: the name of the application that has registered this item - * @app_exec: return location for the string containing the command line - * @count: return location for the number of times this item was registered - * @time_: return location for the timestamp this item was last registered + * @app_exec: (transfer none) (out): return location for the string containing the command line + * @count: (out): return location for the number of times this item was registered + * @time_: (out): return location for the timestamp this item was last registered * for this application * * Gets the data regarding the application that has registered the resource @@ -1779,15 +1780,15 @@ gtk_recent_info_get_application_info (GtkRecentInfo *info, /** * gtk_recent_info_get_applications: * @info: a #GtkRecentInfo - * @length: return location for the length of the returned list, or %NULL + * @length: (out) (allow-none): return location for the length of the returned list * * Retrieves the list of applications that have registered this resource. * - * Return value: a newly allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. + * Return value: (array length=length zero-terminated=1): a newly allocated + * %NULL-terminated array of strings. Use g_strfreev() to free it. * * Since: 2.10 - */ + */ gchar ** gtk_recent_info_get_applications (GtkRecentInfo *info, gsize *length) @@ -2274,14 +2275,14 @@ gtk_recent_info_get_age (GtkRecentInfo *info) /** * gtk_recent_info_get_groups: * @info: a #GtkRecentInfo - * @length: return location for the number of groups returned, or %NULL + * @length: (out) (allow-none): return location for the number of groups returned * * Returns all groups registered for the recently used item @info. The * array of returned group names will be %NULL terminated, so length might * optionally be %NULL. * - * Return value: a newly allocated %NULL terminated array of strings. Use - * g_strfreev() to free it. + * Return value: (array length=length zero-terminated=1): a newly allocated + * %NULL terminated array of strings. Use g_strfreev() to free it. * * Since: 2.10 */ diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c index e1ef6333bb..b4112ae5f7 100644 --- a/gtk/gtkscrolledwindow.c +++ b/gtk/gtkscrolledwindow.c @@ -377,12 +377,12 @@ gtk_scrolled_window_init (GtkScrolledWindow *scrolled_window) /** * gtk_scrolled_window_new: - * @hadjustment: horizontal adjustment - * @vadjustment: vertical adjustment - * - * Creates a new scrolled window. + * @hadjustment: (allow-none): horizontal adjustment + * @vadjustment: (allow-none): vertical adjustment * - * The two arguments are the scrolled window's adjustments; these will be + * Creates a new scrolled window. + * + * The two arguments are the scrolled window's adjustments; these will be * shared with the scrollbars and the child widget to keep the bars in sync * with the child. Usually you want to pass %NULL for the adjustments, which * will cause the scrolled window to create them for you. diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c index 541d5e5d95..1c350ee7da 100644 --- a/gtk/gtkselection.c +++ b/gtk/gtkselection.c @@ -635,8 +635,8 @@ gtk_target_table_free (GtkTargetEntry *targets, /** * gtk_selection_owner_set_for_display: - * @display: the #Gdkdisplay where the selection is set - * @widget: new selection owner (a #GdkWidget), or %NULL. + * @display: the #Gdkdisplay where the selection is set + * @widget: (allow-none): new selection owner (a #GdkWidget), or %NULL. * @selection: an interned atom representing the selection to claim. * @time_: timestamp with which to claim the selection * @@ -1756,10 +1756,11 @@ gtk_selection_data_set_uris (GtkSelectionData *selection_data, * @selection_data: a #GtkSelectionData * * Gets the contents of the selection data as array of URIs. - * - * Return value: if the selection data contains a list of + * + * Return value: (array zero-terminated=1) (element-type utf8) (transfer full): if + * the selection data contains a list of * URIs, a newly allocated %NULL-terminated string array - * containing the URIs, otherwise %NULL. If the result is + * containing the URIs, otherwise %NULL. If the result is * non-%NULL it must be freed with g_strfreev(). * * Since: 2.6 diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c index 9c744daef7..9e28fb9229 100644 --- a/gtk/gtksettings.c +++ b/gtk/gtksettings.c @@ -1063,8 +1063,8 @@ gtk_settings_get_for_screen (GdkScreen *screen) * * Gets the #GtkSettings object for the default GDK screen, creating * it if necessary. See gtk_settings_get_for_screen(). - * - * Return value: a #GtkSettings object. If there is no default + * + * Return value: (transfer none): a #GtkSettings object. If there is no default * screen, then returns %NULL. **/ GtkSettings* diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c index 6cd02c0e2e..645cdef358 100644 --- a/gtk/gtksizegroup.c +++ b/gtk/gtksizegroup.c @@ -585,8 +585,8 @@ gtk_size_group_remove_widget (GtkSizeGroup *size_group, * * Returns the list of widgets associated with @size_group. * - * Return value: a #GSList of widgets. The list is owned by GTK+ - * and should not be modified. + * Return value: (element-type GtkWidget) (transfer none): a #GSList of + * widgets. The list is owned by GTK+ and should not be modified. * * Since: 2.10 **/ diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c index a61ea841ec..ebae4c0fca 100644 --- a/gtk/gtkspinbutton.c +++ b/gtk/gtkspinbutton.c @@ -1596,6 +1596,16 @@ gtk_spin_button_default_output (GtkSpinButton *spin_button) ***********************************************************/ +/** + * gtk_spin_button_configure: + * @spin_button: a #GtkSpinButton + * @adjustment: (allow-none): a #GtkAdjustment. + * @climb_rate: the new climb rate. + * @digits: the number of decimal places to display in the spin button. + * + * Changes the properties of an existing spin button. The adjustment, climb rate, + * and number of decimal places are all changed accordingly, after this function call. + */ void gtk_spin_button_configure (GtkSpinButton *spin_button, GtkAdjustment *adjustment, diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c index f400bff73c..2492af8850 100644 --- a/gtk/gtkstatusicon.c +++ b/gtk/gtkstatusicon.c @@ -1875,9 +1875,9 @@ gtk_status_icon_set_image (GtkStatusIcon *status_icon, /** * gtk_status_icon_set_from_pixbuf: * @status_icon: a #GtkStatusIcon - * @pixbuf: a #GdkPixbuf or %NULL - * - * Makes @status_icon display @pixbuf. + * @pixbuf: (allow-none): a #GdkPixbuf or %NULL + * + * Makes @status_icon display @pixbuf. * See gtk_status_icon_new_from_pixbuf() for details. * * Since: 2.10 @@ -2212,7 +2212,7 @@ gtk_status_icon_get_screen (GtkStatusIcon *status_icon) /** * gtk_status_icon_set_tooltip: * @status_icon: a #GtkStatusIcon - * @tooltip_text: the tooltip text, or %NULL + * @tooltip_text: (allow-none): the tooltip text, or %NULL * * Sets the tooltip of the status icon. * @@ -2561,13 +2561,13 @@ gtk_status_icon_position_menu (GtkMenu *menu, /** * gtk_status_icon_get_geometry: * @status_icon: a #GtkStatusIcon - * @screen: return location for the screen, or %NULL if the - * information is not needed - * @area: return location for the area occupied by the status + * @screen: (out) (transfer none) (allow-none): return location for the screen, or %NULL if the + * information is not needed + * @area: (out) (allow-none): return location for the area occupied by the status * icon, or %NULL - * @orientation: return location for the orientation of the panel - * in which the status icon is embedded, or %NULL. A panel - * at the top or bottom of the screen is horizontal, a panel + * @orientation: (out) (allow-none): return location for the orientation of the panel + * in which the status icon is embedded, or %NULL. A panel + * at the top or bottom of the screen is horizontal, a panel * at the left or right is vertical. * * Obtains information about the location of the status icon diff --git a/gtk/gtkstock.c b/gtk/gtkstock.c index dfff951ba8..2ba74ae2cc 100644 --- a/gtk/gtkstock.c +++ b/gtk/gtkstock.c @@ -215,8 +215,8 @@ gtk_stock_lookup (const gchar *stock_id, * Retrieves a list of all known stock IDs added to a #GtkIconFactory * or registered with gtk_stock_add(). The list must be freed with g_slist_free(), * and each string in the list must be freed with g_free(). - * - * Return value: a list of known stock IDs + * + * Return value: (element-type utf8) (transfer full): a list of known stock IDs **/ GSList* gtk_stock_list_ids (void) diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c index c806aeee44..70b05c1c23 100644 --- a/gtk/gtkstyle.c +++ b/gtk/gtkstyle.c @@ -2169,12 +2169,12 @@ gtk_style_real_set_background (GtkStyle *style, * @state: a state * @size: the size to render the icon at. A size of (GtkIconSize)-1 * means render at the size of the source and don't scale. - * @widget: the widget - * @detail: a style detail + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @returns: a newly-created #GdkPixbuf containing the rendered icon * - * Renders the icon specified by @source at the given @size - * according to the given parameters and returns the result in a + * Renders the icon specified by @source at the given @size + * according to the given parameters and returns the result in a * pixbuf. */ GdkPixbuf * @@ -2200,6 +2200,19 @@ gtk_style_render_icon (GtkStyle *style, } /* Default functions */ + +/** + * gtk_style_apply_default_background: + * @style: + * @window: + * @set_bg: + * @state_type: + * @area: (allow-none): + * @x: + * @y: + * @width: + * @height: + */ void gtk_style_apply_default_background (GtkStyle *style, GdkWindow *window, @@ -5878,14 +5891,14 @@ hls_to_rgb (gdouble *h, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: rectangle to which the output is clipped, or %NULL if the + * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x1: the starting x coordinate * @x2: the ending x coordinate * @y: the y coordinate - * + * * Draws a horizontal line from (@x1, @y) to (@x2, @y) in @window * using the given style and state. **/ @@ -5914,14 +5927,14 @@ gtk_paint_hline (GtkStyle *style, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: rectangle to which the output is clipped, or %NULL if the + * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @y1_: the starting y coordinate * @y2_: the ending y coordinate * @x: the x coordinate - * + * * Draws a vertical line from (@x, @y1_) to (@x, @y2_) in @window * using the given style and state. */ @@ -5951,14 +5964,14 @@ gtk_paint_vline (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle or %NULL if the + * @area: (allow-none): clip rectangle or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle * @y: y origin of the rectangle - * @width: width of the rectangle - * @height: width of the rectangle + * @width: width of the rectangle + * @height: width of the rectangle * * Draws a shadow around the given rectangle in @window * using the given style and state and shadow type. @@ -5991,14 +6004,14 @@ gtk_paint_shadow (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @points: an array of #GdkPoints * @n_points: length of @points * @fill: %TRUE if the polygon should be filled - * + * * Draws a polygon on @window with the given parameters. */ void @@ -6028,10 +6041,10 @@ gtk_paint_polygon (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @arrow_type: the type of arrow to draw * @fill: %TRUE if the arrow tip should be filled * @x: x origin of the rectangle to draw the arrow in @@ -6072,10 +6085,10 @@ gtk_paint_arrow (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle to draw the diamond in * @y: y origin of the rectangle to draw the diamond in * @width: width of the rectangle to draw the diamond in @@ -6111,14 +6124,14 @@ gtk_paint_diamond (GtkStyle *style, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin * @y: y origin * @string: the string to draw - * + * * Draws a text string on @window with the given parameters. * * Deprecated: 2.0: Use gtk_paint_layout() instead. @@ -6149,10 +6162,10 @@ gtk_paint_string (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the box * @y: y origin of the box * @width: the width of the box @@ -6188,10 +6201,10 @@ gtk_paint_box (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the box * @y: y origin of the box * @width: the width of the box @@ -6227,10 +6240,10 @@ gtk_paint_flat_box (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle to draw the check in * @y: y origin of the rectangle to draw the check in * @width: the width of the rectangle to draw the check in @@ -6267,10 +6280,10 @@ gtk_paint_check (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle to draw the option in * @y: y origin of the rectangle to draw the option in * @width: the width of the rectangle to draw the option in @@ -6307,10 +6320,10 @@ gtk_paint_option (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: the type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle to draw the tab in * @y: y origin of the rectangle to draw the tab in * @width: the width of the rectangle to draw the tab in @@ -6347,14 +6360,14 @@ gtk_paint_tab (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle * @y: y origin of the rectangle - * @width: width of the rectangle - * @height: width of the rectangle + * @width: width of the rectangle + * @height: width of the rectangle * @gap_side: side in which to leave the gap * @gap_x: starting position of the gap * @gap_width: width of the gap @@ -6395,14 +6408,14 @@ gtk_paint_shadow_gap (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the rectangle * @y: y origin of the rectangle - * @width: width of the rectangle - * @height: width of the rectangle + * @width: width of the rectangle + * @height: width of the rectangle * @gap_side: side in which to leave the gap * @gap_x: starting position of the gap * @gap_width: width of the gap @@ -6441,14 +6454,14 @@ gtk_paint_box_gap (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the extension * @y: y origin of the extension - * @width: width of the extension - * @height: width of the extension + * @width: width of the extension + * @height: width of the extension * @gap_side: the side on to which the extension is attached * * Draws an extension, i.e. a notebook tab. @@ -6481,10 +6494,10 @@ gtk_paint_extension (GtkStyle *style, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: the x origin of the rectangle around which to draw a focus indicator * @y: the y origin of the rectangle around which to draw a focus indicator * @width: the width of the rectangle around which to draw a focus indicator @@ -6520,10 +6533,10 @@ gtk_paint_focus (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: a shadow - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: the x origin of the rectangle in which to draw a slider * @y: the y origin of the rectangle in which to draw a slider * @width: the width of the rectangle in which to draw a slider @@ -6562,10 +6575,10 @@ gtk_paint_slider (GtkStyle *style, * @window: a #GdkWindow * @state_type: a state * @shadow_type: type of shadow to draw - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin of the handle * @y: y origin of the handle * @width: with of the handle @@ -6602,10 +6615,10 @@ gtk_paint_handle (GtkStyle *style, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: the x position to draw the expander at * @y: the y position to draw the expander at * @expander_style: the style to draw the expander in; determines @@ -6649,14 +6662,14 @@ gtk_paint_expander (GtkStyle *style, * @state_type: a state * @use_text: whether to use the text or foreground * graphics context of @style - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @x: x origin * @y: y origin * @layout: the layout to draw - * + * * Draws a layout on @window using the given parameters. **/ void @@ -6685,10 +6698,10 @@ gtk_paint_layout (GtkStyle *style, * @style: a #GtkStyle * @window: a #GdkWindow * @state_type: a state - * @area: clip rectangle, or %NULL if the + * @area: (allow-none): clip rectangle, or %NULL if the * output should not be clipped - * @widget: the widget (may be %NULL) - * @detail: a style detail (may be %NULL) + * @widget: (allow-none): the widget + * @detail: (allow-none): a style detail * @edge: the edge in which to draw the resize grip * @x: the x origin of the rectangle in which to draw the resize grip * @y: the y origin of the rectangle in which to draw the resize grip @@ -7136,8 +7149,8 @@ draw_insertion_cursor (GtkWidget *widget, /** * gtk_draw_insertion_cursor: * @widget: a #GtkWidget - * @drawable: a #GdkDrawable - * @area: rectangle to which the output is clipped, or %NULL if the + * @drawable: a #GdkDrawable + * @area: (allow-none): rectangle to which the output is clipped, or %NULL if the * output should not be clipped * @location: location where to draw the cursor (@location->width is ignored) * @is_primary: if the cursor should be the primary cursor color. diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c index f82b6d875b..e223d92527 100644 --- a/gtk/gtktextbuffer.c +++ b/gtk/gtktextbuffer.c @@ -805,7 +805,7 @@ _gtk_text_buffer_get_btree (GtkTextBuffer *buffer) * * Get the #GtkTextTagTable associated with this buffer. * - * Return value: the buffer's tag table + * Return value: (transfer none): the buffer's tag table **/ GtkTextTagTable* gtk_text_buffer_get_tag_table (GtkTextBuffer *buffer) @@ -2061,7 +2061,7 @@ gtk_text_buffer_set_mark (GtkTextBuffer *buffer, /** * gtk_text_buffer_create_mark: * @buffer: a #GtkTextBuffer - * @mark_name: name for mark, or %NULL + * @mark_name: (allow-none): name for mark, or %NULL * @where: location to place mark * @left_gravity: whether the mark has left gravity * @@ -2224,7 +2224,7 @@ gtk_text_buffer_delete_mark (GtkTextBuffer *buffer, * Returns the mark named @name in buffer @buffer, or %NULL if no such * mark exists in the buffer. * - * Return value: a #GtkTextMark, or %NULL + * Return value: (transfer none): a #GtkTextMark, or %NULL **/ GtkTextMark* gtk_text_buffer_get_mark (GtkTextBuffer *buffer, @@ -2307,7 +2307,7 @@ gtk_text_buffer_delete_mark_by_name (GtkTextBuffer *buffer, * named "insert", but very slightly more efficient, and involves less * typing. * - * Return value: insertion point mark + * Return value: (transfer none): insertion point mark **/ GtkTextMark* gtk_text_buffer_get_insert (GtkTextBuffer *buffer) @@ -2333,7 +2333,7 @@ gtk_text_buffer_get_insert (GtkTextBuffer *buffer) * for handling the selection, if you just want to know whether there's a * selection and what its bounds are. * - * Return value: selection bound mark + * Return value: (transfer none): selection bound mark **/ GtkTextMark* gtk_text_buffer_get_selection_bound (GtkTextBuffer *buffer) @@ -3732,11 +3732,11 @@ remove_all_selection_clipboards (GtkTextBuffer *buffer) * gtk_text_buffer_paste_clipboard: * @buffer: a #GtkTextBuffer * @clipboard: the #GtkClipboard to paste from - * @override_location: location to insert pasted text, or %NULL for + * @override_location: (allow-none): location to insert pasted text, or %NULL for * at the cursor * @default_editable: whether the buffer is editable by default * - * Pastes the contents of a clipboard at the insertion point, or at + * Pastes the contents of a clipboard at the insertion point, or at * @override_location. (Note: pasting is asynchronous, that is, we'll * ask for the paste data and return, and at some point later after * the main loop runs, the paste data will be inserted.) diff --git a/gtk/gtktextbufferrichtext.c b/gtk/gtktextbufferrichtext.c index 22de4db05b..16501f7681 100644 --- a/gtk/gtktextbufferrichtext.c +++ b/gtk/gtktextbufferrichtext.c @@ -104,7 +104,7 @@ gtk_text_buffer_register_serialize_format (GtkTextBuffer *buffer, /** * gtk_text_buffer_register_serialize_tagset: * @buffer: a #GtkTextBuffer - * @tagset_name: an optional tagset name, on %NULL + * @tagset_name: (allow-none): an optional tagset name, on %NULL * * This function registers GTK+'s internal rich text serialization * format with the passed @buffer. The internal format does not comply @@ -202,7 +202,7 @@ gtk_text_buffer_register_deserialize_format (GtkTextBuffer *buffe /** * gtk_text_buffer_register_deserialize_tagset: * @buffer: a #GtkTextBuffer - * @tagset_name: an optional tagset name, on %NULL + * @tagset_name: (allow-none): an optional tagset name, on %NULL * * This function registers GTK+'s internal rich text serialization * format with the passed @buffer. See diff --git a/gtk/gtktextchild.c b/gtk/gtktextchild.c index 163954f6e4..aaf171576d 100644 --- a/gtk/gtktextchild.c +++ b/gtk/gtktextchild.c @@ -384,9 +384,9 @@ gtk_text_child_anchor_finalize (GObject *obj) * * Gets a list of all widgets anchored at this child anchor. * The returned list should be freed with g_list_free(). - * - * - * Return value: list of widgets anchored at @anchor + * + * + * Return value: (element-type GtkWidget) (transfer container): list of widgets anchored at @anchor **/ GList* gtk_text_child_anchor_get_widgets (GtkTextChildAnchor *anchor) diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c index 37d4c2d4d2..360c855a3e 100644 --- a/gtk/gtktextiter.c +++ b/gtk/gtktextiter.c @@ -371,7 +371,7 @@ check_invariants (const GtkTextIter *iter) * * Returns the #GtkTextBuffer this iterator is associated with. * - * Return value: the buffer + * Return value: (transfer none): the buffer **/ GtkTextBuffer* gtk_text_iter_get_buffer (const GtkTextIter *iter) @@ -972,7 +972,7 @@ gtk_text_iter_get_visible_text (const GtkTextIter *start, * (with no new reference count added). Otherwise, * %NULL is returned. * - * Return value: the pixbuf at @iter + * Return value: (transfer none): the pixbuf at @iter **/ GdkPixbuf* gtk_text_iter_get_pixbuf (const GtkTextIter *iter) @@ -1034,7 +1034,7 @@ gtk_text_iter_get_child_anchor (const GtkTextIter *iter) * can exist in the same place. The returned list is not in any * meaningful order. * - * Return value: list of #GtkTextMark + * Return value: (element-type GtkTextMark) (transfer container): list of #GtkTextMark **/ GSList* gtk_text_iter_get_marks (const GtkTextIter *iter) @@ -1080,7 +1080,7 @@ gtk_text_iter_get_marks (const GtkTextIter *iter) * a tag is toggled off, then some non-empty range following @iter * does not have the tag applied to it. * - * Return value: tags toggled at this point + * Return value: (element-type GtkTextTag) (transfer container): tags toggled at this point **/ GSList* gtk_text_iter_get_toggled_tags (const GtkTextIter *iter, @@ -1129,7 +1129,7 @@ gtk_text_iter_get_toggled_tags (const GtkTextIter *iter, /** * gtk_text_iter_begins_tag: * @iter: an iterator - * @tag: a #GtkTextTag, or %NULL + * @tag: (allow-none): a #GtkTextTag, or %NULL * * Returns %TRUE if @tag is toggled on at exactly this point. If @tag * is %NULL, returns %TRUE if any tag is toggled on at this point. Note @@ -1222,7 +1222,7 @@ gtk_text_iter_ends_tag (const GtkTextIter *iter, /** * gtk_text_iter_toggles_tag: * @iter: an iterator - * @tag: a #GtkTextTag, or %NULL + * @tag: (allow-none): a #GtkTextTag, or %NULL * * This is equivalent to (gtk_text_iter_begins_tag () || * gtk_text_iter_ends_tag ()), i.e. it tells you whether a range with @@ -1307,8 +1307,8 @@ gtk_text_iter_has_tag (const GtkTextIter *iter, * priority (highest-priority tags are last). The #GtkTextTag in the * list don't have a reference added, but you have to free the list * itself. - * - * Return value: list of #GtkTextTag + * + * Return value: (element-type GtkTextTag) (transfer container): list of #GtkTextTag **/ GSList* gtk_text_iter_get_tags (const GtkTextIter *iter) @@ -4111,7 +4111,7 @@ gtk_text_iter_forward_to_line_end (GtkTextIter *iter) /** * gtk_text_iter_forward_to_tag_toggle: * @iter: a #GtkTextIter - * @tag: a #GtkTextTag, or %NULL + * @tag: (allow-none): a #GtkTextTag, or %NULL * * Moves forward to the next toggle (on or off) of the * #GtkTextTag @tag, or to the next toggle of any tag if @@ -4193,7 +4193,7 @@ gtk_text_iter_forward_to_tag_toggle (GtkTextIter *iter, /** * gtk_text_iter_backward_to_tag_toggle: * @iter: a #GtkTextIter - * @tag: a #GtkTextTag, or %NULL + * @tag: (allow-none): a #GtkTextTag, or %NULL * * Moves backward to the next toggle (on or off) of the * #GtkTextTag @tag, or to the next toggle of any tag if @@ -4571,12 +4571,12 @@ strbreakup (const char *string, * @iter: start of search * @str: a search string * @flags: flags affecting how the search is done - * @match_start: return location for start of match, or %NULL - * @match_end: return location for end of match, or %NULL - * @limit: bound for the search, or %NULL for the end of the buffer - * - * Searches forward for @str. Any match is returned by setting - * @match_start to the first character of the match and @match_end to the + * @match_start: (allow-none): return location for start of match, or %NULL + * @match_end: (allow-none): return location for end of match, or %NULL + * @limit: (allow-none): bound for the search, or %NULL for the end of the buffer + * + * Searches forward for @str. Any match is returned by setting + * @match_start to the first character of the match and @match_end to the * first character after the match. The search will not continue past * @limit. Note that a search is a linear or O(n) operation, so you * may wish to use @limit to avoid locking up your UI on large @@ -4868,12 +4868,12 @@ lines_window_free (LinesWindow *win) * @iter: a #GtkTextIter where the search begins * @str: search string * @flags: bitmask of flags affecting the search - * @match_start: return location for start of match, or %NULL - * @match_end: return location for end of match, or %NULL - * @limit: location of last possible @match_start, or %NULL for start of buffer - * + * @match_start: (allow-none): return location for start of match, or %NULL + * @match_end: (allow-none): return location for end of match, or %NULL + * @limit: (allow-none): location of last possible @match_start, or %NULL for start of buffer + * * Same as gtk_text_iter_forward_search(), but moves backward. - * + * * Return value: whether a match was found **/ gboolean diff --git a/gtk/gtktextlayout.c b/gtk/gtktextlayout.c index 8c5d419b63..c4c7143984 100644 --- a/gtk/gtktextlayout.c +++ b/gtk/gtktextlayout.c @@ -299,6 +299,10 @@ gtk_text_layout_finalize (GObject *object) G_OBJECT_CLASS (gtk_text_layout_parent_class)->finalize (object); } +/** + * gtk_text_layout_set_buffer: + * @buffer: (allow-none): + */ void gtk_text_layout_set_buffer (GtkTextLayout *layout, GtkTextBuffer *buffer) @@ -703,6 +707,12 @@ gtk_text_layout_wrap (GtkTextLayout *layout, return GTK_TEXT_LAYOUT_GET_CLASS (layout)->wrap (layout, line, line_data); } + +/** + * gtk_text_layout_get_lines: + * + * Return value: (element-type GtkTextLine) (transfer container): + */ GSList* gtk_text_layout_get_lines (GtkTextLayout *layout, /* [top_y, bottom_y) */ diff --git a/gtk/gtktextmark.c b/gtk/gtktextmark.c index 359e310d24..5964108a57 100644 --- a/gtk/gtktextmark.c +++ b/gtk/gtktextmark.c @@ -283,8 +283,8 @@ gtk_text_mark_get_deleted (GtkTextMark *mark) * * Gets the buffer this mark is located inside, * or %NULL if the mark is deleted. - * - * Return value: the mark's #GtkTextBuffer + * + * Return value: (transfer none): the mark's #GtkTextBuffer **/ GtkTextBuffer* gtk_text_mark_get_buffer (GtkTextMark *mark) diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c index bbbdf6b806..cf698fff73 100644 --- a/gtk/gtktextview.c +++ b/gtk/gtktextview.c @@ -1363,7 +1363,7 @@ gtk_text_view_new_with_buffer (GtkTextBuffer *buffer) /** * gtk_text_view_set_buffer: * @text_view: a #GtkTextView - * @buffer: a #GtkTextBuffer + * @buffer: (allow-none): a #GtkTextBuffer * * Sets @buffer as the buffer being displayed by @text_view. The previous * buffer displayed by the text view is unreferenced, and a reference is @@ -1504,7 +1504,7 @@ get_buffer (GtkTextView *text_view) * The reference count on the buffer is not incremented; the caller * of this function won't own a new reference. * - * Return value: a #GtkTextBuffer + * Return value: (transfer none): a #GtkTextBuffer **/ GtkTextBuffer* gtk_text_view_get_buffer (GtkTextView *text_view) @@ -8199,7 +8199,7 @@ text_window_get_height (GtkTextWindow *win) * height is 0, and are nonexistent before the widget has been * realized. * - * Return value: a #GdkWindow, or %NULL + * Return value: (transfer none): a #GdkWindow, or %NULL **/ GdkWindow* gtk_text_view_get_window (GtkTextView *text_view, diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c index 70126ca2ab..b83790ccac 100644 --- a/gtk/gtktoolbar.c +++ b/gtk/gtktoolbar.c @@ -2253,11 +2253,11 @@ logical_to_physical (GtkToolbar *toolbar, /** * gtk_toolbar_set_drop_highlight_item: * @toolbar: a #GtkToolbar - * @tool_item: a #GtkToolItem, or %NULL to turn of highlighting + * @tool_item: (allow-none): a #GtkToolItem, or %NULL to turn of highlighting * @index_: a position on @toolbar - * + * * Highlights @toolbar to give an idea of what it would look like - * if @item was added to @toolbar at the position indicated by @index_. + * if @item was added to @toolbar at the position indicated by @index_. * If @item is %NULL, highlighting is turned off. In that case @index_ * is ignored. * @@ -3518,9 +3518,9 @@ gtk_toolbar_remove_space (GtkToolbar *toolbar, /** * gtk_toolbar_append_widget: * @toolbar: a #GtkToolbar. - * @widget: a #GtkWidget to add to the toolbar. - * @tooltip_text: the element's tooltip. - * @tooltip_private_text: used for context-sensitive help about this toolbar element. + * @widget: a #GtkWidget to add to the toolbar. + * @tooltip_text: (allow-none): the element's tooltip. + * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element. * * Adds a widget to the end of the given toolbar. * @@ -3542,9 +3542,9 @@ gtk_toolbar_append_widget (GtkToolbar *toolbar, /** * gtk_toolbar_prepend_widget: * @toolbar: a #GtkToolbar. - * @widget: a #GtkWidget to add to the toolbar. - * @tooltip_text: the element's tooltip. - * @tooltip_private_text: used for context-sensitive help about this toolbar element. + * @widget: a #GtkWidget to add to the toolbar. + * @tooltip_text: (allow-none): the element's tooltip. + * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element. * * Adds a widget to the beginning of the given toolbar. * @@ -3566,11 +3566,11 @@ gtk_toolbar_prepend_widget (GtkToolbar *toolbar, /** * gtk_toolbar_insert_widget: * @toolbar: a #GtkToolbar. - * @widget: a #GtkWidget to add to the toolbar. - * @tooltip_text: the element's tooltip. - * @tooltip_private_text: used for context-sensitive help about this toolbar element. + * @widget: a #GtkWidget to add to the toolbar. + * @tooltip_text: (allow-none): the element's tooltip. + * @tooltip_private_text: (allow-none): used for context-sensitive help about this toolbar element. * @position: the number of widgets to insert this widget after. - * + * * Inserts a widget in the toolbar at the given position. * * Deprecated: 2.4: Use gtk_toolbar_insert() instead. diff --git a/gtk/gtktoolbutton.c b/gtk/gtktoolbutton.c index 38055e06cf..5fdcc548f0 100644 --- a/gtk/gtktoolbutton.c +++ b/gtk/gtktoolbutton.c @@ -921,12 +921,12 @@ gtk_tool_button_new_from_stock (const gchar *stock_id) /** * gtk_tool_button_new: - * @label: a string that will be used as label, or %NULL - * @icon_widget: a widget that will be used as icon widget, or %NULL - * + * @label: (allow-none): a string that will be used as label, or %NULL + * @icon_widget: (allow-none): a widget that will be used as icon widget, or %NULL + * * Creates a new %GtkToolButton using @icon_widget as icon and @label as * label. - * + * * Return value: A new #GtkToolButton * * Since: 2.4 @@ -948,8 +948,8 @@ gtk_tool_button_new (GtkWidget *icon_widget, /** * gtk_tool_button_set_label: * @button: a #GtkToolButton - * @label: a string that will be used as label, or %NULL. - * + * @label: (allow-none): a string that will be used as label, or %NULL. + * * Sets @label as the label used for the tool button. The "label" property * only has an effect if not overridden by a non-%NULL "label_widget" property. * If both the "label_widget" and "label" properties are %NULL, the label @@ -1062,8 +1062,8 @@ gtk_tool_button_get_use_underline (GtkToolButton *button) /** * gtk_tool_button_set_stock_id: * @button: a #GtkToolButton - * @stock_id: a name of a stock item, or %NULL - * + * @stock_id: (allow-none): a name of a stock item, or %NULL + * * Sets the name of the stock item. See gtk_tool_button_new_from_stock(). * The stock_id property only has an effect if not * overridden by non-%NULL "label" and "icon_widget" properties. @@ -1110,8 +1110,8 @@ gtk_tool_button_get_stock_id (GtkToolButton *button) /** * gtk_tool_button_set_icon_name * @button: a #GtkToolButton - * @icon_name: the name of the themed icon - * + * @icon_name: (allow-none): the name of the themed icon + * * Sets the icon for the tool button from a named themed icon. * See the docs for #GtkIconTheme for more details. * The "icon_name" property only has an effect if not @@ -1161,8 +1161,8 @@ gtk_tool_button_get_icon_name (GtkToolButton *button) /** * gtk_tool_button_set_icon_widget: * @button: a #GtkToolButton - * @icon_widget: the widget used as icon, or %NULL - * + * @icon_widget: (allow-none): the widget used as icon, or %NULL + * * Sets @icon as the widget used as icon on @button. If @icon_widget is * %NULL the icon is determined by the "stock_id" property. If the * "stock_id" property is also %NULL, @button will not have an icon. @@ -1200,8 +1200,8 @@ gtk_tool_button_set_icon_widget (GtkToolButton *button, /** * gtk_tool_button_set_label_widget: * @button: a #GtkToolButton - * @label_widget: the widget used as label, or %NULL - * + * @label_widget: (allow-none): the widget used as label, or %NULL + * * Sets @label_widget as the widget that will be used as the label * for @button. If @label_widget is %NULL the "label" property is used * as label. If "label" is also %NULL, the label in the stock item diff --git a/gtk/gtktoolitem.c b/gtk/gtktoolitem.c index 5ad31cce4b..1cae42908f 100644 --- a/gtk/gtktoolitem.c +++ b/gtk/gtktoolitem.c @@ -1094,10 +1094,10 @@ gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item, /** * gtk_tool_item_set_tooltip: - * @tool_item: a #GtkToolItem + * @tool_item: a #GtkToolItem * @tooltips: The #GtkTooltips object to be used - * @tip_text: text to be used as tooltip text for @tool_item - * @tip_private: text to be used as private tooltip text + * @tip_text: (allow-none): text to be used as tooltip text for @tool_item + * @tip_private: (allow-none): text to be used as private tooltip text * * Sets the #GtkTooltips object to be used for @tool_item, the * text to be displayed as tooltip on the item and the private text @@ -1332,10 +1332,10 @@ gtk_tool_item_get_visible_vertical (GtkToolItem *toolitem) * Returns the #GtkMenuItem that was last set by * gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem * that is going to appear in the overflow menu. - * - * Return value: The #GtkMenuItem that is going to appear in the + * + * Return value: (transfer none): The #GtkMenuItem that is going to appear in the * overflow menu for @tool_item. - * + * * Since: 2.4 **/ GtkWidget * diff --git a/gtk/gtktooltips.c b/gtk/gtktooltips.c index a414346b9f..6c9131073d 100644 --- a/gtk/gtktooltips.c +++ b/gtk/gtktooltips.c @@ -210,6 +210,17 @@ gtk_tooltips_data_get (GtkWidget *widget) return g_object_get_data (G_OBJECT (widget), tooltips_data_key); } + +/** + * gtk_tooltips_set_tip: + * @tooltips: a #GtkTooltips. + * @widget: the #GtkWidget you wish to associate the tip with. + * @tip_text: (allow-none): a string containing the tip itself. + * @tip_private: (allow-none): a string of any further information that may be useful if the user gets stuck. + * + * Adds a tooltip containing the message @tip_text to the specified #GtkWidget. + * Deprecated: 2.12: + */ void gtk_tooltips_set_tip (GtkTooltips *tooltips, GtkWidget *widget, diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index c8cc7b2dad..0d0a4920e4 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -1173,10 +1173,10 @@ gtk_tree_model_iter_next (GtkTreeModel *tree_model, * gtk_tree_model_iter_children: * @tree_model: A #GtkTreeModel. * @iter: The new #GtkTreeIter to be set to the child. - * @parent: The #GtkTreeIter, or %NULL + * @parent: (allow-none): The #GtkTreeIter, or %NULL * - * Sets @iter to point to the first child of @parent. If @parent has no - * children, %FALSE is returned and @iter is set to be invalid. @parent + * Sets @iter to point to the first child of @parent. If @parent has no + * children, %FALSE is returned and @iter is set to be invalid. @parent * will remain a valid node after this function has been called. * * If @parent is %NULL returns the first node, equivalent to @@ -1229,7 +1229,7 @@ gtk_tree_model_iter_has_child (GtkTreeModel *tree_model, /** * gtk_tree_model_iter_n_children: * @tree_model: A #GtkTreeModel. - * @iter: The #GtkTreeIter, or %NULL. + * @iter: (allow-none): The #GtkTreeIter, or %NULL. * * Returns the number of children that @iter has. As a special case, if @iter * is %NULL, then the number of toplevel nodes is returned. @@ -1254,7 +1254,7 @@ gtk_tree_model_iter_n_children (GtkTreeModel *tree_model, * gtk_tree_model_iter_nth_child: * @tree_model: A #GtkTreeModel. * @iter: The #GtkTreeIter to set to the nth child. - * @parent: The #GtkTreeIter to get the child from, or %NULL. + * @parent: (allow-none): The #GtkTreeIter to get the child from, or %NULL. * @n: Then index of the desired child. * * Sets @iter to be the child of @parent, using the given index. The first diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c index a3398e602d..a161f47943 100644 --- a/gtk/gtktreemodelfilter.c +++ b/gtk/gtktreemodelfilter.c @@ -2956,7 +2956,7 @@ gtk_tree_model_filter_set_root (GtkTreeModelFilter *filter, /** * gtk_tree_model_filter_new: * @child_model: A #GtkTreeModel. - * @root: A #GtkTreePath or %NULL. + * @root: (allow-none): A #GtkTreePath or %NULL. * * Creates a new #GtkTreeModel, with @child_model as the child_model * and @root as the virtual root. diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c index 462f2da7a5..9513f2b788 100644 --- a/gtk/gtktreeselection.c +++ b/gtk/gtktreeselection.c @@ -327,8 +327,8 @@ gtk_tree_selection_get_tree_view (GtkTreeSelection *selection) /** * gtk_tree_selection_get_selected: * @selection: A #GtkTreeSelection. - * @model: A pointer to set to the #GtkTreeModel, or NULL. - * @iter: The #GtkTreeIter, or NULL. + * @model: (out) (allow-none): A pointer to set to the #GtkTreeModel, or NULL. + * @iter: (allow-none): The #GtkTreeIter, or NULL. * * Sets @iter to the currently selected node if @selection is set to * #GTK_SELECTION_SINGLE or #GTK_SELECTION_BROWSE. @iter may be NULL if you @@ -402,7 +402,7 @@ gtk_tree_selection_get_selected (GtkTreeSelection *selection, /** * gtk_tree_selection_get_selected_rows: * @selection: A #GtkTreeSelection. - * @model: A pointer to set to the #GtkTreeModel, or NULL. + * @model: (allow-none): A pointer to set to the #GtkTreeModel, or NULL. * * Creates a list of path of all selected rows. Additionally, if you are * planning on modifying the model after calling this function, you may @@ -415,7 +415,7 @@ gtk_tree_selection_get_selected (GtkTreeSelection *selection, * g_list_free (list); * ]| * - * Return value: A #GList containing a #GtkTreePath for each selected row. + * Return value: (element-type GtkTreePath) (transfer full): A #GList containing a #GtkTreePath for each selected row. * * Since: 2.2 **/ diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c index 81c373e9be..b7fcda89f7 100644 --- a/gtk/gtktreestore.c +++ b/gtk/gtktreestore.c @@ -2690,7 +2690,7 @@ free_paths_and_out: * gtk_tree_store_move_before: * @tree_store: A #GtkTreeStore. * @iter: A #GtkTreeIter. - * @position: A #GtkTreeIter or %NULL. + * @position: (allow-none): A #GtkTreeIter or %NULL. * * Moves @iter in @tree_store to the position before @position. @iter and * @position should be in the same level. Note that this function only @@ -2711,7 +2711,7 @@ gtk_tree_store_move_before (GtkTreeStore *tree_store, * gtk_tree_store_move_after: * @tree_store: A #GtkTreeStore. * @iter: A #GtkTreeIter. - * @position: A #GtkTreeIter. + * @position: (allow-none): A #GtkTreeIter. * * Moves @iter in @tree_store to the position after @position. @iter and * @position should be in the same level. Note that this function only diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c index 9d9b488cc0..7c2e00a441 100644 --- a/gtk/gtktreeview.c +++ b/gtk/gtktreeview.c @@ -10585,10 +10585,10 @@ gtk_tree_view_get_model (GtkTreeView *tree_view) /** * gtk_tree_view_set_model: * @tree_view: A #GtkTreeNode. - * @model: The model. + * @model: (allow-none): The model. * * Sets the model for a #GtkTreeView. If the @tree_view already has a model - * set, it will remove it before setting the new model. If @model is %NULL, + * set, it will remove it before setting the new model. If @model is %NULL, * then it will unset the old model. **/ void @@ -11322,7 +11322,7 @@ gtk_tree_view_get_column (GtkTreeView *tree_view, * Returns a #GList of all the #GtkTreeViewColumn s currently in @tree_view. * The returned list must be freed with g_list_free (). * - * Return value: A list of #GtkTreeViewColumn s + * Return value: (element-type GtkTreeViewColumn) (transfer container): A list of #GtkTreeViewColumn s **/ GList * gtk_tree_view_get_columns (GtkTreeView *tree_view) @@ -11336,7 +11336,7 @@ gtk_tree_view_get_columns (GtkTreeView *tree_view) * gtk_tree_view_move_column_after: * @tree_view: A #GtkTreeView * @column: The #GtkTreeViewColumn to be moved. - * @base_column: The #GtkTreeViewColumn to be moved relative to, or %NULL. + * @base_column: (allow-none): The #GtkTreeViewColumn to be moved relative to, or %NULL. * * Moves @column to be after to @base_column. If @base_column is %NULL, then * @column is placed in the first position. @@ -11519,8 +11519,8 @@ gtk_tree_view_scroll_to_point (GtkTreeView *tree_view, /** * gtk_tree_view_scroll_to_cell: * @tree_view: A #GtkTreeView. - * @path: The path of the row to move to, or %NULL. - * @column: The #GtkTreeViewColumn to move horizontally to, or %NULL. + * @path: (allow-none): The path of the row to move to, or %NULL. + * @column: (allow-none): The #GtkTreeViewColumn to move horizontally to, or %NULL. * @use_align: whether to use alignment arguments, or %FALSE. * @row_align: The vertical alignment of the row specified by @path. * @col_align: The horizontal alignment of the column specified by @column. @@ -12512,7 +12512,7 @@ gtk_tree_view_get_cursor (GtkTreeView *tree_view, * gtk_tree_view_set_cursor: * @tree_view: A #GtkTreeView * @path: A #GtkTreePath - * @focus_column: A #GtkTreeViewColumn, or %NULL + * @focus_column: (allow-none): A #GtkTreeViewColumn, or %NULL * @start_editing: %TRUE if the specified cell should start being edited. * * Sets the current keyboard focus to be at @path, and selects it. This is @@ -12541,8 +12541,8 @@ gtk_tree_view_set_cursor (GtkTreeView *tree_view, * gtk_tree_view_set_cursor_on_cell: * @tree_view: A #GtkTreeView * @path: A #GtkTreePath - * @focus_column: A #GtkTreeViewColumn, or %NULL - * @focus_cell: A #GtkCellRenderer, or %NULL + * @focus_column: (allow-none): A #GtkTreeViewColumn, or %NULL + * @focus_cell: (allow-none): A #GtkCellRenderer, or %NULL * @start_editing: %TRUE if the specified cell should start being edited. * * Sets the current keyboard focus to be at @path, and selects it. This is @@ -12764,8 +12764,8 @@ gtk_tree_view_get_path_at_pos (GtkTreeView *tree_view, /** * gtk_tree_view_get_cell_area: * @tree_view: a #GtkTreeView - * @path: a #GtkTreePath for the row, or %NULL to get only horizontal coordinates - * @column: a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates + * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates + * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordinates * @rect: rectangle to fill with cell rect * * Fills the bounding rectangle in bin_window coordinates for the cell at the @@ -13948,7 +13948,7 @@ gtk_tree_view_get_search_entry (GtkTreeView *tree_view) /** * gtk_tree_view_set_search_entry: * @tree_view: A #GtkTreeView - * @entry: the entry the interactive search code of @tree_view should use or %NULL + * @entry: (allow-none): the entry the interactive search code of @tree_view should use or %NULL * * Sets the entry which the interactive search code will use for this * @tree_view. This is useful when you want to provide a search entry diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c index edec5deffe..c132c9d790 100644 --- a/gtk/gtktreeviewcolumn.c +++ b/gtk/gtktreeviewcolumn.c @@ -2245,8 +2245,8 @@ gtk_tree_view_column_get_clickable (GtkTreeViewColumn *tree_column) /** * gtk_tree_view_column_set_widget: * @tree_column: A #GtkTreeViewColumn. - * @widget: A child #GtkWidget, or %NULL. - * + * @widget: (allow-none): A child #GtkWidget, or %NULL. + * * Sets the widget in the header to be @widget. If widget is %NULL, then the * header button is set with a #GtkLabel set to the title of @tree_column. **/ diff --git a/gtk/gtkuimanager.c b/gtk/gtkuimanager.c index 9ebaa92f41..6112bf799f 100644 --- a/gtk/gtkuimanager.c +++ b/gtk/gtkuimanager.c @@ -786,7 +786,8 @@ gtk_ui_manager_remove_action_group (GtkUIManager *self, * * Returns the list of action groups associated with @self. * - * Return value: a #GList of action groups. The list is owned by GTK+ + * Return value: (element-type GtkActionGroup) (transfer none): a #GList of + * action groups. The list is owned by GTK+ * and should not be modified. * * Since: 2.4 @@ -805,7 +806,7 @@ gtk_ui_manager_get_action_groups (GtkUIManager *self) * * Returns the #GtkAccelGroup associated with @self. * - * Return value: the #GtkAccelGroup. + * Return value: (transfer none): the #GtkAccelGroup. * * Since: 2.4 **/ @@ -835,8 +836,8 @@ gtk_ui_manager_get_accel_group (GtkUIManager *self) * the lifecycle of the ui manager. If you add the widgets returned by this * function to some container or explicitly ref them, they will survive the * destruction of the ui manager. - * - * Return value: the widget found by following the path, or %NULL if no widget + * + * Return value: (transfer none): the widget found by following the path, or %NULL if no widget * was found. * * Since: 2.4 @@ -891,9 +892,9 @@ collect_toplevels (GNode *node, * #GTK_UI_MANAGER_POPUP. * * Obtains a list of all toplevel widgets of the requested types. - * - * Return value: a newly-allocated #GSList of all toplevel widgets of the - * requested types. Free the returned list with g_slist_free(). + * + * Return value: (element-type GtkWidget) (transfer container): a newly-allocated #GSList of + * all toplevel widgets of the requested types. Free the returned list with g_slist_free(). * * Since: 2.4 **/ @@ -1736,11 +1737,11 @@ gtk_ui_manager_add_ui_from_file (GtkUIManager *self, * @merge_id: the merge id for the merged UI, see gtk_ui_manager_new_merge_id() * @path: a path * @name: the name for the added UI element - * @action: the name of the action to be proxied, or %NULL to add a separator + * @action: (allow-none): the name of the action to be proxied, or %NULL to add a separator * @type: the type of UI element to add. - * @top: if %TRUE, the UI element is added before its siblings, otherwise it + * @top: if %TRUE, the UI element is added before its siblings, otherwise it * is added after its siblings. - * + * * Adds a UI element to the current contents of @self. * * If @type is %GTK_UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c index 5fd9014ab4..4fd37b5666 100644 --- a/gtk/gtkviewport.c +++ b/gtk/gtkviewport.c @@ -466,8 +466,8 @@ viewport_set_adjustment (GtkViewport *viewport, /** * gtk_viewport_set_hadjustment: * @viewport: a #GtkViewport. - * @adjustment: a #GtkAdjustment. - * + * @adjustment: (allow-none): a #GtkAdjustment. + * * Sets the horizontal adjustment of the viewport. **/ void @@ -486,8 +486,8 @@ gtk_viewport_set_hadjustment (GtkViewport *viewport, /** * gtk_viewport_set_vadjustment: * @viewport: a #GtkViewport. - * @adjustment: a #GtkAdjustment. - * + * @adjustment: (allow-none): a #GtkAdjustment. + * * Sets the vertical adjustment of the viewport. **/ void diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 74392eb0b3..cf1d3610d9 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -3132,7 +3132,7 @@ gtk_widget_destroy (GtkWidget *widget) /** * gtk_widget_destroyed: * @widget: a #GtkWidget - * @widget_pointer: address of a variable that contains @widget + * @widget_pointer: (inout) (transfer none): address of a variable that contains @widget * * This function sets *@widget_pointer to %NULL if @widget_pointer != * %NULL. It's intended to be used as a callback connected to the @@ -4159,9 +4159,9 @@ gtk_widget_common_ancestor (GtkWidget *widget_a, * @dest_widget: a #GtkWidget * @src_x: X position relative to @src_widget * @src_y: Y position relative to @src_widget - * @dest_x: location to store X position relative to @dest_widget - * @dest_y: location to store Y position relative to @dest_widget - * + * @dest_x: (out): location to store X position relative to @dest_widget + * @dest_y: (out): location to store Y position relative to @dest_widget + * * Translate coordinates relative to @src_widget's allocation to coordinates * relative to @dest_widget's allocations. In order to perform this * operation, both widgets must be realized, and must share a common @@ -4543,9 +4543,9 @@ destroy_accel_path (gpointer data) /** * gtk_widget_set_accel_path: * @widget: a #GtkWidget - * @accel_path: path used to look up the accelerator - * @accel_group: a #GtkAccelGroup. - * + * @accel_path: (allow-none): path used to look up the accelerator + * @accel_group: (allow-none): a #GtkAccelGroup. + * * Given an accelerator group, @accel_group, and an accelerator path, * @accel_path, sets up an accelerator in @accel_group so whenever the * key binding that is defined for @accel_path is pressed, @widget @@ -4977,8 +4977,8 @@ gtk_widget_activate (GtkWidget *widget) /** * gtk_widget_set_scroll_adjustments: * @widget: a #GtkWidget - * @hadjustment: an adjustment for horizontal scrolling, or %NULL - * @vadjustment: an adjustment for vertical scrolling, or %NULL + * @hadjustment: (allow-none): an adjustment for horizontal scrolling, or %NULL + * @vadjustment: (allow-none): an adjustment for vertical scrolling, or %NULL * * For widgets that support scrolling, sets the scroll adjustments and * returns %TRUE. For widgets that don't support scrolling, does @@ -6275,7 +6275,7 @@ gtk_widget_set_parent (GtkWidget *widget, * * Returns the parent container of @widget. * - * Return value: the parent container of @widget, or %NULL + * Return value: (transfer none): the parent container of @widget, or %NULL **/ GtkWidget * gtk_widget_get_parent (GtkWidget *widget) @@ -6293,7 +6293,7 @@ gtk_widget_get_parent (GtkWidget *widget) /** * gtk_widget_set_style: * @widget: a #GtkWidget - * @style: a #GtkStyle, or %NULL to remove the effect of a previous + * @style: (allow-none): a #GtkStyle, or %NULL to remove the effect of a previous * gtk_widget_set_style() and go back to the default style * * Sets the #GtkStyle for a widget (@widget->style). You probably don't @@ -6372,8 +6372,8 @@ gtk_widget_reset_rc_style (GtkWidget *widget) * @widget: a #GtkWidget * * Simply an accessor function that returns @widget->style. - * - * Return value: the widget's #GtkStyle + * + * Return value: (transfer none): the widget's #GtkStyle **/ GtkStyle* gtk_widget_get_style (GtkWidget *widget) @@ -6442,8 +6442,8 @@ gtk_widget_modify_style (GtkWidget *widget, * the passed-in style and sets the copy as the new modifier style, * thus dropping any reference to the old modifier style. Add a reference * to the modifier style if you want to keep it alive. - * - * Return value: the modifier style for the widget. This rc style is + * + * Return value: (transfer none): the modifier style for the widget. This rc style is * owned by the widget. If you want to keep a pointer to value this * around, you must add a refcount using g_object_ref(). **/ @@ -6508,11 +6508,11 @@ gtk_widget_modify_color_component (GtkWidget *widget, * gtk_widget_modify_fg: * @widget: a #GtkWidget * @state: the state for which to set the foreground color - * @color: the color to assign (does not need to be allocated), + * @color: (allow-none): 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. + * + * Sets the foreground color for a widget in a particular state. * All other style values are left untouched. See also * gtk_widget_modify_style(). **/ @@ -6531,11 +6531,11 @@ gtk_widget_modify_fg (GtkWidget *widget, * gtk_widget_modify_bg: * @widget: a #GtkWidget * @state: the state for which to set the background color - * @color: the color to assign (does not need to be allocated), + * @color: (allow-none): 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. + * + * Sets the background color for a widget in a particular state. * All other style values are left untouched. See also * gtk_widget_modify_style(). * @@ -6562,10 +6562,10 @@ gtk_widget_modify_bg (GtkWidget *widget, * gtk_widget_modify_text: * @widget: a #GtkWidget * @state: the state for which to set the text color - * @color: the color to assign (does not need to be allocated), + * @color: (allow-none): 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(). - * + * * Sets the text color for a widget in a particular state. All other * style values are left untouched. The text color is the foreground * color used along with the base color (see gtk_widget_modify_base()) @@ -6587,10 +6587,10 @@ gtk_widget_modify_text (GtkWidget *widget, * gtk_widget_modify_base: * @widget: a #GtkWidget * @state: the state for which to set the base color - * @color: the color to assign (does not need to be allocated), + * @color: (allow-none): 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(). - * + * * Sets the base color for a widget in a particular state. * All other style values are left untouched. The base color * is the background color used along with the text color @@ -6683,9 +6683,9 @@ gtk_widget_modify_cursor (GtkWidget *widget, /** * gtk_widget_modify_font: * @widget: a #GtkWidget - * @font_desc: the font description to use, or %NULL to undo + * @font_desc: (allow-none): the font description to use, or %NULL to undo * the effect of previous calls to gtk_widget_modify_font(). - * + * * Sets the font to use for a widget. All other style values are left * untouched. See also gtk_widget_modify_style(). **/ @@ -6993,10 +6993,10 @@ gtk_widget_reset_rc_styles (GtkWidget *widget) * gtk_widget_get_default_style: * * Returns the default style used by all widgets initially. - * - * Returns: the default style. This #GtkStyle object is owned + * + * Returns: (transfer none): the default style. This #GtkStyle object is owned * by GTK+ and should not be modified or freed. - */ + */ GtkStyle* gtk_widget_get_default_style (void) { @@ -7031,7 +7031,7 @@ gtk_widget_peek_pango_context (GtkWidget *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. + * Return value: (transfer none): the #PangoContext for the widget. **/ PangoContext * gtk_widget_get_pango_context (GtkWidget *widget) @@ -7160,10 +7160,10 @@ gtk_widget_create_pango_layout (GtkWidget *widget, * @widget: a #GtkWidget * @stock_id: a stock ID * @size: a stock size. A size of (GtkIconSize)-1 means render at - * the size of the source and don't scale (if there are multiple + * the size of the source and don't scale (if there are multiple * source sizes, GTK+ picks one of the available sizes). - * @detail: render detail to pass to theme engine - * + * @detail: (allow-none): render detail to pass to theme engine + * * A convenience function that uses the theme engine and RC file * settings for @widget to look up @stock_id and render it to * a pixbuf. @stock_id should be a stock icon ID such as @@ -7241,9 +7241,10 @@ gtk_widget_set_parent_window (GtkWidget *widget, /** * gtk_widget_get_parent_window: * @widget: a #GtkWidget. - * @returns: the parent window of @widget. * * Gets @widget's parent window. + * + * Returns: (transfer none): the parent window of @widget. **/ GdkWindow * gtk_widget_get_parent_window (GtkWidget *widget) @@ -7368,8 +7369,8 @@ gtk_widget_get_screen_unchecked (GtkWidget *widget) * In general, you should only create screen specific * resources when a widget has been realized, and you should * free those resources when the widget is unrealized. - * - * Return value: the #GdkScreen for the toplevel for this widget. + * + * Return value: (transfer none): the #GdkScreen for the toplevel for this widget. * * Since: 2.2 **/ @@ -7430,8 +7431,8 @@ gtk_widget_has_screen (GtkWidget *widget) * In general, you should only create display specific * resources when a widget has been realized, and you should * free those resources when the widget is unrealized. - * - * Return value: the #GdkDisplay for the toplevel for this widget. + * + * Return value: (transfer none): the #GdkDisplay for the toplevel for this widget. * * Since: 2.2 **/ @@ -7455,8 +7456,8 @@ gtk_widget_get_display (GtkWidget *widget) * #GdkWindow associated with the window. In general, you should only * create display specific resources when a widget has been realized, * and you should free those resources when the widget is unrealized. - * - * Return value: the #GdkWindow root window for the toplevel for this widget. + * + * Return value: (transfer none): the #GdkWindow root window for the toplevel for this widget. * * Since: 2.2 **/ @@ -7813,8 +7814,8 @@ gtk_widget_set_size_request (GtkWidget *widget, /** * gtk_widget_get_size_request: * @widget: a #GtkWidget - * @width: return location for width, or %NULL - * @height: return location for height, or %NULL + * @width: (out): return location for width, or %NULL + * @height: (out): 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 @@ -7984,7 +7985,7 @@ gtk_widget_set_extension_events (GtkWidget *widget, * } * ]| * - * Return value: the topmost ancestor of @widget, or @widget itself + * Return value: (transfer none): the topmost ancestor of @widget, or @widget itself * if there's no ancestor. **/ GtkWidget* @@ -8013,7 +8014,7 @@ gtk_widget_get_toplevel (GtkWidget *widget) * Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() * considers @widget to be an ancestor of itself. * - * Return value: the ancestor widget, or %NULL if not found + * Return value: (transfer none): the ancestor widget, or %NULL if not found **/ GtkWidget* gtk_widget_get_ancestor (GtkWidget *widget, @@ -8036,8 +8037,8 @@ gtk_widget_get_ancestor (GtkWidget *widget, * * Gets the colormap that will be used to render @widget. No reference will * be added to the returned colormap; it should not be unreferenced. - * - * Return value: the colormap used by @widget + * + * Return value: (transfer none): the colormap used by @widget **/ GdkColormap* gtk_widget_get_colormap (GtkWidget *widget) @@ -8073,8 +8074,8 @@ gtk_widget_get_colormap (GtkWidget *widget) * @widget: a #GtkWidget * * Gets the visual that will be used to render @widget. - * - * Return value: the visual for @widget + * + * Return value: (transfer none): the visual for @widget **/ GdkVisual* gtk_widget_get_visual (GtkWidget *widget) @@ -8094,8 +8095,8 @@ gtk_widget_get_visual (GtkWidget *widget) * Note that this function can only be called when the #GtkWidget * is attached to a toplevel, since the settings object is specific * to a particular #GdkScreen. - * - * Return value: the relevant #GtkSettings object + * + * Return value: (transfer none): the relevant #GtkSettings object **/ GtkSettings* gtk_widget_get_settings (GtkWidget *widget) @@ -8169,8 +8170,8 @@ gtk_widget_get_extension_events (GtkWidget *widget) /** * gtk_widget_get_pointer: * @widget: a #GtkWidget - * @x: return location for the X coordinate, or %NULL - * @y: return location for the Y coordinate, or %NULL + * @x: (out) (allow-none): return location for the X coordinate, or %NULL + * @y: (out) (allow-none): return location for the Y coordinate, or %NULL * * Obtains the location of the mouse pointer in widget coordinates. * Widget coordinates are a bit odd; for historical reasons, they are @@ -8372,8 +8373,8 @@ gtk_widget_set_default_colormap (GdkColormap *colormap) * gtk_widget_get_default_colormap: * * Obtains the default colormap used to create widgets. - * - * Return value: default widget colormap + * + * Return value: (transfer none): default widget colormap **/ GdkColormap* gtk_widget_get_default_colormap (void) @@ -8386,8 +8387,8 @@ gtk_widget_get_default_colormap (void) * * Obtains the visual of the default colormap. Not really useful; * used to be useful before gdk_colormap_get_visual() existed. - * - * Return value: visual of the default colormap + * + * Return value: (transfer none): visual of the default colormap **/ GdkVisual* gtk_widget_get_default_visual (void) @@ -9205,12 +9206,12 @@ gtk_widget_shape_combine_mask (GtkWidget *widget, } /** - * gtk_widget_input_shape_combine_mask: + * gtk_widget_input_shape_combine_mask: * @widget: a #GtkWidget - * @shape_mask: shape to be added, or %NULL to remove an existing shape + * @shape_mask: (allow-none): 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 * gdk_window_input_shape_combine_mask() for more information. @@ -9796,9 +9797,9 @@ gtk_widget_style_get (GtkWidget *widget, /** * gtk_widget_path: * @widget: a #GtkWidget - * @path_length: location to store length of the path, or %NULL - * @path: location to store allocated path string, or %NULL - * @path_reversed: location to store allocated reverse path string, or %NULL + * @path_length: (out) (allow-none): location to store length of the path, or %NULL + * @path: (out) (allow-none): location to store allocated path string, or %NULL + * @path_reversed: (out) (allow-none): location to store allocated reverse path string, or %NULL * * Obtains the full path to @widget. The path is simply the name of a * widget and all its parents in the container hierarchy, separated by @@ -9869,9 +9870,9 @@ gtk_widget_path (GtkWidget *widget, /** * gtk_widget_class_path: * @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 + * @path_length: (out) (allow-none): location to store the length of the class path, or %NULL + * @path: (out) (allow-none) location to store the class path as an allocated string, or %NULL + * @path_reversed: (out) (allow-none) 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, @@ -9986,10 +9987,10 @@ gtk_requisition_get_type (void) * * The documentation of the ATK * library contains more information about accessible objects and their uses. - * - * Returns: the #AtkObject associated with @widget + * + * Returns: (transfer none): the #AtkObject associated with @widget */ -AtkObject* +AtkObject* gtk_widget_get_accessible (GtkWidget *widget) { GtkWidgetClass *klass; @@ -10576,8 +10577,8 @@ gtk_widget_buildable_custom_finished (GtkBuildable *buildable, * be used with @widget. @widget must have a #GdkDisplay * associated with it, so must be attached to a toplevel * window. - * - * Return value: the appropriate clipboard object. If no + * + * Return value: (transfer none): the appropriate clipboard object. If no * clipboard already exists, a new one will * be created. Once a clipboard object has * been created, it is persistent for all time. @@ -10609,7 +10610,8 @@ gtk_widget_get_clipboard (GtkWidget *widget, GdkAtom selection) * (GFunc)g_object_ref, NULL) first, and then unref all the * widgets afterwards. - * Return value: the list of mnemonic labels; free this list + * Return value: (element-type GtkWidget) (transfer container): the list of + * mnemonic labels; free this list * with g_list_free() when you are done with it. * * Since: 2.4 @@ -10826,7 +10828,7 @@ gtk_widget_set_tooltip_window (GtkWidget *widget, * GtkWindow created by default, or the custom tooltip window set * using gtk_widget_set_tooltip_window(). * - * Return value: The #GtkWindow of the current tooltip. + * Return value: (transfer none): The #GtkWindow of the current tooltip. * * Since: 2.12 */ @@ -11022,7 +11024,7 @@ gtk_widget_get_has_tooltip (GtkWidget *widget) /** * gtk_widget_get_allocation: * @widget: a #GtkWidget - * @allocation: a pointer to a #GtkAllocation to copy to + * @allocation: (out): a pointer to a #GtkAllocation to copy to * * Retrieves the widget's allocation. * diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c index 98747b26a8..3a35731b5b 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -1551,7 +1551,7 @@ gtk_window_get_role (GtkWindow *window) /** * gtk_window_set_focus: * @window: a #GtkWindow - * @focus: widget to be the new focus widget, or %NULL to unset + * @focus: (allow-none): widget to be the new focus widget, or %NULL to unset * any focus widget for the toplevel window. * * If @focus is not the current focus widget, and is focusable, sets @@ -1606,7 +1606,7 @@ _gtk_window_internal_set_focus (GtkWindow *window, /** * gtk_window_set_default: * @window: a #GtkWindow - * @default_widget: widget to be the default, or %NULL to unset the + * @default_widget: (allow-none): widget to be the default, or %NULL to unset the * default widget for the toplevel. * * The default widget is the widget that's activated when the user @@ -1960,9 +1960,9 @@ gtk_window_activate_focus (GtkWindow *window) * Note that this is the widget that would have the focus * if the toplevel window focused; if the toplevel window * is not focused then GTK_WIDGET_HAS_FOCUS (widget) will - * not be %TRUE for the widget. - * - * Return value: the currently focused widget, or %NULL if there is none. + * not be %TRUE for the widget. + * + * Return value: (transfer none): the currently focused widget, or %NULL if there is none. **/ GtkWidget * gtk_window_get_focus (GtkWindow *window) @@ -2071,8 +2071,8 @@ gtk_window_get_modal (GtkWindow *window) * callbacks that might destroy the widgets, you must call * g_list_foreach (result, (GFunc)g_object_ref, NULL) first, and * then unref all the widgets afterwards. - * - * Return value: list of toplevel widgets + * + * Return value: (element-type GtkWidget) (transfer container): list of toplevel widgets **/ GList* gtk_window_list_toplevels (void) @@ -2242,7 +2242,7 @@ gtk_window_unset_transient_for (GtkWindow *window) /** * gtk_window_set_transient_for: * @window: a #GtkWindow - * @parent: parent window + * @parent: (allow-none): parent window * * Dialog windows should be set transient for the main application * window they were spawned from. This allows