pidgin3: comparison pidgin/gtkutils.h

-:5301734d4b1c
+:61e429efe744
 *
 * Create an PidginWebView widget and associated PidginWebViewToolbar widget.  This
 * function puts both widgets in a nice GtkFrame.  They're separated by an
 * attractive GtkSeparator.
 *
-* Returns: The GtkFrame containing the toolbar and webview.
+* Returns: (transfer full): The GtkFrame containing the toolbar and webview.
 */
 GtkWidget *pidgin_create_webview(gboolean editable, GtkWidget **webview_ret, GtkWidget **sw_ret);
 /**
 * pidgin_create_small_button:
 * @image:   A button image.
 *
 * Creates a small button
 *
-* Returns:   A GtkButton created from the image.
+* Returns: (transfer full): A GtkButton created from the image.
 */
 GtkWidget *pidgin_create_small_button(GtkWidget *image);
 /**
 * pidgin_create_window:
 * @border_width: The window's desired border width
 * @role:         A string indicating what the window is responsible for doing, or %NULL
 * @resizable:    Whether the window should be resizable (%TRUE) or not (%FALSE)
 *
 * Creates a new window
+*
+* Returns: (transfer full): A new window.
 */
 GtkWidget *pidgin_create_window(const char *title, guint border_width, const char *role, gboolean resizable);
 /**
 * pidgin_create_dialog:
 * @border_width: The window's desired border width
 * @role:         A string indicating what the window is responsible for doing, or %NULL
 * @resizable:    Whether the window should be resizable (%TRUE) or not (%FALSE)
 *
 * Creates a new dialog window
+*
+* Returns: (transfer full): A new dialog window.
 */
 GtkWidget *pidgin_create_dialog(const char *title, guint border_width, const char *role, gboolean resizable);
 /**
 * pidgin_create_video_widget:
 *
 * Creates a new drawing area suitable for displaying a video
+*
+* Returns: (transfer full): A new drawing area for displaying video.
 */
 GtkWidget *pidgin_create_video_widget(void);
 /**
 * pidgin_dialog_get_vbox_with_properties:
 * @dialog:       The dialog window
 * @homogeneous:  TRUE if all children are to be given equal space allotments.
 * @spacing:      the number of pixels to place by default between children
 *
 * Retrieves the main content box (vbox) from a pidgin dialog window
+*
+* Returns: (transfer none): The main vbox from @dialog.
 */
 GtkWidget *pidgin_dialog_get_vbox_with_properties(GtkDialog *dialog, gboolean homogeneous, gint spacing);
 /**
 * pidgin_dialog_get_vbox:
 * @dialog:       The dialog window
 *
 * Retrieves the main content box (vbox) from a pidgin dialog window
+*
+* Returns: (transfer none): the main vbox from @dialog.
 */
 GtkWidget *pidgin_dialog_get_vbox(GtkDialog *dialog);
 /**
 * pidgin_dialog_add_button:
-* @dialog:         The dialog window
+* @dialog: The dialog window
-* @label:          The stock-id or the label for the button
+* @label: The stock-id or the label for the button
-* @callback:       The callback function for the button
+* @callback: (scope call): The callback function for the button
-* @callbackdata:   The user data for the callback function
+* @callbackdata: The user data for the callback function
 *
 * Add a button to a dialog created by #pidgin_create_dialog.
 *
-* Returns: The created button.
+* Returns: (transfer full): The created button.
 */
 GtkWidget *pidgin_dialog_add_button(GtkDialog *dialog, const char *label,
 		GCallback callback, gpointer callbackdata);
 /**
 * pidgin_dialog_get_action_area:
 * @dialog:       The dialog window
 *
 * Retrieves the action area (button box) from a pidgin dialog window
+*
+* Returns: (transfer none): The action area (button box) from @dialog.
 */
 GtkWidget *pidgin_dialog_get_action_area(GtkDialog *dialog);
 /**
 * pidgin_toggle_sensitive:
 void pidgin_set_sensitive_if_input(GtkWidget *entry, GtkWidget *dialog);
 /**
 * pidgin_toggle_sensitive_array:
 * @w:    %NULL. Used for signal handlers.
-* @data: The array containing the widgets to toggle.
+* @data: (element-type GtkWidget): The array containing the widgets to toggle.
 *
 * Toggles the sensitivity of all widgets in a pointer array.
 */
 void pidgin_toggle_sensitive_array(GtkWidget *w, GPtrArray *data);
 * pidgin_separator:
 * @menu: The menu to add a separator to.
 *
 * Adds a separator to a menu.
 *
-* Returns: The separator.
+* Returns: (transfer full): The separator.
 */
 GtkWidget *pidgin_separator(GtkWidget *menu);
 /**
 * pidgin_new_check_item:
-* @menu:     The menu to which to append the check menu item.
+* @menu: The menu to which to append the check menu item.
-* @str:      The title to use for the newly created menu item.
+* @str: The title to use for the newly created menu item.
-* @cb:       A function to call when the menu item is activated.
+* @cb: (scope call): A function to call when the menu item is activated.
-* @data:     Data to pass to the signal function.
+* @data: Data to pass to the signal function.
-* @checked:  The initial state of the check item
+* @checked: The initial state of the check item
 *
 * Creates a check menu item.
 *
-* Returns: The newly created menu item.
+* Returns: (transfer full): The newly created menu item.
 */
 GtkWidget *pidgin_new_check_item(GtkWidget *menu, const char *str,
 		GCallback cb, gpointer data, gboolean checked);
 /**
 * pidgin_new_menu_item:
 * @menu:       The menu to which to append the menu item.
 * @mnemonic:   The title for the menu item.
 * @icon:       An icon to place to the left of the menu item,
 *                   or %NULL for no icon.
-* @cb:         A function to call when the menu item is activated.
+* @cb: (scope call): A function to call when the menu item is activated.
 * @data:       Data to pass to the signal function.
 *
 * Creates a menu item.
 *
-* Returns: The newly created menu item.
+* Returns: (transfer full): The newly created menu item.
 */
 GtkWidget *pidgin_new_menu_item(GtkWidget *menu, const char *mnemonic,
 const char *icon, GCallback cb, gpointer data);
 /**
 * @icon:  The stock icon name.
 * @style: The orientation of the button.
 *
 * Creates a button with the specified text and stock icon.
 *
-* Returns: The button.
+* Returns: (transfer full): The button.
 */
 GtkWidget *pidgin_pixbuf_button_from_stock(const char *text, const char *icon,
 										 PidginButtonOrientation style);
 /**
 * pidgin_pixbuf_toolbar_button_from_stock:
 * @stock: The stock icon name.
 *
 * Creates a toolbar button with the stock icon.
 *
-* Returns: The button.
+* Returns: (transfer full): The button.
 */
 GtkWidget *pidgin_pixbuf_toolbar_button_from_stock(const char *stock);
 /**
 * pidgin_make_frame:
 * @parent: The widget to put the frame into.
 * @title:  The title for the frame.
 *
 * Creates a HIG preferences frame.
 *
-* Returns: The vbox to put things into.
+* Returns: (transfer full): The vbox to put things into.
 */
 GtkWidget *pidgin_make_frame(GtkWidget *parent, const char *title);
 /**
 * pidgin_protocol_option_menu_new:
-* @id:        The protocol to select by default.
+* @id: The protocol to select by default.
-* @cb:        The callback to call when a protocol is selected.
+* @cb: (scope call): The callback to call when a protocol is selected.
 * @user_data: Data to pass to the callback function.
 *
 * Creates a drop-down option menu filled with protocols.
 *
-* Returns: The drop-down option menu.
+* Returns: (transfer full): The drop-down option menu.
 */
 GtkWidget *pidgin_protocol_option_menu_new(const char *id,
 											 GCallback cb,
 											 gpointer user_data);
 const char *pidgin_protocol_option_menu_get_selected(GtkWidget *optmenu);
 /**
 * pidgin_account_option_menu_new:
 * @default_account: The account to select by default.
-* @show_all:        Whether or not to show all accounts, or just
+* @show_all: Whether or not to show all accounts, or just
-*                        active accounts.
+*            active accounts.
-* @cb:              The callback to call when an account is selected.
+* @cb: (scope call): The callback to call when an account is selected.
-* @filter_func:     A function for checking if an account should
+* @filter_func: (scope call): A function for checking if an account should
-*                        be shown. This can be NULL.
+*               be shown. This can be NULL.
-* @user_data:       Data to pass to the callback function.
+* @user_data: Data to pass to the callback function.
 *
 * Creates a drop-down option menu filled with accounts.
 *
-* Returns: The drop-down option menu.
+* Returns: (transfer full): The drop-down option menu.
 */
 GtkWidget *pidgin_account_option_menu_new(PurpleAccount *default_account,
 		gboolean show_all, GCallback cb,
 		PurpleFilterAccountFunc filter_func, gpointer user_data);
 * @optmenu: The drop-down option menu created by
 *        pidgin_account_option_menu_new.
 *
 * Gets the currently selected account from an account drop down box.
 *
-* Returns: Returns the PurpleAccount that is currently selected.
+* Returns: (transfer none): Returns the PurpleAccount that is currently selected.
 */
 PurpleAccount *pidgin_account_option_menu_get_selected(GtkWidget *optmenu);
 /**
 * pidgin_account_option_menu_set_selected:
 * pidgin_setup_screenname_autocomplete:
 * @entry:       The GtkEntry on which to setup autocomplete.
 * @optmenu:     A menu for accounts, returned by pidgin_account_option_menu_new().
 *                    If @optmenu is not %NULL, it'll be updated when a username is chosen
 *                    from the autocomplete list.
-* @filter_func: A function for checking if an autocomplete entry
+* @filter_func: (scope call): A function for checking if an autocomplete entry
 *                    should be shown. This can be %NULL.
 * @user_data:  The data to be passed to the filter_func function.
 *
 * Add autocompletion of screenames to an entry, supporting a filtering function.
 */
 * @size:         The size of the icon to return.
 *
 * Returns the base image to represent the account, based on
 * the currently selected theme.
 *
-* Returns: A newly-created pixbuf with a reference count of 1,
+* Returns: (transfer full): A newly-created pixbuf with a reference count of 1,
 *         or NULL if any of several error conditions occurred:
 *         the file could not be opened, there was no loader
 *         for the file's format, there was not enough memory
 *         to allocate the image buffer, or the image file
 *         contained invalid data.
 * @w:          The widget to render this
 * @size:       The icon size to render at
 *
 * Creates a status icon for a given primitve
 *
-* Returns: A GdkPixbuf, created from stock
+* Returns: (transfer full): A GdkPixbuf, created from stock
 */
 GdkPixbuf * pidgin_create_status_icon(PurpleStatusPrimitive primitive, GtkWidget *w, const char *size);
 /**
 * pidgin_stock_id_from_status_primitive:
 * @act:     The PurpleMenuAction to append.
 * @gobject: The object to be passed to the action callback.
 *
 * Append a PurpleMenuAction to a menu.
 *
-* Returns:   The menuitem added.
+* Returns: (transfer full): The menuitem added.
 */
 GtkWidget *pidgin_append_menu_action(GtkWidget *menu, PurpleMenuAction *act,
 gpointer gobject);
 /**
 * @callback:    The callback to call when the window is closed. If the user chose an icon, the char* argument will point to its path
 * @data:        Data to pass to @callback
 *
 * Creates a File Selection widget for choosing a buddy icon
 *
-* Returns:            The file dialog
+* Returns: (transfer full): The file dialog
 */
 GtkWidget *pidgin_buddy_icon_chooser_new(GtkWindow *parent, void(*callback)(const char*,gpointer), gpointer data);
 /**
 * pidgin_convert_buddy_icon:
 * Creates a #PidginMiniDialog, tied to a #PurpleConnection, suitable for
 * embedding in the buddy list scrollbook with pidgin_blist_add_alert().
 *
 * See <link linkend="pidgin-pidginstock">Stock Resources</link>.
 *
-* Returns:               A #PidginMiniDialog, suitable for passing to
+* Returns: (transfer full) A #PidginMiniDialog, suitable for passing to
 *                       pidgin_blist_add_alert().
 */
 GtkWidget *pidgin_make_mini_dialog(PurpleConnection *handle,
 	const char* stock_id, const char *primary, const char *secondary,
 	void *user_data, ...) G_GNUC_NULL_TERMINATED;
 /**
 * pidgin_make_mini_dialog_with_custom_icon:
+* @custom_icon: A custom GdkPixbuf to use.
+* @primary: The primary text
+* @secondary: The secondary text, or %NULL for no description.
+* @user_data: Data to pass to the callbacks
+* @...: a %NULL-terminated list of button labels
+*       (<type>char *</type>) and callbacks
+*       (#PidginUtilMiniDialogCallback).  @user_data will be
+*       passed as the first argument.  (Callbacks may lack a
+*       second argument, or be %NULL to take no action when
+*       the corresponding button is pressed.) When a button is
+*       pressed, the callback (if any) will be called; when
+*       the callback returns the dialog will be destroyed.
 *
 * Does exactly what pidgin_make_mini_dialog() does, except you can specify
 * a custom icon for the dialog.
+*
+* Returns: (transfer full): A #PidginMiniDialog, suitable for passing to
+*          pidgin_blist_add_alert().
 */
 GtkWidget *pidgin_make_mini_dialog_with_custom_icon(PurpleConnection *gc,
 	GdkPixbuf *custom_icon,
 	const char *primary,
 	const char *secondary,
 */
 const char *pidgin_get_dim_grey_string(GtkWidget *widget);
 /**
 * pidgin_text_combo_box_entry_new:
-* @default_item:   Initial contents of GtkEntry
+* @default_item: Initial contents of GtkEntry
-* @items:          GList containing strings to add to GtkComboBox
+* @items: (element-type utf8): GList containing strings to add to GtkComboBox
 *
 * Create a simple text GtkComboBoxEntry equivalent
 *
-* Returns:               A newly created text GtkComboBox containing a GtkEntry
+* Returns: (transfer full): A newly created text GtkComboBox containing a GtkEntry
-*                       child.
+*          child.
 */
 GtkWidget *pidgin_text_combo_box_entry_new(const char *default_item, GList *items);
 /**
 * pidgin_text_combo_box_entry_get_text:
 * @expand:       Whether to expand the widget horizontally.
 * @p_label:      Place to store a pointer to the GtkLabel, or %NULL if you don't care.
 *
 * Add a labelled widget to a GtkBox
 *
-* Returns:  A GtkBox already added to the GtkBox containing the GtkLabel and the GtkWidget.
+* Returns:  (transfer full): A GtkBox already added to the GtkBox containing the GtkLabel and the GtkWidget.
 */
 GtkWidget *pidgin_add_widget_to_vbox(GtkBox *vbox, const char *widget_label, GtkSizeGroup *sg, GtkWidget *widget, gboolean expand, GtkWidget **p_label);
 /**
 * pidgin_pixbuf_from_data:
 * @buf: The raw binary image data.
 * @count: The length of buf in bytes.
 *
 * Create a GdkPixbuf from a chunk of image data.
 *
-* Returns: A GdkPixbuf created from the image data, or NULL if
+* Returns: (transfer full): A GdkPixbuf created from the image data, or NULL if
 *         there was an error parsing the data.
 */
 GdkPixbuf *pidgin_pixbuf_from_data(const guchar *buf, gsize count);
 /**
 * @buf: The raw binary image data.
 * @count: The length of buf in bytes.
 *
 * Create a GdkPixbufAnimation from a chunk of image data.
 *
-* Returns: A GdkPixbufAnimation created from the image data, or NULL if
+* Returns: (transfer full): A GdkPixbufAnimation created from the image data, or NULL if
 *         there was an error parsing the data.
 */
 GdkPixbufAnimation *pidgin_pixbuf_anim_from_data(const guchar *buf, gsize count);
 /**
 * pidgin_pixbuf_from_image:
 * @image: a PurpleImage.
 *
 * Create a GdkPixbuf from a PurpleImage.
 *
-* Returns: a GdkPixbuf created from the @image.
+* Returns: (transfer full): a GdkPixbuf created from the @image.
 */
 GdkPixbuf *
 pidgin_pixbuf_from_image(PurpleImage *image);
 /**
 *
 * This function shouldn't be necessary once Pidgin requires a version of
 * gdk-pixbuf where the aforementioned bug is fixed.  However, it might be
 * nice to keep this function around for the debug message that it logs.
 *
-* Returns: The GdkPixbuf if successful.  Otherwise NULL is returned and
+* Returns: (transfer full): The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 */
 GdkPixbuf *pidgin_pixbuf_new_from_file(const char *filename);
 /**
 *
 * This function shouldn't be necessary once Pidgin requires a version of
 * gdk-pixbuf where the aforementioned bug is fixed.  However, it might be
 * nice to keep this function around for the debug message that it logs.
 *
-* Returns: The GdkPixbuf if successful.  Otherwise NULL is returned and
+* Returns: (transfer full): The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 */
 GdkPixbuf *pidgin_pixbuf_new_from_file_at_size(const char *filename, int width, int height);
 /**
 *
 * This function shouldn't be necessary once Pidgin requires a version of
 * gdk-pixbuf where the aforementioned bug is fixed.  However, it might be
 * nice to keep this function around for the debug message that it logs.
 *
-* Returns: The GdkPixbuf if successful.  Otherwise NULL is returned and
+* Returns: (transfer full): The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 */
 GdkPixbuf *pidgin_pixbuf_new_from_file_at_scale(const char *filename, int width, int height, gboolean preserve_aspect_ratio);
 /**
 * returned without modifications.
 *
 * If new image is created, @src reference cound will be decreased and new image
 * with a ref count of 1 will be returned.
 *
-* Returns: The image with proper sizing. %NULL in case of error.
+* Returns: (transfer full): The image with proper sizing. %NULL in case of error.
 */
 GdkPixbuf *
 pidgin_pixbuf_scale_down(GdkPixbuf *src, guint max_width, guint max_height,
 	GdkInterpType interp_type, gboolean preserve_ratio);
 * @shadow_type:        Shadow type
 * @width:              Desired widget width, or -1 for default
 * @height:             Desired widget height, or -1 for default
 *
 * Add scrollbars to a widget
+*
+* Returns: (transfer full): A scrolled window with @child packed inside of it.
 */
 GtkWidget *pidgin_make_scrollable(GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height);
 /**
 * pidgin_utils_init:

Mercurial > pidgin3 / file comparison

comparison: pidgin/gtkutils.h

pidgin/gtkutils.h