Using Layout

The following document describes what Layout utility is and isn't and outlines strategies for using and extending its functionality.

• Purpose and Introduction
• LayoutManager and the Core Types
• Strategies for Implementation

Purpose and Introduction

Unlike the components provided as part of our Astra Flash or Astra Flex libraries, the Layout utility isn't designed to be used as a component you can easily drop into any project. The purpose of the Layout utility is to provide a generic foundation for adding layout containers to a set of UI controls. To better understand what this means, consider the following:

• If you're looking for some ready-made components to automatically position and size display objects in Flash CS3, check out the HBoxPane, VBoxPane, TilePane, FlowPane, and BorderPane containers included with the Astra components for Flash.

• If you're building a set of UI controls from scratch, and you want to create some layout containers that are compatible with your controls, consider looking at the Astra Layout Utility to provide a simple framework for managing some of the low-level infrastructure.

Seeing as the Layout utility is an abstract framework rather than a concrete component, much of the discussion below will focus on coding to interfaces and OOP.

LayoutManager and the Core Types

The Layout utility offers a LayoutManager class that mediates communication between layout containers and their children. When a display object fires an event that may affect the layout, the LayoutManager captures that event and informs the container that it should refresh the layout. You can easily specify which events should be captured from instances of specific classes so that any component may be used in the layout system.

ILayoutContainer offers methods and events that allow LayoutManager to communicate with your container through a simple invalidation/validation scheme. The implementation of this invalidation system is left to the component author so that it may conform to the component set's own paradigms. The default implementation, LayoutContainer, uses the most common method of hooking into the enterFrame event to save validation until the next frame.

The ILayoutMode interface provides a way to create layout algorithms that may be used by implementations of ILayoutContainer. Several algorithms are included, including BoxLayout, FlowLayout, TileLayout, and BorderLayout. Designed for use with any DisplayObject, these simple implementations provide a minimum level of commonly used functionality. For more advanced needs, consider them an excellent starting point for expansion.

Developers are encouraged to implement and extend the provided interfaces to create custom implementations when the desired layout system must work a bit differently. That's why they exist! The core framework is very light and simple, with only these three required types: LayoutManager, ILayoutContainer, and ILayoutMode. The rest of the classes included with the Layout utility can be stripped out if they don't meet your needs.

Strategies for Implementation

The default implementations of ILayoutMode are focused on being compatible with the DisplayObject type. However, a layout algorithm may need extra configuration properties for certain children that aren't available on DisplayObject and cannot be added dynamically. There are two approaches to passing these configuration parameters to the algorithm:

1. Create a custom display object class that has properties for these special values. One should either require that the container (or layout mode) only accepts children of this type (similar to how Flex containers only allow mx.core.UIComponent), or use some default values when children of any other display object type are encountered.

   Some advantages to this approach are that it encourages strong typing and integrates easily with code hinting in IDEs. One disadvantage is that it can strongly couple the layout algorithm with the required display object type.

2. The IAdvancedLayoutMode interface included with the Layout utility allows developers to specify additional parameters for a specific child through its addClient() method. As an example, the BoxLayout class allows you to optionally specify percentWidth and percentHeight properties for individual children.

   Advantages include maximum flexibility to allow any display object and infinite extendability of the dynamically-typed configuration objects. Disadvantages include potential confusion over how to determine which extra properties are available either through poor documentation or lack of code hinting.

In the Constraint Layout example included with the Layout utility examples, we create a custom algorithm ConstraintLayout that allows you to constrain a display object to the edges of its parent container. This class relies on a subclass of Sprite, named ConstraintClient, which defines four extra properties used by the custom layout algorithm (top, right, bottom, and left).

Note: A border has been added around the SWF above to illustrate the constraints. Resizing the browser doesn't cause the constraints to update, contrary to what the message above says. View the example as presented in the Layout utility examples page for the proper effect!

By default, the ConstraintLayout implementation of ILayoutMode requires that you make all children be of type ConstraintClient so that the required properties used by the algorithm are available. If the wrong child type is used, a runtime error is thrown to inform the developer that the layout mode isn't being used correctly.

var child:ConstraintClient = target.getChildAt(i) as ConstraintClient; //ensure that the child is a ConstraintClient. if(!child) { throw new Error("ConstraintLayout requires that all children of target be of type ConstraintClient. Child " + target.getChildAt(i) + " is not compatible."); }

However, some extra code is included and commented out. In the case where a child of the container is not a ConstraintClient, the layout algorithm will ignore that child and skip to the next one.

var child:ConstraintClient = target.getChildAt(i) as ConstraintClient; //skip children that are not of type ConstraintClient. if(!child) { continue; }

Comment out the line that throws the error and uncomment the continue keyword to switch to the other behavior. If you add a non-ConstraintClient child to the container, it will be ignored and the size and position of the child will not be altered.

Next Steps

For additional information, please take a look at the Layout Examples section with several functional demonstrations. The ActionScript Class Reference for the Astra Utilities library contains full details on every property, method, and style available to the Layout utility classes.

Be sure to take a look at the Layout Containers in the Astra library of Flash components. Component authors will be especially interested because these containers use the Layout utility internally. As a reference implementation, these containers offer a good starting point for building containers for any other ActionScript component set.