Elementary: Actionslider example and accompaning documentation.
authorgastal <gastal@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Wed, 15 Jun 2011 14:22:11 +0000 (14:22 +0000)
committergastal <gastal@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>
Wed, 15 Jun 2011 14:22:11 +0000 (14:22 +0000)
git-svn-id: https://svn.enlightenment.org/svn/e/trunk/elementary@60351 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

configure.ac
m4/efl_examples.m4 [new file with mode: 0644]
src/Makefile.am
src/examples/Makefile.am [new file with mode: 0644]
src/examples/actionslider_example_01.c [new file with mode: 0644]
src/lib/Elementary.h.in

index d77a258..bbf7cea 100644 (file)
@@ -518,6 +518,7 @@ src/modules/Makefile
 src/modules/test_entry/Makefile
 src/modules/test_map/Makefile
 src/edje_externals/Makefile
+src/examples/Makefile
 data/Makefile
 data/themes/Makefile
 data/images/Makefile
@@ -531,6 +532,10 @@ config/illume/Makefile
 $po_makefile_in
 ])
 
+### Build and install examples
+EFL_CHECK_BUILD_EXAMPLES([enable_build_examples="yes"], [enable_build_examples="no"])
+EFL_CHECK_INSTALL_EXAMPLES([enable_install_examples="yes"], [enable_install_examples="no"])
+
 #####################################################################
 ## Info
 
@@ -562,6 +567,8 @@ echo "  eet......................: ${eet_eet}"
 echo "  edje_cc..................: ${edje_cc}"
 echo
 echo "  Build elementary_test....: ${have_elementary_test}"
+echo "  Examples.............: ${enable_build_examples}"
+echo "  Examples installed...: ${enable_install_examples}"
 echo "  Build elementary_config..: ${have_elementary_config}"
 echo
 echo "Compilation................: make (or gmake)"
diff --git a/m4/efl_examples.m4 b/m4/efl_examples.m4
new file mode 100644 (file)
index 0000000..2a809ad
--- /dev/null
@@ -0,0 +1,63 @@
+dnl Copyright (C) 2008 Vincent Torri <vtorri at univ-evry dot fr>
+dnl That code is public domain and can be freely used or copied.
+
+dnl Macro that check if building examples is wanted.
+
+dnl Usage: EFL_CHECK_BUILD_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl Defines the automake conditionnal EFL_ENABLE_BUILD_EXAMPLES
+
+AC_DEFUN([EFL_CHECK_BUILD_EXAMPLES],
+[
+
+dnl configure option
+
+AC_ARG_ENABLE([build-examples],
+   [AC_HELP_STRING([--enable-build-examples], [enable building examples @<:@default=disabled@:>@])],
+   [
+    if test "x${enableval}" = "xyes" ; then
+       _efl_enable_build_examples="yes"
+    else
+       _efl_enable_build_examples="no"
+    fi
+   ],
+   [_efl_enable_build_examples="no"])
+
+AC_MSG_CHECKING([whether examples are built])
+AC_MSG_RESULT([${_efl_enable_build_examples}])
+
+AM_CONDITIONAL(EFL_BUILD_EXAMPLES, test "x${_efl_enable_build_examples}" = "xyes")
+
+AS_IF([test "x$_efl_enable_build_examples" = "xyes"], [$1], [$2])
+])
+
+
+dnl Macro that check if installing examples is wanted.
+
+dnl Usage: EFL_CHECK_INSTALL_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]])
+dnl Defines the automake conditionnal EFL_ENABLE_INSTALL_EXAMPLES
+
+AC_DEFUN([EFL_CHECK_INSTALL_EXAMPLES],
+[
+
+dnl configure option
+
+AC_ARG_ENABLE([install-examples],
+   [AC_HELP_STRING([--enable-install-examples], [enable installing example source files @<:@default=disabled@:>@])],
+   [
+    if test "x${enableval}" = "xyes" ; then
+       _efl_enable_install_examples="yes"
+    else
+       _efl_enable_install_examples="no"
+    fi
+   ],
+   [_efl_enable_install_examples="no"])
+
+AC_MSG_CHECKING([whether examples are installed])
+AC_MSG_RESULT([${_efl_enable_install_examples}])
+
+AM_CONDITIONAL(EFL_INSTALL_EXAMPLES, test "x${_efl_enable_install_examples}" = "xyes")
+
+AS_IF([test "x$_efl_enable_install_examples" = "xyes"], [$1], [$2])
+])
+
+dnl End of efl_examples.m4
index be7ccd9..8c0d716 100644 (file)
@@ -1,4 +1,4 @@
 AUTOMAKE_OPTIONS     = 1.4 foreign
 MAINTAINERCLEANFILES = Makefile.in
 
-SUBDIRS = lib bin modules edje_externals
+SUBDIRS = lib bin modules edje_externals examples
diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am
new file mode 100644 (file)
index 0000000..a0bf8fb
--- /dev/null
@@ -0,0 +1,31 @@
+MAINTAINERCLEANFILES = Makefile.in
+
+pkglibdir = $(datadir)/$(PACKAGE)/examples
+
+AM_CPPFLAGS = \
+-I. \
+-I$(top_srcdir)/src/lib \
+-I$(top_builddir)/src/lib \
+@ELEMENTARY_EDBUS_CFLAGS@ \
+@ELEMENTARY_EFREET_CFLAGS@ \
+@ELEMENTARY_ETHUMB_CFLAGS@ \
+@ELEMENTARY_CFLAGS@
+
+LDADD = \
+       $(top_builddir)/src/lib/libelementary.la
+
+SRCS = \
+       actionslider_example_01.c
+
+pkglib_PROGRAMS =
+
+if EFL_INSTALL_EXAMPLES
+filesdir = $(datadir)/$(PACKAGE)/examples
+files_DATA = $(SRCS)
+endif
+
+if EFL_BUILD_EXAMPLES
+pkglib_PROGRAMS += \
+       actionslider_example_01
+endif
+
diff --git a/src/examples/actionslider_example_01.c b/src/examples/actionslider_example_01.c
new file mode 100644 (file)
index 0000000..5b5f4a7
--- /dev/null
@@ -0,0 +1,139 @@
+//Compile with:
+//gcc -g `pkg-config --cflags --libs elementary` actionslider_example_01.c -o actionslider_example_01
+
+#include <Elementary.h>
+
+static void _pos_selected_cb(void *data, Evas_Object *obj, void *event_info)
+{
+   printf("Selection: %s\n", (char *)event_info);
+   printf("Label selected: %s\n", elm_actionslider_selected_label_get(obj));
+}
+
+static void
+_position_change_magnetic_cb(void *data, Evas_Object * obj, void *event_info)
+{
+   if (!strcmp((char *)event_info, "left"))
+     elm_actionslider_magnet_pos_set(obj, ELM_ACTIONSLIDER_LEFT);
+   else if (!strcmp((char *)event_info, "right"))
+     elm_actionslider_magnet_pos_set(obj, ELM_ACTIONSLIDER_RIGHT);
+}
+
+static void
+_magnet_enable_disable_cb(void *data, Evas_Object *obj, void *event_info)
+{
+   if (!strcmp((char *)event_info, "left"))
+      elm_actionslider_magnet_pos_set(obj, ELM_ACTIONSLIDER_CENTER);
+   else if (!strcmp((char *)event_info, "right"))
+      elm_actionslider_magnet_pos_set(obj, ELM_ACTIONSLIDER_NONE);
+}
+
+static void
+on_done(void *data, Evas_Object *obj, void *event_info)
+{
+   elm_exit();
+}
+
+EAPI int
+elm_main(int argc, char **argv)
+{
+   Evas_Object *win, *bg, *bx, *as;
+
+   win = elm_win_add(NULL, "actionslider", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Actionslider");
+   evas_object_smart_callback_add(win, "delete,request", on_done, NULL);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, 0);
+   evas_object_show(bg);
+
+   bx = elm_box_add(win);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, 0);
+   elm_win_resize_object_add(win, bx);
+   evas_object_show(bx);
+
+   as = elm_actionslider_add(win);
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_RIGHT);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_RIGHT);
+   elm_actionslider_labels_set(as, "Snooze", NULL, "Stop");
+   elm_actionslider_enabled_pos_set(as, ELM_ACTIONSLIDER_LEFT |
+                                    ELM_ACTIONSLIDER_RIGHT);
+   evas_object_smart_callback_add(as, "pos_changed",
+                                  _position_change_magnetic_cb, NULL);
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+   as = elm_actionslider_add(win);
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_CENTER);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_CENTER);
+   elm_actionslider_labels_set(as, "Snooze", NULL, "Stop");
+   elm_actionslider_enabled_pos_set(as, ELM_ACTIONSLIDER_LEFT |
+                                    ELM_ACTIONSLIDER_RIGHT);
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+   as = elm_actionslider_add(win);
+   elm_object_style_set(as, "bar");
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_LEFT);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_CENTER|
+                                   ELM_ACTIONSLIDER_RIGHT);
+   elm_actionslider_enabled_pos_set(as, ELM_ACTIONSLIDER_CENTER |
+                                    ELM_ACTIONSLIDER_RIGHT);
+   elm_actionslider_labels_set(as, NULL, "Accept", "Reject");
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+   as = elm_actionslider_add(win);
+   elm_object_style_set(as, "bar");
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_LEFT);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_LEFT);
+   elm_actionslider_labels_set(as, NULL, "Accept", "Reject");
+   elm_actionslider_indicator_label_set(as, "Go");
+   evas_object_smart_callback_add(as, "pos_changed",
+                                  _position_change_magnetic_cb, NULL);
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+
+   as = elm_actionslider_add(win);
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_LEFT);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_ALL);
+   elm_actionslider_labels_set(as, "Left", "Center", "Right");
+   elm_actionslider_indicator_label_set(as, "Go");
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+   as = elm_actionslider_add(win);
+   evas_object_size_hint_weight_set(as, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(as, EVAS_HINT_FILL, 0);
+   elm_actionslider_indicator_pos_set(as, ELM_ACTIONSLIDER_CENTER);
+   elm_actionslider_magnet_pos_set(as, ELM_ACTIONSLIDER_CENTER);
+   elm_actionslider_labels_set(as, "Enable", "Magnet", "Disable");
+   evas_object_smart_callback_add(as, "pos_changed",
+                                  _magnet_enable_disable_cb, NULL);
+   evas_object_smart_callback_add(as, "selected", _pos_selected_cb, NULL);
+   evas_object_show(as);
+   elm_box_pack_end(bx, as);
+
+   evas_object_resize(win, 320, 400);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()
index e45bae4..5d2b5e7 100644 (file)
@@ -1859,6 +1859,107 @@ extern "C" {
     */
 
    /**
+    * @page actionslider_example_page Actionslider usage
+    * @dontinclude actionslider_example_01.c
+    *
+    * For this example we are going to assume knowledge of evas smart callbacks
+    * and some basic evas object functions. Elementary is not meant to be used
+    * without evas, if you're not yet familiar with evas it probably is worth
+    * checking that out.
+    *
+    * And now to the example, when using Elementary we start by including
+    * Elementary.h:
+    * @skipline #include
+    *
+    * Next we define some callbacks, they all share the same signature because
+    * they are all to be used with evas_object_smart_callback_add().
+    * The first one just prints the selected label(in two different ways):
+    * @until }
+    *
+    * This next callback is a little more interesting, it makes the selected
+    * label magnetic(except if it's the center label):
+    * @until }
+    *
+    * This callback enables or disables the magnetic propertty of the center
+    * label:
+    * @until }
+    *
+    * And finally a callback to stop the main loop when the window is closed:
+    * @until }
+    *
+    * To be able to create our actionsliders we need to do some setup, but this
+    * isn't really relevant here, so if you want to know about that go @ref
+    * Win "here".
+    *
+    * With all that boring stuff out of the way we can proceed to creating some
+    * actionsliders.@n
+    * All actionsliders are created the same way:
+    * @skipline actionslider_add
+    * Next we must choose where the indicator starts, and for this one we choose
+    * the right, and set the right as magnetic:
+    * @skipline indicator_pos_set
+    * @until magnet_pos_set
+    *
+    * We then set the labels for the left and right, passing NULL as an argument
+    * to any of the labels makes that position have no label.
+    * @until Stop
+    *
+    * Furthermore we mark both left and right as enabled positions, if we didn't
+    * do this all three positions would be enabled:
+    * @until RIGHT
+    *
+    * Having the the enabled positions we now add a smart callback to change
+    * which position is magnetic, so that only the last selected position is
+    * magnetic:
+    * @until NULL
+    *
+    * And finally we set our printing callback and show the actionslider:
+    * @until object_show
+    * @skip pack_end
+    *
+    * For our next actionslider we are going to do much as we did for the
+    * previous except we are going to have the center as the magnet(and not
+    * change it):
+    * @skipline actionslider_add
+    * @skipline indicator_pos_set
+    * @until object_show
+    *
+    * And another actionslider, in this one the indicator starts on the left.
+    * It has labels only in the center and right, and both bositions are
+    * magnetic. Because the left doesn't have a label and is not magnetic once
+    * the indicator leaves it can't return:
+    * @skipline actionslider_add
+    * @skipline indicator_pos_set
+    * @until object_show
+    * @note The greyed out area is a @ref Styles "style".
+    *
+    * And now an actionslider with a label in the indicator, and whose magnet
+    * properties change based on what was last selected:
+    * @skipline actionslider_add
+    * @skipline indicator_pos_set
+    * @until object_show
+    * @note The greyed out area is a @ref Styles "style".
+    *
+    * We are almost done, this next one is just a actionslider with all
+    * positions magnetized and having every possible label:
+    * @skipline actionslider_add
+    * @skipline indicator_pos_set
+    * @until object_show
+    *
+    * And for our last actionslider we have one that turns the magnetic property
+    * on and off:
+    * @skipline actionslider_add
+    * @skipline indicator_pos_set
+    * @until object_show
+    *
+    * See the full source code @ref actionslider_example_01 "here"
+    */
+   /**
+    * @page actionslider_example_01 Actionslider example
+    * @include actionslider_example_01.c
+    * @example actionslider_example_01.c
+    */
+   /**
     * @addtogroup Actionslider Actionslider
     *
     * A actionslider is a switcher for 2 or 3 labels with customizable magnet
@@ -1876,6 +1977,7 @@ extern "C" {
     * "pos_changed" - when the indicator reaches any of the positions("left",
     *                 "right" or "center").
     *
+    * See an example of actionslider usage @ref actionslider_example_page "here"
     * @{
     */
    typedef enum _Elm_Actionslider_Pos