The MovieClip Class

     

The MovieClip Class

Table A.4. MovieClip Methods

Method

Format

Description

attachMovie

myClip.attachMovie( idName , newName, depth [, initObject ] )

Attaches a movie in the Library to myClip , with the specified depth. The attached movie has all the local properties of the init object.

Returns a reference to the attached movie.

createEmptyMovieClip

myClip.createEmptyMovieClip ( instanceName, depth )

Creates an empty movie clip as a child of myClip , with the specified depth.

createTextField

myClip.createTextField ( instanceName, depth, x, y, width, height )

Creates an empty text field, with the specified instance name , depth, x and y coordinates, width, and height.

duplicateMovieClip

myClip.duplicateMovieClip( newName, depth [, initObject ])

Duplicates myClip , creating a sibling at the specified depth. The new movie has all the local properties of the init object.

getBounds

myClip.getBounds ( targetCoordinateSpace )

Returns the minimum and maximum x and y coordinates of myClip in relation to a specified coordinate space.

getBytesLoaded

myClip.getBytesLoaded()

Returns the number of bytes loaded for myClip .

getBytesTotal

myClip.getBytesTotal()

Returns the size of myClip in bytes.

getDepth

myClip.getDepth()

Returns the depth number of myClip

getInstanceAtDepth

myClip.getInstanceAtDepth( depth )

Returns the name of the child clip of myClip located at the depth number specified by the depth parameter. If there is no child movie clip at that depth, returns undefined . FP7 only.

getNextHighestDepth

myClip.getNextHighest Depth()

Returns a number equal to the highest depth number plus one for children of myClip . This is the depth number you need to use to create new child content that will render on top of all existing child content. FP7 only.

getSWFVersion

myClip.getSWFVersion()

Returns an integer specifying the targeted Flash Player version of the SWF loaded into myClip . Returns a -1 error if a JPEG was loaded into myClip . FP7 only.

getTextSnapshot

myClip.getTextSnapshot()

Returns a TextSnapShot object containing the static text from myClip , or an empty string if myClip contains no static text. Works in FP7 only, but myClip can be targeted for FP6 or FP7.

getURL( URL [, window , variables ])

myClip.getURL("http://www.myDomain.com")_

Loads a document into a browser window from the specified URL, sending all the variables from the root of myClip using GET or POST , as specified in the variables string.

globalToLocal

myClip.globalToLocal( point )

Converts the point object from main movie Stage coordinates to the local coordinates of myClip

gotoAndPlay

myClip.gotoAndPlay( frame )

Sends the playhead to a specific frame in myClip and then starts playing the movie.

gotoAndStop

myClip.gotoAndStop( frame )

Sends the playhead to a specific frame in myClip and then stops the movie.

hitTest

myClip.hitTest( x, y, shapeFlag )

Returns true if myClip 's bounding box overlaps the point specified by the x and y coordinates. shapeFlag is a Boolean value that determines whether the entire shape of myClip is evaluated ( true ), or just myClip 's bounding box ( false ).

myClip.hitTest( target )

Returns true if myClip 's bounding box intersects the bounding box of the target movie clip.

loadMovie

myClip.loadMovie(" url " [, variables ])

Loads the movie or JPEG specified in " url " into myClip , using GET or POST , as specified in the variables string. If targeting FP7, use MovieClipLoader instead of this.

loadVariables

myClip.loadVariables(" url ", variables )

Loads variables from a URL or other location into myClip .

localToGlobal

myClip.localToGlobal( point )

Converts a point object from the local coordinates of myClip to the global Stage coordinates.

nextFrame

myClip.nextFrame() frame of myClip .

Sends the playhead to the next

play

myClip.play()

Plays myClip

prevFrame

myClip.prevFrame()

Sends the playhead to the previous frame of myClip .

removeMovieClip

myClip.removeMovieClip()

Removes myClip from the Timeline if it was created through the use of attachMovie() , duplicateMovieClip() , or createEmptyMovieClip() .

setMask

myClip.setMask ( maskMovieClip )

Specifies a movie clip as a mask for myClip .

startDrag

myClip.startDrag([ lock , [ left, top, right, bottom ]])

Makes myClip draggable and begins dragging myClip . If the value of lock is true , the mouse pointer remains centered on myClip 's registration point. The left, top, right , and bottom values specify coordinates beyond which myClip cannot be dragged.

stop

myClip.stop()

Pauses myClip .

stopDrag

myClip.stopDrag()

Stops the dragging of any clip that is being dragged (not just myClip ). Exact equivalent of global function stopDrag() .

swapDepths

myClip.swapDepths( depth )

Puts myClip at the specified depth. If there is a movie clip at that depth, it is moved to myClip 's former depth level.

myClip.swapDepths( target )

Swaps the depth levels of myClip and the target movie clip.

unloadMovie

myClip.unloadMovie()

Removes myClip if it was loaded with loadMovie() . Also works for JPEGs loaded with loadMovie() .

Legend: (na) not available (undocumented method)


Table A.5. MovieClip Attributes

Attribute

Description

_alpha

Transparency/opacity, an integer from 0 “100.

_currentframe

Current frame number, an integer, read-only.

_droptarget

A read-only string containing the absolute path in slash syntax notation of the movie clip instance on which a draggable movie clip was dropped.

enabled

A Boolean that determines whether a button movie clip is enabled.

focusEnabled

A Boolean that determines whether a movie clip can receive focus.

_focusrect

A Boolean that determines whether a focused movie clip has a yellow rectangle around it.

_framesloaded

An integer; the number of frames that have been loaded into memory, read-only.

_height

The height of a movie clip instance, in pixels; a floating-point number.

hitArea

The movie clip that defines the hit area for a button movie clip.

_lockroot

"Locks" the reference of _root in an SWF, so it doesn't change when the SWF is loaded into another movie clip.

_quality

A string that determines rendering quality: LOW , MEDIUM , HIGH , BEST .

menu

Works with the new ContextMenu and ContextMenuItem classes to let you create a new context menu for a MovieClip.

_name

The instance name, a string.

_parent

A reference to the movie clip's parent clip.

_rotation

A floating-point number; the number of degrees of rotation from the clip's original orientation.

_soundbuftime

An integer; the number of seconds of sound to prebuffer before starting to play the sound.

tabChildren

A Boolean; determines whether the children of a movie clip are included in automatic tab ordering.

tabEnabled

A Boolean; determines whether a movie clip is included in tab ordering.

tabIndex

Determines the tab order of the clip.

_target

The target path of the clip.

_totalframes

The total number of frames in the clip.

trackAsMenu

A Boolean that determines whether, if the user presses the mouse button over this button movie clip (or button) and releases it over a different one, the second one receives a release event.

_url

A read-only string; the location of the SWF file from which the clip was downloaded.

useHandCursor

A Boolean that enables and disables the display of the hand cursor for a button movie clip.

_visible

A Boolean value that determines whether a clip instance is hidden or visible.

_width

The width of a movie clip instance, in pixels; a floating-point number.

_x

The x coordinate of a clip instance; a floating-point number.

_xmouse

The x coordinate of the mouse cursor within a clip instance; a floating-point number.

_xscale

A floating-point number specifying a percentage for horizontally scaling a clip instance.

_y

The y coordinate of a clip instance; a floating-point number.

_ymouse

The y coordinate of the cursor within a clip instance; a floating-point number.

_yscale

A floating-point number specifying a percentage for vertically scaling a clip instance.


Notes on Movie Clip Methods and Attributes

Six attributes ” _focusrect , enabled , focusEnabled , hitArea , trackAsMenu , and useHandCursor ”enable and disable button-like functionality for movie clips and button movie clips. Flash 5 had a _focusrect global variable, which still exists in Flash MX. In addition, buttons and movie clips now have a _focusrect property.

Three movie clip attributes ” tabChildren , tabEnabled , and tabIndex ”control tab ordering , the sequence of text fields, buttons, and/or movie clips that receive keyboard focus as the user presses Tab or Shift+Tab. The typical application is using the Tab key to move from one field to the next while filling out a form.

Enabling and Disabling the Yellow Focus Rectangle

Flash displays a yellow rectangle over a button or button movie clip that has keyboard focus, unless you've done something to suppress this feature. You can enable and disable the yellow focus rectangle on a global basis by using the global _focusrect property. If _focusrect is set to true (the default), the yellow rectangle appears. If _focusrect is set to false , as in the following example, the yellow rectangle does not appear. In that case, buttons and button movie clips display their Over state when they have keyboard focus.

 _focusrect = false; // focus rectangle is disabled globally 

You can enable and disable the yellow focus rectangle for an individual movie clip or button instance by using the _focusrect property of the instance. If _focusrect is set to true (the default), the yellow rectangle appears when the instance gets focus. If _focusrect is set to false , as in the following example, the yellow rectangle does not appear when the instance gets focus. In that case, a button or button movie clip displays its Over state when it has keyboard focus.

 myButton._focusrect = false; // focus rectangle is disabled for graphics/ccc.gif myButton 


If you do nothing about tab ordering, Flash implements automatic tab ordering. That is, it sets up a default order in which items take focus. For example, if you create a form with a number of input text fields in a single column, the default tab ordering, which is simply top-to-bottom, may be perfectly acceptable. Alternatively, you can explicitly set up a custom tab order, which disables automatic tab ordering for the entire document, including any SWFs loaded with loadMovie() or loadMovieNum() . This might be required in a more complex form.

enabled

The enabled property enables and disables button-type functionality in a movie clip. The default is true . Set enabled to false , as shown in the following example, and the hand cursor does not appear; button event handlers are no longer called; and _over , _down , and _up frames are disabled:

 myButtonClip.enabled = false; // no more button functionality 

Even when enabled is false , the movie clip continues to be included in tab ordering, and MovieClip , Mouse , and Key event handlers continue to function.

focusEnabled

The focusEnabled property allows you to enable and disable focus- related event handlers for movie clips.

Text fields, buttons, button movie clips, and ordinary movie clips can all have onSetFocus and onKillFocus event handlers that fire in response to Selection.setFocus() . For text fields, buttons, and button movie clips, these two focus-related event handlers are enabled by default. For ordinary movie clips, these event handlers are disabled by default. If you set the focusEnabled property of an ordinary movie clip to true , its onSetFocus and onKillFocus event handlers fire in response to Selection.setFocus() .

The following example is based on sample movie focusenabled.fla:

 myClip.onSetFocus = function(oldFocus) {      trace("focus was "+oldFocus+ ", new focus is myClip"); }; myClip.focusEnabled = true; // allows myClip.onSetFocus above to fire Selection.setFocus(myClip); // myClip.onSetFocus fires 

Here are four facts about the focusEnabled property:

  • By default, it is undefined , which is equivalent to false .

  • It is unnecessary if tabEnabled is true . ( tabEnabled enables focus.)

  • It has no effect on a text field, button, or button movie clip.

  • It enables event handlers associated with a single movie clip ” myClip in the preceding example. It fires myClip.onSetFocus only when myClip gets focus. If you want myClip.onSetFocus to fire on every change of focus (for other objects, as well as myClip) , define a listener instead of or in addition to setting focusEnabled to true :

     Selection.addListener(myClip); 

If you both define a listener and set focusEnabled to true , myClip.onSetFocus fires twice when myClip gets focus.

You can also use focusEnabled to enable a movie clip to take focus, even though that clip has no onSetFocus event handler. In the following example, focusenabled2.fla on the CD, the movie clip ( myMc ) takes focus, but another object ( myObj ) listens for the event.

 function MyClass () {} MyClass.prototype.onSetFocus = function(){  trace("MyClass.prototype.onSetFocus"); } myObj = new MyClass(); myMc.focusEnabled=true; Selection.addListener(myObj); Selection.setFocus(myMc) ; 

hitArea

The hitArea property enables you to designate any movie clip as a hit area. For button movie clips, as in this example, when the mouse is over the hit area clip, the mouse pointer changes to a hand cursor, and the button movie clip is clickable:

 myButtonClip.hitArea = myButtonClip.myHitClip; 

You can reassign hitArea to a different clip at any time. You can change the size or shape of the hitArea clip. And you can make the hitArea clip invisible, without affecting the button movie clip's clickability. If you don't assign a hitArea clip, or you assign one that doesn't actually exist, the button movie clip itself becomes the hit area by default.

Enabling the Hit Area Feature

Just assigning a hit area to an ordinary movie clip has no effect. Even if you add useHandCursor = true (as described in the "useHandCursor" section later in this appendix), you see no effect. You can achieve clickability and get a hand cursor by assigning a button event handler to the movie clip, making it a button movie clip. Then the hit area feature is functional, as well.


tabChildren

The tabChildren property allows you to exclude a movie clip's children from tab ordering and later to re-include them. This capability could be useful, for instance, if certain fields in a form needed to be filled in only under certain conditions. When those conditions were met, you would set the tabChildren property to true .

By default, the children of a tab- enabled movie clip are tab- disabled (not included in tab ordering). So if you have a user interface component made up of multiple movie clips, for instance, and you always want to treat it as a single tab stop, you don't have to do anything special.

If you sometimes want the children tab-enabled and sometimes tab-disabled, you first tab-enable them (for instance, using the tabEnabled property). Then, if you later want to disable them again, set tabChildren to false . When you want to re-enable them, set tabChildren to true .

If tabChildren is undefined (the default), the children are tab-enabled as soon as you set the tabEnabled property to true or make the movie clip into a button movie clip.

tabEnabled

The tabEnabled property causes the movie clip to be included in either automatic or custom tab ordering, whichever is currently in force in the document. The movie clip can also take focus.

tabIndex

Changing the tabIndex property to a positive integer (from its default, which is undefined ) causes the movie clip to be included in custom tab ordering and enables the movie clip to take focus. The movie clip's place in the tab sequence is determined by the integer: A movie clip with a lower tab index receives focus before a movie clip with a higher tab index.

Setting even one tabIndex property in a document disables automatic tab ordering for the entire document.

trackAsMenu

Normally, an onRelease event occurs when the user presses and releases the mouse button over a single button or button movie clip. With a drop-down menu, you may want the user to press the mouse button over one button, causing the drop-down menu to appear, and then move the mouse to the button representing the desired selection and release it there. The "track as menu" option enables this behavior.

You assign an onPress event handler to the button or button movie clip that reveals the drop-down menu. To the other buttons or button movie clips, you assign an onRelease event and the "track as menu" tracking behavior.

You can assign the "track as menu" behavior to a button in two ways: through the Property inspector or by using ActionScript and the trackAsMenu property. With a button movie clip, you must use ActionScript.

In sample movie options.fla, the "track as menu" tracking behavior is assigned to buttons. ActionScript was used for one option, as shown in the following example, and the Property inspector for the others. Sample movie options2.fla uses button movie clips and ActionScript. Sample movie wapsec.fla demonstrates the default "track as button" behavior.

 option1.trackAsMenu =  true; 

useHandCursor

Button movie clips display the hand cursor by default. You can suppress this behavior by setting the useHandCursor property to false , as shown in the following example, and re-enable it by setting the useHandCursor property to true :

 myButtonClip.useHandCursor = false; 

For an example of useHandCursor in action, see spacelisten.fla on the CD accompanying this book.


The hand cursor is also suppressed if you set the movie clip's enabled or tabEnabled property to false .

Just setting useHandCursor = true on an ordinary movie clip has no effect. You can achieve clickability and get a hand cursor by assigning a button event handler to the movie clip, making it a button movie clip. Then you can use useHandCursor = false to suppress the hand cursor, if you want.



Using Macromedia Studio MX 2004
Special Edition Using Macromedia Studio MX 2004
ISBN: 0789730421
EAN: 2147483647
Year: N/A
Pages: 339

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net