Tizen Native API
Functions | Typedefs
Gengrid (Generic grid)
Elementary Widgets

Functions

Evas_Objectelm_gengrid_add (Evas_Object *parent)
 Adds a new gengrid widget to the given parent Elementary (container) object.
void elm_gengrid_clear (Evas_Object *obj)
 Removes all items from a given gengrid widget.
void elm_gengrid_multi_select_set (Evas_Object *obj, Eina_Bool multi)
 Enables or disables multi-selection in a given gengrid widget.
Eina_Bool elm_gengrid_multi_select_get (const Evas_Object *obj)
 Gets whether multi-selection is enabled or disabled for a given gengrid widget.
void elm_gengrid_horizontal_set (Evas_Object *obj, Eina_Bool horizontal)
 Sets the direction in which a given gengrid widget expands while placing its items.
Eina_Bool elm_gengrid_horizontal_get (const Evas_Object *obj)
 Gets the direction for which a given gengrid widget expands while placing its items.
Elm_Object_Itemelm_gengrid_item_append (Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data)
 Appends a new item to a given gengrid widget.
Elm_Object_Itemelm_gengrid_item_prepend (Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Evas_Smart_Cb func, const void *func_data)
 Prepends a new item to a given gengrid widget.
Elm_Object_Itemelm_gengrid_item_insert_before (Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Object_Item *relative, Evas_Smart_Cb func, const void *func_data)
 Inserts an item before another in a gengrid widget.
Elm_Object_Itemelm_gengrid_item_insert_after (Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Elm_Object_Item *relative, Evas_Smart_Cb func, const void *func_data)
 Inserts an item after another in a gengrid widget.
Elm_Object_Itemelm_gengrid_item_sorted_insert (Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data)
 Inserts an item in a gengrid widget using a user-defined sort function.
Elm_Object_Itemelm_gengrid_selected_item_get (const Evas_Object *obj)
 Gets the selected item in a given gengrid widget.
const Eina_Listelm_gengrid_selected_items_get (const Evas_Object *obj)
 Gets a list of selected items in a given gengrid.
Eina_Listelm_gengrid_realized_items_get (const Evas_Object *obj)
 Gets a list of realized items in the gengrid.
void elm_gengrid_realized_items_update (Evas_Object *obj)
 Updates the contents of all the realized items.
Elm_Object_Itemelm_gengrid_first_item_get (const Evas_Object *obj)
 Gets the first item in a given gengrid widget.
Elm_Object_Itemelm_gengrid_last_item_get (const Evas_Object *obj)
 Gets the last item in a given gengrid widget.
Elm_Object_Itemelm_gengrid_item_next_get (const Elm_Object_Item *it)
 Gets the next item in a gengrid widget's internal list of items, given that a handle to one of those items is present.
Elm_Object_Itemelm_gengrid_item_prev_get (const Elm_Object_Item *it)
 Gets the previous item in a gengrid widget's internal list of items, given that a handle to one of those items is present.
void elm_gengrid_item_selected_set (Elm_Object_Item *it, Eina_Bool selected)
 Sets whether a given gengrid item is selected.
Eina_Bool elm_gengrid_item_selected_get (const Elm_Object_Item *it)
 Gets whether a given gengrid item is selected.
void elm_gengrid_item_show (Elm_Object_Item *it, Elm_Gengrid_Item_Scrollto_Type type)
 Shows the portion of a gengrid internal grid containing a given item immediately.
void elm_gengrid_item_bring_in (Elm_Object_Item *it, Elm_Gengrid_Item_Scrollto_Type type)
 Animatedly brings a given item to the visible area of a gengrid.
void elm_gengrid_item_update (Elm_Object_Item *it)
 Updates the content of a given gengrid item.
void elm_gengrid_item_item_class_update (Elm_Object_Item *it, const Elm_Gengrid_Item_Class *gic)
 Updates the item class of a gengrid item.
const Elm_Gengrid_Item_Classelm_gengrid_item_item_class_get (const Elm_Object_Item *it)
 Gets the gengrid item class for the given gengrid item.
int elm_gengrid_item_index_get (const Elm_Object_Item *it)
 Gets the index of the item. It is only valid once it is displayed.
unsigned int elm_gengrid_items_count (const Evas_Object *obj)
 Returns the number of items that are currently in a list.
Elm_Gengrid_Item_Classelm_gengrid_item_class_new (void)
 Adds a new gengrid item class in a given gengrid widget.
void elm_gengrid_item_class_free (Elm_Gengrid_Item_Class *itc)
 Removes an item class in a given gengrid widget.
void elm_gengrid_item_class_ref (Elm_Gengrid_Item_Class *itc)
 Increments the object reference count for the item class.
void elm_gengrid_item_class_unref (Elm_Gengrid_Item_Class *itc)
 Decrements the object reference count for the item class.
void elm_gengrid_item_tooltip_text_set (Elm_Object_Item *it, const char *text)
 Sets the text to be shown in a given gengrid item's tooltips.
void elm_gengrid_item_tooltip_content_cb_set (Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb)
 Sets the content to be shown in a given gengrid item's tooltips.
void elm_gengrid_item_tooltip_unset (Elm_Object_Item *it)
 Unsets a tooltip from a given gengrid item.
void elm_gengrid_item_tooltip_style_set (Elm_Object_Item *it, const char *style)
 Sets a different style for a given gengrid item's tooltip.
const char * elm_gengrid_item_tooltip_style_get (const Elm_Object_Item *it)
 Gets the style set for a given gengrid item's tooltip.
Eina_Bool elm_gengrid_item_tooltip_window_mode_set (Elm_Object_Item *it, Eina_Bool disable)
 Disables the size restrictions on an object's tooltip.
Eina_Bool elm_gengrid_item_tooltip_window_mode_get (const Elm_Object_Item *it)
 Retrieves the size restriction state of an object's tooltip.
void elm_gengrid_item_cursor_set (Elm_Object_Item *it, const char *cursor)
 Sets the type of mouse pointer/cursor decoration to be displayed, when the mouse pointer is over the given gengrid widget item.
const char * elm_gengrid_item_cursor_get (const Elm_Object_Item *it)
 Gets the type of mouse pointer/cursor decoration set to be displayed, when the mouse pointer is over the given gengrid widget item.
void elm_gengrid_item_cursor_unset (Elm_Object_Item *it)
 Unsets any custom mouse pointer/cursor decoration set to be displayed, when the mouse pointer is over the given gengrid widget item, thus making it show the default cursor again.
void elm_gengrid_item_cursor_style_set (Elm_Object_Item *it, const char *style)
 Sets a different style for a given custom cursor set for a gengrid item.
const char * elm_gengrid_item_cursor_style_get (const Elm_Object_Item *it)
 Gets the current style set for a given gengrid item's custom cursor.
void elm_gengrid_item_cursor_engine_only_set (Elm_Object_Item *it, Eina_Bool engine_only)
 Sets whether the (custom) cursor for a given gengrid item should be searched in its theme or should only rely on the rendering engine.
Eina_Bool elm_gengrid_item_cursor_engine_only_get (const Elm_Object_Item *it)
 Gets whether the (custom) cursor for a given gengrid item is being searched in its theme or is only relying on the rendering engine.
void elm_gengrid_item_size_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h)
 Sets the size for the items of a given gengrid widget.
void elm_gengrid_item_size_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h)
 Gets the size set for the items of a given gengrid widget.
void elm_gengrid_group_item_size_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h)
 Sets the size of the group items of a given gengrid widget.
void elm_gengrid_group_item_size_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h)
 Gets the size set for the group items of a given gengrid widget.
void elm_gengrid_align_set (Evas_Object *obj, double align_x, double align_y)
 Sets the item's grid alignment within a given gengrid widget.
void elm_gengrid_align_get (const Evas_Object *obj, double *align_x, double *align_y)
 Gets the item's grid alignment values within a given gengrid widget.
void elm_gengrid_reorder_mode_set (Evas_Object *obj, Eina_Bool reorder_mode)
 Sets whether a given gengrid widget is able to have items reordered.
Eina_Bool elm_gengrid_reorder_mode_get (const Evas_Object *obj)
 Gets whether a given gengrid widget is able to have items reordered.
void elm_gengrid_page_show (const Evas_Object *obj, int h_pagenumber, int v_pagenumber)
 Shows a specific virtual region within the gengrid content object by its page number.
void elm_gengrid_item_pos_get (const Elm_Object_Item *it, unsigned int *x, unsigned int *y)
 Gets a given gengrid item's position, relative to the whole gengrid's grid area.
void elm_gengrid_filled_set (Evas_Object *obj, Eina_Bool fill)
 Sets the manner in which the items grid is filled within a given gengrid widget.
Eina_Bool elm_gengrid_filled_get (const Evas_Object *obj)
 Gets the manner in which the items grid is filled within a given gengrid widget.
void elm_gengrid_select_mode_set (Evas_Object *obj, Elm_Object_Select_Mode mode)
 Sets the gengrid select mode.
Elm_Object_Select_Mode elm_gengrid_select_mode_get (const Evas_Object *obj)
 Gets the gengrid select mode.
void elm_gengrid_highlight_mode_set (Evas_Object *obj, Eina_Bool highlight)
 Sets whether the gengrid items should be highlighted when an item is selected.
Eina_Bool elm_gengrid_highlight_mode_get (const Evas_Object *obj)
 Gets whether the gengrid items should be highlighted when an item is selected.
void elm_gengrid_item_select_mode_set (Elm_Object_Item *it, Elm_Object_Select_Mode mode)
 Sets the gengrid item's select mode.
Elm_Object_Select_Mode elm_gengrid_item_select_mode_get (const Elm_Object_Item *it)
 Gets the gengrid item's select mode.
Elm_Object_Itemelm_gengrid_at_xy_item_get (const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *xposret, int *yposret)
 Gets the item that is at the x, y canvas coordinates.

Typedefs

typedef Elm_Gen_Item_Class Elm_Gengrid_Item_Class
typedef Elm_Gen_Item_Text_Get_Cb Elm_Gengrid_Item_Text_Get_Cb
typedef Elm_Gen_Item_Content_Get_Cb Elm_Gengrid_Item_Content_Get_Cb
typedef Elm_Gen_Item_State_Get_Cb Elm_Gengrid_Item_State_Get_Cb
typedef Elm_Gen_Item_Del_Cb Elm_Gengrid_Item_Del_Cb

This widget aims to position objects in a grid layout while actually creating and rendering only the visible ones.

gengrid_inheritance_tree.png

Gengrid using the same idea as the genlist: the user defines a class for each item, specifying functions that are called at object creation, deletion, etc. When those items are selected by the user, a callback function is issued. Users may interact with the gengrid via a mouse (by clicking on items to select them and clicking on the grid's viewport and swiping to pan the whole view) or via the keyboard, navigating through items using the arrow keys.

This widget inherits from the Layout one, so that all the functions acting on it also work for gengrid objects.

This widget implements the elm-scrollable-interface interface, so that all (non-deprecated) functions for the base Scroller widget also work for gengrids.

Some calls on the gengrid's API are marked as deprecated, as they just wrap the scrollable widgets counterpart functions. Use the ones mentioned for each case of deprecation here, Eventually the deprecated ones are discarded (next major release).

Gengrid layouts

Gengrid may layout its items in one of the following two possible layouts:

When in the "horizontal mode", items are placed in columns from top to bottom and when the space for a column is filled, another one is started on the right, thus expanding the grid horizontally and allowing horizontal scrolling. When in the "vertical mode", though items are placed in rows from left to right, and when the space for a row is filled, another one is started below, thus expanding the grid vertically (and allowing vertical scrolling).

Gengrid items

An item in a gengrid can have 0 or more texts (they can be regular text or textblock Evas objects - that's up to the style to determine), 0 or more contents (which are simply objects swallowed into the gengrid item's theming Edje object) and 0 or more boolean states, which have their behavior left to the user to define. The Edje part names for each of these properties are looked up in the theme file for the gengrid, under the Edje (string) data items named "texts", "contents", and "states", respectively. For each of these properties, if more than one part is provided, they must have names listed and separated by spaces in the data fields. By default, in a gengrid item theme, we have one text part ("elm.text"), two content parts ("elm.swalllow.icon" and "elm.swallow.end"), and no state parts.

A gengrid item may have one of the several styles. Elementary provides one by default - "default", but this can be extended by the system or application custom themes/overlays/extensions (see themes for more details).

Gengrid item classes

In order to have the ability to add and delete items on the fly, gengrid implements a class (callback) system where the application provides a structure with information about that type of item (gengrid may contain multiple items of different types with different classes, states, and styles). Gengrid calls the functions in this struct (methods) when an item is "realized" (i.e., created dynamically, while the user is scrolling the grid). All objects are simply deleted when no longer needed with evas_object_del(). The Elm_Gengrid_Item_Class structure contains the following members:

Usage hints

If the user wants to have multiple items selected at the same time, elm_gengrid_multi_select_set() permits it. If the gengrid is single-selection only (the default), then elm_gengrid_select_item_get() returns the selected item, otherwise it returns NULL, if no item is selected. If the gengrid is under multi-selection, then elm_gengrid_selected_items_get() returns a list (that is only valid as long as no items are modified (added, deleted, selected, or unselected) from the child items on a gengrid.

If an item changes (internal (boolean) state, text, or content changes), then use elm_gengrid_item_update() to have gengrid update the item with the new state. A gengrid re-realizes the item, thus calling the functions in the Elm_Gengrid_Item_Class set for that item.

To programmatically (un)select an item, use elm_gengrid_item_selected_set(). To get its selected state use elm_gengrid_item_selected_get(). To disable an item (unable to be selected and appear differently) use elm_object_item_disabled_set() to set this and elm_object_item_disabled_get() to get the disabled state.

Grid cells only have their selection smart callbacks called when getting selected for the first time. Any further clicks do nothing, unless you enable the "always select mode", with elm_gengrid_select_mode_set() as ELM_OBJECT_SELECT_MODE_ALWAYS, thus making every click to issue selection callbacks. elm_gengrid_select_mode_set() as ELM_OBJECT_SELECT_MODE_NONE turns off the ability to select items entirely in the widget and they neither appear selected nor call the selection smart callbacks.

Remember that you can create new styles and add your own theme augmentation for each application using elm_theme_extension_add(). If you absolutely must have a specific style that overrides any theme the user or system sets up, you can use elm_theme_overlay_add() to add such a file.

Gengrid smart events

This widget emits the following signals, besides the ones sent from Layout :

Supported common elm_object APIs.

Supported common elm_object_item APIs.


Typedef Documentation


Enumeration Type Documentation

Enumeration that defines the type of item part.

Remarks:
It is used while updating item parts
It can be used at updating multi fields.
Enumerator:
ELM_GENGRID_ITEM_FIELD_ALL 

The item contains all fields

ELM_GENGRID_ITEM_FIELD_TEXT 

The item contains a text field

ELM_GENGRID_ITEM_FIELD_CONTENT 

The item contains a content field

ELM_GENGRID_ITEM_FIELD_STATE 

The item contains a state field

Enumeration that defines where to position the item in the gengrid.

Enumerator:
ELM_GENGRID_ITEM_SCROLLTO_NONE 

Scrolls to nowhere

ELM_GENGRID_ITEM_SCROLLTO_IN 

Scrolls to the nearest viewport

ELM_GENGRID_ITEM_SCROLLTO_TOP 

Scrolls to the top of the viewport

ELM_GENGRID_ITEM_SCROLLTO_MIDDLE 

Scrolls to the middle of the viewport


Function Documentation

Adds a new gengrid widget to the given parent Elementary (container) object.

This function inserts a new gengrid widget on the canvas.

Since :
2.3
Parameters:
[in]parentThe parent object
Returns:
A new gengrid widget handle, otherwise NULL in case of an error
See also:
elm_gengrid_item_size_set()
elm_gengrid_group_item_size_set()
elm_gengrid_horizontal_set()
elm_gengrid_item_append()
elm_object_item_del()
elm_gengrid_clear()
void elm_gengrid_align_get ( const Evas_Object obj,
double *  align_x,
double *  align_y 
)

Gets the item's grid alignment values within a given gengrid widget.

Since :
2.3
Remarks:
Use NULL pointers for the alignment values you're not interested in, they get ignored by the function.
Parameters:
[in]objThe gengrid object
[out]align_xThe pointer to a variable that stores the horizontal alignment
[out]align_yThe pointer to a variable that stores the vertical alignment
See also:
elm_gengrid_align_set()
void elm_gengrid_align_set ( Evas_Object obj,
double  align_x,
double  align_y 
)

Sets the item's grid alignment within a given gengrid widget.

This sets the alignment of the whole grid of gengrid items within its given viewport. By default, those values are both 0.5, meaning that the gengrid has its items grid placed exactly in the middle of its viewport.

Since :
2.3
Remarks:
If the given alignment values are out of the cited range, they are changed to the nearest boundary values on the valid range.
Parameters:
[in]objThe gengrid object
[in]align_xThe alignment along the horizontal axis (0 <= align_x <= 1)
[in]align_yThe alignment along the vertical axis (0 <= align_y <= 1)
See also:
elm_gengrid_align_get()
Elm_Object_Item* elm_gengrid_at_xy_item_get ( const Evas_Object obj,
Evas_Coord  x,
Evas_Coord  y,
int *  xposret,
int *  yposret 
)

Gets the item that is at the x, y canvas coordinates.

This returns the item at the given coordinates (which is canvas relative, not object-relative). If an item is at that coordinate, that item handle is returned, and if xposret is not NULL, the integer it points to is set to either -1, 0, or 1, depending on whether the coordinate is on the left portion of that item (-1), in the middle section (0), or on the right part (1). If yposret is not NULL, the integer it points to is set to either -1, 0, or 1, depending on whether the coordinate is at the upper portion of that item (-1), in the middle section (0), or at the lower part (1). If NULL is returned as an item (no item found there), then posret may indicate -1 or 1 based on whether the coordinate is above or below the items respectively in the gengrid.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]xThe input x coordinate
[in]yThe input y coordinate
[out]xposretThe position relative to the returned item
[out]yposretThe position relative to the returned item
Returns:
The item at the coordinates, otherwise NULL if no item is present
void elm_gengrid_clear ( Evas_Object obj)

Removes all items from a given gengrid widget.

This removes (and deletes) all items in obj, making it empty.

Since :
2.3
Parameters:
[in]objThe gengrid object
See also:
elm_object_item_del() to remove just one item.

Gets the manner in which the items grid is filled within a given gengrid widget.

Since :
2.3
Remarks:
Use NULL pointers for the alignment values you're not interested in, they are ignored by the function.
Parameters:
[in]objThe gengrid object
Returns:
EINA_TRUE if filled is on, otherwise EINA_FALSE if it is off
See also:
elm_gengrid_align_set() for more details
void elm_gengrid_filled_set ( Evas_Object obj,
Eina_Bool  fill 
)

Sets the manner in which the items grid is filled within a given gengrid widget.

This sets the fill state of the whole grid of items of a gengrid within its given viewport. By default, this value is false, meaning that if the first line of items grid isn't filled, the items are centered with the alignment.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]fillIf true if it is filled, otherwise false
See also:
elm_gengrid_filled_get()

Gets the first item in a given gengrid widget.

This returns the first item in the obj internal list of items.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The first item's handle, otherwise NULL if there are no items in obj (and on errors)
See also:
elm_gengrid_last_item_get()
void elm_gengrid_group_item_size_get ( const Evas_Object obj,
Evas_Coord w,
Evas_Coord h 
)

Gets the size set for the group items of a given gengrid widget.

Since :
2.3
Remarks:
Use NULL pointers for the size values you're not interested in, they get ignored by the function.
Parameters:
[in]objThe gengrid object
[out]wThe pointer to a variable that stores the group item's width
[out]hThe pointer to a variable that stores the group item's height
See also:
elm_gengrid_group_item_size_get()

Sets the size of the group items of a given gengrid widget.

Since :
2.3
Remarks:
A gengrid, after creation, still has no information on the size to give to each of its cells. So you most probably end up with squares of one finger wide, the default size. Use this function to force a custom size for your group items, making them as big as you wish.
Parameters:
[in]objThe gengrid object
[in]wThe group item's width
[in]hThe group item's height
See also:
elm_gengrid_group_item_size_get()

Gets whether the gengrid items should be highlighted when an item is selected.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
EINA_TRUE indicates that items can be highlighted, otherwise EINA_FALSE indicates that they can't
If obj is NULL, EINA_FALSE is returned.
See also:
elm_gengrid_highlight_mode_set()
void elm_gengrid_highlight_mode_set ( Evas_Object obj,
Eina_Bool  highlight 
)

Sets whether the gengrid items should be highlighted when an item is selected.

This turns on/off the highlight effect when items are selected and they either get or do not get highlighted. The selected and clicked callback functions are still called.

Since :
2.3
Remarks:
Highlighting is enabled by default.
Parameters:
[in]objThe gengrid object
[in]highlightIf EINA_TRUE highlighting is enabled, otherwise EINA_FALSE to disable it
See also:
elm_gengrid_highlight_mode_get()

Gets the direction for which a given gengrid widget expands while placing its items.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
EINA_TRUE if obj is set to expand horizontally, otherwise EINA_FALSE if it's set to expand vertically
See also:
elm_gengrid_horizontal_set()
void elm_gengrid_horizontal_set ( Evas_Object obj,
Eina_Bool  horizontal 
)

Sets the direction in which a given gengrid widget expands while placing its items.

Since :
2.3
Remarks:
When in the "horizontal mode" (EINA_TRUE), items are placed in columns from top to bottom and when the space for a column is filled, another one is started on the right, thus expanding the grid horizontally. When in the "vertical mode" (EINA_FALSE), though items are placed in rows from left to right, and when the space for a row is filled, another one is started below, thus expanding the grid vertically.
Parameters:
[in]objThe gengrid object
[in]horizontalIf EINA_TRUE the gengrid expands horizontally, otherwise EINA_FALSE to expand vertically
See also:
elm_gengrid_horizontal_get()
Elm_Object_Item* elm_gengrid_item_append ( Evas_Object obj,
const Elm_Gengrid_Item_Class gic,
const void *  data,
Evas_Smart_Cb  func,
const void *  func_data 
)

Appends a new item to a given gengrid widget.

This adds an item to the beginning of the gengrid.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]gicThe item class for the item
[in]dataThe item data
[in]funcThe convenience function that is called when the item is selected
[in]func_dataThe data to be passed to func
Returns:
A handle to the item added, otherwise NULL in case of an error
See also:
elm_gengrid_item_prepend()
elm_gengrid_item_insert_before()
elm_gengrid_item_insert_after()
elm_object_item_del()

Animatedly brings a given item to the visible area of a gengrid.

This causes gengrid to jump to the given it and show it (by scrolling), if it is not fully visible. This uses animation to do so and takes a period of time to complete.

Since :
2.3
Parameters:
[in]itThe gengrid item to display
[in]typeThe position of the item in the viewport
See also:
elm_gengrid_item_show()

Removes an item class in a given gengrid widget.

This removes the item class from the gengrid widget. Whenever it has no more references to it, the item class is freed. Otherwise it just decreases its reference count.

Since :
2.3
Parameters:
[in]itcThe itc to be removed
See also:
elm_gengrid_item_class_new()
elm_gengrid_item_class_ref()
elm_gengrid_item_class_unref()

Adds a new gengrid item class in a given gengrid widget.

This adds the gengrid item class for the gengrid widget. When adding an item, the gengrid_item_{append, prepend, insert} function needs the item class of the item. Given callback parameters are used for retrieving {text, content} of an added item. Set as NULL if it's not used. If there's no available memory, it returns NULL.

Since :
2.3
Returns:
The newly allocated gengrid item class
See also:
elm_gengrid_item_class_free()
elm_gengrid_item_append()

Increments the object reference count for the item class.

Since :
2.3
Remarks:
This API just increases its reference count for item class management.
Parameters:
[in]itcThe given item class object to reference
See also:
elm_gengrid_item_class_unref()

Decrements the object reference count for the item class.

Since :
2.3
Remarks:
This API just decreases its reference count for item class management. the reference count can't be less than 0.
Parameters:
[in]itcThe given item class object to reference
See also:
elm_gengrid_item_class_ref()
elm_gengrid_item_class_free()

Gets whether the (custom) cursor for a given gengrid item is being searched in its theme or is only relying on the rendering engine.

Since :
2.3
Parameters:
[in]itThe gengrid item
Returns:
EINA_TRUE if cursors are being looked for only from those provided by the rendering engine, otherwise EINA_FALSE if they are being searched on the widget's theme as well
See also:
elm_gengrid_item_cursor_engine_only_set()

Sets whether the (custom) cursor for a given gengrid item should be searched in its theme or should only rely on the rendering engine.

Since :
2.3
Remarks:
This call is used only if you have set a custom cursor for gengrid items using elm_gengrid_item_cursor_set().
By default, cursors are looked for only from those provided by the rendering engine.
Parameters:
[in]itThe item with custom (custom) cursor already set on it
[in]engine_onlyIf EINA_TRUE look for cursors only from those provided by the rendering engine, otherwise EINA_FALSE to have them searched on the widget's theme as well
const char* elm_gengrid_item_cursor_get ( const Elm_Object_Item it)

Gets the type of mouse pointer/cursor decoration set to be displayed, when the mouse pointer is over the given gengrid widget item.

Since :
2.3
Parameters:
[in]itThe gengrid item with a custom cursor set
Returns:
The cursor type, otherwise NULL if no custom cursors are set to it(and on errors)
See also:
elm_object_cursor_get()
elm_gengrid_item_cursor_set()
elm_gengrid_item_cursor_unset()
void elm_gengrid_item_cursor_set ( Elm_Object_Item it,
const char *  cursor 
)

Sets the type of mouse pointer/cursor decoration to be displayed, when the mouse pointer is over the given gengrid widget item.

This function is analogous to elm_object_cursor_set(), but the cursor's changing area is restricted to the item's area, and not the whole widget. Note that item cursors have precedence over widget cursors, so a mouse over it always shows the cursor type.

Since :
2.3
Remarks:
If this function is called twice for an object, a previously set cursor is unset on the second call
Parameters:
[in]itThe gengrid item on which to customize the cursor
[in]cursorThe cursor type
See also:
elm_object_cursor_set()
elm_gengrid_item_cursor_get()
elm_gengrid_item_cursor_unset()

Gets the current style set for a given gengrid item's custom cursor.

Since :
2.3
Parameters:
[in]itThe gengrid item with a custom cursor set
Returns:
style The cursor style in use
If the object does not have a cursor set, then NULL is returned.
See also:
elm_gengrid_item_cursor_style_set() for more details
void elm_gengrid_item_cursor_style_set ( Elm_Object_Item it,
const char *  style 
)

Sets a different style for a given custom cursor set for a gengrid item.

This function only makes sense when one is using customized mouse cursor decorations defined in a theme file , which can have, given a cursor name/type, alternate styles on it. It is analogous to elm_object_cursor_style_set(), but is applied only to gengrid item objects.

Since :
2.3
Remarks:
Before you set a cursor style, you should define a custom cursor on the item using elm_gengrid_item_cursor_set()
Parameters:
[in]itThe gengrid item with a custom cursor set
[in]styleThe theme style to use (e.g. "default", "transparent", etc)
See also:
elm_gengrid_item_cursor_engine_only_set()
elm_gengrid_item_cursor_style_get()

Unsets any custom mouse pointer/cursor decoration set to be displayed, when the mouse pointer is over the given gengrid widget item, thus making it show the default cursor again.

Since :
2.3
Remarks:
Use this call to undo any custom settings on this item's cursor decoration, bringing it back to the default value (no custom style set).
Parameters:
[in]itThe gengrid item
See also:
elm_object_cursor_unset()
elm_gengrid_item_cursor_set()

Gets the index of the item. It is only valid once it is displayed.

Since :
2.3
Parameters:
[in]itThe gengrid item
Returns:
The position inside the list of items
Elm_Object_Item* elm_gengrid_item_insert_after ( Evas_Object obj,
const Elm_Gengrid_Item_Class gic,
const void *  data,
Elm_Object_Item relative,
Evas_Smart_Cb  func,
const void *  func_data 
)

Inserts an item after another in a gengrid widget.

This inserts an item after another in the gengrid.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]gicThe item class for the item
[in]dataThe item data
[in]relativeThe item after which to place this new one
[in]funcThe convenience function that is called when the item is selected
[in]func_dataThe data to be passed to func
Returns:
A handle to the item added, otherwise NULL in case of an error
See also:
elm_gengrid_item_append()
elm_gengrid_item_prepend()
elm_gengrid_item_insert_after()
elm_object_item_del()
Elm_Object_Item* elm_gengrid_item_insert_before ( Evas_Object obj,
const Elm_Gengrid_Item_Class gic,
const void *  data,
Elm_Object_Item relative,
Evas_Smart_Cb  func,
const void *  func_data 
)

Inserts an item before another in a gengrid widget.

This inserts an item before another in the gengrid.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]gicThe item class for the item
[in]dataThe item data
[in]relativeThe item tbefore which to place this new one
[in]funcThe convenience function that is called when the item is selected
[in]func_dataThe data to be passed to func
Returns:
A handle to the item added, otherwise NULL in case of an error
See also:
elm_gengrid_item_append()
elm_gengrid_item_prepend()
elm_gengrid_item_insert_after()
elm_object_item_del()

Gets the gengrid item class for the given gengrid item.

This returns the Gengrid_Item_Class for the given item. It can be used to examine the function pointers and item style.

Since :
2.3
Parameters:
[in]itThe gengrid item
Returns:
The item class

Updates the item class of a gengrid item.

This sets another class of the item, changing the way it is displayed. After changing the item class, elm_gengrid_item_update() is called on the item it.

Since :
2.3
Parameters:
[in]itThe gengrid item
[in]gicThe gengrid item class describing the function pointers and the item style

Gets the next item in a gengrid widget's internal list of items, given that a handle to one of those items is present.

This returns the item placed after the it, on the container gengrid.

Since :
2.3
Parameters:
[in]itThe gengrid item to fetch next from
Returns:
The item after it, otherwise NULL if there are none (and on errors)
See also:
elm_gengrid_item_prev_get()
void elm_gengrid_item_pos_get ( const Elm_Object_Item it,
unsigned int *  x,
unsigned int *  y 
)

Gets a given gengrid item's position, relative to the whole gengrid's grid area.

This returns the "logical" position of the item within the gengrid. For example, (0, 1) would stand for the first row and the second column.

Since :
2.3
Parameters:
[in]itThe gengrid item
[out]xThe pointer to a variable that stores the item's row number
[out]yThe pointer to a variable that stores the item's column number
Elm_Object_Item* elm_gengrid_item_prepend ( Evas_Object obj,
const Elm_Gengrid_Item_Class gic,
const void *  data,
Evas_Smart_Cb  func,
const void *  func_data 
)

Prepends a new item to a given gengrid widget.

This adds an item to the end of the gengrid.

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]gicThe item class for the item
[in]dataThe item data
[in]funcThe convenience function that is called when the item is selected
[in]func_dataThe data to be passed to func
Returns:
A handle to the item added, otherwise NULL in case of an error
See also:
elm_gengrid_item_append()
elm_gengrid_item_insert_before()
elm_gengrid_item_insert_after()
elm_object_item_del()

Gets the previous item in a gengrid widget's internal list of items, given that a handle to one of those items is present.

This returns the item placed before the it, on the container gengrid.

Since :
2.3
Parameters:
[in]itThe gengrid item to fetch previous from
Returns:
The item before it, otherwise NULL if there are none (and on errors)
See also:
elm_gengrid_item_next_get()

Gets the gengrid item's select mode.

Since :
2.3
Parameters:
[in]itThe gengrid item object
Returns:
The select mode (If the getting mode fails, it returns ELM_OBJECT_SELECT_MODE_MAX)
See also:
elm_gengrid_item_select_mode_set()

Sets the gengrid item's select mode.

Since :
2.3
Remarks:
elm_gengrid_select_mode_set() changes the item's select mode.
  • ELM_OBJECT_SELECT_MODE_DEFAULT : Items only call their selection func and callback when they get selected for the first time. Any further clicks do nothing, unless you set the always select mode.
  • ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, every click calls the selected callbacks.
  • ELM_OBJECT_SELECT_MODE_NONE : This turns off the ability to select the item entirely and they neither appear selected nor call selected callback functions.
  • ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY : This applies the no-finger-size rule with ELM_OBJECT_SELECT_MODE_NONE. The no-finger-size rule makes an item smaller than the lower limit. Clickable objects should be bigger than the human touch point device (your finger) for some touch or small screen devices. Once it is enabled, the item can shrink beyond the predefined finger-size value. And the item gets updated.
Parameters:
[in]itThe gengrid item object
[in]modeThe select mode
See also:
elm_gengrid_item_select_mode_get()

Gets whether a given gengrid item is selected.

Since :
2.3
Remarks:
This API returns EINA_TRUE for all the items selected in the multi-select mode as well.
Parameters:
[in]itThe gengrid item
Returns:
EINA_TRUE if it's selected, otherwise EINA_FALSE
See also:
elm_gengrid_item_selected_set()

Sets whether a given gengrid item is selected.

This sets the selected state of an item. If multi-selection is not enabled on the containing gengrid and selected is EINA_TRUE, any other previously selected items get unselected in favor of this new one.

Since :
2.3
Parameters:
[in]itThe gengrid item
[in]selectedIf EINA_TRUE it is selected, otherwise EINA_FALSE to unselect it
See also:
elm_gengrid_item_selected_get()

Shows the portion of a gengrid internal grid containing a given item immediately.

Since :
2.3
Remarks:
This causes gengrid to redraw its viewport's contents to the region containing the given it item, if it is not fully visible.
Parameters:
[in]itThe item to display
[in]typeThe position of the item in the viewport
See also:
elm_gengrid_item_bring_in()
void elm_gengrid_item_size_get ( const Evas_Object obj,
Evas_Coord w,
Evas_Coord h 
)

Gets the size set for the items of a given gengrid widget.

Since :
2.3
Remarks:
Use NULL pointers for the size values you're not interested in, they get ignored by the function.
Parameters:
[in]objThe gengrid object
[out]wThe pointer to a variable that stores the item's width
[out]hThe pointer to a variable that stores the item's height
See also:
elm_gengrid_item_size_get() for more details

Sets the size for the items of a given gengrid widget.

Since :
2.3
Remarks:
A gengrid, after creation, still has no information on the size to give to each of its cells. So you most probably end up with squares of one finger wide, the default size. Use this function to force a custom size for your items, making them as big as you wish.
Parameters:
[in]objThe gengrid object
[in]wThe items width
[in]hThe items height
See also:
elm_gengrid_item_size_get()
Elm_Object_Item* elm_gengrid_item_sorted_insert ( Evas_Object obj,
const Elm_Gengrid_Item_Class gic,
const void *  data,
Eina_Compare_Cb  comp,
Evas_Smart_Cb  func,
const void *  func_data 
)

Inserts an item in a gengrid widget using a user-defined sort function.

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

Since :
2.3
Parameters:
[in]objThe gengrid object
[in]gicThe item class for the item
[in]dataThe item data
[in]compThe user defined comparison function that defines the sort order based on Elm_Gen_Item and its data parameter.
[in]funcThe convenience function that is called when the item is selected
[in]func_dataThe data to be passed to func
Returns:
A handle to the item added, otherwise NULL in case of an error
See also:
elm_gengrid_item_append()
elm_gengrid_item_prepend()
elm_gengrid_item_insert_after()
elm_object_item_del()

Sets the content to be shown in a given gengrid item's tooltips.

Since :
2.3
Remarks:
This call is used to setup the tooltip's content to it (analogous to elm_object_tooltip_content_cb_set(), but are item tooltips with higher precedence than object tooltips). It can have only one tooltip at a time, so any previous tooltip content is removed. func (with data) is called every time Elementary needs to display the tooltip. Moreover, it should return a valid Evas object, which is fully managed by the tooltip system and gets deleted when the tooltip is gone.
In order to set just text as a tooltip, see elm_gengrid_item_tooltip_text_set().
Parameters:
[in]itThe gengrid item
[in]funcThe function returning the tooltip contents
[in]dataThe data to provide to func as callback data/context
[in]del_cbCalled when data is not needed anymore, either when another callback replaces func, the tooltip is unset with elm_gengrid_item_tooltip_unset() or the owner it dies. This callback receives the given data as its first parameter with event_info as the item handle

Gets the style set for a given gengrid item's tooltip.

Since :
2.3
Parameters:
[in]itThe gengrid item on which the tooltip is already set
Returns:
style The theme style in use, whose default value is "default"
If the object does not have a tooltip set, then NULL is returned.
See also:
elm_gengrid_item_tooltip_style_set() for more details
void elm_gengrid_item_tooltip_style_set ( Elm_Object_Item it,
const char *  style 
)

Sets a different style for a given gengrid item's tooltip.

Since :
2.3
Remarks:
Tooltips can have alternate styles to be displayed on, which are defined by the theme set on Elementary. This function is analogous to elm_object_tooltip_style_set(), but is applied only to gengrid item objects. The default style for tooltips is "default".
Before you set a style, you should define a tooltip with elm_gengrid_item_tooltip_content_cb_set() or elm_gengrid_item_tooltip_text_set()
Parameters:
[in]itThe gengrid item with a tooltip set
[in]styleThe theme style to use on tooltips (e.g. "default", "transparent", etc)
See also:
elm_gengrid_item_tooltip_style_get()
void elm_gengrid_item_tooltip_text_set ( Elm_Object_Item it,
const char *  text 
)

Sets the text to be shown in a given gengrid item's tooltips.

Since :
2.3
Remarks:
This call is used to setup the text to be used as a tooltip for that item (analogous to elm_object_tooltip_text_set(), but are item tooltips with higher precedence than object tooltips). It can have only one tooltip at a time, so any previous tooltip data is removed.
In order to set content or something else as a tooltip, see elm_gengrid_item_tooltip_content_cb_set().
Parameters:
[in]itThe gengrid item
[in]textThe text to set in the content

Unsets a tooltip from a given gengrid item.

Since :
2.3
Remarks:
This call removes any tooltip set on item. The callback provided as del_cb to elm_gengrid_item_tooltip_content_cb_set() is called to notify that it is not used anymore (and have resources cleaned, if needed).
Parameters:
[in]itThe gengrid item from which to remove a previously set tooltip
See also:
elm_gengrid_item_tooltip_content_cb_set()

Retrieves the size restriction state of an object's tooltip.

This function returns a value that indicates whether a tooltip is allowed to expand beyond its parent window's canvas. It is instead limited only to the size of the display.

Since :
2.3
Parameters:
[in]itThe tooltip's anchor object
Returns:
EINA_TRUE if size restrictions are disabled, otherwise EINA_FALSE

Disables the size restrictions on an object's tooltip.

This function allows a tooltip to expand beyond its parent window's canvas.

Since :
2.3
Remarks:
It is instead limited only to the size of the display.
Parameters:
[in]itThe tooltip's anchor object
disableIf EINA_TRUE size restrictions are disabled, otherwise EINA_FALSE to enable it
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure

Updates the content of a given gengrid item.

This updates an item by calling all the item class functions again to get the content, text, and states. Use this when the original item data has changed and you want the changes to reflect.

Since :
2.3
Parameters:
[in]itThe gengrid item
unsigned int elm_gengrid_items_count ( const Evas_Object obj)

Returns the number of items that are currently in a list.

Since :
2.3
Remarks:
This behavior is O(1) and includes items which may or may not be realized.
Parameters:
[in]objThe list
Returns:
The total number of list items in the list

Gets the last item in a given gengrid widget.

This returns the last item in the obj internal list of items.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The last item's handle, otherwise NULL if there are no items in obj (and on errors)
See also:
elm_gengrid_first_item_get()

Gets whether multi-selection is enabled or disabled for a given gengrid widget.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
EINA_TRUE if multi-selection is enabled, otherwise EINA_FALSE
See also:
elm_gengrid_multi_select_set()
void elm_gengrid_multi_select_set ( Evas_Object obj,
Eina_Bool  multi 
)

Enables or disables multi-selection in a given gengrid widget.

Since :
2.3
Remarks:
Multi-selection is the ability to have more than one item selected, on a given gengrid, simultaneously. When it is enabled, a sequence of clicks on different items makes them all selected, progressively. A click on an already selected item unselects it. If interacting via the keyboard, multi-selection is enabled while holding the "Shift" key.
By default, multi-selection is disabled on gengrids.
Parameters:
[in]objThe gengrid object
[in]multiIf EINA_TRUE multi-selection is enabled, otherwise EINA_FALSE to disable it
See also:
elm_gengrid_multi_select_get()
void elm_gengrid_page_show ( const Evas_Object obj,
int  h_pagenumber,
int  v_pagenumber 
)

Shows a specific virtual region within the gengrid content object by its page number.

Since :
2.3
Remarks:
(0, 0) of the indicated page is located at the top-left of the viewport. This jumps to the page directly without animation.

Example of usage:

 sc = elm_gengrid_add(win);
 elm_gengrid_content_set(sc, content);
 elm_gengrid_page_relative_set(sc, 1, 0);
 elm_gengrid_current_page_get(sc, &h_page, &v_page);
 elm_gengrid_page_show(sc, h_page + 1, v_page);
Parameters:
[in]objThe gengrid object
[in]h_pagenumberThe horizontal page number
[in]v_pagenumberThe vertical page number
See also:
elm_gengrid_page_bring_in()

Gets a list of realized items in the gengrid.

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

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The list of realized items, otherwise NULL if none are realized
See also:
elm_gengrid_realized_items_update()

Updates the contents of all the realized items.

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

Since :
2.3
Remarks:
To update just one item, use elm_gengrid_item_update().
Parameters:
[in]objThe gengrid object
See also:
elm_gengrid_realized_items_get()
elm_gengrid_item_update()

Gets whether a given gengrid widget is able to have items reordered.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
EINA_TRUE if reordering is on, otherwise EINA_FALSE if it's off
See also:
elm_gengrid_reorder_mode_set()
void elm_gengrid_reorder_mode_set ( Evas_Object obj,
Eina_Bool  reorder_mode 
)

Sets whether a given gengrid widget is able to have items reordered.

Since :
2.3
Remarks:
If a gengrid is set to allow reordering, a click held for more than 0.5 over a given item highlights it specially, signaling the gengrid has entered the reordering state. From that time on, the user is able to, while still holding the mouse button down, move the item freely in the gengrid's viewport, replacing the said item by the locations it goes to. The replacements are animated and, whenever the user releases the mouse button, the item being replaced gets a new definitive place in the grid.
Parameters:
[in]objThe gengrid object
[in]reorder_modeIf EINA_TRUE reordering is turned on, otherwise EINA_FALSE to turn it off
See also:
elm_gengrid_reorder_mode_get()

Gets the gengrid select mode.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The select mode (If getting the mode fails, it returns ELM_OBJECT_SELECT_MODE_MAX)
See also:
elm_gengrid_select_mode_set()

Sets the gengrid select mode.

Since :
2.3
Remarks:
elm_gengrid_select_mode_set() changes the item select mode in the gengrid widget.
  • ELM_OBJECT_SELECT_MODE_DEFAULT : Items only call their selection func and callback when they get selected for the first time. Any further clicks do nothing, unless you set the always select mode.
  • ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, every click calls the selected callbacks.
  • ELM_OBJECT_SELECT_MODE_NONE : This turns off the ability to select items entirely and they neither appear selected nor call selected callback functions.
Parameters:
[in]objThe gengrid object
[in]modeThe select mode
See also:
elm_gengrid_select_mode_get()

Gets the selected item in a given gengrid widget.

This returns the selected item in obj. If multi selection is enabled on obj (

See also:
elm_gengrid_multi_select_set()), only the first item in the list is selected, which might not be very useful. In that case, see elm_gengrid_selected_items_get().
Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The selected item's handle, otherwise NULL if none are selected at the moment (and on errors)

Gets a list of selected items in a given gengrid.

This returns a list of the selected items, in the order that they appear in the grid. This list is only valid as long as no more items are selected or unselected (or unselected implicitly by deletion). The list contains gengrid item pointers as data, naturally.

Since :
2.3
Parameters:
[in]objThe gengrid object
Returns:
The list of selected items, otherwise NULL if none are selected at the moment (and on errors)
See also:
elm_gengrid_selected_item_get()

Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License