[gtk+/gi-annotations: 25/31] Update GI annotations in 'Abstract Base Classes'



commit afc11a134007bead458938291d149cb479086386
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Sun Jan 16 16:13:45 2011 +0100

    Update GI annotations in 'Abstract Base Classes'
    
    Abstract Base Classes group from GTK+ manual are: GtkWidget,
    GtkContainer, GtkBin, GtkMenuShell, GtkMisc, GtkRange, GtkIMContext

 gtk/gtkcontainer.c |   20 +++++++++++---------
 gtk/gtkcontainer.h |    2 +-
 gtk/gtkimcontext.c |   24 ++++++++++++------------
 gtk/gtkmenushell.c |    4 ++--
 gtk/gtkmisc.c      |   10 ++++++----
 gtk/gtkrange.c     |    8 +++++---
 gtk/gtkwidget.c    |   16 +++++++++-------
 7 files changed, 46 insertions(+), 38 deletions(-)
---
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index cd400b3..d1c8c2a 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1196,10 +1196,10 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
 
 /**
  * gtk_container_class_find_child_property:
- * @cclass: a #GtkContainerClass
+ * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @property_name: the name of the child property to find
- * @returns: (allow-none): the #GParamSpec of the child property or %NULL if @class has no
- *   child property with that name.
+ * @returns: (transfer none): the #GParamSpec of the child property or
+ *           %NULL if @class has no child property with that name.
  *
  * Finds a child property of a container class by name.
  */
@@ -1218,10 +1218,11 @@ gtk_container_class_find_child_property (GObjectClass *cclass,
 
 /**
  * gtk_container_class_list_child_properties:
- * @cclass: a #GtkContainerClass
+ * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @n_properties: location to return the number of child properties found
- * @returns: a newly allocated %NULL-terminated array of #GParamSpec*.
- *           The array must be freed with g_free().
+ * @returns: (array length=n_properties) (transfer container): a newly
+ *           allocated %NULL-terminated array of #GParamSpec*.  The
+ *           array must be freed with g_free().
  *
  * Returns all child properties of a container class.
  */
@@ -1865,7 +1866,7 @@ gtk_container_class_handle_border_width (GtkContainerClass *klass)
 /**
  * gtk_container_forall:
  * @container: a #GtkContainer
- * @callback: a callback
+ * @callback: (scope call): a callback
  * @callback_data: callback user data
  *
  * Invokes @callback on each child of @container, including children
@@ -1951,8 +1952,9 @@ gtk_container_set_focus_child (GtkContainer *container,
  * currently focused widget. That can be obtained by calling
  * gtk_window_get_focus().
  *
- * Returns: The child widget which will recieve the focus inside @container when
- *          the @conatiner is focussed, or %NULL if none is set.
+ * Returns: (transfer none): The child widget which will receive the
+ *          focus inside @container when the @conatiner is focussed,
+ *          or %NULL if none is set.
  *
  * Since: 2.14
  **/
diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h
index 2498513..b21e2d8 100644
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -72,7 +72,7 @@ struct _GtkContainerClass
 				 GtkCallback	  callback,
 				 gpointer	  callback_data);
   void    (*set_focus_child)	(GtkContainer	 *container,
-				 GtkWidget	 *widget);
+				 GtkWidget	 *child);
   GType   (*child_type)		(GtkContainer	 *container);
   gchar*  (*composite_name)	(GtkContainer	 *container,
 				 GtkWidget	 *child);
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 245c59b..3569ba7 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -419,12 +419,12 @@ gtk_im_context_set_client_window (GtkIMContext *context,
 /**
  * gtk_im_context_get_preedit_string:
  * @context:    a #GtkIMContext
- * @str:        location to store the retrieved string. The
- *              string retrieved must be freed with g_free ().
- * @attrs:      location to store the retrieved attribute list.
- *              When you are done with this list, you must
- *              unreference it with pango_attr_list_unref().
- * @cursor_pos: location to store position of cursor (in characters)
+ * @str:        (out) (transfer full): location to store the retrieved
+ *              string. The string retrieved must be freed with g_free().
+ * @attrs:      (out) (transfer full): location to store the retrieved
+ *              attribute list.  When you are done with this list, you
+ *              must unreference it with pango_attr_list_unref().
+ * @cursor_pos: (out): location to store position of cursor (in characters)
  *              within the preedit string.  
  * 
  * Retrieve the current preedit string for the input context,
@@ -620,12 +620,12 @@ gtk_im_context_set_surrounding (GtkIMContext  *context,
 /**
  * gtk_im_context_get_surrounding:
  * @context: a #GtkIMContext
- * @text: location to store a UTF-8 encoded string of text
- *        holding context around the insertion point.
- *        If the function returns %TRUE, then you must free
- *        the result stored in this location with g_free().
- * @cursor_index: location to store byte index of the insertion cursor
- *        within @text.
+ * @text: (out) (transfer full): location to store a UTF-8 encoded
+ *        string of text holding context around the insertion point.
+ *        If the function returns %TRUE, then you must free the result
+ *        stored in this location with g_free().
+ * @cursor_index: (out) location to store byte index of the insertion
+ *        cursor within @text.
  * 
  * Retrieves context around the insertion point. Input methods
  * typically want context in order to constrain input text based on
diff --git a/gtk/gtkmenushell.c b/gtk/gtkmenushell.c
index 172b576..f210cab 100644
--- a/gtk/gtkmenushell.c
+++ b/gtk/gtkmenushell.c
@@ -1990,7 +1990,7 @@ gtk_menu_shell_set_take_focus (GtkMenuShell *menu_shell,
  *
  * Gets the currently selected item.
  *
- * Returns: the currently selected item
+ * Returns: (transfer none): the currently selected item
  *
  * Since: 3.0
  */
@@ -2011,7 +2011,7 @@ gtk_menu_shell_get_selected_item (GtkMenuShell *menu_shell)
  * The parent menu shell of a submenu is the #GtkMenu or #GtkMenuBar
  * from which it was opened up.
  *
- * Returns: the parent #GtkMenuShell
+ * Returns: (transfer none): the parent #GtkMenuShell
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkmisc.c b/gtk/gtkmisc.c
index bc24ae6..c35bd73 100644
--- a/gtk/gtkmisc.c
+++ b/gtk/gtkmisc.c
@@ -239,8 +239,8 @@ gtk_misc_set_alignment (GtkMisc *misc,
 /**
  * gtk_misc_get_alignment:
  * @misc: a #GtkMisc
- * @xalign: (allow-none): location to store X alignment of @misc, or %NULL
- * @yalign: (allow-none): location to store Y alignment of @misc, or %NULL
+ * @xalign: (out) (allow-none): location to store X alignment of @misc, or %NULL
+ * @yalign: (out) (allow-none): location to store Y alignment of @misc, or %NULL
  *
  * Gets the X and Y alignment of the widget within its allocation. 
  * See gtk_misc_set_alignment().
@@ -300,8 +300,10 @@ gtk_misc_set_padding (GtkMisc *misc,
 /**
  * gtk_misc_get_padding:
  * @misc: a #GtkMisc
- * @xpad: (allow-none): location to store padding in the X direction, or %NULL
- * @ypad: (allow-none): location to store padding in the Y direction, or %NULL
+ * @xpad: (out) (allow-none): location to store padding in the X
+ *        direction, or %NULL
+ * @ypad: (out) (allow-none): location to store padding in the Y
+ *        direction, or %NULL
  *
  * Gets the padding in the X and Y directions of the widget. 
  * See gtk_misc_set_padding().
diff --git a/gtk/gtkrange.c b/gtk/gtkrange.c
index 91431e1..5d67ae3 100644
--- a/gtk/gtkrange.c
+++ b/gtk/gtkrange.c
@@ -1030,7 +1030,7 @@ gtk_range_get_min_slider_size (GtkRange *range)
 /**
  * gtk_range_get_range_rect:
  * @range: a #GtkRange
- * @range_rect: return location for the range rectangle
+ * @range_rect: (out): return location for the range rectangle
  *
  * This function returns the area that contains the range's trough
  * and its steppers, in widget->window coordinates.
@@ -1058,8 +1058,10 @@ gtk_range_get_range_rect (GtkRange     *range,
 /**
  * gtk_range_get_slider_range:
  * @range: a #GtkRange
- * @slider_start: (allow-none): return location for the slider's start, or %NULL
- * @slider_end: (allow-none): return location for the slider's end, or %NULL
+ * @slider_start: (out) (allow-none): return location for the slider's
+ *     start, or %NULL
+ * @slider_end: (out) (allow-none): return location for the slider's
+ *     end, or %NULL
  *
  * This function returns sliders range along the long dimension,
  * in widget->window coordinates.
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 40ec604..fd51eeb 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -4719,7 +4719,7 @@ gtk_widget_queue_shallow_draw (GtkWidget *widget)
 /**
  * gtk_widget_size_allocate:
  * @widget: a #GtkWidget
- * @allocation: (inout): position and size to be allocated to @widget
+ * @allocation: position and size to be allocated to @widget
  *
  * This function is only used by #GtkContainer subclasses, to assign a size
  * and position to their child widgets.
@@ -11459,7 +11459,7 @@ gtk_widget_input_shape_combine_region (GtkWidget *widget,
  */
 
 /**
- * gtk_widget_class_install_style_property_parser:
+ * gtk_widget_class_install_style_property_parser: (skip)
  * @klass: a #GtkWidgetClass
  * @pspec: the #GParamSpec for the style property
  * @parser: the parser for the style property
@@ -11515,8 +11515,8 @@ gtk_widget_class_install_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_find_style_property:
  * @klass: a #GtkWidgetClass
  * @property_name: the name of the style property to find
- * @returns: (allow-none): the #GParamSpec of the style property or %NULL if @class has no
- *   style property with that name.
+ * @returns: (transfer none): the #GParamSpec of the style property or
+ *   %NULL if @class has no style property with that name.
  *
  * Finds a style property of a widget class by name.
  *
@@ -11537,9 +11537,11 @@ gtk_widget_class_find_style_property (GtkWidgetClass *klass,
 /**
  * gtk_widget_class_list_style_properties:
  * @klass: a #GtkWidgetClass
- * @n_properties: location to return the number of style properties found
- * @returns: an newly allocated array of #GParamSpec*. The array must
- *       be freed with g_free().
+ * @n_properties: (out): location to return the number of style properties
+ *       found
+ * @returns: (array length=n_properties) (transfer container): an
+ *       newly allocated array of #GParamSpec*. The array must be
+ *       freed with g_free().
  *
  * Returns all style properties of a widget class.
  *



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]