[framework/uifw/evas.git] / doc / examples.dox

/**
 * @page Examples Examples
 *
 * Here is a page with examples.
 *
 * @ref Example_Evas_Buffer_Simple
 *
 * @ref Example_Evas_Init_Shutdown
 *
 * @ref Example_Evas_Images
 *
 * @ref Example_Evas_Images_2
 *
 * @ref Example_Evas_Events
 *
 * @ref Example_Evas_Object_Manipulation
 *
 * @ref Example_Evas_Aspect_Hints
 *
 * @ref Example_Evas_Size_Hints
 *
 * @ref Example_Evas_Stacking
 */

/**
 * @page Example_Evas_Buffer_Simple Simple Evas canvas example
 *
 * The canvas will here use the buffer engine.
 *
 * @include evas-buffer-simple.c
 * @example evas-buffer-simple.c
 */

/**
 * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
 *
 * @include evas-init-shutdown.c
 * @example evas-init-shutdown.c
 */

/**
 * @page Example_Evas_Images Some image object functions examples
 * @dontinclude evas-images.c
 *
 * In this example, we add two images to a canvas, each one having a
 * quarter of the canvas' size, positioned on the top left and bottom
 * right corners, respectively:
 * @skip img1 = evas_object_image_add(d.evas);
 * @until ecore_main_loop_begin
 * See there is a border image around the top left one, <b>which is
 * the one that should be displayed</b>. The other one will (on
 * purpose) fail to load, because we set a wrong file path as image
 * source on it:
 * @dontinclude evas-images.c
 * @skip valid_path
 * @until bogus_path
 * This is how one is supposed to test for success when binding source
 * images to image objects: evas_object_image_load_error_get(),
 * followed by evas_load_error_str(), if one wants to pretty print/log
 * the error. We'll talk about the border image further.
 *
 * To interact with the program, there's a command line interface,
 * whose help string can be asked for with the 'h' key:
 * @dontinclude evas-images.c
 * @skip commands
 * @until ;
 * The first four commands will change the top left images's @b fill property
 * values, which dictate how the source image (Enlightenment's logo)
 * is to be displayed through the image object's area. Experiment with
 * those switches until you get the idea of evas_object_fill_set().
 *
 * The 'f' command will toggle that image's "filled" property, which
 * is wheter it should track its size and set the fill one to fit the
 * object's boundaries perfectly (stretching). Note that this command
 * and the four above it will conflict: in real usage one would use
 * one or other ways of setting an image object's viewport with regard
 * to its image source.
 *
 * There are four commands which deal with the border image. This red
 * frame is there to illustrate <b>image borders</b>. The image source
 * for the border is a solid red rectangle, with a transparent @b
 * rectangular area in its middle. See how we use it to get a 3 pixel
 * wide frame with <code>evas_object_image_border_set(d.border, 3, 3,
 * 3, 3)</code>. To finish the effect of showing it as a border, we
 * issue <code>evas_object_image_border_center_fill_set(d.border,
 * EVAS_BORDER_FILL_NONE)</code>.
 *
 * Use 't' to change the border's thickness. 'b' will change the
 * border image's center region rendering schema: either a hole (no
 * rendering), blending (see the original transparent area, in this
 * case) or solid (the transparent area gets filled). Finally, 'c'
 * will change the border's scaling factor.
 *
 * While you have the border in 'blending mode', test the command 'm':
 * it will set whether to use or not smooth scaling on the border's
 * source image. Since the image is small originallly (30 x 30), we're
 * obviously up-scaling it (except the border pixels, do you
 * remember?). With this last switch, you'll either see the
 * transparent shape in the middle flat (no smoothing) or blurry
 * (smoothed).
 *
 * The full example follows.
 *
 * @include evas-images.c
 * @example evas-images.c
 */

/**
 * @page Example_Evas_Images_2 Some more image object functions examples (2nd block)
 * @dontinclude evas-images2.c
 *
 * In this example, we have three images on the canvas, but one of
 * them is special -- we're using it as a <b>proxy image
 * object</b>. It will mirror the contents of the other two images
 * (which are the ones on the top of the canvas), one at a time:
 * @skip d.proxy_img = evas_object_image_filled_add(d.evas);
 * @until evas_object_show(d.proxy_img);
 * As in other examples, we have a command line interface on it.
 * @dontinclude evas-images2.c
 * @skip commands
 * @until ;
 * The 'p' one will change the source of the proxy image to one of the
 * other two, as seem above.
 * @skip if (strcmp(ev->keyname, "p") == 0)
 * @until }
 * Note the top right image, the smaller one:
 * @dontinclude evas-images2.c
 * @skip noise_img =
 * @until show
 * Since we are creating the data for its pixel buffer ourselves, we
 * have to set its size with evas_object_image_size_set(), first. We
 * set our data with the function evas_object_image_data_set(),
 * whose second argument is a buffer with random data. There's a last
 * command to print it's @b stride value. Since its created with one
 * quarter of the canvas's original width
 * @dontinclude evas-images2.c
 * @skip define WIDTH
 * @until define HEIGHT
 * you can check this value.
 *
 * The image on the top left also has a subtlety: it is @b pre-loaded
 * on this example.
 * @dontinclude evas-images2.c
 * @skip d.logo =
 * @until show
 * On real use cases we wouldn't be just printing something like this
 * @dontinclude evas-images2.c
 * @skip static void
 * @until }
 * naturally.
 *
 * The 's' command will save one of the images on the disk, in the png
 * format:
 * @dontinclude evas-images2.c
 * @skip if (strcmp(ev->keyname, "a") == 0)
 * @until }
 *
 * The full example follows.
 *
 * @include evas-images2.c
 * @example evas-images2.c
 */

/**
 * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
 * @dontinclude evas-events.c
 *
 * In this example we illustrate how to interact with canvas' (and
 * its objects') events and other canvas operations.
 *
 * After we grab our canvas pointer, we registrate two event callbacks on it:
 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
 * @until two canvas event callbacks
 * The first of them, whose code is
 * @dontinclude evas-events.c
 * @skip render flush callback
 * @until }
 * will be called whenever our canvas has to flush its rendering pipeline.
 * In this example, two ways of observing that message which is printed in
 * the cited callback are:
 * - to resize the example's window (thus resizing the canvas' viewport)
 * - let the animation run
 *
 * When one resizes the canvas, there's at least one operation it has
 * to do which will require new calculation for rendering: the
 * resizing of the background rectangle:
 * @dontinclude evas-events.c
 * @skip here just to keep
 * @until }
 * The animation we talked about comes from a timer we register just before
 * we start the example's main loop:
 * @dontinclude evas-events.c
 * @skip d.resize_timer = ecore
 * @until d.resize_timer = ecore
 * being the timer's callback what follows:
 * @dontinclude evas-events.c
 * @skip put some action
 * @until }
 * As you see, the resizing of the image will also force the canvas to
 * repaint itself, thus flushing the rendering pipeline whenever the
 * timer ticks. When you start this example, this animation will be
 * running, by default. To interact with the program, there's a
 * command line interface, whose help string can be asked for with the
 * 'h' key:
 * @dontinclude evas-events.c
 * @skip if (strcmp(ev->keyname, "h") == 0)
 * @until }
 * These are the commands the example will accept at any time, except
 * when one triggers the 'f' one:
 * @skip if (strcmp(ev->keyname, "f") == 0)
 * @until }
 * This command will exemplify evas_event_freeze(), which interrupts
 * @b all input events processing for the canvas (in the example, just
 * for 3 seconds). Try to issue events for it during that freeze time.
 * The 'd' command will unregister those two canvas callbacks for you,
 * so you won't see the messages about the focused object and the
 * rendering process anymore:
 * @dontinclude evas-events.c
 * @skip if (strcmp(ev->keyname, "d") == 0)
 * @until }
 * The second of those callbacks has the following code:
 * @dontinclude evas-events.c
 * @skip called when our rectangle gets focus
 * @until }
 * It will take place whenever an object in the canvas receives
 * focus. In this example, we use the focus to handle the input
 * events:
 * @skip so we get input events
 * @until }
 * The background rectangle is the chosen object to receive the
 * focus. This also illustrates the use of
 * evas_object_event_callback_add(), which registers an event callback
 * on an Evas @b object (in this case, the event of a key being
 * pressed down). On this callback, we examine each key pressed and,
 * if they match one between the expected, we take some actions:
 * @dontinclude evas-events.c
 * @skip examine the keys pressed
 * @until key grab
 * We do so by examining the @c ev->keyname string (remember the event
 * information struct for key down events is the #Evas_Event_Key_Down
 * one).  There's one more trick for grabbing input events on this
 * example -- evas_object_key_grab(). The 'c' command will, when
 * firstly used, @b unfocus the background rectangle. Unfocused
 * objects on an Evas canvas will @b never receive key events. We
 * grab, then, the keys we're interested at, to the object forcefully:
 * @skip if (d.focus)
 * @until got here by key grabs
 * This shows how one can handle input not depending on focus issues
 * -- you can grab them globally. Switch back and forth focus and
 * forced key grabbing with the 'c' key, and observe the messages
 * printed about the focused object.  Observe, also, that we register
 * two more @b object callbacks, this time on the image object
 * (Enlightenment logo):
 * @skip evas_object_show(d.img);
 * @until mouse_out, NULL
 * whose code blocks are
 * @dontinclude evas-events.c
 * @skip mouse enters the object's area
 * @until mouse exits the object's area
 * Experiment with moving the mouse pointer over the image, letting it
 * enter and exit its area (stop the animation with 'a', for a better
 * experience). When you start the example, Evas will consider this
 * area by being the whole boundary rectangle around the picture. If
 * you issue the 'p' command, though, you get a demonstration of Evas'
 * precise point collision detection on objects:
 * @dontinclude evas-events.c
 * @skip if (strcmp(ev->keyname, "p") == 0)
 * @until }
 * With evas_object_precise_is_inside_get(), one can make Evas
 * consider the transparent areas of an object (the middle of the
 * logo's E letter, in the case) as not belonging to it when
 * calculating mouse in/out/up/down events. To finish the example, try
 * the command bound to Cotrol + 'o':
 * @skip mods = evas_key_modifier_get(evas);
 * @until end of obscured region command
 * It exemplifies Evas' <b>obscured regions</b>. When firstly pressed,
 * you'll get the same contents, in a region in the middle of the
 * canvas, at the time the key was pressed, until you toggle the
 * effect off again (make sure the animation is running on to get the
 * idea better). When you toggle this effect off, we also demonstrate
 * the use of evas_render_updates(), which will force immediate
 * updates on the canvas rendering, bringing back the obscured
 * region's contents to normal.
 *
 * What follows is the complete code for this example.
 *
 * @include evas-events.c
 * @example evas-events.c
 */

/**
 * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
 *
 * @include evas-object-manipulation.c
 * @example evas-object-manipulation.c
 */

/**
 * @page Example_Evas_Aspect_Hints Evas aspect hints example
 *
 * @include evas-aspect-hints.c
 * @example evas-aspect-hints.c
 */

/**
 * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
 *
 * @include evas-hints.c
 * @example evas-hints.c
 */

/**
 * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
 * @dontinclude evas-stacking.c
 *
 * In this example, we illustrate how to stack objects in a custom
 * manner and how to deal with layers.
 *
 * We have three objects of interest in it -- white background, red
 * rectangle, green rectangle and blue rectangle.
 * @skip d.bg = evas_object_rectangle_add(d.canvas);
 * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
 * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
 * @until evas_object_show(d.rects[0]);
 * @dontinclude evas-stacking.c
 * Like in other Evas examples, one interacts with it be means of key commands:
 * @skip "commands are:\n"
 * @until "\th - print help\n");
 * At any given point, like seem above, you'll be operating one rectangle only.
 * Try stacking it below an adjacent object with "b":
 * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
 * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
 * @dontinclude evas-stacking.c
 * "a" will do the opposite:
 * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
 * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
 * To bring it directly to the top/bottom, use "t"/"m", respectively:
 * @dontinclude evas-stacking.c
 * @skip evas_object_raise(d.rects[d.cur_rect]);
 * @until evas_object_raise(d.rects[d.cur_rect]);
 * @skip evas_object_lower(d.rects[d.cur_rect]);
 * @until evas_object_lower(d.rects[d.cur_rect]);
 * At any time, use the "s" command to see the status of the
 * ordering. It will show the background's ordering too. Note that it
 * also shows the @b layer for this object. It starts at a @b
 * different layer than the others. Use "l" to change its layer
 * (higher layer numbers mean higher layers). If the background is on
 * the same layer as the others (0), you'll see it interact with them
 * on the ordering. If it's in the layer above, no matter what you do,
 * you'll see nothing but the white rectangle: it covers the other
 * layers. For the initial layer (-1), it will never mess nor occlude
 * the others.
 *
 * The last two commands available are "p" and "r", which will make
 * the target rectangle to @b pass (ignore) and @b repeat the mouse
 * events occurring on it (the commands will cycle through on and off
 * states). This is demonstrated with the following
 * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
 * colored rectangles:
 * @dontinclude evas-stacking.c
 * @skip static void
 * @until }
 * Try to change these properties on the three rectangles while
 * experimenting with mouse clicks on their intersection region.
 *
 * The full example follows.
 *
 * @include evas-stacking.c
 * @example evas-stacking.c
 */