CompassContainer

Overview

The CompassContainer class is a container with North, South, East, West, and center regions that content can be added to programmatically or via MXML. Because content is added to compass directions, the class is named the "CompassContainer".

Creating the CompassContainer Component

The CompassContainer extends the Flex SDK SkinnableComponent class and therefore can be added to any container that implements IVisualElementContainer.

Using the CompassContainer Component

By default, content added in MXML is added to the center region of the container. Only the center region is required. All other regions are optional. To add content to a different region via MXML, add the content to the respective property ("eastContent", "westContent", etc.).

For example (adding content to the center, North, and East regions):

<compassContainer:CompassContainer>
	
	<!--- center default property -->
	<s:Label text="Center Content" />
	
	<!--- north content -->
	<compassContainer:northContent>
		<s:VGroup>
			<s:Label text="North Content" />
			<s:Label text="North Content" />
			<s:Label text="North Content" />
		</s:VGroup>
	</compassContainer:northContent>
	
	<!--- east content -->
	<compassContainer:eastContent>
		<s:VGroup>
			<s:Label text="East Content" />
			<s:Label text="East Content" />
			<s:Label text="East Content" />
		</s:VGroup>
	</compassContainer:eastContent>
</compassContainer:CompassContainer>

To add content via Actionscript, you have 2 options: (A) create an array of IVisualElement implementing content and set it to the "eastContent", "northContent", etc., property; (B) retrieve the region instance directly and add content to it like any container.

For example, to add a label directly to the North region:

var cc:CompassContainer;
cc.northRegionInstance.addElement(new Label());

Note, when adding content directly to regions, check if the region exists before interacting with it. Regions are created on demand and do not exist until needed.

Add/Remove Regions

During runtime, to add a region to the compass container, call addRegion() and pass the compass direction requested and the region container will be returned.

To remove a region, call removeRegion() and pass the compass direction of the region to be removed.

Resizing Regions

Regions can be resized via dividers that are automatically created when regions are initialized. Users can resize by dragging the dividers. Regional min/max width/height will be respected.

To lock the dimensions of a region, use the "northResizeLocked", "westResizeLocked", etc., properties. When locked and the container's size changes, the center region will resize but the locked region's size will not change.

Use the styles to configure the gap between regions and the size of the divider. The gap and divider size do not need to be the same. For example, the gap between regions could be -1, so they overlap, but a divider width of -1 would mean a user could never hover over it, so in this case a divider width of greater than 0 would make sense.

Dividers use a custom skin.

Minimized Regions

Optional regions (E.G. all regions other than the "center") may also be configured to be minimized via a minimization icon in the region chrome. Once minimized they can be viewed by either restoring them by clicking the minimize icon again, or by floating the content above the container by clicking the minimize region.

To enable or disable whether users can minimize a region, see the "eastCanBeMinimized", "westCanBeMinimized", etc., properties. Note that the center region cannot be minimized.

Only relevant if the region displays its chrome.

Uses a custom skin.

Region Chrome

The region chrome is the border/background and the header part of each region. Even the center region has chrome, although the center region does not typically display a header. To show the regional chrome, use the "showNorthChrome", "showWestChrome", etc. properties.

If the chrome is not displayed, typically the minimize and close icons are not displayed and all of their related properties are irrelevant.

See the skins to configure the regional chrome.

Closing Regions

Optional regions (E.G. all the regions except the "center") can be closed by users clicking the close icon in the chrome if the respective "canBeClosed" property for the region is true. See the "westCanBeClosed", "northCanBeClosed", etc. properties.

Note, that regions can always be closed programmatically. Call the removeRegion() method to immediately remove a region.

Animations & Effects

When minimized content is floated out, a hard-wired Move effect is used with a duration of 150 milliseconds.

When regions are minimized or closed, a hard-wired Fade effect is played. You can set the duration of this effect via the "animationDuration" property.

You can change the default easer used by both animations use via the "easer" property.

Layout

All of the optional regions have explicit dimensions which can be set via the "eastWidth", "northHeight", etc. properties. Min and max dimensions for the optional regions can also be set via the "minEastWidth", "maxEastWidth", "minNorthHeight", "maxNorthHeight", etc. properties.

When the container resizes, the center region's dimensions will adjust to accommodate the explicit dimensions of the optional regions.

Notes on Performance

Regions are created as necessary, therefore the class is highly performant. Do not hesitate to use this class as a lightweight replacement for the Flex SDK DividedBox class, even for simple containers.

To increase performance further, set "showRegionChrome" to false for all regions and only create header elements on demand in the skin using the Flex Spark skinning architecture.

Accessibility & Focus

Regions support focus.

The minimize and close icons can be focused by tabbing to them, and clicked via the spacebar key.

Default Property

"centerContent" is the default property in MXML.

Colors and Border

The background color of each region is set via the "northBackgroundColor", "centerBackgroundColor", etc. styles. The border for each region is also set via styles. The gap color can also be set via styles. See the ASDocs.

Selected Custom Events

REGION_INITIALIZED
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a region is initialized and added to the CompassContainer.

DIVIDER_PRESS
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a "divider" is moused down.

DIVIDER_DRAG
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a "divider" is dragged.

DIVIDER_RELEASE
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a "divider" is moused up or released.

REGION_CLOSE
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a region is closed.

REGION_MINIMIZE_CHANGE
ardisia.components.compassContainer.events.CompassContainerEvent
Dispatched when a region's minimization state changes.

Selected Custom Styles

gap
default 6
The gap between regions.

If the divider width/height styles is not explicitly set, the divider buttons will be sized to the same dimensions as the gap.

dividerWidth
dividerWidth NaN
Width of the divider button for vertical dividers. If NaN, will be set to the width of the gap.

gap
dividerHeight NaN
Height of the divider button for horizontal dividers. If NaN, will be set to the height of the gap.

Themes & Skinning

Skins are provided for the Spark, Stockholm, and London themes.

Example

See the CompassContainer demo application for example code.

Back To Top