[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [E-devel] Efl High level documentation progress



On Tue, 2006-05-02 at 10:50 +0300, kkapelon@freemail.gr wrote:
> Because of Easter, progress is not as fast as I want.
> First draft of EFL high level docs is online!
> 
> Currently only the introduction and
> what _I_ want to write about Evas is ready.
> 
> Browse as html
> http://homepages.pathfinder.gr/kazanaki/contrib/
> 
> Download and view with xpdf
> http://homepages.pathfinder.gr/kazanaki/contrib/concepts.pdf
> 
> Hosting is slow so please be patient.
> 
> I am NOT a core EFL developer. I am not an expert EFL programmer.
> So maybe
> 
> -I have written things which are incorrect/obsolete
> -I have missed important information
> 
> So before I move on to Edje please
> give me some feedback...
> 

Quite some time ago I started an attempt to modernize and cleanup the
Edje book (and learn Edje along the way).  Attached is a patch of my
unfinished efforts.  I hope you find it useful.

Also, here is a link to added imagery:
http://gnuk.net/~eco/edjebook-updated-images.tar.gz
(extract to e17)

It's great to see someone working on the much needed documentation.

> Expecting your comments/flames/suggestions.
> Kostis

Regards,
Brad Anderson
Index: docs/edjebook/Makefile
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/Makefile,v
retrieving revision 1.3
diff -r1.3 Makefile
31,32c31,32
< #FO_XSL = $(PREFIX)/xsl-stylesheets-1.62.0/fo/docbook.xsl	# Gentoo DB FO
< FO_XSL = $(PREFIX)/docbook-xsl-1.64.1/fo/docbook.xsl	# Official DB FO
---
> FO_XSL = $(PREFIX)/xsl-stylesheets-1.68.1/fo/docbook.xsl	# Gentoo DB FO
> #FO_XSL = $(PREFIX)/docbook-xsl-1.64.1/fo/docbook.xsl	# Official DB FO
39,40c39,40
< HTML_XSL = $(PREFIX)/docbook-xsl-1.64.0/html/docbook.xsl	# Gentoo DB HTML
< HTML_CHUNK_XSL = $(PREFIX)/docbook-xsl-1.64.0/html/chunk.xsl	# Gentoo DB HTML CHUNK
---
> HTML_XSL = $(PREFIX)/xsl-stylesheets-1.68.1/html/docbook.xsl	# Gentoo DB HTML
> HTML_CHUNK_XSL = $(PREFIX)/xsl-stylesheets-1.68.1/html/chunk.xsl	# Gentoo DB HTML CHUNK
Index: docs/edjebook/edjebook.xml
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/edjebook.xml,v
retrieving revision 1.1
diff -r1.1 edjebook.xml
2,3c2,3
< <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR1//EN"
<         "file:///usr/share/sgml/docbook/xml-dtd-4.3CR1/docbookx.dtd" [
---
> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
>         "file:///usr/share/sgml/docbook/xml-dtd-4.3/docbookx.dtd" [
Index: docs/edjebook/xml/edc_ref.xml
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/xml/edc_ref.xml,v
retrieving revision 1.8
diff -r1.8 edc_ref.xml
5a6,7
> <section>
> <title>General EDC Structure</title>
45a48,51
> </section>
> 
> <section id="appendix.reference.keywords">
> <title>Keywords</title>
642a649,650
> </section>
> 
Index: docs/edjebook/xml/edc_tour.xml
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/xml/edc_tour.xml,v
retrieving revision 1.5
diff -r1.5 edc_tour.xml
2c2
< <title>A quick tour of Edje EDC</title>
---
> <title>A quick tour of Edje <acronym>EDC</acronym></title>
5,17c5,28
< Whenever you design a graphical application you need to first determine
< what the application needs to do, and then you consider how it should look.
< When developing with Edje these two tasks are the separate activities they should
< be.  When determining how to design your interface, it's common to use GIMP
< as a layout tool,  this is particularly helpful for designing your interface with
< Edje as you can see exactly how each element is going to be positioned and relate
< to other parts of your interface, which is especially helpful when learning Edje.
< Next, it's time to actually build your real interface.  This starts by creating
< a file typically labeled with a .edc extension.  Once you've created your EDC,
< you will generate the EET that will be used by your application. This is done using <command>edje_cc</command>,
< the Edje Collection Compiler.  Edje_cc will pack your EDC plus all of the images
< your interface will need into one tight compact EET, and will even compress
< images if you specified compression in your EDC.  This generated EET will
---
> Whenever you design a graphical application you need to first determine what the application needs
> to do, and then you consider how it should look.
> Unlike many other interface systems, when developing with Edje these two tasks are separate activities, as they should
> be.  When determining how to design your interface it's common to use <application>The GIMP</application>
> as a layout tool.  This is particularly helpful for designing your interface with
> Edje as you can see exactly how each graphical element is going to be positioned and relate
> to other parts of your interface.
> </para>
> <para>
> After creating a rough layout in <application>The GIMP</application> or through other means, it's time to actually build your real Edje interface.  This starts by creating
> an EDC file (typically labeled with a .edc extension).  Once you've created your EDC,
> you will generate an <acronym>EET</acronym> file that will be used by your application. This is done using <command>edje_cc</command>,
> the Edje Collection Compiler.  <command>edje_cc</command> will pack your EDC plus all of the images
> your interface will need into one tight, compact EET.  The generated EET will have the extension <filename class="extension">.edj</filename>.
> <note>
>     <title><filename class="extension">.edj</filename> versus <filename class="extension">.eet</filename></title>
>     Previous versions of <command>edje_cc</command> used the extension
>     <filename class="extension">.eet</filename>.  While a
>     <filename class="extension">.edj</filename> is technically an EET file, an EET file can contain
>     data other than Edje definitions/data (it can contain just about anything, in fact). By using
>     a different extension the purpose of the file is a little less ambiguous.
> </note>
> <command>edje_cc</command> will also compress the images it stores if you specified compression in
> your EDC.  This generated EET will
20,23c31
< just that one file, the EET, and not your entire image structure, or a
< tarball/zip like nearly every other themeing platform on the planet.  EET's
< can be previewed using the <command>edje</command> command as a way to debug and sample
< interfaces.
---
> just that one EET file (the <filename class="extension">.edj</filename>) and not your entire image structure (or a tarball/zip like nearly every other theming platform on the planet).  Your interface <filename class="extension">.edj</filename> EET can then be graphically previewed, tested, and debugged using the <command>edje</command> command.
27c35
< Before starting off with Edje on your own, you should look at the examples in
---
> Before starting off with Edje on your own, you might want to look at the examples in
30,32c38,40
< Run that script and an EET will be generated.  The script simply runs <command>edje_cc</command> with the appropriate
< options to generate a valid EET.  You can then preview the interface  with the Edje command,
< <userinput>edje e_logo.eet test</userinput>.  You can look at the EDC in the <filename class='directory'>edje/data/src/</filename>
---
> Run that script and an <filename class="extension">.edj</filename> EET will be generated.  The script simply runs <command>edje_cc</command> with the appropriate
> options to generate a valid EET.  You can then preview the interface with the <command>edje</command> command,
> <userinput>edje e_logo.edj</userinput>.  You can look at the EDC in the <filename class='directory'>edje/data/src/</filename>
34c42
< is a wonderful reference, as its constantly updated to reflect all avalible options for EDCs.
---
> is a wonderful reference, as it is constantly updated to reflect all available options for EDCs.
39c47
< <title>Writting your first EDC</title>
---
> <title>Writing your first EDC</title>
42c50
< Lets look at a small and simple EDC so we can explore its layout and options.
---
> Let's look at a small and simple EDC so we can explore its layout and options.
44a53,262
> <example id="ch.edc_tour.ex.1">
> <title id="ch.edc_tour.ex.1.title">Basic RECT Edje EDC</title>
> <programlisting>
> /* Begin our collections */                      <co id="simple.comments" linkends="simple.comments-desc"/>
> collections {
>     group {
>         name: "simple";                          <co id="simple.directive" linkends="simple.directive-desc"/>
> 
>         parts {
>             part {
>                 name:   "background";
>                 type:   RECT;
> 
>                 description {
>                     state: "default" 0.0;
>                     color: 0 64 128 255;
> 
>                     // Positioning               <coref linkend="simple.comments"/>
>                     rel1 {
>                         relative: 0.0 0.0;
>                         offset: 0 0;
>                     }
>                     rel2 {
>                         relative: 1.0 1.0;
>                         offset: -1 -1;
>                     }
>                 }
>             }
>         } // end of parts
>     } // end of group
> } // end of collections
> </programlisting>
> <calloutlist>
>     <callout arearefs="simple.comments" id="simple.comment-desc">
>         <para>
>             Comments can be in both C (<code>/* ... */</code>) or C++ (<code>// ...</code>) 
>             format.
>         </para>
>     </callout>
>     <callout arearefs="simple.directive" id="simple.directive-desc">
>         <para>
>             This line contains a <emphasis>directive</emphasis>.  A directive is in the form:
>             <code>
>                 keyword: <parameter>arg1</parameter>
>                 <optional><parameter>arg2</parameter></optional> ...
>                 <optional><parameter>argn</parameter></optional>;
>             </code>.
>             Using a comma (<code>,</code>) rather than a colon (<code>:</code>) after the keyword
>             is also supported.
>         </para>
>     </callout>
> </calloutlist>
> </example>
> 
> <para>
> The first thing to notice is that the syntax is very C-like (some may also note that it also looks
> CSS-like).  Every section begins with the section name followed by a matched set of curly braces.
> Sections can contain subsections (<code>collections</code> contains <code>group</code>,
> <code>group</code> contains <code>parts</code> and so on). Sections also contain
> <emphasis>directives</emphasis> which describe various aspects about each section.
> </para>
> 
> <section>
> <title>Collections</title>
> <para>
> As stated earlier, <code>collections</code> is one of the three main sections of an EDC. The
> <code>collections</code> section contains one or more <code>group</code> sections.  Each
> <code>group</code> contains a complete interface.  In this way, you could, for instance, create two
> <code>group</code>s in your EDC, each having a complete interface which you could then use for 
> either different areas of your application's interface or different looks for your one interface, 
> all in one EET for easy distribution.
> </para>
> 
> <para>
> Each <code>group</code> is given a <code>name</code>, in this case <property>"simple"</property>.
> Any time you reference your EET in your application you will specify both the EET 
> <filename class="extension">.edj</filename> file name and the <code>group</code> to use by
> name so choose your <code>group</code> names descriptively.  The next two lines are the
> <code>min</code> and <code>max</code> size of our interface in pixels. The arguments to 
> <code>min</code> and <code>max</code> are the horizontal size followed by the vertical size.
> In this case, our interface has a minimum size of 100x100 and maximum of 1024x768. Both
> <code>min</code> and <code>max</code> are optional attributes. A <code>group</code> can contain two
> different subsections: <code>parts</code> and <code>programs</code>. Let's take a look at
> <code>parts</code> (we'll discuss <code>programs</code> later on).
> </para>
> 
> <section>
> <title>Parts</title>
> <para>
> The <code>parts</code> section contains definitions of individual pieces of your interface such as
> a text label, a rectangle, or an image. Each piece is described by its own <code>part</code>
> section. Each <code>part</code> has an individual name for reference by other areas of your EDC (as
> with <code>group</code> names, be sure to choose <code>part</code> names as descriptively as you
> can). Following the name we can define our <code>part</code> as one of the following types:
> <itemizedlist>
>     <listitem><code>IMAGE</code></listitem>
>     <listitem><code>RECT</code></listitem>
>     <listitem><code>TEXT</code></listitem>
>     <listitem><code>NONE</code></listitem>
> </itemizedlist>
> </para>
> 
> <section>
> <title>RECT parts</title>
> <para>
> Looking at our EDC example you can see that our first part is an <code>RECT</code> named 
> "background".  A <code>RECT</code> part is simply a solid color rectangle.
> </para>
> 
> <para>
> A <code>part</code> will contain one or more <code>description</code> sections.  Each
> <code>description</code> is a different <emphasis>state</emphasis> of our <code>part</code>.  The
> <code>description</code>s define how our <code>part</code> should look, what images or text the
> <code>part</code> uses, where it should be positioned, how it should be tiled, and a variety
> of other attributes. In this case our "background" <code>part</code> only needs one
> <emphasis>state</emphasis>, which we call "default" using a directive with the <code>state</code>
> keyword.  The number following the <code>state</code> name defines an index value which is
> currently unused (simply use 0.0).
> </para>
> 
> <para>
> Next, we see two sections defining the positioning of our <code>part</code>: <code>rel1</code> and
> <code>rel2</code>.  Both <code>rel</code> sections will at least contain the keywords
> <code>relative</code> and <code>offset</code> and optionally <code>to</code>.  If the
> <code>to</code> keyword is omitted then the position of the part is relative to the full, current
> size of the interface.  <code>rel1</code> is the positioning of the top left corner of the
> <code>part</code> and <code>rel2</code> is the positioning of the bottom right corner of the
> <code>part</code>.  The relative keyword is followed by two rational values ranging from 0.0 to
> 1.0.  As with <code>min</code> and <code>max</code>, the first value is the horizontal and the
> second is the vertical.  The offset specifies the pixel deviation from the relative point. In the
> case of our "background", the top left (<code>rel1</code>) of our <code>part</code> is relative to
> the top left corner of the interface with no offset.  The bottom right (<code>rel2</code>) of our
> <code>part</code> is relative to the bottom right of the interface and offset by 1 pixel left and 1
> pixel up.  Therefore, this <code>part</code> fills the entire interface.  More information about
> positioning can be found later in the <link endterm="ch.layout.title" linkend="ch.layout"/> 
> chapter.
> </para>
> 
> <para>
> While <emphasis>parts</emphasis> may seem confusing and complicated at first, hopefully you can now
> look at the part we just reviewed and simply say that it is an <code>RECT</code> <code>part</code>
> named "background" and fills the interface completely.
> </para>
> 
> <para>
> Let's go ahead and see what it looks like.  Create a file named <filename>simple1.edc</filename>
> and type the <link endterm="ch.edc_tour.ex.1.title" linkend="ch.edc_tour.ex.1"/> example EDC in.
> Compile it using the command: <command>edje_cc simple1.edc</command>. If compilation was successful
> there should now be a file named <filename>simple1.edj</filename> (if compilation failed, ensure
> that there are no typos and try again).  Now, take a look at it by running <command>edje</command>
> on it like this: <command>edje simple1.edj</command>.  You should see something like this:
> <graphic format="PNG" align="center" fileref="img/edje1.png"/>
> When <command>edje</command> first starts up, no collections are shown. To show our collection
> named "simple" click on the button labeled "simple" below "Collections: simple1.edc".  You 
> should now see something like this:
> <graphic format="PNG" align="center" fileref="img/edje2.png"/>
> You can resize the visualization of the collection by dragging the borders with your mouse. Notice
> how it will not let you make it smaller than 100x100 pixels. Remember, that is what we specified as
> the minimum size.  Try playing around with the values now (recompiling after every change).  Tinker
> with it until you have a good understanding of how the various values affect the <code>part</code>.
> </para>
> 
> <!-- MENTION COLORS BEFORE THIS -->
> 
> </section>
> 
> <section>
> <title>IMAGE parts</title>
> 
> <para>
> Our next part is a rectangle named button and it does accept mouse events.  This part has two descriptions, one
> for the default state and one for the clicked state.  The default state will define the normal look and positioning of the
> rectangle we will use as a button, or in other words, the unclicked state of our button.  The second state is the clicked
> state.  You'll notice that the default and clicked states look almost identical, the only change is the color and name.
> This means that when we change from state default to state clicked, the only thing that changes is the color of the rectangle.
> States are changed using programs, which we will discuss later.  You'll notice that the descriptions contain min and max keywords,
> these are used to define the size of the part.  If they are omitted, like in the background part, the part will fill the maximum
> amount of available space (i.e. the whole interface, as limited by rel1 and rel2).  The alignment keyword specifies alignment
> of our part within its available space (container).  Values for align are again horizontal alignment followed by vertical alignment,
> using doubles.  So in this case the rectangle will be an absolute 100x50 pixels, with a container the size of the whole interface
> (as defined by rel1/rel2), and is positioned in the middle of that container.  No matter how big or small the interface is the
> 100x50 pixel rectangle will always stay in exactly the middle of the screen and never resize.  The color keyword is applicable
> only to rectangles and text, and describes the color of the rectangle in the form: color, red green blue alpha.
> </para>
> 
> </section>
> 
> <para>
> The last part is a text part, named text.  It does not accept mouse events.  It has only one state, default.  Notice
> that the rel1 and rel2 sections use the to keyword, this modifies the meaning of the relativity.  This means that the top left
> corner (rel1) of the part is relative to the top left corner (0.0 0.0) of the part named button (to, "button";).  Likewise,
> the bottom right corner (rel2) of the part is relative to the bottom right corner (1.0 1.0) of the part named button, but moving
> the bottom right corner of the part by 1 pixel to the left and upwards from that point.  The text section  describes the text
> itself.  The text keyword describes the text to display ("Press Me"), the font to use ("redensek"), the size of that font (14), and
> the alignment of the text within the container as defined by rel1/rel2.  The font specified to be used must be added to
> the EVAS font path in your application, and the font name is the filename minus it's extension (ie: .ttf).
> </para>
> 
> <para>
> A word about layering.  There is no specific keyword for layering in EDCs on a part-by-part basis.  Each
> new part is layered on top of the previous part.  Therefore in our sample EDC the text is rendered on top of the button, which
> sits atop the background.  If we had defined the button before the background it would not have been visible.  While
> this is common sense for the most part, it can be a common cause of confusion when modifying a large EDC if you aren't
> careful.  Whenever you modify or add parts to your EDCs check whats above and below it.
> </para>
> 
> </section>
> 
> </section>
> 
195c413
< The first thing to notice is that the syntax is very C like.  The second is that EDCs have two major
---
>   The second is that EDCs have two major
200a419,425
> <!-- Discuss in images section in parts -->
> The last
> section in this parts description is the image section.  This section describes which images to use.  One or more images
> can be specified, the image that is first seen is denoted by the keyword normal.  More images can be added using the
> keyword "tween" to form animations, but we will discuss that in a later section.
> <!-- ********************************** -->
> 
202c427
< include in our interface.  Each image will have a line describing how to store it, in the form: image, "filename" STORAGE_METHOD;.
---
> include in our interface.  Each image will have a line describing how to store it, in the form: image: "filename" STORAGE_METHOD;.
205c430
< be uncompressed and stored as the raw image, thus your tidy 1K PNG may be stode as an 8K raw image.
---
> be uncompressed and stored as the raw image, thus your tidy 1K PNG may be stored as an 8K raw image.
211,245c436,439
< The next section is collections.  This section contains one or more groups.  Each group contains a complete interface.
< In this way, you could create two groups in your EDC each having a complete interfaces, for either diffrent parts of your
< applications interface or diffrent looks for your one interface, all in one EET for easy distribution.  Each group is given
< a name, in this case "test".  Any time you reference your EET you will specify both the EET file name, and the group to use so
< choose your name descriptively.  The next two lines are the min and max size of our interface in pixels.  The arguments to
< min and max are the horizontal size then the verital size.  So our interface has a minimum size of 32x32 and maximum of 1024x768.
< </para>
< 
< <para>
< Groups contain parts and programs.  Each part is a particular piece of your interface, such as a text label, or a rectangle,
< or an image.  Each part has an individual name for reference by other parts of your EDC, again choose this name as descriptively
< as you can.  Following the name we can define our part as one of the following types, IMAGE, RECT or TEXT.  Looking at our EDC
< example you can see that our first part is an image named "background".  The keyword "mouse_events" is a boolean value
< defining whether or not this part accepts mouse events (such as clicks, mouse overs, etc), 0 for no and 1 for yes.   More options
< than just these 3 can be used, please refer to the reference for other avalible options.
< </para>
< 
< <para>
< A part will contain one or more description sections.  Each description is a diffrent state of our part.  The descriptions
< define how our part should look, what images or text the part uses, where it should be positioned, how it should be tiled, etc.
< In this case our background only needs one state, which we call default, using the state keyword.  The number following
< the state name defines an index value which is currently unused, simply use 0.0.  Next we see two sections defining the
< positioning of our part, rel1 and rel2.  Each rel
< section will contain the keywords relative and offset, and optionally to.  If the to keyword is omited then the position
< is relative to the full size of the interface as described by min and max in the group section.  rel1 is the positioning of
< the top left corner of the part and rel2 is the positioning of the bottom right
< corner of the part.  The relative keyword is followed by two doubles ranging from 0.0 to 1.0.  As with min and max, the first
< value is the horizontal and the second is the vertical.  The offset specifies the pixel deviation from the relative point.
< In the case of our background, the top left (rel1) of our part (image) is relative to the top left corner of the interface, with no
< offset.  The bottom right (rel2) of our part is relative to the bottom right of the interface, offset by 1 pixel left and 1 pixel
< up.  Therefore, this part fills the entire interface.  More information about positioning can be found later in this guide.  The last
< section in this parts description is the image section.  This section describes which images to use.  One or more images
< can be specified, the image that is first seen is denoted by the keyword normal.  More images can be added using the
< keyword "tween" to form animations, but we will discuss that in a later section.
< </para>
---
> <!-- Mention in the new Programs chapter -->
>   The keyword "mouse_events" is a boolean value
> defining whether or not this part accepts mouse events (such as clicks, mouse overs, etc), 0 for no and 1 for yes.
> <!-- *********************************** -->
247,288d440
< <para>
< While parts may seem confusing and complicated at first, hopefully you now can look at the part we just reviewed and simply
< say that it's an image part named background that doesn't accept mouse events, and fills the interface completely using the
< image background.png.
< </para>
< 
< <para>
< Our next part is a rectangle named button and it does accept mouse events.  This part has two descriptions, one
< for the default state and one for the clicked state.  The default state will define the normal look and positioning of the
< rectangle we will use as a button, or in otherwords, the unclicked state of our button.  The second state is the clicked
< state.  You'll notice that the default and clicked states look almost identical, the only change is the color and name.
< This means that when we change from state default to state clicked, the only thing that changes is the color of the rectangle.
< States are changed using programs, which we will discuss later.  You'll notice that the descriptions contain min and max keywords,
< these are used to define the size of the part.  If they are omited, like in the background part, the part will fill the maximum
< amount of avalible space (ie: the whole interface, as limited by rel1 and rel2).  The alignment keyword specifies alignment
< of our part within its available space (container).  Values for align are again horizontal alignment followed by verital alignment,
< using doubles.  So in this case the rectangle will be an absolute 100x50 pixels, with a container the size of the whole interface
< (as defined by rel1/rel2), and is positioned in the middle of that container.  No matter how big or small the interface is the
< 100x50 pixel rectangle will always stay in exactly the middle of the screen and never resize.  The color keyword is applicable
< only to rectangles and text, and describes the color of the rectangle in the form: color, red green blue alpha.
< </para>
< 
< <para>
< The last part is a text part, named text.  It does not accept mouse events.  It has only one state, default.  Notice
< that the rel1 and rel2 sections use the to keyword, this modifies the meaning of the relativity.  This means that the top left
< corner (rel1) of the part is relative to the top left corner (0.0 0.0) of the part named button (to, "button";).  Likewise,
< the bottom right corner (rel2) of the part is relative to the bottom right corner (1.0 1.0) of the part named button, but moving
< the bottom right corner of the part by 1 pixel to the left and upwards from that point.  The text section  describes the text
< itself.  The text keyword describes the text to display ("Press Me"), the font to use ("redensek"), the size of that font (14), and
< the alignment of the text within the container as defined by rel1/rel2.  The font specified to be used must be added to
< the EVAS font path in your application, and the font name is the filename minus it's extention (ie: .ttf).
< </para>
< 
< <para>
< A word about layering.  There is no specific keyword for layering in EDCs on a part-by-part basis.  Each
< new part is layered on top of the previous part.  Therefore in our sample EDC the text is rendered on top of the button, which
< sits atop the background.  If we had defined the button before the background it would not have been visable.  While
< this is common sense for the mostpart, it can be a common cause of confusion when modifying a large EDC if you aren't
< careful.  Whenever you modify or add parts to your EDCs check whats above and below it.
< </para>
< 
< <para>
291c443
< interfaction, Edje itself, or an external force (usually your window manager).  For instance, a user generated signal would be
---
> interaction, Edje itself, or an external force (usually your window manager).  For instance, a user generated signal would be
301c453
< depressed over your part that accepts mouse events the program activates.  Signals are globable, meaning if we
---
> depressed over your part that accepts mouse events the program activates.  Signals are glob-able, meaning if we
304c456
< which defines the part (or program) from which the signal will be received, in this case button.  Sources are also  globable.
---
> which defines the part (or program) from which the signal will be received, in this case button.  Sources are also  glob-able.
312c464
< After's can also be used as a looping mechanism, by specifying the current program to re-run after it completes, however it
---
> Afters can also be used as a looping mechanism, by specifying the current program to re-run after it completes, however it
335,336c487,488
< In your application code this signal would be received by a callback handler, which would call a specified function based on the recipt of
< a specified signal from a specific source.  We'll learn more about these signals when we discuse the Edje API later.  The keyword
---
> In your application code this signal would be received by a callback handler, which would call a specified function based on the receipt of
> a specified signal from a specific source.  We'll learn more about these signals when we discuss the Edje API later.  The keyword
357c509
< a little until you think you are familar with the syntax, layout and basic functionality of Edje EDCs.
---
> a little until you think you are familiar with the syntax, layout and basic functionality of Edje EDCs.
360a513
> 
Index: docs/edjebook/xml/overview.xml
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/xml/overview.xml,v
retrieving revision 1.2
diff -r1.2 overview.xml
8c8
< Edje is a componant of the Enlightenment Foundation Libraries which abstracts
---
> Edje is a component of the Enlightenment Foundation Libraries which abstracts
10,16c10,16
< Edje is comprised of two componants, the code in the EVAS application which interacts with
< the interface, and a created EET which contains all the elements of the interface itself.
< These EET's are generated from an Edje EDC file in which diffrent parts of the interface
< are described and laid out, and how those parts interact with your application.  This
< allows for the interface to be completely changed simply by creating a new EDC and
< generating the EET for your application to use.  In more popular terms, Edje
< makes every application that uses it "skinable".  Raster describes Edje as "an attempt
---
> Edje is comprised of two components: the code in the EVAS based application which interacts
> with the interface and also an EET which contains all the elements of the interface
> itself. These EETs are generated from an Edje EDC file which defines how different parts of
> the interface are described and laid out as well as how those parts interact with your
> application. This allows for the interface to be completely changed simply by creating a 
> new EDC and generating the EET for your application to use.  In more popular terms, Edje
> makes every application that uses it "skinnable".  Raster describes Edje as "an attempt
27,37c27,28
< The Edje EDC contains every detail about your interface.  An EDC is
< a simple text file that uses C like syntax.  The file is broken into
< three distinct sections: images, data, and collections.  The image section contains
< a list of all the images your interface will use.  When you compile/generate your
< EDC into an EET all the images specified will be loaded into the EET itself allowing you
< to distribute your interface (or skin if you prefer) as a single file.  When
< specifying your images you can even specify the ammount  you want the images to
< be compressed when adding them into the EET to keep your EETs small and portable.
< The collections section actually describes the interface, how it's laid out and how it
< will interact with your application code. Optionally, a third section, data, can contain
< arbitrary data in key-value pairs to provide data to your application.
---
> The Edje EDC contains every detail about your interface.  An EDC is a simple text file that uses
> C-like syntax.  The file is broken into three distinct sections: images, collections, and data.  
39a31,43
> <section>
> <title>Images</title>
> <para>
> The <emphasis>image</emphasis> section contains a list of all the images your interface will
> use.  When you compile/generate your EDC into an EET all the images specified will be loaded into 
> the EET itself allowing you to distribute your interface (or skin if you prefer) as a single file.
> When specifying your images you can even specify the amount  you want the images to be compressed
> when adding them into the EET to keep your EETs small and portable.
> </para>
> </section>
> 
> <section>
> <title>Collections</title>
41,46c45,53
< The collections in an EDC are comprised of one or more groups.  Each group
< contains parts and programs.  A part is a single element of your interface, such
< as a text element, or a rectangle, or an image.  Each part is throughly described
< for one or more states.  For instance, an image part might actually have two images
< in it, each in a different state, one for a normal state and one for a clicked (mouse down)
< state.  A part may have as many states defined as you like.
---
> The <emphasis>collections</emphasis> section actually describes the interface, how it's laid out
> and how it will interact with your application code. A collection in an EDC is comprised of one or
> more <emphasis>groups</emphasis>.  Each group contains <emphasis>parts</emphasis> and
> <emphasis>programs</emphasis>.  A part is a single element of your interface, such as a text
> element, a rectangle, or an image.  Each part is thoroughly described for one or more
> <emphasis>states</emphasis>.  For instance, an image part might actually have two images in it,
> each in a different state. One for a normal state and one for a clicked (mouse down) state.  A part
> may have as many states defined as you like. Parts can then referenced in
> <emphasis>programs</emphasis>.
50,58c57,64
< These parts are then referenced in the programs.  Programs are descriptions about
< how the interface should respond to both the user and the application code itself.  A
< program can accept interface events (such as mouse button 1 down), and then change the state of
< a part described earlier (change to state clicked) to create an effect.  Programs
< can also emit signals to your application.  In your application code you would define
< a callback for that event.  Each program is concise and distinct.  For example, to
< create an animated button, you would create 3 programs, one to change the image state
< from normal to clicked on a mouse down event, one to emit a signal to your application on
< the mouse down event, and yet another to change state back to normal on a mouse up event.
---
> <emphasis>Programs</emphasis> are descriptions about how the interface should respond to both the
> user and the application code itself.  A program can accept interface events (such as mouse button
> 1 down) and then change the state of a part described previously (e.g. change to state clicked) to
> create an effect.  Programs can also emit signals to your application.  In your application code
> you would define a callback for that event.  Each program is concise and distinct.  For example, to
> create an animated button, you would create 3 programs: one to change the image state from normal
> to clicked on a mouse down event, one to emit a signal to your application on the mouse down event,
> and yet another to change state back to normal on a mouse up event.
59a66
> </section>
60a68,69
> <section>
> <title>Data</title>
62,69c71,73
< Because of the abstraction Edje provides, your applcation only needs to
< know the name of the EET to use, what signals it will receive from
< the interface so that callbacks can be defined when that event is received, and
< what text parts in the interface can be modified.   This allows maximum flexability in
< interface design, including the ability to offload the interface to graphic designers and
< themers freeing the application coders, allowing users of the application to modify the
< interface without hacking or forking your project, and a much quicker prototyping and design
< tool than modifying your C application directly.
---
> Optionally, a third section, data, can contain arbitrary data in key-value pairs to provide
> additional data to your application (e.g. a theme's name or other details the application could use
> while dealing with the theme).
70a75
> </section>
71a77,85
> <para>
> Because of the abstraction Edje provides, your application only needs to know the name of the EET
> to use, what signals it will receive from the interface so that callbacks can be defined when that
> event is received, and what text parts in the interface can be modified. This allows maximum
> flexibility in interface creation due to the ability to offload the interface design from
> application coders to graphic designers and themers. This also allows users of the application to
> modify the interface without hacking or forking your project and also provides a much quicker
> prototyping and design tool than modifying your C application directly.
> </para>
72a87
> 
Index: docs/edjebook/xml/positioning.xml
===================================================================
RCS file: /var/cvs/e/e17/docs/edjebook/xml/positioning.xml,v
retrieving revision 1.2
diff -r1.2 positioning.xml
1,2c1,2
< <chapter>
< <title>Edje Layout, Fills and Positioning</title>
---
> <chapter id="ch.layout">
> <title id="ch.layout.title">Edje Layout, Fills, and Positioning</title>