ControlBars In Spark Panels Specification

Glossary

ControlBar - a group of controls placed above or below the main content area of a container. Toolbars and MenuBars are specific kinds of ControlBars
Chrome - non-content area for borders and titlebars in a container

Summary and Background

The Halo Panel supports having its last child be of a ControlBar class. It detects that case, removes the ControlBar child from the list of children and places the ControlBar at the bottom within the chrome of the Panel.

Spark Panel currently has no support for such a thing. The original plan was that users would re-skin the Panel and add controls in the skin, but feedback from beta users indicate that they would like to add controls to a controlbar without having to re-skin.

Usage Scenarios

Fido is creating a Panel that will have various widgets in it, but wants to have a row of controls at the bottom that dictate the size and font used to display the rest of the content and doesn't want that row of controls to be scrolled when the rest of the content scrolls. This could be done by placing a Scroller in the content and the row of controls below that, but that seems like a lot of work compared to the way it worked in Flex 3. In Flex 3, the markup might look like:

<mx:Panel>
	<mx:Button />
	<mx:TextArea />
	<mx:ControlBar >
		<mx:ComboBox dataProvider="{listOfFontSizes}" />
		<mx:ColorPicker />
	</mx:ControlBar>
</mx:Panel>

The markup for Flex 4 would require something more complex like this:

<s:Panel>
	<s:layout>
		<s:VerticalLayout />
	<s:layout>
	<s:Scroller>
                  <s:Group>
  		         <s:layout>
			         <s:VerticalLayout />
		         <s:layout>
		         <s:Button />
		         <s:TextArea />
                  </s:Group>
	</s:Scroller>
	<s:Group>
		<s:HGroup>
			<s:DropDownList dataProvider="{listOfFontSizes}" />
			<mx:ColorPicker />
		</s:HGroup>
		<s:Rect left="0" right="0" bottom="0" top="1" >
			<s:fill>
				<s:SolidColor color="0xE8E8E8" />
			</s:fill>
		</s:Rect>
	</s:Group>
</s:Panel>

That's more work than Fido would like to do, so he and many other users asked the Flex team to make it simpler. With the proposed changes, the markup will look like this:

<s:Panel>
	<s:Scroller>
                  <s:Group>
		         <s:layout>
			         <s:VerticalLayout />
		         <s:layout>
		         <s:Button />
		         <s:TextArea />
                  </s:Group>
	</s:Scroller>
	<s:controlBarContent>
		<s:DropDownList dataProvider="{listOfFontSizes}" />
		<mx:ColorPicker />
	</s:controlBarContent>
</s:Panel>

Detailed Description

The changes to put a controlbar in Panel (and Application) are:

1) Add two new states to PanelSkin and ApplicationSkin: "normalWithControlBar" and "disabledWithControlBar"
2) Add a controlBarGroup to PanelSkin that is only created in the "...withControlBar" states
3) Add other chrome behind and around the controlBarGroup so it appears as part of the chrome
4) Refactor the PanelSkin to use VerticalLayout to manage the variable height of the titlebar, contentGroup and controlBarGroup (and the same for Application, but without the titlebar)
5) Add a controlBarContent property that takes an array of controls similar to the mxmlContent property
6) Add a controlBarLayout property that is similar to the layout property
7) Add code that detects if the controlBarContent array is set and if so, switches the states to the "...withControlBar" states
8) Add code that then detects the existence of the controlBarGroup skin part and load the controlBarContent array as its content and assigns the controlBarLayout as the controlBarGroup's layout.
9) Add a controlBarVisible property to also control whether the ControlBar is visible

API Description

New APIs in both Panel and Application (WindowedApplication and Window are not supported)

    //----------------------------------
    //  controlBarGroup
    //---------------------------------- 
    
    [SkinPart(required="false")]

    /**
     *  The skin part that defines the appearance of the 
     *  control bar in the container.
     *
     *  @see spark.skins.spark.PanelSkin
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public var controlBarGroup:Group;

    //----------------------------------
    //  controlBarContent
    //---------------------------------- 
    
    [ArrayElementType("mx.core.IVisualElement")]
    
    /**
     *  The set of items that become the content of
     *  the controlBarGroup
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get controlBarContent():Array
    public function set controlBarContent(value:Array):void

    //----------------------------------
    //  controlBarLayout
    //---------------------------------- 
    /**
     *  An optional Layout assigned to the control bar.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get controlBarLayout():LayoutBase
    public function set controlBarLayout(value:LayoutBase):void

    //----------------------------------
    //  controlBarVisible
    //---------------------------------- 
    /**
     *  A flag that will control whether the controlBar is visible
     *  if it has content.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 1.5
     *  @productversion Flex 4
     */
    public function get controlBarVisible():Boolean
    public function set controlBarVisible(value:Boolean):void

B Features

None

Examples and Usage

In MXML:

<s:Panel>
	<!—content goes here ->
	<!—controls for the control bar go here ->
	<s:controlBarContent>
		<s:DropDownList dataProvider="{listOfFontSizes}" />
		<mx:ColorPicker />
	</s:controlBarContent>
	<!— (optional) alter the default layout of the controlbar ->
	<s:controlBarLayout>
		<s:HorizontalLayout gap="20" paddingTop="10" paddingBottom="10" />
	</s:controlBarLayout>
</s:Panel>

Additional Implementation Details

None

Prototype Work

Prototype complete

Compiler Work

None

Web Tier Compiler Impact

None

Flex Feature Dependencies

None

Backwards Compatibility

Syntax changes

None

Behavior

None

Warnings/Deprecation

None

Accessibility

None

Performance

The skins have more sub-groups and groups within those sub-groups to manage variable height of the titlebars and controlbars. That is a performance hit, but there are usually relatively few Applications and Panels in an application.