How to use the Feathers
Toast class allows the display of in-app notifications as pop-ups over all other content. A toast may contain a string message and optional action buttons, or it can display completely custom content. The toast will close automatically after a timeout, but it may also be configured to remain open indefinitely.
We create a
Toast a bit differently than other components. Rather than calling a constructor, we call the static function, like
Let's see how this works by displaying some simple text in a
Toast when we touch a button. First, let's create the button:
Then, in the listener for the
Event.TRIGGERED event, we create the toast:
In addition to the string to display in the toast,
Toast.showMessage() accepts a second argument, the timeout when the toast will be closed automatically. This value is measured in seconds.
In the example above, the timeout will be closed in six and a half seconds. If we don't want the toast to close automatically, we can set the timeout to
Number.POSITIVE_INFINITY. We can close the toast manually by calling its
Message and actions
A toast may optionally include one or more action buttons by creating it with
Toast.showMessageWithActions(). In the following example, we display a toast with an Undo button:
Each item in the colllection may contain its own separate
Event.TRIGGERED listener, or you can listen for
Event.CLOSE on the
Toast instance. If one of the buttons was triggered, the event's data will contain an item from the collection.
A toast may be created without a message and actions and use completely custom content instead by calling
Toast.showContent(). In the following example, we display a toast that contains an
Any Starling display object or Feathers component may be used as the content. To include multiple items in the content, you may add them all to a parent
A number of styles may be customized on a toast, including the message font styles, the background skin, and layout properties. Additionally, a toast has a button group sub-component that may be styled. For full details about which properties are available, see the
Toast API reference. We'll look at a few of the most common ways of styling a toast below.
The font styles of the toast's message may be customized using the
Pass in a
starling.text.TextFormat object, which will work with any type of text renderer.
The font styles of the toast's action buttons may be customized through the toast's
ButtonGroup component. See How to use the Feathers
ButtonGroup component for details.
The background skin fills the full width and height of the toast. In the following example, we pass in a
starling.display.Image, but the skin may be any Starling display object:
It's as simple as setting the
Padding may be added around the edges of the toast. This padding is applied around the edges of the message text renderer, and is generally used to show a bit of the background as a border.
If all four padding values should be the same, you may use the
padding property to quickly set them all at once:
If the optional action buttons are displayed, you may use the
gap property to add some space between the message and the actions:
Skinning the action buttons
This section only explains how to access the button group sub-component. Please read How to use the Feathers
ButtonGroup component for full details about the skinning properties that are available on
With a Theme
If you're creating a theme, you can target the
Toast.DEFAULT_CHILD_STYLE_NAME_ACTIONS style name.
The styling function might look like this:
You can override the default style name to use a different one in your theme, if you prefer:
You can set the styling function for the
customActionsStyleName like this:
Without a Theme
If you are not using a theme, you can use
actionsFactory to provide skins for the toast's action buttons group:
Using a factory to skin a
Toast without a theme
If you're not using a theme, you can specify a factory to create the toast, including setting skins, in a couple of different ways. The first is to set the
Toast.toastFactory static property to a function that provides skins for the toast. This factory will be called any time that
Toast.showContent() is used to create a toast.
Another option is to pass a toast factory to
Toast.showMessage() or one of the other static methods to create a toast. This allows you to create a specific toast differently than the default global
Closing and Disposal
When manually closing the toast, you may call the
close() function and pass in
false for the
It's possible that the toast will close itself automatically. For instance, the
timeout property specifies the time, in seconds, that the toast will remain open.
By default, when the toast closes itself, it will also dispose itself. Set the
disposeOnSelfClose property to
false if you intend to reuse the toast. Simply pass it to
Toast.addToast() to reuse it.
Finally, you may want to reuse the toasts's content. By default, the toast will also dispose its content when it is disposed. Set the
disposeContent property to
false to allow your code to reuse the toast's content in another toast or elsewhere on the display list after the original toast is disposed.