diff --git a/src/examples/evas/evas-object-manipulation.c b/src/examples/evas/evas-object-manipulation.c index 3e6728373b..c1735ba941 100644 --- a/src/examples/evas/evas-object-manipulation.c +++ b/src/examples/evas/evas-object-manipulation.c @@ -1,6 +1,16 @@ /** * Example of basic object manipulation in Evas. * + * The evas-buffer-simple.c example shows how to manually create and + * manage buffers, but mentioned that real code would use higher level + * functionality from Ecore's Ecore-Evas submodule. This example + * shows the use of that submodule to create an Evas canvas and + * manipulate the objects within it. + * + * Please note that this example uses Evas' legacy API. Compare this + * implementation with evas-object-manipulation-eo.c to learn how the + * new Eo API is used. + * * You'll need at least one engine built for it (excluding the buffer * one) and the png image loader also built. See stdout/stderr for * output. @@ -47,6 +57,9 @@ _canvas_resize_cb(Ecore_Evas *ee) evas_object_resize(d.bg, w, h); } +/* Keyboard event callback routine, to enable the user to toggle various + * object properties on the clipper object. + */ static void _on_keydown(void *data EINA_UNUSED, Evas *evas EINA_UNUSED, @@ -55,8 +68,9 @@ _on_keydown(void *data EINA_UNUSED, { Evas_Event_Key_Down *ev = einfo; - if (strcmp(ev->key, "h") == 0) /* print help */ + if (strcmp(ev->key, "h") == 0) { + /* h - print help */ printf("commands are:\n" "\to - change clipper's opacity\n" "\tr - toggle clipper's color between red and white\n" @@ -65,8 +79,9 @@ _on_keydown(void *data EINA_UNUSED, return; } - if (strcmp(ev->key, "o") == 0) /* change clipper's opacity */ + if (strcmp(ev->key, "o") == 0) { + /* o - Change clipper's opacity */ int alpha, r, g, b; evas_object_color_get(d.clipper, &r, &g, &b, &alpha); @@ -84,9 +99,9 @@ _on_keydown(void *data EINA_UNUSED, return; } - if (strcmp(ev->key, "r") == 0) /* toggle clipper's color - * between red and white */ + if (strcmp(ev->key, "r") == 0) { + /* r - Toggle clipper's color between red and white */ int alpha, r, g, b; printf("Changing clipper's color to"); @@ -110,8 +125,9 @@ _on_keydown(void *data EINA_UNUSED, return; } - if (strcmp(ev->key, "c") == 0) /* toggle clipper's clipping function */ + if (strcmp(ev->key, "c") == 0) { + /* o - Toggle clipper's clipping function */ printf("Toggling clipping "); if (evas_object_clip_get(d.img) == d.clipper) @@ -127,8 +143,9 @@ _on_keydown(void *data EINA_UNUSED, return; } - if (strcmp(ev->key, "v") == 0) /* toggle clipper's visibility */ + if (strcmp(ev->key, "v") == 0) { + /* v - Toggle clipper's visibility */ printf("Clipper is now "); if (evas_object_visible_get(d.clipper)) @@ -150,21 +167,38 @@ main(void) { int err; + /* In other examples, evas_init() has been used to turn Evas on. In this + * example we're using Ecore-Evas' init routine, which takes care of + * bringing up Evas. + */ if (!ecore_evas_init()) return EXIT_FAILURE; - /* this will give you a window with an Evas canvas under the first - * engine available */ + /* In the evas-buffer-simple.c example, we coded our own + * create_canvas() routine. Here we make use of Ecore-Evas's + * ecore_evas_new() routine to do it. The first argument of this + * function is used to specify the name of an engine we wish to use; + * by passing NULL instead, we are requesting a window with an Evas + * canvas using the first engine available. + */ d.ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL); if (!d.ee) goto error; + /* Like other windowing systems, Ecore-Evas provides hooks for a + * number of different events. We can register our own functions to + * be called when the events occur in our window. + */ ecore_evas_callback_resize_set(d.ee, _canvas_resize_cb); ecore_evas_show(d.ee); - /* the canvas pointer, de facto */ + /* Retrieve a pointer to the canvas we created. */ d.canvas = ecore_evas_get(d.ee); + /* Create background. As mentioned earlier, the evas_object_* + * routines are part of the legacy Evas API; with the new API + * you should use code as shown in evas-object-manipulation-eo.c. + */ d.bg = evas_object_rectangle_add(d.canvas); evas_object_name_set(d.bg, "background rectangle"); evas_object_color_set(d.bg, 255, 255, 255, 255); /* white bg */ @@ -172,10 +206,17 @@ main(void) evas_object_resize(d.bg, WIDTH, HEIGHT); /* covers full canvas */ evas_object_show(d.bg); + /* Callbacks can also be set on Evas objects. We'll add a keyboard + * handler routine to the background rectangle, for processing user + * key hits. + */ evas_object_focus_set(d.bg, EINA_TRUE); evas_object_event_callback_add( d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL); + /* Load enlightenment.png as an image object, then make it fill the + * whole canvas area. + */ d.img = evas_object_image_filled_add(d.canvas); evas_object_image_file_set(d.img, img_path, NULL); err = evas_object_image_load_error_get(d.img); @@ -193,7 +234,9 @@ main(void) evas_object_type_get(d.img)); } - /* border on the image's clipper, here just to emphasize its position */ + /* Add a second image to the canvas - a red square this time. It + * will be given a border to emphasize its position. + */ d.clipper_border = evas_object_image_filled_add(d.canvas); evas_object_image_file_set(d.clipper_border, border_img_path, NULL); err = evas_object_image_load_error_get(d.clipper_border); @@ -212,9 +255,9 @@ main(void) evas_object_show(d.clipper_border); } - /* solid white clipper (note that it's the default color for a - * rectangle) - it won't change clippees' colors, then (multiplying - * by 255) */ + /* Lastly, add a rectangle. It will be white (the default color for + * rectangles) and so won't change the color of anything it clips. + */ d.clipper = evas_object_rectangle_add(d.canvas); evas_object_move(d.clipper, WIDTH / 4, HEIGHT / 4); evas_object_resize(d.clipper, WIDTH / 2, HEIGHT / 2);