[gtk+/gi-annotations: 19/31] Update GI annotations in 'Selectors (Color/File/Font)'

From: Pavel Holejsovsky <pholejs src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk+/gi-annotations: 19/31] Update GI annotations in 'Selectors (Color/File/Font)'
Date: Mon, 17 Jan 2011 05:52:26 +0000 (UTC)
commit 34b544ccf5330e5099c8a337c054d37f6c840003
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Sun Jan 16 08:35:25 2011 +0100

    Update GI annotations in 'Selectors (Color/File/Font)'
    
    'Selectors (Color/File/Font)' group from GTK+ manual is:
    GtkColorButton, GtkColorSelectionDialog, GtkColorSelection, GtkHSV,
    GtkFileChooser, GtkFileChooserButton, GtkFileChooserDialog,
    GtkFileChooserWidget, GtkFileFilter, GtkFontButton, GtkFontSelection,
    GtkFontSelectionDialog.

 gtk/gtkcolorsel.c    |   11 ++++----
 gtk/gtkfilechooser.c |   64 ++++++++++++++++++++++++++-----------------------
 gtk/gtkfilefilter.h  |    2 +-
 gtk/gtkhsv.c         |   22 ++++++++--------
 4 files changed, 52 insertions(+), 47 deletions(-)
---
diff --git a/gtk/gtkcolorsel.c b/gtk/gtkcolorsel.c
index f60d1e7..c5f05fb 100644
--- a/gtk/gtkcolorsel.c
+++ b/gtk/gtkcolorsel.c
@@ -2650,7 +2650,7 @@ gtk_color_selection_set_previous_alpha (GtkColorSelection *colorsel,
 /**
  * gtk_color_selection_get_previous_color:
  * @colorsel: a #GtkColorSelection.
- * @color: a #GdkColor to fill in with the original color value.
+ * @color: (out): a #GdkColor to fill in with the original color value.
  *
  * Fills @color in with the original color value.
  **/
@@ -2802,7 +2802,7 @@ gtk_color_selection_set_previous_rgba (GtkColorSelection *colorsel,
 /**
  * gtk_color_selection_get_previous_rgba:
  * @colorsel: a #GtkColorSelection.
- * @rgba: a #GdkRGBA to fill in with the original color value.
+ * @rgba: (out): a #GdkRGBA to fill in with the original color value.
  *
  * Fills @rgba in with the original color value.
  *
@@ -2881,7 +2881,8 @@ gtk_color_selection_is_adjusting (GtkColorSelection *colorsel)
 /**
  * gtk_color_selection_palette_from_string:
  * @str: a string encoding a color palette.
- * @colors: return location for allocated array of #GdkColor.
+ * @colors: (out) (array length=n_colors): return location for allocated
+ *          array of #GdkColor.
  * @n_colors: return location for length of array.
  * 
  * Parses a color palette string; the string is a colon-separated
@@ -2966,7 +2967,7 @@ gtk_color_selection_palette_from_string (const gchar *str,
 
 /**
  * gtk_color_selection_palette_to_string:
- * @colors: an array of colors.
+ * @colors: (array length=n_colors): an array of colors.
  * @n_colors: length of the array.
  * 
  * Encodes a palette as a string, useful for persistent storage.
@@ -3012,7 +3013,7 @@ gtk_color_selection_palette_to_string (const GdkColor *colors,
 }
 
 /**
- * gtk_color_selection_set_change_palette_with_screen_hook:
+ * gtk_color_selection_set_change_palette_with_screen_hook: (skip)
  * @func: a function to call when the custom palette needs saving.
  * 
  * Installs a global function to be called whenever the user tries to
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 898b3d4..9243612 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -1033,7 +1033,7 @@ gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
  * If the file chooser is in folder mode, this function returns the selected
  * folder.
  * 
- * Return value: The currently selected filename, or %NULL
+ * Return value: (type filename): The currently selected filename, or %NULL
  *  if no file is selected, or the selected file can't
  *  be represented with a local filename. Free with g_free().
  *
@@ -1061,7 +1061,7 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to set as current
+ * @filename: (type filename): the filename to set as current
  * 
  * Sets @filename as the current filename for the file chooser, by changing
  * to the file's parent folder and actually selecting the file in list.  If
@@ -1115,7 +1115,7 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
 /**
  * gtk_file_chooser_select_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to select
+ * @filename: (type filename): the filename to select
  * 
  * Selects a filename. If the file name isn't in the current
  * folder of @chooser, then the current folder of @chooser will
@@ -1146,7 +1146,7 @@ gtk_file_chooser_select_filename (GtkFileChooser *chooser,
 /**
  * gtk_file_chooser_unselect_filename:
  * @chooser: a #GtkFileChooser
- * @filename: the filename to unselect
+ * @filename: (type filename): the filename to unselect
  * 
  * Unselects a currently selected filename. If the filename
  * is not in the current directory, does not exist, or
@@ -1201,9 +1201,10 @@ files_to_strings (GSList  *files,
  * folder cannot be represented as local filenames they will be ignored. (See
  * gtk_file_chooser_get_uris())
  *
- * 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().
+ * Return value: (element-type filename) (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().
  *
  * Since: 2.4
  **/
@@ -1226,7 +1227,7 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_current_folder:
  * @chooser: a #GtkFileChooser
- * @filename: the full path of the new current folder
+ * @filename: (type filename): the full path of the new current folder
  * 
  * Sets the current folder for @chooser from a local filename.
  * The user will be shown the full contents of the current folder,
@@ -1269,10 +1270,11 @@ gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
  * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
  * usual way to get the selection.
  * 
- * Return value: the full path of the current folder, or %NULL if the current
- * path cannot be represented as a local filename.  Free with g_free().  This
- * function will also return %NULL if the file chooser was unable to load the
- * last folder that was requested from it; for example, as would be for calling
+ * Return value: (type filename): the full path of the current folder,
+ * or %NULL if the current path cannot be represented as a local
+ * filename.  Free with g_free().  This function will also return
+ * %NULL if the file chooser was unable to load the last folder that
+ * was requested from it; for example, as would be for calling
  * gtk_file_chooser_set_current_folder() on a nonexistent folder.
  *
  * Since: 2.4
@@ -1298,7 +1300,7 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_set_current_name:
  * @chooser: a #GtkFileChooser
- * @name: the filename to use, as a UTF-8 string
+ * @name: (type filename): the filename to use, as a UTF-8 string
  * 
  * Sets the current name in the file selector, as if entered
  * by the user. Note that the name passed in here is a UTF-8
@@ -1696,9 +1698,10 @@ 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: (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().
+ * Return value: (element-type GFile) (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().
  *
  * Since: 2.14
  **/
@@ -1986,7 +1989,7 @@ gtk_file_chooser_get_use_preview_label (GtkFileChooser *chooser)
  * Gets the #GFile that should be previewed in a custom preview
  * Internal function, see gtk_file_chooser_get_preview_uri().
  *
- * Return value: (transfer none): the #GFile for the file to preview,
+ * Return value: (transfer full): the #GFile for the file to preview,
  *     or %NULL if no file is selected. Free with g_object_unref().
  *
  * Since: 2.14
@@ -2056,8 +2059,8 @@ _gtk_file_chooser_remove_shortcut_folder (GtkFileChooser  *chooser,
  * Gets the filename that should be previewed in a custom preview
  * widget. See gtk_file_chooser_set_preview_widget().
  * 
- * Return value: the filename to preview, or %NULL if no file
- *  is selected, or if the selected file cannot be represented
+ * Return value: (type filename): the filename to preview, or %NULL if
+ *  no file is selected, or if the selected file cannot be represented
  *  as a local filename. Free with g_free()
  *
  * Since: 2.4
@@ -2206,10 +2209,10 @@ 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: (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.
+ * Return value: (element-type GtkFileFilter) (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.
  *
  * Since: 2.4
  **/
@@ -2276,7 +2279,7 @@ gtk_file_chooser_get_filter (GtkFileChooser *chooser)
 /**
  * gtk_file_chooser_add_shortcut_folder:
  * @chooser: a #GtkFileChooser
- * @folder: filename of the folder to add
+ * @folder: (type filename): filename of the folder to add
  * @error: (allow-none): location to store error, or %NULL
  * 
  * Adds a folder to be displayed with the shortcut folders in a file chooser.
@@ -2310,7 +2313,7 @@ gtk_file_chooser_add_shortcut_folder (GtkFileChooser    *chooser,
 /**
  * gtk_file_chooser_remove_shortcut_folder:
  * @chooser: a #GtkFileChooser
- * @folder: filename of the folder to remove
+ * @folder: (type filename): filename of the folder to remove
  * @error: (allow-none): location to store error, or %NULL
  * 
  * Removes a folder from a file chooser's list of shortcut folders.
@@ -2347,8 +2350,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().
  *
- * 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
+ * Return value: (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
@@ -2444,9 +2448,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().
  *
- * 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().
+ * 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().
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtkfilefilter.h b/gtk/gtkfilefilter.h
index c566ef1..02e2775 100644
--- a/gtk/gtkfilefilter.h
+++ b/gtk/gtkfilefilter.h
@@ -58,7 +58,7 @@ typedef enum {
  * GtkFileFilterFunc:
  * @filter_info: a #GtkFileFilterInfo that is filled according
  *   to the @needed flags passed to gtk_file_filter_add_custom()
- * @data: user data passed to gtk_file_filter_add_custom()
+ * @data: (closure): user data passed to gtk_file_filter_add_custom()
  *
  * The type of function that is used with custom filters, see
  * gtk_file_filter_add_custom().
diff --git a/gtk/gtkhsv.c b/gtk/gtkhsv.c
index 62356bc..427a7d5 100644
--- a/gtk/gtkhsv.c
+++ b/gtk/gtkhsv.c
@@ -1330,9 +1330,9 @@ gtk_hsv_set_color (GtkHSV *hsv,
 /**
  * gtk_hsv_get_color:
  * @hsv: An HSV color selector
- * @h: Return value for the hue
- * @s: Return value for the saturation
- * @v: Return value for the value
+ * @h: (out): Return value for the hue
+ * @s: (out): Return value for the saturation
+ * @v: (out): Return value for the value
  *
  * Queries the current color in an HSV color selector.
  * Returned values will be in the [0.0, 1.0] range.
@@ -1400,8 +1400,8 @@ gtk_hsv_set_metrics (GtkHSV *hsv,
 /**
  * gtk_hsv_get_metrics:
  * @hsv: An HSV color selector
- * @size: Return value for the diameter of the hue ring
- * @ring_width: Return value for the width of the hue ring
+ * @size: (out): Return value for the diameter of the hue ring
+ * @ring_width: (out): Return value for the width of the hue ring
  *
  * Queries the size and ring width of an HSV color selector.
  *
@@ -1457,9 +1457,9 @@ gtk_hsv_is_adjusting (GtkHSV *hsv)
  * @h: Hue
  * @s: Saturation
  * @v: Value
- * @r: Return value for the red component
- * @g: Return value for the green component
- * @b: Return value for the blue component
+ * @r: (out): Return value for the red component
+ * @g: (out): Return value for the green component
+ * @b: (out): Return value for the blue component
  *
  * Converts a color from HSV space to RGB.
  * Input values must be in the [0.0, 1.0] range; 
@@ -1496,9 +1496,9 @@ gtk_hsv_to_rgb (gdouble  h,
  * @r: Red
  * @g: Green
  * @b: Blue
- * @h: Return value for the hue component
- * @s: Return value for the saturation component
- * @v: Return value for the value component
+ * @h: (out): Return value for the hue component
+ * @s: (out): Return value for the saturation component
+ * @v: (out): Return value for the value component
  *
  * Converts a color from RGB space to HSV.
  * Input values must be in the [0.0, 1.0] range;
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]