TimebarContainer

Overview

The TimebarContainer component allows users to display and select time periods with custom time intervals.

Creating the TimebarContainer Component

The TimebarContainer extends the Flex SDK SkinnableContainer class and thus can be added to any container that implements IVisualElementContainer.

Using the TimebarContainer Component

The TimebarContainer works by first defining a series of "intervalModes" that will determine what time intervals can be displayed. Each item renderer displays a "IntervalMode". The most specific interval will be displayed. For example, if the minimum visible duration is 1 week, then a time interval of 1 year will obviously not fit, but an interval of 1 day might. See the ASDocs for the ardisia.components.timebarContainer.dataTypes.IntervalMode class.

Next, define the start and end time via the "periodBegin" and "periodEnd" properties and the minimum displayed period via the "minimumVisibleDuration". Users can scroll and change the time period that is visible or it can be set directly or retrieved via the "visiblePeriodBegin" and "visiblePeriodEnd" properties.

Child content can be added generally, exactly the same as a SkinnableContainer. Often times, a simple chart makes sense.

Adding a Custom Interval Mode

Each interval mode is defined by an IntervalMode object and sets how many years, months, days, hours, minutes, and seconds are in the interval mode.

The time span is additive for IntervalMode objects. In other words, if the "years" value is 1 and the "months" value is 6, each renderer would span 1 year and 6 months.

Also, supply a name for each IntervalMode object to pass to the item renderers to provide them with some information as to how to display the date information. For example, if displaying a single day per renderer, set the "name" property on the IntervalMode object to "day" and then on the renderer detect that the mode is "day" and parse Date objects with the names of the days of the week.

See the item renderer classes for further explanation of how to create custom time intervals.

Below is a list of interval modes defined in the demo application:

<fx:Array id="intervalsExample">
	<dataTypes:IntervalMode name="millennium" years="1000" />
	<dataTypes:IntervalMode name="halfMillenium" years="500" />
	<dataTypes:IntervalMode name="century" years="100" />
	<dataTypes:IntervalMode name="halfCentury" years="50" />
	<dataTypes:IntervalMode name="quarterCentury" years="25" />
	<dataTypes:IntervalMode name="decade" years="10" />
	<dataTypes:IntervalMode name="halfDecade" years="5" />
	<dataTypes:IntervalMode name="year" years="1" />
	<dataTypes:IntervalMode name="halfYear" months="6" />
	<dataTypes:IntervalMode name="quarter" months="3" />
	<dataTypes:IntervalMode name="month" months="1" />
	<dataTypes:IntervalMode name="week" days="7" />
	<dataTypes:IntervalMode name="day" days="1" />
	<dataTypes:IntervalMode name="hours" hours="1" />
	<dataTypes:IntervalMode name="thirtyMinutes" minutes="30" />
	<dataTypes:IntervalMode name="tenMinutes" minutes="10" />
	<dataTypes:IntervalMode name="minutes" minutes="1" />
	<dataTypes:IntervalMode name="thirtySeconds" seconds="30" />
	<dataTypes:IntervalMode name="fifteenSeconds" seconds="15" />
	<dataTypes:IntervalMode name="seconds" seconds="1" />
</fx:Array>

Item Renderers

There are two sets of interval item renderers: the header interval renderers that sit at the top of the TimebarContainer and the generalized item renderers. The header item renderers display longer time intervals and sit above the general item renderers. The item renderer factories are defined in the skin as "headerItemRendererFactoryPart" and the "itemRendererFactoryPart" skin parts.

Both sets of the renderers implement ardisia.components.timebarContainer.interfaces.ITimebarContainerItemRenderer and can be further customized to display new interval modes. See the code for the TimebarContainerItemRendererBase to understand how the process of adding modes works. It is rather easy to understand when looking at the code directly. Subclass the ardisia.components.timebarContainer.themes.baseClasses.TimebarContainerItemRendererBase when creating custom time interval item renderers.

The selection lasso is created by a skin part factory "selectionLassoFactoryPart" and will only create a single item renderer. It must implement ardisia.components.timebarContainer.interfaces.ITimebarContainerSelectionLasso.

Selected Time Periods

Users can select time periods if the "selectionEnabled" property is true, and the selected time period can be set explicitly or retrieved via the "selectionPeriodBegin" and "selectionPeriodEnd" properties.

Users can also drag the selected time period. Use the "autoScrollThreshold" property to set how close to the horizontal boundaries of the viewport the user must drag before the TimebarContainer will automatically scroll.

Zooming In and Out

Users can zoom in and out by using the resize buttons on the left and right of the horizontal scroll bar or via the mouse wheel. For the mouse wheel, control the amount of zoom via the "zoomFactor" property.

Animations & Effects

When a selected time lasso drag ends, it will animate into the snapped time interval. This animation is hard wired and cannot be customized without subclassing.

Layout

Layout is completely handled in the host component without the need for a layout class.

Vertical Overflow

If the child content overflows the TimebarContainer's viewport, dynamic vertical scrollbars will be added automatically. See the "vScrollBarFactoryPart" skin part to change the vertical scrollbar factory.

Considerations

The contentGroup can have a massive width. So if a display object will be extremely wide, remember to increase its "maxWidth" property.

Also, remember that bitmaps have width restrictions under older Flash VMs.

You can overwhelm the component if the number of time intervals grows too large. For example, displaying every second for a hundred years will crash the VM.

Default Property

Child content, like a Flex SDK SkinnableContainer.

Selected Custom Events

VISIBLE_PERIOD_CHANGE
ardisia.components.timebarContainer.events.TimebarContainerEvent
Dispatched when the visible period changes.

SELECTED_PERIOD_CHANGE
ardisia.components.timebarContainer.events.TimebarContainerEvent
Dispatched when the selected period changes.

Selected Custom Styles

borderVisible
default true
True to display a border.

borderColor
default defaults.css
The color of the border.

borderAlpha
default 1
The alpha of the border.

paddingTop
default 60
Padding from the top for the contentGroup.

paddingBottom
default 0
Padding from the bottom for the contentGroup.

Themes & Skinning

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

Example

See the TimebarContainer demo application for example code.

Back To Top