Table of Contents

Constructor

new 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 ^[5] 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 ^[6] 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

Property name	Access	Type	Property description
_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[5][6]	R/W	string	Assigns the clickable area for a button-enabled movie clip
_name[5]	R/W	string	Identifier of an instance as a string (not a reference)
_parent[5]	RO	MovieClip reference	A reference to the instance or movie that contains the current instance
_rotation	R/W	number	Degrees of rotation
tabChildren[5][6]	R/W	Boolean	Controls whether contained objects are included in the automatic tab order
tabEnabled[5][6]	R/W	Boolean	Includes or excludes the movie clip from the current tab order
tabIndex[5][6]	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[5][6]	R/W		Modifies the onRelease( ) handler requirements, enabling menu-style behavior
_url	RO	string	Disk or network location of the source .swf file
useHandCursor[5][6]	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

^[5] Applies to movie clip instances only; does not apply to the main timeline (_root).

^[6] New in Flash 6. Not supported in prior versions.

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 ^[8]. Methods introduced in Flash 6 are marked by ^[7] in the tables. The movie clip methods marked by ^[9] 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

Method name	Method description
attachMovie( )	Creates a new instance based on an exported symbol from the current document's Library
createEmptyMovieClip( )[7]	Creates a new, empty MovieClip instance
createTextField( )[7]	Creates a new TextField object
duplicateMovieClip( )[8][9]	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( )[7]	Returns the movie clip's position in the visual content stack
getURL( )[9]	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( )[9]	Moves the playhead of an instance or movie to a specific frame and then plays the instance or movie
gotoAndStop( )[9]	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( )[9]	Loads an external .swf file into the Player
loadVariables( )[9]	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( )[9]	Moves the playhead of an instance or movie ahead one frame and stops it there
play( )[9]	Starts the playhead of an instance or movie in motion (i.e., plays the clip)
prevFrame( )[9]	Moves the playhead of an instance or movie back one frame and stops it there
removeMovieClip( )[8][9]	Deletes a duplicated or attached instance
setMask( )[7]	Assigns a movie clip as a mask for another clip
startDrag( )[9]	Causes an instance or movie to follow the mouse pointer physically
stop( )[9]	Halts the playback of an instance or movie
stopDrag( )[9]	Ends any drag operation in progress
swapDepths( )[8]	Alters the position of an instance in the content stack
unloadMovie( )[9]	Removes an instance or main movie from a document level or host clip
valueOf( )	Returns an object reference to the instance

^[7] New in Flash 6. Not supported in prior versions.

^[8] Applies to movie clip instances only; does not apply to the main timeline (_root).

^[9] MovieClip method that is analogous to a global function of the same name.

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

Method name	Method description
beginFill( )[10]	Starts a solid-filled shape
beginGradientFill( )[10]	Starts a gradient-filled shape
clear( )[10]	Removes all drawings from the movie clip
curveTo( )[10]	Draws a curved line
endFill( )[10]	Finishes a filled shape
lineStyle( )[10]	Sets stroke thickness, color, and transparency
lineTo( )[10]	Draws a straight line
moveTo( )[10]	Moves the drawing pen to a new position without drawing a line

^[10] New in Flash 6. Not supported in prior versions.

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 ^[11] 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

Clip event handler	Clip event occurs when...	Flash 5 equivalent
onData( )	The clip receives the end of a stream of loaded variables, or a portion of a loaded movie	onClipEvent(data)
onDragOut( )[11]	The mouse is pressed over the clip, then the mouse moves off the clip before the mouse is released	None
onDragOver( )[11]	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( )[11]	The clip loses keyboard focus	None
onLoad( )[11]	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( )[11]	The mouse is pressed over the clip	None
onRelease( )	The mouse is pressed and then released over the clip	None
onReleaseOutside( )[11]	The mouse is pressed over the clip and then released after moving off the clip	None
onRollOut( )[11]	The mouse pointer moves off the clip while the mouse button is not depressed	None
onRollOver( )[11]	The mouse pointer moves over the clip while the mouse button is not depressed	None
onSetFocus( )[11]	The clip gains keyboard focus	None
onUnload( )[11]	The clip is removed from the Stage	onClipEvent(unload)

^[11] Applies to movie clip instances only; does not apply to the main timeline (_root).

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

Table of Contents