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)
(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);
(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:
The above call will remove all the formats applied by the provided annotation handle.
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
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>).
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); //vs. efl_canvas_text_cursor_char_next(cur); //legacy
The following are dropped from Textblock2 Eo API (in favor of Annotation):
This saves the trouble of having to instantiate a style on our own.