ScreenOutline object

Availability

Flash MX 2004.

Description

The ScreenOutline object represents the group of screens in a slide or form document. The object is accessed by using fl.getDocumentDOM().screenOutline.

The ScreenOutline object exists only if the document is a slide or form document, so before accessing the property, use document.allowScreens() to verify that a Screens document exists, as shown in the following example:

if(fl.getDocumentDOM().allowScreens) {    var myName =      fl.getDocumentDOM().screenOutline.rootScreen.childScreens[0].name;    fl.trace("The name of the screen is " + myName + ". "); }

Method summary for the ScreenOutline object

You can use the following methods with the ScreenOutline object:

Method	Description
screenOutline.copyScreenFromFile()	Inserts all the screens, or a named screen and its children, from a specified document under the currently selected screen.
screenOutline.deleteScreen()	Deletes the currently selected screen(s), or a specified screen, and the children of the screen(s).
screenOutline.duplicateScreen()	Duplicates the currently selected screen(s) or a specified screen.
screenOutline.getSelectedScreens()	Returns an array of Screen objects that are currently selected in the screen outline.
screenOutline.insertNestedScreen()	Inserts a nested screen of a specific type into a particular location in the screen outline.
screenOutline.insertScreen()	Inserts a new blank screen of a specified type into the document at a specified location.
screenOutline.moveScreen()	Moves the specified screen in relation to the value of the referenceScreen parameter; either before, after, as the first child, or as the last child.
screenOutline.renameScreen()	Changes the screen with a specified name to a new name.
screenOutline.setCurrentScreen()	Sets the current selection in the screen outline to the specified screen.
screenOutline.setScreenProperty()	Lets the specified property with the specified value for the selected screens.
screenOutline.setSelectedScreens()	Selects the specified screens in the Screen Outline pane.

Property summary for the ScreenOutline object

You can use the following properties with the ScreenOutline object:

Property	Description
screenOutline.currentScreen	A Screen object; the currently selected screen.
screenOutline.rootScreen	Read-only; the first screen in the screen outline.
screenOutline.screens	Read-only ; the array of top level Screen objects contained in the document (see Screen object).

screenOutline.copyScreenFromFile()

Availability

Flash MX 2004.

Usage

screenOutline.copyScreenFromFile( fileURI [, screenName] )

Parameters

fileURI A string, expressed as a file:/// URI, that specifies a filename for the authoring file that contains the screens to copy into the document.

screenName The name of the screen to copy. If the screenName parameter is present, Flash copies that screen and its children. If the screenName is not specified, Flash copies the whole document. This parameter is optional.

Returns

Nothing. If the file is not found or is not a valid FLA file, or if the specified screen is not found, an error is reported and the script is cancelled.

Description

Method; inserts all the screens, or a named screen and its children, from a specified document under the currently selected screen. If more than one screen is selected, the screen(s) are inserted under the last selected screen, as its sibling.

Example

The following example copies the "slide1" screen from the myTarget.fla file on the Desktop into the current document (substitute your user name for userName):

fl.getDocumentDOM().screenOutline.copyScreenFromFile("file:///C|/Documents   and Settings/userName/Desktop/myTarget.fla", "slide1");

screenOutline.currentScreen

Availability

Flash MX 2004.

Usage

screenOutline.currentScreen

Description

Property; a Screen object, the currently selected screen (see Screen object).

Example

The following example stores the currentScreen object in the myScreen variable and then displays the name of that screen in the Output panel:

var myScreen = fl.getDocumentDOM().screenOutline.currentScreen; fl.trace(myScreen.name);

screenOutline.deleteScreen()

Availability

Flash MX 2004.

Usage

screenOutline.deleteScreen( [screenName] )

Parameters

screenName A string that specifies the name of the screen to be deleted. If you don't pass a value for screenName, the currently selected screen(s) and their children are deleted. This parameter is optional.

Returns

Nothing.

Description

Method; deletes the currently selected screen(s), or a specified screen, and the children of the screen(s).

Example

The following example removes the screen named apple and all its children:

fl.getDocumentDOM().screenOutline.deleteScreen("apple");

screenOutline.duplicateScreen()

Availability

Flash MX 2004.

Usage

screenOutline.duplicateScreen( [screenName] )

Parameters

screenName A string value that specifies the screen name to duplicate. If you don't pass a value for screenName, the currently selected screen(s) are duplicated. This parameter is optional.

Returns

A Boolean value: true if the screen is successfully duplicated; false otherwise.

Description

Method; duplicates the currently selected screen(s) or a specified screen. The duplicate screens are given a default name by appending _copy to the original name, such as Screen_copy, Screen_copy2, and so on. If you duplicate multiple screens, the duplicates are placed directly below the selected screen that is lowest in the screen outline hierarchy.

Example

The following example duplicates a screen named apple:

fl.getDocumentDOM().screenOutline.duplicateScreen("apple");

screenOutline.getSelectedScreens()

Availability

Flash MX 2004.

Usage

screenOutline.getSelectedScreens()

Parameters

None.

Returns

An array of selected Screen objects (see Screen object).

Description

Method; returns an array of Screen objects that are currently selected in the screen outline.

Example

The following example stores the selected Screen objects in the myArray variable and displays the screen names in the Output panel:

var myArray = fl.getDocumentDOM().screenOutline.getSelectedScreens(); for (var i in myArray) {   fl.trace(myArray[i].name) }

screenOutline.insertNestedScreen()

Availability

Flash MX 2004.

Usage

screenOutline.insertNestedScreen( [ name [, referenceScreen [,   screenTypeName ] ] ])

Parameters

name A string indicating the name of the new screen to insert. An empty name will insert a screen with a default screen name, such as Slide n or Form n (where n is the first available unique number). This parameter is optional.

referenceScreen A string indicating the name of the screen into which the new screen is inserted as a child. If this parameter is omitted, the new screen is inserted as a child of the currently selected screen. This parameter is optional.

screenTypeName A string that specifies the screen type to attach to the new nested screen. The screen type and class name are set for this screen. Acceptable values are "Form" and "Slide". This parameter is optional. If this parameter is omitted, the type is inherited from the parent screen.

Returns

A Screen object.

Description

Method; inserts a nested screen of a specific type into a particular location in the screen outline.

Example

The following example inserts slide2 as a child of slide1:

fl.getDocumentDOM().screenOutline.insertNestedScreen("slide2", "slide1",   "Slide");

screenOutline.insertScreen()

Availability

Flash MX 2004.

Usage

screenOutline.insertScreen( [name [, referenceScreen [, screenTypeName ] ]   ])

Parameters

name A string indicating the name of the new screen to insert. If this parameter is omitted, the method inserts a screen with a default screen name, such as Slide n or Form n (where n is the first available unique number). This parameter is optional.

referenceScreen A string indicating the name of the screen before the new screen. If this parameter is omitted, the new screen is inserted after the currently selected screen. If the referenceScreen parameter identifies a child screen, the new screen will be a peer of the child screen, and a child screen of the same parent. This parameter is optional.

screenTypeName A string that specifies the screen type to attach to the new screen. The screen type and classname are set for this screen. Acceptable values are "Form" and "Slide". This parameter is optional.

Returns

A Screen object.

Description

Method; inserts a new blank screen of a specified type into the document at a specified location.

Example

The following example inserts a form named slide2 after the screen named slide1:

fl.getDocumentDOM().screenOutline.insertScreen("slide2","slide1","Form");

The following example inserts a slide named slide4 after the screen slide3:

fl.getDocumentDOM().screenOutline.insertScreen("slide4","slide3","Slide");

screenOutline.moveScreen()

Availability

Flash MX 2004.

Usage

screenOutline.moveScreen( screenToMove, referenceScreen, position )

Parameters

screenToMove A string that is the screen name to move.

referenceScreen A string that specifies the screen near which screenToMove will be placed.

position A string that specifies where to move the screen in relation to referenceScreen. Acceptable values are "before", "after", "firstChild", and "lastChild".

Returns

A Boolean value: TRue if the move is successful; false otherwise.

Description

Method; moves the specified screen in relation to the value of the referenceScreen parameter; either before, after, as the first child, or as the last child.

Example

The following example moves screen slide1 to be the first child of slide2:

fl.getDocumentDOM().screenOutline.moveScreen("slide1", "slide2",   "firstChild");

screenOutline.renameScreen()

Availability

Flash MX 2004.

Usage

screenOutline.renameScreen( newScreenName [, oldScreenName [,   bDisplayError] ] )

Parameters

newScreenName A string that specifies the new name of the screen

oldScreenName A string that specifies the name of the existing screen to change. If not specified, the name of the currently selected screen changes. This parameter is optional.

bDisplayError A Boolean value that, if set to TRue, shows an error message if an error occurs, for example, if a screen with the same name as the value passed to newScreenName already exists. The default value is false.

Returns

A Boolean value: true if the renaming is successful; false otherwise.

Description

Method; changes the screen with a specified name to a new name.

Example

The following example changes the name of slide1 to Intro:

fl.getDocumentDOM().screenOutline.renameScreen("Intro", "slide1");

screenOutline.rootScreen

Availability

Flash MX 2004.

Usage

screenOutline.rootScreen

Description

Read-only property; the first screen in the screen outline. You can use screenOutline.rootScreen as a shortcut for screenOutline.screens[0].

Example

The following example displays the name of the first child of the first screen in the screen outline:

fl.trace(fl.getDocumentDOM().screenOutline.rootScreen.childScreens[0].name)   ;

screenOutline.screens

Availability

Flash MX 2004.

Usage

screenOutline.screens

Description

Read-only property; the array of top level Screen objects contained in the document (see Screen object).

Example

The following example stores the array of Screen objects in the myArray variable and then displays their names in the Output panel:

var myArray = new Array(); if(fl.getDocumentDOM().allowScreens) {   for(var i in fl.getDocumentDOM().screenOutline.screens) {      myArray.push(" "+fl.getDocumentDOM().screenOutline.screens[i].name);   }   fl.trace("The screens array contains objects whose names are:   "+myArray+". "); }

screenOutline.setCurrentScreen()

Availability

Flash MX 2004.

Usage

screenOutline.setCurrentScreen( name )

Parameters

name A string that specifies the name screen which should become the currently selected screen. If the screen is a child of another screen, you do not need to indicate a path or hierarchy.

Returns

Nothing.

Description

Method; sets the current selection in the screen outline to the specified screen.

Example

The following example sets the current screen to the screen named ChildOfSlide_1:

fl.getDocumentDOM().screenOutline.setCurrentScreen("ChildOfSlide_1");

screenOutline.setScreenProperty()

Availability

Flash MX 2004.

Usage

screenOutline.setScreenProperty( property, value )

Parameters

property A string that specifies the property to set.

value The new value for the property. The type of value depends on the property being set.

For a list of available properties and values, see Property summary for the Screen object.

Returns

Nothing.

Description

Method; sets the specified property with the specified value for the selected screens.

Example

The following example changes the visibility of the currently selected screens from hidden to visible:

fl.getDocumentDOM().screenOutline.setScreenProperty("hidden", false);

screenOutline.setSelectedScreens()

Availability

Flash MX 2004.

Usage

screenOutline.setSelectedScreens ( selection [, bReplaceCurrentSelection ]   )

Parameters

selection An array of screen names to be selected in the screen outline.

bReplaceCurrentSelection A Boolean value that, if TRue, lets you deselect the current selection. The default value is TRue. If false, Flash extends the current selection to include the specified screens. This parameter is optional.

Returns

Nothing.

Description

Method; selects the specified screens in the screen outline. If multiple screens are specified, the screen with the last index value of the selection array is focused on the Stage.

Example

The following example deselects any currently selected screens, and then selects screens slide1, slide2, slide3, and slide4 in the screen outline:

myArray = new Array("slide1", "slide2", "slide3", "slide4"); fl.getDocumentDOM().screenOutline.setSelectedScreens(myArray, true);