Textblock Object Functions
[Specific Object Functions]

Functions used to create and manipulate textblock objects. More...

Defines

#define ENFN   obj->layer->evas->engine.func

Functions

EAPI Evas_Object * evas_object_textblock_add (Evas *e)
 Adds a textblock to the given evas.
EAPI Evas_Textblock_Style * evas_textblock_style_new (void)
 Creates a new textblock style.
EAPI void evas_textblock_style_free (Evas_Textblock_Style *ts)
 Destroys a textblock style.
EAPI void evas_textblock_style_set (Evas_Textblock_Style *ts, const char *text)
 Sets the style ts to the style passed as text by text.
EAPI const char * evas_textblock_style_get (const Evas_Textblock_Style *ts)
 Return the text of the style ts.
EAPI void evas_object_textblock_style_set (Evas_Object *obj, Evas_Textblock_Style *ts)
 Set the objects style to ts.
EAPI const Evas_Textblock_Style * evas_object_textblock_style_get (const Evas_Object *obj)
 Return the style of an object.
EAPI void evas_object_textblock_replace_char_set (Evas_Object *obj, const char *ch)
 Set the "replacement character" to use for the given textblock object.
EAPI const char * evas_object_textblock_replace_char_get (Evas_Object *obj)
 Get the "replacement character" for given textblock object.
EAPI const char * evas_textblock_escape_string_get (const char *escape)
 Returns the unescaped version of escape.
EAPI const char * evas_textblock_escape_string_range_get (const char *escape_start, const char *escape_end)
 Return the unescaped version of the string between start and end.
EAPI const char * evas_textblock_string_escape_get (const char *string, int *len_ret)
 Returns the escaped version of the string.
EAPI void evas_object_textblock_text_markup_set (Evas_Object *obj, const char *text)
 Sets the tetxblock's text to the markup text.
EAPI void evas_object_textblock_text_markup_prepend (Evas_Textblock_Cursor *cur, const char *text)
 Prepends markup to the cursor cur.
EAPI const char * evas_object_textblock_text_markup_get (const Evas_Object *obj)
 Return the markup of the object.
EAPI const Evas_Textblock_Cursor * evas_object_textblock_cursor_get (const Evas_Object *obj)
 Return the object's main cursor.
EAPI Evas_Textblock_Cursor * evas_object_textblock_cursor_new (Evas_Object *obj)
 Create a new cursor, associate it to the obj and init it to point to the start of the textblock.
EAPI void evas_textblock_cursor_free (Evas_Textblock_Cursor *cur)
 Free the cursor and unassociate it from the object.
EAPI Eina_Bool evas_textblock_cursor_is_format (const Evas_Textblock_Cursor *cur)
 Returns true if the cursor points to a format.
EAPI const
Evas_Object_Textblock_Node_Format * 		evas_textblock_node_format_first_get (const Evas_Object *obj)
 Returns the first format node.
EAPI const
Evas_Object_Textblock_Node_Format * 		evas_textblock_node_format_last_get (const Evas_Object *obj)
 Returns the last format node.
EAPI const
Evas_Object_Textblock_Node_Format * 		evas_textblock_node_format_next_get (const Evas_Object_Textblock_Node_Format *n)
 Returns the next format node (after n).
EAPI const
Evas_Object_Textblock_Node_Format * 		evas_textblock_node_format_prev_get (const Evas_Object_Textblock_Node_Format *n)
 Returns the prev format node (after n).
EAPI void evas_textblock_node_format_remove_pair (Evas_Object *obj, Evas_Object_Textblock_Node_Format *n)
 Remove a format node and it's match.
EAPI void evas_textblock_cursor_paragraph_first (Evas_Textblock_Cursor *cur)
 Sets the cursor to the start of the first text node.
EAPI void evas_textblock_cursor_paragraph_last (Evas_Textblock_Cursor *cur)
 sets the cursor to the end of the last text node.
EAPI Eina_Bool evas_textblock_cursor_paragraph_next (Evas_Textblock_Cursor *cur)
 Advances to the the start of the next text node.
EAPI Eina_Bool evas_textblock_cursor_paragraph_prev (Evas_Textblock_Cursor *cur)
 Advances to the the end of the previous text node.
EAPI void evas_textblock_cursor_set_at_format (Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n)
 Sets the cursor to point to the place where format points to.
EAPI Eina_Bool evas_textblock_cursor_format_next (Evas_Textblock_Cursor *cur)
 Advances to the next format node.
EAPI Eina_Bool evas_textblock_cursor_format_prev (Evas_Textblock_Cursor *cur)
 Advances to the previous format node.
EAPI Eina_Bool evas_textblock_cursor_char_next (Evas_Textblock_Cursor *cur)
 Advances 1 char forward.
EAPI Eina_Bool evas_textblock_cursor_char_prev (Evas_Textblock_Cursor *cur)
 Advances 1 char backward.
EAPI void evas_textblock_cursor_paragraph_char_first (Evas_Textblock_Cursor *cur)
 Go to the first char in the node the cursor is pointing on.
EAPI void evas_textblock_cursor_paragraph_char_last (Evas_Textblock_Cursor *cur)
 Go to the last char in a text node.
EAPI void evas_textblock_cursor_line_char_first (Evas_Textblock_Cursor *cur)
 Go to the start of the current line.
EAPI void evas_textblock_cursor_line_char_last (Evas_Textblock_Cursor *cur)
 Go to the end of the current line.
EAPI int evas_textblock_cursor_pos_get (const Evas_Textblock_Cursor *cur)
 Return the current cursor pos.
EAPI void evas_textblock_cursor_pos_set (Evas_Textblock_Cursor *cur, int _pos)
 Set the cursor pos.
EAPI Eina_Bool evas_textblock_cursor_line_set (Evas_Textblock_Cursor *cur, int line)
 Go to the start of the line passed.
EAPI int evas_textblock_cursor_compare (const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2)
 Compare two cursors.
EAPI void evas_textblock_cursor_copy (const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest)
 Make cur_dest point to the same place as cur.
EAPI int evas_textblock_cursor_text_append (Evas_Textblock_Cursor *cur, const char *_text)
 Adds text to the current cursor position and set the cursor to *before* the start of the text just added.
EAPI int evas_textblock_cursor_text_prepend (Evas_Textblock_Cursor *cur, const char *_text)
 Adds text to the current cursor position and set the cursor to *after* the start of the text just added.
EAPI Eina_Bool evas_textblock_cursor_format_append (Evas_Textblock_Cursor *cur, const char *format)
 Adds format to the current cursor position.
EAPI Eina_Bool evas_textblock_cursor_format_prepend (Evas_Textblock_Cursor *cur, const char *format)
 Adds format to the current cursor position.
EAPI void evas_textblock_cursor_char_delete (Evas_Textblock_Cursor *cur)
 Delete the character at the location of the cursor.
EAPI void evas_textblock_cursor_range_delete (Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2)
 Delete the range between cur1 and cur2.
EAPI char * evas_textblock_cursor_content_get (const Evas_Textblock_Cursor *cur)
 Return the content of the cursor.
EAPI char * evas_textblock_cursor_range_text_get (const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *_cur2, Evas_Textblock_Text_Type format __UNUSED__)
 Return the text in the range between cur1 and cur2.
EAPI const char * evas_textblock_cursor_paragraph_text_get (const Evas_Textblock_Cursor *cur)
 Return the text of the paragraph cur points to - returns the text in markup.
EAPI int evas_textblock_cursor_paragraph_text_length_get (const Evas_Textblock_Cursor *cur)
 Return the length of the paragraph, cheaper the eina_unicode_strlen().
EAPI const
Evas_Object_Textblock_Node_Format * 		evas_textblock_cursor_format_get (const Evas_Textblock_Cursor *cur)
 Return the format node at the position pointed by cur.
EAPI const char * evas_textblock_node_format_text_get (const Evas_Object_Textblock_Node_Format *fmt)
 Get the text format representation of the format node.
EAPI void evas_textblock_cursor_at_format_set (Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt)
 Set the cursor to point to the position of fmt.
EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get (const Evas_Textblock_Cursor *cur)
 Check if the current cursor position is a visible format.
EAPI int evas_textblock_cursor_geometry_get (const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_BiDi_Direction *dir, Evas_Textblock_Cursor_Type ctype)
 Returns the geometry of the cursor.
EAPI int evas_textblock_cursor_char_geometry_get (const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch)
 Returns the geometry of the char at cur.
EAPI int evas_textblock_cursor_line_geometry_get (const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch)
 Returns the geometry of the line at cur.
EAPI Eina_Bool evas_textblock_cursor_char_coord_set (Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y)
 Set the position of the cursor according to the X and Y coordinates.
EAPI int evas_textblock_cursor_line_coord_set (Evas_Textblock_Cursor *cur, Evas_Coord y)
 Set the cursor position according to the y coord.
EAPI Eina_List * evas_textblock_cursor_range_geometry_get (const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2)
 Get the geometry of a range.
EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get (const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch)
 to be documented.
EAPI Eina_Bool evas_textblock_cursor_eol_get (const Evas_Textblock_Cursor *cur)
 Checks if the cursor points to the end of the line.
EAPI Eina_Bool evas_object_textblock_line_number_geometry_get (const Evas_Object *obj, int line, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch)
 Get the geometry of a line number.
EAPI void evas_object_textblock_clear (Evas_Object *obj)
 Clear the textblock object.
EAPI void evas_object_textblock_size_formatted_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h)
 Get the formatted width and height.
EAPI void evas_object_textblock_size_native_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h)
 Get the native width and height.
EAPI void evas_object_textblock_style_insets_get (const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b)
 to be documented.

Detailed Description

Functions used to create and manipulate textblock objects.

Unlike Text Object Functions, these handle complex text, doing multiple styles and multiline text based on HTML-like tags. Of these extra features will be heavier on memory and processing cost.

Todo:
put here some usage examples

Define Documentation

#define ENFN   obj->layer->evas->engine.func

Textblock Object Tutorial

This part explains about the textblock object's API and proper usage. If you want to develop textblock, you should also refer to Evas_Object_Textblock_Internal. The main user of the textblock object is the edje entry object in Edje, so that's a good place to learn from, but I think this document is more than enough, if it's not, please request for me info and I'll update it.

Introduction

The textblock objects is, as implied, an object that can show big chunks of text. Textblock supports many features including: Text formatting, automatic and manual text alignment, embedding items (for example icons) and more. Textblock has three important parts, the text paragraphs, the format nodes and the cursors.

Textblock Object Cursors

A textblock Cursor Evas_Textblock_Cursor is data type that represents a position in a textblock. Each cursor contains information about the paragraph it points to, the position in that paragraph and the object itself. Cursors register to textblock objects upon creation, this means that once you created a cursor, it belongs to a specific obj and you can't for example copy a cursor "into" a cursor of a different object. Registered cursors also have the added benefit of updating automatically upon textblock changes, this means that if you have a cursor pointing to a specific character, it'll still point to it even after you change the whole object completely (as long as the char was not deleted), this is not possible without updating, because as mentioned, each cursor holds a character position. There are many functions that handle cursors, just check out the evas_textblock_cursor* functions. For creation and deletion of cursors check out:

See also:
evas_object_textblock_cursor_new()
evas_textblock_cursor_free()
Note:
Cursors are generally the correct way to handle text in the textblock object, and there are enough functions to do everything you need with them (no need to get big chunks of text and processing them yourself).

Textblock Object Paragraphs

The textblock object is made out of text splitted to paragraphs (delimited by the paragraph separation character). Each paragraph has many (or none) format nodes associated with it which are responsible for the formatting of that paragraph.

Textblock Object Format Nodes

As explained in Textblock Object Paragraphs each one of the format nodes is associated with a paragraph. There are two types of format nodes, visible and invisible: Visible: formats that a cursor can point to, i.e formats that occupy space, for example: newlines, tabs, items and etc. Some visible items are made of two parts, in this case, only the opening tag is visible. A closing tag (i.e a </tag> tag) should NEVER be visible. Invisible: formats that don't occupy space, for example: bold and underline. Being able to access format nodes is very important for some uses. For example, edje uses the "<a>" format to create links in the text (and pop popups above them when clicked). For the textblock object a is just a formatting instruction (how to color the text), but edje utilizes the access to the format nodes to make it do more. For more information, take a look at all the evas_textblock_node_format_* functions. The translation of "<tag>" tags to actual format is done according to the tags defined in the style, see evas_textblock_style_set

Special Formats

This section is not yet written. If you want some info about styles/formats and how to use them, expedite's textblock_basic test is a great start.

Todo:
Write

Referenced by evas_object_text_char_coords_get(), evas_object_text_char_pos_get(), evas_object_text_font_set(), evas_object_text_horiz_advance_get(), evas_object_text_inset_get(), evas_object_text_last_up_to_pos(), evas_object_text_text_set(), and evas_object_text_vert_advance_get().

Function Documentation

EAPI Evas_Object* evas_object_textblock_add ( Evas *  e  ) 

Adds a textblock to the given evas.

Parameters:
e The given evas.
Returns:
The new textblock object.
EAPI void evas_object_textblock_clear ( Evas_Object *  obj  ) 

Clear the textblock object.

Note:
Does *NOT* free the evas object itself.
Parameters:
obj the object to clear.
Returns:
nothing.
EAPI const Evas_Textblock_Cursor* evas_object_textblock_cursor_get ( const Evas_Object *  obj  ) 

Return the object's main cursor.

Parameters:
obj the object.
Returns:
the obj's main cursor.
EAPI Evas_Textblock_Cursor* evas_object_textblock_cursor_new ( Evas_Object *  obj  ) 

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).
Parameters:
obj the object to associate to.
Returns:
the new cursor.
EAPI Eina_Bool evas_object_textblock_line_number_geometry_get ( const Evas_Object *  obj,
int  line,
Evas_Coord *  cx,
Evas_Coord *  cy,
Evas_Coord *  cw,
Evas_Coord *  ch 
)

Get the geometry of a line number.

Parameters:
obj the object.
line the line number.
cx x coord of the line.
cy y coord of the line.
cw w coord of the line.
ch h coord of the line.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

Referenced by evas_textblock_cursor_range_geometry_get().

EAPI const char* evas_object_textblock_replace_char_get ( Evas_Object *  obj  ) 

Get the "replacement character" for given textblock object.

Returns NULL if no replacement character is in use.

Parameters:
obj The given textblock object
Returns:
replacement character or NULL
EAPI void evas_object_textblock_replace_char_set ( Evas_Object *  obj,
const char *  ch 
)

Set the "replacement character" to use for the given textblock object.

Parameters:
obj The given textblock object.
ch The charset name.
EAPI void evas_object_textblock_size_formatted_get ( const Evas_Object *  obj,
Evas_Coord *  w,
Evas_Coord *  h 
)

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 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.

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.

Parameters:
obj the evas object.
w[out] the width of the object.
h[out] the height of the object
Returns:
Returns no value.
See also:
evas_object_textblock_size_native_get
EAPI void evas_object_textblock_size_native_get ( const Evas_Object *  obj,
Evas_Coord *  w,
Evas_Coord *  h 
)

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 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.

Parameters:
obj the evas object of the textblock
w[out] the width returned
h[out] the height returned
Returns:
Returns no value.
EAPI const Evas_Textblock_Style* evas_object_textblock_style_get ( const Evas_Object *  obj  ) 

Return the style of an object.

Parameters:
obj the object to get the style from.
Returns:
the style of the object.
EAPI void evas_object_textblock_style_insets_get ( const Evas_Object *  obj,
Evas_Coord *  l,
Evas_Coord *  r,
Evas_Coord *  t,
Evas_Coord *  b 
)

to be documented.

Parameters:
obj to be documented.
l to be documented.
r to be documented.
t to be documented.
b to be documented.
Returns:
Returns no value.
EAPI void evas_object_textblock_style_set ( Evas_Object *  obj,
Evas_Textblock_Style *  ts 
)

Set the objects style to ts.

Parameters:
obj the evas object to set the style to.
ts the style to set.
Returns:
Returns no value.

References evas_object_textblock_text_markup_get(), and evas_textblock_style_free().

EAPI const char* evas_object_textblock_text_markup_get ( const Evas_Object *  obj  ) 

Return the markup of the object.

Parameters:
obj the evas object.
Returns:
the markup text of the object.

Referenced by evas_object_textblock_style_set(), and evas_textblock_style_set().

EAPI void evas_object_textblock_text_markup_prepend ( Evas_Textblock_Cursor *  cur,
const char *  text 
)

Prepends markup to the cursor cur.

Note:
assumes text does not include the unicode object replacement char (0xFFFC)
Parameters:
cur the cursor to prepend to.
text the markup text to prepend.
Returns:
Return no value.

References evas_textblock_cursor_format_prepend().

Referenced by evas_object_textblock_text_markup_set().

EAPI void evas_object_textblock_text_markup_set ( Evas_Object *  obj,
const char *  text 
)

Sets the tetxblock's text to the markup text.

Note:
assumes text does not include the unicode object replacement char (0xFFFC)
Parameters:
obj the textblock object.
text the markup text to use.
Returns:
Return no value.

References evas_object_textblock_text_markup_prepend(), and evas_textblock_cursor_paragraph_first().

Referenced by evas_textblock_style_set().

EAPI void evas_textblock_cursor_at_format_set ( Evas_Textblock_Cursor *  cur,
const Evas_Object_Textblock_Node_Format *  fmt 
)

Set the cursor to point to the position of fmt.

Parameters:
cur the cursor to update
fmt the format to update according to.
EAPI Eina_Bool evas_textblock_cursor_char_coord_set ( Evas_Textblock_Cursor *  cur,
Evas_Coord  x,
Evas_Coord  y 
)

Set the position of the cursor according to the X and Y coordinates.

Parameters:
cur the cursor to set.
x coord to set by.
y coord to set by.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise.

References evas_textblock_cursor_line_char_last().

EAPI void evas_textblock_cursor_char_delete ( Evas_Textblock_Cursor *  cur  ) 

Delete the character at the location of the cursor.

If there's a format pointing to this position, delete it as well.

Parameters:
cur the cursor pointing to the current location.
Returns:
Returns no value.
EAPI int evas_textblock_cursor_char_geometry_get ( const Evas_Textblock_Cursor *  cur,
Evas_Coord *  cx,
Evas_Coord *  cy,
Evas_Coord *  cw,
Evas_Coord *  ch 
)

Returns the geometry of the char at cur.

Parameters:
cur the position of the char.
cx the x of the char.
cy the y of the char.
cw the width of the char.
ch the height of the char.
Returns:
line number of the char on success, -1 on error.

References evas_textblock_cursor_copy(), and evas_textblock_cursor_format_is_visible_get().

Referenced by evas_textblock_cursor_geometry_get(), and evas_textblock_cursor_range_geometry_get().

EAPI Eina_Bool evas_textblock_cursor_char_next ( Evas_Textblock_Cursor *  cur  ) 

Advances 1 char forward.

Parameters:
cur the cursor to advance.
Returns:
EINA_TRUE on success EINA_FALSE otherwise.

References evas_textblock_cursor_paragraph_next().

Referenced by evas_textblock_cursor_format_prepend().

EAPI Eina_Bool evas_textblock_cursor_char_prev ( Evas_Textblock_Cursor *  cur  ) 

Advances 1 char backward.

Parameters:
cur the cursor to advance.
Returns:
EINA_TRUE on success EINA_FALSE otherwise.

References evas_textblock_cursor_paragraph_prev().

EAPI int evas_textblock_cursor_compare ( const Evas_Textblock_Cursor *  cur1,
const Evas_Textblock_Cursor *  cur2 
)

Compare two cursors.

Parameters:
cur1 the first cursor.
cur2 the second cursor.
Returns:
-1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise.

Referenced by evas_textblock_cursor_range_delete(), evas_textblock_cursor_range_geometry_get(), and evas_textblock_cursor_range_text_get().

EAPI char* evas_textblock_cursor_content_get ( const Evas_Textblock_Cursor *  cur  ) 

Return the content of the cursor.

Parameters:
cur the cursor
Returns:
the text in the range

References evas_textblock_cursor_format_get(), evas_textblock_cursor_format_is_visible_get(), and evas_textblock_node_format_text_get().

EAPI void evas_textblock_cursor_copy ( const Evas_Textblock_Cursor *  cur,
Evas_Textblock_Cursor *  cur_dest 
)

Make cur_dest point to the same place as cur.

Does not work if they don't point to the same object.

Parameters:
cur the source cursor.
cur_dest destination cursor.
Returns:
Returns no value.

Referenced by evas_textblock_cursor_char_geometry_get(), evas_textblock_cursor_eol_get(), evas_textblock_cursor_geometry_get(), evas_textblock_cursor_line_char_first(), evas_textblock_cursor_line_char_last(), evas_textblock_cursor_line_geometry_get(), evas_textblock_cursor_range_delete(), and evas_textblock_cursor_range_text_get().

EAPI Eina_Bool evas_textblock_cursor_eol_get ( const Evas_Textblock_Cursor *  cur  ) 

Checks if the cursor points to the end of the line.

Parameters:
cur the cursor to check.
Returns:
EINA_TRUE if true, EINA_FALSE otherwise.

References evas_textblock_cursor_copy(), and evas_textblock_cursor_line_char_last().

EAPI Eina_Bool evas_textblock_cursor_format_append ( Evas_Textblock_Cursor *  cur,
const char *  format 
)

Adds format to the current cursor position.

If the format being added is a visible format, add it *before* the cursor position, otherwise, add it after. This behavior is because visible formats are like characters and invisible should be stacked in a way that the last one is added last.

Parameters:
cur the cursor to where to add format at.
format the format to add.
Returns:
Returns true if a visible format was added, false otherwise.
See also:
evas_textblock_cursor_format_prepend()

References evas_textblock_cursor_format_is_visible_get(), and evas_textblock_cursor_text_prepend().

Referenced by evas_textblock_cursor_format_prepend().

EAPI const Evas_Object_Textblock_Node_Format* evas_textblock_cursor_format_get ( const Evas_Textblock_Cursor *  cur  ) 

Return the format node at the position pointed by cur.

Parameters:
cur the position to look at.
Returns:
the format node if found, NULL otherwise.
See also:
evas_textblock_cursor_format_is_visible_get()

Referenced by evas_textblock_cursor_content_get().

EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get ( const Evas_Textblock_Cursor *  cur  ) 

Check if the current cursor position is a visible format.

This way is more efficient than evas_textblock_cursor_format_get() to check for the existence of a visible format.

Parameters:
cur the cursor to look at.
Returns:
EINA_TRUE if the cursor points to a visible format, EINA_FALSE otherwise.
See also:
evas_textblock_cursor_format_get()

Referenced by evas_textblock_cursor_char_geometry_get(), evas_textblock_cursor_content_get(), evas_textblock_cursor_format_append(), evas_textblock_cursor_format_item_geometry_get(), evas_textblock_cursor_is_format(), evas_textblock_cursor_line_char_first(), evas_textblock_cursor_line_char_last(), evas_textblock_cursor_line_geometry_get(), and evas_textblock_cursor_text_append().

EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get ( const Evas_Textblock_Cursor *  cur,
Evas_Coord *  cx,
Evas_Coord *  cy,
Evas_Coord *  cw,
Evas_Coord *  ch 
)

to be documented.

Parameters:
cur to be documented.
cx to be documented.
cy to be documented.
cw to be documented.
ch to be documented.
Returns:
to be documented.

References evas_textblock_cursor_format_is_visible_get().

EAPI Eina_Bool evas_textblock_cursor_format_next ( Evas_Textblock_Cursor *  cur  ) 

Advances to the next format node.

Parameters:
cur the cursor to be updated.
Returns:
EINA_TRUE on success EINA_FALSE otherwise.
EAPI Eina_Bool evas_textblock_cursor_format_prepend ( Evas_Textblock_Cursor *  cur,
const char *  format 
)

Adds format to the current cursor position.

If the format being added is a visible format, add it *before* the cursor position, otherwise, add it after. This behavior is because visible formats are like characters and invisible should be stacked in a way that the last one is added last. If the format is visible the cursor is advanced after it.

Parameters:
cur the cursor to where to add format at.
format the format to add.
Returns:
Returns true if a visible format was added, false otherwise.
See also:
evas_textblock_cursor_format_prepend()

References evas_textblock_cursor_char_next(), and evas_textblock_cursor_format_append().

Referenced by evas_object_textblock_text_markup_prepend().

EAPI Eina_Bool evas_textblock_cursor_format_prev ( Evas_Textblock_Cursor *  cur  ) 

Advances to the previous format node.

Parameters:
cur the cursor to update.
Returns:
EINA_TRUE on success EINA_FALSE otherwise.

References evas_textblock_cursor_is_format().

EAPI void evas_textblock_cursor_free ( Evas_Textblock_Cursor *  cur  ) 

Free the cursor and unassociate it from the object.

Note:
do not use it to free unassociated cursors.
Parameters:
cur the cursor to free.
Returns:
Returns no value.
EAPI int evas_textblock_cursor_geometry_get ( const Evas_Textblock_Cursor *  cur,
Evas_Coord *  cx,
Evas_Coord *  cy,
Evas_Coord *  cw,
Evas_Coord *  ch,
Evas_BiDi_Direction *  dir,
Evas_Textblock_Cursor_Type  ctype 
)

Returns the geometry of the cursor.

Depends on the type of cursor requested. This should be used instead of char_geometry_get because there are weird special cases with BiDi text. in '_' cursor mode (i.e a line below the char) it's the same as char_geometry get, except for the case of the last char of a line which depends on the paragraph direction.

in '|' cursor mode (i.e a line between two chars) it is very varyable. For example consider the following visual string: "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw a '|' between the c and the C.

Parameters:
cur the cursor.
cx the x of the cursor
cy the y of the cursor
cw the width of the cursor
ch the height of the cursor
dir the direction of the cursor, can be NULL.
ctype the type of the cursor.
Returns:
line number of the char on success, -1 on error.

References evas_textblock_cursor_char_geometry_get(), and evas_textblock_cursor_copy().

EAPI Eina_Bool evas_textblock_cursor_is_format ( const Evas_Textblock_Cursor *  cur  ) 

Returns true if the cursor points to a format.

Parameters:
cur the cursor to check.
Returns:
Returns EINA_TRUE if a cursor points to a format EINA_FALSE otherwise.

References evas_textblock_cursor_format_is_visible_get().

Referenced by evas_textblock_cursor_format_prev().

EAPI void evas_textblock_cursor_line_char_first ( Evas_Textblock_Cursor *  cur  ) 

Go to the start of the current line.

Parameters:
cur the cursor to update.
Returns:
Returns no value.

References evas_textblock_cursor_copy(), and evas_textblock_cursor_format_is_visible_get().

EAPI void evas_textblock_cursor_line_char_last ( Evas_Textblock_Cursor *  cur  ) 

Go to the end of the current line.

Parameters:
cur the cursor to update.
Returns:
Returns no value.

References evas_textblock_cursor_copy(), and evas_textblock_cursor_format_is_visible_get().

Referenced by evas_textblock_cursor_char_coord_set(), and evas_textblock_cursor_eol_get().

EAPI int evas_textblock_cursor_line_coord_set ( Evas_Textblock_Cursor *  cur,
Evas_Coord  y 
)

Set the cursor position according to the y coord.

Parameters:
cur the cur to be set.
y the coord to set by.
Returns:
the line number found, -1 on error.

References evas_textblock_cursor_line_set().

EAPI int evas_textblock_cursor_line_geometry_get ( const Evas_Textblock_Cursor *  cur,
Evas_Coord *  cx,
Evas_Coord *  cy,
Evas_Coord *  cw,
Evas_Coord *  ch 
)

Returns the geometry of the line at cur.

Parameters:
cur the position of the line.
cx the x of the line.
cy the y of the line.
cw the width of the line.
ch the height of the line.
Returns:
line number of the line on success, -1 on error.

References evas_textblock_cursor_copy(), and evas_textblock_cursor_format_is_visible_get().

Referenced by evas_textblock_cursor_range_geometry_get().

EAPI Eina_Bool evas_textblock_cursor_line_set ( Evas_Textblock_Cursor *  cur,
int  line 
)

Go to the start of the line passed.

Parameters:
cur cursor to update.
line numer to set.
Returns:
EINA_TRUE on success, EINA_FALSE on error.

Referenced by evas_textblock_cursor_line_coord_set().

EAPI void evas_textblock_cursor_paragraph_char_first ( Evas_Textblock_Cursor *  cur  ) 

Go to the first char in the node the cursor is pointing on.

Parameters:
cur the cursor to update.
Returns:
Returns no value.

Referenced by evas_textblock_cursor_paragraph_text_get().

EAPI void evas_textblock_cursor_paragraph_char_last ( Evas_Textblock_Cursor *  cur  ) 

Go to the last char in a text node.

Parameters:
cur the cursor to update.
Returns:
Returns no value.

Referenced by evas_textblock_cursor_paragraph_last(), evas_textblock_cursor_paragraph_prev(), and evas_textblock_cursor_paragraph_text_get().

EAPI void evas_textblock_cursor_paragraph_first ( Evas_Textblock_Cursor *  cur  ) 

Sets the cursor to the start of the first text node.

Parameters:
cur the cursor to update.
Returns:
Returns no value.

Referenced by evas_object_textblock_text_markup_set().

EAPI void evas_textblock_cursor_paragraph_last ( Evas_Textblock_Cursor *  cur  ) 

sets the cursor to the end of the last text node.

Parameters:
cur the cursor to set.
Returns:
Returns no value.

References evas_textblock_cursor_paragraph_char_last().

EAPI Eina_Bool evas_textblock_cursor_paragraph_next ( Evas_Textblock_Cursor *  cur  ) 

Advances to the the start of the next text node.

Parameters:
cur the cursor to update
Returns:
EINA_TRUE if it managed to advance a paragraph, EINA_FALSE otherwise.

Referenced by evas_textblock_cursor_char_next().

EAPI Eina_Bool evas_textblock_cursor_paragraph_prev ( Evas_Textblock_Cursor *  cur  ) 

Advances to the the end of the previous text node.

Parameters:
cur the cursor to update
Returns:
EINA_TRUE if it managed to advance a paragraph, EINA_FALSE otherwise.

References evas_textblock_cursor_paragraph_char_last().

Referenced by evas_textblock_cursor_char_prev().

EAPI const char* evas_textblock_cursor_paragraph_text_get ( const Evas_Textblock_Cursor *  cur  ) 

Return the text of the paragraph cur points to - returns the text in markup.

Parameters:
cur the cursor pointing to the paragraph.
Returns:
the text on success, NULL otherwise.

References evas_textblock_cursor_paragraph_char_first(), evas_textblock_cursor_paragraph_char_last(), and evas_textblock_cursor_range_text_get().

EAPI int evas_textblock_cursor_paragraph_text_length_get ( const Evas_Textblock_Cursor *  cur  ) 

Return the length of the paragraph, cheaper the eina_unicode_strlen().

Parameters:
cur the position of the paragraph.
Returns:
the length of the paragraph on success, -1 otehrwise.
EAPI int evas_textblock_cursor_pos_get ( const Evas_Textblock_Cursor *  cur  ) 

Return the current cursor pos.

Parameters:
cur the cursor to take the position from.
Returns:
the position or -1 on error
EAPI void evas_textblock_cursor_pos_set ( Evas_Textblock_Cursor *  cur,
int  _pos 
)

Set the cursor pos.

Parameters:
cur the cursor to be set.
pos the pos to set.
EAPI void evas_textblock_cursor_range_delete ( Evas_Textblock_Cursor *  cur1,
Evas_Textblock_Cursor *  cur2 
)

Delete the range between cur1 and cur2.

Parameters:
cur1 one side of the range.
cur2 the second side of the range
Returns:
Returns no value.

References evas_textblock_cursor_compare(), and evas_textblock_cursor_copy().

EAPI Eina_List* evas_textblock_cursor_range_geometry_get ( const Evas_Textblock_Cursor *  cur1,
const Evas_Textblock_Cursor *  cur2 
)

Get the geometry of a range.

Parameters:
cur1 one side of the range.
cur2 other side of the range.
Returns:
a list of Rectangles representing the geometry of the range.

References evas_object_textblock_line_number_geometry_get(), evas_textblock_cursor_char_geometry_get(), evas_textblock_cursor_compare(), and evas_textblock_cursor_line_geometry_get().

EAPI char* evas_textblock_cursor_range_text_get ( const Evas_Textblock_Cursor *  cur1,
const Evas_Textblock_Cursor *  _cur2,
Evas_Textblock_Text_Type format  __UNUSED__ 
)

Return the text in the range between cur1 and cur2.

FIXME: format is currently unused, you always get markup back.

Parameters:
cur1 one side of the range.
cur2 the other side of the range
format to be documented
Returns:
the text in the range
See also:
elm_entry_markup_to_utf8()

References evas_textblock_cursor_compare(), and evas_textblock_cursor_copy().

Referenced by evas_textblock_cursor_paragraph_text_get().

EAPI void evas_textblock_cursor_set_at_format ( Evas_Textblock_Cursor *  cur,
const Evas_Object_Textblock_Node_Format *  n 
)

Sets the cursor to point to the place where format points to.

Parameters:
cur the cursor to update.
n the format node to update according.

Referenced by evas_textblock_node_format_remove_pair().

EAPI int evas_textblock_cursor_text_append ( Evas_Textblock_Cursor *  cur,
const char *  _text 
)

Adds text to the current cursor position and set the cursor to *before* the start of the text just added.

Parameters:
cur the cursor to where to add text at.
_text the text to add.
Returns:
Returns the len of the text added.
See also:
evas_textblock_cursor_text_prepend()

References evas_textblock_cursor_format_is_visible_get().

Referenced by evas_textblock_cursor_text_prepend().

EAPI int evas_textblock_cursor_text_prepend ( Evas_Textblock_Cursor *  cur,
const char *  _text 
)

Adds text to the current cursor position and set the cursor to *after* the start of the text just added.

Parameters:
cur the cursor to where to add text at.
_text the text to add.
Returns:
Returns the len of the text added.
See also:
evas_textblock_cursor_text_append()

References evas_textblock_cursor_text_append().

Referenced by evas_textblock_cursor_format_append().

EAPI const char* evas_textblock_escape_string_get ( const char *  escape  ) 

Returns the unescaped version of escape.

Parameters:
escape the string to be escaped
Returns:
the unescaped version of escape
EAPI const char* evas_textblock_escape_string_range_get ( const char *  escape_start,
const char *  escape_end 
)

Return the unescaped version of the string between start and end.

Parameters:
escape_start the start of the string.
escape_end the end of the string.
Returns:
the unescaped version of the range
EAPI const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_first_get ( const Evas_Object *  obj  ) 

Returns the first format node.

Parameters:
obj The evas, must not be NULL.
Returns:
Returns the first format node, may be null if there are none.
EAPI const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_last_get ( const Evas_Object *  obj  ) 

Returns the last format node.

Parameters:
obj The evas textblock, must not be NULL.
Returns:
Returns the first format node, may be null if there are none.
EAPI const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_next_get ( const Evas_Object_Textblock_Node_Format *  n  ) 

Returns the next format node (after n).

Parameters:
n the current format node - not null.
Returns:
Returns the next format node, may be null.
EAPI const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_prev_get ( const Evas_Object_Textblock_Node_Format *  n  ) 

Returns the prev format node (after n).

Parameters:
n the current format node - not null.
Returns:
Returns the prev format node, may be null.
EAPI void evas_textblock_node_format_remove_pair ( Evas_Object *  obj,
Evas_Object_Textblock_Node_Format *  n 
)

Remove a format node and it's match.

i.e, removes a <tag> </tag> pair. Assumes the node is the first part of <tag> i.e, this won't work if n is a closing tag.

Parameters:
obj the evas object of the textblock - not null.
n the current format node - not null.

References evas_textblock_cursor_set_at_format().

EAPI const char* evas_textblock_node_format_text_get ( const Evas_Object_Textblock_Node_Format *  fmt  ) 

Get the text format representation of the format node.

Parameters:
fmt the format node.
Returns:
the textual format of the format node.

Referenced by evas_textblock_cursor_content_get().

EAPI const char* evas_textblock_string_escape_get ( const char *  string,
int *  len_ret 
)

Returns the escaped version of the string.

Parameters:
string to escape
len_ret the len of the new escape
Returns:
the escaped string.
EAPI void evas_textblock_style_free ( Evas_Textblock_Style *  ts  ) 

Destroys a textblock style.

Parameters:
ts The textblock style to free.

Referenced by evas_object_textblock_style_set().

EAPI const char* evas_textblock_style_get ( const Evas_Textblock_Style *  ts  ) 

Return the text of the style ts.

Parameters:
ts the style to get it's text.
Returns:
the text of the style or null on error.
EAPI Evas_Textblock_Style* evas_textblock_style_new ( void   ) 

Creates a new textblock style.

Returns:
The new textblock style.
EAPI void evas_textblock_style_set ( Evas_Textblock_Style *  ts,
const char *  text 
)

Sets the style ts to the style passed as text by text.

Expected a string consisting of many (or none) tag='format' pairs.

Parameters:
ts the style to set.
text the text to parse - NOT NULL.
Returns:
Returns no value.

References evas_object_textblock_text_markup_get(), and evas_object_textblock_text_markup_set().