From e5415e6a0542f9c7787a672499d6ab48b65698b0 Mon Sep 17 00:00:00 2001 From: bdilly Date: Mon, 1 Aug 2011 21:32:25 +0000 Subject: [PATCH] Elementary: Mapbuf Documentation git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@61968 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/Makefile.am | 1 + doc/examples.dox | 84 +++++++++++++++++ doc/index.doxy | 3 + doc/widgets/Makefile.am | 2 + doc/widgets/widget_preview_mapbuf.c | 29 ++++++ src/examples/Makefile.am | 3 + src/examples/mapbuf_example.c | 127 ++++++++++++++++++++++++++ src/lib/Elementary.h.in | 175 +++++++++++++++++++++++++++++++++++- src/lib/elm_mapbuf.c | 94 ------------------- 9 files changed, 423 insertions(+), 95 deletions(-) create mode 100644 doc/widgets/widget_preview_mapbuf.c create mode 100644 src/examples/mapbuf_example.c diff --git a/doc/Makefile.am b/doc/Makefile.am index 7ea36ff..024f62d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -36,6 +36,7 @@ WGT_PREVIEW = \ 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 \ + mapbuf:preview-00.png:widget_preview_mapbuf:200:200 \ 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 \ diff --git a/doc/examples.dox b/doc/examples.dox index 1cdb7aa..4b3156e 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -39,6 +39,8 @@ * * @ref clock_example * + * @ref mapbuf_example + * * @ref diskselector_example_01 * * @ref diskselector_example_02 @@ -1766,6 +1768,88 @@ */ /** + * @page mapbuf_example Mapbuf Widget Example + * + * This code places a Elementary mapbuf widget on a window, + * to exemplify part of the widget's API. + * + * First we'll add an window with a background and a vertical box to + * pack our interface elements: + * @dontinclude mapbuf_example.c + * @skipline win_add + * @until show(bx) + * + * Next we'll simply add the mapbuf widget to the box: + * @skipline mapbuf_add + * @until pack_end + * + * But mapbuf is a container widget, it won't do anything alone. So let's + * create a table full of icons. For that we'll loop to fill each line of each + * column. See @ref tutorial_table_01 "tutorial_table_01" + * if you don't know how to use tables: + * @skipline table_add + * @until } + * @until } + * + * Finally, setting mapbuf content: + * @skipline content_set + * @skipline show + * + * Also, would be good a horizontal box with some controls to change mapbuf + * behavior: + * @skipline box_add + * @until show + * + * By default map is disabled. So just setting content isn't enough. + * Alpha and smooth settings will be applied when map is enabled. + * So we'll add a toggle for that. Everytime the map properties + * are changed, map will need to be enabled again. So if you + * want to play a bit with our example, remember to always enable + * map again after concluding your changes. + * @skipline toggle_add + * @until show + * + * We have added a callback function to this toggle, so it will enable + * or disable map: + * @dontinclude mapbuf_example.c + * @skip static + * @skip } + * @skipline static + * @until } + * + * Let's add check boxes for alpha blending and smooth rendering: + * @skipline check_add + * @until show + * @until show + * + * By default, mapbuf would enable alpha blending and smooth rendering, + * so we need to check boxes to be consistent with its behavior. + * + * Callback functions look like the one added to the toggle. This way we + * could enable or disable the both properties: + * @dontinclude mapbuf_example.c + * @skip static + * @skip } + * @skip static + * @skip } + * @skipline static + * @until } + * @until } + * + * You'll see that disabling alpha blending will set a black rectangle below + * the icons. That's the reason you only should enable that when you're sure + * the mapbuf content is 100% solid. + * + * See @ref mapbuf_example.c "mapbuf_example.c", whose window should + * look like this picture: + * + * @image html screenshots/mapbuf_example.png + * @image latex screenshots/mapbuf_example.eps width=\textwidth + * + * @example mapbuf_example.c + */ + +/** * @page diskselector_example_01 Diskselector widget example * * This code places 4 Elementary diskselector widgets on a window, each of diff --git a/doc/index.doxy b/doc/index.doxy index 956c861..55e783b 100644 --- a/doc/index.doxy +++ b/doc/index.doxy @@ -137,6 +137,9 @@ * @image latex img/widget/label/preview-00.eps * @li @ref Map * @li @ref Mapbuf + * + * @image html img/widget/mapbuf/preview-00.png + * @image latex img/widget/mapbuf/preview-00.eps * @li @ref Menu * * @image html img/widget/menu/preview-00.png diff --git a/doc/widgets/Makefile.am b/doc/widgets/Makefile.am index 1bfb9b8..8221adb 100644 --- a/doc/widgets/Makefile.am +++ b/doc/widgets/Makefile.am @@ -51,6 +51,7 @@ widget_preview_frame \ widget_preview_slider \ widget_preview_panes \ widget_preview_toolbar \ +widget_preview_mapbuf \ widget_preview_ctxpopup \ widget_preview_icon \ widget_preview_image \ @@ -121,6 +122,7 @@ EXTRA_DIST = \ widget_preview_slider.c \ widget_preview_panes.c \ widget_preview_toolbar.c \ + widget_preview_mapbuf.c \ widget_preview_ctxpopup.c \ widget_preview_diskselector.c \ widget_preview_entry1.c \ diff --git a/doc/widgets/widget_preview_mapbuf.c b/doc/widgets/widget_preview_mapbuf.c new file mode 100644 index 0000000..812c76c --- /dev/null +++ b/doc/widgets/widget_preview_mapbuf.c @@ -0,0 +1,29 @@ +#include "widget_preview_tmpl_head.c" + +Evas_Object *o = elm_mapbuf_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); + +Evas_Object *tb = elm_table_add(win); +evas_object_size_hint_weight_set(tb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); +evas_object_size_hint_fill_set(tb, EVAS_HINT_FILL, EVAS_HINT_FILL); +evas_object_show(tb); + +unsigned int i, j; +for (i = 0; i < 8; i++) + { + for (j = 0; j < 8; j++) + { + Evas_Object *ic = elm_icon_add(win); + elm_icon_standard_set(ic, "home"); + elm_icon_scale_set(ic, EINA_FALSE, EINA_FALSE); + evas_object_show(ic); + elm_table_pack(tb, ic, i, j, 1, 1); + } + } + +elm_mapbuf_content_set(o, tb); +elm_mapbuf_enabled_set(o, EINA_TRUE); + +#include "widget_preview_tmpl_foot.c" diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index 5e70e9d..fe9778e 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -64,6 +64,7 @@ SRCS = \ toolbar_example_03.c \ spinner_example.c \ clock_example.c \ + mapbuf_example.c \ conformant_example_01.c \ conformant_example_02.c \ image_example_01.c \ @@ -163,6 +164,7 @@ pkglib_PROGRAMS += \ toolbar_example_03 \ spinner_example \ clock_example \ + mapbuf_example \ conformant_example_01 \ conformant_example_02 \ image_example_01 \ @@ -241,6 +243,7 @@ SCREENSHOTS = \ toolbar_example_03:toolbar_example_03.png:1 \ spinner_example:spinner_example.png:0.0 \ clock_example:clock_example.png:0.5 \ + mapbuf_example:mapbuf_example.png:0.0 \ image_example_01:image_example_01.png:0.0 \ diskselector_example_01:diskselector_example_01.png:0.2 \ diskselector_example_02:diskselector_example_02.png:0.2 \ diff --git a/src/examples/mapbuf_example.c b/src/examples/mapbuf_example.c new file mode 100644 index 0000000..de2dae5 --- /dev/null +++ b/src/examples/mapbuf_example.c @@ -0,0 +1,127 @@ +/** + * Simple Elementary's mapbuf widget example, illustrating its API. + * + * See stdout/stderr for output. Compile with: + * + * @verbatim + * gcc -g `pkg-config --cflags --libs elementary` mapbuf_example.c -o mapbuf_example + * @endverbatim + */ + +#include +#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 +_enabled_cb(void *data, Evas_Object *obj, void *event_info __UNUSED__) +{ + Evas_Object *mb = data; + elm_mapbuf_enabled_set(mb, elm_toggle_state_get(obj)); +} + +static void +_alpha_cb(void *data, Evas_Object *obj, void *event_info __UNUSED__) +{ + Evas_Object *mb = data; + elm_mapbuf_alpha_set(mb, elm_check_state_get(obj)); +} + +static void +_smooth_cb(void *data, Evas_Object *obj, void *event_info __UNUSED__) +{ + Evas_Object *mb = data; + elm_mapbuf_smooth_set(mb, elm_check_state_get(obj)); +} + +EAPI int +elm_main(int argc __UNUSED__, char **argv __UNUSED__) +{ + Evas_Object *win, *bg, *bx, *hbx, *tg, *ck, *mb, *tb, *ic; + unsigned int i, j; + + win = elm_win_add(NULL, "mapbuf", ELM_WIN_BASIC); + elm_win_title_set(win, "Mapbuf 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); + 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_win_resize_object_add(win, bx); + evas_object_show(bx); + + mb = elm_mapbuf_add(win); + evas_object_size_hint_weight_set(mb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(mb, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_box_pack_end(bx, mb); + + tb = elm_table_add(win); + evas_object_size_hint_weight_set(tb, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(tb, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(tb); + + for (i = 0; i < 8; i++) + { + for (j = 0; j < 8; j++) + { + ic = elm_icon_add(win); + elm_icon_standard_set(ic, "home"); + elm_icon_scale_set(ic, EINA_FALSE, EINA_FALSE); + evas_object_show(ic); + elm_table_pack(tb, ic, i, j, 1, 1); + } + } + + elm_mapbuf_content_set(mb, tb); + evas_object_show(mb); + + hbx = elm_box_add(win); + elm_box_horizontal_set(hbx, EINA_TRUE); + evas_object_size_hint_weight_set(hbx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(hbx, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_box_pack_end(bx, hbx); + evas_object_show(hbx); + + tg = elm_toggle_add(win); + elm_object_text_set(tg, "Map"); + elm_toggle_states_labels_set(tg, "Enabled", "Disabled"); + evas_object_smart_callback_add(tg, "changed", _enabled_cb, mb); + elm_box_pack_end(hbx, tg); + evas_object_show(tg); + + ck = elm_check_add(win); + elm_object_text_set(ck, "Alpha"); + elm_check_state_set(ck, EINA_TRUE); + evas_object_smart_callback_add(ck, "changed", _alpha_cb, mb); + elm_box_pack_end(hbx, ck); + evas_object_show(ck); + + ck = elm_check_add(win); + elm_object_text_set(ck, "Smooth"); + elm_check_state_set(ck, EINA_TRUE); + evas_object_smart_callback_add(ck, "changed", _smooth_cb, mb); + elm_box_pack_end(hbx, ck); + evas_object_show(ck); + + evas_object_resize(win, 240, 320); + evas_object_show(win); + + elm_run(); + return 0; +} +ELM_MAIN() diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index e0a2a6f..929ee33 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -19068,19 +19068,192 @@ extern "C" { * @} */ - /* mapbuf */ + /** + * @defgroup Mapbuf Mapbuf + * @ingroup Elementary + * + * @image html img/widget/mapbuf/preview-00.png + * @image latex img/widget/mapbuf/preview-00.eps width=\textwidth + * + * This holds one content object and uses an Evas Map of transformation + * points to be later used with this content. So the content will be + * moved, resized, etc as a single image. So it will improve performance + * when you have a complex interafce, with a lot of elements, and will + * need to resize or move it frequently (the content object and its + * children). + * + * See how to use this widget in this example: + * @ref mapbuf_example + */ + + /** + * @addtogroup Mapbuf + * @{ + */ + + /** + * Add a new mapbuf widget to the given parent Elementary + * (container) object. + * + * @param parent The parent object. + * @return A new mapbuf widget handle or @c NULL, on errors. + * + * This function inserts a new mapbuf widget on the canvas. + * + * @ingroup Mapbuf + */ EAPI Evas_Object *elm_mapbuf_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + + /** + * Set the content of the mapbuf. + * + * @param obj The mapbuf object. + * @param content The content that will be filled in this mapbuf object. + * + * Once the content object is set, a previously set one will be deleted. + * If you want to keep that old content object, use the + * elm_mapbuf_content_unset() function. + * + * To enable map, elm_mapbuf_enabled_set() should be used. + * + * @ingroup Mapbuf + */ EAPI void elm_mapbuf_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1); + + /** + * Get the content of the mapbuf. + * + * @param obj The mapbuf object. + * @return The content that is being used. + * + * Return the content object which is set for this widget. + * + * @see elm_mapbuf_content_set() for details. + * + * @ingroup Mapbuf + */ EAPI Evas_Object *elm_mapbuf_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Unset the content of the mapbuf. + * + * @param obj The mapbuf object. + * @return The content that was being used. + * + * Unparent and return the content object which was set for this widget. + * + * @see elm_mapbuf_content_set() for details. + * + * @ingroup Mapbuf + */ EAPI Evas_Object *elm_mapbuf_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Enable or disable the map. + * + * @param obj The mapbuf object. + * @param enabled @c EINA_TRUE to enable map or @c EINA_FALSE to disable it. + * + * This enables the map that is set or disables it. On enable, the object + * geometry will be saved, and the new geometry will change (position and + * size) to reflect the map geometry set. + * + * Also, when enabled, alpha and smooth states will be used, so if the + * content isn't solid, alpha should be enabled, for example, otherwise + * a black retangle will fill the content. + * + * When disabled, the stored map will be freed and geometry prior to + * enabling the map will be restored. + * + * It's disabled by default. + * + * @see elm_mapbuf_alpha_set() + * @see elm_mapbuf_smooth_set() + * + * @ingroup Mapbuf + */ EAPI void elm_mapbuf_enabled_set(Evas_Object *obj, Eina_Bool enabled) EINA_ARG_NONNULL(1); + + /** + * Get a value whether map is enabled or not. + * + * @param obj The mapbuf object. + * @return The value that the enabled state is set to. + * @return @c EINA_TRUE means map is enabled. @c EINA_FALSE indicates + * it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_mapbuf_enabled_set() for details. + * + * @ingroup Mapbuf + */ EAPI Eina_Bool elm_mapbuf_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Enable or disable smooth map rendering. + * + * @param obj The mapbuf object. + * @param smooth @c EINA_TRUE to enable smooth map rendering or @c EINA_FALSE + * to disable it. + * + * This sets smoothing for map rendering. If the object is a type that has + * its own smoothing settings, then both the smooth settings for this object + * and the map must be turned off. + * + * By default smooth maps are enabled. + * + * @ingroup Mapbuf + */ EAPI void elm_mapbuf_smooth_set(Evas_Object *obj, Eina_Bool smooth) EINA_ARG_NONNULL(1); + + /** + * Get a value whether smooth map rendering is enabled or not. + * + * @param obj The mapbuf object. + * @return @c EINA_TRUE means smooth map rendering is enabled. @c EINA_FALSE + * indicates it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_mapbuf_smooth_set() for details. + * + * @ingroup Mapbuf + */ EAPI Eina_Bool elm_mapbuf_smooth_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set or unset alpha flag for map rendering. + * + * @param obj The mapbuf object. + * @param alpha @c EINA_TRUE to enable alpha blending or @c EINA_FALSE + * to disable it. + * + * This sets alpha flag for map rendering. If the object is a type that has + * its own alpha settings, then this will take precedence. Only image objects + * have this currently. It stops alpha blending of the map area, and is + * useful if you know the object and/or all sub-objects is 100% solid. + * + * Alpha is enabled by default. + * + * @ingroup Mapbuf + */ EAPI void elm_mapbuf_alpha_set(Evas_Object *obj, Eina_Bool alpha) EINA_ARG_NONNULL(1); + + /** + * Get a value whether alpha blending is enabled or not. + * + * @param obj The mapbuf object. + * @return @c EINA_TRUE means alpha blending is enabled. @c EINA_FALSE + * indicates it's disabled. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_mapbuf_alpha_set() for details. + * + * @ingroup Mapbuf + */ EAPI Eina_Bool elm_mapbuf_alpha_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); /** + * @} + */ + + /** * @defgroup Flipselector Flip Selector * * @image html img/widget/flipselector/preview-00.png diff --git a/src/lib/elm_mapbuf.c b/src/lib/elm_mapbuf.c index 09b1a04..c87ecff 100644 --- a/src/lib/elm_mapbuf.c +++ b/src/lib/elm_mapbuf.c @@ -1,12 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Mapbuf Mapbuf - * - * This holds 1 content object and uses an Evas Map to move/resize etc. it. - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -152,14 +146,6 @@ _resize(void *data __UNUSED__, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, _configure(data); } -/** - * Add a new mapbuf to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Mapbuf - */ EAPI Evas_Object * elm_mapbuf_add(Evas_Object *parent) { @@ -196,18 +182,6 @@ elm_mapbuf_add(Evas_Object *parent) return obj; } -/** - * Set the mapbuf front content - * - * Once the content object is set, a previously set one will be deleted. - * If you want to keep that old content object, use the - * elm_mapbuf_content_unset() function. - * - * @param obj The mapbuf object - * @param content The content will be filled in this mapbuf object - * - * @ingroup Mapbuf - */ EAPI void elm_mapbuf_content_set(Evas_Object *obj, Evas_Object *content) { @@ -234,16 +208,6 @@ elm_mapbuf_content_set(Evas_Object *obj, Evas_Object *content) _configure(obj); } -/** - * Get the mapbuf front content - * - * Return the content object which is set for this widget. - * - * @param obj The mapbuf object - * @return The content that is being used - * - * @ingroup Mapbuf - */ EAPI Evas_Object * elm_mapbuf_content_get(const Evas_Object *obj) { @@ -253,16 +217,6 @@ elm_mapbuf_content_get(const Evas_Object *obj) return wd->content; } -/** - * Unset the mapbuf front content - * - * Unparent and return the content object which was set for this widget. - * - * @param obj The mapbuf object - * @return The content that was being used - * - * @ingroup Mapbuf - */ EAPI Evas_Object * elm_mapbuf_content_unset(Evas_Object *obj) { @@ -281,14 +235,6 @@ elm_mapbuf_content_unset(Evas_Object *obj) return content; } -/** - * Set the mapbuf enabled state - * - * @param obj The mapbuf object - * @param enabled The value to set the enabled state to - * - * @ingroup Mapbuf - */ EAPI void elm_mapbuf_enabled_set(Evas_Object *obj, Eina_Bool enabled) { @@ -301,14 +247,6 @@ elm_mapbuf_enabled_set(Evas_Object *obj, Eina_Bool enabled) _configure(obj); } -/** - * Get the mapbuf enabled state - * - * @param obj The mapbuf object - * @return The value that the enabled state is set to - * - * @ingroup Mapbuf - */ EAPI Eina_Bool elm_mapbuf_enabled_get(const Evas_Object *obj) { @@ -318,14 +256,6 @@ elm_mapbuf_enabled_get(const Evas_Object *obj) return wd->enabled; } -/** - * Sets the mapbuf smooth state - * - * @param obj The mapbuf object - * @param smooth The value of the smooth state of @p obj - * - * @ingroup Mapbuf - */ EAPI void elm_mapbuf_smooth_set(Evas_Object *obj, Eina_Bool smooth) { @@ -337,14 +267,6 @@ elm_mapbuf_smooth_set(Evas_Object *obj, Eina_Bool smooth) _configure(obj); } -/** - * Gets the mapbuf smooth state - * - * @param obj The mapbuf object - * @return The value of the smooth state of @p obj - * - * @ingroup Mapbuf - */ EAPI Eina_Bool elm_mapbuf_smooth_get(const Evas_Object *obj) { @@ -354,14 +276,6 @@ elm_mapbuf_smooth_get(const Evas_Object *obj) return wd->smooth; } -/** - * Enables/disables the mapbuf alpha channel - * - * @param obj The mapbuf object - * @param alpha The state of the alpha channel - * - * @ingroup Mapbuf - */ EAPI void elm_mapbuf_alpha_set(Evas_Object *obj, Eina_Bool alpha) { @@ -373,14 +287,6 @@ elm_mapbuf_alpha_set(Evas_Object *obj, Eina_Bool alpha) _configure(obj); } -/** - * Gets the state of the mapbuf alpha channel - * - * @param obj The mapbuf object - * @return The state of the alpha channel - * - * @ingroup Mapbuf - */ EAPI Eina_Bool elm_mapbuf_alpha_get(const Evas_Object *obj) { -- 2.7.4