Menu
▾
▴
E SVN: discomfitor trunk/edje/doc
|
From: Enlightenment S. <no-...@en...> - 2011-07-24 21:32:42
|
Log: populate edje.dox.in from edje.dox (was this intentionally empty?), update from AUTHORS Author: discomfitor Date: 2011-07-24 14:32:35 -0700 (Sun, 24 Jul 2011) New Revision: 61657 Trac: http://trac.enlightenment.org/e/changeset/61657 Modified: trunk/edje/doc/edje.dox.in Modified: trunk/edje/doc/edje.dox.in =================================================================== --- trunk/edje/doc/edje.dox.in 2011-07-24 21:25:27 UTC (rev 61656) +++ trunk/edje/doc/edje.dox.in 2011-07-24 21:32:35 UTC (rev 61657) @@ -0,0 +1,521 @@ +/** +@file edje.dox +@brief Edje Graphical Design Library + +These routines are used for Edje. +*/ + +/** + +@mainpage Edje Library Documentation +@image html e.png +@version 1.0.999.57208 +@author Carsten Haitzler <raster@@rasterman.com> +@author Tilman Sauerbeck (tilman at code-monkey de) +@author ZigsMcKenzie <zigsmckenzie@@gmail.com> +@author Cedric BAIL <cedric.bail@@free.fr> +@author Brian Mattern <rephorm@@rephorm.com> +@author Mathieu Taillefumier <mathieu.taillefumier@@free.fr> +@author Tristan <blunderer@@gmail.com> +@author Gustavo Lima Chaves <glima@@profusion.mobi> +@author Bruno Dilly <bdilly@@profusion.mobi> +@author Fabiano Fidêncio <fidencio@@profusion.mobi> +@author Jihoon Kim <jihoon48.kim@@samsung.com> +@author Tiago Falcão <tiago@@profusion.mobi> +@author Davide Andreoli <dave@@gurumeditation.it> +@author Sebastian Dransfeld <sd@@tango.flipp.net> +@author Tom Hacohen <tom@@stosb.com> +@author Aharon Hillel <a.hillel@@partner.samsung.com> +@author Shilpa Singh <shi...@sa...> <shi...@gm...> +@author Mike Blumenkrantz <mi...@ze... +@date 2003-2011 + + + + + + + + + + +@section intro What is Edje? + +Edje is a complex graphical design & layout library. + +It doesn't pretend to do containing and regular layout like a widget +set, but it is the base for such components. Based on the requirements +of Enlightenment 0.17, Edje should serve all the purposes of creating +visual elements (borders of windows, buttons, scrollbars, etc.) and +allow the designer the ability to animate, layout and control the look +and feel of any program using Edje as its basic GUI constructor. This +library allows for multiple collections of Layouts in one file, +sharing the same image and font database and thus allowing a whole +theme to be conveniently packaged into 1 file and shipped around. + +Edje separates the layout and behavior logic. Edje files ship with an +image and font database, used by all the parts in all the collections +to source graphical data. It has a directory of logical part names +pointing to the part collection entry ID in the file (thus allowing +for multiple logical names to point to the same part collection, +allowing for the sharing of data between display elements). Each part +collection consists of a list of visual parts, as well as a list of +programs. A program is a conditionally run program that if a +particular event occurs (a button is pressed, a mouse enters or leaves +a part) will trigger an action that may affect other parts. In this +way a part collection can be "programmed" via its file as to hilight +buttons when the mouse passes over them or show hidden parts when a +button is clicked somewhere etc. The actions performed in changing +from one state to another are also allowed to transition over a period +of time, allowing animation. Programs and animations can be run in +"parallel". + +This separation and simplistic event driven style of programming can produce +almost any look and feel one could want for basic visual elements. Anything +more complex is likely the domain of an application or widget set that may +use Edje as a convenient way of being able to configure parts of the display. + +For details of Edje's history, see the \ref history section. + + + + + + + + +@section requirements What does Edje require? + +Edje requires fairly little on your system. to use the Edje runtime library +you need: + + - Evas (library) + - Ecore (library) + - Eet (library) + - Embryo (library) + - Eina (library) + +Evas needs to be build with the JPEG, PNG and EET image loaders enabled at a +minimum. Edje uses X for the test program, so you will need the SOFTWARE_X11 +engine built into Evas as well. A suggested configure list is below in the +"cheat sheet" for Evas. + +Ecore needs the ECORE, ECORE_EVAS and ECORE_X modules built at a minimum. +It's suggested to build all the Ecore modules, but the ECORE_FB modules is +definitely optional. + +Eina, Eet and Embryo have no interesting options so just build and +install them. + +It is suggested right now that you get the latest SVN versions of the +required libraries. You also need to build them in the right order and make +sure the right options are enabled in the required libraries. Here is a +quick "cheat sheet" on how to get started. + +@verbatim +1. You need Eina from the trunk svn branch. + + svn co http://svn.enlightenment.org/svn/e/trunk/eina/ + cd eina + ./autogen.sh + ./configure + make + sudo make install + cd + +2. You need Eet from the trunk svn branch. + + svn co http://svn.enlightenment.org/svn/e/trunk/eet/ + cd eet + ./autogen.sh + ./configure + make + sudo make install + cd + +3. You need Evas from the trunk svn branch built with eet, png and jpeg loader support. + + svn co http://svn.enlightenment.org/svn/e/trunk/evas/ + cd evas + ./autogen.sh + ./configure --enable-image-loader-eet --enable-font-loader-eet --enable-image-loader-jpeg --enable-image-loader-png --enable-buffer + make + sudo make install + cd + +4. You need Ecore from the trunk svn branch built with ecore-x and ecore-evas. + + svn co http://svn.enlightenment.org/svn/e/trunk/ecore/ + cd ecore + ./autogen.sh + ./configure --enable-ecore-x --enable-ecore-evas --enable-ecore-evas-software-buffer --enable-ecore-evas-software-x11 --enable-ecore-evas-software-buffer + make + sudo make install + cd + +5. You need embryo from the trunk svn branch + + svn co http://svn.enlightenment.org/svn/e/trunk/embryo/ + cd embryo + ./autogen.sh + ./configure + make + sudo make install + cd + +@endverbatim + + + + + + + + + +@section compiling How to compile and test Edje + +Now you need to compile and install Edje. + +@verbatim + ./configure + make + sudo make install +@endverbatim + +You now have it installed and ready to go, but you need input +data. There are lots of examples in SVN, the best one is +Enlightenment's own theme file. + +You may use different tools to edit and view the generated ".edj" +files, for instance: + + - editje (http://trac.enlightenment.org/e/wiki/Editje) + - edje_viewer (http://trac.enlightenment.org/e/wiki/Edje_Viewer) + + + + + + + + + + +@section details So how does this all work? + +Edje internally holds a geometry state machine and state graph of what is +visible, not, where, at what size, with what colors etc. This is described +to Edje from an Edje .edj file containing this information. These files can +be produced by using edje_cc to take a text file (a .edc file) and "compile" +an output .edj file that contains this information, images and any other +data needed. + +The application using Edje will then create an object in its Evas +canvas and set the bundle file to use, specifying the @b group name to +use. Edje will load such information and create all the required +children objects with the specified properties as defined in each @b +part of the given group. See the following annotated example: + +@code +/* + * edje_example.c: + * + * Creates a window using Ecore_Evas and inside it an object with + * the edje group "my_group" from file "edje_example.edj". + * + * Requires edje_example.edj in the current folder. + * + * Compile: + * gcc -o edje_example edje_example.c `pkg-config --cflags --libs eina evas ecore ecore-evas edje` + */ + +#include <Eina.h> +#include <Evas.h> +#include <Ecore.h> +#include <Ecore_Evas.h> +#include <Edje.h> + +#define WIDTH 320 +#define HEIGHT 240 + +static Evas_Object *create_my_group(Evas *canvas, const char *text) +{ + Evas_Object *edje; + + /* create the edje object where we'll load our file */ + edje = edje_object_add(canvas); + if (!edje) + { + EINA_LOG_CRIT("could not create edje object!"); + return NULL; + } + + /* load our desired file */ + if (!edje_object_file_set(edje, "edje_example.edj", "my_group")) + { + int err = edje_object_load_error_get(edje); + const char *errmsg = edje_load_error_str(err); + EINA_LOG_ERR("could not load 'my_group' from edje_example.edj: %s", + errmsg); + + evas_object_del(edje); + return NULL; + } + + if (text) + { + /* this is will replace the string used by "text" part in "my_group" */ + if (!edje_object_part_text_set(edje, "text", text)) + { + EINA_LOG_WARN("could not set the text. " + "Maybe part 'text' does not exist?"); + } + } + + /* operate on edje as any other object */ + evas_object_move(edje, 0, 0); + evas_object_resize(edje, WIDTH, HEIGHT); + evas_object_show(edje); + return edje; +} + +int main(int argc, char *argv[]) +{ + Ecore_Evas *window; + Evas *canvas; + Evas_Object *edje; + const char *text; + + eina_init(); + evas_init(); + ecore_init(); + ecore_evas_init(); + edje_init(); + + window = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL); + if (!window) + { + EINA_LOG_CRIT("could not create window."); + return -1; + } + canvas = ecore_evas_get(window); + + text = (argc > 1) ? argv[1] : NULL; + + edje = create_my_group(canvas, text); + if (!edje) + return -2; + + ecore_evas_show(window); + ecore_main_loop_begin(); + + evas_object_del(edje); + ecore_evas_free(window); + + return 0; +} +@endcode + +It requires the following source Edje file: +@code +// compile: edje_cc edje_example.edc +collections { + group { + name: "my_group"; // must be the same as in edje_example.c + + parts { + part { + name: "background"; + type: RECT; // plain boring rectangle + mouse_events: 0; // we don't need any mouse event on the background + + // just one state "default" + description { + state: "default" 0.0; // must always exist + color: 255 255 255 255; // white + + // define part coordinates: + + rel1 { // top-left point at (0, 0) [WIDTH * 0 + 0, HEIGHT * 0 + 0] + relative: 0.0 0.0; + offset: 0 0; + } + rel2 { // bottom-right point at (WIDTH * 1.0 - 1, HEIGHT * 1.0 - 1) + relative: 1.0 1.0; + offset: -1 -1; + } + } + } + + part { + name: "text"; + type: TEXT; + mouse_events: 1; // we want to change the color on mouse-over + + // 2 states, one "default" and another "over" to be used + // on mouse over effect + + description { + state: "default" 0.0; + color: 255 0 0 255; // red + + // define part coordinates: + + rel1 { // top-left at (WIDTH * 0.1 + 5, HEIGHT * 0.2 + 10) + relative: 0.1 0.2; + offset: 5 10; + } + rel2 { // bottom-right at (WIDTH * 0.9 - 6, HEIGHT * 0.8 - 11) + relative: 0.9 0.8; + offset: -6 -11; + } + + // define text specific state details + text { + font: "Sans"; /* using fontconfig name! */ + size: 10; + text: "hello world"; + } + } + + description { + state: "over" 0.0; + inherit: "default" 0.0; // copy everything from "default" at this point + + color: 0 255 0 255; // override color, now it is green + } + } + + // do programs to change color on text mouse in/out (over) + programs { + program { + // what triggers this program: + signal: "mouse,in"; + source: "text"; + + // what this program does: + action: STATE_SET "over" 0.0; + target: "text"; + + // do the state-set in a nice interpolation animation + // using linear time in 0.1 second + transition: LINEAR 0.1; + } + + program { + // what triggers this program: + signal: "mouse,out"; + source: "text"; + + // what this program does: + action: STATE_SET "default" 0.0; + target: "text"; + + // do the state-set in a nice interpolation animation + // using linear time in 0.1 second + transition: LINEAR 0.1; + } + } + } + } +} +@endcode + + +One should save these files as edje_example.c and edje_example.edc then: +@verbatim +gcc -o edje_example edje_example.c `pkg-config --cflags --libs eina evas ecore ecore-evas edje` +edje_cc edje_example.edc + +./edje_example "some text" +@endverbatim + +Although simple, this example illustrates that animations and state +changes can be done from the Edje file itself without any requirement +in the C application. + +Before digging into changing or creating your own Edje source (edc) +files, read the \ref edcref. + + + +@section history Edje History + +It's a sequel to "Ebits" which has serviced the needs of Enlightenment +development for early version 0.17. The original design parameters under +which Ebits came about were a lot more restricted than the resulting +use of them, thus Edje was born. + +Edje is a more complex layout engine compared to Ebits. It doesn't +pretend to do containing and regular layout like a widget set. It +still inherits the more simplistic layout ideas behind Ebits, but it +now does them a lot more cleanly, allowing for easy expansion, and the +ability to cover much more ground than Ebits ever could. For the +purposes of Enlightenment 0.17, Edje was conceived to serve all the +purposes of creating visual elements (borders of windows, buttons, +scrollbars, etc.) and allow the designer the ability to animate, +layout and control the look and feel of any program using Edje as its +basic GUI constructor. + +Unlike Ebits, Edje separates the layout and behavior logic. + + + + + + + + + +@todo Complete documentation of API +@todo Bytecode language for extending programs... but what/how? + +*/ + + +/** + +@example embryo_custom_state.edc +This example show how to create a custom state from embryo. Clicking on the +3 labels will rotate the object in the given direction. + +@example embryo_pong.edc +Super-simple Pong implementation in pure embryo. + +@example embryo_run_program.edc +This example show how to run an edje program from embryo code. + +@example embryo_set_state.edc +This example show how to change the state of a part from embryo code. + +@example embryo_set_text.edc +This example show how to set the text in TEXT part from embryo code. + +@example embryo_timer.edc +This example show the usage of timers in embryo. + +@example external_elm_anchorblock.edc +This example use an elementary anchorblock and a button to animate the text. + +@example external_elm_button.edc +This example create some elementary buttons and do some actions on user click. + +@example external_elm_check.edc +This example show EXTERNAL checkbox in action. + +@example external_elm_panes.edc +This example show EXTERNAL elementary panes in action. + +@example external_emotion_elm.edc +Super-concise video player example using Edje/Emotion/Elementary. + +@example lua_script.edc +This example show the usage of lua scripting to create and animate some +objects in the canvas. + +@example toggle_using_filter.edc +This example show how to toggle the state of a part using the 'filter' +param in edje programs + +*/ |