[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

git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@61705 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/doc/examples.dox b/doc/examples.dox
index 2220b5c..e863f89 100644 (file)
--- a/doc/examples.dox
+++ b/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/src/examples/gengrid_example.c b/src/examples/gengrid_example.c
index 7e22e95..705a0ce 100644 (file)
--- a/src/examples/gengrid_example.c
+++ b/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/src/lib/Elementary.h.in b/src/lib/Elementary.h.in
index 2be3a45..582aa79 100644 (file)
--- a/src/lib/Elementary.h.in
+++ b/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)
+    *
+    * This returns the last item in the @p obj's internal list of
+    * items.
     *
-    * @return The last item, or NULL if none
+    * @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
-    *
-    * 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).
+    * Get the selected item in a given gengrid widget
     *
-    * If no item is selected, NULL is returned.
+    * @param obj The gengrid object.
+    * @return The selected item's handleor @c NULL, if none is
+    * selected at the moment (and on errors)
     *
-    * @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 <b>a list</b> of selected items in a given gengrid
+    *
+    * @param obj The gengrid object.
+    * @return The list of selected items or @c NULL, if none is
+    * selected at the moment (and on errors)
     *
-    * 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.
+    * 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.
     *
-    * @param obj The Gengrid object.
-    * @return The list of selected items, or NULL if none are selected.
+    * @see @elm_gengrid_selected_item_get()
     *
     * @ingroup Gengrid
     */