| MovieClip.onKeyDown ( ) Event Handler | Flash 6 |
| handler executed when a key is depressed while the clip has focusFlash 5; callback form introduced in |
The onKeyDown( ) event handler is the callback form (and more modern analogue) of the legacy onClipEvent(keyDown) event handler. However, it is one of the few handlers whose behavior changes between its callback form and its Flash 5-style onClipEvent( ) form. When implemented as a callback function, onKeyDown( ) executes only when a key is depressed and the clip specified by mc has keyboard focus. By default, keyboard focus is indicated by a yellow rectangle. However, in Flash 6, a couple of caveats make the callback form of onKeyDown( ) tricky to use. First, a movie clip without button handlers is not focusable unless one or both of its focusEnabled or tabEnabled properties is explicitly set to true. Second, keyboard focus on a movie clip is lost the instant mouse movement over the Flash Player is detected. In the following code, we specify an onKeyDown( ) callback, then we enable focusing, and finally we focus the clip programmatically. Only then will the clip rotate when keys are pressed.
theClip_mc.onKeyDown = function () {
this._rotation++;
}
theClip_mc.focusEnabled = true;
Selection.setFocus(theClip_mc);
If you try this code in Test Movie mode, it will work only when your mouse pointer is not over the movie's Stage; otherwise, focus will immediately be lost, and the event will not fire. These caveats limit the general usefulness of the onKeyDown( ) movie clip event. Indeed, the Key.onKeyDown( ) listener event, not MovieClip.onKeyDown( ), is Macromedia's intended all-purpose keyboard response tool. However, MovieClip.onKeyDown( ) proves important when movie clips function as keyboard-controlled interface elements. For example, by implementing onKeyDown( ) on two separate "menu" movie clips, we can easily use the same shortcut key to trigger different operations, depending on which menu has focus. Unfortunately, this scenario applies strictly to keyboard-only interfaces because even the slightest mouse movement removes the current focus. Macromedia's keyboard-focus implementation is slated for further refinement in future versions of Flash, so a different model may arise to address this situation in Flash 7.
In contrast, the onClipEvent(keyDown) version of the handler is intuitive and unchanged from its Flash 5 behavior; it executes whenever any key is pressed, period. It requires only that the Flash Player itself be focused. As of Flash 6, the Key.onKeyDown( ) listener event is usually preferred over MovieClip.onKeyDown( ); see complete documentation under Key.onKeyDown( ). However, there's one final ingredient in the onKeyDown( ) stew: the updateAfterEvent( ) function (which refreshes the screen between frames) works with MovieClip.onKeyDown( ) but not with Key.onKeyDown( ). The general rules of usage, therefore, are:
If you need a general key-handling mechanism but do not require between-frame screen updates, use Key.onKeyDown( ).
If you need a general key-handling mechanism, but your application must update the screen between frames, use the Flash 5-style onClipEvent (keyDown).
If you need keyboard control over a movie clip only when it has keyboard focus, use MovieClip.onKeyDown( ).
The onKeyDown( ) handler does not work with main movie timelines (e.g., _root, _level0, _level1) because main timelines cannot receive input focus.
Key.onKeyDown( ), Key.onKeyUp( ), MovieClip.focusEnabled, MovieClip.onKeyUp( ), MovieClip.tabEnabled
