This application is a thorough exercise on the gengrid widget's API.
We place an Elementary gengrid widget on a window, with various knobs below its viewport, each one acting on it somehow.
The code's relevant part begins at the grid's creation. After instantiating it, we set its items sizes, so that we don't end with items one finger size wide, only. We're setting them to fat, 150 pixel wide ones, for this example. We give it some size hints, not to be discussed in this context and, than, we register a callback on one of its smart events – the one coming each time an item gets doubly clicked. There, we just print the item handle's value.
Before we actually start to deal with the items API, let's show some things items will be using throughout all the code. The first of them is a struct to be used as item data, for all of them:
That path will be used to index an image, to be swallowed into one of the item's icon spots. The images themselves are distributed with Elementary:
We also have an (unique) gengrid item class we'll be using for items in the example:
As you see, our items will follow the default theme on gengrid items. For the label fetching code, we return a string composed of the item's image path:
For item icons, we'll be populating the item default theme's two icon spots,
"elm.swallow.end". The former will receive one of the images in our list (in the form of a background), while the latter will be a check widget. Note that we prevent the check to propagate click events, so that the user can toggle its state without messing with the respective item's selection in the grid:
As the default gengrid item's theme does not have parts implementing item states, we'll be just returning false for every item state:
Finally, the deletion callback on gengrid items takes care of freeing the item's label string and its data struct:
Let's move to item insertion/deletion knobs, them. They are four buttons, above the grid's viewport, namely
which are displaced and declared in that order. We're not dealing with the buttons' creation code (see a button example, for more details on it), but with their
"clicked" registered callbacks. For all of them, the grid's handle is passed as
data. The ones creating new items use a common code, which just gives a new
Example_Item struct, with
path filled with a random image in our images list:
Moreover, that ones will set a common function to be issued on the selection of the items. There, we print the item handle's value, along with the callback function data. The latter will be
NULL, always, because it's what we pass when adding all icons. By using elm_object_item_data_get(), we can have the item data back and, with that, we're priting the item's path string. Finally, we exemplify elm_gengrid_item_pos_get(), printing the item's position in the grid:
The appending button will exercise elm_gengrid_item_append(), simply:
The prepending, naturally, is analogous, but exercising elm_gengrid_item_prepend(), on its turn. The "Insert before" one will expect an item to be selected in the grid, so that it will insert a new item just before it:
The "Bring in 1st" button is there exercise two gengrid functions – elm_gengrid_first_item_get() and elm_gengrid_item_bring_in(). With the former, we get a handle to the first item and, with the latter, you'll see that the widget animatedly scrolls its view until we can see that item:
The "Show last", in its turn, will use elm_gengrid_last_item_get() and elm_gengrid_item_show(). The latter differs from elm_gengrid_item_bring_in() in that it immediately replaces the contents of the grid's viewport with the region containing the item in question:
To change the grid's cell (items) size, we've placed a spinner, which has the following
"changed" smart callback:
Experiment with it and see how the items are affected. The "Disable item" button will, as the name says, disable the currently selected item:
To toggle between horizontal and vertical layouting modes on the grid, use the "Horizontal mode" check, which will call the respective API function on the grid:
If you toggle the check right after that one, "Always select", you'll notice all subsequent clicks on the same grid item will still issue the selection callback on it, what is different from when it's not checked. This is the elm_gengrid_select_mode_set() behavior:
One more check follows, "Bouncing", which will turn on/off the bouncing animations on the grid, when one scrolls past its borders. Experiment with scrolling the grid to get the idea, having it turned on and off:
The next two checks will affect items selection on the grid. The first, "Multi-selection", will make it possible to select more the one item on the grid. Because it wouldn't make sense to fetch for an unique selected item on this case, we also disable two of the buttons, which insert items relatively, if multi-selection is on:
Note that we also unselect all items in the grid, when returning from multi-selection mode, making use of elm_gengrid_item_selected_set().
The second check acting on selection, "No selection", is just what its name depicts – no selection will be allowed anymore, on the grid, while it's on. Check it out for yourself, interacting with the program:
We have, finally, one more line of knobs, now sliders, to change the grids behavior. The two first will change the horizontal alignment of the whole actual grid of items within the gengrid's viewport:
Naturally, the vertical counterpart just issues elm_gengrid_align_set() changing the second alignment component, instead.
The last slider will change the grid's page size, relative to its own one. Try to change those values and, one manner of observing the paging behavior, is to scroll softly and release the mouse button, with different page sizes, at different grid positions, while having lots of items in it – you'll see it snapping to page boundaries differenty, for each configuration:
This is how the example program's window looks like:
Note that it starts with three items which we included at will:
See the full source code for this example.