SymbolInstance object

Inheritance Element object > Instance object > SymbolInstance object

Availability

Flash MX 2004.

Description

SymbolInstance is a subclass of the Instance object and represents a symbol in a frame (see Instance object).

Property summary for the SymbolInstance object

In addition to the Instance object properties, the SymbolInstance object has the following properties:

Property	Description
symbolInstance.accName	A string that is equivalent to the Name field in the Accessibility panel.
symbolInstance.actionScript	A string that specifies the actions assigned to the symbol.
symbolInstance.blendMode	A string that specifies the blend mode to be applied to a movie clip symbol.
symbolInstance.buttonTracking	A string that, for button symbols only, sets the same property as the pop-up menu for Track as Button or Track as Menu Item in the Property inspector.
symbolInstance.cacheAsBitmap	A Boolean value that specifies whether runtime bitmap caching is enabled.
symbolInstance.colorAlphaAmount	An integer that is part of the color transformation for the instance, specifying the Advanced Effect Alpha settings; equivalent to using the Color > Advanced setting in the Property inspector and adjusting the controls on the right of the dialog box.
symbolInstance.colorAlphaPercent	An integer that specifies part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box).
symbolInstance.colorBlueAmount	An integer that is part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector.
symbolInstance.colorBluePercent	An integer that is part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box).
symbolInstance.colorGreenAmount	An integer that is part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector. Allowable values are from -255 to 255.
symbolInstance.colorGreenPercent	Part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box).
symbolInstance.colorMode	A string that specifies the color mode as identified in the symbol Property inspector Color pop-up menu.
symbolInstance.colorRedAmount	An integer that is part of the color transformation for the instance, equivalent to using the Color > Advanced setting in the instance Property inspector.
symbolInstance.colorRedPercent	Part of the color transformation for the instance; equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box).
symbolInstance.description	A string that is equivalent to the Description field in the Accessibility panel.
symbolInstance.filters	An array of Filter objects (see Filter object).
symbolInstance.firstFrame	A zero-based integer that specifies the first frame to appear in the timeline of the graphic.
symbolInstance.forceSimple	A Boolean value that enables and disables the accessibility of the object's children; equivalent to the inverse logic of the Make Child Objects Accessible setting in the Accessibility panel.
symbolInstance.loop	A string that, for graphic symbols, sets the same property as the Loop pop-up menu in the Property inspector.
symbolInstance.shortcut	A string that is equivalent to the shortcut key associated with the symbol; equivalent to the Shortcut field in the Accessibility panel.
symbolInstance.silent	A Boolean value that enables or disables the accessibility of the object; equivalent to the inverse logic of the Make Object Accessible setting in the Accessibility panel.
symbolInstance.symbolType	A string that specifies the type of symbol; equivalent to the value for Behavior in the Create New Symbol and Convert To Symbol dialog boxes.
symbolInstance.tabIndex	An integer that is equivalent to the Tab index field in the Accessibility panel.

symbolInstance.accName

Availability

Flash MX 2004.

Usage

symbolInstance.accName

Description

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers identify objects by reading the name aloud. This property is not available for graphic symbols.

Example

The following example stores the value for the Accessibility panel name of the object in the theName variable:

var theName = fl.getDocumentDOM().selection[0].accName;

The following example sets the value for the Accessibility panel name of the object to "Home Button":

fl.getDocumentDOM().selection[0].accName = "Home Button";

symbolInstance.actionScript

Availability

Flash MX 2004.

Usage

symbolInstance.actionScript

Description

Property; a string that specifies the actions assigned to the symbol. This applies only to movie clip and button instances. For a graphic symbol instance, the value returns undefined.

Example

The following example assigns an onClipEvent action to the first item in the first frame of the first layer in the timeline:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].actionScr   ipt   = "onClipEvent(enterFrame) {trace('movie clip enterFrame');}";

symbolInstance.blendMode

Availability

Flash 8.

Usage

symbolInstance.blendMode

Description

Property; a string that specifies the blend mode to be applied to a movie clip symbol. Acceptable values are "normal", "layer", "multiply", "screen", "overlay", "hardlight", "lighten", "darken", "difference", "add", "subtract", "invert", "alpha", and "erase".

Example

The following example sets the blend mode for the first movie clip symbol in the first frame on the first level to "add":

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].blendMode   = 'add';

See also

document.setBlendMode()

symbolInstance.buttonTracking

Availability

Flash MX 2004.

Usage

symbolInstance.buttonTracking

Description

Property; a string that, for button symbols only, sets the same property as the pop-up menu for Track as Button or Track as Menu Item in the Property inspector. For other types of symbols, this property is ignored. Acceptable values are "button" or "menu".

Example

The following example sets the first symbol in the first frame of the first layer in the timeline to Track as Menu Item, as long as that symbol is a button:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].buttonTra   cking = "menu";

symbolInstance.cacheAsBitmap

Availability

Flash 8.

Usage

symbolInstance.cacheAsBitmap

Description

Property; a Boolean value that specifies whether runtime bitmap caching is enabled.

Example

The following example enables runtime bitmap caching for the first element in the first frame on the first layer:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].cacheAsBi   tmap = true;

symbolInstance.colorAlphaAmount

Availability

Flash MX 2004.

Usage

symbolInstance.colorAlphaAmount

Description

Property; an integer that is part of the color transformation for the instance, specifying the Advanced Effect Alpha settings. This property is equivalent to using the Color > Advanced setting in the Property inspector and adjusting the controls on the right of the dialog box. This value either reduces or increases the tint and alpha values by a constant amount. This value is added to the current value. This property is most useful if used with symbolInstance.colorAlphaPercent. Allowable values are from -255 to 255.

Example

The following example subtracts 100 from the alpha setting of the selected symbol instance:

fl.getDocumentDOM().selection[0].colorAlphaAmount = -100;

symbolInstance.colorAlphaPercent

Availability

Flash MX 2004.

Usage

symbolInstance.colorAlphaPercent

Description

Property; an integer that specifies part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box). This value changes the tint and alpha values to a specified percentage. Allowable values are from -100 to 100. See also symbolInstance.colorAlphaAmount.

Example

The following example sets the colorAlphaPercent of the selected symbol instance to 80:

fl.getDocumentDOM().selection[0].colorAlphaPercent = 80;

symbolInstance.colorBlueAmount

Availability

Flash MX 2004.

Usage

symbolInstance.colorBlueAmount

Description

Property; an integer that is part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector. Allowable values are from -255 to 255.

symbolInstance.colorBluePercent

Availability

Flash MX 2004.

Usage

symbolInstance.colorBluePercent

Description

Property; an integer that is part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box). This value sets the blue values to a specified percentage. Allowable values are from -100 to 100.

Example

The following example sets the colorBluePercent of the selected symbol instance to 80: fl.getDocumentDOM().selection[0].colorBluePercent = 80;

symbolInstance.colorGreenAmount

Availability

Flash MX 2004.

Usage

symbolInstance.colorGreenAmount

Description

Property; an integer that is part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector. Allowable values are from -255 to 255.

symbolInstance.colorGreenPercent

Availability

Flash MX 2004.

Usage

symbolInstance.colorGreenPercent

Description

Property; part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box). This value sets the green values by a specified percentage. Allowable values are from -100 to 100.

Example

The following example sets the colorGreenPercent of the selected symbol instance to 70:

fl.getDocumentDOM().selection[0].colorGreenPercent = 70;

symbolInstance.colorMode

Availability

Flash MX 2004.

Usage

symbolInstance.colorMode

Description

Property; a string that specifies the color mode as identified in the symbol Property inspector Color pop-up menu. Acceptable values are "none", "brightness", "tint", "alpha", and "advanced".

Example

The following example changes the colorMode property of the first element in the first frame of the first layer in the timeline to "alpha":

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].colorMode   = "alpha";

symbolInstance.colorRedAmount

Availability

Flash MX 2004.

Usage

symbolInstance.colorRedAmount

Description

Property; an integer that is part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector. Allowable values are from -255 to 255.

Example

The following example sets the colorRedAmount of the selected symbol instance to 255:

fl.getDocumentDOM().selection[0].colorRedAmount = 255;

symbolInstance.colorRedPercent

Availability

Flash MX 2004.

Usage

symbolInstance.colorRedPercent

Description

Property; part of the color transformation for the instance. This property is equivalent to using the Color > Advanced setting in the instance Property inspector (the percentage controls on the left of the dialog box). This value sets the red values to a specified percentage. Allowable values are from -100 to 100.

Example

The following example sets the colorRedPercent of the selected symbol instance to 10:

fl.getDocumentDOM().selection[0].colorRedPercent = 10;

symbolInstance.description

Availability

Flash MX 2004.

Usage

symbolInstance.description

Description

Property; a string that is equivalent to the Description field in the Accessibility panel. The description is read by the screen reader. This property is not available for graphic symbols.

Example

The following example stores the value for the Accessibility panel description of the object in the theDescription variable:

var theDescription = fl.getDocumentDOM().selection[0].description;

The following example sets the value for the Accessibility panel description to "Click the home button to go to home":

fl.getDocumentDOM().selection[0].description= "Click the home button to go   to home";

symbolInstance.filters

Availability

Flash 8.

Usage

symbolInstance.filters

Description

Property; an array of Filter objects (see Filter object). To modify filter properties, you don't write to this array directly. Instead, retrieve the array, set the individual properties, and then set the array to reflect the new properties.

Example

The following example traces the name of the filter at index 0. If it is a Glow filter, its blurX property is set to 100 and the new value is written to the filters array.

var filterName =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].filter   s[0].name; fl.trace(filterName); var filterArray =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].filter   s; if (filterName == 'glowFilter'){   filterArray[0].blurX = 100; } fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].filters =   filterArray;

symbolInstance.firstFrame

Availability

Flash MX 2004.

Usage

symbolInstance.firstFrame

Description

Property; a zero-based integer that specifies the first frame to appear in the timeline of the graphic. This property applies only to graphic symbols and sets the same property as the First field in the Property inspector. For other types of symbols, this property is undefined.

Example

The following example specifies that Frame 11 should be the first frame to appear in the timeline of the specified element:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].firstFram   e = 10;

symbolInstance.forceSimple

Availability

Flash MX 2004.

Usage

symbolInstance.forceSimple

Description

Property; a Boolean value that enables and disables the accessibility of the object's children. This property is equivalent to the inverse logic of the Make Child Objects Accessible setting in the Accessibility panel. For example, if forceSimple is true, it is the same as the Make Child Object Accessible option being unchecked. If forceSimple is false, it is the same as the Make Child Object Accessible option being checked.

This property is available only for movie clip objects.

Example

The following example checks to see if the children of the object are accessible; a return value of false means the children are accessible:

var areChildrenAccessible = fl.getDocumentDOM().selection[0].forceSimple;

The following example allows the children of the object to be accessible:

fl.getDocumentDOM().selection[0].forceSimple = false;

symbolInstance.loop

Availability

Flash MX 2004.

Usage

symbolInstance.loop

Description

Property; a string that, for graphic symbols, sets the same property as the Loop pop-up menu in the Property inspector. For other types of symbols, this property is undefined. Acceptable values are "loop", "play once", and "single frame" to set the graphic's animation accordingly.

Example

The following example sets the first symbol in the first frame of the first layer in the timeline to Single Frame (display one specified frame of the graphic timeline), as long as that symbol is a graphic:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].loop =   'single frame';

symbolInstance.shortcut

Availability

Flash MX 2004.

Usage

symbolInstance.shortcut

Description

Property; a string that is equivalent to the shortcut key associated with the symbol. This property is equivalent to the Shortcut field in the Accessibility panel. This key is read by the screen readers. This property is not available for graphic symbols.

Example

The following example stores the value for the shortcut key of the object in the theShortcut variable:

var theShortcut = fl.getDocumentDOM().selection[0].shortcut;

The following example sets the shortcut key of the object to "Ctrl+i":

fl.getDocumentDOM().selection[0].shortcut = "Ctrl+i";

symbolInstance.silent

Availability

Flash MX 2004.

Usage

symbolInstance.silent

Description

Property; a Boolean value that enables or disables the accessibility of the object. This property is equivalent to the inverse logic of the Make Object Accessible setting in the Accessibility panel. For example, if silent is true, it is the same as the Make Object Accessible option being unchecked. If silent is false, it is the same as the Make Object Accessible option being checked.

This property is not available for graphic objects.

Example

The following example checks to see if the object is accessible; a return value of false means the object is accessible:

var isSilent = fl.getDocumentDOM().selection[0].silent;

The following example sets the object to be accessible:

fl.getDocumentDOM().selection[0].silent = false;

symbolInstance.symbolType

Availability

Flash MX 2004.

Usage

symbolInstance.symbolType

Description

Property; a string that specifies the type of symbol. This property is equivalent to the value for Behavior in the Create New Symbol and Convert To Symbol dialog boxes. Acceptable values are "button", "movie clip", and "graphic".

Example

The following example sets the first symbol in the first frame of the first layer in the timeline of the current document to behave as a graphic symbol:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].symbolTyp   e = "graphic";

symbolInstance.tabIndex

Availability

Flash MX 2004.

Usage

symbolInstance.tabIndex

Description

Property; an integer that is equivalent to the Tab index field in the Accessibility panel. Creates a tab order in which objects are accessed when the user presses the Tab key. This property is not available for graphic symbols.

Example

The following example sets the tabIndex property of the mySymbol object to 3 and displays that value in the Output panel:

var mySymbol = fl.getDocumentDOM().selection[0]; mySymbol.tabIndex = 3; fl.trace(mySymbol.tabIndex);