From e5e66db3d562f6adea836d90b9f9a57a168fc394 Mon Sep 17 00:00:00 2001 From: Rafael Antognolli Date: Tue, 26 Jul 2011 18:32:14 +0000 Subject: [PATCH] elementary/genlist - Explaining the examples. SVN revision: 61769 --- legacy/elementary/doc/examples.dox | 216 ++++++++++++++++++++++ legacy/elementary/src/lib/Elementary.h.in | 7 + 2 files changed, 223 insertions(+) diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index c88385f9e4..6913b91828 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -58,6 +58,10 @@ * @ref index_example_02 * * @ref gengrid_example + * + * @ref genlist_example_01 + * + * @ref genlist_example_02 */ /** @@ -3644,6 +3648,206 @@ * @example gengrid_example.c */ +/** + * @page genlist_example_01 + * + * This example creates a simple genlist with a small number of items and + * a callback that is called whenever an item is selected. All the properties of + * this genlist are the default ones. The full code for this example can be seen + * at @ref genlist_example_01_c. + * + * For the simplest list that you plan to create, it's necessary to define some + * of the basic functions that are used for creating each list item, and + * associating them with the "item class" for that list. The item class is just + * an struct that contains pointers to the specific list item functions that are + * common to all the items of the list. + * + * Let's show it by example. Our item class is declared globally and static as + * it will be the only item class that we need (we are just creating one list): + * + * @dontinclude genlist_example_01.c + * @skip static Elm_Genlist + * @until static Elm_Genlist + * + * This item class will be used for every item that we create. The only + * functions that we are going to set are @c label_get and @c icon_get. As the + * name suggests, they are used by the genlist to generate the label for the + * respective item, and to generate icon(s) to it too. Both the label and icon + * get functions can be called more than once for each item, with different @c + * part parameters, which represent where in the theme of the item that label or + * icon is going to be set. + * + * The default theme for the genlist contains only one area for label, and two + * areas for icon ("elm.swallow.icon" and "elm.swallow.end"). Since we just want + * to set the first icon (that will be at the left side of the label), we + * compare the part name given with "elm.swallow.icon". Notice that the + * @c label_get function must return a strduped string, that will be freed later + * automatically by the list. Here's the code for @c label_get and @c icon_get: + * + * @until static void + * + * We will also provide a function that will be called whenever an item is + * selected in the genlist. However, this function is not part of the item + * class, it will be passed for each item being added to the genlist explicitly. + * Notice the similarity of the function signature with those used by @c + * evas_object_smart_callback_add: + * + * @until } + * + * Now let's show the code used for really creating the list. Skipping + * boilerplate code used for creating a window and background, the first piece + * of code specific to our genlist example is setting the pointer functions of + * the item class to our above defined functions: + * + * @skip _itc + * @until func.del + * + * Notice that we also choose to use the "default" style for our genlist items. + * Another interesting point is that @c state_get and @c del are set to @c NULL, + * since we don't need these functions now. @c del doesn't need to be used + * because we don't add any data that must be freed to our items, and @c + * state_get is also not used since all of our items are the same and don't need + * to have different states to be used for each item. Finally we create our + * list: + * + * @until genlist_add + * + * Now we append several items to the list, and for all of them we need to give + * the list pointer, a pointer to the item class, the data that will be used + * with that item, a pointer to the parent of this item if it is in a group type + * list (this is not the case so we pass @c NULL), possible flags for this item, + * the callback for when the item is selected, and the data pointer that will be + * given to the selected callback. + * + * @until } + * + * The rest of the code is also common to all the other examples, so it will be + * omitted here (look at the full source code link above if you need it). + * + * You can try to play with this example, and see the selected callback being + * called whenever an item is clicked. It also already has some features enabled + * by default, like vertical bounce animation when reaching the end of the list, + * automatically visible/invisible scrollbar, etc. Look at the @ref + * genlist_example_02 to see an example of setting these properties to the list. + * + * The current example will look like this when running: + * + * @image html screenshots/genlist_example_01.png + * @image latex screenshots/genlistexample_01.eps width=\textwidth + */ + +/** + * @page genlist_example_02 + * + * This example is very similar to the @ref genlist_example_01, but it fetch + * most of the properties of the genlist and displays them on startup (thus + * getting the default value for them) and then set them to some other values, + * to show how to use that API. The full source code is at @ref + * genlist_example_02_c. + * + * Considering that the base code for instantiating a genlist was already + * described in the previous example, we are going to focus on the new code. + * + * Just a small difference for the @c _item_label_get function, we are going to + * store the time that this function was called. This is the "realized" time, + * the time when the visual representation of this item was created. This is the + * code for the @c label_get function: + * + * @dontinclude genlist_example_02.c + * @skip static char + * @until return strdup + * + * Now let's go to the list creation and setup. First, just after creating the + * list, we get most of the default properties from it, and print them on the + * console: + * + * @skip genlist_add + * @until printf("\n") + * + * We are going to change some of the properties of our list. + * + * There's no need to call the selected callback at every click, just when the + * selected item changes, thus we call elm_genlist_always_select_mode_set() with + * false. + * + * For this list we don't want bounce animations at all, so we set both the + * horizontal bounce and the vertical bounce to false with + * elm_genlist_bounce_set(). + * + * We also want our list to compress items if they are wider than the list + * width (thus we call elm_genlist_compress_mode_set(). + * + * The items have different width, so they are not homogeneous: + * elm_genlist_homogeneous_set() is set to false. + * + * Since the compress mode is active, the call to + * elm_genlist_horizontal_mode_set() doesn't make difference, but the current + * option would make the list to have at least the width of the largest item. + * + * This list will support multiple selection, so we call + * elm_genlist_multi_select_set() on it. + * + * The option elm_genlist_height_for_width_mode_set() would allow text block to + * wrap lines if the Edje part is configured with "text.min: 0 1", for example. + * But since we are compressing the elements to the width of the list, this + * option wouldn't take any effect. + * + * We want the vertical scrollbar to be always displayed, and the orizontal one + * to never be displayed, and set this with elm_genlist_scroller_policy_set(). + * + * The timeout to consider a longpress is set to half of a second with + * elm_genlist_longpress_timeout_set(). + * + * We also change the block count to a smaller value, but that should have not + * impact on performance since the number of visible items is too small. We just + * increase the granularity of the block count (setting it to have at most 4 + * items). + * + * @until block_count_set + * + * Now let's add elements to the list: + * + * @until item_append + * @until } + * + * It's exactly the same as the previous example. The difference is on the + * behavior of the list, if you try to scroll, select items and so. + * + * In this example we also need two buttons. One of them, when clicked, will + * display several status info about the current selection, the "realized" + * items, the item in the middle of the screen, and the current mode and active + * item of that mode for the genlist. + * + * The other button will ask the genlist to "realize" again the items already + * "realized", so their respective label_get and icon_get functions will be + * called again. + * + * These are the callbacks for both of these buttons: + * + * @dontinclude genlist_example_02.c + * @skip item_sel_cb + * @skip static + * @until } + * @until } + * + * Try to scroll, select some items and click on the "Show status" button. + * You'll notice that not all items of the list are "realized", thus consuming + * just a small amount of memory. The selected items are listed in the order + * that they were selected, and the current selected item printed using + * elm_genlist_selected_item_get() is the first selected item of the multiple + * selection. + * + * Now resize the window so that you can see the "realized time" of some items. + * This is the time of when the label_get function was called. If you click on + * the "Realize" button, all the already realized items will be rebuilt, so the + * time will be updated for all of them. + * + * The current example will look like this when running: + * + * @image html screenshots/genlist_example_02.png + * @image latex screenshots/genlistexample_02.eps width=\textwidth + */ + /** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c @@ -3767,3 +3971,15 @@ * @include gengrid_example.c * @example gengrid_example.c */ + +/** + * @page genlist_example_01_c genlist_example_01.c + * @include genlist_example_01.c + * @example genlist_example_01.c + */ + +/** + * @page genlist_example_02_c genlist_example_02.c + * @include genlist_example_02.c + * @example genlist_example_02.c + */ diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index e816e97d8b..5a655ece91 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -10923,6 +10923,13 @@ extern "C" { * pinched out. "- @c multi,pinch,in" - This is called when the genlist is * multi-touch pinched in. * - @c "swipe" - This is called when the genlist is swiped. + * + * @section Genlist_Examples Examples + * + * Here is a list of examples that use the genlist, trying to show some of + * its capabilities: + * - @ref genlist_example_01 + * - @ref genlist_example_02 */ /**