Page MenuHomePhabricator

Efl.Canvas.Text (Textblock 2)
Updated 560 Days AgoPublic

Efl.Canvas.Text is the next iteration of the current Evas Textblock object. It is meant to cover the basic parts of Evas Textblock, while making some of the API and functionalities obsolete (as an Evas object anyway), and passed to higher level implementations (such as the Elm Entry widget), if at all.
(Tracking task: T3340: Add Textblock2 object)

Efl.Canvas.Text API (was: Evas Textblock)

EFL Text Interface API

(Tracking task: T3381: Evas textblock: add EFL Text interface API)
Manipulation of text in the Textblock object. Only UTF-8 is supported.

/* clears and sets a text to the object. The characters U+2029 (paragraph separator)
 * and U+000A (\n - line feed) create new paragraphs and new lines, respectively. */
void efl_text_set(Evas_Object *tb, const char *text);

/* returns the current text in the object in UTF-8. */
char * efl_text_get(tb);

Annotation API

(Tracking task: T3341: Evas textblock: add annotation API)
Used for setting formats in specific ranges in the text.
Inserting an annotation will return the Evas_Textblock_Annotation handle, which can be used for performing actions on the added annotations at any stage (like edit, replace, remove).
The ranges are specified as [start, end] indices in the text.


We apply the format color=#0ff in the range [1, 5]:

Efl_Canvas_Text_Cursor *start, *end;
efl_canvas_text_cursor_pos_set(start, 1);
efl_canvas_text_cursor_pos_set(end, 5);
Efl_Canvas_Text_Annotation*an = efl_canvas_text_annotation_insert(obj, start, end, "color=#0ff");

The annotation can now be queried using calls of the annotation API with the handle an.
For example, to get the string representation of the annotation's format:

const char *fmt = efl_canvas_text_annotation_string_get(obj, an);

The string fmt will be the format we had just passed: color=#0ff.

We may want to replace the format quickly, say to change the font size rather than the color:

efl_canvas_text_annotation_set(obj, an, "font_size=14");

Removing the annotation completely will be as followed:

efl_canvas_text_annotation_del(obj, an);

The above call will remove all the formats applied by the provided annotation handle.

NOTE: del means that the handle will be freed internally, so there should not be calls with it following the above.

Object Item

These are placeholders that occupy space in the text. The legacy API had "<item>" formats to implement this functionality (as explained in the following section).
Now, it is done via object_item_insert, for example:

//current text: hello world
Efl_Canvas_Text_Cursor *cur;
efl_canvas_text_cursor_pos_set(cur, 4);
efl_canvas_text_object_item_insert(tb, cur, "size=16x16");
//text after call: hel[OBJ]lo world

API Changes (Legacy)


Format-related API is removed. These have been moved to Evas_Textblock_Legacy.h.
With annotations, formats items are now legacy, meaning that the annotation API will block the specially handled formats: <ps>, <br>, <tab>.
This special formatting will be achieved only with their Unicode counterparts (e.g. U+0029 instead of <ps>).

IMPORTANT: Format items should actually be removed as well, and a new API for this needs to be introduced. It will essentially wrap the creation of a replacement character and set an annotation on it.


Some of the cursor API is ported to Eo, and requires the object to be passed, as expected in eo:

efl_canvas_text_cursor_char_next(obj, cur);
efl_canvas_text_cursor_char_next(cur); //legacy

The following are dropped from Textblock2 Eo API (in favor of Annotation):

  • evas_textblock_cursor_markup_prepend
  • evas_textblock_cursor_format_prepend
  • evas_textblock_cursor_range_formats_get
  • evas_textblock_cursor_format_item_geometry_get
  • evas_textblock_cursor_at_format_set
  • evas_textblock_cursor_format_get
  • evas_textblock_cursor_format_is_visible_get
  • evas_textblock_cursor_format_next
  • evas_textblock_cursor_format_prev
  • evas_textblock_cursor_is_format

This saves the trouble of having to instantiate a style on our own.

Last Author
Last Edited
Jul 9 2017, 7:46 AM
id213sin, tasn