From 465bffcf7d10122b57406a7f2ff3ee034c0b531f Mon Sep 17 00:00:00 2001 From: Daniel Kolesa Date: Thu, 30 Jul 2015 13:16:05 +0100 Subject: [PATCH] evas textblock: convert docs --- src/lib/evas/canvas/evas_textblock.eo | 333 ++++++++++++++++------------------ 1 file changed, 158 insertions(+), 175 deletions(-) diff --git a/src/lib/evas/canvas/evas_textblock.eo b/src/lib/evas/canvas/evas_textblock.eo index 3832e50..6c5231b 100644 --- a/src/lib/evas/canvas/evas_textblock.eo +++ b/src/lib/evas/canvas/evas_textblock.eo @@ -9,120 +9,109 @@ class Evas.Textblock (Evas.Object) methods { @property text_markup { set { - /*@ - Sets the tetxblock's text to the markup text. + [[Sets the tetxblock's text to the markup text. - @note assumes text does not include the unicode object replacement char (0xFFFC) - - @return Return no value. */ + Note: assumes text does not include the unicode object + replacement char (0xFFFC) + ]] } get { - /*@ - Return the markup of the object. - - @return the markup text of the object. */ + [[Get the markup of the object.]] } values { - text: const(char)*; /*@ the markup text to use. */ + text: const(char)*; [[The markup text to use.]] } } @property valign { set { - /*@ - @brief Sets the vertical alignment of text within the textblock object - as a whole. + [[Sets the vertical alignment of text within the textblock object + as a whole. - Normally alignment is 0.0 (top of object). Values given should be - between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered - etc.). + Normally alignment is 0.0 (top of object). Values given should + be between 0.0 and 1.0 (1.0 bottom of object, 0.5 being + vertically centered etc.). - @since 1.1 */ + @since 1.1 + ]] } get { - /*@ - @brief Gets the vertical alignment of a textblock + [[Gets the vertical alignment of a textblock - @return The alignment set for the object. - @since 1.1 */ + @since 1.1 + ]] } values { - align: double; /*@ A value between @c 0.0 and @c 1.0. */ + align: double; [[The alignment set for the object.]] } } @property bidi_delimiters { set { - /*@ - @brief Sets the BiDi delimiters used in the textblock. + [[Sets the BiDi delimiters used in the textblock. - BiDi delimiters are use for in-paragraph separation of bidi segments. This - is useful for example in recipients fields of e-mail clients where bidi - oddities can occur when mixing RTL and LTR. + BiDi delimiters are use for in-paragraph separation of bidi + segments. This is useful for example in recipients fields of + e-mail clients where bidi oddities can occur when mixing RTL + and LTR. - @since 1.1 */ + @since 1.1 + ]] } get { - /*@ - @brief Gets the BiDi delimiters used in the textblock. + [[Gets the BiDi delimiters used in the textblock. - BiDi delimiters are use for in-paragraph separation of bidi segments. This - is useful for example in recipients fields of e-mail clients where bidi - oddities can occur when mixing RTL and LTR. + BiDi delimiters are use for in-paragraph separation of bidi + segments. This is useful for example in recipients fields of + e-mail clients where bidi oddities can occur when mixing RTL + and LTR. - @return A null terminated string of delimiters, e.g ",|". If empty, returns - @c NULL. - @since 1.1 */ + @since 1.1 + ]] } values { - delim: const(char)*; /*@ A null terminated string of delimiters, e.g ",|". */ + delim: const(char)*; [[A null terminated string of delimiters, e.g ",|" or $null if empty.]] } } @property replace_char { set { - /*@ - @brief Set the "replacement character" to use for the given textblock object. */ + [[Set the "replacement character" to use for the given textblock object.]] } values { - ch: const(char)*; /*@ The charset name. */ + ch: const(char)*; [[The charset name.]] } } @property legacy_newline { set { - /*@ - @brief Sets newline mode. When true, newline character will behave - as a paragraph separator. + [[Sets newline mode. When true, newline character will behave + as a paragraph separator. - @since 1.1 */ + @since 1.1 + ]] } get { - /*@ - @brief Gets newline mode. When true, newline character behaves - as a paragraph separator. + [[Gets newline mode. When true, newline character behaves + as a paragraph separator. - @return @c EINA_TRUE if in legacy mode, @c EINA_FALSE otherwise. - @since 1.1 */ + @since 1.1 + ]] } values { - mode: bool; /*@ @c EINA_TRUE for legacy mode, @c EINA_FALSE otherwise. */ + mode: bool; [[$true for legacy mode, $false otherwise.]] } } @property style { set { - /*@ - Set the objects style to ts. - @return Returns no value. */ + [[Set the objects style to $ts.]] } get { - /*@ - Return the style of an object. - @return the style of the object. */ + [[Get the style of an object.]] } values { - ts: const(Evas.Textblock.Style)*; /*@ the style to set. */ + ts: const(Evas.Textblock.Style)*; [[The style.]] } } @property node_format_first { get { - /*@ Returns the first format node. */ + [[Gets the first format node.]] legacy: evas_textblock_node_format_first_get; } values { @@ -131,32 +120,32 @@ class Evas.Textblock (Evas.Object) } @property size_formatted { get { - /*@ - Get the formatted width and height. This calculates the actual size after restricting - the textblock to the current size of the object. - The main difference between this and @ref evas_object_textblock_size_native_get - is that the "native" function does not wrapping into account - it just calculates the real width of the object if it was placed on an - infinite canvas, while this function gives the size after wrapping - according to the size restrictions of the object. + [[Get the formatted width and height. - For example for a textblock containing the text: "You shall not pass!" - with no margins or padding and assuming a monospace font and a size of - 7x10 char widths (for simplicity) has a native size of 19x1 - and a formatted size of 5x4. + This calculates the actual size after restricting the + textblock to the current size of the object. + The main difference between this and @.size_native.get + is that the "native" function does not wrapping into account + it just calculates the real width of the object if it was + placed on an infinite canvas, while this function gives the + size after wrapping according to the size restrictions of the + object. - @return Returns no value. - @see evas_object_textblock_size_native_get */ + For example for a textblock containing the text: + "You shall not pass!" with no margins or padding and assuming + a monospace font and a size of 7x10 char widths (for simplicity) + has a native size of 19x1 and a formatted size of 5x4. + ]] } values { - w: Evas.Coord; /*@ the width of the object. */ - h: Evas.Coord; /*@ the height of the object */ + w: Evas.Coord; [[The width of the object.]] + h: Evas.Coord; [[The height of the object.]] } } @property node_format_last { get { - /*@ Returns the last format node. */ + [[Gets the last format node.]] legacy: evas_textblock_node_format_last_get; } values { @@ -165,40 +154,37 @@ class Evas.Textblock (Evas.Object) } @property cursor { get { - /*@ - Return the object's main cursor. - - @return The @p obj's main cursor. */ + [[Get the object's main cursor.]] return: Evas.Textblock.Cursor *; } } @property size_native { get { - /*@ - Get the native width and height. This calculates the actual size without taking account - the current size of the object. - The main difference between this and @ref evas_object_textblock_size_formatted_get - is that the "native" function does not take wrapping into account - it just calculates the real width of the object if it was placed on an - infinite canvas, while the "formatted" function gives the size after - wrapping text according to the size restrictions of the object. - - For example for a textblock containing the text: "You shall not pass!" - with no margins or padding and assuming a monospace font and a size of - 7x10 char widths (for simplicity) has a native size of 19x1 - and a formatted size of 5x4. - - @return Returns no value. */ + [[Get the native width and height. + + This calculates the actual size without taking account the + current size of the object. + + The main difference between this and @.size_formatted.get + is that the "native" function does not take wrapping into + account it just calculates the real width of the object if + it was placed on an infinite canvas, while the "formatted" + function gives the size after wrapping text according to + the size restrictions of the object. + + For example for a textblock containing the text: + "You shall not pass!" with no margins or padding and assuming + a monospace font and a size of 7x10 char widths (for simplicity) + has a native size of 19x1 and a formatted size of 5x4. + ]] } values { - w: Evas.Coord; /*@ the width returned */ - h: Evas.Coord; /*@ the height returned */ + w: Evas.Coord; [[The width returned.]] + h: Evas.Coord; [[The height returned.]] } } @property style_insets { - get { - /*@ No description supplied by the EAPI. */ - } + get {} values { l: Evas.Coord; r: Evas.Coord; @@ -207,49 +193,46 @@ class Evas.Textblock (Evas.Object) } } line_number_geometry_get @const { - /*@ - Get the geometry of a line number. - - @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. */ - return: bool; + [[Get the geometry of a line number.]] + return: bool; [[$true on success, $false otherwise.]] params { - @in line: int; /*@ the line number. */ - @out cx: Evas.Coord; /*@ x coord of the line. */ - @out cy: Evas.Coord; /*@ y coord of the line. */ - @out cw: Evas.Coord; /*@ w coord of the line. */ - @out ch: Evas.Coord; /*@ h coord of the line. */ + @in line: int; [[The line number.]] + @out cx: Evas.Coord; [[x coord of the line.]] + @out cy: Evas.Coord; [[y coord of the line.]] + @out cw: Evas.Coord; [[w coord of the line.]] + @out ch: Evas.Coord; [[h coord of the line.]] } } replace_char_get { - /*@ - @brief Get the "replacement character" for given textblock object. Returns - @c NULL if no replacement character is in use. - - @return Replacement character or @c NULL. */ + [[Get the "replacement character" for given textblock object. - return: const(char)*; + Returns $null if no replacement character is in use. + ]] + return: const(char)*; [[Replacement character or $null.]] } style_user_pop { - /*@ - Del the from the top of the user style stack. + [[Del the from the top of the user style stack. - @see evas_object_textblock_style_get - @since 1.2 */ + See also @.style.get. + @since 1.2 + ]] } cursor_new @const { - /*@ - Create a new cursor, associate it to the obj and init it to point - to the start of the textblock. Association to the object means the cursor - will be updated when the object will change. - - @note if you need speed and you know what you are doing, it's slightly faster to just allocate the cursor yourself and not associate it. (only people developing the actual object, and not users of the object). - - @return the new cursor. */ - return: Evas.Textblock.Cursor *; + [[Create a new cursor, associate it to the obj and init it to point + to the start of the textblock. + + Association to the object means the cursor will be updated when + the object will change. + + Note: if you need speed and you know what you are doing, it's + slightly faster to just allocate the cursor yourself and not + associate it. (only people developing the actual object, and + not users of the object). + ]] + return: Evas.Textblock.Cursor *; [[The new cursor.]] } node_format_list_get @const { - /*@ No description supplied by the EAPI. */ legacy: evas_textblock_node_format_list_get; return: const(list)*; params { @@ -257,85 +240,85 @@ class Evas.Textblock (Evas.Object) } } style_user_peek @const { - /*@ - Get (don't remove) the style at the top of the user style stack. + [[Get (don't remove) the style at the top of the user style stack. + + See also @.style.get. - @return the style of the object. - @see evas_object_textblock_style_get - @since 1.2 */ - return: const(Evas.Textblock.Style)*; + @since 1.2 + ]] + return: const(Evas.Textblock.Style)*; [[The style of the object.]] } node_format_remove_pair { - /*@ Remove a format node and its match. */ + [[Remove a format node and its match.]] legacy: evas_textblock_node_format_remove_pair; params { @in n: Evas.Textblock.Node_Format *; } } clear { - /*@ - Clear the textblock object. - @note Does *NOT* free the Evas object itself. - - @return nothing. */ + [[Clear the textblock object. + Note: Does *NOT* free the Evas object itself. + ]] legacy: null; } style_user_push { - /*@ - Push ts to the top of the user style stack. + [[Push ts to the top of the user style stack. + + FIXME: API is solid but currently only supports 1 style in the + stack. - FIXME: API is solid but currently only supports 1 style in the stack. + The user style overrides the corresponding elements of the + regular style. This is the proper way to do theme overrides + in code. - The user style overrides the corresponding elements of the regular style. - This is the proper way to do theme overrides in code. - @return Returns no value. - @see evas_object_textblock_style_set - @since 1.2 */ + See also @.style.set. + @since 1.2 + ]] params { - @in ts: Evas.Textblock.Style *; /*@ the style to set. */ + @in ts: Evas.Textblock.Style *; [[The style to set.]] } } obstacle_add { - /*@ - Add obstacle evas object @p eo_obs to be observed during layout of text. - The textblock does the layout of the text according to the position - of the obstacle. + [[Add obstacle evas object $eo_obs to be observed during layout + of text. - @return Returns true on success, false on failure. + The textblock does the layout of the text according to the + position of the obstacle. - @since 1.15 */ + @since 1.15 + ]] params { @in eo_obs: Evas.Object *; } - return: bool; + return: bool; [[$true on success, $false otherwise.]] } obstacle_del { - /*@ - Removes @p eo_obs from observation during text layout + [[Removes $eo_obs from observation during text layout. - @return Returns true on success, false on failure. - - @since 1.15 */ + @since 1.15 + ]] params { @in eo_obs: Evas.Object *; } - return: bool; + return: bool; [[$true on success, $false otherwise.]] } obstacles_update { - /*@ - Triggers for relayout due to obstacles' state change. The obstacles - alone don't affect the layout, until this is called. Use this after - doing changes (moving, positioning etc.) in the obstacles that you - would like to be considered in the layout. - For example: if you have just repositioned the obstacles to differrent - coordinates relative to the textblock, you need to call this so - it will consider this new state and will relayout the text. - - @return Returns no value. - - @since 1.15 */ + [[Triggers for relayout due to obstacles' state change. + + The obstacles alone don't affect the layout, until this is + called. Use this after doing changes (moving, positioning etc.) + in the obstacles that you would like to be considered in the + layout. + + For example: if you have just repositioned the obstacles to + differrent coordinates relative to the textblock, you need to + call this so it will consider this new state and will relayout + the text. + + @since 1.15 + ]] } } implements { -- 2.7.4