+/**
+@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 <shilpa.singh@samsung.com> <shilpasingh.o@gmail.com>
+@author Mike Blumenkrantz <mike@zentific.com
+@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
+
+*/
projects / framework / uifw / edje.git / commitdiff