summaryrefslogtreecommitdiff
path: root/legacy/edje/doc
diff options
context:
space:
mode:
authorCarsten Haitzler <raster@rasterman.com>2011-04-08 07:45:46 +0000
committerCarsten Haitzler <raster@rasterman.com>2011-04-08 07:45:46 +0000
commit5829d373c9ba1eed786da8ce2723d97a6095c654 (patch)
tree5934d66756733b484d3aba6473f8d569ea6c1fc0 /legacy/edje/doc
parent09069b617285ab26f5b9ac696b51aad3a87079cc (diff)
doxy -> .h
SVN revision: 58478
Diffstat (limited to 'legacy/edje/doc')
-rw-r--r--legacy/edje/doc/edje.dox.in519
1 files changed, 0 insertions, 519 deletions
diff --git a/legacy/edje/doc/edje.dox.in b/legacy/edje/doc/edje.dox.in
index 739a5130e8..e69de29bb2 100644
--- a/legacy/edje/doc/edje.dox.in
+++ b/legacy/edje/doc/edje.dox.in
@@ -1,519 +0,0 @@
1/**
2@file edje.dox
3@brief Edje Graphical Design Library
4
5These routines are used for Edje.
6*/
7
8/**
9
10@mainpage Edje Library Documentation
11@image html e.png
12@version @PACKAGE_VERSION@
13@author Carsten Haitzler <raster@@rasterman.com>
14@author Tilman Sauerbeck (tilman at code-monkey de)
15@author ZigsMcKenzie <zigsmckenzie@@gmail.com>
16@author Cedric BAIL <cedric.bail@@free.fr>
17@author Brian Mattern <rephorm@@rephorm.com>
18@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr>
19@author Tristan <blunderer@@gmail.com>
20@author Gustavo Lima Chaves <glima@@profusion.mobi>
21@author Bruno Dilly <bdilly@@profusion.mobi>
22@author Fabiano Fidêncio <fidencio@@profusion.mobi>
23@author Jihoon Kim <jihoon48.kim@@samsung.com>
24@author Tiago Falcão <tiago@@profusion.mobi>
25@author Davide Andreoli <dave@@gurumeditation.it>
26@author Sebastian Dransfeld <sd@@tango.flipp.net>
27@author Tom Hacohen <tom@@stosb.com>
28@author Aharon Hillel <a.hillel@@partner.samsung.com>
29@date 2003-2011
30
31
32
33
34
35
36
37
38
39
40@section intro What is Edje?
41
42Edje is a complex graphical design & layout library.
43
44It doesn't pretend to do containing and regular layout like a widget
45set, but it is the base for such components. Based on the requirements
46of Enlightenment 0.17, Edje should serve all the purposes of creating
47visual elements (borders of windows, buttons, scrollbars, etc.) and
48allow the designer the ability to animate, layout and control the look
49and feel of any program using Edje as its basic GUI constructor. This
50library allows for multiple collections of Layouts in one file,
51sharing the same image and font database and thus allowing a whole
52theme to be conveniently packaged into 1 file and shipped around.
53
54Edje separates the layout and behavior logic. Edje files ship with an
55image and font database, used by all the parts in all the collections
56to source graphical data. It has a directory of logical part names
57pointing to the part collection entry ID in the file (thus allowing
58for multiple logical names to point to the same part collection,
59allowing for the sharing of data between display elements). Each part
60collection consists of a list of visual parts, as well as a list of
61programs. A program is a conditionally run program that if a
62particular event occurs (a button is pressed, a mouse enters or leaves
63a part) will trigger an action that may affect other parts. In this
64way a part collection can be "programmed" via its file as to hilight
65buttons when the mouse passes over them or show hidden parts when a
66button is clicked somewhere etc. The actions performed in changing
67from one state to another are also allowed to transition over a period
68of time, allowing animation. Programs and animations can be run in
69"parallel".
70
71This separation and simplistic event driven style of programming can produce
72almost any look and feel one could want for basic visual elements. Anything
73more complex is likely the domain of an application or widget set that may
74use Edje as a convenient way of being able to configure parts of the display.
75
76For details of Edje's history, see the \ref history section.
77
78
79
80
81
82
83
84
85@section requirements What does Edje require?
86
87Edje requires fairly little on your system. to use the Edje runtime library
88you need:
89
90 - Evas (library)
91 - Ecore (library)
92 - Eet (library)
93 - Embryo (library)
94 - Eina (library)
95
96Evas needs to be build with the JPEG, PNG and EET image loaders enabled at a
97minimum. Edje uses X for the test program, so you will need the SOFTWARE_X11
98engine built into Evas as well. A suggested configure list is below in the
99"cheat sheet" for Evas.
100
101Ecore needs the ECORE, ECORE_EVAS and ECORE_X modules built at a minimum.
102It's suggested to build all the Ecore modules, but the ECORE_FB modules is
103definitely optional.
104
105Eina, Eet and Embryo have no interesting options so just build and
106install them.
107
108It is suggested right now that you get the latest SVN versions of the
109required libraries. You also need to build them in the right order and make
110sure the right options are enabled in the required libraries. Here is a
111quick "cheat sheet" on how to get started.
112
113@verbatim
1141. You need Eina from the trunk svn branch.
115
116 svn co http://svn.enlightenment.org/svn/e/trunk/eina/
117 cd eina
118 ./autogen.sh
119 ./configure
120 make
121 sudo make install
122 cd
123
1242. You need Eet from the trunk svn branch.
125
126 svn co http://svn.enlightenment.org/svn/e/trunk/eet/
127 cd eet
128 ./autogen.sh
129 ./configure
130 make
131 sudo make install
132 cd
133
1343. You need Evas from the trunk svn branch built with eet, png and jpeg loader support.
135
136 svn co http://svn.enlightenment.org/svn/e/trunk/evas/
137 cd evas
138 ./autogen.sh
139 ./configure --enable-image-loader-eet --enable-font-loader-eet --enable-image-loader-jpeg --enable-image-loader-png --enable-buffer
140 make
141 sudo make install
142 cd
143
1444. You need Ecore from the trunk svn branch built with ecore-x and ecore-evas.
145
146 svn co http://svn.enlightenment.org/svn/e/trunk/ecore/
147 cd ecore
148 ./autogen.sh
149 ./configure --enable-ecore-x --enable-ecore-evas --enable-ecore-evas-software-buffer --enable-ecore-evas-software-x11 --enable-ecore-evas-software-buffer
150 make
151 sudo make install
152 cd
153
1545. You need embryo from the trunk svn branch
155
156 svn co http://svn.enlightenment.org/svn/e/trunk/embryo/
157 cd embryo
158 ./autogen.sh
159 ./configure
160 make
161 sudo make install
162 cd
163
164@endverbatim
165
166
167
168
169
170
171
172
173
174@section compiling How to compile and test Edje
175
176Now you need to compile and install Edje.
177
178@verbatim
179 ./configure
180 make
181 sudo make install
182@endverbatim
183
184You now have it installed and ready to go, but you need input
185data. There are lots of examples in SVN, the best one is
186Enlightenment's own theme file.
187
188You may use different tools to edit and view the generated ".edj"
189files, for instance:
190
191 - editje (http://trac.enlightenment.org/e/wiki/Editje)
192 - edje_viewer (http://trac.enlightenment.org/e/wiki/Edje_Viewer)
193
194
195
196
197
198
199
200
201
202
203@section details So how does this all work?
204
205Edje internally holds a geometry state machine and state graph of what is
206visible, not, where, at what size, with what colors etc. This is described
207to Edje from an Edje .edj file containing this information. These files can
208be produced by using edje_cc to take a text file (a .edc file) and "compile"
209an output .edj file that contains this information, images and any other
210data needed.
211
212The application using Edje will then create an object in its Evas
213canvas and set the bundle file to use, specifying the @b group name to
214use. Edje will load such information and create all the required
215children objects with the specified properties as defined in each @b
216part of the given group. See the following annotated example:
217
218@code
219/*
220 * edje_example.c:
221 *
222 * Creates a window using Ecore_Evas and inside it an object with
223 * the edje group "my_group" from file "edje_example.edj".
224 *
225 * Requires edje_example.edj in the current folder.
226 *
227 * Compile:
228 * gcc -o edje_example edje_example.c `pkg-config --cflags --libs eina evas ecore ecore-evas edje`
229 */
230
231#include <Eina.h>
232#include <Evas.h>
233#include <Ecore.h>
234#include <Ecore_Evas.h>
235#include <Edje.h>
236
237#define WIDTH 320
238#define HEIGHT 240
239
240static Evas_Object *create_my_group(Evas *canvas, const char *text)
241{
242 Evas_Object *edje;
243
244 /* create the edje object where we'll load our file */
245 edje = edje_object_add(canvas);
246 if (!edje)
247 {
248 EINA_LOG_CRIT("could not create edje object!");
249 return NULL;
250 }
251
252 /* load our desired file */
253 if (!edje_object_file_set(edje, "edje_example.edj", "my_group"))
254 {
255 int err = edje_object_load_error_get(edje);
256 const char *errmsg = edje_load_error_str(err);
257 EINA_LOG_ERR("could not load 'my_group' from edje_example.edj: %s",
258 errmsg);
259
260 evas_object_del(edje);
261 return NULL;
262 }
263
264 if (text)
265 {
266 /* this is will replace the string used by "text" part in "my_group" */
267 if (!edje_object_part_text_set(edje, "text", text))
268 {
269 EINA_LOG_WARN("could not set the text. "
270 "Maybe part 'text' does not exist?");
271 }
272 }
273
274 /* operate on edje as any other object */
275 evas_object_move(edje, 0, 0);
276 evas_object_resize(edje, WIDTH, HEIGHT);
277 evas_object_show(edje);
278 return edje;
279}
280
281int main(int argc, char *argv[])
282{
283 Ecore_Evas *window;
284 Evas *canvas;
285 Evas_Object *edje;
286 const char *text;
287
288 eina_init();
289 evas_init();
290 ecore_init();
291 ecore_evas_init();
292 edje_init();
293
294 window = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
295 if (!window)
296 {
297 EINA_LOG_CRIT("could not create window.");
298 return -1;
299 }
300 canvas = ecore_evas_get(window);
301
302 text = (argc > 1) ? argv[1] : NULL;
303
304 edje = create_my_group(canvas, text);
305 if (!edje)
306 return -2;
307
308 ecore_evas_show(window);
309 ecore_main_loop_begin();
310
311 evas_object_del(edje);
312 ecore_evas_free(window);
313
314 return 0;
315}
316@endcode
317
318It requires the following source Edje file:
319@code
320// compile: edje_cc edje_example.edc
321collections {
322 group {
323 name: "my_group"; // must be the same as in edje_example.c
324
325 parts {
326 part {
327 name: "background";
328 type: RECT; // plain boring rectangle
329 mouse_events: 0; // we don't need any mouse event on the background
330
331 // just one state "default"
332 description {
333 state: "default" 0.0; // must always exist
334 color: 255 255 255 255; // white
335
336 // define part coordinates:
337
338 rel1 { // top-left point at (0, 0) [WIDTH * 0 + 0, HEIGHT * 0 + 0]
339 relative: 0.0 0.0;
340 offset: 0 0;
341 }
342 rel2 { // bottom-right point at (WIDTH * 1.0 - 1, HEIGHT * 1.0 - 1)
343 relative: 1.0 1.0;
344 offset: -1 -1;
345 }
346 }
347 }
348
349 part {
350 name: "text";
351 type: TEXT;
352 mouse_events: 1; // we want to change the color on mouse-over
353
354 // 2 states, one "default" and another "over" to be used
355 // on mouse over effect
356
357 description {
358 state: "default" 0.0;
359 color: 255 0 0 255; // red
360
361 // define part coordinates:
362
363 rel1 { // top-left at (WIDTH * 0.1 + 5, HEIGHT * 0.2 + 10)
364 relative: 0.1 0.2;
365 offset: 5 10;
366 }
367 rel2 { // bottom-right at (WIDTH * 0.9 - 6, HEIGHT * 0.8 - 11)
368 relative: 0.9 0.8;
369 offset: -6 -11;
370 }
371
372 // define text specific state details
373 text {
374 font: "Sans"; /* using fontconfig name! */
375 size: 10;
376 text: "hello world";
377 }
378 }
379
380 description {
381 state: "over" 0.0;
382 inherit: "default" 0.0; // copy everything from "default" at this point
383
384 color: 0 255 0 255; // override color, now it is green
385 }
386 }
387
388 // do programs to change color on text mouse in/out (over)
389 programs {
390 program {
391 // what triggers this program:
392 signal: "mouse,in";
393 source: "text";
394
395 // what this program does:
396 action: STATE_SET "over" 0.0;
397 target: "text";
398
399 // do the state-set in a nice interpolation animation
400 // using linear time in 0.1 second
401 transition: LINEAR 0.1;
402 }
403
404 program {
405 // what triggers this program:
406 signal: "mouse,out";
407 source: "text";
408
409 // what this program does:
410 action: STATE_SET "default" 0.0;
411 target: "text";
412
413 // do the state-set in a nice interpolation animation
414 // using linear time in 0.1 second
415 transition: LINEAR 0.1;
416 }
417 }
418 }
419 }
420}
421@endcode
422
423
424One should save these files as edje_example.c and edje_example.edc then:
425@verbatim
426gcc -o edje_example edje_example.c `pkg-config --cflags --libs eina evas ecore ecore-evas edje`
427edje_cc edje_example.edc
428
429./edje_example "some text"
430@endverbatim
431
432Although simple, this example illustrates that animations and state
433changes can be done from the Edje file itself without any requirement
434in the C application.
435
436Before digging into changing or creating your own Edje source (edc)
437files, read the \ref edcref.
438
439
440
441@section history Edje History
442
443It's a sequel to "Ebits" which has serviced the needs of Enlightenment
444development for early version 0.17. The original design parameters under
445which Ebits came about were a lot more restricted than the resulting
446use of them, thus Edje was born.
447
448Edje is a more complex layout engine compared to Ebits. It doesn't
449pretend to do containing and regular layout like a widget set. It
450still inherits the more simplistic layout ideas behind Ebits, but it
451now does them a lot more cleanly, allowing for easy expansion, and the
452ability to cover much more ground than Ebits ever could. For the
453purposes of Enlightenment 0.17, Edje was conceived to serve all the
454purposes of creating visual elements (borders of windows, buttons,
455scrollbars, etc.) and allow the designer the ability to animate,
456layout and control the look and feel of any program using Edje as its
457basic GUI constructor.
458
459Unlike Ebits, Edje separates the layout and behavior logic.
460
461
462
463
464
465
466
467
468
469@todo Complete documentation of API
470@todo Bytecode language for extending programs... but what/how?
471
472*/
473
474
475/**
476
477@example embryo_custom_state.edc
478This example show how to create a custom state from embryo. Clicking on the
4793 labels will rotate the object in the given direction.
480
481@example embryo_pong.edc
482Super-simple Pong implementation in pure embryo.
483
484@example embryo_run_program.edc
485This example show how to run an edje program from embryo code.
486
487@example embryo_set_state.edc
488This example show how to change the state of a part from embryo code.
489
490@example embryo_set_text.edc
491This example show how to set the text in TEXT part from embryo code.
492
493@example embryo_timer.edc
494This example show the usage of timers in embryo.
495
496@example external_elm_anchorblock.edc
497This example use an elementary anchorblock and a button to animate the text.
498
499@example external_elm_button.edc
500This example create some elementary buttons and do some actions on user click.
501
502@example external_elm_check.edc
503This example show EXTERNAL checkbox in action.
504
505@example external_elm_panes.edc
506This example show EXTERNAL elementary panes in action.
507
508@example external_emotion_elm.edc
509Super-concise video player example using Edje/Emotion/Elementary.
510
511@example lua_script.edc
512This example show the usage of lua scripting to create and animate some
513objects in the canvas.
514
515@example toggle_using_filter.edc
516This example show how to toggle the state of a part using the 'filter'
517param in edje programs
518
519*/