< Jewel Components list

Jewel Button

Reference

Available since version 0.9.4.

^{Note: This component is currently only available for JavaScript.}

Overview

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";
parent.addElement(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.

Properties

Methods

None.

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:

<fx:Script>
    <![CDATA[      
        private function clickHandler(event:MouseEvent):void {
            trace("Hello from a Button!");
        }
    ]]>
</fx:Script>

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);
parent.addElement(button);

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

More examples

• Using the Jewel Slider Control
• Selecting options from a group of Jewel CheckBox controls
• Dividing an Apache Royale application with modules

Related controls

Other useful Jewel button components are:

• IconButton
• ToggleButton