Anatomy of a Feathers user interface component
The following properties and methods are core parts of FeathersControl
and all component developers should be intimately familiar with them. Please be sure to read Feathers Component Lifecycle for additional, related information.
The Constructor
Any code appearing within the constructor should be kept to a minimum. In general, most initialization code should appear within initialize()
instead.
initialize()
The initialize()
method is called the first time that the component is added to the display list. It will only be called once in the component's lifetime. You may override this method to create children and handle other tasks that should be run when the component is first initialized.
invalidate()
The invalidate()
method should be called to tell the component that a property has changed and that it needs to redraw itself. Typically, this method is called within a setter function. It takes one or more flags as arguments to inform the component what has changed. The component may use these flags to focus on redrawing only a subset of itself if some parts are able to remain the same.
draw()
The draw()
method is called immediately before the component is rendered by Starling. You should override it to commit property changes, calculate an ideal size, and layout children.
Please read Component Validation with draw() for more detailed information about the draw()
method.
isInvalid()
The isInvalid()
method is used to determine if a specific flag has been set with invalidate()
. Call this in draw()
to determine which parts of the component need to be redrawn. If you call it with no arguments, the result will be true
if invalidate()
has been called regardless of which flags have been passed in.
setSizeInternal()
The setSizeInternal()
method is called to specify ideal dimensions. It chooses between explicit and ideal dimensions to calculate the final "actual" dimensions used for layout.
The final argument determines if the component should invalidate after adjusting the dimensions. If you call it during validation (during draw()
, basically), then you should probably pass false
. Otherwise, the component will end up redrawing itself every render cycle, which you probably don't want.
See below for more detailed information on component dimensions.
isQuickHitAreaEnabled
The isQuickHitAreaEnabled
property is similar to mouseChildren
from the classic display list. However, it takes things a step further and limits the component's hit area to a simple rectangle, which can greatly improve performance of touch hit tests. The rectangular hit area is automatically calculated based on the component's "actual" width and height dimensions (see below). This is most useful in buttons, but any component where the children don't need to receive touch events can benefit from it.
styleName and styleNameList
A component's styleNameList
is used by Feathers themes to provide separate skins to different types of the same component. It is most often used by components that have child components that need to be skinned, such as a Slider
has track and a thumb sub-components that are buttons.
For more information about component style names, please read Introduction to Feathers Themes.
width and height
FeathersControl
provides a number of useful width and height values. Understanding the differences among them is important for maximizing performance and getting the most out Feathers' capabilities.
The width
and height
getters and setters expose the component's dimensions externally. The values returned by the getters are determined based on a number of factors. They may be explicit dimensions passed to the setters or they may be ideal dimensions calculated automatically because no explicit dimensions were specified.
The explicitWidth
and explicitHeight
variables are changed if the width
and height
setters are called with numeric values. In the following example, a Button
control is created, and its width
property is set to 150
pixels. Internally, the button will store this value in the explicitWidth
variable.
var button:Button = new Button();
button.width = 150;
The actualWidth
and actualHeight
variables are the values returned by the width
and height
getters. These values should also be used when drawing the component. The "actual" dimensions typically default to the values of explicitWidth
and explicitHeight
, but if explicit dimensions are not specified, the component may try to calculate ideal dimensions. These could be hard-coded pixel values or they could be determined based on the dimensions of skins or other children (such as sub-components). How the ideal dimensions are calculated is often different from component to component.
A custom component should pass its ideal calculated dimensions to the setSizeInternal()
method before the layout phase. This method will determine if the dimensions were already set explicitly. If so, the ideal values will be ignored, and the actualWidth
and actualHeight
variables will be set to the explicit dimensions. If not, they will be set to the ideal dimensions instead.
If explicit dimensions have been set, and you want to use the component's ideal dimensions instead, pass NaN
to the width
and height
setters.
The minWidth
and minHeight
properties are used by setSizeInternal()
to adjust the ideal dimensions to a minimum value. minWidth
and minHeight
do not affect explicit dimensions in any way.