Edje Data Collection reference

An Edje Data Collection, it's a plain text file (normally identified with the .edc extension),consisting of instructions for the Edje Compiler.

The syntax for the edje data collection files follows a simple structure of "blocks { .. }" that can contain "properties: ..", more blocks, or both.

Author:: Andres Blanc (dresb) andresblanc@gmail.com

images

        images {
            image: "filename1.ext" COMP;
            image: "filename2.ext" LOSSY 99;
            ..
        }

The "images" block is used to list each image file that will be used in the theme along with its compression method (if any). Besides the domcument's root, additional "images" blocks can be included inside other blocks, normally "collections", "group" and "part", easing mantienance of the file list when the theme is split among multiple files.

`image`	`[image file] [compression method] (compression level)`
	Used to include each image file. The full path to the directory holding the images can be defined later with edje_cc's "-id" option. Compression methods: RAW: Uncompressed. COMP: Lossless compression. LOSSY [0-100]: Lossy comression with quality from 0 to 100.

fonts

        fonts {
            font: "filename1.ext" "fontname";
            font: "filename2.ext" "otherfontname";
            ..
        }

The "fonts" block is used to list each font file with an alias used later in the theme. As with the "images" block, additional "fonts" blocks can be included inside other blocks.

`font`	`[font filename] [font alias]`
	Defines each font "file" and "alias", the full path to the directory holding the font files can be defined with edje_cc's "-fd" option.

data

        data {
            item: "arbitraryname" "arbitraryvalue";
            item: "othername" "othervalue";
            ..
        }

The "data" block is used to pass arbitrary parameters from the theme to the application. Unlike the "images" and "fonts" blocks, additional "data" blocks can only be included inside the "group" block.

`item`	`[parameter name] [parameter value]`
	Defines each additional parameter.

data

        data {
            file: "arbitraryname" "filename";
            file: "othername" "otherfilename";
            ..
        }

`file`	`[parameter name] [parameter filename]`
	Defines each additional parameter.

color_classes

        color_classes {
            color_class {
                name:  "colorclassname";
                color:  [0-255] [0-255] [0-255] [0-255];
                color2: [0-255] [0-255] [0-255] [0-255];
                color3: [0-255] [0-255] [0-255] [0-255]
            }
            ..
        }

The "color_classes" block contains a list of one or more "color_class" blocks. Each "color_class" allows the designer to name an arbitrary group of colors to be used in the theme, the application can use that name to alter the color values at runtime.

`name`	`[color class name]`
	Sets the name for the color class, used as reference by both the theme and the application.

`color`	`[red] [green] [blue] [alpha]`
	The main color.

`color2`	`[red] [green] [blue] [alpha]`
	Used as shadow in text and textblock parts.

`color3`	`[red] [green] [blue] [alpha]`
	Used as outline in text and textblock parts.

spectra

        spectra {
            spectrum {
                name: "colorspectrumname";
                color: [0-255] [0-255] [0-255] [0-255] [0-?]
                color: [0-255] [0-255] [0-255] [0-255] [0-?]
                ..
            }
            ..
        }

The "spectra" block contains a list of one or more "spectrum" blocks. Each "spectrum" block defines a color range used to fill GRADIENT parts. The colors are defined with the red, green, blue, alpha, delta format.

`name`	`[spectrum name]`
	The name of the spectrum used as reference later in the theme.

`color`	`[red] [green] [blue] [alpha] [delta]`
	Each color declaration represents a stop point in the color range. The last parameter (delta) is used to set the proportion of a given stop point higher or lower in contrast with the other color's delta value.

styles

        styles {
            style {
                name: "stylename";
                base: "..default style properties..";

                tag:  "tagname" "..style properties..";
                ..
            }
            ..
        }

The "styles" block contains a list of one or more "style" blocks. A "style" block is used to create style <tags> for advanced TEXTBLOCK formatting.

`name`	`[style name]`
	The name of the style to be used as reference later in the theme.

`base`	`[style properties string]`
	The default style properties that will be applied to the complete text.

`tag`	`[tag name] [style properties string]`
	Style to be applied only to text between style <tags>..</tags>.

collections

        collections {
            ..
            group { }
            group { }
            ..
        }

The "collections" block is used to list the groups that compose the theme. Additional "collections" blocks do not prevent overriding group names.

group

        collections {
            ..
            group {
                name: "nameusedbytheapplication";
                alias: "anothername";
                min: width height;
                max: width height;

                data { }
                script { }
                parts { }
                programs { }
            }
            ..
        }

A "group" block contains the list of parts and programs that compose a given Edje Object.

`name`	`[group name]`
	The name that will be used by the application to load the resulting Edje object, must be unique within the theme.

`alias`	`[aditional group name]`
	Additional name to serve as identifier. Defining multiple aliases is supported.

`min`	`[width] [height]`
	The minimum size for the container defined by the composition of the parts.

`max`	`[width] [height]`
	The maximum size for the container defined by the totality of the parts.

script

        ..
        group {
            script {
                //embryo script
            }
            ..
            program {
                script {
                    //embryo script
                }
            }
            ..
        }
        ..

This block is used to "inject" embryo scripts to a given Edje theme and it functions in two modalities. When it's included inside a "program" block, the script will be executed every time the program is run, on the other hand, when included directly into a "group", "part" or "description" block, it will be executed once at load time, in the load order.

part

        group {
            parts {
                ..
                part {
                    name: "partname";
                    type: IMAGE;
                    mouse_events:  1;
                    repeat_events: 0;
                    clip_to: "anotherpart";
                    source:  "groupname";
                    pointer_mode: AUTOGRAB;
                    use_alternate_font_metrics: 0;

                    description { }
                    dragable { }
                }
                ..
            }
        }

Parts are used to represent the most basic design elements of the theme, for example, a part can represent a line in a border or a label on a button.

`name`	`[part name]`
	The part's name will be used as reference in the theme's relative positioning system, by programs and in some cases by the application. It must be unique within the group.

`type`	`[TYPE]`
	Set the type (all caps) from among the available types, it's set to IMAGE by default. Valid types: RECT TEXT IMAGE SWALLOW TEXTBLOCK GRADIENT GROUP

`mouse_events`	`[1 or 0]`
	Specifies whether the part will emit signals, altought is named "mouse_events", disabling it (0) will prevent the part from emitting any type of signal at all. Its set to 1 by default.

`repeat_events`	`[1 or 0]`
	Specifies whether a part echoes a mouse event to other parts below the pointer (1), or not (0). Its set to 0 by default.

`pointer_mode`	`[MODE]`
	Sets the mouse pointer behavior for a given part. The default value is AUTOGRAB. Aviable modes: AUTOGRAB, when the part is clicked and the button remains pressed, the part will be the source of all future mouse signals emitted, even outside the object, until the button is released. NOGRAB, the effect will be limited to the part's container. container.

`precise_is_inside`	`[1 or 0]`
	Enables precise point collision detection for the part, which is more resource intensive. Disabled by default.

`use_alternate_font_metrics`	`[1 or 0]`
	Only affects text and textblock parts, when enabled Edje will use different size measurement functions. Disabled by default. (note from the author: I don't know what this is exactlu useful for?)

`clip_to`	`[another part's name]`
	Only renders the area of part that coincides with another part's container. Overflowing content will not be displayed.

`source`	`[another group's name]`
	Only available to GROUP parts. Swallows the specified group into the part's container.

`effect`	`[EFFECT]`
	Causes Edje to draw the selected effect among: PLAIN OUTLINE SOFT_OUTLINE SHADOW SOFT_SHADOW OUTLINE_SHADOW OUTLINE_SOFT_SHADOW FAR_SHADOW FAR_SOFT_SHADOW GLOW

dragable

        part {
            ..
            dragable {
                confine: "anotherpart";
                events: "anotherdragablepart";
                x: 0 0 0;
                y: 0 0 0;
            }
            ..
        }

This block is used to set the properties for parts that will be dragged around the interface (not external drag & drop).

x [enable/disable] [step] [count]

Used to setup dragging events for the X axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis, in the first case, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and will limit movement to values divisibles by it, causing the part to jump from position to position. The third parameter, (question from the author: What is count for?).

y [enable/disable] [step] [count]

Used to setup dragging events for the Y axis. The first parameter is used to enable (1 or -1) and disable (0) dragging along the axis, in the first case, 1 sets the starting point at 0.0 and -1 at 1.0. The second parameter takes any integer and will limit movement to values divisibles by it, causing the part to jump from position to position. The third parame, (question from the author: What is count for?).

`confine`	`[another part's name]`
	When set, limits the movement of the dragged part to another part's container. Since the size of dragable object will be setup by the application, the "min" property of "description" should be an accesible size.

`events`	`[another dragable part's name]`
	It causes the part to forward the drag events to another part, thus ignoring them for itself.

description

        description {
            inherit: "another_description" INDEX;
            state: "description_name" INDEX;
            visible: 1;
            min: 0 0;
            max: -1 -1;
            align: 0.5 0.5;
            fixed: 0 0;
            step: 0 0;
            aspect: 1 1;

            rel1 {
                ..
            }

            rel2 {
                ..
            }
        }

Every part can have one or more description blocks. Each description is used to define style and layout properties of a part in a given "state".

`inherit`	`[another description's name] [another description's index]`
	When set, the description will inherit all the properties from the named description. The properties defined in this part will override the inherited properties, reducing the amount of necessary code for simple state changes. Note: inheritance in Edje is single level only.

`state`	`[a name for the description] [an index]`
	Sets a name used to identify a description inside a given part. Multiple descriptions are used to declare different states of the same part, like "clicked" or "invisible". All states declarations are also coupled with an index number between 0.0 and 1.0. All parts must have at least one description named "default 0.0".

`visible`	`[0 or 1]`
	Takes a boolean value specifying whether part is visible (1) or not (0). Non-visible parts do not emit signals. The default value is 1.

`align`	`[X axis] [Y axis]`
	When the displayed object's size is smaller than its container, this property moves it relatively along both axis inside its container. The default value is "0.5 0.5".

`fixed`	`[width, 0 or 1] [height, 0 or 1]`
	When the "min" or "max" properties are set, fixed enables or disables resizing for each dimension. The default value is "0 0"

`min`	`[width] [height]`
	The minimum size of the state.

`max`	`[width] [height]`
	The maximum size of the state.

`step`	`[width] [height]`
	Restricts resizing of each dimension to values divisibles by its value. This causes the part to jump from value to value while resizing. The default value is "0 0" disabling stepping.

`aspect`	`[min] [max]`
	Normally width and height can be resized to any values independently. The aspect property forces the width to height ratio to be kept between the minimum and maximum set. For example, "1.0 1.0" will increase the width a pixel for every pixel added to heigh. The default value is "0.0 0.0" disabling aspect.

`aspect_preference`	`[DIMENSION]`
	Sets the scope of the "aspect" property to a given dimension. Available options are BOTH, VERTICAL, HORIZONTAL and NONE

`color_class`	`[color class name]`
	The part will use the color values of the named color_class, these values can be overrided by the "color", "color2" and "color3" properties set below.

`color`	`[red] [green] [blue] [alpha]`
	Sets the main color to the specified values (between 0 and 255).

`color2`	`[red] [green] [blue] [alpha]`
	Sets the text shadow color to the specified values (0 to 255).

`color3`	`[red] [green] [blue] [alpha]`
	Sets the text outline color to the specified values (0 to 255).

rel1/rel2

        description {
            ..
            rel1 {
                relative: 0.0 0.0;
                offset:     0   0;
            }
            ..
            rel2 {
                relative: 1.0 1.0;
                offset:    -1  -1;
            }
            ..
        }

The rel1 and rel2 blocks are used to define the position of each corner of the part's container. With rel1 being the left-up corner and rel2 being the right-down corner.

`relative`	`[X axis] [Y axis]`
	Moves a corner to a relative position inside the container of the relative "to" part. Values from 0.0 (0%, begining) to 1.0 (100%, end) of each axis.

`offset`	`[X axis] [Y axis]`
	Affects the corner postion a fixed number of pixels along each axis.

`to`	`[another part's name]`
	Causes a corner to be positioned relatively to another part's container.

`to_x`	`[another part's name]`
	Causes a corner to be positioned relatively to the X axis of another part's container. Simply put affects the first parameter of "relative".

`to_y`	`[another part's name]`
	Causes a corner to be positioned relatively to the Y axis of another part's container. Simply put, affects the second parameter of "relative".

image

        description {
            ..
            image {
                normal: "filename.ext";
                tween:  "filename2.ext";
                ..
                tween:  "filenameN.ext";
                border:  left right top bottom;
                middle:  0-1;
            }
            ..
        }

`normal`	`[image's filename]`
	Name of image to be used as previously declared in the images block. In an animation, this is the first and last image displayed. It's required in any image part

`tween`	`[image's filename]`
	Name of an image to be used in an animation loop, an image block can have none, one or multiple tween declarations. Images are displayed in the order they are listed.

`border`	`[left] [right] [top] [bottom]`
	If set, the area (in pixels) of each side of the image will be displayed as a fixed size border, from the side -> inwards, preventing the corners from being changed on a resize.

`middle`	`[0 or 1]`
	If border is set, this boolean value tells Edje if the rest of the image (not covered by the defined border) will be displayed or not. The default value is 1.

fill

        description {
            ..
            fill {
                smooth: 0-1;
                origin {
                    relative: X-axis Y-axis;
                    offset:   X-axis Y-axis;
                }
                size {
                    relative: width  height;
                    offset:   width  height;
                }
            }
            ..
        }

The fill method is an optional block that defines the way an IMAGE or GRADIENT part is going to be displayed inside its container.

`smooth`	`[0 or 1]`
	The smooth property takes a boolean value to decide if the image will be smoothed on scaling (1) or not (0). The default value is 1.

`spread`	`TODO`
	TODO

`angle`	`TODO`
	TODO

`type`	`TODO`
	TODO

origin

        description {
            ..
            fill {
                ..
                origin {
                    relative: 0.0 0.0;
                    offset:   0   0;
                }
                ..
            }
            ..
        }

The origin block is used to place the starting point, inside the displayed element, that will be used to render the tile. By default, the origin is set at the element's left-up corner.

`relative`	`[X axis] [Y axis]`
	Sets the starting point relatively to displayed element's content.

`offset`	`[X axis] [Y axis]`
	Affects the starting point a fixed number of pixels along each axis.

size

        description {
            ..
            fill {
                ..
                size {
                    relative: 1.0 1.0;
                    offset:  -1  -1;
                }
                ..
            }
            ..
        }

The size block defines the tile size of the content that will be displayed.

`relative`	`[width] [height]`
	Takes a pair of decimal values that represent the a percentual value of the original size of the element. For example, "0.5 0.5" represents half the size, while "2.0 2.0" represents the double. The default value is "1.0 1.0".

`offset`	`[X axis] [Y axis]`
	Affects the size of the tile a fixed number of pixels along each axis.

text

        part {
            description {
                ..
                text {
                    text:        "some string of text to display";
                    font:        "font_name";
                    size:         SIZE;
                    text_class:  "class_name";
                    fit:          horizontal vertical;
                    min:          horizontal vertical;
                    max:          horizontal vertical;
                    align:        X-axis     Y-axis;
                    source:      "part_name";
                    text_source: "text_part_name";
                    elipsis:      0.0-1.0;
                    style:       "stylename";
                }
                ..
            }
        }

`text`	`[a string of text, or nothing]`
	Sets the default content of a text part, normally the application is the one changing its value.

`text_class`	`[text class name]`
	Similar to color_class, this is the name used by the application to alter the font family and size at runtime.

`font`	`[font alias]`
	This sets the font family to one of the aliases set up in the "fonts" block. Can be overrided by the application.

`style`	`[the style name]`
	Causes the part to use the default style and tags defined in the "style" block with the specified name.

`size`	`[font size in points (pt)]`
	Sets the default font size for the text part. Can be overrided by the application.

`fit`	`[horizontal] [vertical]`
	When any of the parameters is set to 1 edje will resize the text for it to fit in it's container. Both are disabled by default.

`min`	`[horizontal] [vertical]`
	When any of the parameters is enabled (1) it forces the minimum size of the container to be equal to the minimum size of the text. The default value is "0 0".

`max`	`[horizontal] [vertical]`
	When any of the parameters is enabled (1) it forces the maximum size of the container to be equal to the maximum size of the text. The default value is "0 0".

`align`	`[horizontal] [vertical]`
	Change the position of the point of balance inside the container. The default value is 0.5 0.5.

`source`	`[another TEXT part's name]`
	Causes the part to use the text properties (like font and size) of another part and update them as they change.

`text_source`	`[another TEXT part's name]`
	Causes the part to display the text content of another part and update them as they change.

`text_elipsis`	`[point of balance]`
	Used to balance the text in a relative point from 0.0 to 1.0, this point is the last section of the string to be cut out in case of a resize that is smaller than the text itself. The default value is 0.0.