Commit e0aa12eb authored by Matthias Clasen's avatar Matthias Clasen
Browse files

Tons of transfer annotations

parent ca251cf1
......@@ -221,12 +221,11 @@ drops.
<!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
<para>
Determines the source widget for a drag.
</para>
@context: a (destination side) drag context.
@Returns: if the drag is occurring within a single application,
a pointer to the source widget. Otherwise, %NULL.
@context:
@Returns:
<!-- ##### FUNCTION gtk_drag_highlight ##### -->
......
......@@ -392,11 +392,11 @@ widget and this function does nothing.
<!-- ##### FUNCTION gtk_grab_get_current ##### -->
<para>
Queries the current grab of the default window group.
</para>
@void:
@Returns: The widget which currently has the grab or %NULL if no grab is active.
@void:
@Returns:
<!-- ##### FUNCTION gtk_grab_remove ##### -->
......
......@@ -140,11 +140,10 @@ Sets the group of a radio menu item, or changes it.
<!-- ##### FUNCTION gtk_radio_menu_item_get_group ##### -->
<para>
Returns the group to which the radio menu item belongs, as a #GList of
#GtkRadioMenuItem. The list belongs to GTK+ and should not be freed.
</para>
@radio_menu_item: a #GtkRadioMenuItem.
@Returns: the group of @radio_menu_item.
@radio_menu_item:
@Returns:
......@@ -972,7 +972,7 @@ gdk_event_set_device (GdkEvent *event,
* If the event contains a "device" field, this function will return
* it, else it will return %NULL.
*
* Returns: a #GdkDevice, or %NULL.
* Returns: (transfer none): a #GdkDevice, or %NULL.
*
* Since: 3.0
**/
......
......@@ -319,7 +319,7 @@ gtk_accel_label_finalize (GObject *object)
* Fetches the widget monitored by this accelerator label. See
* gtk_accel_label_set_accel_widget().
*
* Returns: the object monitored by the accelerator label, or %NULL.
* Returns: (transfer none): the object monitored by the accelerator label, or %NULL.
**/
GtkWidget*
gtk_accel_label_get_accel_widget (GtkAccelLabel *accel_label)
......
......@@ -873,7 +873,7 @@ gtk_action_unblock_activate (GtkAction *action)
* This function is intended for use by action implementations to
* create icons displayed in the proxy widgets.
*
* Returns: a widget that displays the icon for this action.
* Returns: (transfer full): a widget that displays the icon for this action.
*
* Since: 2.4
*/
......@@ -899,7 +899,7 @@ gtk_action_create_icon (GtkAction *action, GtkIconSize icon_size)
*
* Creates a menu item widget that proxies for the given action.
*
* Returns: a menu item connected to the action.
* Returns: (transfer full): a menu item connected to the action.
*
* Since: 2.4
*/
......@@ -924,7 +924,7 @@ gtk_action_create_menu_item (GtkAction *action)
*
* Creates a toolbar item widget that proxies for the given action.
*
* Returns: a toolbar item connected to the action.
* Returns: (transfer full): a toolbar item connected to the action.
*
* Since: 2.4
*/
......@@ -1609,7 +1609,7 @@ gtk_action_set_gicon (GtkAction *action,
*
* Gets the gicon of @action.
*
* Returns: The action's #GIcon if one is set.
* Returns: (transfer none): The action's #GIcon if one is set.
*
* Since: 2.16
*/
......@@ -1811,7 +1811,7 @@ gtk_action_disconnect_accelerator (GtkAction *action)
* item or the toolbar item it creates, this function returns an
* instance of that menu.
*
* Return value: the menu item provided by the action, or %NULL.
* Return value: (transfer full): the menu item provided by the action, or %NULL.
*
* Since: 2.12
*/
......
......@@ -478,7 +478,7 @@ gtk_activatable_do_set_related_action (GtkActivatable *activatable,
*
* Gets the related #GtkAction for @activatable.
*
* Returns: the related #GtkAction if one is set.
* Returns: (transfer none): the related #GtkAction if one is set.
*
* Since: 2.16
**/
......
......@@ -66,12 +66,12 @@ struct _GtkApplicationClass
GApplicationClass parent_class;
/*< vfuncs >*/
GtkWindow *(* create_window) (GtkApplication *application);
void (* activated) (GtkApplication *application,
GtkWindow *(* create_window) (GtkApplication *app);
void (* activated) (GtkApplication *app,
GVariant *args);
void (* action) (GtkApplication *application,
void (* action) (GtkApplication *app,
const gchar *action_name);
gboolean (* quit) (GtkApplication *application);
gboolean (* quit) (GtkApplication *app);
/* Padding for future expansion */
......
......@@ -1686,7 +1686,8 @@ gtk_assistant_get_n_pages (GtkAssistant *assistant)
*
* Returns the child widget contained in page number @page_num.
*
* Return value: The child widget, or %NULL if @page_num is out of bounds.
* Return value: (transfer none): The child widget, or %NULL
* if @page_num is out of bounds.
*
* Since: 2.10
**/
......@@ -2117,11 +2118,11 @@ gtk_assistant_set_page_header_image (GtkAssistant *assistant,
* gtk_assistant_get_page_header_image:
* @assistant: a #GtkAssistant
* @page: a page of @assistant
*
* Gets the header image for @page.
*
* Return value: the header image for @page, or %NULL
* if there's no header image for the page.
*
* Gets the header image for @page.
*
* Return value: (transfer none): the header image for @page, or %NULL
* if there's no header image for the page.
*
* Since: 2.10
**/
......@@ -2197,11 +2198,11 @@ gtk_assistant_set_page_side_image (GtkAssistant *assistant,
* gtk_assistant_get_page_side_image:
* @assistant: a #GtkAssistant
* @page: a page of @assistant
*
* Gets the header image for @page.
*
* Return value: the side image for @page, or %NULL
* if there's no side image for the page.
*
* Gets the header image for @page.
*
* Return value: (transfer none): the side image for @page, or %NULL
* if there's no side image for the page.
*
* Since: 2.10
**/
......
......@@ -204,12 +204,12 @@ gtk_buildable_parser_finished (GtkBuildable *buildable,
* @builder: #GtkBuilder used to construct this object
* @name: name of child to construct
*
* Constructs a child of @buildable with the name @name.
* Constructs a child of @buildable with the name @name.
*
* #GtkBuilder calls this function if a "constructor" has been
* specified in the UI definition.
*
* Returns: the constructed child
* Returns: (transfer full): the constructed child
*
* Since: 2.12
**/
......@@ -337,7 +337,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable,
*
* Get the internal child called @childname of the @buildable object.
*
* Returns: the internal child of the buildable object
* Returns: (transfer none): the internal child of the buildable object
*
* Since: 2.12
**/
......
......@@ -2443,7 +2443,7 @@ gtk_button_set_image (GtkButton *button,
* This may have been explicitly set by gtk_button_set_image()
* or constructed by gtk_button_new_from_stock().
*
* Return value: a #GtkWidget or %NULL in case there is no image
* Return value: (transfer none): a #GtkWidget or %NULL in case there is no image
*
* Since: 2.6
*/
......
......@@ -719,15 +719,15 @@ gtk_cell_renderer_activate (GtkCellRenderer *cell,
* @cell: a #GtkCellRenderer
* @event: a #GdkEvent
* @widget: widget that received the event
* @path: widget-dependent string representation of the event location;
* @path: widget-dependent string representation of the event location;
* e.g. for #GtkTreeView, a string representation of #GtkTreePath
* @background_area: background area as passed to gtk_cell_renderer_render()
* @cell_area: cell area as passed to gtk_cell_renderer_render()
* @flags: render flags
*
*
* Passes an activate event to the cell renderer for possible processing.
*
* Return value: A new #GtkCellEditable, or %NULL
*
* Return value: (transfer full): A new #GtkCellEditable, or %NULL
**/
GtkCellEditable *
gtk_cell_renderer_start_editing (GtkCellRenderer *cell,
......
......@@ -266,8 +266,6 @@ gtk_cell_size_request_get_height_for_width (GtkCellSizeRequest *cell,
* gtk_cell_size_request_get_size:
* @cell: a #GtkCellSizeRequest instance
* @widget: the #GtkWidget this cell will be rendering to
* @request_natural: Whether to base the contextual request off of the
* base natural or the base minimum
* @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
* @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
*
......
......@@ -923,7 +923,7 @@ gtk_cell_view_set_model (GtkCellView *cell_view,
* Returns the model for @cell_view. If no model is used %NULL is
* returned.
*
* Returns: a #GtkTreeModel used or %NULL
* Returns: (transfer none): a #GtkTreeModel used or %NULL
*
* Since: 2.16
**/
......
......@@ -563,22 +563,23 @@ gtk_clipboard_set_contents (GtkClipboard *clipboard,
/**
* gtk_clipboard_set_with_data:
* @clipboard: a #GtkClipboard
* @targets: array containing information about the available forms for the
* clipboard data
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
* be called, and @get_func will not be subsequently called.
* @user_data: user data to pass to @get_func and @clear_func.
*
* @clipboard: a #GtkClipboard
* @targets: array containing information about the available forms for the
* clipboard data
* @n_targets: number of elements in @targets
* @get_func: (scope async): function to call to get the actual clipboard data
* @clear_func: (scope async): when the clipboard contents are set again,
* this function will be called, and @get_func will not be subsequently
* called.
* @user_data: user data to pass to @get_func and @clear_func.
*
* Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
* Return value: %TRUE if setting the clipboard data succeeded. If setting
* the clipboard data failed the provided callback functions
* will be ignored.
*
* Return value: %TRUE if setting the clipboard data succeeded.
* If setting the clipboard data failed the provided callback
* functions will be ignored.
**/
gboolean
gtk_clipboard_set_with_data (GtkClipboard *clipboard,
......@@ -599,27 +600,28 @@ gtk_clipboard_set_with_data (GtkClipboard *clipboard,
/**
* gtk_clipboard_set_with_owner:
* @clipboard: a #GtkClipboard
* @targets: array containing information about the available forms for the
* clipboard data
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
* be called, and @get_func will not be subsequently called.
* @owner: an object that "owns" the data. This object will be passed
* to the callbacks when called.
*
* @clipboard: a #GtkClipboard
* @targets: array containing information about the available forms for
* the clipboard data
* @n_targets: number of elements in @targets
* @get_func: (scope async): function to call to get the actual clipboard data
* @clear_func: (scope async): when the clipboard contents are set again,
* this function will be called, and @get_func will not be subsequently
* called
* @owner: an object that "owns" the data. This object will be passed
* to the callbacks when called
*
* Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
* The difference between this function and gtk_clipboard_set_with_data()
* is that instead of an generic @user_data pointer, a #GObject is passed
* in.
*
* Return value: %TRUE if setting the clipboard data succeeded. If setting
* the clipboard data failed the provided callback functions
* will be ignored.
* in.
*
* Return value: %TRUE if setting the clipboard data succeeded.
* If setting the clipboard data failed the provided callback
* functions will be ignored.
**/
gboolean
gtk_clipboard_set_with_owner (GtkClipboard *clipboard,
......@@ -642,13 +644,14 @@ gtk_clipboard_set_with_owner (GtkClipboard *clipboard,
/**
* gtk_clipboard_get_owner:
* @clipboard: a #GtkClipboard
*
* If the clipboard contents callbacks were set with
* gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
* gtk_clipboard_clear() has not subsequently called, returns the owner set
*
* If the clipboard contents callbacks were set with
* gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
* gtk_clipboard_clear() has not subsequently called, returns the owner set
* by gtk_clipboard_set_with_owner().
*
* Return value: the owner of the clipboard, if any; otherwise %NULL.
*
* Return value: (transfer none): the owner of the clipboard, if any;
* otherwise %NULL.
**/
GObject *
gtk_clipboard_get_owner (GtkClipboard *clipboard)
......@@ -874,14 +877,13 @@ selection_received (GtkWidget *widget,
/**
* gtk_clipboard_request_contents:
* @clipboard: a #GtkClipboard
* @target: an atom representing the form into which the clipboard
* owner should convert the selection.
* @callback: A function to call when the results are received
* (or the retrieval fails). If the retrieval fails
* the length field of @selection_data will be
* negative.
* @target: an atom representing the form into which the clipboard
* owner should convert the selection.
* @callback: (scope async): A function to call when the results are received
* (or the retrieval fails). If the retrieval fails the length field of
* @selection_data will be negative.
* @user_data: user data to pass to @callback
*
*
* Requests the contents of clipboard as the given target.
* When the results of the result are later received the supplied callback
* will be called.
......@@ -957,14 +959,13 @@ request_text_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_request_text:
* @clipboard: a #GtkClipboard
* @callback: a function to call when the text is received,
* or the retrieval fails. (It will always be called
* one way or the other.)
* @callback: (scope async): a function to call when the text is received,
* or the retrieval fails. (It will always be called one way or the other.)
* @user_data: user data to pass to @callback.
*
*
* Requests the contents of the clipboard as text. When the text is
* later received, it will be converted to UTF-8 if necessary, and
* @callback will be called.
* @callback will be called.
*
* The @text parameter to @callback will contain the resulting text if
* the request succeeded, or %NULL if it failed. This could happen for
......@@ -1021,10 +1022,9 @@ request_rich_text_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_request_rich_text:
* @clipboard: a #GtkClipboard
* @buffer: a #GtkTextBuffer
* @callback: a function to call when the text is received,
* or the retrieval fails. (It will always be called
* one way or the other.)
* @buffer: a #GtkTextBuffer
* @callback: (scope async): a function to call when the text is received,
* or the retrieval fails. (It will always be called one way or the other.)
* @user_data: user data to pass to @callback.
*
* Requests the contents of the clipboard as rich text. When the rich
......@@ -1114,19 +1114,18 @@ request_image_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_request_image:
* @clipboard: a #GtkClipboard
* @callback: a function to call when the image is received,
* or the retrieval fails. (It will always be called
* one way or the other.)
* @callback: (scope async): a function to call when the image is received,
* or the retrieval fails. (It will always be called one way or the other.)
* @user_data: user data to pass to @callback.
*
*
* Requests the contents of the clipboard as image. When the image is
* later received, it will be converted to a #GdkPixbuf, and
* @callback will be called.
* @callback will be called.
*
* The @pixbuf parameter to @callback will contain the resulting
* #GdkPixbuf if the request succeeded, or %NULL if it failed. This
* could happen for various reasons, in particular if the clipboard
* was empty or if the contents of the clipboard could not be
* The @pixbuf parameter to @callback will contain the resulting
* #GdkPixbuf if the request succeeded, or %NULL if it 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 an image.
*
* Since: 2.6
......@@ -1169,11 +1168,10 @@ request_uris_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_request_uris:
* @clipboard: a #GtkClipboard
* @callback: a function to call when the URIs are received,
* or the retrieval fails. (It will always be called
* one way or the other.)
* @callback: (scope async): a function to call when the URIs are received,
* or the retrieval fails. (It will always be called one way or the other.)
* @user_data: user data to pass to @callback.
*
*
* Requests the contents of the clipboard as URIs. When the URIs are
* later received @callback will be called.
*
......@@ -1223,13 +1221,13 @@ request_targets_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_request_targets:
* @clipboard: a #GtkClipboard
* @callback: a function to call when the targets are received,
* or the retrieval fails. (It will always be called
* one way or the other.)
* @callback: (scope async): a function to call when the targets are
* received, or the retrieval fails. (It will always be called
* one way or the other.)
* @user_data: user data to pass to @callback.
*
* Requests the contents of the clipboard as list of supported targets.
* When the list is later received, @callback will be called.
*
* Requests the contents of the clipboard as list of supported targets.
* When the list is later received, @callback will be called.
*
* The @targets parameter to @callback will contain the resulting targets if
* the request succeeded, or %NULL if it failed.
......@@ -1466,18 +1464,18 @@ clipboard_image_received_func (GtkClipboard *clipboard,
/**
* gtk_clipboard_wait_for_image:
* @clipboard: a #GtkClipboard
*
*
* Requests the contents of the clipboard as image and converts
* the result to a #GdkPixbuf. 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 #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 was empty or if the contents of
* the clipboard could not be converted into an image.)
*
* Return value: (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
* was empty or if the contents of the clipboard could not be
* converted into an image.)
*
* Since: 2.6
**/
......@@ -1568,7 +1566,7 @@ gtk_clipboard_wait_for_uris (GtkClipboard *clipboard)
*
* Gets the #GdkDisplay associated with @clipboard
*
* Return value: the #GdkDisplay associated with @clipboard
* Return value: (transfer none): the #GdkDisplay associated with @clipboard
*
* Since: 2.2
**/
......
......@@ -210,7 +210,7 @@ gtk_color_selection_dialog_new (const gchar *title)
*
* Retrieves the #GtkColorSelection widget embedded in the dialog.
*
* Returns: the embedded #GtkColorSelection
* Returns: (transfer none): the embedded #GtkColorSelection
*
* Since: 2.14
**/
......
......@@ -5099,12 +5099,13 @@ out:
}
/**
* gtk_combo_box_get_model
* gtk_combo_box_get_model:
* @combo_box: A #GtkComboBox
*
* Returns the #GtkTreeModel which is acting as data source for @combo_box.
*
* Return value: (transfer none): A #GtkTreeModel which was passed during construction.
* Return value: (transfer none): A #GtkTreeModel which was passed
* during construction.
*
* Since: 2.4
*/
......@@ -5744,7 +5745,8 @@ gtk_combo_box_set_title (GtkComboBox *combo_box,
* This function is mostly intended for use by accessibility technologies;
* applications should have little use for it.
*
* Returns: the accessible object corresponding to the combo box's popup.
* Returns: (transfer none): the accessible object corresponding
* to the combo box's popup.
*
* Since: 2.6
*/
......
......@@ -1663,7 +1663,7 @@ gtk_container_forall (GtkContainer *container,
/**
* gtk_container_foreach:
* @container: a #GtkContainer
* @callback: a callback
* @callback: (scope call): a callback
* @callback_data: callback user data
*
* Invokes @callback on each non-internal child of @container. See
......
......@@ -1009,17 +1009,16 @@ gtk_drag_get_data (GtkWidget *widget,
}
/*************************************************************
/**
* gtk_drag_get_source_widget:
* Get the widget the was the source of this drag, if
* the drag originated from this application.
* arguments:
* context: The drag context for this drag
* results:
* The source widget, or NULL if the drag originated from
* a different application.
*************************************************************/
* @context: a (destination side) drag context
*
* Determines the source widget for a drag.
*
* Return value: (transfer none): if the drag is occurring
* within a single application, a pointer to the source widget.
* Otherwise, %NULL.
*/
GtkWidget *
gtk_drag_get_source_widget (GdkDragContext *context)
{
......@@ -1692,7 +1691,7 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
* @context: drag context
* @target_list: (allow-none): list of droppable targets, or %NULL to use
* gtk_drag_dest_get_target_list (@widget).
*
*
* Looks for a match between @context->targets and the
* @dest_target_list, returning the first matching target, otherwise
* returning %GDK_NONE. @dest_target_list should usually be the return
......@@ -1700,7 +1699,7 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
* have different valid targets for different parts of the widget; in
* that case, they will have to implement a drag_motion handler that
* passes the correct target list to this function.
*
*
* Return value: first target that the source offers and the dest can accept, or %GDK_NONE
**/
GdkAtom
......@@ -2561,7 +2560,7 @@ gtk_drag_begin_internal (GtkWidget *widget,
* @actions: A bitmask of the allowed drag actions for this drag.
* @button: The button the user clicked to start the drag.
* @event: The event that triggered the start of the drag.
*
*
* Initiates a drag on the source side. The function
* only needs to be used when the application is
* starting drags itself, and is not needed when
......@@ -2573,23 +2572,23 @@ gtk_drag_begin_internal (GtkWidget *widget,
* used by GTK+ to get information about the start position of the drag, for
* example if the @event is a GDK_MOTION_NOTIFY.
*
* Generally there are three cases when you want to start a drag by hand by calling
* this function:
* Generally there are three cases when you want to start a drag by hand by
* calling this function:
*
* 1. During a button-press-event handler, if you want to start a drag immediately
* when the user presses the mouse button. Pass the @event that you have in your
* button-press-event handler.
* 1. During a button-press-event handler, if you want to start a drag
* immediately when the user presses the mouse button. Pass the @event
* that you have in your button-press-event handler.
*
* 2. During a motion-notify-event handler, if you want to start a drag when the mouse
* moves past a certain threshold distance after a button-press. Pass the @event that you
* have in your motion-notify-event handler.
* 2. During a motion-notify-event handler, if you want to start a drag
* when the mouse moves past a certain threshold distance after a button-press.
* Pass the @event that you have in your motion-notify-event handler.
*
* 3. During a timeout handler, if you want to start a drag after the mouse
* button is held down for some time. Try to save the last event that you got
* from the mouse, using gdk_event_copy(), and pass it to this function
* (remember to free the event with gdk_event_free() when you are done). If you
* can really not pass a real event, pass #NULL instead.
*
* (remember to free the event with gdk_event_free() when you are done).
* If you can really not pass a real event, pass #NULL instead.
*
* Return value: the context for this drag.
**/
GdkDragContext *
......