path: root/src/lib/elm_genlist.eo

class Elm_Genlist (Elm_Layout, Elm_Interface_Scrollable, Evas.Clickable_Interface)
{
   eo_prefix: elm_obj_genlist;
   properties {
      homogeneous {
         set {
            /*@
            Enable/disable homogeneous mode.

            This will enable the homogeneous mode where items are of the same
            height and width so that genlist may do the lazy-loading at its
            maximum (which increases the performance for scrolling the list).
            In the normal mode, genlist will pre-calculate all the items' sizes even
            though they are not in use. So items' callbacks are called many times than
            expected. But homogeneous mode will skip the item size pre-calculation
            process so items' callbacks are called only when the item is needed.

            @note This also works well with group index.

            @see elm_genlist_mode_set()
            @see elm_genlist_homogeneous_get()

            @ingroup Genlist */
         }
         get {
            /*@
            Get whether the homogeneous mode is enabled.

            @return Assume the items within the genlist are of the same height
            and width (EINA_TRUE = on, EINA_FALSE = off)

            @see elm_genlist_homogeneous_set()

            @ingroup Genlist */
         }
         values {
            Eina_Bool homogeneous; /*@ Assume the items within the genlist are of the
            same height and width (EINA_TRUE = on, EINA_FALSE = off). Default is @c
            EINA_FALSE. */
         }
      }
      select_mode {
         set {
            /*@
            Set the genlist select mode.

            elm_genlist_select_mode_set() changes item select mode in the genlist widget.
            - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will call their selection func and
            callback once when first becoming selected. Any further clicks will
            do nothing, unless you set always select mode.
            - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected,
            every click will make the selected callbacks be called.
            - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items
            entirely and they will neither appear selected nor call selected
            callback functions.

            @see elm_genlist_select_mode_get()

            @ingroup Genlist */
         }
         get {
            /*@
            Get the genlist select mode.

            @return The select mode
            (If getting mode is failed, it returns ELM_OBJECT_SELECT_MODE_MAX)

            @see elm_genlist_select_mode_set()

            @ingroup Genlist */
         }
         values {
            Elm_Object_Select_Mode mode; /*@ The select mode */
         }
      }
      focus_on_selection {
         set {
            /*@
            Set focus upon items selection mode

            When enabled, every selection of an item inside the genlist will automatically set focus to
            its first focusable widget from the left. This is true of course if the selection was made by
            clicking an unfocusable area in an item or selecting it with a key movement. Clicking on a
            focusable widget inside an item will couse this particular item to get focus as usual.

            @ingroup Genlist */
         }
         get {
            /*@
            Get whether focus upon item's selection mode is enabled.

            @return The tree effect status
            (EINA_TRUE = enabled, EINA_FALSE = disabled)

            @ingroup Genlist */
         }
         values {
            Eina_Bool enabled; /*@ The tree effect status
            (EINA_TRUE = enabled, EINA_FALSE = disabled) */
         }
      }
      longpress_timeout {
         set {
            /*@
            Set the timeout in seconds for the longpress event.

            This option will change how long it takes to send an event "longpressed"
            after the mouse down signal is sent to the list. If this event occurs, no
            "clicked" event will be sent.

            @warning If you set the longpress timeout value with this API, your genlist
            will not be affected by the longpress value of elementary config value
            later.

            @see elm_genlist_longpress_timeout_set()

            @ingroup Genlist */
         }
         get {
            /*@
            Get the timeout in seconds for the longpress event.

            @return timeout in seconds

            @see elm_genlist_longpress_timeout_get()

            @ingroup Genlist */
         }
         values {
            double timeout; /*@ timeout in seconds. Default is elm config value(1.0) */
         }
      }
      multi_select {
         set {
            /*@
            Enable or disable multi-selection in the genlist

            This enables (@c EINA_TRUE) or disables (@c EINA_FALSE) multi-selection in
            the list. This allows more than 1 item to be selected. To retrieve the list
            of selected items, use elm_genlist_selected_items_get().

            @see elm_genlist_selected_items_get()
            @see elm_genlist_multi_select_get()

            @ingroup Genlist */
         }
         get {
            /*@
            Get if multi-selection in genlist is enabled or disabled.

            @return Multi-select enabled/disabled
            (@c EINA_TRUE = enabled/@c EINA_FALSE = disabled). Default is @c EINA_FALSE.

            @see elm_genlist_multi_select_set()

            @ingroup Genlist */
         }
         values {
            Eina_Bool multi; /*@ Multi-select enable/disable. Default is disabled. */
         }
      }
      reorder_mode {
         set {
            /*@
            Set reorder mode

            After turning on the reorder mode, longpress on normal item will trigger
            reordering of the item. You can move the item up and down. However, reorder
            does not work with group item.

            @ingroup Genlist */
         }
         get {
            /*@
            Get the reorder mode

            @return The reorder mode
            (EINA_TRUE = on, EINA_FALSE = off)

            @ingroup Genlist */
         }
         values {
            Eina_Bool reorder_mode; /*@ The reorder mode
            (EINA_TRUE = on, EINA_FALSE = off) */
         }
      }
      decorate_mode {
         set {
            /*@
            Set Genlist decorate mode

            This sets Genlist decorate mode to all items.

            @ingroup Genlist */
         }
         get {
            /*@
            Get Genlist decorate mode

            @return The decorate mode status
            (EINA_TRUE = decorate mode, EINA_FALSE = normal mode

            @ingroup Genlist */
         }
         values {
            Eina_Bool decorated; /*@ The decorate mode status
            (EINA_TRUE = decorate mode, EINA_FALSE = normal mode */
         }
      }
      multi_select_mode {
         set {
            /*@
            Set the genlist multi select mode.

            - ELM_OBJECT_MULTI_SELECT_MODE_DEFAULT : select/unselect items whenever each
            item is clicked.
            - ELM_OBJECT_MULTI_SELECT_MODE_WITH_CONTROL : Only one item will be selected
            although multi-selection is enabled, if clicked without pressing control
            key. This mode is only available with multi-selection.

            @see elm_genlist_multi_select_set()
            @see elm_genlist_multi_select_mode_get()

            @ingroup Genlist
            @since 1.8 */
         }
         get {
            /*@
            Get the genlist multi select mode.

            @return The multi select mode
            (If getting mode is failed, it returns ELM_OBJECT_MULTI_SELECT_MODE_MAX)

            @see elm_genlist_multi_select_set()
            @see elm_genlist_multi_select_mode_set()

            @ingroup Genlist
            @since 1.8 */
         }
         values {
            Elm_Object_Multi_Select_Mode mode; /*@ The multi select mode */
         }
      }
      block_count {
         set {
            /*@
            Set the maximum number of items within an item block

            This will configure the block count to tune to the target with particular
            performance matrix.

            A block of objects will be used to reduce the number of operations due to
            many objects in the screen. It can determine the visibility, or if the
            object has changed, it theme needs to be updated, etc. doing this kind of
            calculation to the entire block, instead of per object.

            The default value for the block count is enough for most lists, so unless
            you know you will have a lot of objects visible in the screen at the same
            time, don't try to change this.

            @see elm_genlist_block_count_get()
            @see @ref Genlist_Implementation

            @ingroup Genlist */
         }
         get {
            /*@
            Get the maximum number of items within an item block

            @return Maximum number of items within an item block

            @see elm_genlist_block_count_set()

            @ingroup Genlist */
         }
         values {
            int count; /*@ Maximum number of items within an item block. Default is 32. */
         }
      }
      tree_effect_enabled {
         set {
            /*@
            Set Genlist tree effect

            @ingroup Genlist */
         }
         get {
            /*@
            Get Genlist tree effect

            @return The tree effect status
            (EINA_TRUE = enabled, EINA_FALSE = disabled

            @ingroup Genlist */
         }
         values {
            Eina_Bool enabled; /*@ The tree effect status
            (EINA_TRUE = enabled, EINA_FALSE = disabled */
         }
      }
      highlight_mode {
         set {
            /*@
            Set whether the genlist items should be highlighted on item selection.

            This will turn on/off the highlight effect on item selection. The selected
            and clicked callback functions will still be called.

            Highlight is enabled by default.

            @see elm_genlist_highlight_mode_get().

            @ingroup Genlist */
         }
         get {
            /*@
            Get whether the genlist items' should be highlighted when item selected.

            @return @c EINA_TRUE means items can be highlighted. @c EINA_FALSE indicates
            they can't. If @p obj is @c NULL, @c EINA_FALSE is returned.

            @see elm_genlist_highlight_mode_set() for details.

            @ingroup Genlist */
         }
         values {
            Eina_Bool highlight; /*@ @c EINA_TRUE to enable highlighting or @c EINA_FALSE to
            disable it. */
         }
      }
      mode {
         set {
            /*@
            This sets the horizontal stretching mode.

            This sets the mode used for sizing items horizontally. Valid modes
            are #ELM_LIST_LIMIT, #ELM_LIST_SCROLL, and #ELM_LIST_COMPRESS. The default 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 (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 have to
            recalculate every item height again whenever the list width
            changes!
            @note Homogeneous mode is for that all items in the genlist same
            width/height. With ELM_LIST_COMPRESS, it makes genlist items to fast
            initializing. However there's no sub-objects in genlist which can be
            on the flying resizable (such as TEXTBLOCK). If then, some dynamic
            resizable objects in genlist would not diplayed properly.

            @see elm_genlist_mode_get()

            @ingroup Genlist */
         }
         get {
            /*@
            Get the horizontal stretching mode.

            @return The mode to use
            (#ELM_LIST_LIMIT, #ELM_LIST_SCROLL)

            @see elm_genlist_mode_set()

            @ingroup Genlist */
         }
         values {
            Elm_List_Mode mode; /*@ The mode to use (one of #ELM_LIST_SCROLL or #ELM_LIST_LIMIT). */
         }
      }
      decorated_item {
         get {
            /*@
            Get active genlist mode item

            @return The active item for that current mode. Or @c NULL if no item is
            activated with any mode.

            This function returns the item that was activated with a mode, by the
            function elm_genlist_item_decorate_mode_set().

            @see elm_genlist_item_decorate_mode_set()
            @see elm_genlist_mode_get()

            @ingroup Genlist */
            return Elm_Object_Item *;
         }
      }
      selected_item {
         get {
            /*@
            Get the selected item in the genlist.

            @return The selected item, or NULL if none is selected.

            This gets the selected item in the list (if multi-selection is enabled, only
            the item that was first selected in the list is returned - which is not very
            useful, so see elm_genlist_selected_items_get() for when multi-selection is
            used).

            If no item is selected, NULL is returned.

            @see elm_genlist_selected_items_get()

            @ingroup Genlist */
            return Elm_Object_Item *;
         }
      }
      first_item {
         get {
            /*@
            Get the first item in the genlist

            This returns the first item in the list.

            @return The first item, or NULL if none

            @ingroup Genlist */
            return Elm_Object_Item *;
         }
      }
      realized_items {
         get {
            /*@
            Get a list of realized items in genlist

            @return The list of realized items, nor NULL if none are realized.

            This returns a list of the realized items in the genlist. The list
            contains genlist item pointers. The list must be freed by the
            caller when done with eina_list_free(). The item pointers in the
            list are only valid so long as those items are not deleted or the
            genlist is not deleted.

            @see elm_genlist_realized_items_update()

            @ingroup Genlist */
            return Eina_List *;
         }
      }
      selected_items {
         get {
            /*@
            Get a list of selected items in the genlist.

            @return The list of selected items, or NULL if none are selected.

            It returns a list of the selected items. This list pointer is only valid so
            long as the selection doesn't change (no items are selected or unselected, or
            unselected implicitly by deletion). The list contains genlist items
            pointers. The order of the items in this list is the order which they were
            selected, i.e. the first item in this list is the first item that was
            selected, and so on.

            @note If not in multi-select mode, consider using function
            elm_genlist_selected_item_get() instead.

            @see elm_genlist_multi_select_set()
            @see elm_genlist_selected_item_get()

            @ingroup Genlist */
            return const Eina_List *;
         }
      }
      last_item {
         get {
            /*@
            Get the last item in the genlist

            This returns the last item in the list.

            @return The last item, or NULL if none

            @ingroup Genlist */
            return Elm_Object_Item *;
         }
      }
   }
   methods {
      item_insert_before {
         /*@
         Insert an item before another in a genlist widget

         @return A handle to the item added or @c NULL if not possible

         This inserts an item before another in the list. It will be in the
         same tree level or group as the item it is inserted before.

         @see elm_genlist_item_append()
         @see elm_genlist_item_prepend()
         @see elm_genlist_item_insert_after()
         @see elm_object_item_del()

         @ingroup Genlist */

         return Elm_Object_Item *;
         params {
            @in const Elm_Genlist_Item_Class *itc; /*@ The item class for the item */
            @in const void *data; /*@ The item data */
            @in Elm_Object_Item *parent; /*@ The parent item, or NULL if none */
            @in Elm_Object_Item *before_it; /*@ The item to place this new one before. */
            @in Elm_Genlist_Item_Type type; /*@ Item type */
            @in Evas_Smart_Cb func; /*@ Convenience function called when the item is selected */
            @in const void *func_data; /*@ Data passed to @p func above. */
         }
      }
      realized_items_update {
         /*@
         Update the contents of all realized items.

         This updates all realized items by calling all the item class functions again
         to get the contents, texts and states. Use this when the original
         item data has changed and the changes are desired to be reflected.

         To update just one item, use elm_genlist_item_update().

         @see elm_genlist_realized_items_get()
         @see elm_genlist_item_update()

         @ingroup Genlist */

      }
      item_insert_after {
         /*@
         Insert an item after another in a genlist widget

         @return A handle to the item added or @c NULL if not possible

         This inserts an item after another in the list. It will be in the
         same tree level or group as the item it is inserted after.

         @see elm_genlist_item_append()
         @see elm_genlist_item_prepend()
         @see elm_genlist_item_insert_before()
         @see elm_object_item_del()

         @ingroup Genlist */

         return Elm_Object_Item *;
         params {
            @in const Elm_Genlist_Item_Class *itc; /*@ The item class for the item */
            @in const void *data; /*@ The item data */
            @in Elm_Object_Item *parent; /*@ The parent item, or NULL if none */
            @in Elm_Object_Item *after_it; /*@ The item to place this new one after. */
            @in Elm_Genlist_Item_Type type; /*@ Item type */
            @in Evas_Smart_Cb func; /*@ Convenience function called when the item is selected */
            @in const void *func_data; /*@ Data passed to @p func above. */
         }
      }
      at_xy_item_get {
         /*@
         Get the item that is at the x, y canvas coords.

         @return The item at the coordinates or NULL if none

         This returns the item at the given coordinates (which are canvas
         relative, not object-relative). If an item is at that coordinate,
         that item handle is returned, and if @p posret is not NULL, the
         integer pointed to is set to a value of -1, 0 or 1, depending if
         the coordinate is on the upper portion of that item (-1), on the
         middle section (0) or on the lower part (1). If NULL is returned as
         an item (no item found there), then posret may indicate -1 or 1
         based if the coordinate is above or below all items respectively in
         the genlist.

         @ingroup Genlist */

         const;
         return Elm_Object_Item *;
         params {
            @in Evas_Coord x; /*@ The input x coordinate */
            @in Evas_Coord y; /*@ The input y coordinate */
            @out int posret; /*@ The position relative to the item returned here */
         }
      }
      items_count {
         /*@
         Return how many items are currently in a list

         @return The total number of list items in the list

         This behavior is O(1) and includes items which may or may not be realized.

         @ingroup Genlist */

         const;
         return unsigned int;
      }
      item_prepend {
         /*@
         Prepend a new item in a given genlist widget.

         @return A handle to the item added or NULL if not possible

         This adds an item to the beginning of the list or beginning of the
         children of the parent if given.

         @see elm_genlist_item_append()
         @see elm_genlist_item_insert_before()
         @see elm_genlist_item_insert_after()
         @see elm_object_item_del()

         @ingroup Genlist */

         return Elm_Object_Item *;
         params {
            @in const Elm_Genlist_Item_Class *itc; /*@ The item class for the item */
            @in const void *data; /*@ The item data */
            @in Elm_Object_Item *parent; /*@ The parent item, or NULL if none */
            @in Elm_Genlist_Item_Type type; /*@ Item type */
            @in Evas_Smart_Cb func; /*@ Convenience function called when the item is selected */
            @in const void *func_data; /*@ Data passed to @p func above. */
         }
      }
      clear {
         /*@
         Remove all items from a given genlist widget.

         This removes (and deletes) all items in @p obj, leaving it empty.

         @see elm_object_item_del(), to remove just one item.

         @ingroup Genlist */

      }
      item_append {
         /*@
         Append a new item in a given genlist widget.

         @return A handle to the item added or @c NULL if not possible

         This adds the given item to the end of the list or the end of
         the children list if the @p parent is given.

         @see elm_genlist_item_prepend()
         @see elm_genlist_item_insert_before()
         @see elm_genlist_item_insert_after()
         @see elm_object_item_del()

         @ingroup Genlist */

         return Elm_Object_Item *;
         params {
            @in const Elm_Genlist_Item_Class *itc; /*@ The item class for the item */
            @in const void *data; /*@ The item data */
            @in Elm_Object_Item *parent; /*@ The parent item, or NULL if none */
            @in Elm_Genlist_Item_Type type; /*@ Item type */
            @in Evas_Smart_Cb func; /*@ Convenience function called when the item is selected */
            @in const void *func_data; /*@ Data passed to @p func above. */
         }
      }
      item_sorted_insert {
         /*@
         Insert a new item into the sorted genlist object

         @return A handle to the item added or NULL if not possible

         This inserts an item in the genlist based on user defined comparison
         function. The two arguments passed to the function @p func are genlist item
         handles to compare.

         @see elm_genlist_item_append()
         @see elm_genlist_item_prepend()
         @see elm_genlist_item_insert_after()
         @see elm_object_item_del()

         @ingroup Genlist */

         return Elm_Object_Item *;
         params {
            @in const Elm_Genlist_Item_Class *itc; /*@ The item class for the item */
            @in const void *data; /*@ The item data */
            @in Elm_Object_Item *parent; /*@ The parent item, or NULL if none */
            @in Elm_Genlist_Item_Type type; /*@ Item type */
            @in Eina_Compare_Cb comp; /*@ The function called for the sort */
            @in Evas_Smart_Cb func; /*@ Convenience function called when item selected */
            @in const void *func_data; /*@ Data passed to @p func above. */
         }
      }
      search_by_text_item_get {
         /*@
         Get genlist item by given string.

         @return Pointer to the genlist item which matches search_string in case of success, otherwise returns NULL.

         This function takes pointer to the function that returns
         comparison string for item (it could be the same function as used for setting text for labels).
         Also it takes pointer to the genlist item that will be used to start search from it.

         This function uses fnmatch() for searching and takes it's seatcing flags as last parameter.
         The list of available flags:
         <dl>
            <dt>FNM_NOESCAPE</dt>
            <dd>If this flag is set, treat backslash as an ordinary character, instead of an escape character.</dd>
            <dt>FNM_PATHNAME</dt>
            <dd>If this flag is set, match a slash in string only with a slash in pattern and not by an asterisk (*)
                or a question mark (?) metacharacter, nor by a bracket expression ([]) containing a slash.</dd>
            <dt>FNM_PERIOD</dt>
            <dd>If this flag is set, a leading period in string has to be matched exactly by a period in pattern.
                A period is considered to be leading if it is the first character in string, or if both
                FNM_PATHNAME is set and the period immediately follows a slash.</dd>
            <dt>FNM_FILE_NAME</dt>
            <dd>This is a GNU synonym for FNM_PATHNAME.</dd>
            <dt>FNM_LEADING_DIR</dt>
            <dd>If this flag (a GNU extension) is set, the pattern is considered to be matched if it matches an
                initial segment of string which is followed by a slash. This flag is mainly for the internal
                use of glibc and is only implemented in certain cases.</dd>
            <dt>FNM_CASEFOLD</dt>
            <dd>If this flag (a GNU extension) is set, the pattern is matched case-insensitively.</dd>
         </dl>
         For more details see <a href=http://man7.org/linux/man-pages/man3/fnmatch.3.html>Linux Programmer's Manual. FNMATCH()</a>

         @ingroup Genlist
         @since 1.10 */

         return Elm_Object_Item *;
         params {
            @in Elm_Object_Item * item_to_search_from; /*@ Pointer to item to start search from. If NULL search will be started from the first item of the genlist. */
            @in Elm_Gen_Item_Text_Get_Cb _text_get; /*@ Pointer to Elm_Gen_Item_Text_Get_Cb function to get text for comparison. */
            @in const char * part_name; /*@ Name of the TEXT part of genlist item to search string in. */
            @in const char * pattern; /*@ The search pattern. */
            @in int flags; /*@ fnmatch search flags */
         }
      }
   }
   implements {
      class.constructor;
      Eo.Base.constructor;
      Evas.Object_Smart.member_add;
      Evas.Object_Smart.move;
      Evas.Object_Smart.add;
      Evas.Object_Smart.del;
      Evas.Object_Smart.resize;
      Elm_Widget.theme_apply;
      Elm_Widget.focus_next_manager_is;
      Elm_Widget.sub_object_add;
      Elm_Widget.access;
      Elm_Widget.focus_highlight_geometry_get;
      Elm_Widget.focus_next;
      Elm_Widget.on_focus;
      Elm_Widget.focus_direction_manager_is;
      Elm_Widget.sub_object_del;
      Elm_Widget.event;
      Elm_Widget.focused_item.get;
      Elm_Widget.item_loop_enabled.set;
      Elm_Widget.item_loop_enabled.get;
      Elm_Layout.sub_object_add_enable;
      Elm_Layout.sizing_eval;
      Elm_Interface_Scrollable.bounce_allow;
      Elm_Interface_Scrollable.policy;
   }
   events {
      language,changed;
      access,changed;
      focused;
      unfocused;
      item,focused;
      item,unfocused;
   }

}