How to use the Panel component

The Panel class is a container that may display a header and a footer, and it can position its children using a layout. This type of container offers support for scrolling content that is too large to fit within its visible bounds. Scrolling is supported in a variety of ways — including touch and drag, mouse wheel and scroll bars, or by using a keyboard's arrow keys when the container has focus.

The Basics

Create a Panel component, add it to the display list, and add some children.

var panel = new Panel();
addChild(panel);

var child1 = new Label();
child1.text = "Hello";
panel.addChild(child1);

var child2 = new Sprite();
child2.graphics.beginFill(0xcccccc);
child2.graphics.drawRect(0.0, 0.0, 100.0, 100.0);
child2.graphics.endFill();
panel.addChild(child2);

A mix of OpenFL's core display objects and other Feathers UI components may be added to the panel.

Set the panel's layout property to automatically position its children.

panel.layout = new HorizontalLayout();

The example above uses HorizontalLayout, but a number of different layouts are available in Feathers UI, and it's also possible to create custom layouts.

A panel may optionally display a header, which will stretch along panel's the top edge. Like the panel's children, its header may be any of OpenFL's core display objects or a Feathers UI component.

In the following example, a LayoutGroup component is used as a panel's header.

var header = new LayoutGroup();
header.variant = LayoutGroup.VARIANT_TOOL_BAR;
header.layout = new AnchorLayout();

var title = new Label();
title.text = "Header";
title.variant = Label.VARIANT_HEADING;
title.layoutData = AnchorLayoutData.center();
header.addChild(title);

panel.header = header;

A panel may optionally display a footer, which will stretch along panel's the bottom edge. Like the panel's children, its footer may be any of OpenFL's core display objects or a Feathers UI component.

In the following example, a LayoutGroup component is used as a panel's footer.

var footer = new LayoutGroup();
footer.variant = LayoutGroup.VARIANT_TOOL_BAR;
footer.layout = new AnchorLayout();

var title = new Label();
title.text = "Footer";
title.variant = Label.VARIANT_HEADING;
title.layoutData = AnchorLayoutData.center();
footer.addChild(title);

panel.footer = footer;

Styles

A number of styles may be customized on a Panel component, including an optional background skin and the appearance of the panel's scroll bars.

Background skin

Optionally give the panel a background using the backgroundSkin property. The following example sets it to a RectangleSkin instance.

var skin = new RectangleSkin();
skin.border = SolidColor(1.0, 0x999999);
skin.fill = SolidColor(0xcccccc);
skin.width = 16.0;
skin.height = 16.0;
panel.backgroundSkin = skin;

The border and fill properties of the RectangleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.

The panel automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like header and footer, and the size and position of children), so it's important to set a skin's width and height properties to appropriate values to use in this calculation.

See Skinning with common shapes for more details about how to use RectangleSkin with the LineStyle and FillStyle enums that change its border and fill appearance.

The appearance of the panel's border or fill may be customized to change when the panel is disabled. In the next example, setting the skin's disabledFill method makes it switch to a different fill when the panel is disabled.

skin.disabledFill = SolidColor(0xffcccc);

Similarly, use the skin's disabledBorder property to change the border when disabled.

skin.disabledBorder = SolidColor(2.0, 0x999999);

In the examples above, the panel uses the same RectangleSkin for all states, and that skin listens for changes to the panel's current state. Alternatively, the panel's disabledBackgroundSkin method allows the panel to display a completely different display object when it is disabled.

var defaultSkin = new RectangleSkin();
// ... set border, fill, width, and height
panel.backgroundSkin = defaultSkin;

var disabledSkin = new RectangleSkin();
// ... set border, fill, width, and height
panel.disabledBackgroundSkin = disabledSkin;

In the example above, the panel will have a separate skins when enabled and disabled.

Scroll bars

The scroll bars in a Panel component are of type HScrollBar and VScrollBar. Their appearance may be customized globally in a theme, or they may be customized outside of a theme on an specific, individual panel.

See How to use the HScrollBar and VScrollBar components for complete details about which styles are available for the scroll bars.

Style scroll bars globally

Use the HScrollBar and VScrollBar classes in a theme to provide a function that globally styles all scroll bars in your project.

styleProvider.setStyleFunction(HScrollBar, null, setHScrollBarStyles);
styleProvider.setStyleFunction(VScrollBar, null, setVScrollBarStyles);

The functions should use the following signatures.

function setHScrollBarStyles(scrollBar:HScrollBar):Void {
    // ... set styles here
}

function setVScrollBarStyles(scrollBar:VScrollBar):Void {
    // ... set styles here
}

Style scroll bars in a specific Panel

The scrollBarXFactory and scrollBarYFactory properties may be used to customize the creation of an individual panel's scroll bars.

panel.scrollBarXFactory = () -> {
    var scrollBar = new HScrollBar();
    // ... set styles here
    return scrollBar;
};

panel.scrollBarYFactory = () -> {
    var scrollBar = new VScrollBar();
    // ... set styles here
    return scrollBar;
};