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