forked from enlightenment/efl
populate edje.dox.in from edje.dox (was this intentionally empty?), update from AUTHORS
SVN revision: 61657
This commit is contained in:
parent
f862f71e4c
commit
db98b3fe32
|
@ -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 <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
|
||||
|
||||
*/
|
Loading…
Reference in New Issue