From f6047df5a4d224f48ad4fd46b45c4c1a64e696de Mon Sep 17 00:00:00 2001 From: Gustavo Lima Chaves Date: Wed, 22 Jun 2011 14:52:05 +0000 Subject: [PATCH] [elementary] Example for top level functions. SVN revision: 60595 --- legacy/elementary/doc/examples.dox | 125 +++++++++++ legacy/elementary/src/examples/Makefile.am | 8 +- .../src/examples/general_funcs_example.c | 194 ++++++++++++++++++ legacy/elementary/src/lib/Elementary.h.in | 21 ++ 4 files changed, 346 insertions(+), 2 deletions(-) create mode 100644 legacy/elementary/src/examples/general_funcs_example.c diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index b069485be8..b0baf5e7fe 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -16,6 +16,8 @@ * @ref transit_example_01_explained * * @ref transit_example_02_explained + * + * @ref general_functions_example_page */ /** @@ -579,6 +581,123 @@ * transition chain. */ +/** + * @page general_functions_example_page General (top-level) functions example + * @dontinclude general_funcs_example.c + * + * As told in their documentation blocks, the + * elm_app_compile_*_dir_set() family of functions have to be called + * before elm_app_info_set(): + * @skip tell elm about + * @until elm_app_info_set + * + * We are here setting the fallback paths to the compiling time target + * paths, naturally. If you're building the example out of the + * project's build system, we're assuming they are the canonical ones. + * + * After the program starts, elm_app_info_set() will actually run and + * then you'll see an intrincasy: Elementary does the prefix lookup @b + * twice. This is so because of the quicklaunch infrastructure in + * Elementary (@ref Start), which will register a predefined prefix + * for possible users of the launch schema. We're not hooking into a + * quick launch, so this first call can't be avoided. + * + * If you ran this example from your "bindir" installation + * directiory, no output will emerge from these both attempts -- it + * will find the "magic" file there registered and set the prefixes + * silently. Otherwise, you could get something like: + @verbatim + WARNING: Could not determine its installed prefix for 'ELM' + so am falling back on the compiled in default: + usr + implied by the following: + bindir = usr/lib + libdir = usr/lib + datadir = usr/share/elementary + localedir = usr/share/locale + Try setting the following environment variables: + ELM_PREFIX - points to the base prefix of install + or the next 4 variables + ELM_BIN_DIR - provide a specific binary directory + ELM_LIB_DIR - provide a specific library directory + ELM_DATA_DIR - provide a specific data directory + ELM_LOCALE_DIR - provide a specific locale directory + @endverbatim + * if you also didn't change those environment variables (remember + * they are also a valid way of communicating your prefix to the + * binary) - this is the scenario where it fallbacks to the paths set + * for compile time. + * + * Then, you can check the prefixes set on the standard output: + * @skip prefix was set to + * @until locale directory is + * + * In the fragment + * @skip by using this policy + * @until elm_win_autodel_set + * we demonstrate the use of Elementary policies. The policy defining + * under which circunstances our application should quit automatically + * is set to when its last window is closed (this one has just one + * window, though). This will save us from having to set a callback + * ourselves on the window, like done in @ref bg_example_01_c "this" + * example. Note that we need to tell the window to delete itself's + * object on a request to destroy the canvas coming, with + * elm_win_autodel_set(). + * + * What follows is some boilerplate code, creating a frame with a @b + * button, our object of interest, and, below, widgets to change the + * button's behavior and exemplify the group of functions in question. + * + * @dontinclude general_funcs_example.c + * We enabled the focus highlight object for this window, so that you + * can keep track of the current focused object better: + * @skip elm_win_focus_highlight_enabled_set + * @until evas_object_show + * Use the tab key to navigate through the focus chain. + * + * @dontinclude general_funcs_example.c + * While creating the button, we exemplify how to use Elementary's + * finger size information to scale our UI: + * @skip fprintf(stdout, "Elementary + * @until evas_object_show + * + * @dontinclude general_funcs_example.c + * The first checkbox's callback is: + * @skip static void + * @until } + * When unsetting the checkbox, we disable the button, which will get a new + * decoration (greyed out) and stop receiving events. The focus chain + * will also ignore it. + * + * Following, there are 2 more buttons whose actions are focus/unfocus + * the top button, respectively: + * @skip focus callback + * @until } + * and + * @skip unfocus callback + * @until } + * Note the situations in which they won't take effect: + * - the button is not allowed to get focus or + * - the button is disabled + * + * The first restriction above you'll get by a second checkbox, whose + * callback is: + * @skip focus allow callback + * @until } + * Note that the button will still get mouse events, though. + * + * Next, there's a slider controlling the button's scale: + * @skip scaling callback + * @until } + * + * Experiment with it, so you understand the effect better. If you + * change its value, it will mess with the button's original size, + * naturally. + * + * The full code for this example can be found + * @ref general_functions_example_c "here". + */ + /** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c @@ -620,3 +739,9 @@ * @include transit_example_02.c * @example transit_example_02.c */ + +/** + * @page general_functions_example_c General (top-level) functions example + * @include general_funcs_example.c + * @example general_funcs_example.c + */ diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index 53896fdd95..094d1038db 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -9,6 +9,8 @@ AM_CPPFLAGS = \ -I$(top_srcdir)/src/lib \ -I$(top_builddir)/src/lib \ -DPACKAGE_DATA_DIR="\"$(datadir)/elementary\"" \ +-DPACKAGE_BIN_DIR=\"$(bindir)\" \ +-DPACKAGE_LIB_DIR=\"$(libdir)\" \ @ELEMENTARY_EDBUS_CFLAGS@ \ @ELEMENTARY_EFREET_CFLAGS@ \ @ELEMENTARY_ETHUMB_CFLAGS@ \ @@ -28,7 +30,8 @@ SRCS = \ transit_example_04.c \ bg_example_01.c \ bg_example_02.c \ - bg_example_03.c + bg_example_03.c \ + general_funcs_example.c pkglib_PROGRAMS = @@ -48,7 +51,8 @@ pkglib_PROGRAMS += \ transit_example_04 \ bg_example_01 \ bg_example_02 \ - bg_example_03 + bg_example_03 \ + general_funcs_example # This variable will hold the list of screenshots that will be made # by "make screenshots". Each item in the list is of the form: diff --git a/legacy/elementary/src/examples/general_funcs_example.c b/legacy/elementary/src/examples/general_funcs_example.c new file mode 100644 index 0000000000..b7e509fae4 --- /dev/null +++ b/legacy/elementary/src/examples/general_funcs_example.c @@ -0,0 +1,194 @@ +/* Compile with: + * gcc -g `pkg-config --cflags --libs elementary` general_funcs_example.c -o general_funcs_example + */ + +#include + +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#else +# define __UNUSED__ +# define PACKAGE_BIN_DIR "/usr/bin" +# define PACKAGE_LIB_DIR "/usr/lib" +# define PACKAGE_DATA_DIR "/usr/share/elementary" +#endif + +#define WIDTH 300 +#define HEIGHT 300 + +struct test_data +{ + Evas_Object *btn; + Eina_Bool btn_enabled; + Eina_Bool btn_gets_focus; +}; + +struct test_data d = {NULL, EINA_TRUE, EINA_TRUE}; + +static void +_btn_enabled_cb(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event __UNUSED__) +{ + elm_object_disabled_set(d.btn, !d.btn_enabled); +} + +static void +/* focus callback */ +_btn_focus_cb(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event __UNUSED__) +{ + elm_object_focus(d.btn); +} + +static void +/* unfocus callback */ +_btn_unfocus_cb(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event __UNUSED__) +{ + elm_object_unfocus(d.btn); +} + +static void +/* focus allow callback */ +_btn_focus_allow_cb(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event __UNUSED__) +{ + elm_object_focus_allow_set(d.btn, d.btn_gets_focus); +} + +static void /* scaling callback */ +_btn_scale_cb(void *data __UNUSED__, + Evas_Object *obj, + void *event __UNUSED__) +{ + elm_object_scale_set(d.btn, elm_slider_value_get(obj)); +} + +int +elm_main(int argc __UNUSED__, + char **argv __UNUSED__) +{ + int h; + Evas_Object *win, *bg, *box, *frame, *check, *b, *slider; + + /* tell elm about our app so it can figure out where to get files */ + elm_app_compile_bin_dir_set(PACKAGE_BIN_DIR); + elm_app_compile_data_dir_set(PACKAGE_DATA_DIR); + elm_app_compile_lib_dir_set(PACKAGE_LIB_DIR); + elm_app_info_set(elm_main, "elementary", "images/logo.png"); + + fprintf(stdout, "prefix was set to: %s\n", elm_app_prefix_dir_get()); + fprintf(stdout, "data directory is: %s\n", elm_app_data_dir_get()); + fprintf(stdout, "library directory is: %s\n", elm_app_lib_dir_get()); + fprintf(stdout, "locale directory is: %s\n", elm_app_locale_dir_get()); + + win = elm_win_add(NULL, "top-level-funcs-example", ELM_WIN_BASIC); + elm_win_title_set(win, "Elementary Top-level Functions Example"); + + /* by using this policy value, we avoid having to + * evas_object_smart_callback_add(win, "delete,request", _on_exit, NULL), + * calling elm_exit() on that callback ourselves. + */ + elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED); + elm_win_autodel_set(win, EINA_TRUE); + + bg = elm_bg_add(win); + evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_win_resize_object_add(win, bg); + evas_object_show(bg); + evas_object_size_hint_min_set(bg, 160, 160); + + /* outer box */ + box = elm_box_add(win); + evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_win_resize_object_add(win, box); + evas_object_show(box); + + frame = elm_frame_add(win); + elm_frame_label_set(frame, "Button"); + evas_object_size_hint_align_set(frame, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_show(frame); + elm_box_pack_end(box, frame); + + d.btn = elm_button_add(win); + elm_button_label_set(d.btn, "Click me"); + elm_frame_content_set(frame, d.btn); + + fprintf(stdout, "Elementary's finger size is set to %d pixels\n.", + elm_finger_size_get()); + elm_coords_finger_size_adjust(0, NULL, 3, &h); + /* so, button will be 3 fingers tall */ + evas_object_size_hint_min_set(d.btn, 0, h); + evas_object_show(d.btn); + + b = elm_box_add(win); + elm_box_horizontal_set(b, EINA_FALSE); + evas_object_size_hint_weight_set(b, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(b, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_win_resize_object_add(win, b); + elm_box_pack_end(box, b); + evas_object_show(b); + + check = elm_check_add(win); + evas_object_size_hint_weight_set(check, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(check, 0.0, 0.0); + elm_check_label_set(check, "Button enabled"); + elm_check_state_pointer_set(check, &d.btn_enabled); + evas_object_smart_callback_add(check, "changed", _btn_enabled_cb, NULL); + elm_box_pack_end(box, check); + evas_object_show(check); + + b = elm_button_add(win); + evas_object_size_hint_weight_set(b, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(b, 0.0, 0.0); + elm_button_label_set(b, "Focus top button"); + evas_object_smart_callback_add(b, "clicked", _btn_focus_cb, NULL); + elm_box_pack_end(box, b); + evas_object_show(b); + + b = elm_button_add(win); + evas_object_size_hint_weight_set(b, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(b, 0.0, 0.0); + elm_button_label_set(b, "Unfocus top button"); + evas_object_smart_callback_add(b, "clicked", _btn_unfocus_cb, NULL); + elm_box_pack_end(box, b); + evas_object_show(b); + + check = elm_check_add(win); + evas_object_size_hint_weight_set(check, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(check, 0.0, 0.0); + elm_check_label_set(check, "Button gets focus"); + elm_check_state_pointer_set(check, &d.btn_gets_focus); + evas_object_smart_callback_add(check, "changed", _btn_focus_allow_cb, NULL); + elm_box_pack_end(box, check); + evas_object_show(check); + + slider = elm_slider_add(win); + elm_slider_min_max_set(slider, 0, 4); + elm_slider_unit_format_set(slider, "%1.1f"); + elm_slider_indicator_format_set(slider, "%1.1f"); + evas_object_size_hint_weight_set( + slider, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(slider, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_smart_callback_add(slider, "changed", _btn_scale_cb, NULL); + elm_box_pack_end(box, slider); + evas_object_show(slider); + + evas_object_resize(win, WIDTH, HEIGHT); + elm_win_focus_highlight_enabled_set(win, EINA_TRUE); + evas_object_show(win); + + elm_run(); /* and run the program now, starting to handle all + * events, etc. */ + elm_shutdown(); /* clean up and shut down */ + + /* exit code */ + return 0; +} + +ELM_MAIN() diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index ad1fd1e4e1..8fe7d673c0 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -222,6 +222,9 @@ extern "C" { * Here are documented functions which init/shutdown the library, * that apply to generic Elementary objects, that deal with * configuration, et cetera. + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ /** @@ -417,6 +420,9 @@ extern "C" { * @see elm_init() for an example. There, just after a request to * close the window comes, the main loop will be left. * + * @note By using the #ELM_POLICY_QUIT on your Elementary + * applications, you'll this function called automatically for you. + * * @ingroup General */ EAPI void elm_exit(void); @@ -699,6 +705,9 @@ extern "C" { * child also has a scale size set it is in turn multiplied by its * parent's scale size. @c 1.0 means “don't scale”, @c 2.0 is * double size, @c 0.5 is half, etc. + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ /** @@ -734,6 +743,9 @@ extern "C" { * Widgets can have different styles of look. These generic API's * set styles of widgets, if they support them (and if the theme(s) * do). + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ /** @@ -775,6 +787,9 @@ extern "C" { * How to check if an Evas Object is an Elementary widget? How to * get the first elementary widget that is parent of the given * object? These are all covered in widget tree navigation. + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ EAPI Eina_Bool elm_object_widget_check(const Evas_Object *obj) EINA_ARG_NONNULL(1); @@ -867,6 +882,9 @@ extern "C" { * on touchscreens. * * Different profiles may have pre-set values for finger sizes. + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ /** @@ -911,6 +929,9 @@ extern "C" { * creation, by their very nature: they are not meant to be * interacted with input events, but are there just for visual * purposes. + * + * @ref general_functions_example_page "This" example contemplates + * some of these functions. */ EAPI Eina_Bool elm_focus_highlight_enabled_get(void);