Add examples with explanations for elm_box

SVN revision: 60843

legacy/elementary/doc/examples.dox

@@ -925,6 +925,170 @@
  * @example bubble_example_01.c
  */
 
+/**
+ * @page box_example_01 Box - Basic API
+ *
+ * @dontinclude button_example_01.c
+ *
+ * As a special guest tonight, we have the @ref button_example_01 "simple
+ * button example". There are plenty of boxes in it, and to make the cursor
+ * buttons that moved a central one around when pressed, we had to use a
+ * variety of values for their hints.
+ *
+ * To start, let's take a look at the handling of the central button when
+ * we were moving it around. To achieve this effect without falling back to
+ * a complete manual positioning of the @c Evas_Object in our canvas, we just
+ * put it in a box and played with its alignment within it, as seen in the
+ * following snippet of the callback for the pressed buttons.
+ * @skip evas_object_size_hint_align_get
+ * @until evas_object_size_hint_align_set
+ *
+ * Not much to it. We get the current alignment of the object and change it
+ * by just a little, depending on which button was pressed, then set it
+ * again, making sure we stay within the 0.0-1.0 range so the button moves
+ * inside the space it has, instead of disappearing under the other objects.
+ *
+ * But as useful as an example as that may have been, the usual case with boxes
+ * is to set everything at the moment they are created, like we did for
+ * everything else in our main function.
+ *
+ * The entire layout of our program is made with boxes. We have one set as the
+ * resize object for the window, which means it will always be resized with
+ * the window. The weight hints set to @c EVAS_HINT_EXPAND will tell the
+ * window that the box can grow past it's minimum size, which allows resizing
+ * of it.
+ * @skip elm_main
+ * @skip elm_box_add
+ * @until evas_object_show
+ *
+ * Two more boxes, set to horizontal, hold the buttons to change the autorepeat
+ * configuration used by the buttons. We create each to take over all the
+ * available space horizontally, but we don't want them to grow vertically,
+ * so we keep that axis of the weight with 0.0. Then it gets packed in the
+ * main box.
+ * @skip box2
+ * @until evas_object_show
+ *
+ * The buttons in each of those boxes have nothing special, they are just packed
+ * in with their default values and the box will use their minimum size, as set
+ * by Elementary itself based on the label, icon, finger size and theme.
+ *
+ * But the buttons used to move the central one have a special disposition.
+ * The top one first, is placed right into the main box like our other smaller
+ * boxes. Set to expand horizontally and not vertically, and in this case we
+ * also tell it to fill that space, so it gets resized to take the entire
+ * width of the window.
+ * @skip Gap: 1.0
+ * @skip elm_button_add
+ * @until evas_object_show
+ *
+ * The bottom one will be the same, but for the other two we need to use a
+ * second box set to take as much space as we have, so we can place our side
+ * buttons in place and have the big empty space where the central button will
+ * move.
+ * @skip elm_box_add
+ * @until evas_object_show
+ *
+ * Then the buttons will have their hints inverted to the other top and bottom
+ * ones, to expand and fill vertically and keep their minimum size horizontally.
+ * @skip elm_button_add
+ * @until evas_object_show
+ *
+ * The central button takes every thing else. It will ask to be expanded in
+ * both directions, but without filling its cell. Changing its alignment by
+ * pressing the buttons will make it move around.
+ * @skip elm_button_add
+ * @until evas_object_show
+ *
+ * To end, the rightmost button is packed in the smaller box after the central
+ * one, and back to the main box we have the bottom button at the end.
+ */
+
+/**
+ * @page box_example_02 Box - Layout transitions
+ *
+ * @dontinclude box_example_02.c
+ *
+ * Setting a customized layout for a box is simple once you have the layout
+ * function, which is just like the layout function for @c Evas_Box. The new
+ * and fancier thing we can do with Elementary is animate the transition from
+ * one layout to the next. We'll see now how to do that through a simple
+ * example, while also taking a look at some of the API that was left
+ * untouched in our @ref box_example_01 "previous example".
+ *
+ * @image html screenshots/box_example_02.png
+ * @image latex screenshots/box_example_02.eps
+ *
+ * @skipline Elementary.h
+ *
+ * Our application data consists of a list of layout functions, given by
+ * @c transitions. We'll be animating through them throughout the entire run.
+ * The box with the stuff to move around and the last layout that was set to
+ * make things easier in the code.
+ * @skip typedef
+ * @until Transitions_Data
+ *
+ * The box starts with three buttons, clicking on any of them will take it
+ * out of the box without deleting the object. There are also two more buttons
+ * outside, one to add an object to the box and the other to clear it.
+ * This is all to show how you can interact with the items in the box, add
+ * things and even remove them, while the transitions occur.
+ *
+ * One of the callback we'll be using creates a new button, asks the box for
+ * the list of its children and if it's not empty, we add the new object after
+ * the first one, otherwise just place at the end as it will not make any
+ * difference.
+ * @skip static void
+ * @until }
+ * @until }
+ *
+ * The clear button is even simpler. Everything in the box will be deleted,
+ * leaving it empty and ready to fill it up with more stuff.
+ * @skip static void
+ * @until }
+ *
+ * And a little function to remove buttons from the box without deleting them.
+ * This one is set for the @c clicked callback of the original buttons,
+ * unpacking them when clicked and placing it somewhere in the screen where
+ * they will not disturb. Once we do this, the box no longer has any control
+ * of it, so it will be left untouched until the program ends.
+ * @skip static void
+ * @until }
+ *
+ * If we wanted, we could just call @c evas_object_del() on the object to
+ * destroy it. In this case, no unpack is really necessary, as the box would
+ * be notified of a child being deleted and adjust its calculations accordingly.
+ *
+ * The core of the program is the following function. It takes whatever
+ * function is first on our list of layouts and together with the
+ * @c last_layout, it creates an ::Elm_Box_Transition to use with
+ * elm_box_layout_transition(). In here, we tell it to start from whatever
+ * layout we last set, end with the one that was at the top of the list and
+ * when everything is finished, call us back so we can create another
+ * transition. Finally, move the new layout to the end of the list so we
+ * can continue running through them until the program ends.
+ * @skip static void
+ * @until }
+ *
+ * The main function doesn't have antyhing special. Creation of box, initial
+ * buttons and some callback setting. The only part worth mentioning is the
+ * initialization of our application data.
+ * @skip tdata.box
+ * @until evas_object_box_layout_stack
+ *
+ * We have a simple static variable, set the box, the first layout we are
+ * using as last and create the list with the different functions to go
+ * through.
+ *
+ * And in the end, we set the first layout and call the same function we went
+ * through before to start the run of transitions.
+ * @until _test_box_transition_change
+ *
+ * For the full code, follow @ref box_example_02.c "here".
+ *
+ * @example box_example_02.c
+ */
+
 /**
  * @page bg_example_01_c bg_example_01.c
  * @include bg_example_01.c

legacy/elementary/src/examples/Makefile.am

@@ -39,6 +39,7 @@ SRCS = \
 	bg_example_01.c \
 	bg_example_02.c \
 	bg_example_03.c \
+	box_example_02.c \
 	general_funcs_example.c \
 	theme_example_01.c \
 	theme_example_02.c \
@@ -73,6 +74,7 @@ pkglib_PROGRAMS += \
 	bg_example_01 \
 	bg_example_02 \
 	bg_example_03 \
+	box_example_02 \
 	general_funcs_example \
 	theme_example_01 \
 	theme_example_02 \
@@ -84,6 +86,7 @@ pkglib_PROGRAMS += \
 SCREENSHOTS = \
 	actionslider_example_01:actionslider_01.png:0.0 \
 	bg_example_02:bg_01.png:0.0 \
+	box_example_02:box_example_02.png:1.3 \
 	button_example_01:button_01.png:0.0 \
 	animator_example_01:animator_example_01.png:0.2 \
 	animator_example_01:animator_example_02.png:0.5 \

legacy/elementary/src/examples/box_example_02.c

@@ -0,0 +1,170 @@
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+typedef struct
+{
+   Eina_List *transitions;
+   Evas_Object *box;
+   Evas_Object_Box_Layout last_layout;
+} Transitions_Data;
+
+static void
+_add_cb(void *data, Evas_Object *obj __UNUSED__, void *ev __UNUSED__)
+{
+   Evas_Object *btn;
+   Eina_List *children;
+   Transitions_Data *tdata = data;
+
+   btn = elm_button_add(tdata->box);
+   elm_button_label_set(btn, "I do nothing");
+   children = (Eina_List *)elm_box_children_get(tdata->box);
+   if (children)
+     {
+        elm_box_pack_after(tdata->box, btn, (Evas_Object *)children->data);
+        eina_list_free(children);
+     }
+   else
+     elm_box_pack_end(tdata->box, btn);
+   evas_object_show(btn);
+}
+
+static void
+_clear_cb(void *data, Evas_Object *obj __UNUSED__, void *ev __UNUSED__)
+{
+   Transitions_Data *tdata = data;
+   elm_box_clear(tdata->box);
+}
+
+static void
+_unpack_cb(void *data, Evas_Object *obj, void *ev __UNUSED__)
+{
+   Transitions_Data *tdata = data;
+   elm_box_unpack(tdata->box, obj);
+   evas_object_move(obj, 0, 50);
+   evas_object_color_set(obj, 128, 64, 0, 128);
+}
+
+static void
+_test_box_transition_change(void *data)
+{
+   Transitions_Data *tdata = data;
+   Elm_Box_Transition *layout_data;
+   Evas_Object_Box_Layout next_layout;
+
+   if (!data) return;
+   next_layout = eina_list_data_get(tdata->transitions);
+   layout_data = elm_box_transition_new(2.0, tdata->last_layout,
+                                        NULL, NULL, next_layout, NULL, NULL,
+                                        _test_box_transition_change, tdata);
+   elm_box_layout_set(tdata->box, elm_box_layout_transition, layout_data,
+                      elm_box_transition_free);
+   tdata->last_layout = next_layout;
+
+   tdata->transitions = eina_list_demote_list(tdata->transitions,
+                                              tdata->transitions);
+}
+
+int
+elm_main(int argc __UNUSED__, char *argv[] __UNUSED__)
+{
+   Evas_Object *win, *bg, *bigbox, *bx, *bt;
+   static Transitions_Data tdata = {
+        .transitions = NULL,
+        .box = NULL,
+        .last_layout = NULL
+   };
+
+   elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
+
+   win = elm_win_add(NULL, "box-transition", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Box Transition");
+   elm_win_autodel_set(win, EINA_TRUE);
+   evas_object_resize(win, 300, 320);
+   evas_object_show(win);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   bigbox = elm_box_add(win);
+   evas_object_size_hint_weight_set(bigbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   elm_win_resize_object_add(win, bigbox);
+   evas_object_show(bigbox);
+
+   bx = elm_box_add(win);
+   elm_box_horizontal_set(bx, EINA_TRUE);
+   elm_box_pack_end(bigbox, bx);
+   evas_object_show(bx);
+
+   bt = elm_button_add(win);
+   elm_button_label_set(bt, "Add");
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+   evas_object_smart_callback_add(bt, "clicked", _add_cb, &tdata);
+
+   bt = elm_button_add(win);
+   elm_button_label_set(bt, "Clear");
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+   evas_object_smart_callback_add(bt, "clicked", _clear_cb, &tdata);
+
+   bx = elm_box_add(win);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bx, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(bigbox, bx);
+   evas_object_show(bx);
+
+   bt = elm_button_add(win);
+   elm_button_label_set(bt, "Button 1");
+   evas_object_smart_callback_add(bt, "clicked", _unpack_cb, &tdata);
+   evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bt, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+
+   bt = elm_button_add(win);
+   elm_button_label_set(bt, "Button 2");
+   evas_object_size_hint_weight_set(bt, EVAS_HINT_EXPAND, 0.0);
+   evas_object_size_hint_align_set(bt, 1.0, 0.5);
+   evas_object_smart_callback_add(bt, "clicked", _unpack_cb, &tdata);
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+
+   bt = elm_button_add(win);
+   elm_button_label_set(bt, "Button 3");
+   evas_object_smart_callback_add(bt, "clicked", _unpack_cb, &tdata);
+   elm_box_pack_end(bx, bt);
+   evas_object_show(bt);
+
+   tdata.box = bx;
+   tdata.last_layout = evas_object_box_layout_horizontal;
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_vertical);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_horizontal);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_stack);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_homogeneous_vertical);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_homogeneous_horizontal);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_flow_vertical);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_flow_horizontal);
+   tdata.transitions = eina_list_append(tdata.transitions,
+         evas_object_box_layout_stack);
+
+   elm_box_layout_set(bx, evas_object_box_layout_horizontal, NULL, NULL);
+   _test_box_transition_change(&tdata);
+
+   elm_run();
+
+   return 0;
+}
+ELM_MAIN();

legacy/elementary/src/lib/Elementary.h.in

@@ -1995,6 +1995,10 @@ extern "C" {
     *
     * @note Objects should not be added to box objects using _add() calls.
     *
+    * Some examples on how to use boxes follow:
+    * @li @ref box_example_01
+    * @li @ref box_example_02
+    *
     * @{
     */
    /**