Book HomeActionScript: The Definitive GuideSearch this book

10.8. Button Events

Table 10-1 briefly introduces the various events available for buttons. Using button events, we can easily create code for navigation, forms, games, and other interface elements. Let's explore each button event and learn how a button can be programmed to react to mouse and keyboard events.

Each of the button events in Table 10-1 is handled by a matching button event handler of the form on (eventName). For example, the press event is handled using an event handler beginning with on (press). The exception is the keyPress event handler which takes the form on (keyPress key) where key is the key to detect. Button events are sent only to the button with which the mouse is interacting. If multiple buttons overlap, the topmost button receives all events; no other buttons can respond, even if the topmost button has no handlers defined. In the following descriptions, the hit area refers to the physical region of the button that must be under the mouse pointer in order for the button to be activated. (A button's hit area is defined graphically when you create the button in the Flash authoring tool.)

Table 10-1. Button Events

Button Event Name

Button Event Occurs When . . .

press

Primary mouse button is depressed while pointer is in the button's hit area. Other mouse buttons are not detectable.

release

Primary mouse button is depressed and then released while pointer is in the button's hit area.

releaseOutside

Primary mouse button is depressed while pointer is in the button's hit area and then released while pointer is outside of the hit area.

rollOver

Mouse pointer moves into the button's hit area without the mouse button depressed.

rollOut

Mouse pointer moves out of the button's hit area without the mouse button depressed.

dragOut

Primary mouse button is depressed while pointer is in the button's hit area, and then, while mouse button is still depressed, pointer is moved out of the hit area.

dragOver

Primary mouse button is depressed while pointer is in the button's hit area, and then, while mouse button is still depressed, pointer is moved out of, then back into, the button's hit area.

keyPress

Specified key is depressed. In most cases, the keyDown clip event is preferred over the keyPress button event.

10.8.1. press

A mouseclick is technically a two-step process: the mouse button is depressed ( press) and then released (release). A press event occurs when the mouse pointer is in the hit area of a button and the primary mouse button is depressed. Secondary mouse buttons are not detectable. Button press events are appropriate for radio buttons or weapons firing in a game, but use release events to allow the user to change his mind before releasing the mouse.

10.8.2. release

The release button event occurs when the following sequence is detected:

  1. The mouse pointer is in the hit area of a button.

  2. The primary mouse button is pressed while the mouse pointer is still in the hit area of the button (at which point a press event occurs).

  3. The primary mouse button is released while the mouse pointer is still in the hit area of the original button (at which point the release event occurs).

By using the release event instead of the press event, you give users a chance to move the pointer off of a button even after it has been clicked, thus allowing them to retract their action.

10.8.3. releaseOutside

The releaseOutside event typically indicates that the user changed his mind by clicking on a button but moving the pointer off the button before releasing the mouse button. The event is generated when the following sequence is detected:

  1. The mouse pointer is in the hit area of a button.

  2. The primary mouse button is pressed and held (the press event occurs).

  3. The mouse pointer moves out of the button's hit area (the dragOut event occurs).

  4. The primary mouse button is released while not in the hit area of the original button.

You will rarely bother detecting releaseOutside events, as they usually indicate that the user intended not to perform any action.

10.8.4. rollOver

The rollOver event occurs when the mouse pointer moves into the hit area of a button with no mouse buttons depressed. The rollOver event is rarely used in ActionScript because visual button changes are created directly in the authoring tool, not with scripting. You should use the provided up, over, and down frames in the authoring tool to create highlight states for buttons.

The rollOver event in Flash 5 provides a handy means of retrieving a text field selection. For more details, see Reference 20.200" in Part III, "Language Reference".

10.8.5. rollOut

The rollOut event is rollOver 's counterpart; it occurs when the mouse pointer is moved out of the hit area of a button with no mouse buttons depressed. As with rollOver, rollOut is rarely used because button highlight states are created directly in the authoring tool, so manual image swapping is not required in ActionScript.

10.8.6. dragOut

The dragOut event is similar to rollOut, except that it is generated if the mouse button is down when the pointer leaves a button's hit area. The dragOut event is followed by either the releaseOutside event (if the user releases the mouse button) or the dragOver event (if the user moves the pointer back into the button's hit area without having released the mouse button).

10.8.7. dragOver

The dragOver event is a seldom-seen woodland creature. It is conjured up when the following sequence is performed:

  1. The mouse pointer moves into the hit area of a button (rollOver event occurs).

  2. The primary mouse button is pressed and held ( press event occurs).

  3. The mouse pointer moves out of the button's hit area (dragOut event occurs).

  4. The mouse pointer moves back into the button's hit area (dragOver event occurs).

Thus, the dragOver event indicates that the user has moved the mouse pointer out of and back into the hit area, all the while holding the mouse button down. Note that dragover, instead of the rollOver event, is generated if the mouse button is still down when the pointer reenters the button's hit area.

10.8.8. keyPress

The keyPress event is unrelated to mouse events and is instead triggered by the pressing of a specified key. We cover it here because it uses the on (eventName) syntax of other ActionScript button event handlers. This event handler requires us to specify the key that triggers the event:

on (keyPress key) {
  statements
}

where key is a string representing the key associated with the event. The string may be either the character on the key (such as "s" or "S"), or a keyword representing the key in the format "<Keyword >". Only one key may be specified with each handler. To capture multiple keys using keyPress, we must create multiple keyPress event handlers. For example:

// Detects the "a" key
on (keyPress "a") {
  trace("The 'a' key was pressed");
}

// Detects the Enter key
on (keyPress "<Enter>") {
  trace("The Enter key was pressed");
}

// Detects the Down Arrow key
on (keyPress "<Down>") {
  trace("The Down Arrow key was pressed");
}

The legal values of Keyword are as follows (note that the function keys F1 . . . F12 are not supported by keyPress, but are detectable using the Key object):

<Backspace>
<Delete>
<Down>
<End>
<Enter>
<Home>
<Insert>
<Left>
<PgDn>
<PgUp>
<Right>
<Space>
<Tab>
<Up>

In Flash 4, keyPress was the only means we had of interacting with the keyboard. In Flash 5 and later, the Key object, in combination with the movie clip events keyDown and keyUp (discussed later), offer much greater control over keyboard interaction. The keyPress event detects the pressing of a single key at a time, whereas the Key object can detect the simultaneous pressing of multiple keys.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.