summaryrefslogtreecommitdiff
path: root/legacy
diff options
context:
space:
mode:
authorTom Hacohen <tom@stosb.com>2010-08-16 08:22:18 +0000
committerTom Hacohen <tom@stosb.com>2010-08-16 08:22:18 +0000
commit0f184462d1a0b62503d4c33d1fb6b6bf9fdc8391 (patch)
tree21330a5ab9b0a02767ec86fa2e5b106bf2c96709 /legacy
parente286f4874571a2b0e865abc5ffafcb040762fa16 (diff)
Evas textblock: Updated usage documentation.
SVN revision: 51166
Diffstat (limited to 'legacy')
-rw-r--r--legacy/evas/src/lib/canvas/evas_object_textblock.c70
1 files changed, 65 insertions, 5 deletions
diff --git a/legacy/evas/src/lib/canvas/evas_object_textblock.c b/legacy/evas/src/lib/canvas/evas_object_textblock.c
index 91517bf126..a252f95369 100644
--- a/legacy/evas/src/lib/canvas/evas_object_textblock.c
+++ b/legacy/evas/src/lib/canvas/evas_object_textblock.c
@@ -5,12 +5,72 @@
5 */ 5 */
6 6
7/** 7/**
8 * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
9 *
10 * This part explains about the textblock object's API and proper usage.
11 * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
12 * The main user of the textblock object is the edje entry object in Edje, so
13 * that's a good place to learn from, but I think this document is more than
14 * enough, if it's not, please request for me info and I'll update it.
15 *
16 * @subsection textblock_intro Introduction
17 * The textblock objects is, as implied, an object that can show big chunks of
18 * text. Textblock supports many features including: Text formatting, automatic
19 * and manual text alignment, embedding items (for example icons) and more.
20 * Textblock has three important parts, the text paragraphs, the format nodes
21 * and the cursors.
22 *
23 * @subsection textblock_cursors Textblock Object Cursors
24 * A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
25 * a position in a textblock. Each cursor contains information about the
26 * paragraph it points to, the position in that paragraph and the object itself.
27 * Cursors register to textblock objects upon creation, this means that once
28 * you created a cursor, it belongs to a specific obj and you can't for example
29 * copy a cursor "into" a cursor of a different object. Registered cursors
30 * also have the added benefit of updating automatically upon textblock changes,
31 * this means that if you have a cursor pointing to a specific character, it'll
32 * still point to it even after you change the whole object completely (as long
33 * as the char was not deleted), this is not possible without updating, beacuse
34 * as mentioned, each cursor holds a character position. There are many
35 * functions that handle cursors, just check out the evas_textblock_cursor*
36 * functions. For creation and deletion of cursors check out:
37 * @see evas_object_textblock_cursor_new()
38 * @see evas_textblock_cursor_free()
39 * @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).
40 *
41 * @subsection textblock_paragraphs Textblock Object Paragraphs
42 * The textblock object is made out of text splitted to paragraphs (delimited
43 * by the paragraph separation character). Each paragraph has many (or none)
44 * format nodes associated with it which are responsible for the formatting
45 * of that paragraph.
46 *
47 * @subsection textblock_format_nodes Textblock Object Format Nodes
48 * As explained in @ref textblock_paragraphs each one of the format nodes
49 * is associated with a paragraph.
50 * There are two types of format nodes, visible and invisible:
51 * Visible: formats that a cursor can point to, i.e formats that
52 * occupy space, for example: newlines, tabs, items and etc.
53 * Invisible: formats that don't occupy space, for example: bold and underline.
54 * Being able to access format nodes is very important for some uses. For
55 * example, edje uses the "<a>" format to create links in the text (and pop
56 * popups above them when clicked). For the textblock object a is just a
57 * formatting instruction (how to color the text), but edje utilizes the access
58 * to the format nodes to make it do more.
59 * For more information, take a look at all the evas_textblock_node_format_*
60 * functions.
61 *
62 * @subsection textblock_special_formats Special Formats
63 * @todo Write @textblock_special_formats
64 */
65
66/**
8 * @internal 67 * @internal
9 * @section Evas_Object_Textblock_Internal Internal Textblock Object Tutorial 68 * @section Evas_Object_Textblock_Internal Internal Textblock Object Tutorial
10 * 69 *
11 * This explains the internal design of the Evas Textblock Object. 70 * This explains the internal design of the Evas Textblock Object, it's assumed
71 * that the reader of this section has already read @ref Evas_Object_Textblock_Tutorial "Textblock's usage docs.".
12 * 72 *
13 * @subsection textblock_intro Introduction 73 * @subsection textblock_internal_intro Introduction
14 * There are two main parts to the textblock object, the first being the node 74 * There are two main parts to the textblock object, the first being the node
15 * system, and the second being the layout system. The former is just an 75 * system, and the second being the layout system. The former is just an
16 * internal representation of the markup text, while the latter is the internal 76 * internal representation of the markup text, while the latter is the internal
@@ -26,7 +86,7 @@
26 * Each text node is essentially a paragraph, it includes an @ref Eina_UStrbuf 86 * Each text node is essentially a paragraph, it includes an @ref Eina_UStrbuf
27 * that stores the actual paragraph text, a utf8 string to store the paragraph 87 * that stores the actual paragraph text, a utf8 string to store the paragraph
28 * text in utf8 (which is not used internally at all), A pointer to it's 88 * text in utf8 (which is not used internally at all), A pointer to it's
29 * main @ref textblock_nodes_format "Format Node" and the paragraph's 89 * main @ref textblock_nodes_format_internal "Format Node" and the paragraph's
30 * @ref evas_bidi_props "BiDi properties". The pointer to the format node may be 90 * @ref evas_bidi_props "BiDi properties". The pointer to the format node may be
31 * NULL if there's no format node anywhere before the end of the text node, 91 * NULL if there's no format node anywhere before the end of the text node,
32 * not even in previous text nodes. If not NULL, it points to the first format 92 * not even in previous text nodes. If not NULL, it points to the first format
@@ -37,7 +97,7 @@
37 * happens because text nodes are paragraphs and paragraphs are delimited by 97 * happens because text nodes are paragraphs and paragraphs are delimited by
38 * paragraph separators. 98 * paragraph separators.
39 * 99 *
40 * @subsection textblock_nodes_format Format Nodes 100 * @subsection textblock_nodes_format_internal Format Nodes - Internal
41 * Each format node stores a group of format information, for example the 101 * Each format node stores a group of format information, for example the
42 * markup: \<font=Vera,Kochi font_size=10 align=left\> will all be inserted 102 * markup: \<font=Vera,Kochi font_size=10 align=left\> will all be inserted
43 * inside the same format node, altohugh it consists of different formatting 103 * inside the same format node, altohugh it consists of different formatting
@@ -4251,7 +4311,7 @@ evas_object_textblock_cursor_get(const Evas_Object *obj)
4251 * to the start of the textblock. Association to the object means the cursor 4311 * to the start of the textblock. Association to the object means the cursor
4252 * will be updated when the object will change. 4312 * will be updated when the object will change.
4253 * 4313 *
4254 * @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. 4314 * @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).
4255 * 4315 *
4256 * @param obj the object to associate to. 4316 * @param obj the object to associate to.
4257 * @return the new cursor. 4317 * @return the new cursor.