< Jewel Components list

Jewel Button


Available since version 0.9.4.

Class Extends
org.apache.royale.jewel.Button org.apache.royale.jewel.supportClasses.button.SimpleButton

Note: This component is currently only available for JavaScript.


The Jewel Button is a commonly-used rectangular button with a text label. Users can click or tap it to take an action or make a choice.

The Jewel Button can have different looks and feels. By default it appears with light or dark highlights depending on the Jewel theme configuration. You can use the emphasis property to tint the button with PRIMARY, SECONDARY or EMPHASIZED colors (defined in the Jewel theme).

When a user interacts with the button (mouse over, long-press, double-click…) the button calls an event listener that can perform an action. When a user clicks the mouse on the button or taps the button on a touch screen, the button dispatches a click event.

If you don’t need a custom label on your button consider using Jewel’s SimpleButton, located in the Jewel supportClasses package, since it is more lightweight and will save you some bytes if it fits your use case.

Example of use

In MXML declare a Button with a default look like this:

<j:Button text="Button"/>

In ActionScript we can do the same in the following way:

var button:Button = new Button();
button.text = "Button";

where parent is the container where the control will be added.

Here is an example of the default button:

code here

Relevant Properties and Methods

Check the Reference of org.apache.royale.jewel.Button for a more detailed list of properties and methods.


PROPERTY Type Description
text String The text that appears on the button.
html String The html text that appears on the button.
emphasis String Applies an emphasis color. Possible constant values are: PRIMARY, SECONDARY, EMPHASIZED. Colors are defined in the Royale Jewel theme CSS. If you don’t select a value for this field, you get the default look (light or dark).



Relevant Events

The Button component has many events like rollOver, rollOut, mouseDown, mouseUp, mouseMove, mouseOut, mouseOver, and mouseWheel, all of which are of the type org.apache.royale.events.MouseEvent. The most important event is click, which usually triggers some action coded in a callback function.

You can attach callback listeners to the click event in MXML as follows:

<j:Button text="Button" click="clickHandler(event)"/>

the click event will use the clickHandler callback function you provide in ActionScript:

        private function clickHandler(event:MouseEvent):void {
            trace("Hello from a Button!");

When the user clicks the button, the message “Hello from a Button!” appears in the console log.

In ActionScript we can add an event handler this way:

var b:Button = new Button();
b.text = "Button";
b.addEventListener('click', clickHandler);

Relevant Beads

Unlike other components in Royale, the Jewel Button does not have beads for View, Controller or Model in the JavaScript platform.

On the other hand, you can add to it other common Jewel control beads to provide more functionality. Many Jewel controls share these beads.

Common Beads

Bead Type Implementation Description
Disabled org.apache.royale.core.IBead This bead lets you disable and enable a Jewel control.
MultiLine org.apache.royale.core.IBead The bead can be used with any IClassSelectorListSupport control to allow more than one line of text.
SizeControl org.apache.royale.core.IBead Add this bead to give the Jewel control a custom size.
ToolTip org.apache.royale.core.IBead Add this bead to enable floating a text string over the control when the user hovers the mouse cursor over it.
Badge org.apache.royale.core.IBead Add this bead to provide small status descriptors for the control

More examples

Other useful Jewel button components are: