From f94eab803b5b7193720ac9b32f182271437cf90a Mon Sep 17 00:00:00 2001 From: "Owen W. Taylor" Date: Wed, 16 Sep 2009 19:07:23 -0400 Subject: [PATCH] Add GObject Introspection annotations Add GObject Introspection annotations to methods where needed, in particular adding (transfer none) to return values that don't transfer ownership. st_texture_cache_get_actor() and st_texture_cache_get_texture() are annotated as (transfer none) since they return a newly created *floating* texture. https://bugzilla.gnome.org/show_bug.cgi?id=591245 --- src/st/st-bin.c | 2 +- src/st/st-clipboard.c | 4 ++-- src/st/st-entry.c | 4 ++-- src/st/st-label.c | 4 ++-- src/st/st-scroll-bar.c | 9 +++++++++ src/st/st-scroll-view.c | 16 ++++++++++++++++ src/st/st-scroll-view.h | 1 - src/st/st-scrollable.c | 8 ++++++++ src/st/st-stylable.c | 20 ++++++++++---------- src/st/st-style.c | 6 +++--- src/st/st-subtexture.c | 2 +- src/st/st-texture-cache.c | 6 +++--- src/st/st-texture-frame.c | 2 +- src/st/st-widget.c | 4 ++-- 14 files changed, 60 insertions(+), 28 deletions(-) diff --git a/src/st/st-bin.c b/src/st/st-bin.c index 005ed6bab..6ae322cf8 100644 --- a/src/st/st-bin.c +++ b/src/st/st-bin.c @@ -617,7 +617,7 @@ st_bin_set_child (StBin *bin, * * Retrieves a pointer to the child of @bin. * - * Return value: a #ClutterActor, or %NULL + * Return value: (transfer none): a #ClutterActor, or %NULL */ ClutterActor * st_bin_get_child (StBin *bin) diff --git a/src/st/st-clipboard.c b/src/st/st-clipboard.c index c6507c141..d166a86fe 100644 --- a/src/st/st-clipboard.c +++ b/src/st/st-clipboard.c @@ -285,8 +285,8 @@ st_clipboard_x11_event_filter (XEvent *xev, * * Get the global #StClipboard object that represents the clipboard. * - * Returns: a #StClipboard owned by St and must not be unrefferenced or - * freed. + * Returns: (transfer none): a #StClipboard owned by St and must not be + * unrefferenced or freed. */ StClipboard* st_clipboard_get_default (void) diff --git a/src/st/st-entry.c b/src/st/st-entry.c index 20151bfc8..77816911f 100644 --- a/src/st/st-entry.c +++ b/src/st/st-entry.c @@ -810,8 +810,8 @@ st_entry_set_text (StEntry *entry, * * Retrieve the internal #ClutterText so that extra parameters can be set * - * Returns: the #ClutterText used by #StEntry. The entry is owned by the - * #StEntry and should not be unref'ed by the application. + * Returns: (transfer none): ethe #ClutterText used by #StEntry. The entry is + * owned by the #StEntry and should not be unref'ed by the application. */ ClutterActor* st_entry_get_clutter_text (StEntry *entry) diff --git a/src/st/st-label.c b/src/st/st-label.c index bcfcac603..6d1151f96 100644 --- a/src/st/st-label.c +++ b/src/st/st-label.c @@ -351,8 +351,8 @@ st_label_set_text (StLabel *label, * * Retrieve the internal #ClutterText so that extra parameters can be set * - * Returns: the #ClutterText used by #StLabel. The label is owned by the - * #StLabel and should not be unref'ed by the application. + * Returns: (transfer none): ethe #ClutterText used by #StLabel. The label + * is owned by the #StLabel and should not be unref'ed by the application. */ ClutterActor* st_label_get_clutter_text (StLabel *label) diff --git a/src/st/st-scroll-bar.c b/src/st/st-scroll-bar.c index ad636dfc2..414c6e685 100644 --- a/src/st/st-scroll-bar.c +++ b/src/st/st-scroll-bar.c @@ -1095,6 +1095,15 @@ st_scroll_bar_set_adjustment (StScrollBar *bar, } } +/** + * st_scroll_bar_get_adjustment: + * @bar: a #StScrollbar + * + * Gets the adjustment object that stores the current position + * of the scrollbar. + * + * Return value: (transfer none): the adjustment + */ StAdjustment * st_scroll_bar_get_adjustment (StScrollBar *bar) { diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c index 8f4332f45..c6c64b3ce 100644 --- a/src/st/st-scroll-view.c +++ b/src/st/st-scroll-view.c @@ -709,6 +709,14 @@ st_scroll_view_new (void) return g_object_new (ST_TYPE_SCROLL_VIEW, NULL); } +/** + * st_scroll_view_get_hscroll_bar: + * @scroll: a #StScrollView + * + * Gets the horizontal scrollbar of the scrollbiew + * + * Return value: (transfer none): the horizontal #StScrollbar + */ ClutterActor * st_scroll_view_get_hscroll_bar (StScrollView *scroll) { @@ -717,6 +725,14 @@ st_scroll_view_get_hscroll_bar (StScrollView *scroll) return scroll->priv->hscroll; } +/** + * st_scroll_view_get_vscroll_bar: + * @scroll: a #StScrollView + * + * Gets the vertical scrollbar of the scrollbiew + * + * Return value: (transfer none): the vertical #StScrollbar + */ ClutterActor * st_scroll_view_get_vscroll_bar (StScrollView *scroll) { diff --git a/src/st/st-scroll-view.h b/src/st/st-scroll-view.h index c2a3553fb..774fc05fd 100644 --- a/src/st/st-scroll-view.h +++ b/src/st/st-scroll-view.h @@ -70,7 +70,6 @@ StWidget *st_scroll_view_new (void); ClutterActor *st_scroll_view_get_hscroll_bar (StScrollView *scroll); ClutterActor *st_scroll_view_get_vscroll_bar (StScrollView *scroll); -ClutterActor *st_scroll_view_get_child (StScrollView *scroll); gfloat st_scroll_view_get_column_size (StScrollView *scroll); void st_scroll_view_set_column_size (StScrollView *scroll, diff --git a/src/st/st-scrollable.c b/src/st/st-scrollable.c index 1c3fc7b2f..384ac4b6b 100644 --- a/src/st/st-scrollable.c +++ b/src/st/st-scrollable.c @@ -77,6 +77,14 @@ st_scrollable_set_adjustments (StScrollable *scrollable, vadjustment); } +/** + * st_scroll_bar_get_adjustments: + * @hadjustment: (transfer none) (out) (allow-none): location to store the horizontal adjustment, or %NULL + * @vadjustment: (transfer none) (out) (allow-none): location to store the vertical adjustment, or %NULL + * + * Gets the adjustment objects that store the offsets of the scrollable widget + * into its possible scrolling area. + */ void st_scrollable_get_adjustments (StScrollable *scrollable, StAdjustment **hadjustment, diff --git a/src/st/st-stylable.c b/src/st/st-stylable.c index 1af8788a5..6d23deeda 100644 --- a/src/st/st-stylable.c +++ b/src/st/st-stylable.c @@ -337,12 +337,12 @@ st_stylable_iface_install_property (StStylableIface *iface, /** * st_stylable_list_properties: * @stylable: a #StStylable - * @n_props: return location for the number of properties, or %NULL + * @n_props: (out): return location for the number of properties, or %NULL * * Retrieves all the #GParamSpecs installed by @stylable. * - * Return value: an array of #GParamSpecs. Free it with - * g_free() when done. + * Return value: (transfer container) (array length=n_props): an array + * of #GParamSpecs. Free it with g_free() when done. */ GParamSpec ** st_stylable_list_properties (StStylable *stylable, @@ -370,8 +370,8 @@ st_stylable_list_properties (StStylable *stylable, * Finds the #GParamSpec installed by @stylable for the property * with @property_name. * - * Return value: a #GParamSpec for the given property, or %NULL if - * no property with that name was found + * Return value: (transfer none): a #GParamSpec for the given property, + * or %NULL if no property with that name was found */ GParamSpec * st_stylable_find_property (StStylable *stylable, @@ -413,7 +413,7 @@ st_stylable_get_property_internal (StStylable *stylable, * st_stylable_get_property: * @stylable: a #StStylable * @property_name: the name of the property - * @value: return location for an empty #GValue + * @value: (out): return location for an empty #GValue * * Retrieves the value of @property_name for @stylable, and puts it * into @value. @@ -514,7 +514,7 @@ st_stylable_get (StStylable *stylable, * st_stylable_get_default_value: * @stylable: a #StStylable * @property_name: name of the property to query - * @value_out: return location for the default value + * @value_out: (out): return location for the default value * * Query @stylable for the default value of property @property_name and * fill @value_out with the result. @@ -559,7 +559,7 @@ st_stylable_get_default_value (StStylable *stylable, * Retrieves the #StStyle used by @stylable. This function does not * alter the reference count of the returned object. * - * Return value: a #StStyle + * Return value: (transfer none): a #StStyle */ StStyle * st_stylable_get_style (StStylable *stylable) @@ -624,7 +624,7 @@ st_stylable_set_style (StStylable *stylable, * * Obtain the parent #StStylable that contains @stylable. * - * Return value: The parent #StStylable + * Return value: (transfer none): The parent #StStylable */ StStylable* st_stylable_get_container (StStylable *stylable) @@ -647,7 +647,7 @@ st_stylable_get_container (StStylable *stylable) * * Get the parent ancestor #StStylable of @stylable. * - * Return value: the parent #StStylable + * Return value: (transfer none): the parent #StStylable */ StStylable* st_stylable_get_base_style (StStylable *stylable) diff --git a/src/st/st-style.c b/src/st/st-style.c index 15e74a675..3e9619a66 100644 --- a/src/st/st-style.c +++ b/src/st/st-style.c @@ -356,8 +356,8 @@ st_style_new (void) * Return the default StStyle object. This includes the current theme (if * any). * - * Returns: a #StStyle object. This must not be freed or unref'd by - * applications + * Returns: (transfer none): a #StStyle object. This must not be freed or + * unref'd by applications */ StStyle * st_style_get_default (void) @@ -625,7 +625,7 @@ st_style_get_ccss_query (StStyle *style, * @style: the style data store object * @stylable: a stylable to retreive the data for * @pspec: a #GParamSpec describing the property required - * @value: a #GValue to place the return value in + * @value: (out): a #GValue to place the return value in * * Requests the property described in @pspec for the specified stylable */ diff --git a/src/st/st-subtexture.c b/src/st/st-subtexture.c index 7ea1fa4b6..1bcd896c9 100644 --- a/src/st/st-subtexture.c +++ b/src/st/st-subtexture.c @@ -457,7 +457,7 @@ st_subtexture_new (ClutterTexture *texture, * * Return the texture used by the #StSubtexture * - * Returns: a #ClutterTexture owned by the #StSubtexture + * Returns: (transfer none): a #ClutterTexture owned by the #StSubtexture */ ClutterTexture * st_subtexture_get_parent_texture (StSubtexture *frame) diff --git a/src/st/st-texture-cache.c b/src/st/st-texture-cache.c index 0cab32c32..dea1beeaa 100644 --- a/src/st/st-texture-cache.c +++ b/src/st/st-texture-cache.c @@ -169,7 +169,7 @@ st_texture_cache_init (StTextureCache *self) * Returns the default texture cache. This is owned by St and should not be * unreferenced or freed. * - * Returns: a StTextureCache + * Returns: (transfer none): a StTextureCache */ StTextureCache* st_texture_cache_get_default (void) @@ -243,7 +243,7 @@ add_texture_to_cache (StTextureCache *self, * the same image path will return a new ClutterTexture with the previously * loaded image. * - * Returns: a newly created ClutterTexture + * Returns: (transfer none): a newly created ClutterTexture */ ClutterTexture* st_texture_cache_get_texture (StTextureCache *self, @@ -317,7 +317,7 @@ st_texture_cache_get_texture (StTextureCache *self, * * Use this function if all you need is an actor for drawing. * - * Returns: a newly created ClutterTexture + * Returns: (transfer none): a newly created ClutterTexture */ ClutterActor* st_texture_cache_get_actor (StTextureCache *self, diff --git a/src/st/st-texture-frame.c b/src/st/st-texture-frame.c index 75d34308a..916216934 100644 --- a/src/st/st-texture-frame.c +++ b/src/st/st-texture-frame.c @@ -501,7 +501,7 @@ st_texture_frame_new (ClutterTexture *texture, * * Return the texture used by the #StTextureFrame * - * Returns: a #ClutterTexture owned by the #StTextureFrame + * Returns: (transfer none): a #ClutterTexture owned by the #StTextureFrame */ ClutterTexture * st_texture_frame_get_parent_texture (StTextureFrame *frame) diff --git a/src/st/st-widget.c b/src/st/st-widget.c index bcc4a2cf2..a27d9d0d6 100644 --- a/src/st/st-widget.c +++ b/src/st/st-widget.c @@ -1122,7 +1122,7 @@ st_widget_ensure_style (StWidget *widget) * "border-image" CSS property. This function should normally only be used * by subclasses. * - * Returns: #ClutterActor + * Returns: (transfer none): #ClutterActor */ ClutterActor * st_widget_get_border_image (StWidget *actor) @@ -1139,7 +1139,7 @@ st_widget_get_border_image (StWidget *actor) * "background-image" CSS property. This function should normally only be used * by subclasses. * - * Returns: a #ClutterActor + * Returns: (transfer none): a #ClutterActor */ ClutterActor * st_widget_get_background_image (StWidget *actor)