summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDave Andreoli <dave@gurumeditation.it>2015-08-16 12:10:46 +0200
committerDave Andreoli <dave@gurumeditation.it>2015-08-16 12:10:46 +0200
commit191ce5c22c8e651309f7e84adbba9d51c54c56c4 (patch)
tree468feaa7b0f9a8b36af6aa91cbfc5d5475ecbc3c /doc
parent40ac305d0dd586d29230cc71aedf501fbfb0d376 (diff)
Improve a bit Genlist documentation
This can be improved lots more, but I'm out of time :(
Diffstat (limited to 'doc')
-rw-r--r--doc/elementary/genlist.rst73
1 files changed, 25 insertions, 48 deletions
diff --git a/doc/elementary/genlist.rst b/doc/elementary/genlist.rst
index 493a06c..53a6b6c 100644
--- a/doc/elementary/genlist.rst
+++ b/doc/elementary/genlist.rst
@@ -14,8 +14,8 @@ Elementary that could have more flexible items and allow many more
14entries while still being fast and low on memory usage. At the same time 14entries while still being fast and low on memory usage. At the same time
15it was also made to be able to do tree structures. But the price to pay 15it was also made to be able to do tree structures. But the price to pay
16is more complexity when it comes to usage. If all you want is a simple 16is more complexity when it comes to usage. If all you want is a simple
17list with icons and a single text, use the normal 17list (not much items) with icons and a single text, use the normal
18:py:class:`~efl.elementary.list.List` object. 18:class:`List` object.
19 19
20Genlist has a fairly large API, mostly because it's relatively complex, 20Genlist has a fairly large API, mostly because it's relatively complex,
21trying to be both expansive, powerful and efficient. First we will begin 21trying to be both expansive, powerful and efficient. First we will begin
@@ -26,63 +26,45 @@ Genlist item classes - creating items
26===================================== 26=====================================
27 27
28In order to have the ability to add and delete items on the fly, genlist 28In order to have the ability to add and delete items on the fly, genlist
29implements a class (callback) system where the application provides a 29implements the item class (callback) system where the application provides a
30structure with information about that type of item (genlist may contain 30structure with information about that type of item (genlist may contain
31multiple different items with different classes, states and styles). 31multiple different items with different classes, states and styles).
32Genlist will call the functions in this struct (methods) when an item is 32Genlist will call the functions in this class (methods) when an item is
33"realized" (i.e., created dynamically, while the user is scrolling the 33"realized" (i.e., created dynamically, while the user is scrolling the
34grid). All objects will simply be deleted when no longer needed with 34grid). All objects will simply be deleted when no longer needed with
35:py:meth:`~efl.evas.Object.delete`. :py:class:`GenlistItemClass` contains the 35:func:`efl.evas.Object.delete`. :class:`GenlistItemClass` contains the
36following members: 36following members:
37 37
38- ``item_style`` - This is a constant string and simply defines the name 38- ``item_style`` - This is a constant string and define the name of the default
39 of the item style. It **must** be specified and the default should be 39 item style. It **must** be provided.
40 ``"default".`` 40- ``decorate_item_style`` - This is a constant string and define the name of
41- ``decorate_item_style`` - This is a constant string and simply defines 41 the style to be used in the "decorate" mode.
42 the name of the decorate mode item style. It is used to specify 42 See :attr:`GenlistItem.decorate_mode`.
43 decorate mode item style. It can be used when you call 43- ``decorate_all_item_style`` - This is a constant string and
44 :py:attr:`GenlistItem.decorate_mode`. 44 define the name of the style to be used in the "decorate all" mode.
45- ``decorate_all_item_style`` - This is a constant string and simply 45 See :attr:`Genlist.decorate_mode`.
46 defines the name of the decorate all item style. It is used to specify 46- ``text_get`` - This function will be called for every text part. Should
47 decorate all item style. It can be used to set selection, checking and 47 return the text to display. See :func:`GenlistItemClass.text_get`.
48 deletion mode. This is used when you call 48- ``content_get`` - This function will be called for every content part.
49 :py:attr:`Genlist.decorate_mode`. 49 Should return an object to display, the object will be deleted by the
50- ``func`` - A struct with pointers to functions that will be called when
51 an item is going to be actually created. All of them receive a ``data``
52 parameter that will point to the same data passed to
53 :py:meth:`GenlistItem.append_to` and related item creation functions, and an
54 ``obj`` parameter that points to the genlist object itself.
55
56The function pointers inside ``func`` are ``text_get``, ``content_get``,
57``state_get`` and ``del``. The 3 first functions also receive a ``part``
58parameter described below. A brief description of these functions follows:
59
60- ``text_get`` - The ``part`` parameter is the name string of one of the
61 existing text parts in the Edje group implementing the item's theme.
62 See :py:meth:`GenlistItemClass.text_get`.
63- ``content_get`` - The ``part`` parameter is the name string of one of the
64 existing (content) swallow parts in the Edje group implementing the
65 item's theme. It must return ``None``, when no content is desired, or
66 a valid object handle, otherwise. The object will be deleted by the
67 genlist on its deletion or when the item is "unrealized". See 50 genlist on its deletion or when the item is "unrealized". See
68 :py:meth:`GenlistItemClass.content_get`. 51 :func:`GenlistItemClass.content_get`.
69- ``func.state_get`` - The ``part`` parameter is the name string of one of 52- ``state_get`` - This function will be called for every state part. Must
70 the state parts in the Edje group implementing the item's theme. Return 53 return ``True`` for false/off or ``True`` for true/on. Genlists will
71 ``False`` for false/off or ``True`` for true/on. Genlists will
72 emit a signal to its theming Edje object with ``"elm,state,xxx,active"`` 54 emit a signal to its theming Edje object with ``"elm,state,xxx,active"``
73 and ``"elm"`` as "emission" and "source" arguments, respectively, when 55 and ``"elm"`` as "emission" and "source" arguments, respectively, when
74 the state is true (the default is false), where ``xxx`` is the name of 56 the state is true (the default is false), where ``xxx`` is the name of
75 the (state) part. See :py:meth:`GenlistItemClass.state_get`. 57 the (state) part. See :func:`GenlistItemClass.state_get`.
76- ``func.del`` - This is intended for use when genlist items are deleted, 58- ``func.del`` - This is intended for use when genlist items are deleted,
77 so any data attached to the item (e.g. its data parameter on creation) 59 so any data attached to the item (e.g. its data parameter on creation)
78 can be deleted. See :py:meth:`GenlistItemClass.delete`. 60 can be deleted. See :func:`GenlistItemClass.delete`.
79 61
80 62
81Available item styles 63Available item styles
82===================== 64=====================
83 65
84- ``default`` 66- ``default`` The default style: icon, text, end icon
85- ``default_style`` The text part is a textblock 67- ``default_style`` The text part is a textblock and can use markups
86- ``double_label`` Two different text parts 68- ``double_label`` Two different text parts
87- ``icon_top_text_bottom`` 69- ``icon_top_text_bottom``
88- ``group_index`` 70- ``group_index``
@@ -109,11 +91,6 @@ spaces in the data fields. For the default genlist item theme, we have
109**one** text part (``elm.text``), **two** content parts 91**one** text part (``elm.text``), **two** content parts
110(``elm.swallow.icon`` and ``elm.swallow.end``) and **no** state parts. 92(``elm.swallow.icon`` and ``elm.swallow.end``) and **no** state parts.
111 93
112A genlist item may be at one of several styles. Elementary provides one
113by default - "default", but this can be extended by system or application
114custom themes/overlays/extensions (see :py:mod:`themes<efl.elementary.theme>`)
115for more details).
116
117 94
118Editing and Navigating 95Editing and Navigating
119====================== 96======================
@@ -147,7 +124,7 @@ item. :py:meth:`GenlistItem.subitems_clear` will clear all items that are
147children of the indicated parent item. 124children of the indicated parent item.
148 125
149To help inspect list items you can jump to the item at the top of the list 126To help inspect list items you can jump to the item at the top of the list
150with :py:attr:`Genlist.first_item` which will return the item pointer, and 127with :py:attr:`Genlist.first_item` which will return the first item, and
151similarly :py:attr:`Genlist.last_item` gets the item at the end of the list. 128similarly :py:attr:`Genlist.last_item` gets the item at the end of the list.
152:py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next 129:py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next
153and previous items respectively relative to the indicated item. Using 130and previous items respectively relative to the indicated item. Using