Commit 54ec42f0 authored by Evan Nemerson's avatar Evan Nemerson

gtk: port many nullability annotation fixes from Vala bindings

https://bugzilla.gnome.org/show_bug.cgi?id=730745
parent 4d1930cf
......@@ -1154,7 +1154,7 @@ shared_data_unref (gpointer data)
* @entries: (array length=n_entries): an array of action descriptions
* @n_entries: the number of entries
* @user_data: data to pass to the action callbacks
* @destroy: destroy notification callback for @user_data
* @destroy: (nullable): destroy notification callback for @user_data
*
* This variant of gtk_action_group_add_actions() adds a #GDestroyNotify
* callback for @user_data.
......@@ -1265,7 +1265,7 @@ gtk_action_group_add_toggle_actions (GtkActionGroup *action_group,
* @entries: (array length=n_entries): an array of toggle action descriptions
* @n_entries: the number of entries
* @user_data: data to pass to the action callbacks
* @destroy: destroy notification callback for @user_data
* @destroy: (nullable): destroy notification callback for @user_data
*
* This variant of gtk_action_group_add_toggle_actions() adds a
* #GDestroyNotify callback for @user_data.
......
......@@ -68,7 +68,8 @@ gtk_hscale_init (GtkHScale *hscale)
/**
* gtk_hscale_new:
* @adjustment: the #GtkAdjustment which sets the range of the scale.
* @adjustment: (nullable): the #GtkAdjustment which sets the range of
* the scale.
*
* Creates a new #GtkHScale.
*
......
......@@ -1409,11 +1409,12 @@ gtk_rc_get_style (GtkWidget *widget)
* G_OBJECT_TYPE (widget));
* ]|
*
* Returns: (transfer none): A style created by matching with the
* supplied paths, or %NULL if nothing matching was specified and the
* default style should be used. The returned value is owned by GTK+
* as part of an internal cache, so you must call g_object_ref() on
* the returned value if you want to keep a reference to it.
* Returns: (nullable) (transfer none): A style created by matching
* with the supplied paths, or %NULL if nothing matching was
* specified and the default style should be used. The returned
* value is owned by GTK+ as part of an internal cache, so you
* must call g_object_ref() on the returned value if you want to
* keep a reference to it.
*
* Deprecated:3.0: Use #GtkStyleContext instead
**/
......
......@@ -4498,12 +4498,12 @@ gtk_widget_modify_base (GtkWidget *widget,
/**
* gtk_widget_modify_cursor:
* @widget: a #GtkWidget
* @primary: the color to use for primary cursor (does not need to be
* allocated), or %NULL to undo the effect of previous calls to
* of gtk_widget_modify_cursor().
* @secondary: the color to use for secondary cursor (does not need to be
* allocated), or %NULL to undo the effect of previous calls to
* of gtk_widget_modify_cursor().
* @primary: (nullable): the color to use for primary cursor (does not
* need to be allocated), or %NULL to undo the effect of previous
* calls to of gtk_widget_modify_cursor().
* @secondary: (nullable): the color to use for secondary cursor (does
* not need to be allocated), or %NULL to undo the effect of
* previous calls to of gtk_widget_modify_cursor().
*
* Sets the cursor color to use in a widget, overriding the #GtkWidget
* cursor-color and secondary-cursor-color
......
......@@ -1643,7 +1643,7 @@ gtk_builder_connect_signals (GtkBuilder *builder,
* @object: object to connect a signal to
* @signal_name: name of the signal
* @handler_name: name of the handler
* @connect_object: a #GObject, if non-%NULL, use g_signal_connect_object()
* @connect_object: (nullable): a #GObject, if non-%NULL, use g_signal_connect_object()
* @flags: #GConnectFlags to use
* @user_data: user data
*
......
......@@ -1385,7 +1385,7 @@ clipboard_received_func (GtkClipboard *clipboard,
* This function waits for the data to be received using the main
* loop, so events, timeouts, etc, may be dispatched during the wait.
*
* Returns: a newly-allocated #GtkSelectionData object or %NULL
* Returns: (nullable): a newly-allocated #GtkSelectionData object or %NULL
* if retrieving the given target failed. If non-%NULL,
* this value must be freed with gtk_selection_data_free()
* when you are finished with it.
......@@ -1438,7 +1438,7 @@ clipboard_text_received_func (GtkClipboard *clipboard,
* the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
* Returns: a newly-allocated UTF-8 string which must
* Returns: (nullable): a newly-allocated UTF-8 string which must
* be freed with g_free(), or %NULL if retrieving
* the selection data failed. (This could happen
* for various reasons, in particular if the
......@@ -1497,7 +1497,7 @@ clipboard_rich_text_received_func (GtkClipboard *clipboard,
* waits for the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
* Returns: (array length=length) (transfer full): a
* Returns: (nullable) (array length=length) (transfer full): a
* newly-allocated binary block of data which must be
* freed with g_free(), or %NULL if retrieving the
* selection data failed. (This could happen for various
......@@ -1564,7 +1564,7 @@ clipboard_image_received_func (GtkClipboard *clipboard,
* the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
* Returns: (transfer full): a newly-allocated #GdkPixbuf
* Returns: (nullable) (transfer full): a newly-allocated #GdkPixbuf
* object which must be disposed with g_object_unref(), or
* %NULL if retrieving the selection data failed. (This could
* happen for various reasons, in particular if the clipboard
......@@ -1618,13 +1618,12 @@ clipboard_uris_received_func (GtkClipboard *clipboard,
* for the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
* Returns: (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
* the clipboard could not be converted into URI form.)
* Returns: (nullable) (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
* the clipboard could not be converted into URI form.)
*
* Since: 2.14
**/
......
......@@ -51,9 +51,10 @@ typedef void (* GtkClipboardReceivedFunc) (GtkClipboard *clipboard,
/**
* GtkClipboardTextReceivedFunc:
* @clipboard: the #GtkClipboard
* @text: the text received, as a UTF-8 encoded string, or %NULL
* if retrieving the data failed.
* @data: the @user_data supplied to gtk_clipboard_request_text().
* @text: (nullable): the text received, as a UTF-8 encoded string, or
* %NULL if retrieving the data failed.
* @data: (closure): the @user_data supplied to
* gtk_clipboard_request_text().
*
* A function to be called when the results of gtk_clipboard_request_text()
* are received, or when the request fails.
......@@ -120,8 +121,8 @@ typedef void (* GtkClipboardURIReceivedFunc) (GtkClipboard *clipboard,
/**
* GtkClipboardTargetsReceivedFunc:
* @clipboard: the #GtkClipboard
* @atoms: the supported targets, as array of #GdkAtom, or %NULL
* if retrieving the data failed.
* @atoms: (nullable) (array length=n_atoms): the supported targets,
* as array of #GdkAtom, or %NULL if retrieving the data failed.
* @n_atoms: the length of the @atoms array.
* @data: (closure): the @user_data supplied to
* gtk_clipboard_request_targets().
......
......@@ -5807,7 +5807,7 @@ gtk_combo_box_get_id_column (GtkComboBox *combo_box)
* no row is active, or if the active row has a %NULL ID value, then %NULL
* is returned.
*
* Returns: the ID of the active row, or %NULL
* Returns: (nullable): the ID of the active row, or %NULL
*
* Since: 3.0
**/
......
......@@ -1311,8 +1311,9 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
*
* Finds a child property of a container class by name.
*
* Returns: (transfer none): the #GParamSpec of the child property
* or %NULL if @class has no child property with that name.
* Returns: (nullable) (transfer none): the #GParamSpec of the child
* property or %NULL if @class has no child property with that
* name.
*/
GParamSpec*
gtk_container_class_find_child_property (GObjectClass *cclass,
......
......@@ -177,7 +177,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
/**
* gtk_theming_engine_register_property: (skip)
* @name_space: namespace for the property name
* @parse_func: parsing function to use, or %NULL
* @parse_func: (nullable): parsing function to use, or %NULL
* @pspec: the #GParamSpec for the new property
*
* Registers a property so it can be used in the CSS file format,
......
......@@ -174,7 +174,7 @@ gtk_css_section_get_section_type (const GtkCssSection *section)
* #GTK_CSS_SECTION_IMPORT if it was loaded with an import rule from
* a different file.
*
* Returns: the parent section or %NULL if none
* Returns: (nullable) (transfer none): the parent section or %NULL if none
*
* Since: 3.2
**/
......
......@@ -8131,7 +8131,8 @@ 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.
*
* Returns: (transfer none): the entry’s #GtkBorder, or %NULL if none was set.
* Returns: (nullable) (transfer none): the entry’s #GtkBorder, or
* %NULL if none was set.
*
* Since: 2.10
*
......@@ -9153,8 +9154,8 @@ ensure_has_tooltip (GtkEntry *entry)
* Gets the contents of the tooltip on the icon at the specified
* position in @entry.
*
* Returns: the tooltip text, or %NULL. Free the returned string
* with g_free() when done.
* Returns: (nullable): the tooltip text, or %NULL. Free the returned
* string with g_free() when done.
*
* Since: 2.16
*/
......@@ -9240,8 +9241,8 @@ gtk_entry_set_icon_tooltip_text (GtkEntry *entry,
* Gets the contents of the tooltip on the icon at the specified
* position in @entry.
*
* Returns: the tooltip text, or %NULL. Free the returned string
* with g_free() when done.
* Returns: (nullable): the tooltip text, or %NULL. Free the returned
* string with g_free() when done.
*
* Since: 2.16
*/
......@@ -10849,7 +10850,7 @@ gtk_entry_set_tabs (GtkEntry *entry,
* Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if
* any.
*
* Returns: (transfer none): the tabstops, or %NULL if none was set.
* Returns: (nullable) (transfer none): the tabstops, or %NULL if none was set.
*
* Since: 3.10
*/
......
......@@ -2046,9 +2046,9 @@ 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().
*
* Returns: (element-type filename) (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
* Returns: (nullable) (element-type filename) (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().
*
* Since: 2.4
......@@ -2144,9 +2144,9 @@ 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().
*
* Returns: (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().
* Returns: (nullable) (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().
*
* Since: 2.4
**/
......
......@@ -448,7 +448,7 @@ gtk_frame_get_label (GtkFrame *frame)
/**
* gtk_frame_set_label_widget:
* @frame: a #GtkFrame
* @label_widget: the new label widget
* @label_widget: (nullable): the new label widget
*
* Sets the label widget for the frame. This is the widget that
* will appear embedded in the top edge of the frame as a
......@@ -501,7 +501,8 @@ gtk_frame_set_label_widget (GtkFrame *frame,
* Retrieves the label widget for the frame. See
* gtk_frame_set_label_widget().
*
* Returns: (transfer none): the label widget, or %NULL if there is none.
* Returns: (nullable) (transfer none): the label widget, or %NULL if
* there is none.
**/
GtkWidget *
gtk_frame_get_label_widget (GtkFrame *frame)
......
......@@ -1957,8 +1957,9 @@ choose_icon (GtkIconTheme *icon_theme,
* gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
* combines these two steps if all you need is the pixbuf.)
*
* Returns: (transfer full): a #GtkIconInfo object containing information
* about the icon, or %NULL if the icon wasn’t found.
* Returns: (nullable) (transfer full): a #GtkIconInfo object
* containing information about the icon, or %NULL if the icon wasn’t
* found.
*
* Since: 2.4
*/
......@@ -1994,8 +1995,9 @@ gtk_icon_theme_lookup_icon (GtkIconTheme *icon_theme,
* gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines
* these two steps if all you need is the pixbuf.)
*
* Returns: (transfer full): a #GtkIconInfo object containing
* information about the icon, or %NULL if the icon wasn’t found.
* Returns: (nullable) (transfer full): a #GtkIconInfo object
* containing information about the icon, or %NULL if the icon wasn’t
* found.
*
* Since: 3.10
*/
......@@ -2098,8 +2100,9 @@ gtk_icon_theme_lookup_icon_for_scale (GtkIconTheme *icon_theme,
* tries them all in the given order before falling back to
* inherited icon themes.
*
* Returns: (transfer full): a #GtkIconInfo object containing information
* about the icon, or %NULL if the icon wasn’t found.
* Returns: (nullable) (transfer full): a #GtkIconInfo object
* containing information about the icon, or %NULL if the icon wasn’t
* found.
*
* Since: 2.12
*/
......@@ -2136,8 +2139,9 @@ gtk_icon_theme_choose_icon (GtkIconTheme *icon_theme,
* tries them all in the given order before falling back to
* inherited icon themes.
*
* Returns: (transfer full): a #GtkIconInfo object containing information
* about the icon, or %NULL if the icon wasn’t found.
* Returns: (nullable) (transfer full): a #GtkIconInfo object
* containing information about the icon, or %NULL if the icon wasn’t
* found.
*
* Since: 3.10
*/
......@@ -2188,8 +2192,8 @@ gtk_icon_theme_error_quark (void)
* returned by this function. Otherwise GTK+ may need to keep the old
* icon theme loaded, which would be a waste of memory.
*
* Returns: (transfer full): the rendered icon; this may be a
* newly created icon or a new reference to an internal icon, so
* Returns: (nullable) (transfer full): the rendered icon; this may be
* a newly created icon or a new reference to an internal icon, so
* you must not modify the icon. Use g_object_unref() to release
* your reference to the icon. %NULL if the icon isn’t found.
*
......@@ -2237,8 +2241,8 @@ gtk_icon_theme_load_icon (GtkIconTheme *icon_theme,
* returned by this function. Otherwise GTK+ may need to keep the old
* icon theme loaded, which would be a waste of memory.
*
* Returns: (transfer full): the rendered icon; this may be a
* newly created icon or a new reference to an internal icon, so
* Returns: (nullable) (transfer full): the rendered icon; this may be
* a newly created icon or a new reference to an internal icon, so
* you must not modify the icon. Use g_object_unref() to release
* your reference to the icon. %NULL if the icon isn’t found.
*
......@@ -2299,10 +2303,11 @@ gtk_icon_theme_load_icon_for_scale (GtkIconTheme *icon_theme,
* update the icon. This is usually done by connecting to the
* GtkWidget::style-set signal.
*
* Returns: (transfer full): the rendered icon; this may be a
* newly created icon or a new reference to an internal icon, so
* you must not modify the icon. Use cairo_surface_destroy() to release
* your reference to the icon. %NULL if the icon isn’t found.
* Returns: (nullable) (transfer full): the rendered icon; this may be
* a newly created icon or a new reference to an internal icon, so
* you must not modify the icon. Use cairo_surface_destroy() to
* release your reference to the icon. %NULL if the icon isn’t
* found.
*
* Since: 3.10
**/
......@@ -2638,7 +2643,7 @@ gtk_icon_theme_list_contexts (GtkIconTheme *icon_theme)
* current theme (for instance, to use when presenting
* a list of themes to the user.)
*
* Returns: the name of an example icon or %NULL.
* Returns: (nullable): the name of an example icon or %NULL.
* Free with g_free().
*
* Since: 2.4
......@@ -5360,9 +5365,9 @@ find_builtin_icon (const gchar *icon_name,
* The icon can then be rendered into a pixbuf using
* gtk_icon_info_load_icon().
*
* Returns: (transfer full): a #GtkIconInfo containing
* information about the icon, or %NULL if the icon
* wasn’t found. Unref with g_object_unref()
* Returns: (nullable) (transfer full): a #GtkIconInfo containing
* information about the icon, or %NULL if the icon wasn’t
* found. Unref with g_object_unref()
*
* Since: 2.14
*/
......@@ -5390,9 +5395,9 @@ gtk_icon_theme_lookup_by_gicon (GtkIconTheme *icon_theme,
* The icon can then be rendered into a pixbuf using
* gtk_icon_info_load_icon().
*
* Returns: (transfer full): a #GtkIconInfo containing
* information about the icon, or %NULL if the icon
* wasn’t found. Unref with g_object_unref()
* Returns: (nullable) (transfer full): a #GtkIconInfo containing
* information about the icon, or %NULL if the icon wasn’t
* found. Unref with g_object_unref()
*
* Since: 3.10
*/
......
......@@ -390,7 +390,7 @@ gtk_list_box_class_init (GtkListBoxClass *klass)
/**
* GtkListBox::row-selected:
* @box: the #GtkListBox
* @row: the selected row
* @row: (nullable): the selected row
*
* The ::row-selected signal is emitted when a new row is selected, or
* (with a %NULL @row) when the selection is cleared.
......
......@@ -1311,7 +1311,7 @@ gtk_menu_item_set_use_action_appearance (GtkMenuItem *menu_item,
/**
* gtk_menu_item_set_submenu:
* @menu_item: a #GtkMenuItem
* @submenu: (allow-none): the submenu, or %NULL
* @submenu: (allow-none) (type Gtk.Menu): the submenu, or %NULL
*
* Sets or replaces the menu item’s submenu, or removes it when a %NULL
* submenu is passed.
......
......@@ -77,13 +77,14 @@ typedef gboolean (*GtkRecentFilterFunc) (const GtkRecentFilterInfo *filter_info,
/**
* GtkRecentFilterInfo:
* @contains: #GtkRecentFilterFlags to indicate which fields are set.
* @uri: The URI of the file being tested.
* @display_name: The string that will be used to display the file in
* the recent chooser.
* @mime_type: MIME type of the file.
* @applications: The list of applications that have registered the
* file.
* @groups: The groups to which the file belongs to.
* @uri: (nullable): The URI of the file being tested.
* @display_name: (nullable): The string that will be used to display
* the file in the recent chooser.
* @mime_type: (nullable): MIME type of the file.
* @applications: (nullable) (array zero-terminated=1): The list of
* applications that have registered the file.
* @groups: (nullable) (array zero-terminated=1): The groups to which
* the file belongs to.
* @age: The number of days elapsed since the file has been
* registered.
*
......
......@@ -1714,10 +1714,11 @@ gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data,
*
* Gets the contents of the selection data as a #GdkPixbuf.
*
* Returns: (transfer full): if the selection data contained a recognized
* image type and it could be converted to a #GdkPixbuf, a
* newly allocated pixbuf is returned, otherwise %NULL.
* If the result is non-%NULL it must be freed with g_object_unref().
* Returns: (nullable) (transfer full): if the selection data
* contained a recognized image type and it could be converted to a
* #GdkPixbuf, a newly allocated pixbuf is returned, otherwise
* %NULL. If the result is non-%NULL it must be freed with
* g_object_unref().
*
* Since: 2.6
**/
......
......@@ -2249,7 +2249,7 @@ gtk_tree_store_reorder_func (gconstpointer a,
/**
* gtk_tree_store_reorder: (skip)
* @tree_store: A #GtkTreeStore
* @parent: A #GtkTreeIter, or %NULL
* @parent: (nullable): A #GtkTreeIter, or %NULL
* @new_order: (array): an array of integers mapping the new position of each child
* to its old position before the re-ordering,
* i.e. @new_order`[newpos] = oldpos`.
......
......@@ -11263,7 +11263,8 @@ gtk_tree_view_new_with_model (GtkTreeModel *model)
* Returns the model the #GtkTreeView is based on. Returns %NULL if the
* model is unset.
*
* Returns: (transfer none): A #GtkTreeModel, or %NULL if none is currently being used.
* Returns: (transfer none) (nullable): A #GtkTreeModel, or %NULL if
* none is currently being used.
**/
GtkTreeModel *
gtk_tree_view_get_model (GtkTreeView *tree_view)
......
......@@ -7865,7 +7865,7 @@ gtk_widget_reparent (GtkWidget *widget,
* gtk_widget_intersect:
* @widget: a #GtkWidget
* @area: a rectangle
* @intersection: rectangle to store intersection of @widget and @area
* @intersection: (nullable): rectangle to store intersection of @widget and @area
*
* Computes the intersection of a @widget’s area and @area, storing
* the intersection in @intersection, and returns %TRUE if there was
......@@ -10254,7 +10254,7 @@ gtk_widget_create_pango_context (GtkWidget *widget)
/**
* gtk_widget_create_pango_layout:
* @widget: a #GtkWidget
* @text: text to set on the layout (can be %NULL)
* @text: (nullable): text to set on the layout (can be %NULL)
*
* Creates a new #PangoLayout with the appropriate font map,
* font description, and base direction for drawing text for
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment