From 191ce5c22c8e651309f7e84adbba9d51c54c56c4 Mon Sep 17 00:00:00 2001 From: Dave Andreoli Date: Sun, 16 Aug 2015 12:10:46 +0200 Subject: [PATCH] Improve a bit Genlist documentation This can be improved lots more, but I'm out of time :( --- CODING | 39 +++++++++++++++++ doc/elementary/genlist.rst | 73 +++++++++++-------------------- efl/elementary/genlist_widget.pxi | 16 +++---- 3 files changed, 72 insertions(+), 56 deletions(-) diff --git a/CODING b/CODING index d01752c..8b1fed6 100644 --- a/CODING +++ b/CODING @@ -23,6 +23,45 @@ Style ...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 =============== 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 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 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 -:py:class:`~efl.elementary.list.List` object. +list (not much items) with icons and a single text, use the normal +:class:`List` object. Genlist has a fairly large API, mostly because it's relatively complex, 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 -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 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 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: -- ``item_style`` - This is a constant string and simply defines the name - of the item style. It **must** be specified and the default should be - ``"default".`` -- ``decorate_item_style`` - This is a constant string and simply defines - the name of the decorate mode item style. It is used to specify - decorate mode item style. It can be used when you call - :py:attr:`GenlistItem.decorate_mode`. -- ``decorate_all_item_style`` - This is a constant string and simply - defines the name of the decorate all item style. It is used to specify - decorate all item style. It can be used to set selection, checking and - deletion mode. This is used when you call - :py:attr:`Genlist.decorate_mode`. -- ``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 +- ``item_style`` - This is a constant string and define the name of the default + item style. It **must** be provided. +- ``decorate_item_style`` - This is a constant string and define the name of + the style to be used in the "decorate" mode. + See :attr:`GenlistItem.decorate_mode`. +- ``decorate_all_item_style`` - This is a constant string and + define the name of the style to be used in the "decorate all" mode. + See :attr:`Genlist.decorate_mode`. +- ``text_get`` - This function will be called for every text part. Should + return the text to display. See :func:`GenlistItemClass.text_get`. +- ``content_get`` - This function will be called for every content part. + Should return an object to display, the object will be deleted by the genlist on its deletion or when the item is "unrealized". See - :py:meth:`GenlistItemClass.content_get`. -- ``func.state_get`` - The ``part`` parameter is the name string of one of - the state parts in the Edje group implementing the item's theme. Return - ``False`` for false/off or ``True`` for true/on. Genlists will + :func:`GenlistItemClass.content_get`. +- ``state_get`` - This function will be called for every state part. Must + return ``True`` for false/off or ``True`` for true/on. Genlists will emit a signal to its theming Edje object with ``"elm,state,xxx,active"`` 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) 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, 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 ===================== -- ``default`` -- ``default_style`` The text part is a textblock +- ``default`` The default style: icon, text, end icon +- ``default_style`` The text part is a textblock and can use markups - ``double_label`` Two different text parts - ``icon_top_text_bottom`` - ``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 (``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`) -for more details). - 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. 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. :py:attr:`GenlistItem.next` and :py:attr:`GenlistItem.prev` get the next and previous items respectively relative to the indicated item. Using diff --git a/efl/elementary/genlist_widget.pxi b/efl/elementary/genlist_widget.pxi index f0260d4..c8f2a18 100644 --- a/efl/elementary/genlist_widget.pxi +++ b/efl/elementary/genlist_widget.pxi @@ -67,29 +67,29 @@ cdef class Genlist(Object): property mode: """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 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 - to that size. If it is ELM_LIST_COMPRESS, the item width will be fixed + ``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 (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, for instance, text block to wrap lines if the Edje part is configured 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 width changes! - .. note:: With Homogeneous mode all items in the genlist have the same - width/height. With ELM_LIST_COMPRESS the genlist items have + .. note:: With :attr:`homogeneous` mode all items in the genlist have the same + width/height. With ``ELM_LIST_COMPRESS`` the genlist items have fast initializing. However there are no sub-objects in genlist which can be on-the-fly resizable (such as TEXTBLOCK), as some 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): elm_genlist_mode_set(self.obj, mode)