Echo Web Framework

Properties are set on Echo.Components and layoutData property values to define their visual appearance and behavior. The basic Echo properties consist of colors, fonts, borders, images, extents, and insets.

Immutable: Property objects should be treated as being immutable. Modifying the state of a property which is in use can have undesirable results. If a property is modified, the object conatining it, e.g., a Component will not notify interested parties of the change via events. If you need to alter a property, you should always create a new property instance containing the alteration.

Performance Considerations: Performance may be improved by storing properties as static constants rather than recreating them each time they are used. The use of style objects and StyleSheets (discussed in a later tutorial chapter) to store properties will yield further performance benefits.

Common Properties

This section takes a quick look at a few of the property objects commonly used to configure the visual appearance of Echo components.

Alignment

An alignment property is used to describe how objects should be aligned or positioned with respect to each other. Alignment properties are commonly used within layout data objects to control how child components are aligned inside their containers. Echo.Button and Echo.Label components use the property to describe how text should be positioned and aligned with respect to an icon.

A single alignment object can be used to represent either horizontal, vertical, or both horizontal and vertical alignment. An alignment property may be expressed in two different forms, either as a string or as an object.

If an alignment property only has a horizontal or vertical component, the property may be expressed as a string, for example:

button.set("textAlignment", "right");

If the property has both horizontal and vertical components, it is expressed as an object with "horizontal" and "vertical" properties set appropriately, for example:

button.set("textAlignment", {
    horizontal: "right",
    vertical: "middle"
});

Limitations: Some components that use alignment properties can only render the horizontal or vertical portion of the property. Other components will require that a particular alignment value never have settings for both horizontal and vertical values. You will need to refer to the API documentation of any particular component to determine the valid alignment settings.

The following table shows the available settings for alignment properties:

Border

A border property object describes a stylized border surrounding a region. Borders may have a specific style, size, and color. Border properties can be represented as strings using the same format as CSS borders, for example:

button.set("border", "2px groove #a1b2c3");

The order of border properties must be an extent, followed by a border style, followed by a color.

The style property of a border may be any of the following values:

The capability also exists to create a border with different appearances for each of its top, left, right, and bottom sides. Multi-sided borders are expressed as objects with top, right, bottom, and left properties, as illustrated in the following example:

button.set("border", { 
    top: "2px solid #123456", 
    bottom: "4px groove #abcdef",
    right: "2px solid #123456", 
    left: "4px groove #abcdef" });

Color

A color property object describes a 24 bit RGB color (8 bits per channel). Color properties are represented as strings in a similar fashion to W3C CSS. The string must start with a sharp ("#"), and be followed by six hexadecimal digits. The first two digits represent the hex value, 00-FF (0-255), of the red component of the color. The second and third sets of two digits similarly represent the green and blue components respectively.

The following table shows some example color properties:

Extent

An extent describes a dimension with specific units. Extents are used extensively by the built-in components in addition to other properties such as borders, insets, and fonts.

Extents may be expressed as integers or as strings. An integer extent refers to a pixel value. A string extent can specify units, e.g., "20pt", or "5cm". The following units may be used:

Unit Requirements: Some components will not support percentage-based extents. Refer to the API documentation for each component for specific information.

Fill Image

A "fill image" describes how a region should be filled with an image background. In addition to specifying the image to be used, fill image properties allow you to customize the position of a background image and its repetition.

Fill images may be represented as either objects or strings. The string form simply describes the URL of the image, e.g.:

button.set("backgroundImage", "images/Gradient.png");

The object form allows the positioning of the image as well as its repetition:

button.set("backgroundImage", { url: "images/Gradient.png", 
    repeat: "repeat-x", x: "50%", y: 20 });

The object form has the following properties:

Font

A font property object describes the typeface, size, and style of text. Fonts do not need to be specified on every component: if a text component does not have a specified font, it will be rendered using the font of its parent.

Fonts are represented as objects which may contain the following properties:

The following code shows an example of font property:

button.set("font", {
    typeface: ["Verdana", "Arial", "Helvetica", "sans-serif"],
    size: 15,
    bold: true,
    underline: true
});

Image

Image properties represent the URL and optionally the dimensions of an image. They can take the form of either strings or objects. A string form image is simply the HTTP URL from which the image may be retrieved, for example:

button.set("icon", "images/HelpIcon.png");

Object form images may specify the url, width, and height of the image as in the example which follows. The width and height are extent properties.

button.set("icon", { url: "images/HelpIcon.png", 
    width: 16, height: 16 });

Insets

An insets property is used to describe the inset margins of a region. Insets can individually specify dimensions for each margin if desired.

Insets may be represented as either integers or strings. An integer-based insets value will indicate a pixel value for the margins, and all will be the same size. String values take the form of between one and four extents, separated by spaces, for example:

button.set("insets", "5px 3em 2px");

The values are provided in the following order: top, right, bottom, left. This is identical to the order of padding/margin values used in CSS. If only one value is provided, it will be used for all margins. If only two values are provided, the first will be used for the vertical margins (top/bottom) and the second used for the horizontal margins (right/left). If only three values are provided, the first specifies the top margin, the second the horizontal margin, and the third the bottom margin.