Enlightenment CVS committal
Author : dresb
Project : e17
Module : docs
Dir : e17/docs/devwithedje/txt
Modified Files:
building_a_framework.txt introduction_to_widgets.txt
the_foundations_in_practice.txt widgets_with_edje.txt
Added Files:
simpler_library_initialization.txt
simpler_theme_management.txt simpler_window_setup.txt
the_ewl_as_a_shortcut.txt
Log Message:
almost there.
===================================================================
RCS file: /cvs/e/e17/docs/devwithedje/txt/building_a_framework.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- building_a_framework.txt 6 Apr 2008 19:04:25 -0000 1.1
+++ building_a_framework.txt 13 Apr 2008 21:30:14 -0000 1.2
@@ -1,23 +1,117 @@
Hopefully the reader has not been introduced to the concept of software
frameworks by web based monsters like Ruby on Rails. Personally I think RoR is
-great, my point is that a framework does not necessarily mean big complex,
-abstract software libraries. A framework can be seen as the standardization of
-common, complex tasks into a library shared by group of applications. With a
-framework short development times means a compromise with flexibility.
+great and my point is that a framework does not necessarily mean large software
+libraries. A framework can be seen as library of functions determined by the
+similiarity in the profile of the applications that use it. In a framework,
+shorter development time means either more specific profiles or more complex
+library code.
In this section and the following subsections we will develop an application
-framework for applications with a specific profile. An X11 desktop application
-that doesn't require any exotic manipulation of its theme files and with a
-interface simple enough that all its objects can be laid out using a single
-Edje object.
-
-The tasks that this framework will take care of are pretty straight forward:
-* Maintain a configuration file (in the default location used by Ecore_Config).
-* Setup the window properties and main layout from a theme object.
-* Manage theme objects, including changing a theme file on runtime and
-maintaining two the files, current and default.
-
-The example application will be an Edje group viewer, this application will
-receive a filename and a group name, it will display the application inside a
-viewport, print the last signal emitted by the group and provide a minimap for
-navigating the viewport. Without further ado, here it is, the main file::
+framework for applications with a specific profile: "A X11 desktop application
+that doesn't require any exotic manipulation of its theme or configuration
+files". A list of the tasks the framework must perform follow:
+
+* Configuration (Using Ecore_Config).
+ * Initialization and shutdown of the necesary services.
+ * Saving configuration changes on exit.
+ * Recall the previously saved values on initialzation.
+ * Control that the necessary configuration and theme files exist.
+
+* Interface Management
+ * Create windows with their properties lifted from a given Edje object.
+ * Allocate, load and display Edje objects from a "current" theme file, set
+ by the user or a "default" theme file setup by the application developer.
+
+The example application using this framework will be an Edje group viewer, this
+application will receive a filename and a group name, it will display them
+inside a viewport managed with a minimap. The last signal emitted by the object
+is going to be printed to a given text string. Without further ado, here it is,
+the main file::
+
+ #include "../lib/framework.c"
+ #include "../lib/viewport.c"
+ #include "../lib/minimap.c"
+ #include <string.h>
+ #include <limits.h>
+
+ int arguments_parse(char path[], char group[], int argc, char **argv);
+
+ int main(int argc, char **argv) {
+
+ Ecore_Evas *mainWindow = NULL;
+ Evas *mainCanvas = NULL;
+ Evas_Coord width, height;
+ Evas_Object *mainLayout, *toView, *viewport, *minimap;
+ char path[PATH_MAX],group[100];
+
+ application_name_set("Plain Edje Viewer");
+ if (!simpler_init())
+ return EXIT_FAILURE;
+
+ if(!arguments_parse(path, group, argc, argv))
+ return EXIT_FAILURE;
+
+ mainWindow = simpler_window_new("window/main",NULL);
+ if (!mainWindow)
+ return EXIT_FAILURE;
+ mainCanvas = ecore_evas_get(mainWindow);
+ mainLayout = ecore_evas_data_get(mainWindow,"layout");
+
+The precedeing code snippet shows two of the three shortcuts our framework
+provides. The first function ``simpler_init`` is used to group all the library
+intialization functions along with the configuration initialzation functions.
+Following the library initialzation comes ``simpler_window_new`` which is used
+to create a window based on values provided by a given Edje group. The group
+itself is saved inside the Ecore_Evas canvas wrapper as a data pointer and can
+be retrieved with ``ecore_evas_data_get``. As you might notice we use of a
+function named ``arguments_parse`` to get the path of the requested file and
+group from the array of arguments.
+
+Notice that the call to ``simpler_window_new`` does not have any filename
+attached to it. But how does the application know where to look this group up?
+This is the work of Ecore_Config and we will review how is it used in the next
+section of the book. In any case, the following code snippet show a little
more
+Edje related action::
+
+ toView = edje_object_add(mainCanvas);
+ edje_object_file_set(toView, path, group);
+ edje_object_size_min_calc(toView, &width, &height);
+ if(width <= 0)
+ ecore_evas_geometry_get(mainWindow, NULL, NULL, &width, NULL);
+ if(height <= 0)
+ ecore_evas_geometry_get(mainWindow, NULL, NULL, NULL, &height);
+ evas_object_resize(toView, width, height);
+ evas_object_move(toView,0,0);
+ evas_object_show(toView);
+
+ viewport = viewport_add(mainCanvas);
+ viewport_theme_set(viewport, simpler_object_add(mainCanvas,
"widget.minimap"));
+ viewport_target_set(viewport,toView);
+ edje_object_part_swallow(mainLayout,"swallow.viewport", viewport);
+
+ minimap = minimap_add(mainCanvas);
+ minimap_theme_set(minimap, simpler_object_add(mainCanvas,
"widget.minimap"));
+ edje_object_part_swallow(mainLayout,"swallow.minimap", minimap);
+ minimap_viewport_set(minimap,viewport);
+
+ ecore_main_loop_begin();
+ }
+
+You might notice the code snippet is split in three bigger sections. In
+these sections we include an Edje object to view, we setup the viewport for the
+object and the minimap for the viewport respectively. Since the application is
+going to display a
+group of an arbitrary name from an arbitrary file we don't use the shortcut
+functions to load and display the target. But among these know functions
+``ecore_evas_geometry_get`` stands out. This function is used to load the
+current size of the window as the object width or height in case it does not
+have either one.
+
+The following two code sections setup each widget, we won't review the
+internals of these yet. We will explore the function ``simpler_object_add``
+that is used to load the theme groups for these widgets. In order to mantain
+our santity (and to save some trees) some additional functions or pieces have
+been left out of the book. The complete, commented sources for this framework
+and the "Plain Edje Viewer" application can be found in the CVS repository of
+the Enlightenment proyect under ``e17/docs/devwithedje/src``. Rest assured the
+omitted functions wont add much to your knowledege about Edje.
\ No newline at end of file
===================================================================
RCS file: /cvs/e/e17/docs/devwithedje/txt/introduction_to_widgets.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- introduction_to_widgets.txt 6 Apr 2008 19:04:25 -0000 1.1
+++ introduction_to_widgets.txt 13 Apr 2008 21:30:14 -0000 1.2
@@ -32,7 +32,7 @@
In general terms, a developer implementing a widget from the scratch would have
to program functions to:
-* Manipulate the canvas to draw its primitives.
+* Manipulate the canvas primitives to draw the widget.
* Register new signal types to emit as a widget.
* Display information and retreive changes.
* Handle events ocurring in the environment that affect it.
===================================================================
RCS file: /cvs/e/e17/docs/devwithedje/txt/the_foundations_in_practice.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- the_foundations_in_practice.txt 4 Apr 2008 23:18:38 -0000 1.1
+++ the_foundations_in_practice.txt 13 Apr 2008 21:30:14 -0000 1.2
@@ -1,17 +1,17 @@
By pointing out that the Enlightenment Foundation Libraries are designed in a
Object Oriented manner I wish not to raise the wrath of OO purists but to
-simplify the mental image of the structure of the EFL C API in the reader's
-imagination.
+simplify the reader's mental image of how the EFL C Application Programming
+Interface is structured.
-Now that the pitchforks are back in the barn allow me to put it in more clear
-terms with a simple example::
+Now that the pitchforks are back in the barn and torchs have been put off,
+allow me to put it in more clear terms using a simple example::
Evas_Object *button = NULL;
button = edje_object_add(evascanvas);
edje_object_file_set(button, "theme.edj", "button");
This is a simple C snippet that could be translated into a more (sintactically
-speaking) object oriented language like Python as::
+speaking) OO language like Python as::
button = Evas_Object()
button.file_set("theme.edj","button")
@@ -21,8 +21,8 @@
If we dissected the last function call we could split it into three groups.
First, the class of the object to manipulate, ``edje_object``, second, the
method to call ``file_set`` and third the pointer to the object instance
-``(button,`` along with the parameters ``"theme.edj","button")`` or, in more
-generic terms, ``class_method(instance,parameters)``.
+``(button,`` along with the parameters ``"theme.edj","button")`` or generically
+speaking, ``class_method(instance,parameters)``.
The first source snippet in the following tutorial is, of course, the first
exception. The following function calls deal with the library itself. Anyway,
===================================================================
RCS file: /cvs/e/e17/docs/devwithedje/txt/widgets_with_edje.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- widgets_with_edje.txt 6 Apr 2008 19:04:25 -0000 1.1
+++ widgets_with_edje.txt 13 Apr 2008 21:30:14 -0000 1.2
@@ -1,7 +1,64 @@
We have seen there are roughly 5 kinds of functions that have to be implemented
-in order to create a widget from scratch. Altought the way groups are split
-might not seem equitative to the amount of work each one might entail, the
-divisions are concordant with the shortcuts Edje provides. For the cases where
-the number of functions in one group seems to clearly outweights the others,
+in order to create a widget from scratch. Although the way groups are split
+might not seem to correspond with the amount of work each one might entail, the
+divisions concord with the shortcuts Edje provides. For the cases where
+the number of functions in one group seems to clearly outweighs the others,
Edje provides additional shortcuts not directly related to the design concepts
and design elements we have seen in the previous chapters.
+
+I will begin with **Manipulate the canvas primitives to draw the widget** since
+it's the easiest to explain. With a plain canvas approach to widget creation,
+this would mean the developer must manually create each rect, line, etc. that
+form its widget. Instead, Edje draws the primitive objects based on the
+designer's specifications in the Edje Data Collection file, not a single
+primitive has to be created or manipulated by the application developer.
+
+Addressing the task **Handle events occurring on its primitives** using
+Edje can be done with two different, but compatible, approaches. The first
+approach is also available in the other low level libraries. To intercept all
+the signals coming from the primitive objects that form the widget, filter the
+signals and (sometimes) emit a new kind of signal. This approach is useful in
+many situations and that's why it is possible to use it in Edje even when it
+provides an alternative, not available among its low level cousins. With Edje
+designer can write small "programs" in his EDC files. An Edje program is
+not as complex as the name might make us think. Unless the designer uses a
+script block (rare) the average Edje program would look like this::
+
+ program {
+ name: "playthemusic";
+ signal: "mouse,down,1";
+ source: "*";
+ action: action: SIGNAL_EMIT "PLAY" "button";
+ }
+
+There is more to Edje programs than just this, but this example will be enough
+to illustrate the point. Since Edje programs are limited to their own group,
+this program is limited to a hypothetical "button" group. What the program
does
+is to emit the signal "PLAY" when the left button is pressed over any part that
+forms the "button" group. The application only has to listen for the PLAY
+signal. When and why that signal will be emitted is completely up to the
+designer to decide. He could change "mouse,down,1" to "mouse,wheel,*" and cause
+the music to play when the user uses the mouse wheel over any part of the
+button.
+
+The previously illustrated program shows that **Register new signal types to
+emit as a widget** will not be as common as it would with another canvas
+library. Most of the time, it will be designer who implements new signal
types.
+Sadly, there is little that Edje can provide concerning **Handle events
+occurring in the environment that affect it**.
+
+To **Display information and retrieve changes** is quite simple. As with any
+other low level library, the developer will have to alter some primitive in
+order to display the requested information. Most of the time this means
+changing a string of characters, complex diagrams and similar objects go
+beyond the scope of Edje and enter the realm of Evas programming. Plain Evas
+objects, of course, integrate perfectly with Edje interfaces.
+
+A difference between a regular canvas lib and Edje concerns conveying subtle
+information by changing the "state" of the interface. Designers can implement
+any arbitrary number of states for any part or group and change them using
+simple Edje programs. The same programs can also be triggered by the
+application. For example, to disable a button in a plain canvas the developer
+would have to call functions that gray out the background and text. With Edje
+the developer just emits the signal "DISABLED" to the button and lets the
+designer implement this however he wants.
\ No newline at end of file
-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference
Don't miss this year's exciting event. There's still time to save $100.
Use priority code J8TL2D2.
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone
_______________________________________________
enlightenment-cvs mailing list
enlightenment-cvs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
