Improve a bit Genlist documentation
This can be improved lots more, but I'm out of time :(
This commit is contained in:
parent
40ac305d0d
commit
191ce5c22c
39
CODING
39
CODING
|
@ -23,6 +23,45 @@ Style
|
||||||
...also because I found it more readable and I like it more :P -davemds-
|
...also because I found it more readable and I like it more :P -davemds-
|
||||||
|
|
||||||
|
|
||||||
|
Documentation cheatsheet
|
||||||
|
========================
|
||||||
|
|
||||||
|
* Links:
|
||||||
|
|
||||||
|
:class:`List` (for classes)
|
||||||
|
:func:`elm_list_go` (for functions)
|
||||||
|
:attr:`homogeneous` (for properties)
|
||||||
|
:ref:`Elm_List_Mode` (for enums)
|
||||||
|
|
||||||
|
:func:`efl.evas.Object.delete` (for items not in current scope)
|
||||||
|
:func:`~efl.evas.Object.delete` (will show it short, just "delete")
|
||||||
|
|
||||||
|
* Formatting:
|
||||||
|
|
||||||
|
``ELM_LIST_SCROLL`` (for enum values, bools and None)
|
||||||
|
|
||||||
|
|
||||||
|
* Versions:
|
||||||
|
|
||||||
|
.. versionadded:: 1.15
|
||||||
|
|
||||||
|
.. versionchanged:: 1.15
|
||||||
|
Description of the change.
|
||||||
|
|
||||||
|
.. deprecated:: 1.15
|
||||||
|
Use the blah, blah way instead.
|
||||||
|
|
||||||
|
* Notes:
|
||||||
|
|
||||||
|
.. seealso:: :py:attr:`mode`
|
||||||
|
|
||||||
|
.. note:: Some text to be noted, blah, blah, blah,
|
||||||
|
some more information for this note, etc.
|
||||||
|
|
||||||
|
.. warning:: Same as note, but the box will be red
|
||||||
|
some more information for this warning, etc.
|
||||||
|
|
||||||
|
|
||||||
Design patterns
|
Design patterns
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
|
|
@ -14,8 +14,8 @@ Elementary that could have more flexible items and allow many more
|
||||||
entries while still being fast and low on memory usage. At the same time
|
entries while still being fast and low on memory usage. At the same time
|
||||||
it was also made to be able to do tree structures. But the price to pay
|
it was also made to be able to do tree structures. But the price to pay
|
||||||
is more complexity when it comes to usage. If all you want is a simple
|
is more complexity when it comes to usage. If all you want is a simple
|
||||||
list with icons and a single text, use the normal
|
list (not much items) with icons and a single text, use the normal
|
||||||
:py:class:`~efl.elementary.list.List` object.
|
:class:`List` object.
|
||||||
|
|
||||||
Genlist has a fairly large API, mostly because it's relatively complex,
|
Genlist has a fairly large API, mostly because it's relatively complex,
|
||||||
trying to be both expansive, powerful and efficient. First we will begin
|
trying to be both expansive, powerful and efficient. First we will begin
|
||||||
|
@ -26,63 +26,45 @@ Genlist item classes - creating items
|
||||||
=====================================
|
=====================================
|
||||||
|
|
||||||
In order to have the ability to add and delete items on the fly, genlist
|
In order to have the ability to add and delete items on the fly, genlist
|
||||||
implements a class (callback) system where the application provides a
|
implements the item class (callback) system where the application provides a
|
||||||
structure with information about that type of item (genlist may contain
|
structure with information about that type of item (genlist may contain
|
||||||
multiple different items with different classes, states and styles).
|
multiple different items with different classes, states and styles).
|
||||||
Genlist will call the functions in this struct (methods) when an item is
|
Genlist will call the functions in this class (methods) when an item is
|
||||||
"realized" (i.e., created dynamically, while the user is scrolling the
|
"realized" (i.e., created dynamically, while the user is scrolling the
|
||||||
grid). All objects will simply be deleted when no longer needed with
|
grid). All objects will simply be deleted when no longer needed with
|
||||||
:py:meth:`~efl.evas.Object.delete`. :py:class:`GenlistItemClass` contains the
|
:func:`efl.evas.Object.delete`. :class:`GenlistItemClass` contains the
|
||||||
following members:
|
following members:
|
||||||
|
|
||||||
- ``item_style`` - This is a constant string and simply defines the name
|
- ``item_style`` - This is a constant string and define the name of the default
|
||||||
of the item style. It **must** be specified and the default should be
|
item style. It **must** be provided.
|
||||||
``"default".``
|
- ``decorate_item_style`` - This is a constant string and define the name of
|
||||||
- ``decorate_item_style`` - This is a constant string and simply defines
|
the style to be used in the "decorate" mode.
|
||||||
the name of the decorate mode item style. It is used to specify
|
See :attr:`GenlistItem.decorate_mode`.
|
||||||
decorate mode item style. It can be used when you call
|
- ``decorate_all_item_style`` - This is a constant string and
|
||||||
:py:attr:`GenlistItem.decorate_mode`.
|
define the name of the style to be used in the "decorate all" mode.
|
||||||
- ``decorate_all_item_style`` - This is a constant string and simply
|
See :attr:`Genlist.decorate_mode`.
|
||||||
defines the name of the decorate all item style. It is used to specify
|
- ``text_get`` - This function will be called for every text part. Should
|
||||||
decorate all item style. It can be used to set selection, checking and
|
return the text to display. See :func:`GenlistItemClass.text_get`.
|
||||||
deletion mode. This is used when you call
|
- ``content_get`` - This function will be called for every content part.
|
||||||
:py:attr:`Genlist.decorate_mode`.
|
Should return an object to display, the object will be deleted by the
|
||||||
- ``func`` - A struct with pointers to functions that will be called when
|
|
||||||
an item is going to be actually created. All of them receive a ``data``
|
|
||||||
parameter that will point to the same data passed to
|
|
||||||
:py:meth:`GenlistItem.append_to` and related item creation functions, and an
|
|
||||||
``obj`` parameter that points to the genlist object itself.
|
|
||||||
|
|
||||||
The function pointers inside ``func`` are ``text_get``, ``content_get``,
|
|
||||||
``state_get`` and ``del``. The 3 first functions also receive a ``part``
|
|
||||||
parameter described below. A brief description of these functions follows:
|
|
||||||
|
|
||||||
- ``text_get`` - The ``part`` parameter is the name string of one of the
|
|
||||||
existing text parts in the Edje group implementing the item's theme.
|
|
||||||
See :py:meth:`GenlistItemClass.text_get`.
|
|
||||||
- ``content_get`` - The ``part`` parameter is the name string of one of the
|
|
||||||
existing (content) swallow parts in the Edje group implementing the
|
|
||||||
item's theme. It must return ``None``, when no content is desired, or
|
|
||||||
a valid object handle, otherwise. The object will be deleted by the
|
|
||||||
genlist on its deletion or when the item is "unrealized". See
|
genlist on its deletion or when the item is "unrealized". See
|
||||||
:py:meth:`GenlistItemClass.content_get`.
|
:func:`GenlistItemClass.content_get`.
|
||||||
- ``func.state_get`` - The ``part`` parameter is the name string of one of
|
- ``state_get`` - This function will be called for every state part. Must
|
||||||
the state parts in the Edje group implementing the item's theme. Return
|
return ``True`` for false/off or ``True`` for true/on. Genlists will
|
||||||
``False`` for false/off or ``True`` for true/on. Genlists will
|
|
||||||
emit a signal to its theming Edje object with ``"elm,state,xxx,active"``
|
emit a signal to its theming Edje object with ``"elm,state,xxx,active"``
|
||||||
and ``"elm"`` as "emission" and "source" arguments, respectively, when
|
and ``"elm"`` as "emission" and "source" arguments, respectively, when
|
||||||
the state is true (the default is false), where ``xxx`` is the name of
|
the state is true (the default is false), where ``xxx`` is the name of
|
||||||
the (state) part. See :py:meth:`GenlistItemClass.state_get`.
|
the (state) part. See :func:`GenlistItemClass.state_get`.
|
||||||
- ``func.del`` - This is intended for use when genlist items are deleted,
|
- ``func.del`` - This is intended for use when genlist items are deleted,
|
||||||
so any data attached to the item (e.g. its data parameter on creation)
|
so any data attached to the item (e.g. its data parameter on creation)
|
||||||
can be deleted. See :py:meth:`GenlistItemClass.delete`.
|
can be deleted. See :func:`GenlistItemClass.delete`.
|
||||||
|
|
||||||
|
|
||||||
Available item styles
|
Available item styles
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
- ``default``
|
- ``default`` The default style: icon, text, end icon
|
||||||
- ``default_style`` The text part is a textblock
|
- ``default_style`` The text part is a textblock and can use markups
|
||||||
- ``double_label`` Two different text parts
|
- ``double_label`` Two different text parts
|
||||||
- ``icon_top_text_bottom``
|
- ``icon_top_text_bottom``
|
||||||
- ``group_index``
|
- ``group_index``
|
||||||
|
@ -109,11 +91,6 @@ spaces in the data fields. For the default genlist item theme, we have
|
||||||
**one** text part (``elm.text``), **two** content parts
|
**one** text part (``elm.text``), **two** content parts
|
||||||
(``elm.swallow.icon`` and ``elm.swallow.end``) and **no** state parts.
|
(``elm.swallow.icon`` and ``elm.swallow.end``) and **no** state parts.
|
||||||
|
|
||||||
A genlist item may be at one of several styles. Elementary provides one
|
|
||||||
by default - "default", but this can be extended by system or application
|
|
||||||
custom themes/overlays/extensions (see :py:mod:`themes<efl.elementary.theme>`)
|
|
||||||
for more details).
|
|
||||||
|
|
||||||
|
|
||||||
Editing and Navigating
|
Editing and Navigating
|
||||||
======================
|
======================
|
||||||
|
@ -147,7 +124,7 @@ item. :py:meth:`GenlistItem.subitems_clear` will clear all items that are
|
||||||
children of the indicated parent item.
|
children of the indicated parent item.
|
||||||
|
|
||||||
To help inspect list items you can jump to the item at the top of the list
|
To help inspect list items you can jump to the item at the top of the list
|
||||||
with :py:attr:`Genlist.first_item` which will return the item pointer, and
|
with :py:attr:`Genlist.first_item` which will return the first item, and
|
||||||
similarly :py:attr:`Genlist.last_item` gets the item at the end of the list.
|
similarly :py:attr:`Genlist.last_item` gets the item at the end of the list.
|
||||||
:py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next
|
:py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next
|
||||||
and previous items respectively relative to the indicated item. Using
|
and previous items respectively relative to the indicated item. Using
|
||||||
|
|
|
@ -67,29 +67,29 @@ cdef class Genlist(Object):
|
||||||
property mode:
|
property mode:
|
||||||
"""The mode used for sizing items horizontally.
|
"""The mode used for sizing items horizontally.
|
||||||
|
|
||||||
Default value is ELM_LIST_SCROLL. This mode means that if items are too
|
Default value is ``ELM_LIST_SCROLL``. This mode means that if items are too
|
||||||
wide to fit, the scroller will scroll horizontally. Otherwise items are
|
wide to fit, the scroller will scroll horizontally. Otherwise items are
|
||||||
expanded to fill the width of the viewport of the scroller. If it is
|
expanded to fill the width of the viewport of the scroller. If it is
|
||||||
ELM_LIST_LIMIT, items will be expanded to the viewport width and limited
|
``ELM_LIST_LIMIT``, items will be expanded to the viewport width and limited
|
||||||
to that size. If it is ELM_LIST_COMPRESS, the item width will be fixed
|
to that size. If it is ``ELM_LIST_COMPRESS``, the item width will be fixed
|
||||||
(restricted to a minimum of) to the list width when calculating its size
|
(restricted to a minimum of) to the list width when calculating its size
|
||||||
in order to allow the height to be calculated based on it. This allows,
|
in order to allow the height to be calculated based on it. This allows,
|
||||||
for instance, text block to wrap lines if the Edje part is configured
|
for instance, text block to wrap lines if the Edje part is configured
|
||||||
with "text.min: 0 1".
|
with "text.min: 0 1".
|
||||||
|
|
||||||
.. note:: ELM_LIST_COMPRESS will make list resize slower as it will
|
:type: :ref:`Elm_List_Mode`
|
||||||
|
|
||||||
|
.. note:: ``ELM_LIST_COMPRESS`` will make list resize slower as it will
|
||||||
have to recalculate every item height again whenever the list
|
have to recalculate every item height again whenever the list
|
||||||
width changes!
|
width changes!
|
||||||
|
|
||||||
.. note:: With Homogeneous mode all items in the genlist have the same
|
.. note:: With :attr:`homogeneous` mode all items in the genlist have the same
|
||||||
width/height. With ELM_LIST_COMPRESS the genlist items have
|
width/height. With ``ELM_LIST_COMPRESS`` the genlist items have
|
||||||
fast initializing. However there are no sub-objects in genlist
|
fast initializing. However there are no sub-objects in genlist
|
||||||
which can be on-the-fly resizable (such as TEXTBLOCK), as some
|
which can be on-the-fly resizable (such as TEXTBLOCK), as some
|
||||||
dynamic resizable objects would not be diplayed properly.
|
dynamic resizable objects would not be diplayed properly.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
# TODO: The above description had badly broken English, check that
|
|
||||||
# it's correct.
|
|
||||||
def __set__(self, mode):
|
def __set__(self, mode):
|
||||||
elm_genlist_mode_set(self.obj, mode)
|
elm_genlist_mode_set(self.obj, mode)
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue