From 6e8d098655f2298dc636c22bf4be9ee250dea5bf Mon Sep 17 00:00:00 2001 From: Gustavo Lima Chaves Date: Mon, 25 Jul 2011 19:52:15 +0000 Subject: [PATCH] [elementary] Documenting/exemplifying the following: - elm_gengrid_item_append - elm_gengrid_item_prepend - elm_gengrid_item_bring_in - elm_gengrid_item_show - elm_gengrid_item_insert_after - elm_gengrid_item_insert_before - elm_gengrid_item_size_get - elm_gengrid_item_size_set - elm_gengrid_selected_item_get - elm_gengrid_selected_items_get - elm_gengrid_first_item_get - elm_gengrid_last_item_get SVN revision: 61705 --- legacy/elementary/doc/examples.dox | 20 +++++ .../elementary/src/examples/gengrid_example.c | 38 +++++++++ legacy/elementary/src/lib/Elementary.h.in | 83 ++++++++++++------- 3 files changed, 109 insertions(+), 32 deletions(-) diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index 2220b5c74f..e863f89a6d 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -3147,6 +3147,8 @@ * - "Insert after" (to insert an item after the selection, on the * grid), * - "Clear" (to delete all items in the grid), + * - "Bring in 1st" (to make the 1st item visible, by scrolling), + * - "Show last" (to directly show the last item), * . * which are displaced and declared in that order. We're not dealing * with the buttons' creation code (see @ref button_example_01 @@ -3184,6 +3186,24 @@ * @skip delete items * @until } * + * 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: + * @dontinclude gengrid_example.c + * @skip bring in 1st item + * @until } + * + * 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: + * @dontinclude gengrid_example.c + * @skip show last item + * @until } + * * To change the grid's cell (items) size, we've placed a spinner, * which has the following @c "changed" smart callback: * @dontinclude gengrid_example.c diff --git a/legacy/elementary/src/examples/gengrid_example.c b/legacy/elementary/src/examples/gengrid_example.c index 7e22e95154..705a0cef34 100644 --- a/legacy/elementary/src/examples/gengrid_example.c +++ b/legacy/elementary/src/examples/gengrid_example.c @@ -222,6 +222,32 @@ _clear_cb(void *data, fprintf(stdout, "Clearing the grid!\n"); } +/* bring in 1st item */ +static void +_bring_1st_clicked(void *data, + Evas_Object *obj __UNUSED__, + void *event_info __UNUSED__) +{ + Elm_Gengrid_Item *it = elm_gengrid_first_item_get(data); + + if (!it) return; + + elm_gengrid_item_bring_in(it); +} + +/* show last item */ +static void +_show_last_clicked(void *data, + Evas_Object *obj __UNUSED__, + void *event_info __UNUSED__) +{ + Elm_Gengrid_Item *it = elm_gengrid_last_item_get(data); + + if (!it) return; + + elm_gengrid_item_show(it); +} + /* change items' size */ static void _size_changed(void *data, @@ -422,6 +448,18 @@ elm_main(int argc __UNUSED__, elm_box_pack_end(hbx_1, bt); evas_object_show(bt); + bt = elm_button_add(win); + elm_object_text_set(bt, "Bring in 1st"); + evas_object_smart_callback_add(bt, "clicked", _bring_1st_clicked, grid); + elm_box_pack_end(hbx_1, bt); + evas_object_show(bt); + + bt = elm_button_add(win); + elm_object_text_set(bt, "Show last"); + evas_object_smart_callback_add(bt, "clicked", _show_last_clicked, grid); + elm_box_pack_end(hbx_1, bt); + evas_object_show(bt); + sp = elm_spinner_add(win); elm_spinner_min_max_set(sp, 10, 1024); elm_spinner_value_set(sp, 150); diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index 2be3a4579b..582aa791a1 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -5105,23 +5105,32 @@ extern "C" { EAPI Eina_Bool elm_gengrid_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Get the first item in the gengrid - * - * This returns the first item in the list. + * Get the first item in a given gengrid widget * * @param obj The gengrid object - * @return The first item, or NULL if none + * @return The first item's handle or @c NULL, if there are no + * items in @p obj (and on errors) + * + * This returns the first item in the @p obj's internal list of + * items. + * + * @see elm_gengrid_last_item_get() * * @ingroup Gengrid */ EAPI Elm_Gengrid_Item *elm_gengrid_first_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Get the last item in the gengrid + * Get the last item in a given gengrid widget * - * This returns the last item in the list. + * @param obj The gengrid object + * @return The last item's handle or @c NULL, if there are no + * items in @p obj (and on errors) * - * @return The last item, or NULL if none + * This returns the last item in the @p obj's internal list of + * items. + * + * @see elm_gengrid_first_item_get() * * @ingroup Gengrid */ @@ -5281,25 +5290,32 @@ extern "C" { EAPI const Evas_Object *elm_gengrid_item_object_get(const Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1); /** - * Show the given item + * Show the portion of a gengrid's internal grid containing a given + * item, @b immediately. * - * This causes gengrid to jump to the given item @p item and show it - * (by scrolling), if it is not fully visible. + * @param item The item to display * - * @param item The item + * This causes gengrid to @b redraw its viewport's contents to the + * region contining the given @p item item, if it is not fully + * visible. + * + * @see elm_gengrid_item_bring_in() * * @ingroup Gengrid */ EAPI void elm_gengrid_item_show(Elm_Gengrid_Item *item) EINA_ARG_NONNULL(1); /** - * Bring in the given item + * Animatedly bring in, to the visible are of a gengrid, a given + * item on it. * - * This causes gengrig to jump to the given item @p item and show it - * (by scrolling), if it is not fully visible. This may use animation - * to do so and take a period of time + * @param item The gengrid item to display * - * @param item The item + * This causes gengrig to jump to the given @p item item and show + * it (by scrolling), if it is not fully visible. This will use + * animation to do so and take a period of time to complete. + * + * @see elm_gengrid_item_show() * * @ingroup Gengrid */ @@ -5506,32 +5522,35 @@ extern "C" { EAPI void elm_gengrid_clear(Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Get the selected item in the Gengrid + * Get the selected item in a given gengrid widget * - * This gets the selected item in the Gengrid (if multi-select is - * enabled only the first item in the list is selected - which is not - * very useful, so see elm_gengrid_selected_items_get() for when - * multi-select is used). + * @param obj The gengrid object. + * @return The selected item's handleor @c NULL, if none is + * selected at the moment (and on errors) * - * If no item is selected, NULL is returned. - * - * @param obj The Gengrid object. - * @return The selected item, or NULL if none. + * This returns the selected item in @p obj. If multi selection is + * enabled on @p obj (@see elm_gengrid_multi_select_set()), only + * the first item in the list is selected, which might not be very + * useful. For that case, see elm_gengrid_selected_items_get(). * * @ingroup Gengrid */ EAPI Elm_Gengrid_Item *elm_gengrid_selected_item_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /** - * Get a list of selected items in the Gengrid. + * Get a list of selected items in a given gengrid * - * This returns a list of the selected items. This list pointer is - * only valid so long as no items are selected or unselected (or - * unselected implictly by deletion). The list contains - * Elm_Gengrid_Item pointers. + * @param obj The gengrid object. + * @return The list of selected items or @c NULL, if none is + * selected at the moment (and on errors) * - * @param obj The Gengrid object. - * @return The list of selected items, or NULL if none are selected. + * 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 implictly + * by deletion). The list contains #Elm_Gengrid_Item pointers as + * data, naturally. + * + * @see @elm_gengrid_selected_item_get() * * @ingroup Gengrid */