Gengrid

This feature is supported in mobile applications only.

Gengrid component is based on the same idea as the genlist. It aims at displaying objects on a grid layout and rendering only the visible ones. Similar to the genlist, callbacks are called at item creation or deletion.

The gengrid component inherits from the layout component and implements the scroller interface, which means that scroller and layout functions can be used with the gengrid component.

For more information, see the Gengrid API.

A gengrid can display its items using a horizontal or vertical layout. In the horizontal layout, the items are displayed in columns from top to bottom, starting a new column when the space for the current column is filled. In the vertical layout, items are set in rows from left to right.

Figure: Gengrid component

Figure: Gengrid hierarchy

Adding a Gengrid Component

To add a gengrid component, use the elm_gengrid_add() function:

Evas_Object *gengrid, *parent;
gengrid = elm_gengrid_add(parent);

Using Gengrid and Item Styles

The following gengrid styles and related item styles are supported:

• default
  • default
  • type1 (identical to the default style in Tizen 2.4)
  • type2
• popup
  • default

To use the popup gengrid style with the default item style:

elm_object_style_set(gengrid, "popup");
gic->item_style = "default";

The following figure shows examples of the default (type1), type2, and popup styles.

Figure: Gengrid styles

Creating and Deleting Items

A gengrid item is composed of 0 or more texts, 0 or more contents, and 0 or more boolean states. The number of texts and contents depends on the theme used for the gengrid items. In the default Tizen gengrid item theme, the items can have 2 content parts that can be set with the elm.swallow.icon and elm.swallow.end part names.

As in the genlist, to save up memory and speed up processing when many items exist, the gengrid has the concept of realization when managing items. It means that a gengrid item creates its text and content when the item shows up on the display (realize), and frees them when the item is scrolled out of the screen (unrealize). Text and content are retrieved by calling the text_get and content_get functions defined in the gengrid item class.

You can use the Elm_Gengrid_Item_Class for the following purposes:

• Setting the item style
• Registering callback functions for item realization
• Registering a callback function for item deletion

static Elm_Gengrid_Item_Class *gic = elm_gengrid_item_class_new();
int i;

gic->item_style = "default"; 
gic->func.text_get = _item_label_get;
gic->func.content_get = _item_content_get;
gic->func.del = _item_del;

for (i = 0; i < 10; i++)
{
   elm_gengrid_item_append(gengrid, // Gengrid object
                           gic, // Gengrid item class
                           (void *)i, // Item data
                           _item_select, // Select callback
                           (void *)i); // Callback data
}
elm_gengrid_item_class_free(gic);

The func structure in the gengrid item class contains pointers to functions that are called when an item is going to be realized or deleted. All of them receive item data (third parameter of the elm_gengrid_item_append() function) as their first parameter and the gengrid object itself as the second parameter.

The gengrid item class must be freed manually with the elm_gengrid_item_class_free() function after appending items is finished. To delete a gengrid item, use the elm_object_item_del() function. You can also use the elm_gengrid_clear() function to clear all items. If a gengrid object is deleted by the evas_object_del() function, all items are deleted automatically. On item deletion, the del function in the item class is called.

• text_get

  When a gengrid item becomes realized, the text_get function is called repeatedly for all text parts in that item. This function can return text with the strdup() function when the desired part is found. After the text is set to the part, it is freed automatically (do not free it manually).

  static char *
  _item_label_get(void *data, Evas_Object *obj, const char *part)
  {
     if (!strcmp(part, "elm.text"))
        return strdup("text");
     else return NULL;
  }
  

• content_get

  As the text_get function, the content_get function is also called repeatedly for all swallow parts in the item. When no content is desired, it must return NULL, or a valid object handle to be set. The object is deleted by the gengrid on its deletion or when the item is unrealized.

  static Evas_Object *
  _item_content_get(void *data, Evas_Object *obj, const char *part)
  {
     if (!strcmp(part, "elm.swallow.icon"))
     {
        Evas_Object *img = elm_image_add(obj);
        elm_image_file_Set(img, "sample.png", NULL);
  
        return img;
     }
     else return NULL;
  } 
  

• del

  This function is called when the gengrid item is deleted. It deletes any data which were allocated at the item creation.

  static void
  _item_del(void *data, Evas_Object *obj)
  {
     printf("item(%d) is now deleted", (int) data);
  }
  

Managing Items

To manage the items:

• Add items:

  As with genlists, items can be added with the elm_gengrid_item_append(), elm_gengrid_item_prepend(), elm_gengrid_item_insert_before(), and elm_gengrid_item_insert_after() functions. With the gengrid, there is no need to pass the type parameters. They can be cleared with the elm_gengrid_clear() function.

• Select multiple items:

  To select multiple items, use the multiselection mode:

  elm_gengrid_multi_select_set(gengrid, EINA_TRUE);
  

  When the multiselection mode is on, the selected items are retrieved with the elm_gengrid_selected_items_get() function. The function returns a list of all selected items.

• Update items:

  When the content of an item changes, you can call the elm_gengrid_item_update() function to ask the gengrid to update this item. The gengrid re-realizes the item and calls the functions in the _Elm_Gengrid_Item_Class for it.

  If you want to change some parts of the items, you can also use the elm_gengrid_item_fields_update() function for the specific parts:

  • ELM_GENGRID_ITEM_FIELD_TEXT
  • ELM_GENGRID_ITEM_FIELD_CONTENT
  • ELM_GENGRID_ITEM_FIELD_STATE
• Select or disable items:

  It is also possible to select or disable some items manually with the elm_gengrid_item_selected_set() and elm_object_item_disabled_set() functions.

Using Gengrid Callbacks

The gengrid component emits the following signals:

• activated: The item is double-clicked or pressed (enter | return | spacebar). The event_info parameter is the gengrid item that is activated.
• clicked,double: The item is double-clicked. The event_info parameter is the gengrid item that is double-clicked.
• clicked,right: The item is right-clicked. The event_info parameter is the gengrid item that is right-clicked.
• longpressed: The item is pressed for a certain amount of time. By default it is one second.
• selected: The item is selected. The event_info parameter is the gengrid item that is selected.
• unselected: The item is unselected. The event_info parameter is the gengrid item that is unselected.
• realized: The item is created as a real evas object. The event_info parameter in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• unrealized: The item is going to be unrealized. Content objects provided are deleted and the item object is deleted or put into a floating cache. The event_info parameter in the callback function points at an object of the type Elm_Object_Item that contains the activated item.
• changed: An item is added, removed, resized or moved and the gengrid is resized or has horizontal property changes.
• scroll,anim,start: Scrolling animation starts.
• scroll,anim,stop: Scrolling animation stops.
• drag,start,up: The item in the gengrid is dragged (not scrolled) up.
• drag,start,down: The item in the gengrid has dragged (not scrolled) down.
• drag,start,left: The item in the gengrid is dragged (not scrolled) left.
• drag,start,right: The item in the gengrid is dragged (not scrolled) right.
• drag,stop: The item in the gengrid stops being dragged.
• drag: The item in the gengrid is dragged.
• scroll: The content is scrolled (moved).
• scroll,drag,start: Dragging the content starts.
• scroll,drag,stop: Dragging the content stops.
• scroll,page,changed: The visible page changes.
• edge,top: The gengrid is scrolled to the top edge.
• edge,bottom: The gengrid is scrolled to the bottom edge.
• edge,left: The gengrid is scrolled to the left edge.
• edge,right: The gengrid is scrolled to the right edge.
• moved: The item in the gengrid is moved.
• pressed: The item in the gengrid is pressed by the action pressing the mouse.
• released: The item in the gengrid is released by the action releasing the mouse.
• item,reorder,anim,start: When the reorder animation starts.
• item,reorder,anim,stop: When the reorder animation stops.

Note
Except as noted, this content is licensed under LGPLv2.1+.