From e9c369f86d0eea327458cc4bd7b9bc750960a09f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 11 Dec 2008 12:17:11 +0000 Subject: [PATCH] Add documentation annotations ClutterText is heavily under-documented. This commit ports most of the API documentation from ClutterLabel and ClutterEntry to ClutterText. --- clutter/clutter-text.c | 192 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 4 deletions(-) diff --git a/clutter/clutter-text.c b/clutter/clutter-text.c index db5432896..886256844 100644 --- a/clutter/clutter-text.c +++ b/clutter/clutter-text.c @@ -1648,7 +1648,7 @@ clutter_text_class_init (ClutterTextClass *klass) /** * ClutterText::text-changed: - * @actor: the actor which received the event + * @self: the #ClutterText that emitted the signal * * The ::text-changed signal is emitted after @actor's text changes * @@ -1663,6 +1663,15 @@ clutter_text_class_init (ClutterTextClass *klass) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * ClutterText::cursor-event: + * @self: the #ClutterText that emitted the signal + * @geometry: the coordinates of the cursor + * + * FIXME + * + * Since: 1.0 + */ text_signals[CURSOR_EVENT] = g_signal_new ("cursor-event", G_TYPE_FROM_CLASS (gobject_class), @@ -1675,7 +1684,7 @@ clutter_text_class_init (ClutterTextClass *klass) /** * ClutterText::activate - * @actor: the actor which received the event + * @self: the #ClutterText that emitted the signal * * The ::activate signal is emitted each time the actor is 'activated' * by the user, normally by pressing the 'Enter' key. @@ -2076,6 +2085,18 @@ clutter_text_get_selection_bound (ClutterText *self) return self->priv->selection_bound; } +/** + * clutter_text_get_font_name: + * @self: a #ClutterText + * + * Retrieves the font name as set by clutter_text_set_font_name(). + * + * Return value: a string containing the font name. The returned + * string is owned by the #ClutterText actor and should not be + * modified or freed + * + * Since: 1.0 + */ G_CONST_RETURN gchar * clutter_text_get_font_name (ClutterText *text) { @@ -2084,6 +2105,23 @@ clutter_text_get_font_name (ClutterText *text) return text->priv->font_name; } +/** + * clutter_text_set_font_name: + * @self: a #ClutterText + * @font_name: a font name + * + * Sets the font used by a #ClutterText. The @font_name string + * must be something that can be parsed by the + * pango_font_description_from_string() function, like: + * + * |[ + * clutter_text_set_font_name (text, "Sans 10pt"); + * clutter_text_set_font_name (text, "Serif 16px"); + * clutter_text_set_font_name (text, "Helvetica 10"); + * ]| + * + * Since: 1.0 + */ void clutter_text_set_font_name (ClutterText *self, const gchar *font_name) @@ -2126,6 +2164,28 @@ clutter_text_set_font_name (ClutterText *self, g_object_notify (G_OBJECT (self), "font-name"); } +/** + * clutter_text_get_text: + * @self: a #ClutterText + * + * Retrieves a pointer to the current contents of a #ClutterText + * actor. + * + * If you need a copy of the contents for manipulating, either + * use g_strdup() on the returned string, or use: + * + * |[ + * copy = clutter_text_get_chars (text, 0, -1); + * ]| + * + * Which will return a newly allocated string. + * + * Return value: the contents of the actor. The returned string + * is owned by the #ClutterText actor and should never be + * modified or freed + * + * Since: 1.0 + */ G_CONST_RETURN gchar * clutter_text_get_text (ClutterText *self) { @@ -2134,6 +2194,15 @@ clutter_text_get_text (ClutterText *self) return self->priv->text; } +/** + * clutter_text_set_text: + * @self: a #ClutterText + * @text: the text to set + * + * Sets the contents of a #ClutterText actor. + * + * Since: 1.0 + */ void clutter_text_set_text (ClutterText *self, const gchar *text) @@ -2188,6 +2257,17 @@ clutter_text_set_text (ClutterText *self, g_object_notify (G_OBJECT (self), "text"); } +/** + * clutter_text_get_layout: + * @self: a #ClutterText + * + * Retrieves the current #PangoLayout used by a #ClutterText actor. + * + * Return value: a #PangoLayout. The returned object is owned by + * the #ClutterText actor and should not be modified or freed + * + * Since: 1.0 + */ PangoLayout * clutter_text_get_layout (ClutterText *self) { @@ -2200,6 +2280,20 @@ clutter_text_get_layout (ClutterText *self) return clutter_text_create_layout (self, width); } +/** + * clutter_text_set_color: + * @self: a #ClutterText + * @color: a #ClutterColor + * + * Sets the color of the contents of a #ClutterText actor. + * + * The overall opacity of the #ClutterText actor will be the + * result of the alpha value of @color and the composited + * opacity of the actor itself on the scenegraph, as returned + * by clutter_actor_get_paint_opacity(). + * + * Since: 1.0 + */ void clutter_text_set_color (ClutterText *self, const ClutterColor *color) @@ -2219,6 +2313,15 @@ clutter_text_set_color (ClutterText *self, g_object_notify (G_OBJECT (self), "color"); } +/** + * clutter_text_get_color: + * @self: a #ClutterText + * @color: return location for a #ClutterColor + * + * Retrieves the text color as set by clutter_text_get_color(). + * + * Since: 1.0 + */ void clutter_text_get_color (ClutterText *self, ClutterColor *color) @@ -2287,6 +2390,17 @@ clutter_text_get_ellipsize (ClutterText *self) return self->priv->ellipsize; } +/** + * clutter_text_get_line_wrap: + * @self: a #ClutterText + * + * Retrieves the value set using clutter_text_set_line_wrap(). + * + * Return value: %TRUE if the #ClutterText actor should wrap + * its contents + * + * Since: 1.0 + */ gboolean clutter_text_get_line_wrap (ClutterText *self) { @@ -2295,6 +2409,16 @@ clutter_text_get_line_wrap (ClutterText *self) return self->priv->wrap; } +/** + * clutter_text_set_line_wrap: + * @self: a #ClutterText + * @line_wrap: whether the contents should wrap + * + * Sets whether the contents of a #ClutterText actor should wrap, + * if they don't fit the size assigned to the actor. + * + * Since: 1.0 + */ void clutter_text_set_line_wrap (ClutterText *self, gboolean line_wrap) @@ -2555,7 +2679,7 @@ clutter_text_get_use_markup (ClutterText *self) * on both margins. This setting is ignored if Clutter is compiled * against Pango < 1.18. * - * Since: 0.6 + * Since: 1.0 */ void clutter_text_set_justify (ClutterText *self, @@ -2616,6 +2740,17 @@ clutter_text_get_cursor_position (ClutterText *self) return self->priv->position; } +/** + * clutter_text_set_cursor_position: + * @self: a #ClutterText + * @position: the new cursor position, in characters + * + * Sets the cursor of a #ClutterText actor at @position. + * + * The position is expressed in characters, not in bytes. + * + * Since: 1.0 + */ void clutter_text_set_cursor_position (ClutterText *self, gint position) @@ -2805,6 +2940,16 @@ clutter_text_get_max_length (ClutterText *self) return self->priv->max_length; } +/** + * clutter_text_insert_unichar: + * @self: a #ClutterText + * @wc: a Unicode character + * + * Inserts @wc at the current cursor position of a + * #ClutterText actor. + * + * Since: 1.0 + */ void clutter_text_insert_unichar (ClutterText *self, gunichar wc) @@ -2841,6 +2986,21 @@ clutter_text_insert_unichar (ClutterText *self, g_string_free (new, TRUE); } +/** + * clutter_text_insert_text: + * @self: a #ClutterText + * @text: the text to be inserted + * @position: the position of the insertion, or -1 + * + * Inserts @text into a #ClutterActor at the given position. + * + * If @position is a negative number, the text will be appended + * at the end of the current contents of the #ClutterText. + * + * The position is expressed in characters, not in bytes. + * + * Since: 1.0 + */ void clutter_text_insert_text (ClutterText *self, const gchar *text, @@ -2862,6 +3022,20 @@ clutter_text_insert_text (ClutterText *self, g_string_free (new, TRUE); } +/** + * clutter_text_delete_text: + * @self: a #ClutterText + * @start_pos: starting position + * @end_pos: ending position + * + * Deletes the text inside a #ClutterText actor between @start_pos + * and @end_pos. + * + * The starting and ending positions are expressed in characters, + * not in bytes. + * + * Since: 1.0 + */ void clutter_text_delete_text (ClutterText *self, gssize start_pos, @@ -2900,6 +3074,16 @@ clutter_text_delete_text (ClutterText *self, g_string_free (new, TRUE); } +/** + * clutter_text_delete_chars: + * @self: a #ClutterText + * @n_chars: the number of characters to delete + * + * Deletes @n_chars inside a #ClutterText actor, starting from the + * current cursor position. + * + * Since: 1.0 + */ void clutter_text_delete_chars (ClutterText *self, guint n_chars) @@ -2944,7 +3128,7 @@ clutter_text_delete_chars (ClutterText *self, /** * clutter_text_get_chars: - * @self: a #ClutterTex + * @self: a #ClutterText * @start_pos: start of text, in characters * @end_pos: end of text, in characters *