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.

Textblock Object Tutorial

This part explains about the textblock object's API and proper usage. 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 contact me 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.

You can use markup to format text, for example: "<font_size=50>Big!</font_size>". You can also put more than one style directive in one tag: "<font_size=50 color=#F00>Big and Red!</font_size>". Please notice that we used "</font_size>" although the format also included color, this is because the first format determines the matching closing tag's name. You can also use anonymous tags, like: "<font_size=30>Big</>" which just pop any type of format, but it's advised to use the named alternatives instead.

Textblock Object Cursors

A 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

Textblock supports various format directives that can be used in markup. In addition to the mentioned format directives, textblock allows creating additional format directives using "tags" that can be set in the style see evas_textblock_style_set .

For more details see evas_textblock_style_page

Textblock supports the following formats:

font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
font_weight - Overrides the weight defined in "font". E.g: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
font_style - Overrides the style defined in "font". E.g: "font_style=Italic" is the same as "font=:style=Italic". Supported styles: "normal", "oblique", and "italic".
font_width - Overrides the width defined in "font". E.g: "font_width=Condensed" is the same as "font=:style=Condensed". Supported widths: "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded".
lang - Overrides the language defined in "font". E.g: "lang=he" is the same as "font=:lang=he".
font_fallbacks - A comma delimited list of fonts to try if finding the main font fails.
font_size - The font size in points.
font_source - The source of the font, e.g an eet file.
color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
underline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
underline2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
outline_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
shadow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
glow_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
glow2_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
strikethrough_color - color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
align - Either "auto" (meaning according to text direction), "left", "right", "center", "middle", a value between 0.0 and 1.0, or a value between 0% to 100%.
valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between 0.0 and 1.0, or a value between 0% to 100%.
wrap - "word", "char", "mixed", or "none".
left_margin - Either "reset", or a pixel value indicating the margin.
right_margin - Either "reset", or a pixel value indicating the margin.
underline - "on", "off", "single", or "double".
strikethrough - "on" or "off"
backing_color - Background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA".
backing - Enable/disable background color. ex) "on" or "off"
style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow". Direction can be selected by adding "bottom_right", "bottom", "bottom_left", "left", "top_left", "top", "top_right", or "right". E.g: "style=shadow,bottom_right".
tabstops - Pixel value for tab width.
linesize - Force a line size in pixels.
linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
linegap - Force a line gap in pixels.
linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size.
item - Creates an empty space that should be filled by an upper layer. Use "size", "abssize", or "relsize". To define the items size, and an optional: vsize=full/ascent to define the item's position in the line.
linefill - Either a float value or percentage indicating how much to fill the line.
ellipsis - Value between 0.0-1.0 to indicate the type of ellipsis, or -1.0 to indicate ellipsis isn't wanted.
password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off.

Warning:: We don't guarantee any proper results if you create a Textblock object without setting the evas engine.

Functions
const char *	evas_textblock_escape_string_get (const char *escape)
const char *	evas_textblock_string_escape_get (const char string, int len_ret)
const char *	evas_textblock_escape_string_range_get (const char escape_start, const char escape_end)
Evas_Textblock_Style *	evas_textblock_style_new (void)
void	evas_textblock_style_free (Evas_Textblock_Style *ts)
void	evas_textblock_style_set (Evas_Textblock_Style ts, const char text)
const char *	evas_textblock_style_get (const Evas_Textblock_Style *ts)
const Evas_Object_Textblock_Node_Format *	evas_textblock_node_format_next_get (const Evas_Object_Textblock_Node_Format *n)
const Evas_Object_Textblock_Node_Format *	evas_textblock_node_format_prev_get (const Evas_Object_Textblock_Node_Format *n)
void	evas_textblock_cursor_set_at_format (Evas_Textblock_Cursor cur, const Evas_Object_Textblock_Node_Format n)
const Evas_Object_Textblock_Node_Format *	evas_textblock_cursor_format_get (const Evas_Textblock_Cursor *cur)
const char *	evas_textblock_node_format_text_get (const Evas_Object_Textblock_Node_Format *fnode)
void	evas_textblock_cursor_at_format_set (Evas_Textblock_Cursor cur, const Evas_Object_Textblock_Node_Format fmt)
Eina_Bool	evas_textblock_cursor_format_is_visible_get (const Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_format_next (Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_format_prev (Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_is_format (const Evas_Textblock_Cursor *cur)
int	evas_textblock_cursor_pos_get (const Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_line_set (Evas_Textblock_Cursor *cur, int line)
Eina_Bool	evas_textblock_cursor_format_append (Evas_Textblock_Cursor cur, const char format)
Eina_Bool	evas_textblock_cursor_format_prepend (Evas_Textblock_Cursor cur, const char format)
void	evas_textblock_cursor_range_delete (Evas_Textblock_Cursor cur1, Evas_Textblock_Cursor cur2)
const char *	evas_textblock_cursor_paragraph_text_get (const Evas_Textblock_Cursor *cur)
int	evas_textblock_cursor_paragraph_text_length_get (const Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_visible_range_get (Evas_Textblock_Cursor start, Evas_Textblock_Cursor end)
Eina_List *	evas_textblock_cursor_range_formats_get (const Evas_Textblock_Cursor cur1, const Evas_Textblock_Cursor cur2)
char *	evas_textblock_cursor_range_text_get (const Evas_Textblock_Cursor cur1, const Evas_Textblock_Cursor cur2, Evas_Textblock_Text_Type format)
char *	evas_textblock_cursor_content_get (const Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_geometry_bidi_get (const Evas_Textblock_Cursor cur, Evas_Coord cx, Evas_Coord cy, Evas_Coord cw, Evas_Coord ch, Evas_Coord cx2, Evas_Coord cy2, Evas_Coord cw2, Evas_Coord *ch2, Evas_Textblock_Cursor_Type ctype)
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)
int	evas_textblock_cursor_char_geometry_get (const Evas_Textblock_Cursor cur, Evas_Coord cx, Evas_Coord cy, Evas_Coord cw, Evas_Coord *ch)
int	evas_textblock_cursor_pen_geometry_get (const Evas_Textblock_Cursor cur, Evas_Coord cpen_x, Evas_Coord cy, Evas_Coord cadv, Evas_Coord *ch)
int	evas_textblock_cursor_line_geometry_get (const Evas_Textblock_Cursor cur, Evas_Coord cx, Evas_Coord cy, Evas_Coord cw, Evas_Coord *ch)
int	evas_textblock_cursor_line_coord_set (Evas_Textblock_Cursor *cur, Evas_Coord y)
Eina_List *	evas_textblock_cursor_range_geometry_get (const Evas_Textblock_Cursor cur1, const Evas_Textblock_Cursor cur2)
Eina_Iterator *	evas_textblock_cursor_range_simple_geometry_get (const Evas_Textblock_Cursor cur1, const Evas_Textblock_Cursor cur2)
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)
Eina_Bool	evas_textblock_cursor_eol_get (const Evas_Textblock_Cursor *cur)
Eina_Bool	evas_textblock_cursor_char_prev (Evas_Textblock_Cursor *obj)
	Advances the cursor one char backwards.
Eina_Bool	evas_textblock_cursor_char_next (Evas_Textblock_Cursor *obj)
	Advances the cursor one char forward.
Eina_Bool	evas_textblock_cursor_cluster_prev (Evas_Textblock_Cursor *obj)
	Advances the cursor one grapheme cluster backwards.
Eina_Bool	evas_textblock_cursor_cluster_next (Evas_Textblock_Cursor *obj)
	Advances the cursor one grapheme cluster forward.
Eina_Bool	evas_textblock_cursor_paragraph_next (Evas_Textblock_Cursor *obj)
	Advances to the start of the next text node.
Eina_Bool	evas_textblock_cursor_paragraph_prev (Evas_Textblock_Cursor *obj)
	Advances to the end of the previous text node.
Eina_Bool	evas_textblock_cursor_word_start (Evas_Textblock_Cursor *obj)
	Moves the cursor to the start of the word under the cursor.
Eina_Bool	evas_textblock_cursor_word_end (Evas_Textblock_Cursor *obj)
	Moves the cursor to the end of the word under the cursor.
Typedefs
typedef struct _Efl_Canvas_Text_Style	Evas_Textblock_Style
typedef struct _Efl_Text_Cursor_Cursor	Evas_Textblock_Cursor
typedef struct _Evas_Textblock_Node_Format	Evas_Object_Textblock_Node_Format
typedef Eina_Rectangle	Evas_Textblock_Rectangle
typedef enum _Evas_Textblock_Text_Type	Evas_Textblock_Text_Type
typedef enum _Evas_Textblock_Cursor_Type	Evas_Textblock_Cursor_Type

Typedef Documentation

Evas_Object_Textblock_Node_Format

A format node.

XXX: Adapter for legacy.

Evas_Textblock_Cursor

A textblock cursor object, used to maipulate the cursor of an evas textblock

See also:: evas_object_textblock_cursor_new

typedef enum _Evas_Textblock_Cursor_Type Evas_Textblock_Cursor_Type

Cursor type for evas textblock.

typedef struct _Evas_Textblock_Node_Format Evas_Textblock_Node_Format

A format node.

XXX: Adapter for legacy.

Evas_Textblock_Rectangle

General-purpose rectangle that represents some geometry in this object.

Evas_Textblock_Style

A textblock style object.

See also:: evas_textblock_style_new(); evas_textblock_style_get(); evas_textblock_style_set()

typedef enum _Evas_Textblock_Text_Type Evas_Textblock_Text_Type

Text type for evas textblock.

Enumeration Type Documentation

enum _Evas_Textblock_Cursor_Type

Cursor type for evas textblock.

Enumerator:

EVAS_TEXTBLOCK_CURSOR_UNDER	cursor type is under
EVAS_TEXTBLOCK_CURSOR_BEFORE	cursor type is before

enum _Evas_Textblock_Text_Type

Text type for evas textblock.

Enumerator:

EVAS_TEXTBLOCK_TEXT_RAW	textblock text of type raw
EVAS_TEXTBLOCK_TEXT_PLAIN	textblock text of type plain
EVAS_TEXTBLOCK_TEXT_MARKUP	textblock text of type markup

Function Documentation

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.

Since :: 2.3

Examples:: ecore_imf_example.c, and evas-images2.c.

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.

Since :: 2.3

Evas_Textblock_Cursor* evas_object_textblock_cursor_get ( const Evas_Object * obj )

Get the object's main cursor.

Since :: 2.3

Evas_Textblock_Cursor* evas_object_textblock_cursor_new ( const 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 textblock to which the new cursor will associate.

Returns:: Returns a new cursor associated with the given textblock object.

Since :: 2.3

Examples:: ecore_imf_example.c.

Eina_Bool evas_object_textblock_ellipsis_disabled_get ( Evas_Object * eo_obj )

TIZEN_ONLY(20161011): add ellipsis_disabled_set/get APIs

void evas_object_textblock_ellipsis_disabled_set	(	Evas_Object *	eo_obj,
		Eina_Bool	disabled
	)

TIZEN_ONLY(20161011): add ellipsis_disabled_set/get APIs

double evas_object_textblock_ellipsis_get ( const Evas_Object * eo_obj )

TIZEN_ONLY(20170703): Add ellipsize feature and refactory fade_ellipsis, marquee features.

void evas_object_textblock_ellipsis_set	(	Evas_Object *	eo_obj,
		double	ellipsis
	)

TIZEN_ONLY(20170703): Add ellipsize feature and refactory fade_ellipsis, marquee features.

Eina_Bool evas_object_textblock_ellipsis_status_get ( const Evas_Object * eo_obj )

TIZEN_ONLY(20160920): Add fade_ellipsis feature to TEXTBLOCK, TEXT part.

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
	)

Gets the geometry of the line specified by its number.

Parameters:

obj	The textblock object to query.
line	the line number of the queried line.

Returns:: Returns no value.

Since :: 2.3

const char* evas_object_textblock_replace_char_get ( const Evas_Object * obj )

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

Returns:: The charset name.

Since :: 2.3

void evas_object_textblock_replace_char_set	(	Evas_Object *	obj,
		const char *	ch
	)

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

Parameters:

[in] ch The charset name.

Since :: 2.3

Evas_Textblock_Style* evas_object_textblock_style_get ( const Evas_Object * obj )

Gets the object's current style.

Parameters:

obj	the object to get the style from.

Returns:: Returns the current active style.

See also:: evas_textblock_style_user_peek()

Since :: 2.3

void evas_object_textblock_style_set	(	Evas_Object *	obj,
		const Evas_Textblock_Style *	ts
	)

Sets object's style to given style.

Parameters:

obj	the object we set the style on
ts	the style to set.

Returns:: Returns no value.

See also:: evas_textblock_style_user_push()

Since :: 2.3

Examples:: ecore_imf_example.c, and evas-images2.c.

const Evas_Textblock_Style* evas_object_textblock_style_user_peek ( const Evas_Object * obj )

Peeks at the user-styles stack

Parameters:

obj	the object to get the style from.

Returns:: Returns the user style at the top of the user style stack.

See also:: evas_textblock_style_user_pop()

Since :: 2.3

void evas_object_textblock_style_user_pop ( Evas_Object * obj )

Removes the style at the top of the user-style stack

Parameters:

obj	the object to remove the style from.

Returns:: Returns no value.

See also:: evas_textblock_style_user_peek()

Since :: 2.3

void evas_object_textblock_style_user_push	(	Evas_Object *	obj,
		Evas_Textblock_Style *	ts
	)

Pushes ts to the top of the user style 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.

Parameters:

obj	the object to push the style.

See also:: also evas_textblock_style_set().

Since (EFL) :: 1.2

Since :: 2.3

const char* evas_object_textblock_text_markup_get ( Evas_Object * obj )

Gets the current markup text of the textblock object.

Parameters:

obj	the textblock object.

Returns:: Returns the current markup text.

Since :: 2.3

Examples:: ecore_imf_example.c.

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

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

Sets given text as markup for the textblock object.

Note:: assumes text does not include the unicode object replacement char (0xFFFC)

Parameters:

obj	the textblock object.
text	the markup text to set.

Returns:: Returns no value.

Since :: 2.3

Examples:: evas-images2.c.

double evas_object_textblock_valign_get ( const Evas_Object * obj )

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

Returns:: The alignment set for the object.

Since (EFL) :: 1.1

Since :: 2.3

void evas_object_textblock_valign_set	(	Evas_Object *	obj,
		double	align
	)

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

Parameters:

[in] align The alignment set for the object.

Since (EFL) :: 1.1

Since :: 2.3

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.

Since :: 2.3

Eina_Bool evas_textblock_cursor_char_coord_set	(	Evas_Textblock_Cursor *	obj,
		Evas_Coord	x,
		Evas_Coord	y
	)

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

Parameters:

[in] y y coord to set by.

Returns:: true on success, false otherwise.

Since :: 2.3

void evas_textblock_cursor_char_delete ( Evas_Textblock_Cursor * cur )

Deletes a single character from position pointed by given cursor.

Parameters:

cur	the cursor to update.

Returns:: Returns no value.

Since :: 2.3

Examples:: ecore_imf_example.c.

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 w of the char.
ch	the h of the char.

Returns:: line number of the char on success, -1 on error.

Since :: 2.3

Eina_Bool evas_textblock_cursor_char_next ( Evas_Textblock_Cursor * obj )

Advances the cursor one char forward.

Returns:: true on success, false otherwise.

Since :: 2.3

Eina_Bool evas_textblock_cursor_char_prev ( Evas_Textblock_Cursor * obj )

Advances the cursor one char backwards.

Returns:: true on success, false otherwise.

Since :: 2.3

Examples:: ecore_imf_example.c.

Eina_Bool evas_textblock_cursor_cluster_next ( Evas_Textblock_Cursor * obj )

Advances the cursor one grapheme cluster forward.

Returns:: true on success, false otherwise.

Eina_Bool evas_textblock_cursor_cluster_prev ( Evas_Textblock_Cursor * obj )

Advances the cursor one grapheme cluster backwards.

Returns:: true on success, false otherwise.

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

char* evas_textblock_cursor_content_get ( const Evas_Textblock_Cursor * cur )

Return the content of the cursor.

Free the returned string pointer when done (if it is not NULL).

Parameters:

cur	the cursor

Returns:: the text in the range, terminated by a nul byte (may be utf8).

Since :: 2.3

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

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.

Since :: 2.3

Eina_Bool evas_textblock_cursor_equal	(	const Evas_Textblock_Cursor *	obj,
		const Evas_Textblock_Cursor *	cur
	)

Checks if two cursors are equal.

This is faster than evas_textblock_cursor_compare so it should be used if all we care about is equality.

Parameters:

[in] cur The second cursor.

Returns:: true if equal

Since (EFL) :: 1.18

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.

This function works with native formats, that means that style defined tags like
won't work here. For those kind of things use markup prepend.

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() Check if the current cursor position points to the terminating null of the last paragraph. (shouldn't be allowed to point to the terminating null of any previous paragraph anyway.

Parameters:

cur	the cursor to look at.

Returns:: EINA_TRUE if the cursor points to the terminating null, EINA_FALSE otherwise.

Since :: 2.3

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()

Since :: 2.3

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()

Since :: 2.3

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
	)

Get the geometry of ?

Parameters:

cur	one side of the range.
cur2	other side of the range.

Since :: 3.0

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.

Since :: 2.3

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.

This function works with native formats, that means that style defined tags like
won't work here. For those kind of things use markup prepend.

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()

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

Eina_Bool evas_textblock_cursor_geometry_bidi_get	(	const Evas_Textblock_Cursor *	cur,
		Evas_Coord *	cx,
		Evas_Coord *	cy,
		Evas_Coord *	cw,
		Evas_Coord *	ch,
		Evas_Coord *	cx2,
		Evas_Coord *	cy2,
		Evas_Coord *	cw2,
		Evas_Coord *	ch2,
		Evas_Textblock_Cursor_Type	ctype
	)

Returns the geometry of two cursors ("split cursor"), if logical cursor is between LTR/RTL text, also considering paragraph direction. Upper cursor is shown for the text of the same direction as paragraph, lower cursor - for opposite.

Split cursor geometry is valid only in '|' cursor mode. In this case EINA_TRUE is returned and cx2, cy2, cw2, ch2 are set, otherwise it behaves like cursor_geometry_get.

Parameters:

[in]	cur	the cursor.
[out]	cx	the x of the cursor (or upper cursor)
[out]	cy	the y of the cursor (or upper cursor)
[out]	cw	the width of the cursor (or upper cursor)
[out]	ch	the height of the cursor (or upper cursor)
[out]	cx2	the x of the lower cursor
[out]	cy2	the y of the lower cursor
[out]	cw2	the width of the lower cursor
[out]	ch2	the height of the lower cursor
[in]	ctype	the type of the cursor.

Returns:: EINA_TRUE for split cursor, EINA_FALSE otherwise

Since (EFL) :: 1.8

Since :: 2.3

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

Since :: 2.3

Examples:: ecore_imf_example.c.

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:: EINA_TRUE if a cursor points to a format EINA_FALSE otherwise.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

Evas_BiDi_Direction evas_textblock_cursor_paragraph_direction_get ( const Evas_Textblock_Cursor * cur )

TIZEN_ONLY(20170703): Add ellipsize feature and refactory fade_ellipsis, marquee features.

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.

Since :: 2.3

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.

Since :: 2.3

Eina_Bool evas_textblock_cursor_paragraph_next ( Evas_Textblock_Cursor * obj )

Advances to the start of the next text node.

Returns:: true if managed to advance, false otherwise

Since :: 2.3

Eina_Bool evas_textblock_cursor_paragraph_prev ( Evas_Textblock_Cursor * obj )

Advances to the end of the previous text node.

Returns:: true if managed to advance, false otherwise

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

int evas_textblock_cursor_pen_geometry_get	(	const Evas_Textblock_Cursor *	cur,
		Evas_Coord *	cpen_x,
		Evas_Coord *	cy,
		Evas_Coord *	cadv,
		Evas_Coord *	ch
	)

Returns the geometry of the pen at cur.

Parameters:

cur	the position of the char.
cpen_x	the pen_x of the char.
cy	the y of the char.
cadv	the adv of the char.
ch	the h of the char.

Returns:: line number of the char on success, -1 on error.

Since :: 2.3

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

Since :: 2.3

Examples:: ecore_imf_example.c.

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

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.

Since :: 2.3

Examples:: ecore_imf_example.c.

Eina_List* evas_textblock_cursor_range_formats_get	(	const Evas_Textblock_Cursor *	cur1,
		const Evas_Textblock_Cursor *	cur2
	)

Return the format nodes in the range between cur1 and cur2.

Parameters:

cur1	one side of the range.
cur2	the other side of the range

Returns:: the foramt nodes in the range. You have to free it.

Since (EFL) :: 1.1

Since :: 2.3

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.

Since :: 2.3

Eina_Iterator* evas_textblock_cursor_range_simple_geometry_get	(	const Evas_Textblock_Cursor *	cur1,
		const Evas_Textblock_Cursor *	cur2
	)

Get the simple geometry of a range. The simple geometry is the geomtry in which rectangles in middle lines of range are merged into one big rectangle.

Since (EFL) :: 1.13

Parameters:

cur1	one side of the range.
cur2	other side of the range.

Returns:: an iterator of rectangles representing the geometry of the range.

Since :: 3.0

char* evas_textblock_cursor_range_text_get	(	const Evas_Textblock_Cursor *	cur1,
		const Evas_Textblock_Cursor *	cur2,
		Evas_Textblock_Text_Type	format
	)

Return the text in the range between cur1 and cur2

Parameters:

cur1	one side of the range.
cur2	the other side of the range
format	The form on which to return the text. Markup - in textblock markup. Plain - UTF8.

Returns:: the text in the range

See also:: elm_entry_markup_to_utf8()

Since :: 2.3

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.

Deprecated:: duplicate of evas_textblock_cursor_at_format_set

Since :: 2.3

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()

Since :: 2.3

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()

Since :: 2.3

Eina_Bool evas_textblock_cursor_visible_range_get	(	Evas_Textblock_Cursor *	start,
		Evas_Textblock_Cursor *	end
	)

Return the currently visible range.

Parameters:

start	the start of the range.
end	the end of the range.

Returns:: EINA_TRUE on success, EINA_FALSE otherwise.

Since (EFL) :: 1.1

Since :: 2.3

Eina_Bool evas_textblock_cursor_word_end ( Evas_Textblock_Cursor * obj )

Moves the cursor to the end of the word under the cursor.

Returns:: true on success, false otherwise

Since :: 2.3

Eina_Bool evas_textblock_cursor_word_start ( Evas_Textblock_Cursor * obj )

Moves the cursor to the start of the word under the cursor.

Returns:: true on success, false otherwise

Since :: 2.3

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

Since :: 2.3

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

Since :: 2.3

const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_first_get ( Evas_Object * obj )

Gets the first format node

Parameters:

obj	The textblock object.

Returns:: Returns the first format node.

Since :: 2.3

const Evas_Object_Textblock_Node_Format* evas_textblock_node_format_last_get ( Evas_Object * obj )

Gets the last format node

Parameters:

obj	The textblock object.

Returns:: Returns the first format node.

Since :: 2.3

const Eina_List* evas_textblock_node_format_list_get	(	const Evas_Object *	obj,
		const char *	anchor
	)

Gets a list of format nodes that match given format.

Parameters:

obj	The textblock object to query.
anchor	The format to find in the textblock.

Returns:: Returns a list of format nodes that match the given format.

Since :: 2.3

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.

Since :: 2.3

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.

Since :: 2.3

void evas_textblock_node_format_remove_pair	(	Evas_Object *	obj,
		Evas_Object_Textblock_Node_Format *	n
	)

Removes format node and its matching format node.

Parameters:

obj	The textblock object.
n	The format node to remove.

Returns:: Returns no value.

Since :: 2.3

const char* evas_textblock_node_format_text_get ( const Evas_Object_Textblock_Node_Format * fnode )

Get the text format representation of the format node.

Parameters:

fnode the format node.

Returns:: the textual format of the format node.

Since :: 2.3

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 part of the string that was used.

Returns:: the escaped string.

Since :: 2.3

void evas_textblock_style_free ( Evas_Textblock_Style * ts )

Destroys a textblock style.

Parameters:

ts	The textblock style to free.

Since :: 2.3

Examples:: ecore_imf_example.c.

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.

Since :: 2.3

Evas_Textblock_Style* evas_textblock_style_new ( void )

Creates a new textblock style.

Returns:: The new textblock style.

Since :: 2.3

Examples:: ecore_imf_example.c, and evas-images2.c.

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.

Since :: 2.3

Examples:: ecore_imf_example.c, and evas-images2.c.

char* evas_textblock_text_markup_to_utf8	(	const Evas_Object *	obj,
		const char *	text
	)

Return the plain version of the markup.

Works as if you set the markup to a textblock and then retrieve the plain version of the text. i.e:
and <
> will be replaced with
, &...; with the actual char and etc.

Parameters:

obj	The textblock object to work with. (if `NULL`, tries the default).
text	The markup text (if `NULL`, return `NULL`).

Returns:: An allocated plain text version of the markup.

Since (EFL) :: 1.2

Since :: 2.3

char* evas_textblock_text_utf8_to_markup	(	const Evas_Object *	obj,
		const char *	text
	)

Return the markup version of the plain text.

Replaces \n -> <br/> \t -> <tab/> and etc. Generally needed before you pass plain text to be set in a textblock.

Parameters:

obj	the textblock object to work with (if `NULL`, it just does the default behaviour, i.e with no extra object information).
text	The plain text (if `NULL`, return `NULL`).

Returns:: An allocated markup version of the plain text.

Since (EFL) :: 1.2

Since :: 2.3

Textblock Object Tutorial

Introduction

Textblock Object Cursors

Textblock Object Paragraphs

Textblock Object Format Nodes

Special Formats

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation