| class-like datatype for main movies and movie clipsFlash 3; enhanced in Flash 4, Flash 5, and | | Constructornew MovieClip(); The constructor syntax is used only to create MovieClip subclasses. It does not create an on-stage movie clip! To create a movie clip instance, use attachMovie( ), createEmptyMovieClip( ), or duplicateMovieClip( ). MovieClip symbols, on which instances are based, must be created manually in the Flash authoring tool. Properties Movie clip properties provide descriptions of, and control over, various physical features of movie clips and main movies. As with any object, MovieClip properties are accessed using the dot or [ ] operators. See Section 13.1 for details on using movie clip properties. Here are three property-related issues to note: -
Changing a physical property of a MovieClip object places that clip under programmatic control, breaking the internal timeline's hold on it. This halts any tween currently in progress. -
Some MovieClip properties appear to be floating-point numbers but are mapped to other formats internally. The _alpha property, for example, is mapped internally to an integer between 0 and 255. This results in a loss of precision between setting and retrieving values of certain properties. For example, we may set a property value to 90 and then immediately retrieve the value back as 89.84375. If minor variations in property values make a difference to a script, we must manually round those values using Math.round( ), Math.floor( ), or Math.ceil( ) after retrieval, or we must store the original value in a variable separate from the property. -
The built-in MovieClip properties are not enumerated by a for-in loop. Table 18-11 lists the properties of the MovieClip class. Movie clip properties can be accessed for any movie clip instance and, in most cases, on the main movie timeline (_root). Those that cannot be used with the main movie timeline are marked by in Table 18-11. Prior to Flash 6, all built-in movie clip properties were prefaced with an underscore. To conform more closely with other ECMA-262 languages, properties that are new in Flash 6, and are not analogous to legacy Flash 5 Button properties such as _focusRect, do not obey the underscore convention. Properties introduced in Flash 6 are marked by character in Table 18-11. In the Access column of Table 18-11, R/W indicates that a property's value can be both retrieved and set (i.e., read/write), and RO indicates that it can be retrieved but not set (i.e., read-only). Some read-only properties can sometimes be set indirectly through the authoring tool or via some related function (e.g., gotoAndStop( ) sets the _currentframe property), but only read/write properties can be set directly via ActionScript. The Type column describes the datatype of each property's value. The Property description column gives a quick summary of the property's purpose, but the full descriptions that follow later provide important details. All properties of the current timeline can be accessed without an explicit reference to it, as in _alpha versus someClip._alpha. Table 18-11. Movie clip property summary | _alpha | R/W | number | Opacity percentage: 0 is transparent; 100 is opaque | | _currentframe | RO | number | Frame number at which playhead resides | | _droptarget | RO | string | Target path of the clip over which a dragged clip hovers or has been dropped, in slash notation | | enabled | R/W | Boolean | Allows or disallows button interaction | | focusEnabled | R/W | Boolean | Allows the clip to receive keyboard focus programmatically | | _focusrect | R/W | Boolean | Disables automatic yellow rectangle around focused movie clips | | _framesloaded | RO | number | Number of frames that have been downloaded | | _height | R/W | number | Height, in pixels, of the current contents | | hitArea | R/W | string | Assigns the clickable area for a button-enabled movie clip | | _name | R/W | string | Identifier of an instance as a string (not a reference) | | _parent | RO | MovieClip reference | A reference to the instance or movie that contains the current instance | | _rotation | R/W | number | Degrees of rotation | | tabChildren | R/W | Boolean | Controls whether contained objects are included in the automatic tab order | | tabEnabled | R/W | Boolean | Includes or excludes the movie clip from the current tab order | | tabIndex | R/W | Boolean | Specifies the movie clip's index in the custom tab order | | _target | RO | string | Target path in absolute terms, in slash notation | | _totalframes | RO | number | Number of frames in the timeline | | trackAsMenu | R/W | | Modifies the onRelease( ) handler requirements, enabling menu-style behavior | | _url | RO | string | Disk or network location of the source .swf file | | useHandCursor | R/W | Boolean | Dictates whether a hand cursor is displayed when the mouse is over the clip (applies to clips with button handlers only) | | _visible | R/W | Boolean | Visibility: true if shown; false if hidden | | _width | R/W | number | Width, in pixels, of the current contents | | _x | R/W | number | Horizontal position, in pixels | | _xmouse | RO | number | Horizontal location of mouse pointer, in pixels | | _xscale | R/W | number | Horizontal scaling percentage | | _y | R/W | number | Vertical position, in pixels | | _ymouse | RO | number | Vertical location of mouse pointer, in pixels | | _yscale | R/W | number | Vertical scaling percentage | Methods Table 18-12 and Table 18-13 list the methods of the MovieClip class. Movie clip methods can be invoked on any movie clip instance and, in most cases, on the main movie timeline (_root). Those in Table 18-12 that cannot be used with the main movie timeline are marked by . Methods introduced in Flash 6 are marked by in the tables. The movie clip methods marked by character in Table 18-12 provide the same functionality as analogous global functions but use the preferred MovieClip.method( ) dot syntax format (that is, a movie clip instance must precede the dot). Methods that do not correspond to a global function can be applied to the current clip without an explicit reference to the movie clip instance, as in attachMovie( ) versus someClip.attachMovie( ). Table 18-12. Movie clip method summary | attachMovie( ) | Creates a new instance based on an exported symbol from the current document's Library | | createEmptyMovieClip( ) | Creates a new, empty MovieClip instance | | createTextField( ) | Creates a new TextField object | | duplicateMovieClip( ) | Creates a copy of a movie clip instance | | getBounds( ) | Returns an object whose properties give the coordinates of the bounding box that defines the visual region occupied by the clip | | getBytesLoaded( ) | Returns the number of downloaded bytes of an instance or a movie (not applicable to internal clips) | | getBytesTotal( ) | Returns the physical byte size of an instance or a main movie | | getDepth( ) | Returns the movie clip's position in the visual content stack | | getURL( ) | Loads an external document (usually a web page) into the browser | | globalToLocal( ) | Converts the properties of a coordinates object from Stage coordinates to instance coordinates | | gotoAndPlay( ) | Moves the playhead of an instance or movie to a specific frame and then plays the instance or movie | | gotoAndStop( ) | Moves the playhead of an instance or movie to a specific frame and then stops the playhead | | hitTest( ) | Returns a Boolean indicating whether a clip intersects with a given point or another clip | | loadMovie( ) | Loads an external .swf file into the Player | | loadVariables( ) | Retrieves external data composed of variable names and values, and converts that data into equivalent ActionScript variables | | localToGlobal( ) | Converts the properties of a coordinates object from an instance's coordinates to Stage coordinates | | nextFrame( ) | Moves the playhead of an instance or movie ahead one frame and stops it there | | play( ) | Starts the playhead of an instance or movie in motion (i.e., plays the clip) | | prevFrame( ) | Moves the playhead of an instance or movie back one frame and stops it there | | removeMovieClip( ) | Deletes a duplicated or attached instance | | setMask( ) | Assigns a movie clip as a mask for another clip | | startDrag( ) | Causes an instance or movie to follow the mouse pointer physically | | stop( ) | Halts the playback of an instance or movie | | stopDrag( ) | Ends any drag operation in progress | | swapDepths( ) | Alters the position of an instance in the content stack | | unloadMovie( ) | Removes an instance or main movie from a document level or host clip | | valueOf( ) | Returns an object reference to the instance | Methods to draw lines and fills in a movie clip instance, the so-called Drawing API, are also new in Flash 6 and are shown in Table 18-13. Refer also to the MovieClip.createEmptyMovieClip( ), method, which is convenient for creating an empty canvas on which to draw. Table 18-13. Movie clip Drawing API methods | beginFill( ) | Starts a solid-filled shape | | beginGradientFill( ) | Starts a gradient-filled shape | | clear( ) | Removes all drawings from the movie clip | | curveTo( ) | Draws a curved line | | endFill( ) | Finishes a filled shape | | lineStyle( ) | Sets stroke thickness, color, and transparency | | lineTo( ) | Draws a straight line | | moveTo( ) | Moves the drawing pen to a new position without drawing a line | Events Movie clip instances support event handlers, which respond automatically to a predefined set of events (e.g., mouse and keyboard interaction or movie playback). As of Flash 6, Button events (e.g., onPress( ), onRelease( ), and onRollOver( )) are also available for movie clips, although not for main movie timelines (_root). Movie clip event handlers can be created in the following ways: -
By attaching an onClipEvent( ) block directly to a movie clip instance at authoring time -
By attaching a button-style on( ) block directly to a movie clip instance at authoring time -
By assigning a callback function to the associated event property with ActionScript Here are examples of each of these techniques: // An onClipEvent() block onClipEvent (enterFrame) { // statements } // An on() block on (release) { // statements } // Two callback functions theClip_mc.onEnterFrame = function () { // statements } theClip_mc.onPress = function () { // statements } Callback functions are not supported by Flash 5 but are generally preferred over onClipEvent( ) and on( ) blocks as of Flash 6. For important details on the differences between the types of event handlers, see Chapter 10. In particular, note that: -
When the contents of a movie clip are unloaded, event handler properties (e.g., onEnterFrame( )) are lost, but onClipEvent( ) handlers (e.g., onClipEvent(enterFrame)) are not. -
When a movie clip is duplicated via duplicateMovieClip( ), the event handler properties are not copied to the duplicate clip, but the onClipEvent( ) handlers are. The supported movie clip event handlers are listed in Table 18-14. Handlers listed with are not supported by main movies (_root). All the event handlers in Table 18-14 are new in Flash 6, but the Flash 5 equivalents are shown where applicable. With the exception of onKillFocus( ) and onSetFocus( ), events listed without Flash 5 equivalents are adopted Button events. Table 18-14. Movie clip event handler summary | onData( ) | The clip receives the end of a stream of loaded variables, or a portion of a loaded movie | onClipEvent(data) | | onDragOut( ) | The mouse is pressed over the clip, then the mouse moves off the clip before the mouse is released | None | | onDragOver( ) | The mouse is pressed over the clip, then the mouse moves off and back onto the clip | None | | onEnterFrame( ) | One tick of the frame rate passes in the Flash Player | onClipEvent(enterFrame) | | onKeyDown( ) | A key is pressed down while the clip is on stage and has keyboard focus | onClipEvent(keyDown) | | onKeyUp( ) | A depressed key is released while the clip is on stage and has keyboard focus | onClipEvent(keyUp) | | onKillFocus( ) | The clip loses keyboard focus | None | | onLoad( ) | The clip first appears on stage, or a .swf file finishes loading into the clip | onClipEvent(load) | | onMouseDown( ) | Primary mouse button is depressed while the clip is on stage | onClipEvent(mouseDown) | | onMouseMove( ) | Primary mouse button is depressed and then released while the clip is on stage | onClipEvent(mouseMove) | | onMouseUp( ) | Mouse pointer moves (even a teensy bit) while the clip is on stage | onClipEvent(mouseUp) | | onPress( ) | The mouse is pressed over the clip | None | | onRelease( ) | The mouse is pressed and then released over the clip | None | | onReleaseOutside( ) | The mouse is pressed over the clip and then released after moving off the clip | None | | onRollOut( ) | The mouse pointer moves off the clip while the mouse button is not depressed | None | | onRollOver( ) | The mouse pointer moves over the clip while the mouse button is not depressed | None | | onSetFocus( ) | The clip gains keyboard focus | None | | onUnload( ) | The clip is removed from the Stage | onClipEvent(unload) | Description MovieClip is not just a class in ActionScript; it is also a unique ActionScript datatype used to represent information about, and allow control of, movies and movie clips. For most purposes, we treat movie clips and movies as objects; we can create and access movie clip properties, and we can create and invoke movie clip methods. For a full consideration of the MovieClip class, see Chapter 13. We do not use a constructor to create new MovieClip instances. Instead, we create movie clip symbols in the authoring tool and place instances on the Stage manually. Some methods, however, allow us to copy existing clips (e.g., duplicateMovieClip( )) or add new clips to the Stage programmatically (e.g., attachMovie( ) and createEmptyMovieClip( )). Not all MovieClip objects are equal; some MovieClip methods and properties apply to movie clip instances only, not to main movies (a main movie is the _root timeline of a .swf document). In our consideration of the MovieClip properties and methods, we'll note cases in which functionality is limited to one type of MovieClip object. Note that we use the word MovieClip to refer to the "class" of the objects, and the word movieclip (lowercase) to refer to the ActionScript datatype; we use the words movie clip, clip, or instance to refer to a particular movie clip, and we use movie to refer to the main movie of a .swf file. In the synopsis for each detailed property and method entry, the abbreviation mc stands in for the name of a clip or main movie. For many properties and methods, mc is optional if omitted, the current timeline is assumed (see Table 18-12). Throughout this MovieClip section, when talking about coordinates, we need to refer to the location of movie clips. We measure the position of a clip in reference to one representative point, its so-called registration point, as marked by a crosshair in the clip's Library symbol. When a clip resides on the main Stage, we describe its location relative to the top-left corner of the Stage, which corresponds to the point (0,0). When a clip resides within another clip, we describe its location relative to the registration point of the parent clip, which again corresponds to the point (0,0). The point (0,0) in both cases is the origin point (or simply origin) of the coordinate space being used to plot the location of the clip. We'll see how the localToGlobal( ) and globalToLocal( ) methods can convert between these two coordinate spaces.  | Flash's coordinate system inverts the Y-axis of Cartesian coordinates; that is, y values increase in a downward direction, not upward. For example, a y-coordinate of 100 indicates a point 100 pixels below the X-axis. | | We'll often use the coordinate-related properties and methods to move a clip, determine where a clip is, or determine whether it intersects another object or point. The last technique is referred to as collision detection because it is often used to determine whether to change the direction in which a clip is animating, as if it bounced off another object (see the MovieClip.hitTest( ) method). Note that ActionScript doesn't have a native datatype to represent a point (i.e., an x- and y-coordinate). See MovieClip.globalToLocal( ) for an explanation of how to create a point object from a generic object. In Flash 5, no direct API was available to create ActionScript subclasses of the MovieClip class. As of Flash 6, the Object.registerClass( ) method can be used to register a custom class as a subclass of MovieClip. For full details, see Chapter 14. As of Flash 6, movie clip instances can behave exactly like buttons. To implement button behaviors for a movie clip, define one or more of the following button event handlers: onDragOut( ), onDragOver( ), onPress( ), onRelease( ), onReleaseOutside( ), onRollOut( ), onRollOver( ) (see Table 18-14). Once a button handler is defined for a movie clip, the following button-related properties become active: enabled, hitArea, trackAsMenu, and useHandCursor. These properties can be set at any time, but they have an effect only when at least one button handler is defined. To provide button-style Up, Over, and Down states for a movie clip, create frames with the special labels "_up", "_over", and "_down". To define the button-style Hit state for a movie clip, use the hitArea property. If no hitArea property is defined, the clip's own content is used as the hit area. Note that though Macromedia's documentation refers to movie clips with button handlers as "button movie clips," there is no such symbol type or class. A "button movie clip" is simply Macromedia's term for a movie clip that happens to define at least one button handler. See Section 13.9. See Also Chapter 13, Chapter 14 |
