How do I add a button to a movie?

Added: 31 Jan 2009. Working example for Java

Buttons are reasonably complex objects but still relatively straightforward to create. The first part is to define sets of shapes that will be displayed for each of the three button states:

An additional shape is needed to define the Active area of the button so the Flash Player can identify when the button should move between the different states in response to the mouse being moved or a mouse button being clicked.

You can specify more than one shape for each of the three states to create more visually appealing buttons. As with movies and movie clips each shape is placed on a different layer with shapes on a higher layer number displayed in front of shapes on a lower one. The layer numbers are independent to the layer used in a movie clip or main movie so the button can be treated as a single object when it is placed on the display list.

ArrayList<ButtonShape> records = new ArrayList<ButtonShape>();

records.add(new ButtonShape().setState(ButtonState.ACTIVE)
    .setIdentifier(up).setLayer(layer++);
records.add(new ButtonShape().setState(ButtonState.UP)
    .setIdentifier(shadow).setLayer(layer++).setTransform(recess);
records.add(new ButtonShape().setState(ButtonState.UP)
    .setIdentifier(up).setLayer(layer++);
records.add(new ButtonShape().setState(ButtonState.UP)
    .setIdentifier(label).setLayer(layer++);
    .setTransfrom(CoordTransform.translate(-width/2, height/2));

records.add(new ButtonShape().setState(ButtonState.OVER)
    .setIdentifier(shadow).setLayer(layer++).setTransform(recess);
records.add(new ButtonShape().setState(ButtonState.OVER)
    .setIdentifier(over).setLayer(layer++);
records.add(new ButtonShape().setState(ButtonState.OVER)
    .setIdentifier(label).setLayer(layer++)
    .setTranform(CoordTransform.translate(-width/2, height/2));

records.add(new ButtonShape().setState(ButtonState.DOWN)
    .setIdentifier(over).setLayer(layer++.setTransform(recess);
records.add(new ButtonShape().setState(ButtonState.DOWN)
    .setIdentifier(label).setLayer(layer++)
    .setTransform(CoordTransform.translate(
        -width/2 + xShadow, height/2 + yShadow));

In addition to specifying the shape you can also specify a coordinate transform to change position of the shape. This allows effects such as shadows to be created. It also allows the button to give the appearance of being clicked with the shapes changing position slightly as if the button was floating above the screen.

The next stage in creating a button is to define the set of actions that are executed when the button is clicked. For the DefineButton class this is a simple list:

ArrayList<Action> actions = new ArrayList<Action>();
actions.add(new GetUrl("http://www.flagstonesoftware.com", ""));

However for DefineButton2 you can specify different actions for a wide range of events, not only when the button is clicked. See What is an event? for the types of event that buttons created using this class can handle and How can I use Actionscript in a movie? to see how to write the event handlers for the button.