Elementary: Toolbar Documentation

SVN revision: 61955

legacy/elementary/doc/Makefile.am

@@ -35,6 +35,7 @@ WGT_PREVIEW = \
 	clock:preview-00.png:widget_preview_clock:200:100 \
 	slider:preview-00.png:widget_preview_slider:200:100 \
 	panes:preview-00.png:widget_preview_panes:200:100 \
+	toolbar:preview-00.png:widget_preview_toolbar:300:100 \
 	ctxpopup:preview-00.png:widget_preview_ctxpopup:200:130 \
 	icon:preview-00.png:widget_preview_icon:50:50 \
 	image:preview-00.png:widget_preview_image:50:50 \

legacy/elementary/doc/examples.dox

@@ -48,7 +48,13 @@
  * @ref list_example_02
  *
  * @ref list_example_03
-
+ *
+ * @ref toolbar_example_01
+ *
+ * @ref toolbar_example_02
+ *
+ * @ref toolbar_example_03
+ *
  * @ref segment_control_example
  *
  * @ref flipselector_example
@@ -2217,6 +2223,158 @@
  * @example list_example_03.c
  */
 
+/**
+ * @page toolbar_example_01 Toolbar Example - Simple Items
+ *
+ * This code places a Elementary toolbar widget on a window,
+ * to exemplify part of the widget's API.
+ *
+ * Let's start adding a button to our window, that will have its text
+ * modified depending on which item is selected. It's used just to exemplify
+ * how to change a window content from the toolbar.
+ * @dontinclude toolbar_example_01.c
+ * @skipline elm_button_add
+ * @until evas_object_show
+ *
+ * Also, we'll need a toolbar widget, obviously:
+ * @skipline elm_toolbar_add
+ * @until evas_object_show
+ *
+ * When appending an item is possible to set an icon, label, and a callback
+ * function that will receive passed data.
+ * @skipline _item_append
+ * @until Folder
+ *
+ * It's possible to disable items, so the user can't select then. We will
+ * disable the third item:
+ * @skipline _item_append
+ * @until disable
+ *
+ * Our callbacks will just set button's label:
+ * @dontinclude toolbar_example_01.c
+ * @skip static
+ * @skip }
+ * @skipline static
+ * @until }
+ * @until }
+ * @until }
+ *
+ * By default, toolbars would display items homogeneously, so item with
+ * long labels, like the third, will make all of them occupy a lot of space.
+ * To avoid that, we can disable it:
+ * @dontinclude toolbar_example_01.c
+ * @skipline homogeneous
+ *
+ * Another default behavior, is to add an menu item if we have more items
+ * that would fit on toolbar size. To simply enable scroll, without menus,
+ * it's required to change toolbar's shrink mode:
+ * @dontinclude toolbar_example_01.c
+ * @skipline shrink
+ *
+ * See @ref toolbar_example_01.c "toolbar_example_01.c", whose window should
+ * look like this picture:
+ *
+ * @image html screenshots/toolbar_example_01.png
+ * @image latex screenshots/toolbar_example_01.eps width=\textwidth
+ *
+ * @example toolbar_example_01.c
+ */
+
+/**
+ * @page toolbar_example_02 Toolbar Example - Items with States
+ *
+ * This code places a Elementary toolbar widget on a window,
+ * to exemplify part of the widget's API.
+ *
+ * Toolbar widgets has support to items with states. Each state
+ * can have it's own label, icon, and callback function.
+ *
+ * Let's start populating a toolbar with some regular items.
+ * If you don't know how to do that, see
+ * @ref toolbar_example_01 "Toolbar Example 1".
+ * @dontinclude toolbar_example_02.c
+ * @skipline elm_toolbar_add
+ * @until Update
+ *
+ * The only difference here is that we set shrink mode to #ELM_SHRINK_MODE_HIDE,
+ * that won't display items that doesn't fit to the window.
+ *
+ * Now, let's add an item with states. First, add the item just as any other.
+ * @skipline elm_toolbar_item_append
+ * @until _item_pressed
+ *
+ * After that states can be added to this item:
+ * @skipline state_add
+ * @until Full
+ * @until _item_pressed
+ *
+ * The both states and the item are using the same callback function,
+ * that will cycle between states and unselect the item. Unseleting
+ * is required because it won't call the callback if an user clicks
+ * over an item already selected:
+ * @dontinclude toolbar_example_02.c
+ * @skip static
+ * @skip }
+ * @skipline static
+ * @until }
+ *
+ * On our example, some items are hidden
+ * because we set the window to be small. But if an item should be displayed
+ * anyway, is needed to set its priority to be higher than others.
+ * Any positive value will be enough in our case. Let's force the item
+ * with multiple states to be displayed.
+ * @skipline priority
+ *
+ * See @ref toolbar_example_02.c "toolbar_example_02.c", whose window should
+ * look like this picture:
+ *
+ * @image html screenshots/toolbar_example_02.png
+ * @image latex screenshots/toolbar_example_02.eps width=\textwidth
+ *
+ * @example toolbar_example_02.c
+ */
+
+/**
+ * @page toolbar_example_03 Toolbar Example - Items with Menus
+ *
+ * Toolbar widgets have support to items with menus. This kind
+ * of item will display a menu when selected by the user.
+ *
+ * Let's start populating a toolbar with some regular items, the same
+ * way we started @ref toolbar_example_02 "Toolbar Example 2".
+ * @dontinclude toolbar_example_03.c
+ * @skipline elm_toolbar_add
+ * @until Update
+ *
+ * The only difference is that we'll keep the default shrink mode, that
+ * adds an item with a menu of hidden items.
+ *
+ * So, a important thing to do is to set a parent for toolbar menus, or they
+ * will use the toolbar as parent, and its size will be restricted to that.
+ * @skipline parent_set
+ *
+ * Not only items' menus will respect this parent, but also the own toolbar
+ * menu, used to show hidden items.
+ *
+ * Next, let's add an item set to display a menu:
+ * @skipline elm_toolbar_item_append
+ * @until _menu_set
+ *
+ * Now, to add two options to this item, we can get the menu object and use
+ * it as a regular elm_menu. See @ref tutorial_menu "Menu example" for more
+ * about menu widget.
+ * @skipline _menu_get
+ * @until Full
+ *
+ * See @ref toolbar_example_03.c "toolbar_example_03.c", whose window should
+ * look like this picture:
+ *
+ * @image html screenshots/toolbar_example_03.png
+ * @image latex screenshots/toolbar_example_03.eps width=\textwidth
+ *
+ * @example toolbar_example_03.c
+ */
+
 /**
  * @page segment_control_example Segment Control Example
  *

legacy/elementary/doc/index.doxy

@@ -195,6 +195,11 @@
  * @image html img/widget/toggle/preview-00.png
  * @image latex img/widget/toggle/preview-00.eps
  * @li @ref Toolbar
+ *
+ * @image html img/widget/toolbar/preview-00.png
+ * @image latex img/widget/toolbar/preview-00.eps
+ * @image html img/toolbar.png
+ * @image latex img/toolbar.eps
  * @li @ref Tooltips
  * @li @ref Video
  * @li @ref Widget

legacy/elementary/doc/widgets/Makefile.am

@@ -50,6 +50,7 @@ widget_preview_label \
 widget_preview_frame \
 widget_preview_slider \
 widget_preview_panes \
+widget_preview_toolbar \
 widget_preview_ctxpopup \
 widget_preview_icon \
 widget_preview_image \
@@ -118,6 +119,7 @@ EXTRA_DIST = \
 	widget_preview_conformant.c \
 	widget_preview_slider.c \
 	widget_preview_panes.c \
+	widget_preview_toolbar.c \
 	widget_preview_ctxpopup.c \
 	widget_preview_diskselector.c \
 	widget_preview_entry1.c \

legacy/elementary/doc/widgets/widget_preview_toolbar.c

@@ -0,0 +1,13 @@
+#include "widget_preview_tmpl_head.c"
+
+Evas_Object *o = elm_toolbar_add(win);
+evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+elm_win_resize_object_add(win, o);
+evas_object_show(o);
+
+elm_toolbar_item_append(o, "document-print", "Print", NULL, NULL);
+elm_toolbar_item_append(o, "folder-new", "New Folder", NULL, NULL);
+elm_toolbar_item_append(o, "mail-send", "Send Mail", NULL, NULL);
+elm_toolbar_item_append(o, "clock", "Clock", NULL, NULL);
+
+#include "widget_preview_tmpl_foot.c"

legacy/elementary/src/examples/Makefile.am

@@ -59,6 +59,9 @@ SRCS = \
 	calendar_example_04.c \
 	calendar_example_05.c \
 	calendar_example_06.c \
+	toolbar_example_01.c \
+	toolbar_example_02.c \
+	toolbar_example_03.c \
 	spinner_example.c \
 	clock_example.c \
 	conformant_example_01.c \
@@ -154,6 +157,9 @@ pkglib_PROGRAMS += \
 	calendar_example_04 \
 	calendar_example_05 \
 	calendar_example_06 \
+	toolbar_example_01 \
+	toolbar_example_02 \
+	toolbar_example_03 \
 	spinner_example \
 	clock_example \
 	conformant_example_01 \
@@ -228,6 +234,9 @@ SCREENSHOTS = \
 	calendar_example_04:calendar_example_04.png:0.0 \
 	calendar_example_05:calendar_example_05.png:0.0 \
 	calendar_example_06:calendar_example_06.png:0.0 \
+	toolbar_example_01:toolbar_example_01.png:0.0 \
+	toolbar_example_02:toolbar_example_02.png:1 \
+	toolbar_example_03:toolbar_example_03.png:1 \
 	spinner_example:spinner_example.png:0.0 \
 	clock_example:clock_example.png:0.5 \
 	image_example_01:image_example_01.png:0.0 \

legacy/elementary/src/examples/toolbar_example_01.c

@@ -0,0 +1,100 @@
+/**
+ * Simple Elementary's <b>toolbar widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` toolbar_example_01.c -o toolbar_example_01
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static void
+_on_done(void *data __UNUSED__,
+         Evas_Object *obj __UNUSED__,
+         void *event_info __UNUSED__)
+{
+   elm_exit();
+}
+
+static void
+_item_1_pressed(void *data, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
+{
+   Evas_Object *bt = data;
+   elm_object_text_set(bt, "Print Document");
+}
+
+static void
+_item_2_pressed(void *data, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
+{
+   Evas_Object *bt = data;
+   elm_object_text_set(bt, "Create new folder");
+}
+
+static void
+_item_3_pressed(void *data, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
+{
+   /* This function won't be called because we disabled item that call it */
+   Evas_Object *bt = data;
+   elm_object_text_set(bt, "Create and send email");
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *bx, *tb, *bt;
+   Elm_Toolbar_Item *item;
+
+   win = elm_win_add(NULL, "toolbar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Toolbar Example");
+   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, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   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);
+   evas_object_show(bx);
+
+   bt = elm_button_add(win);
+   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_object_text_set(bt, "Button");
+   evas_object_show(bt);
+
+   tb = elm_toolbar_add(win);
+   elm_toolbar_mode_shrink_set(tb, ELM_TOOLBAR_SHRINK_SCROLL);
+   evas_object_size_hint_weight_set(tb, 0.0, 0.0);
+   evas_object_size_hint_align_set(tb, EVAS_HINT_FILL, 0.0);
+   evas_object_show(tb);
+
+   elm_toolbar_item_append(tb, "document-print", "Print", _item_1_pressed, bt);
+   elm_toolbar_item_append(tb, "folder-new", "New Folder", _item_2_pressed, bt);
+
+   item = elm_toolbar_item_append(tb, "mail-send", "Create and send email",
+                                  _item_3_pressed, bt);
+   elm_toolbar_item_disabled_set(item, EINA_TRUE);
+
+   elm_toolbar_homogeneous_set(tb, EINA_FALSE);
+
+   elm_box_pack_end(bx, tb);
+   elm_box_pack_end(bx, bt);
+
+   evas_object_resize(win, 200, 200);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/toolbar_example_02.c

@@ -0,0 +1,91 @@
+/**
+ * Simple Elementary's <b>toolbar widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` toolbar_example_02.c -o toolbar_example_02
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static void
+_on_done(void *data __UNUSED__,
+         Evas_Object *obj __UNUSED__,
+         void *event_info __UNUSED__)
+{
+   elm_exit();
+}
+
+static void
+_item_pressed(void *data __UNUSED__, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
+{
+   Elm_Toolbar_Item *item = event_info;
+   elm_toolbar_item_state_set(item, elm_toolbar_item_state_next(item));
+   elm_toolbar_item_selected_set(item, EINA_FALSE);
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *bx, *tb, *bt;
+   Elm_Toolbar_Item *item;
+
+   win = elm_win_add(NULL, "toolbar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Toolbar Example");
+   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, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   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);
+   evas_object_show(bx);
+
+   bt = elm_button_add(win);
+   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_object_text_set(bt, "Button");
+   evas_object_show(bt);
+
+   tb = elm_toolbar_add(win);
+   elm_toolbar_mode_shrink_set(tb, ELM_TOOLBAR_SHRINK_HIDE);
+   evas_object_size_hint_weight_set(tb, 0.0, 0.0);
+   evas_object_size_hint_align_set(tb, EVAS_HINT_FILL, 0.0);
+   evas_object_show(tb);
+
+   elm_toolbar_item_append(tb, "document-print", "Print", NULL, NULL);
+   elm_toolbar_item_append(tb, "folder-new", "Folder", NULL, NULL);
+   elm_toolbar_item_append(tb, "clock", "Clock", NULL, NULL);
+   elm_toolbar_item_append(tb, "refresh", "Update", NULL, NULL);
+
+   item = elm_toolbar_item_append(tb, "mail-send", "Send Mail",
+                                  _item_pressed, NULL);
+   elm_toolbar_item_state_add(item, "emptytrash", "Empty Trash",
+                              _item_pressed, NULL);
+   elm_toolbar_item_state_add(item, "trashcan_full", "Full Trash",
+                              _item_pressed, NULL);
+
+   elm_toolbar_item_priority_set(item, 10);
+
+   elm_box_pack_end(bx, tb);
+   elm_box_pack_end(bx, bt);
+
+   evas_object_resize(win, 230, 200);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/toolbar_example_03.c

@@ -0,0 +1,92 @@
+/**
+ * Simple Elementary's <b>toolbar widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` toolbar_example_03.c -o toolbar_example_03
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static void
+_on_done(void *data __UNUSED__,
+         Evas_Object *obj __UNUSED__,
+         void *event_info __UNUSED__)
+{
+   elm_exit();
+}
+
+static void
+_item_pressed(void *data __UNUSED__, Evas_Object *obj __UNUSED__, void *event_info __UNUSED__)
+{
+   Elm_Toolbar_Item *item = event_info;
+   elm_toolbar_item_state_set(item, elm_toolbar_item_state_next(item));
+   elm_toolbar_item_selected_set(item, EINA_FALSE);
+}
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *bx, *tb, *bt, *menu;
+   Elm_Toolbar_Item *item;
+
+   win = elm_win_add(NULL, "toolbar", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Toolbar Example");
+   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, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   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);
+   evas_object_show(bx);
+
+   bt = elm_button_add(win);
+   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_object_text_set(bt, "Button");
+   evas_object_show(bt);
+
+   tb = elm_toolbar_add(win);
+   evas_object_size_hint_weight_set(tb, 0.0, 0.0);
+   evas_object_size_hint_align_set(tb, EVAS_HINT_FILL, 0.0);
+   evas_object_show(tb);
+
+   elm_toolbar_item_append(tb, "document-print", "Print", NULL, NULL);
+   elm_toolbar_item_append(tb, "folder-new", "Folder", NULL, NULL);
+   elm_toolbar_item_append(tb, "clock", "Clock", NULL, NULL);
+   elm_toolbar_item_append(tb, "refresh", "Update", NULL, NULL);
+
+   elm_toolbar_menu_parent_set(tb, win);
+
+   item = elm_toolbar_item_append(tb, "mail-send", "Send Mail", NULL, NULL);
+   elm_toolbar_item_menu_set(item, EINA_TRUE);
+
+   menu = elm_toolbar_item_menu_get(item);
+   elm_menu_item_add(menu, NULL, "emptytrash", "Empty Trash", NULL, NULL);
+   elm_menu_item_add(menu, NULL, "trashcan_full", "Full Trash", NULL, NULL);
+
+   elm_toolbar_item_priority_set(item, 10);
+
+   elm_box_pack_end(bx, tb);
+   elm_box_pack_end(bx, bt);
+
+   evas_object_resize(win, 230, 200);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()