Echo Web Framework

Properties are set on Components and LayoutData objects to define their visual appearance and behavior.

Mutable Properties: Most property objects are immutable, i.e., they cannot be altered once they have been instantiated. Some property objects however are too complex to be defined wholly by a single call to a constructor, and must instead provide configurability after instantiation. Once a property has been configured, you should always treat it as being immutable. Modifying the state of a property that is in use by an application will most likely have undesirable results.

Saving Memory: Performance may be improved by storing properties as static constants rather than recreating them each time they are used. The use of Styles and StyleSheets (discussed in a later tutorial chapter) to store properties will yield further memory saving 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. Please visit the API documentation links for a full treatment on each property.

Alignment

The Alignment property is used to describe how objects should be aligned or positioned with respect to each other. The property is commonly used in LayoutData implementations to control how child Components are aligned within a container. Button and 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 both horizontal and vertical alignment. A value of Alignment.DEFAULT for either the horizontal or vertical portion indicates that a given Alignment does not effect how alignment should be handled along that axis.

Limitations: Some Components that use Alignment objects can only render the horizontal or vertical portion of an Alignment property. Other Components will require that a particular Alignment property never have non-default settings for both horizontal and vertical values. You will need to refer to the API documentation of any particular Component to determine the valid settings for its Alignment properties.

API Reference: Visit the Alignment API Documentation for more information.

Border

The Border property object describes a stylized border surrounding a region. A Border may have a specific style, size, and color. The following border styles are available:

API Reference: Visit the Border API Documentation for more information.

Color

The Color property object describes an RGB color. Arbitrary colors may be specified by constructing a new Color object with a specific RGB value. The Color class itself provides constants for a few common colors:

API Reference: Visit the Color API Documentation for more information.

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.

Unit Requirements: Some units cannot be used in certain environments. You will want to refer to the API documentation for each Extent property of a Component to determine which units are valid. Failure to do so may result in an exception being thrown at render-time. A significant number of Components will require Extent values to be in pixels.

API Reference: Visit the Extent API Documentation for more information.

FillImage

A FillImage describes how a region should be filled with an image background. The use of FillImage properties allows you to customize the position of a background image as well as its repetition.

API Reference: Visit the FillImage API Documentation for more information.

Font

The 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.

API Reference: Visit the Font API Documentation for more information.

Insets

An Insets property is used to describe the inset margins of a region. An Insets object contains four Extents, representing each of the top, bottom, left, and right margins.

API Reference: Visit the Insets API Documentation for more information.

ImageReferences

An ImageReference is used to represent a graphical image. The ImageReference object itself is an interface, with four implementations provided to suit various methods of image retrieval.

ResourceImageReference

A ResourceImageReference represents an image which may be retrieved via the ClassLoader. Placing images directly within the CLASSPATH and accessing them via ResourceImageReferences is generally the most sensible method of handling images within an Echo application.

API Reference: Visit the ResourceImageReference API Documentation for more information.

HttpImageReference

An HttpImageReference represents an image that may be retrieved via an HTTP request. Use HttpImageReferences in situations where you have images located on a different server from the application. For images that will be served by the Java-based web application server, HttpImageReferences provide no performance benefit over ResourceImageReferences.

API Reference: Visit the HttpImageReference API Documentation for more information.

StreamImageReference

StreamImageReference is an abstract class which allows an application to provide an image as raw binary data for display. This image type can be useful when images are retrieved from a database or filesystem.

API Reference: Visit the StreamImageReference API Documentation for more information.

AwtImageReference

AwtImageReferences provide the capability to render java.awt.Image objects to an Echo application's clients. The image will first be converted into a PNG before rendering. The use of AwtImageReferences will require an available graphics context, which may be of particular concern in Unix/Linux environments. The typical cure for the graphics context issue is to run the hosting JVM in headless mode.

Performance Warning: AwtImageReferences will require a significant expenditure of memory and processor cycles to render. The performance hit is not noticeable if they are used infrequently.

API Reference: Visit the AwtImageReference API Documentation for more information.