How to use the Feathers PickerList
component
The PickerList
class displays a Button
that may be triggered to show a pop-up List
. The way that the list is displayed may be customized for different platforms by changing the picker list's pop-up content manager. Several different options are available, including drop downs, callouts, and simply filling the stage vertically.
The Basics
First, let's create a PickerList
control and add it to the display list:
var list:PickerList = new PickerList();
this.addChild( list );
Next, we want to actually allow it to select some items, so like a List
components, we pass in a ListCollection
to the dataProvider
property.
var groceryList:ListCollection = new ListCollection(
[
{ text: "Milk" },
{ text: "Eggs" },
{ text: "Bread" },
{ text: "Chicken" },
]);
list.dataProvider = groceryList;
We need to tell the picker list's item renderers about the text to display, so we'll define the labelField
.
list.listProperties.@itemRendererProperties.labelField = "text";
Since the selected item's label is also displayed by the picker list's button, we also need to pass a value to the labelField
of the picker list.
list.labelField = "text";
We can provide some text to display with the button's label when no item is selected. This is often called a hint, a description, or a prompt
:
list.prompt = "Select an Item";
list.selectedIndex = -1;
We need to set the selectedIndex
to -1
if you want to display the prompt because the picker list will automatically select the first item.
Skinning a PickerList
The skins for a PickerList
control are divided into several parts, including the button and pop-up list sub-components. For full details about what skin and style properties are available, see the PickerList
API reference.
Targeting a PickerList
in a theme
If you are creating a theme, you can set a function for the default styles like this:
getStyleProviderForClass( PickerList ).defaultStyleFunction = setPickerListStyles;
If you want to customize a specific picker list to look different than the default, you may use a custom style name to call a different function:
list.styleNameList.add( "custom-picker-list" );
You can set the function for the custom style name like this:
getStyleProviderForClass( PickerList )
.setFunctionForStyleName( "custom-picker-list", setCustomPickerListStyles );
Trying to change the picker list's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the picker list was added to the stage and initialized. Learn to extend an existing theme to add custom skins.
If you aren't using a theme, then you may set any of the picker list's properties directly.
Skinning the Button
Please read How to use the Feathers Button
component for full details about how to skin this component.
With a Theme
If you're creating a theme, you can target the PickerList.DEFAULT_CHILD_STYLE_NAME_BUTTON
style name:
getStyleProviderForClass( Button )
.setFunctionForStyleName( PickerList.DEFAULT_CHILD_STYLE_NAME_BUTTON, setPickerListButtonStyles );
You can override the default style name to use a different one in your theme, if you prefer:
list.customButtonStyleName = "custom-button-name";
You can set the function for the customButtonStyleName
like this:
getStyleProviderForClass( Button )
.setFunctionForStyleName( "custom-button-name", setPickerListCustomButtonStyles );
Without a Theme
If you are not using a theme, you can use buttonFactory
to provide skins for the picker list's button:
list.buttonFactory = function():Button
{
var button:Button = new Button();
button.defaultSkin = new Scale9Image( upTextures );
button.downSkin = new Scale9Image( downTextures );
button.hoverSkin = new Scale9Image( hoverTextures );
return button;
};
Alternatively, or in addition to the buttonFactory
, you may use the buttonProperties
to pass skins to the button:
list.buttonProperties.defaultSkin = new Scale9Image( upTextures );
list.buttonProperties.downSkin = new Scale9Image( downTextures );
list.buttonProperties.hoverSkin = new Scale9Image( hoverTextures );
In general, you should only skins to the picker list's button through buttonProperties
if you need to change skins after the button is created. Using buttonFactory
will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.
Skinning the List
Please read How to use the Feathers List
component for full details about how to skin this component.
With a Theme
If you're creating a theme, you can target the PickerList.DEFAULT_CHILD_STYLE_NAME_LIST
style name:
getStyleProviderForClass( List )
.setFunctionForStyleName( PickerList.DEFAULT_CHILD_STYLE_NAME_LIST, setPickerListListStyles );
You can override the default style name to use a different one in your theme, if you prefer:
list.customListStyleName = "custom-list";
You can set the function for the customListStyleName
like this:
getStyleProviderForClass( List )
.setFunctionForStyleName( "custom-list", setPickerListCustomListStyles );
Without a Theme
If you are not using a theme, you can use listFactory
to provide skins for the picker list's pop-up list:
list.listFactory = function():List
{
var list:List = new List();
list.backgroundSkin = new Scale9Image( backgroundSkinTextures );
return list;
};
Alternatively, or in addition to the listFactory
, you may use the listProperties
to pass skins to the list.
list.listProperties.backgroundSkin = new Scale9Image( backgroundSkinTextures );
In general, you should only skins to the picker list's list through listProperties
if you need to change skins after the list is created. Using listFactory
will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.
Customizing the Pop Up Behavior
Next, we'll take a look at how to use the popUpContentManager
property to customize how the pop-up list appears when you trigger the picker list's button.
Feathers comes with three pop-up content managers:
VerticalCenteredPopUpContentManager
provides a pop-up UI similar to Android. The list fills the entire vertical space of the screen. The list fills enough space horizontally to fit within the shorter edge of the screen, even when the device is in the landscape orientation. Along all edges, padding around the edges of the list may be customized.CalloutPopUpContentManager
places the list into aCallout
component. The callout points to the picker list's button.DropDownPopUpContentManager
displays the list as a drop down along the edge of the picker list's button. This is similar to a drop down list in a desktop UI.
Selecting the pop up content manager, is as simple as instantiating it and passing it to the picker list:
list.popUpContentManager = new DropDownPopUpContentManager();
You may customize properties of the pop up content manager first, if needed:
var popUpContentManager:VerticalCenteredPopUpContentManager = new VerticalCenteredPopUpContentManager();
popUpContentManager.marginTop = 20;
popUpContentManager.marginRight = 25;
popUpContentManager.marginBottom = 20;
popUpContentManager.marginLeft = 25;
list.popUpContentManager = popUpContentManager;
You can completely customize the pop-up behavior of the picker list by implementing the IPopUpContentManager
interface.