Macromedia Flash File Format (SWF)

recompiled with RAW HTWL

Buttons

Introduction	Basic Types	Display List	Control Tags
Shapes	(Examples Shapes)	Gradients	Buttons
Sprites	Fonts and Text	Shape Morphing	Bitmap
Sounds	Actions	ActionScripts	Reference

Buttons Contents

Buttons
Button States and Shapes
Button Tracking
Events, State Transitions and Actions
Button Records
DefineButton
DefineButton2
DefineButtonCxForm
DefineButtonSound

Buttons

Button objects are the key to interactivity in a Macromedia Flash movie. Buttons are the only objects that can react to events such as mouse movement and mouse clicks. When an event occurs, the button object can perform a series of actions, such as jumping to a URL or jumping to another frame in the movie. This event-action model is surprisingly powerful. Button objects have been used to serve many purposes, from simple menus, to sprites in a complex game.

Button States and Shapes

A button object can be displayed in one of three states: up, over, or down.

The up state is the default appearance of the button. The up state is displayed when the Macromedia Flash movie starts playing, and whenever the mouse is outside the button. The over state is displayed when the mouse is moved inside the button. This allows ‘rollover’ or ‘hover’ buttons in a Macromedia Flash movie. The down state is the ‘clicked’ appearance of the button. It is displayed when the mouse is clicked inside the button.

A fourth state – the hit-state – defines the active area of the button. This is an invisible state and is never displayed. It defines the area of the button that reacts to mouse-clicks.

Each state is defined by a BUTTONRECORD. The button record contains a link to a previously defined shape, called a character. For visible states, this shape is rendered to the display when the button enters the state. For the hit-area, this shape defines the active area of the button.

Below is a typical button and its four states. The button is initially blue. When the mouse is moved over the button it changes to a mauve color. When the mouse is pressed inside the button, the shading changes to simulate a depressed button. The fourth state – the hit-area – is a simple rectangle. Anything outside this shape is outside the button, and anything inside this shape is inside the button.

Here is an overview of the button states:

The Up State — The default appearance of the button.
This shape defines what the button looks like when the button is ‘idle’. That is, when the cursor is outside the hit-area. A button is always in the up state when the movie starts playing.
The Over State — The mouse-over state.
This shape defines what the button looks like when the cursor is ‘over’ the button. That is, when the cursor is inside the hit-area. The over state can be used to create ‘rollover’ or ‘hover’ buttons in a Flash movie.
The Down State — The ‘clicked’ appearance of the button.
This shape defines what the button looks like when the mouse button is pressed while the cursor is inside the hit-area.
The Hit Area — The active area of the button.
This shape is never displayed; it defines the active area of the button that reacts to events such as mouse-clicks. The hit-area is not necessarily rectangular and need not reflect the visible shape of the button.

Macromedia Flash (SWF) has no native support for radio-buttons or checkboxes. There is no ‘checked’ state, and buttons cannot ‘stick’ down after the mouse is released. Neither is there any way to group buttons into mutually exclusive choices. However, both these behaviors can be simulated using button actions.

Button Tracking

Button tracking refers to how a button behaves as it ‘tracks’ the movement of the mouse. A button object can track the mouse in one of two modes:

As a push button
As a menu button.

If a push button is clicked, all mouse movement events are directed to the push button until the mouse button is released. This is called ‘capturing’ the mouse. For example, if you click a push button and drag outside the button (without releasing) the button changes to the over state, and the pointer remains a hand cursor.

Menu buttons do not capture the mouse. If you click on a menu button and drag outside, the button changes to the up state, and the pointer reverts to an arrow cursor.

Events, State Transitions and Actions

A button object can perform an action whenever there is a state transition, that is, when the button changes from one state to another. A state transition occurs in response to some event, such as a mouse-click, or mouse entering the button.

The Macromedia Flash user-interface and Macromedia Flash (SWF) use different terminology to describe how button actions are triggered. In the Macromedia Flash user-interface, button actions are performed in response to events. In Macromedia Flash (SWF), button actions are performed in response to state transitions. For the purposes of this discussion, events and state transitions are equivalent.

Below is a table of possible state transitions and corresponding Macromedia Flash events:

State Transition	Flash Event	Description	Visual Effect
IdleToOverUp	Roll Over	Mouse enters the hit area while the mouse button is up.	Button changes from up to over state.
OverUpToIdle	Roll Out	Mouse leaves the hit area while the mouse button is up.	Button changes from over to up state.
OverUpToOverDown	Press	Mouse button is pressed while the mouse is inside the hit area.	Button changes from over to down state.
OverDownToOverUp	Release	Mouse button is released while the mouse is inside the hit area.	Button changes from down to over state.

These transitions only apply when tracking Push buttons:

State Transition	Flash Event	Description	Visual Effect
OutDownToOverDown	Drag Over	Mouse is dragged inside the hit area while the mouse button is down.	Button changes from over to down state.
OverDownToOutDown	Drag Out	Mouse is dragged outside the hit area while the mouse button is down.	Button changes from down to over state.
OutDownToIdle	Release Outside	Mouse button is released outside the hit area while the mouse is captured.	Button changes from over to up state.

These transitions only apply when tracking Menu buttons:

State Transition	Flash Event	Description	Visual Effect
IdleToOverDown	Drag Over	Mouse is dragged inside the hit area while the mouse button is down.	Button changes from up to down state.
OverDownToIdle	Drag Out	Mouse is dragged outside the hit area while the mouse button is down.	Button changes from down to up state.

Typically button actions are performed on OverDownToOverUp (when the mouse button is released), but DefineButton2 allows actions to be triggered by any state transition.

A button object can perform any action supported by the DoAction flag.

Button Records

A button record defines the shape to be displayed for a button state. The ButtonState flags indicate which state (or states) the shape belongs to.

There is not a one-to-one relationship between button records and button states. A single button record may define more than one button state (by setting multiple ButtonState flags), and two or more button records may refer to the same button state. In this case, both shapes will be displayed for that state.

Each button record also includes a transformation matrix and stacking-order information.

     BUTTONRECORD

     Field           Type           Comment

     ButtonReserved           UB[4]           Reserved bits — always 0

     ButtonStateHitTest           UB[1]           Button state hit test flag

     ButtonStateDown           UB[1]           Button state down flag

     ButtonStateOver           UB[1]           Button state over flag

     ButtonStateUp           UB[1]           Button state up flag

     ButtonCharacter           UI16           Button character ID

     ButtonLayer           UI16           Button character layer

     ButtonMatrix           MATRIX           Button character matrix

     ColorTransform           CXFORM           Character color transform

SwfJava v0.0: how to create a ButtonRecord object

new ButtonRecord ( int state, int characterID, int characterLayer, Matrix matrix, CXFormWithAlpha cxForm, ); state can be a combination of UP, OVER, DOWN, HIT.

XWF v0.0: how to declare a Button element

<Button ref="(ID)" layer="(int)" [up] [over] [down] [hit] > [<Matrix ... /> [<ColorTransform ... /> </Button>

- The above spec is wrong: DefineButton doesn't use CXForm at all, whereas DefineButton2 uses CXFormWithAlpha.
- ButtonRecords are byte-aligned (UI8 instead of UB[4]+UB[1]+UB[1]+UB[1]+UB[1])

DefineButton

This tag defines a button character for later use by control tags such as PlaceObject.

DefineButton includes an array of BUTTONRECORDs which represent the four button shapes – an up character, a mouse-over character, a down character, and a hit-area character. It is not necessary to define all four states, but there must be at least one button record. For example, if the same button record defines both the up and over states, only three button records are required to describe the button.

More than one button-record per state is allowed. If two button records refer to the same state, both shapes will be displayed for that state.

DefineButton also includes an array of ACTIONRECORDs which are performed when the button is clicked and released. See the DoAction tag. (SWF 1.0)

     DefineButton

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 7

     ButtonId           UI16           ID for this character

     Buttons           BUTTONRECORD[one or more]           Button character records

     ButtonEndFlag           UI8 = 0           Always set to 0

     Actions           ACTIONRECORD [zero or more]           Actions to perform — see the DoAction tag

     ActionEndFlag           UI8 = 0           Always set to 0

SwfJava v0.0: how to create a DefineButton object

new DefineButton ( int id, ButtonRecord [] buttonRecords, ActionRecord [] actionRecords, );

XWF v0.0: how to declare a DefineButton tag

<DefineButton id="(ID)" > <Button ... /> <Button ... /> ... [<action ... />] [<action ... />] ... </DefineButton>

It is possible to have no ActionRecord at all (not even the ending UI8=0) if the tag length is set so.

DefineButton2

DefineButton2 extends the capabilities of DefineButton by allowing actions to be triggered by any state transition.

     DefineButton2

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 34

     ButtonId           UI16           ID for this character

     Flags           UI8 = 0 or 1           Track as menu flag

     Offset           UI16           Offset to the first Button2ActionCondition (immediately following the BUTTONRECORDs)

     Buttons           BUTTONRECORD[one or more]           Button character records with color transform with alpha

     ButtonEndFlag           UI8 = 0           Always set to 0

     Button2ActionCondition                     Specifies a series of actions to perform based on a condition. Each Button2ActionCondition consists of ActionOffset, Condition, Actions, and ActionEndFlag

     ActionOffset           UI16           Points to next Button2Action condition

     Condition           UI16           Button state transitions triggering an action.
UB[7] Reserved
UB[1] OverDownToIdle
UB[1] IdleToOverDown
UB[1] OutDownToIdle
UB[1] OutDownToOverDown
UB[1] OverDownToOutDown
UB[1] OverDownToOverUp
UB[1] OverUpToOverDown
UB[1] OverUptoIdle
UB[1] IdleToOverUp

     Actions           ACTIONRECORD [zero or more]           Actions to perform — see the DoAction tag

     ActionEndFlag           UI8 = 0           Always set to 0

Note: The ActionOffset preceding the last Button2ActionCondition should be zero.

SwfJava v0.0: how to create a ActionCondition object

new ActionCondition ( int condition, ActionRecord [] actionRecords ); new ActionCondition ( int condition, char key, ActionRecord [] actionRecords ); condition can be a combination of OVER_DOWN_TO_IDLE, IDLE_TO_OVER_DOWN, OUT_DOWN_TO_IDLE, OUT_DOWN_TO_OVER_DOWN, OVER_DOWN_TO_OUT_DOWN, OVER_DOWN_TO_OVER_UP, OVER_UP_TO_OVER_DOWN, OVER_UP_TO_IDLE, IDLE_TO_OVER_UP.

SwfJava v0.0: how to create a DefineButton2 object

new DefineButton2 ( int id, boolean isTrackAsMenu ButtonRecord [] buttonRecords, ActionCondition [] actionConditions, );

XWF v0.0: how to declare a DefineButton2 tag

The 7 reserved bits are used for key press events: they are the 7 bits ASCII code of the key.

DefineButtonCxForm

Defines the color transform for each shape and text character in a button. Not used for DefineButton2. (SWF 2.0)

     DefineButtonCxForm

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 23

     ButtonId           UI16           Button ID for this information

     ButtonColorTransform           CXFORM           Character color transform

SwfJava v0.0: how to create a DefineButtonCxForm object

{not yet implemented}

DefineButtonSound

The DefineButtonSound tag defines which sounds (if any) are played on state transitions. (Macromedia Flash (SWF) 2)

     DefineButtonSound

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 17

     ButtonId           UI16           The ID of the button these sounds apply to.

     ButtonSoundChar0           UI16           Sound ID for OverUpToIdle

     ButtonSoundInfo0           SOUNDINFO           Sound style for OverUpToIdle

     ButtonSoundChar1           UI16           Sound ID for IdleToOverUp

     ButtonSoundInfo1           SOUNDINFO           Sound style for IdleToOverUp

     ButtonSoundChar2           UI16           Sound ID for OverUpToOverDown

     ButtonSoundInfo2           SOUNDINFO           Sound style for OverUpToOverDown

     ButtonSoundChar3           UI16           Sound ID for OverDownToOverUp

     ButtonSoundInfo3           SOUNDINFO           Sound style for OverDownToOverUp

SwfJava v0.0: how to create a DefineButtonSound object

{not yet implemented}

Introduction	Basic Types	Display List	Control Tags
Shapes	(Examples Shapes)	Gradients	Buttons
Sprites	Fonts and Text	Shape Morphing	Bitmap
Sounds	Actions	ActionScripts	Reference