summaryrefslogtreecommitdiff
path: root/legacy/edje/doc/examples.dox
blob: a93fc3fce36407bc16cde0c75a46f4c3850ac79e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
/**
 * @page Examples Examples
 *
 * Here is a page with examples.
 *
 * @li @ref Example_Edje_Basics
 * @li @ref tutorial_edje_swallow
 * @li @ref tutorial_edje_text
 * @li @ref tutorial_edje_table
 * @li @ref Example_Edje_Signals_Messages
 */

/**
 * @page Example_Edje_Basics Edje basics example
 *
 * In this example, we illustrate how to start using the Edje library,
 * with the very basic one needs to instantiate an Edje object.
 *
 * We place, in the canvas, an Edje object along with a @b red border
 * image to delimit its geometry. After we instantiate the Edje
 * object, we @b have to set a file and a group, within that file, to
 * bind to it. For this example, we're using an EDC file which
 * declares two parts (blue and green rectangles) and an item data:
 * @include basic.edc
 *
 * We start by trying to acces an @b unexistant group in the file, so
 * that you can see the usefulness of edje_object_load_error_get() and
 * edje_load_error_str(). Check that the error message will tell you
 * just that -- a group which didn't exist in the file was called for:
 * @dontinclude edje-basic.c
 * @skip file_path
 * @until file_path
 * @dontinclude edje-basic.c
 * @skip edje_object_add
 * @until }
 *
 * Than, we finally bind our Edje object to @c "example_group",
 * printing a message afterwards:
 * @dontinclude edje-basic.c
 * @skip file_path, "example_group"
 * @until object_show
 *
 * What follows is a series of Edje API calls which are of general
 * use. The first of them is edje_object_data_get(), which we use to
 * get the value we have put in the @c "example_data" data field, in
 * our EDC object declaration:
 * @dontinclude edje-basic.c
 * @skip data field in group
 * @until ;
 *
 * Than, we exemplify edje_object_part_exists():
 * @dontinclude edje-basic.c
 * @skip Testing if
 * @until ;
 *
 * The next call is to query @c "part_one"'s geometry, relative to the
 * whole Edje object's area. The part will be situated in the middle
 * of the Edje object's, because it has a restricted forced size (we
 * set its minimum size equal to its maximum, for that) and, by
 * default, parts are aligned to the center of their containers:
 * @dontinclude edje-basic.c
 * @skip part_geometry_get
 * @until x, y, w, h
 *
 * We can grab a direct pointer on the rectangle implementing @c
 * "part_one", by using edje_object_part_object_get(). Since we are
 * not allowed to set properties on it, we just check its color, to
 * assure its really blue, as declared in the EDC:
 * @dontinclude edje-basic.c
 * @skip color_get
 * @until x, y, w, h
 *
 * The @c "min" and @c "max" EDC properties can be queried with the
 * following calls:
 * @dontinclude edje-basic.c
 * @skip max_get
 * @until min. size is
 *
 * The next two calls are to make <b>size calculations</b> on our
 * object. Because of the minumim size declared for @c "part_one" part's
 * default state description, that will be our exact minimum
 * size calculated for the group (remember the @c "min" declaration at
 * group level is just a @b hint, not an enforcement). We then
 * exercise the edje_object_size_min_restricted_calc() function,
 * passing a minimum size of 500, in each axis. Since we have @b no
 * object bigger than that, it will be the minimum size calculated, in
 * the end:
 * @dontinclude edje-basic.c
 * @skip min_calc
 * @until size calculation is
 *
 * @c "part_two" part is there with a purpose: since it extrapolates
 * the Edje object's boundaries, the edje_object_parts_extends_calc()
 * function will report origin coordinates for the rectangle grouping
 * both parts with @b negative values, indicating it extrapolates to
 * the upper left of our group, just as we see it.
 *
 * To interact with the last features exemplified in the program,
 * there's a command line interface.  A help string can be asked for
 * with the 'h' key:
 * @dontinclude edje-basic.c
 * @skip commands
 * @until ;
 *
 * Those commands will change the scaling factors of our Edje objects.
 * The first of them, @c 's', will change Edje's @b global scaling
 * factor between @c 1.0 (no scaling) and @c 2.0 (double
 * scale). Scaling will be applied to @c "part_one", only, because
 * that's the part flagged to be scaled at EDC level:
 * @dontinclude edje-basic.c
 * @skip strcmp(ev->keyname, "s") == 0
 * @until }
 *
 * Note, finally, that the @c 's' command will depend on the 'r' one
 * to have its effects applied. The latter will change @c "part_one"'s
 * @b individual scaling factor, which @b overrides Edje's global
 * scaling factor. Only when the individual one is set to zero, will
 * the global one take effect:
 * @dontinclude edje-basic.c
 * @skip strcmp(ev->keyname, "r") == 0
 * @until }
 *
 * The example's window should look like this picture:
 *
 * @image html edje-basics-example.png
 * @image rtf edje-basics-example.png
 * @image latex edje-basics-example.eps
 *
 * The full example follows.
 *
 * @include edje-basic.c
 * @example edje-basic.c
 */

/**
 * @page tutorial_edje_swallow Swallow example
 * @dontinclude edje-swallow.c
 *
 * This is a simple example in which we create a rect and swallow it.
 *
 * Focusing on the relevant parts of the code we go right to the creation of our
 * rectangle. It should be noted that we don't resize or show our rect, that is
 * because when an object is swallowed it's geometry and visibility is
 * controlled by the theme:
 * @skip 20
 * @skipline evas_object_rectangle_add
 * @until swallow
 *
 * The other bit of code that is relevant to us now is our check that the
 * swallow worked:
 * @until printf
 *
 * The full source code follows:
 * @include edje-swallow.c
 * @example edje-swallow.c
 */

/**
 * @page tutorial_edje_text Edje Text example
 * @dontinclude edje-text.c
 *
 * This example shows how to manipulate TEXT and TEXTBLOCK parts from code.
 *
 * The very first we are going to do is register a callback to react to changes
 * in the text of our parts:
 * @skip _on_destroy
 * @skip static void
 * @until }
 *
 * @skipline text_change
 * @note Since edje_obj represent a group we'll be notified whenever any part's
 * text in that group changes.
 *
 * We now set the text for two our two parts:
 * @until text_set
 * @until text_set
 * @note Since the "part_two" part is a TEXTBLOCK we can use formatting such as
 * @<b@>
 *
 * And we now move on to selection issues, first thing we do is make sure the
 * user can select text:
 * @until select_allow
 *
 * We then select the entire text, and print the selected text:
 * @until printf
 *
 * We now unselect the entire text(set selection to none), and print the
 * selected text:
 * @until printf
 *
 * Our example will look like this:
 *
 * @image html edje-text.png
 * @image rtf edje-text.png
 * @image latex edje-text.eps
 *
 * The full source code follows:
 * @include edje-text.c
 * @example edje-text.c
 *
 * The theme used in this example is:
 * @include text.edc
 * @example text.edc
 */

/**
 * @page tutorial_edje_table Table example
 *
 * In this example, we illustrate how to organize your objects on a table, using
 * the evas_object_part_table functions. To be easier to understand the objects
 * in this example will be four simple rects, when the user click over one
 * item with the left button its is removed from the table, if any other button
 * was used all items are removed. For each action is printed a message with
 * the current number of rows and columns.
 *
 * We started creating an EDC file with one part of the type TABLE called
 * @b "table_part", that is the part which we will refer to access the table:
 * @include table.edc
 *
 * On the other hand, in the C file we first create the rectangles and added a
 * callback for mouse down, as you can see bellow:
 * @dontinclude edje-table.c
 * @skip _rects_create
 * @until }
 * @skip }
 * @until }
 *
 * With the objects created we have to pack them into the table, to do this, we
 * just have to use the function edje_object_part_table_pack().
 * @dontinclude edje-table.c
 * @skip (!edje_object_part_table_pack
 * @until 4
 *
 * The other bit of code that is relevant to us now is our event handler for
 * when the user click over the rectangle. Here we use the function
 * edje_object_part_table_unpack() to remove the item from the table or
 * edje_object_part_table_clear() to remove all items, it depends on which mouse
 * button the user uses.
 * @dontinclude edje-table.c
 * @skip _on_mouse_down
 * @until }
 *
 * Finally, the last important thing in this example is about how to know how many
 * columns and rows are there in the table, It should be noted that this function
 * don't tell you how many items are there in the table, just the number of the
 * columns and rows of the table.
 * @dontinclude edje-table.c
 * @skip _columns_rows_
 * @until }
 *
 * The example's window should look like this picture:
 *
 * @image html edje-table-example.png
 * @image rtf edje-table-example.png
 * @image latex edje-table-example.eps
 *
 * The full source code follows:
 * @include edje-table.c
 * @example edje-table.c
 */

/**
 * @page Example_Edje_Signals_Messages Edje signals and messages
 *
 * In this example, we illustrate how Edje signals and Edje messages
 * work.
 *
 * We place, in the canvas, an Edje object along with a @b red border
 * image to delimit its geometry. The object's group definition is so
 * that we have four parts:
 * - a blue rectangle, aligned to the right
 * - a white rectangle, aligned to the left
 * - a text part, aligned to the center
 * - a clipper rectangle on the blue rectangle
 *
 * The left rectangle is bound to a <b>color class</b>, so that we can
 * multiply its colors by chosen values on the go:
 * @dontinclude signals-messages.edc
 * @until visible
 * @until }
 * @until }
 * @until }
 *
 * The @c #define's on the beginning will serve as message
 * identifiers, for our accorded message interface between the code
 * and the this theme file.
 *
 * Let's move to the code, then. After instantiating the Edje object,
 * we register two <b>signal callbacks</b> on it. The first one uses
 * @b globbing, making all of the wheel mouse actions over the left
 * rectangle to trigger @c _mouse_wheel_cb. Note that those kind of
 * signals are generated @b internally (and automatically) in Edje. The
 * second is a direct signal match, to a (custom) signal we defined in
 * the EDC, ourselves:
 * @dontinclude edje-signals-messages.c
 * @skip edje_object_add
 * @until _mouse_over_cb
 * @dontinclude edje-signals-messages.c
 * @skip print signals coming from theme
 * @until }
 * @until }
 *
 * That second callback is on a signal we emit on the theme, where we
 * just translate Edje @c "mouse,move" internal events to the custom @c
 * "mouse,over" one. When that signals reaches the code, we are,
 * besides printing the signals' strings, sending a @b message back to
 * the theme. We generate random values of color components and send
 * them as an #EDJE_MESSAGE_INT_SET message type:
 * @dontinclude signals-messages.edc
 * @skip custom signal
 * @until }
 * @dontinclude edje-signals-messages.c
 * @skip mouse over signals
 * @until }
 *
 * In our theme we'll be changing the @c "cc" color class' values with
 * those integer values of the message, so that moving the mouse over
 * the right rectangle will change the left one's colors:
 * @dontinclude signals-messages.edc
 * @skip public message
 * @until }
 * @until }
 *
 * Now we're also sending messages <b>from the Edje object</b>,
 * besides signals.  We do so when one clicks with the left button
 * over the left rectangle.  With that, we change the text part's
 * text, cycling between 3 pre-set strings declared in the EDC. With
 * each new text string attribution, we send a string message to our
 * code, with the current string as argument:
 * @dontinclude signals-messages.edc
 * @skip program
 * @until }
 * @until }
 * @skip change text
 * @until }
 * @until }
 * @dontinclude signals-messages.edc
 * @skip set_text_string
 * @until }
 *
 * To get the message in code, we have to register a message handler, as
 * follows:
 * @dontinclude edje-signals-messages.c
 * @skip message_handler_set
 * @until message_handler_set
 * @dontinclude edje-signals-messages.c
 * @skip print out
 * @until }
 *
 * To interact with the last missing feature -- emitting signals
 * <b>from code</b> -- there's a command line interface to exercise
 * it.  A help string can be asked for with the 'h' key:
 * @dontinclude edje-signals-messages.c
 * @skip commands
 * @until ;
 *
 * The @c 't' command will send either @c "part_right,show" or @c
 * "part_right,hide" signals to the Edje object (those being the
 * emission part of the signal), which was set to react on them as the
 * names indicate. We'll set the right rectangle's visibility on/off,
 * respectively, for those two signals:
 * @dontinclude signals-messages.edc
 * @skip hide right rectangle
 * @until }
 * @until }
 * @dontinclude edje-signals-messages.c
 * @skip keyname, "t"
 * @until }
 *
 * The example's window should look like this picture:
 *
 * @image html edje-signals-messages-example.png
 * @image rtf edje-signals-messages-example.png
 * @image latex edje-signals-messages-example.eps
 *
 * The full example follows, along with its EDC file.
 *
 * @include signals-messages.edc
 * @include edje-signals-messages.c
 * @example edje-signals-messages.c
 */