Feathers 3.0 Migration Guide (Starling version)

This guide explains how to migrate an application created with a previous version of Feathers to Feathers 3.0. Some APIs have been removed and others have been deprecated. New classes like ImageSkin make it easier to skin components while optimizing memory and performance.

• Starling 2

• Skinning Changes

  • Removal of Scale9Image, Scale3Image, and TiledImage

  • The new ImageSkin class

  • Setting font styles on text renderers

  • Removal of StandardIcons.listDrillDownAccessoryTexture

• saveMeasurements() replaces setSizeInternal()

• Return type API changes

• Multi-Resolution Development with Feathers

• Duplicate constants moved to shared classes

• Backwards compatibility with feathers-compat

• Appendix: List of Removed APIs

• Appendix: List of Deprecated APIs

• Appendix: Find and Replace Regular Expressions

Starling 2

Feathers 3.0 has upgraded to Starling 2. For complete details about Starling's changes, see the Starling 2 migration guide.

Skinning Changes

Removal of Scale9Image, Scale3Image, and TiledImage

Starling 2.0 now offers these features natively!

To replace Scale9Image, create an Image and set its scale9Grid property:

var image:Image = new Image( texture );
image.scale9Grid = new Rectangle( 2, 2, 3, 6 );
this.addChild( image );

To replace Scale3Image, create an Image and set its scale9Grid property. For horizontal scaling, set the grid's height to the full height of the texture. For vertical scaling, set the grid's width to the full width of the texture. In the following example, the Image can be scaled horizontally like the old Scale3Image:

var image:Image = new Image( texture );
image.scale9Grid = new Rectangle( 2, 0, 3, texture.frameHeight );
this.addChild( image );

To replace TiledImage, create an Image and set the tileGrid property to an empty Rectangle:

var image:Image = new Image( texture );
image.tileGrid = new Rectangle();
this.addChild( image );

The new ImageSkin class

feathers.skin.ImageSkin provides a more optimized way to skin Feathers components that have multiple states, such as Button and TextInput.

Previously, the easiest way to skin these components involved creating separate display objects for each state. For instance, a Button might have a default skin, a down skin, a hover skin, and a disabled skin. You would create four separate Image objects with four textures.

From an optimization perspective, it would be better to use a single Image and simply reuse it with all four textures. Previously, we could do that by using the stateToSkinFunction property, but it's wasn't very intuitive, so many developers preferred to use separate display objects for each state. The ImageSkin class takes advantage of new capabilities in Starling 2.0 to make using multiple textures easy.

Let's take a look at how a button can use ImageSkin:

var skin:ImageSkin = new ImageSkin( defaultTexture );
skin.setTextureForState( ButtonState.DOWN, downTexture );
skin.setTextureForState( ButtonState.DISABLED, disabledTexture );
skin.scale9Grid = SCALE_9_GRID;
button.defaultSkin = skin;

Each state can display a different texture, and the ImageSkin automatically detects when the button's state changes. If a texture isn't specified for the current state, the default texture will be used.

ImageSkin is a subclass of starling.display.Image, so all properties like scale9Grid and tileGrid are available too!

In addition to being used for background skins, ImageSkin can also be used for the icon on buttons, text inputs, and item renderers.

Setting font styles on text renderers

Text renderers in Feathers components can now change their own font styles when their parent component changes state. Previously, the Button class managed multiple sets of properties for different states (like defaultLabelProperties and downLabelProperties) using objects that were not strictly type-checked at compile-time. The new approach is stricter, and easier to customize outside of the theme:

button.labelFactory = function():ITextRenderer
{
	var textRenderer:BitmapFontTextRenderer = new BitmapFontTextRenderer();
	textRenderer.styleProvider = null; // avoid conflicts with the theme
	textRenderer.textFormat = new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0xffffff );
	return textRenderer;
};

In the code above, we create a BitmapFontTextRenderer and we use the textFormat property to set its font styles in the labelFactory of a Button.

On the BitmapFontTextRenderer, we can call the setTextFormatForState() function to pass in different font styles of each of the button's states. Let's do that in the same labelFactory:

textRenderer.setTextFormatForState( ButtonState.DOWN,
	new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0xffcc00 ) );

textRenderer.setTextFormatForState( ButtonState.DISABLED,
	new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0x999999 ) );

To display text with a different text renderer, the approach is mostly the same, but each text renderer has its own way to set font styles. To use a TextBlockTextRenderer, pass the default font styles to the elementFormat property. Call the setElementFormatForState() function to pass in font styles for different states.

If you prefer to keep all of your styling code in your theme, you can create a new style name for the text renderer class. On a Button, you'd pass this custom style name to the customLabelStyleName property:

button.customLabelStyleName = "my-custom-text-renderer";

In your theme, you'd add a new styling function for BitmapFontTextRenderer.

getStyleProviderForClass( BitmapFontTextRenderer )
	.setFunctionForStyleName( "my-custom-text-renderer", setCustomTextRendererStyles );

Just like above, we can set the default font styles, and styles for different states:

function setCustomTextRendererStyles( textRenderer: BitmapFontTextRenderer ):void
{
	textRenderer.textFormat = new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0xffffff );
	textRenderer.setElementFormatForState( ButtonState.DOWN,
		new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0xffcc00 ) );
	textRenderer.setElementFormatForState( ButtonState.DISABLED,
		new BitmapFontTextFormat( "My Font", BitmapFont.NATIVE_SIZE, 0x999999 ) );
}

Removal of StandardIcons.listDrillDownAccessoryTexture

This static property was previously used to return a special icon for item renderers inside accessorySourceFunction. In Feathers 3.0, you should add the DefaultListItemRenderer.ALTERNATE_STYLE_NAME_DRILL_DOWN constant to the item renderer's styleNameList instead. The theme will detect this style name, and it will pass a drill down icon to the item renderer.

DefaultGroupedListItemRenderer also defines a ALTERNATE_STYLE_NAME_DRILL_DOWN constant.

If some of the items in the list should not display a drill down icon, use the setItemRendererFactoryWithID() and factoryIDFunction to pass multiple item renderer factories to the List or GroupedList.

list.itemRendererFactory = function():IListItemRenderer
{
	var itemRenderer:DefaultListItemRenderer = new DefaultListItemRenderer();
	itemRenderer.styleNameList.add( DefaultListItemRenderer.ALTERNATE_STYLE_NAME_DRILL_DOWN );
	return itemRenderer;
};

If all items in the list should have a drill down icon, you may use customItemRendererStyleName instead:

list.customItemRendererStyleName = DefaultListItemRenderer.ALTERNATE_STYLE_NAME_DRILL_DOWN;

saveMeasurements() replaces setSizeInternal()

Custom component developers should migrate to the new saveMeasurements() as a replacement for setSizeInternal(), which is now considered deprecated.

In addition to the more intuitive name, saveMeasurements() now allows components to dynamically calculate minimum width and height:

this.saveMeasurements(newWidth, newHeight, newMinWidth, newMinHeight);

To maintain the previous behavior, you may pass a value of 0 for the minimum dimensions:

this.saveMeasurements(newWidth, newHeight, 0, 0);

You might also consider setting the minimum dimensions to the same as the regular dimensions:

this.saveMeasurements(newWidth, newHeight, newWidth, newHeight);

All of the core Feathers components now calculate minimum dimensions, if they are not set explicitly.

Return type API changes

The Drawers component now requires its content and drawers to be Feathers components. Previously, starling.display.Sprite was allowed. To replace Sprite as a generic container, consider using LayoutGroup instead.

The INativeFocusOwner interface now returns type Object for its nativeFocus property to allow objects like flash.text.StageText to receive focus. Previously, the return type was flash.display.InteractiveObject.

Multi-Resolution Development with Feathers

Feathers 3.0 fully embraces Starling's contentScaleFactor system described in Starling Multi-Resolution Development. Feathers even has some tricks up its sleeve to make it easy to scale to any mobile device's screen, while using its native aspect ratio.

ScreenDensityScaleFactorManager

The ScreenDensityScaleFactorManager class provides a convienent way to automatically calculate an appropriate contentScaleFactor value while maintaining the aspect ratio of any mobile device's screen. It uses a system inspired by Android that takes into account the screen density and the screen's resolution.

The following example shows how to use ScreenDensityScaleFactorManager by modifying the sample Startup Code from the Starling wiki.

public class Startup extends Sprite
{
	private var mStarling:Starling;
	private var mScaler:ScreenDensityScaleFactorManager;

	public function Startup()
	{
		mStarling = new Starling( Game, stage );
		mScaler = new ScreenDensityScaleFactorManager( mStarling );
		mStarling.start();
	}
}

You don't need to set the dimensions of Starling's view port, or the stageWidth and stageHeight properties of the Starling stage. ScreenDensityScaleFactorManager handles it all for you — even when the device's orientation changes.

ScreenDensityScaleFactorManager is considered optional, and if you'd prefer to manage the Starling view port and stage size manually using the techniques in Multi-Resolution Development, Feathers fully supports that approach too.

Changes to example themes

The example themes have been modified to allow Starling to automatically scale assets using contentScaleFactor. The textures in these themes now use a scale factor value of 2.

The themes no longer have scale variable that is calculated using the screen density. Pixel dimensions and font sizes are now the same for all scale factors.

If subclasses of example themes define scale9Grid rectangles, the values may need to be scaled down to continue working in Feathers 3.0. Previously, these themes defined textures with scale factor 1, and then scaled them up or down manually using the scale variable. Since the textures now use scale factor 2, the old scale9Grid values should be divided by 2. Note: If the original values in the scale9Grid are odd numbers, rounding up may work, but the skin may need to be widened by an extra pixel to get an even number width or height.

Duplicate constants moved to shared classes

In previous versions of Feathers, a number of constants were duplicated across many classes. For instance, you could find HORIZONTAL_ALIGN_LEFT on such classes as Button, DefaultListItemRenderer, HorizontalLayout, and TiledRowsLayout (and elsewhere too!). In Feathers 3.0, you can now use a shared HorizontalAlign.LEFT constant. Put another way, once you've used HorizontalAlign.LEFT constant with one class, you'll know exactly where to find when you need it in the future for any other class.

Other duplicate constants have been consolidated in the same way. The following classes with shared constants have been added to Feathers:

• feathers.controls.AutoSizeMode

• feathers.controls.ButtonState

• feathers.controls.DecelerationRate

• feathers.controls.ScrollBarDisplayMode

• feathers.controls.ScrollInteractionMode

• feathers.controls.ScrollPolicy

• feathers.controls.TextInputState

• feathers.layout.Direction

• feathers.layout.HorizontalAlign

• feathers.layout.RelativePosition

• feathers.layout.VerticalAlign

See Appendix: List of Deprecated APIs for details about which deprecated constants map to the new shared constants.

The original duplicate constants are considered deprecated. They will remain available in order to maintain backward compatibility for a short time. However, they will be removed at some point in the future.

In general, a deprecated API in Feathers will not be removed until six months have passed or two minor updates have been released (whichever takes longer). However, due to the impact of this change, the deprecated constants will not be removed until 18 months have passed or one major update has been released (again, whichever takes longer). This should give developers more time to migrate.

Additionally, take a look at Appendix: Find and Replace Regular Expressions to find a set of regular expressions to help automate the process of migrating to these new shared constants.

Backwards compatibility with feathers-compat

The feathers-compat project is a backwards compatibility library that is designed to make migration to Feathers 3.0 easier. It includes a number classes that were removed from Feathers 3.0. If you relied on these classes with earlier versions of Feathers, use feathers-compat to get your project up and running more quickly when upgrading to Starling 2.0 and Feathers 3.0. Then, you can take a little extra time to migrate your existing code.

For example, if you used SmartDisplayObjectValueSelector for skinning, you are strongly encouraged to switch to the new, more intuitive ImageSkin. However, you can add feathers-compat to your project, and you'll be able to continue using SmartDisplayObjectValueSelector and save the migration to ImageSkin for a later time.

Download feathers-compat from Github

Appendix: List of Removed APIs

The following table lists all removed APIs, organized alphabetically. The replacement API or migration instructions appear next to each listed API.

Appendix: List of Deprecated APIs

The following tables list all deprecated APIs, organized by class. The replacement API or migration instructions appear next to each listed property or method.

APIs that are deprecated have not been removed yet, but they will be removed at some point in the future. You are encouraged to migrate as soon as possible.

FeathersControl

Alert

No APIs are deprecated.

AutoComplete

No APIs are deprecated.

BaseDefaultItemRenderer

Button

ButtonGroup

Callout

Check

DateTimeSpinner

DefaultGroupedListItemRenderer

DefaultListItemRenderer

Drawers

GroupedList

Header

ImageLoader

Label

No APIs are deprecated.

LayoutGroup

List

NumericStepper

PageIndicator

Panel

PanelScreen

PickerList

No APIs are deprecated.

ProgressBar

Radio

Screen

ScreenNavigator

ScrollBar

ScrollContainer

ScrollScreen

ScrollText

SimpleScrollBar

Slider

SoundPlayer

No APIs are deprecated.

SpinnerList

No APIs are deprecated.

StackScreenNavigator

TabBar

TextArea

TextInput

ToggleButton

ToggleSwitch

WebView

No APIs are deprecated.

VideoPlayer

No APIs are deprecated.

FlowLayout

HorizontalLayout

HorizontalSpinnerLayout

TiledColumnsLayout

TiledRowsLayout

TimeLabel

VerticalLayout

VerticalSpinnerLayout

WaterfallLayout

Appendix: Find and Replace Regular Expressions

Many IDEs and text editors offer the ability to use regular expressions to Find and Replace text in a file. You may use the following regular expressions to accelerate the Feathers 3.0 migration process.

These regular expressions are provided for convenience only, and they may not work perfectly in all cases. After making replacements, be sure to double-check the modified code to verify that no unexpected errors were introduced.