2 * @page Examples Examples
4 * Here is a page with examples.
6 * @ref Example_Evas_Buffer_Simple
8 * @ref Example_Evas_Init_Shutdown
10 * @ref Example_Evas_Load_Error_Str
12 * @ref Example_Evas_Events
14 * @ref Example_Evas_Object_Manipulation
16 * @ref Example_Evas_Aspect_Hints
18 * @ref Example_Evas_Size_Hints
20 * @ref Example_Evas_Stacking
24 * @page Example_Evas_Buffer_Simple Simple Evas canvas example
26 * The canvas will here use the buffer engine.
28 * @include evas-buffer-simple.c
29 * @example evas-buffer-simple.c
33 * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
35 * @include evas-init-shutdown.c
36 * @example evas-init-shutdown.c
40 * @page Example_Evas_Load_Error_Str evas_load_error_str() example
42 * @include evas-load-error-str.c
43 * @example evas-load-error-str.c
47 * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
48 * @dontinclude evas-events.c
50 * In this example we illustrate how to interact with canvas' (and
51 * its objects') events and other canvas operations.
53 * After we grab our canvas pointer, we registrate two event callbacks on it:
54 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
55 * @until two canvas event callbacks
56 * The first of them, whose code is
57 * @dontinclude evas-events.c
58 * @skip render flush callback
60 * will be called whenever our canvas has to flush its rendering pipeline.
61 * In this example, two ways of observing that message which is printed in
62 * the cited callback are:
63 * - to resize the example's window (thus resizing the canvas' viewport)
64 * - let the animation run
66 * When one resizes the canvas, there's at least one operation it has
67 * to do which will require new calculation for rendering: the
68 * resizing of the background rectangle:
69 * @dontinclude evas-events.c
70 * @skip here just to keep
72 * The animation we talked about comes from a timer we register just before
73 * we start the example's main loop:
74 * @dontinclude evas-events.c
75 * @skip d.resize_timer = ecore
76 * @until d.resize_timer = ecore
77 * being the timer's callback what follows:
78 * @dontinclude evas-events.c
79 * @skip put some action
81 * As you see, the resizing of the image will also force the canvas to
82 * repaint itself, thus flushing the rendering pipeline whenever the
83 * timer ticks. When you start this example, this animation will be
84 * running, by default. To interact with the program, there's a
85 * command line interface, whose help string can be asked for with the
87 * @dontinclude evas-events.c
88 * @skip if (strcmp(ev->keyname, "h") == 0)
90 * These are the commands the example will accept at any time, except
91 * when one triggers the 'f' one:
92 * @skip if (strcmp(ev->keyname, "f") == 0)
94 * This command will exemplify evas_event_freeze(), which interrupts
95 * @b all input events processing for the canvas (in the example, just
96 * for 3 seconds). Try to issue events for it during that freeze time.
97 * The 'd' command will unregister those two canvas callbacks for you,
98 * so you won't see the messages about the focused object and the
99 * rendering process anymore:
100 * @dontinclude evas-events.c
101 * @skip if (strcmp(ev->keyname, "d") == 0)
103 * The second of those callbacks has the following code:
104 * @dontinclude evas-events.c
105 * @skip called when our rectangle gets focus
107 * It will take place whenever an object in the canvas receives
108 * focus. In this example, we use the focus to handle the input
110 * @skip so we get input events
112 * The background rectangle is the chosen object to receive the
113 * focus. This also illustrates the use of
114 * evas_object_event_callback_add(), which registers an event callback
115 * on an Evas @b object (in this case, the event of a key being
116 * pressed down). On this callback, we examine each key pressed and,
117 * if they match one between the expected, we take some actions:
118 * @dontinclude evas-events.c
119 * @skip examine the keys pressed
121 * We do so by examining the @c ev->keyname string (remember the event
122 * information struct for key down events is the #Evas_Event_Key_Down
123 * one). There's one more trick for grabbing input events on this
124 * example -- evas_object_key_grab(). The 'c' command will, when
125 * firstly used, @b unfocus the background rectangle. Unfocused
126 * objects on an Evas canvas will @b never receive key events. We
127 * grab, then, the keys we're interested at, to the object forcefully:
129 * @until got here by key grabs
130 * This shows how one can handle input not depending on focus issues
131 * -- you can grab them globally. Switch back and forth focus and
132 * forced key grabbing with the 'c' key, and observe the messages
133 * printed about the focused object. Observe, also, that we register
134 * two more @b object callbacks, this time on the image object
135 * (Enlightenment logo):
136 * @skip evas_object_show(d.img);
137 * @until mouse_out, NULL
138 * whose code blocks are
139 * @dontinclude evas-events.c
140 * @skip mouse enters the object's area
141 * @until mouse exits the object's area
142 * Experiment with moving the mouse pointer over the image, letting it
143 * enter and exit its area (stop the animation with 'a', for a better
144 * experience). When you start the example, Evas will consider this
145 * area by being the whole boundary rectangle around the picture. If
146 * you issue the 'p' command, though, you get a demonstration of Evas'
147 * precise point collision detection on objects:
148 * @dontinclude evas-events.c
149 * @skip if (strcmp(ev->keyname, "p") == 0)
151 * With evas_object_precise_is_inside_get(), one can make Evas
152 * consider the transparent areas of an object (the middle of the
153 * logo's E letter, in the case) as not belonging to it when
154 * calculating mouse in/out/up/down events. To finish the example, try
155 * the command bound to Cotrol + 'o':
156 * @skip mods = evas_key_modifier_get(evas);
157 * @until end of obscured region command
158 * It exemplifies Evas' <b>obscured regions</b>. When firstly pressed,
159 * you'll get the same contents, in a region in the middle of the
160 * canvas, at the time the key was pressed, until you toggle the
161 * effect off again (make sure the animation is running on to get the
162 * idea better). When you toggle this effect off, we also demonstrate
163 * the use of evas_render_updates(), which will force immediate
164 * updates on the canvas rendering, bringing back the obscured
165 * region's contents to normal.
167 * What follows is the complete code for this example.
169 * @include evas-events.c
170 * @example evas-events.c
174 * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
176 * @include evas-object-manipulation.c
177 * @example evas-object-manipulation.c
181 * @page Example_Evas_Aspect_Hints Evas aspect hints example
183 * @include evas-aspect-hints.c
184 * @example evas-aspect-hints.c
188 * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
190 * @include evas-hints.c
191 * @example evas-hints.c
195 * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
196 * @dontinclude evas-stacking.c
198 * In this example, we illustrate how to stack objects in a custom
199 * manner and how to deal with layers.
201 * We have three objects of interest in it -- white background, red
202 * rectangle, green rectangle and blue rectangle.
203 * @skip d.bg = evas_object_rectangle_add(d.canvas);
204 * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
205 * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
206 * @until evas_object_show(d.rects[0]);
207 * @dontinclude evas-stacking.c
208 * Like in other Evas examples, one interacts with it be means of key commands:
209 * @skip "commands are:\n"
210 * @until "\th - print help\n");
211 * At any given point, like seem above, you'll be operating one rectangle only.
212 * Try stacking it below an adjacent object with "b":
213 * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
214 * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
215 * @dontinclude evas-stacking.c
216 * "a" will do the opposite:
217 * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
218 * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
219 * To bring it directly to the top/bottom, use "t"/"m", respectively:
220 * @dontinclude evas-stacking.c
221 * @skip evas_object_raise(d.rects[d.cur_rect]);
222 * @until evas_object_raise(d.rects[d.cur_rect]);
223 * @skip evas_object_lower(d.rects[d.cur_rect]);
224 * @until evas_object_lower(d.rects[d.cur_rect]);
225 * At any time, use the "s" command to see the status of the
226 * ordering. It will show the background's ordering too. Note that it
227 * also shows the @b layer for this object. It starts at a @b
228 * different layer than the others. Use "l" to change its layer
229 * (higher layer numbers mean higher layers). If the background is on
230 * the same layer as the others (0), you'll see it interact with them
231 * on the ordering. If it's in the layer above, no matter what you do,
232 * you'll see nothing but the white rectangle: it covers the other
233 * layers. For the initial layer (-1), it will never mess nor occlude
236 * The last two commands available are "p" and "r", which will make
237 * the target rectangle to @b pass (ignore) and @b repeat the mouse
238 * events occurring on it (the commands will cycle through on and off
239 * states). This is demonstrated with the following
240 * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
241 * colored rectangles:
242 * @dontinclude evas-stacking.c
245 * Try to change these properties on the three rectangles while
246 * experimenting with mouse clicks on their intersection region.
248 * The full example follows.
250 * @include evas-stacking.c
251 * @example evas-stacking.c