From c8e506d9ed9ea33db46f4256765600e4411d692b Mon Sep 17 00:00:00 2001 From: Rafael Antognolli Date: Thu, 16 Jun 2011 14:10:23 +0000 Subject: [PATCH] elementary: add some examples and a better explanation to elm_bg. The example code was copied from elementary_test, but now there are 3 pages (one for each example) explaining its usage. SVN revision: 60394 --- legacy/elementary/src/examples/Makefile.am | 12 +- .../elementary/src/examples/bg_example_01.c | 48 +++ .../elementary/src/examples/bg_example_02.c | 44 ++ .../elementary/src/examples/bg_example_03.c | 170 ++++++++ legacy/elementary/src/lib/Elementary.h.in | 406 ++++++++++++++++++ legacy/elementary/src/lib/elm_bg.c | 124 ------ 6 files changed, 678 insertions(+), 126 deletions(-) create mode 100644 legacy/elementary/src/examples/bg_example_01.c create mode 100644 legacy/elementary/src/examples/bg_example_02.c create mode 100644 legacy/elementary/src/examples/bg_example_03.c diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index a0bf8fbf0f..8df3835408 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -6,6 +6,7 @@ AM_CPPFLAGS = \ -I. \ -I$(top_srcdir)/src/lib \ -I$(top_builddir)/src/lib \ +-DPACKAGE_DATA_DIR="\"$(datadir)/elementary\"" \ @ELEMENTARY_EDBUS_CFLAGS@ \ @ELEMENTARY_EFREET_CFLAGS@ \ @ELEMENTARY_ETHUMB_CFLAGS@ \ @@ -15,7 +16,10 @@ LDADD = \ $(top_builddir)/src/lib/libelementary.la SRCS = \ - actionslider_example_01.c + actionslider_example_01.c \ + bg_example_01.c \ + bg_example_02.c \ + bg_example_03.c pkglib_PROGRAMS = @@ -26,6 +30,10 @@ endif if EFL_BUILD_EXAMPLES pkglib_PROGRAMS += \ - actionslider_example_01 + actionslider_example_01 \ + bg_example_01 \ + bg_example_02 \ + bg_example_03 + endif diff --git a/legacy/elementary/src/examples/bg_example_01.c b/legacy/elementary/src/examples/bg_example_01.c new file mode 100644 index 0000000000..5d866f660d --- /dev/null +++ b/legacy/elementary/src/examples/bg_example_01.c @@ -0,0 +1,48 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` bg_example_03.c -o bg_example_03 + +#include + +static void +on_done(void *data, Evas_Object *obj, void *event_info) +{ + /* quit the mainloop (elm_run) */ + elm_exit(); +} + +int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg; + + win = elm_win_add(NULL, "bg-plain", ELM_WIN_BASIC); + elm_win_title_set(win, "Bg Plain"); + evas_object_smart_callback_add(win, "delete,request", on_done, NULL); + elm_win_autodel_set(win, 1); + + bg = elm_bg_add(win); + /* allow bg to expand in x & y */ + evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_win_resize_object_add(win, bg); + evas_object_show(bg); + + /* set size hints. a minimum size for the bg. this should propagate back + * to the window thus limiting its size based off the bg as the bg is one + * of the window's resize objects. */ + evas_object_size_hint_min_set(bg, 160, 160); + /* and set a maximum size. not needed very often. normally used together + * with evas_object_size_hint_min_set() at the same size to make a + * window not resizable */ + evas_object_size_hint_max_set(bg, 640, 640); + /* and now just resize the window to a size you want. normally widgets + * will determine the initial size though */ + evas_object_resize(win, 320, 320); + /* and show the window */ + evas_object_show(win); + + elm_run(); + + return 0; +} + +ELM_MAIN() diff --git a/legacy/elementary/src/examples/bg_example_02.c b/legacy/elementary/src/examples/bg_example_02.c new file mode 100644 index 0000000000..238bf3589f --- /dev/null +++ b/legacy/elementary/src/examples/bg_example_02.c @@ -0,0 +1,44 @@ +//Compile with: +//gcc -g -DPACKAGE_DATA_DIR="\"\"" `pkg-config --cflags --libs elementary` bg_example_02.c -o bg_example_02 +// where directory is the a path where images/plant_01.jpg can be found. + +#include + +static void +on_done(void *data, Evas_Object *obj, void *event_info) +{ + /* quit the mainloop (elm_run) */ + elm_exit(); +} + +int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg; + char buf[PATH_MAX]; + + win = elm_win_add(NULL, "bg-image", ELM_WIN_BASIC); + elm_win_title_set(win, "Bg Image"); + evas_object_smart_callback_add(win, "delete,request", on_done, NULL); + elm_win_autodel_set(win, 1); + + bg = elm_bg_add(win); + elm_bg_option_set(bg, ELM_BG_OPTION_CENTER); + snprintf(buf, sizeof(buf), "%s/images/plant_01.jpg", PACKAGE_DATA_DIR); + elm_bg_file_set(bg, buf, NULL); + elm_bg_load_size_set(bg, 20, 20); + 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); + evas_object_size_hint_max_set(bg, 640, 640); + evas_object_resize(win, 320, 320); + evas_object_show(win); + + elm_run(); + + return 0; +} + +ELM_MAIN() diff --git a/legacy/elementary/src/examples/bg_example_03.c b/legacy/elementary/src/examples/bg_example_03.c new file mode 100644 index 0000000000..f450ed0aab --- /dev/null +++ b/legacy/elementary/src/examples/bg_example_03.c @@ -0,0 +1,170 @@ +//Compile with: +//gcc -g -DPACKAGE_DATA_DIR="\"\"" `pkg-config --cflags --libs elementary` bg_example_03.c -o bg_example_03 +// where directory is the a path where images/plant_01.jpg can be found. + +#include + +static void +on_done(void *data, Evas_Object *obj, void *event_info) +{ + /* quit the mainloop (elm_run) */ + elm_exit(); +} + +static void +_cb_radio_changed(void *data, Evas_Object *obj, void *event) +{ + Evas_Object *o_bg = data; + + elm_bg_option_set(o_bg, elm_radio_value_get((Evas_Object *)obj)); +} + +static void +_cb_overlay_changed(void *data, Evas_Object *obj, void *event) +{ + Evas_Object *o_bg = data; + + if (elm_check_state_get(obj)) + { + Evas_Object *parent, *over; + char buff[PATH_MAX]; + + snprintf(buff, sizeof(buff), "%s/objects/test.edj", PACKAGE_DATA_DIR); + parent = elm_object_parent_widget_get(o_bg); + over = edje_object_add(evas_object_evas_get(parent)); + edje_object_file_set(over, buff, "bg_overlay"); + elm_bg_overlay_set(o_bg, over); + } + else + elm_bg_overlay_set(o_bg, NULL); +} + +static void +_cb_color_changed(void *data, Evas_Object *obj, void *event) +{ + Evas_Object *o_bg = data; + double val = 0.0; + + val = elm_spinner_value_get(obj); + if (val == 1.0) + elm_bg_color_set(o_bg, 255, 255, 255); + else if (val == 2.0) + elm_bg_color_set(o_bg, 255, 0, 0); + else if (val == 3.0) + elm_bg_color_set(o_bg, 0, 0, 255); + else if (val == 4.0) + elm_bg_color_set(o_bg, 0, 255, 0); +} + +int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg; + Evas_Object *box, *hbox, *o_bg; + Evas_Object *rd, *rdg; + char buf[PATH_MAX]; + + win = elm_win_add(NULL, "bg-options", ELM_WIN_BASIC); + elm_win_title_set(win, "Bg Options"); + evas_object_smart_callback_add(win, "delete,request", on_done, NULL); + elm_win_autodel_set(win, 1); + + 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); + + box = elm_box_add(win); + evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + elm_win_resize_object_add(win, box); + evas_object_show(box); + + o_bg = elm_bg_add(win); + snprintf(buf, sizeof(buf), "%s/images/plant_01.jpg", PACKAGE_DATA_DIR); + elm_bg_file_set(o_bg, buf, NULL); + evas_object_size_hint_weight_set(o_bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(o_bg, EVAS_HINT_FILL, EVAS_HINT_FILL); + elm_box_pack_end(box, o_bg); + evas_object_show(o_bg); + + hbox = elm_box_add(win); + elm_box_horizontal_set(hbox, EINA_TRUE); + evas_object_size_hint_weight_set(hbox, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_size_hint_align_set(hbox, EVAS_HINT_FILL, EVAS_HINT_FILL); + + rd = elm_radio_add(win); + elm_radio_state_value_set(rd, ELM_BG_OPTION_CENTER); + elm_radio_label_set(rd, "Center"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_radio_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + rdg = rd; + + rd = elm_radio_add(win); + elm_radio_state_value_set(rd, ELM_BG_OPTION_SCALE); + elm_radio_group_add(rd, rdg); + elm_radio_label_set(rd, "Scale"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_radio_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + + rd = elm_radio_add(win); + elm_radio_state_value_set(rd, ELM_BG_OPTION_STRETCH); + elm_radio_group_add(rd, rdg); + elm_radio_label_set(rd, "Stretch"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_radio_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + + rd = elm_radio_add(win); + elm_radio_state_value_set(rd, ELM_BG_OPTION_TILE); + elm_radio_group_add(rd, rdg); + elm_radio_label_set(rd, "Tile"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_radio_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + + elm_radio_value_set(rdg, ELM_BG_OPTION_SCALE); + + rd = elm_check_add(win); + elm_check_label_set(rd, "Show Overlay"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_overlay_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + + /* color choices ... this is ghetto, but we don't have a 'colorpicker' + * widget yet :( */ + rd = elm_spinner_add(win); + elm_object_style_set(rd, "vertical"); + elm_spinner_min_max_set(rd, 1, 4); + elm_spinner_label_format_set(rd, "%.0f"); + elm_spinner_editable_set(rd, EINA_FALSE); + elm_spinner_special_value_add(rd, 1, "White"); + elm_spinner_special_value_add(rd, 2, "Red"); + elm_spinner_special_value_add(rd, 3, "Blue"); + elm_spinner_special_value_add(rd, 4, "Green"); + evas_object_size_hint_weight_set(rd, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); + evas_object_size_hint_align_set(rd, EVAS_HINT_FILL, EVAS_HINT_FILL); + evas_object_smart_callback_add(rd, "changed", _cb_color_changed, o_bg); + elm_box_pack_end(hbox, rd); + evas_object_show(rd); + + elm_box_pack_end(box, hbox); + evas_object_show(hbox); + + evas_object_size_hint_min_set(bg, 160, 160); + evas_object_size_hint_max_set(bg, 640, 640); + evas_object_resize(win, 320, 320); + evas_object_show(win); + + elm_run(); + + return 0; +} + +ELM_MAIN() diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index f96c5d642c..45924dcf83 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -690,6 +690,276 @@ extern "C" { * "moved" - window that holds the canvas was moved */ + /** + * @page bg_01_example_page elm_bg - Plain color background. + * @dontinclude bg_example_01.c + * + * The full code for this example can be found at @ref bg_example_01_c, + * in the function @c test_bg_plain. It's part of the @c elementar_test + * suite, and thus has the code for the three examples referenced by this + * documentation. + * + * This first example just sets a default background with a plain color. The + * first part consists of creating an Elementary window. It's the common + * piece of code that you'll see everywhere in Elementary: @skip elm_main + * @until autodel_set + * + * Now we really create our background object, using the window object as + * its parent: + * + * @skipline bg_add + * + * Then we set the size hints of the background object so that it will use + * all space available for it, and then add it as a resize object to the + * window, making it visible in the end: + * + * @skip size_hint_weight_set + * @until resize_object_add + * + * See @ref evas_object_size_hint_weight_set and elm_win_resize_object_add() + * for more detailed info about these functions. + * + * The end of the example is quite simple, just setting the minimum and + * maximum size of the background, so the Elementary window knows that it + * has to have at least the minimum size. The background also won't scale to + * a size above its maximum. Then we resize the window and show it in the + * end: + * + * @skip set size hints + * @until } + * + * And here we finish our very simple background object usage example. + */ + + /** + * @page bg_02_example_page elm_bg - Image background. + * @dontinclude bg_example_02.c + * + * The full code for this example can be found at @ref bg_example_02_c, + * in the function @c test_bg_image. It's part of the @c elementar_test + * suite, and thus has the code for the three examples referenced by this + * documentation. + * + * This is the second example, and shows how to use the Elementary + * background object to set an image as background of your application. + * + * We start this example exactly in the same way as the previous one, even + * when creating the background object: + * + * @skip elm_main + * @until bg_add + * + * Now it's the different part. + * + * Our background will have an image, that will be displayed over the + * background color. Before loading the image, we set the load size of the + * image. The load size is a hint about the size that we want the image + * displayed in the screen. It's not the exact size that the image will have, + * but usually a bit bigger. The background object can still be scaled to a + * size bigger than the one set here. Setting the image load size to + * something smaller than its real size will reduce the memory used to keep + * the pixmap representation of the image, and the time to load it. Here we + * set the load size to 20x20 pixels, but the image is loaded with a size + * bigger than that (since it's just a hint): + * + * @skipline load_size_set + * + * And set our background image to be centered, instead of stretched or + * scaled, so the effect of the elm_bg_load_size_set() can be easily + * understood: + * + * @skipline option_set + * + * We need a filename to set, so we get one from the previous installed + * images in the @c PACKAGE_DATA_DIR, and write its full path to a buffer. + * Then we use this buffer to set the filename in the background object: + * + * @skip snprintf + * @until bg_file_set + * + * Notice that the third argument of the elm_bg_file_set() function is @c + * NULL, since we are setting an image to this background. This function + * also supports setting an edje group as background, in which case the @c + * group parameter wouldn't be @c NULL, but be the name of the group + * instead. + * + * Finally, we can set the size hints, add the background as a resize + * object, and resize the window, exactly the same thing we do in the @ref + * bg_01_example_page example: + * + * @skip size_hint + * @until } + * + * And this is the end of this example. + */ + + /** + * @page bg_03_example_page elm_bg - Background properties. + * @dontinclude bg_example_03.c + * + * The full code for this example can be found at @ref bg_example_03_c, in the + * function @c test_bg_options, with the callbacks @c _cb_overlay_changed, @c + * _cb_color_changed and @c _cb_radio_changed defined in the beginning of the + * file. It's part of the @c elementar_test suite, and thus has the code for + * the three examples referenced by this documentation. + * + * This example will show the properties available for the background object, + * and will use of some more widgets to set them. + * + * In order to do this, we will set some callbacks for these widgets. The + * first is for the radio buttons that will be used to choose the option + * passed as argument to elm_bg_option_set(): + * + * @skip _cb_radio_changed + * @until } + * + * The next callback will be used when setting the overlay (using + * elm_bg_overlay_set()): + * + * @skip _cb_overlay_changed + * @until } + * @until } + * + * And the last one, used to set the color (with elm_bg_color_set()): + * + * @skip _cb_color_changed + * @until } + * + * We will get back to what these functions do soon. If you want to know more + * about how to set these callbacks and what these widgets are, look for: + * @li elm_radio_add() + * @li elm_check_add() + * @li elm_spinner_add() + * + * Now going to the main function, @c test_bg_options, we have the common + * code with the other examples: + * + * @skip bg-options + * @until autodel_set + * + * We add a plain background to this window, so it will have the default + * background color behind everything: + * + * @skip bg = elm_bg_add + * @until evas_object_show(bg) + * + * Then we add a vertical box (elm_box_add()) that will hold the background + * object that we are going to play with, as well as a horizontal box that + * will hold widgets: + * + * @skip elm_box_add + * @until evas_object_show + * + * Now we add the background object that is going to be of use for our + * example. It is an image background, as used in @ref bg_02_example_page , + * so the code should be familiar: + * + * @skip elm_bg_add + * @until evas_object_show + * + * Notice the call to elm_box_pack_end(): it will pack the background object + * in the end of the Elementary box declared above. Just refer to that + * documentation for more info. + * + * Since this Elementary background is already an image background, we are + * going to play with its other properties. We will change its option + * (CENTER, SCALE, STRETCH, TILE), its color (RGB), and add an overlay to it. + * For all of these properties, we are going to add widgets that will + * configure them. + * + * First, lets add the horizontal box that will hold these widgets: + * @skip hbox + * @until align_set + * + * For now, just consider this @c hbox as a rectangle that will contain the + * widgets, and will distribute them horizontally inside its content. Then we + * add radio buttons that will allow us to choose the property to use with + * this background: + * + * @skip radio_add + * @until evas_object_show + * + * Again, I won't give details about the use of these widgets, just look for + * their documentation if necessary. It's enough to know for now that we are + * packing them in the @c hbox, setting a label for them, and the most + * important parts: setting its value to @c ELM_BG_OPTION_CENTER and its + * callback to @c _cb_radio_changed (the function defined in the beginning of + * this example). We do this for the next 3 radio buttons added after this + * one, each of them with a different value. + * + * Now taking a look at the code of the callback @c _cb_radio_changed again, + * it will call elm_bg_option_set() with the value set from the checked radio + * button, thus setting the option for this background. The background is + * passed as argument to the @p data parameter of this callback, and is + * referenced here as @c o_bg. + * + * Later we set the default value for this radio button: + * + * @skipline elm_radio_value_set + * + * Then we add a checkbox for the elm_bg_overlay_set() function: + * + * @skip check_add + * @until evas_object_show + * + * Now look at the code of the @c _cb_overlay_changed again. If the checkbox + * state is checked, an overlay will be added to the background. It's done by + * creating an Edje object, and setting it with elm_bg_overlay_set() to the + * background object. For information about what are and how to set Edje + * object, look at the Edje documentation. + * + * Finally we add a spinner object (elm_spinner_add()) to be used to select + * the color of our background. In its callback it's possible to see the call + * to elm_bg_color_set(), which will change the color of this background. + * This color is used by the background to fill areas where the image doesn't + * cover (in this case, where we have an image background). The spinner is + * also packed into the @c hbox : + * + * @skip elm_spinner_add + * @until evas_object_show + * + * Then we just have to pack the @c hbox inside the @c box, set some size + * hints, and show our window: + * + * @skip pack_end + * @until } + * + * Now to see this code in action, open elementary_test, and go to the "Bg + * Options" test. It should demonstrate what was implemented here. + */ + + /** + * @page bg_example_01_c bg_example_01.c + * @include bg_example_01.c + */ + + /** + * @page bg_example_02_c bg_example_02.c + * @include bg_example_02.c + */ + + /** + * @page bg_example_03_c bg_example_03.c + * @include bg_example_03.c + */ + + /** + * @defgroup Bg Bg + * + * @brief Background object, used for setting a solid color, image or Edje + * group as background to a window or any container object. + * + * The bg object is used for setting a solid background to a window or + * packing into any container object. It works just like an image, but has + * some properties useful to a background, like setting it to tiled, + * centered, scaled or stretched. + * + * Here is some sample code using it: + * @li @ref bg_01_example_page + * @li @ref bg_02_example_page + * @li @ref bg_03_example_page + */ + /* bg */ typedef enum _Elm_Bg_Option { @@ -699,16 +969,152 @@ extern "C" { ELM_BG_OPTION_TILE /**< tile background at its original size */ } Elm_Bg_Option; + /** + * Add a new background to the parent + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * @ingroup Bg + */ EAPI Evas_Object *elm_bg_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + + /** + * Set the file (image or edje) used for the background + * + * @param obj The bg object + * @param file The file path + * @param group Optional key (group in Edje) within the file + * + * This sets the image file used in the background object. The image (or edje) + * will be stretched (retaining aspect if its an image file) to completely fill + * the bg object. This may mean some parts are not visible. + * + * @note Once the image of @p obj is set, a previously set one will be deleted, + * even if @p file is NULL. + * + * @ingroup Bg + */ EAPI void elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1); + + /** + * Get the file (image or edje) used for the background + * + * @param obj The bg object + * @param file The file path + * @param group Optional key (group in Edje) within the file + * + * @ingroup Bg + */ EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1); + + /** + * Set the option used for the background image + * + * @param obj The bg object + * @param option The desired background option (TILE, SCALE) + * + * This sets the option used for manipulating the display of the background + * image. The image can be tiled or scaled. + * + * @ingroup Bg + */ EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) EINA_ARG_NONNULL(1); + + /** + * Get the option used for the background image + * + * @param obj The bg object + * @return The desired background option (CENTER, SCALE, STRETCH or TILE) + * + * @ingroup Bg + */ EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the option used for the background color + * + * @param obj The bg object + * @param r + * @param g + * @param b + * + * This sets the color used for the background rectangle. Its range goes + * from 0 to 255. + * + * @ingroup Bg + */ EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b) EINA_ARG_NONNULL(1); + /** + * Get the option used for the background color + * + * @param obj The bg object + * @param r + * @param g + * @param b + * + * @ingroup Bg + */ EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) EINA_ARG_NONNULL(1); + + /** + * Set the overlay object used for the background object. + * + * @param obj The bg object + * @param overlay The overlay object + * + * This provides a way for elm_bg to have an 'overlay' that will be on top + * of the bg. Once the over object is set, a previously set one will be + * deleted, even if you set the new one to NULL. If you want to keep that + * old content object, use the elm_bg_overlay_unset() function. + * + * @ingroup Bg + */ + EAPI void elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) EINA_ARG_NONNULL(1); + + /** + * Get the overlay object used for the background object. + * + * @param obj The bg object + * @return The content that is being used + * + * Return the content object which is set for this widget + * + * @ingroup Bg + */ EAPI Evas_Object *elm_bg_overlay_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Get the overlay object used for the background object. + * + * @param obj The bg object + * @return The content that was being used + * + * Unparent and return the overlay object which was set for this widget + * + * @ingroup Bg + */ EAPI Evas_Object *elm_bg_overlay_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set the size of the pixmap representation of the image. + * + * This option just makes sense if an image is going to be set in the bg. + * + * @param obj The bg object + * @param w The new width of the image pixmap representation. + * @param h The new height of the image pixmap representation. + * + * This function sets a new size for pixmap representation of the given bg + * image. It allows the image to be loaded already in the specified size, + * reducing the memory usage and load time when loading a big image with load + * size set to a smaller size. + * + * NOTE: this is just a hint, the real size of the pixmap may differ + * depending on the type of image being loaded, being bigger than requested. + * + * @ingroup Bg + */ EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); /* smart callbacks called: */ diff --git a/legacy/elementary/src/lib/elm_bg.c b/legacy/elementary/src/lib/elm_bg.c index a771077b81..21a4a7bcd6 100644 --- a/legacy/elementary/src/lib/elm_bg.c +++ b/legacy/elementary/src/lib/elm_bg.c @@ -1,13 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Bg Bg - * - * The bg object is used for setting a solid background to a window or packing - * into any container object. - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -120,14 +113,6 @@ _custom_resize(void *data, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, void evas_object_size_hint_max_set(wd->img, mw, mh); } -/** - * Add a new background to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Bg - */ EAPI Evas_Object * elm_bg_add(Evas_Object *parent) { @@ -156,22 +141,6 @@ elm_bg_add(Evas_Object *parent) return obj; } -/** - * Set the file (image or edje) used for the background - * - * @param obj The bg object - * @param file The file path - * @param group Optional key (group in Edje) within the file - * - * This sets the image file used in the background object. The image (or edje) - * will be stretched (retaining aspect if its an image file) to completely fill - * the bg object. This may mean some parts are not visible. - * - * @note Once the image of @p obj is set, a previously set one will be deleted, - * even if @p file is NULL. - * - * @ingroup Bg - */ EAPI void elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) { @@ -212,15 +181,6 @@ elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) _custom_resize(wd, NULL, NULL, NULL); } -/** - * Get the file (image or edje) used for the background - * - * @param obj The bg object - * @param file The file path - * @param group Optional key (group in Edje) within the file - * - * @ingroup Bg - */ EAPI void elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) { @@ -230,17 +190,6 @@ elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) if (group) *group = wd->group; } -/** - * Set the option used for the background image - * - * @param obj The bg object - * @param option The desired background option (TILE, SCALE) - * - * This sets the option used for manipulating the display of the background - * image. The image can be tiled or scaled. - * - * @ingroup Bg - */ EAPI void elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) { @@ -252,14 +201,6 @@ elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) _custom_resize(wd, NULL, NULL, NULL); } -/** - * Get the option used for the background image - * - * @param obj The bg object - * @return The desired background option (TILE, SCALE) - * - * @ingroup Bg - */ EAPI Elm_Bg_Option elm_bg_option_get(const Evas_Object *obj) { @@ -270,18 +211,6 @@ elm_bg_option_get(const Evas_Object *obj) return wd->option; } -/** - * Set the option used for the background color - * - * @param obj The bg object - * @param r - * @param g - * @param b - * - * This sets the color used for the background rectangle. - * - * @ingroup Bg - */ EAPI void elm_bg_color_set(Evas_Object *obj, int r, int g, int b) { @@ -299,16 +228,6 @@ elm_bg_color_set(Evas_Object *obj, int r, int g, int b) evas_object_color_set(wd->rect, r, g, b, 255); } -/** - * Get the option used for the background color - * - * @param obj The bg object - * @param r - * @param g - * @param b - * - * @ingroup Bg - */ EAPI void elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) { @@ -319,19 +238,6 @@ elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) evas_object_color_get(wd->rect, r, g, b, NULL); } -/** - * Set the overlay object used for the background object. - * - * @param obj The bg object - * @param overlay The overlay object - * - * This provides a way for elm_bg to have an 'overlay' (such as animated fog) - * Once the over object is set, a previously set one will be deleted. - * If you want to keep that old content object, use the - * elm_bg_overlay_unset() function. - * - * @ingroup Bg - */ EAPI void elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) { @@ -353,16 +259,6 @@ elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) _custom_resize(wd, NULL, NULL, NULL); } -/** - * Set the overlay object used for the background object. - * - * @param obj The bg object - * @return The content that is being used - * - * Return the content object which is set for this widget - * - * @ingroup Bg - */ EAPI Evas_Object * elm_bg_overlay_get(const Evas_Object *obj) { @@ -372,16 +268,6 @@ elm_bg_overlay_get(const Evas_Object *obj) return wd->overlay; } -/** - * Get the overlay object used for the background object. - * - * @param obj The bg object - * @return The content that was being used - * - * Unparent and return the overlay object which was set for this widget - * - * @ingroup Bg - */ EAPI Evas_Object * elm_bg_overlay_unset(Evas_Object *obj) { @@ -398,16 +284,6 @@ elm_bg_overlay_unset(Evas_Object *obj) return overlay; } -/** - * Set the size of a loaded image of the canvas of the bg. - * - * @param obj The bg object - * @param w The new width of the canvas image given. - * @param h The new height of the canvas image given. - * - * This function sets a new size for the canvas image of the given the bg. - * - */ EAPI void elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) {