This Document
The "1: prepareMovie" Movie Script
gWFSMultiSpriteList
Public Handlers

See Also
"3: Window Manager" behavior API
"Menu Manager" behavior API

Site Nav

• Home
• Tutorial Docs
  • 1: Creating Windows
  • 2: Creating Menus
  • 3: The Score
  • 4: wfsAddElementToManager
  • 5: wfsSetParent, wfsSetChild
  • 6: wfsWriteMultiSprite
  • 7: wfsWriteMultiSpriteFamily
  • 8: wfsWriteElement
  • 9: Dynamism API
  • 10: Dynamism API (cont)
• Window Docs
  • 1: prepareMovie
  • 2: Window Manager
  • 3: Window Manager
  • 4: Win/Menu Element
  • 5: Close My Window
  • 6: Handle
  • 6b: Handle
  • 7: Open A Window
  • Drag Element
  • Drag Element b
  • Close A Window
  • Rollover
  • Cursor Control
• Menu Docs
  • 1: prepareMovie
  • Menu Manager
  • Menu Manager
  • 4: Win/Menu Element
  • Menu Verb
  • 6: Handle
  • 6b: Handle
  • 7: Open A Window
  • Drag Element
  • Drag Element b
  • Menu item highlight
  • Menu item highlight
  • Rollover
  • Arrow for menus
• Dynamism
  • Script Writer
  • wfsWriteMultiSprite
  • wfsWriteMultiSpriteFamily
  • wfsWriteElement
  • wfsWriteSpriteCode
  • wfsWriteBehaviorCode
  • wfsWriteSpriteAndBehavior
  • Dynamism
  • Dynamic Channel Mgr
  • Constructors, Attachers...
  • Destructors
  • Miscellaneous
  • Limitations, Bugs
• Other Docs
  • Mouse Handlers & WFS
  • Troubleshooting Rules
  • API Index
  • Director Resources
• Update Info
• Credits
• Purchase

css drop down menu by Css3Menu.com

1: prepareMovie

The "1: prepareMovie" Movie Script

Every project that uses WFS must have a copy of the "1: prepareMovie" movie script in its Cast. If you don't have one in your Cast, WFS will issue an error message to you requesting that you drag and drop a copy of it from the Library Palette into your Cast.

The "1: prepareMovie" movie script just sits in your Cast. You don't drag and drop it onto anything in the Score. In Director, movie scripts are different from behaviors. Movie scripts are typically used as the place where you write an 'on prepareMovie' handler that executes before the movie begins, to initialize any global variables and such.

And that's just what WFS uses it for. The "1: prepareMovie" handler does indeed contain an 'on prepareMovie' handler that initializes some global variables used in WFS. It also creates some parent script objects. It also contains a stopMovie handler.

This script contains an extensive API for use by programmers. Check it out. But if you're not a programmer, ignore it.

The "1: prepareMovie" handler also contains the WFS stopMovie handler. It does two things. If the "Dynamism" script is in a cast, that means you are using dynamic sprites, so stopMovie calls wfsCleanupDynamicChannels, a handler in the "Dynamism" script, which does garbage collection and destroys all dynamic sprites. The stopMovie handler also voids the gWFSHandle variable, which is used by the "6: Handle" behavior, and the gWFSDragElement variable, used by the "Drag Element" behavior.

All globals in WFS start with "gWFS". So don't name your globals such that they start with "gWFS". All WFS handler names start with "wfs". So don't name your handlers such that they start with "wfs". All WFS properties start with "pWFS". So don't name your properties such that they start with "pWFS". If you follow these simple naming rules, you won't have any name-space conflicts with WFS.

gWFSMultiSpriteList (for Programmers)

The "1: prepareMovie" handler initializes the global variable gWFSMultiSpriteList. It contains entries for both windows and menus.

It is a sorted property list (sorted by spritenum). For each instantiated window or menu, there will be a property and a value in gWFSMultiSpriteList. For instance, if there is just one Manager currently instantiated named 'window1' and it's sprite 38, then gWFSMultiSpriteList=[38:"window1"]. If you then add another Manager named 'window2' and it's sprite 58, then gWFSMultiSpriteList=[38:"window1", 58:"window2"]

Managers add themselves to this list in their 'on beginSprite' handler and delete themselves from this list in their 'on endSprite' handler. So gWFSMultiSpriteList is a list of the currently instantiated Managers.

Actually, Managers call the wfsAddManagerToMultiSpriteList handler in their 'on beginSprite' handler. wfsAddManagerToMultiSpriteList is a handler in the "1: prepareMovie" script. And it is this handler that adds the Manager to gWFSMultiSpriteList, as long as there is not already some other Manager in gWFSMultiSpriteList that has the same name. Managers must be named uniquely by you, the developer. Well, Managers can have the same name as long as they are not instantiated at all simultaneously, since gWFSMultiSpriteList is a list of currently instantiated Managers. You will get an error message from WFS if you name simultaneously instantiated Managers with the same name. The error message will straighten you out, so name them as you please.

Public Handlers

API INTO gWFSMultiSpriteList
wfsManagerIsInstantiated
wfsGetNumberOfInstantiatedManagers
wfsGetManagerSpriteNum
wfsGetManagerName
wfsGetSpritenumOfManagerAtThisIndex
wfsGetNameOfManagerAtThisIndex
wfsAddManagerToMultiSpriteList
wfsDeleteManagerFromMultiSpriteList

API INTO gWFSHighestLocZ
AND gWFSOpenMultiSpriteList
wfsGetHighestLocZ
wfsIncrementHighestLocZ
wfsIncrementAndGetHighestLocZ
wfsBoostHighestLocZ
wfsGetOpenMultiSpriteList
wfsGetFocusManager
wfsAddToOpenMultiSpriteList
wfsDeleteFromOpenMultiSpriteList
wfsGetZOrdinal
wfsGetNumberOfOpenMultiSprites
wfsGetManagerOfZOrdinal
wfsGetLocZOfZOrdinal

DETERMINING INTERSECTION
AND CONTAINMENT
wfsSpriteIsWithin
wfsSpriteIntersects

DETERMINING
ANCESTORS/DESCENDANTS
wfsIsADescendant
wfsGetTheRootSpriteNum

ELEMENT NAME SEARCH
wfsGetElementNamed

See also

All API's
"Menu Manager" API
"3: Window Manager" API
"4: Window/Menu Element" API

Public Handlers (for Programmers)

WFS provides you with an API into gWFSMultiSpriteList. Use this rather than accessing the global gWFSMultiSpriteList directly.

Sometimes these handlers are used in WFS to do error checking. If you know how to build windows and menus, some of this error checking is unneccessary. But if you are developing behaviors for public use, then good error checking helps people debug their movies.

API INTO gWFSMultiSpriteList

wfsManagerIsInstantiated (theManager)

theManager can be an integer or string; if it's an integer, it should refer to the spritenum of a manager; if it's a string, it should be the name of a manager. wfsManagerIsInstantiated returns the spriteNum of the manager if the manager is instantiated, and 0 if the manager isn't instantiated. This handler checks gWFSMultiSpriteList to see if theManager is in it.

wfsManagerIsInstantiated is used widely in the WFS code. It is used both to check whether a manager is instantiated and also to return the spritenum of the manager in cases where the parameter fed to wfsManagerIsInstantiated could be either an integer or a string.

This handler is changed a bit from WFS 3.0. It used to return a boolean.

theIntegerResult = wfsManagerIsInstantiated(theManager)

wfsGetNumberOfInstantiatedManagers ()

This returns the number of currently instantiated Managers. This is the total number of currently instantiated windows and menus. This is the number of elements in gWFSMultiSpriteList.

theIntegerResult = wfsGetNumberOfInstantiatedManagers()

wfsGetManagerSpriteNum (theName)

theName is a string, the name of a window or menu. This handler returns the integer spriteNum of the corresponding Manager or 0 if there is no such Manager currently instantiated. This is the same as wfsManagerIsInstantiated except the parameter of wfsGetManagerSpriteNum has to be a string.

theIntegerResult = wfsGetManagerSpriteNum(theName).

wfsGetManagerName (theSpriteNum)

This returns the name of the specified Manager. theSpriteNum should be the spriteNum of an instantiated multi-sprite. This returns the name of the multi-sprite if it is instantiated, and returns 0 if it isn't currently instantiated.

theStringOr0Result = wfsGetManagerName(theSpriteNum)

wfsGetSpritenumOfManagerAtThisIndex (theIndex)

If theIndex=3, then this handler returns the spritenum of the 3^rd Manager in gWFSMultiSpriteList (which is sorted by spriteNum). In general, if theIndex=n, this handler returns the spritenum of the n^th Manager in gWFSMultiSpriteList. Or 0 if theIndex does not correspond with an instantiated Manager.

theIntegerResult = wfsGetSpritenumOfManagerAtThisIndex(theIndex)

wfsGetNameOfManagerAtThisIndex (theIndex)

If theIndex=3, then this handler returns the name of the 3^rd Manager in gWFSMultiSpriteList (which is sorted by spriteNum). In general, if theIndex=n, this handler returns the name of the n^th Manager in gWFSMultiSpriteList. Or it returns the empty string ("")if theIndex does not correspond with an instantiated Manager.

theStringResult=wfsGetNameOfManagerAtThisIndex(theIndex)

wfsAddManagerToMultiSpriteList  (theManagerName, theManagerSpriteNum)

theManagerName is a string. It is the name of the Manager you want to add to gWFSMultiSpriteList. theManagerSpriteNum is an integer. It is the spriteNum of the Manager you want to add to gWFSMultiSpriteList. This handler adds the Manager to gWFSMultiSpriteList. It returns 1 if the handler successfully added the Manager to gWFSMultiSpriteList. It returns 0 if the handler discovered that the Manager was already part of gWFSMultiSpriteList, ie, there is no reason to add it. This handler alerts you if you are trying to add a Manager and there is another instantiated Manager with the same name. In such case, you need to change the name of one of the Managers since Managers must be named uniquely. Make sure that the Manager is currently instantiated if you add it to gWFSMultiSpriteList.

This handler is called in the 'on beginSprite' handler of windows and menus. You shouldn't need to use it, therefore. Perhaps it should be private. But it's there for the very strange. This handler opens an alert dialog box if it returns 0 and tells you its problems.

theBooleanResult = wfsAddManagerToMultiSpriteList(theManagerName, theManagerSpriteNum)

wfsDeleteManagerFromMultiSpriteList  (theManagerName)

This handler deletes a Manger from gWFSMultiSpriteList. It returns 1 if the Manager was deleted successfully, and returns 0 if the Manager wasn't in gWFSMultiSpriteList to delete it. Even if it returns 0, however, the Manager is not in gWFSMultiSpriteList when this handler returns its result. This handler is called in the 'on endSprite' handler of windows and menus. So you shouldn't need to use it, therefore. But it's there for the very strange. Perhaps it should be private. This handler opens an alert dialog box if if returns 0 and tells you its problems.

theBooleanResult = wfsDeleteManagerFromMultiSpriteList(theManagerName)

API INTO gWFSHighestLocZ
AND gWFSOpenMultiSpriteList
wfsGetHighestLocZ
wfsIncrementHighestLocZ
wfsIncrementAndGetHighestLocZ
wfsBoostHighestLocZ
wfsGetOpenMultiSpriteList
wfsGetFocusManager
wfsAddToOpenMultiSpriteList
wfsDeleteFromOpenMultiSpriteList
wfsGetZOrdinal
wfsGetNumberOfOpenMultiSprites
wfsGetManagerOfZOrdinal
wfsGetLocZOfZOrdinal

wfsGetHighestLocZ ()

This returns an integer indicating the highest locZ value of any window or menu element. Or any sprite that uses this API to set its locZ.

theIntegerResult = wfsGetHighestLocZ()

wfsIncrementHighestLocZ ()

This increments gWFSHighestLocZ by gWFSLocZIncrement, which is a constant defined in "1: prepareMovie.

Each time a multi-sprite is opened, the multi-sprite is brought to front. gWFSHighestLocZ is incremented by 25,000 and the individual elements of the multi-sprite are assigned a locZ that is incremented by gWFSLocZIncrement, which is 50. So there is locZ space between elements in WFS, and there is 25000 worth of locZ space between multi-sprites.

wfsIncrementHighestLocZ()

wfsIncrementAndGetHighestLocZ ()

This increments the highest locZ by gWFSLocZIncrement and returns the new value. This is used by the "3: Window Manager" and "Menu Manager" behaviors when windows or menus are opened to bring windows and menus to the front.

theIntegerResult=wfsIncrementAndGetHighestLocZ()

wfsBoostHighestLocZ ()

This boost gWFSHighestLocZ by 25000. The idea is that when you open a window, you put a space of 25000 locZ units between the window and the most recently opened window. The maxInteger=2147483647. So if the locZ values are getting precariously close to that value (which would take opening windows about 86,000 times), gWFSHighestLocZ is automatically reset and open windows are reopened (in the right order), which readjusts their locZ values. This handler is called in wfsBringWindowToFront in both the "3: Window Manager" and "Menu Manager" behaviors. So even if your app is a kiosk that is run continuously, we won't get integer overflow and all is well with the locZ space.

wfsBoostHighestLocZ()

wfsGetOpenMultiSpriteList ()

This returns a duplicate copy of gWFSOpenMultiSpriteList. Changing what this handler returns does not change gWFSOpenMultiSpriteList. This list is sorted by locZ values of open windows and menus, ie, the last entry in the list is topmost. Suppose the open windows are two in number. One is managed by sprite 5 and the Manager has locZ=345. The other is managed by sprite 12 and has locZ=100. Then gWFSOpenMultiSpriteList=[100:12, 345:5], the list is sorted by locZ order.

theListResult=wfsGetOpenMultiSpriteList()

wfsGetFocusManager ()

This returns the spriteNum of the Manager that has focus, ie, is topmost (and is visible) amongst windows or menus. It returns VOID if there are no open windows or menus. This is different from wfsGetHighestLocZ, which returns the maximal locZ value amongst window and menu elements.

theResult = wfsGetFocusManager()

wfsAddToOpenMultiSpriteList (managerSpriteNum)

This adds the window or menu managed by managerSpriteNum to the gWFSOpenMultiSpriteList, which is a sorted property list of the open windows and menus and their locZ values. This list is sorted by locZ values of open windows and menus, ie, the last entry in the list is topmost. Suppose the open windows are two in number. One is managed by sprite 5 and the Manager has locZ=345. The other is managed by sprite 12 and has locZ=100. Then gWFSOpenMultiSpriteList=[100:12, 345:5], the list is sorted by locZ order. wfsAddToOpenMultiSpriteList returns 1 if the operation was successful, and 0 if it failed. It will fail if managerSpriteNum is not the spritenum of an instantiated Manager of a multi-sprite.

theBooleanResult = wfsAddToOpenMultiSpriteList(managerSpriteNum)

wfsDeleteFromOpenMultiSpriteList (managerSpriteNum)

Deletes managerSpritenum from the gWFSOpenMultiSpriteList. Returns 1 if the operation was successful. Returns 0 if managerSpriteNum was not a property value in the gWFSOpenMultiSpriteList.

theBooleanResult = wfsDeleteFromOpenMultiSpriteList(managerSpriteNum)

wfsGetZOrdinal (managerSpriteNum)

This returns the position of managerSpritenum in gWFSOpenMultiSpriteList or 0 if it isn't in the list. It doesn't return the locZ, but the position in the gWFSOpenMultiSpriteList property list.

theIntegerResult = wfsGetZOrdinal(managerSpriteNum)

wfsGetNumberOfOpenMultiSprites ()

Returns the number of open windows and menus.

theIntegerResult = wfsGetNumberOfOpenMultiSprites()

wfsGetManagerOfZOrdinal (theZOrdinal)

Presupposes a positive integer parameter for theZOrdinal. This returns the manager spritenum of the window or menu in position theZOrdinal in gWFSOpenMultiSpriteList. It returns 0 if theZOrdinal is out of range of gWFSOpenMultiSpriteList.

theIntegerResult = wfsGetManagerOfZOrdinal(theZOrdinal)

wfsGetLocZOfZOrdinal (theZOrdinal)

Presupposes a positive integer for theZOrdinal. Returns the locZ of the manager in position theZOrdinal in gWFSOpenMultiSpriteList, or returns 0 if theZOrdinal is out of range of gWFSOpenMultiSpriteList.

theIntegerResult = wfsGetLocZOfZOrdinal(theZOrdinal)

DETERMINING INTERSECTION
AND CONTAINMENT
wfsSpriteIsWithin
wfsSpriteIntersects

Look at scene 8 of the demo for working use of these handlers. Search the source code of the demo for the handler names.

wfsSpriteIsWithin (theSpriteNum)

This returns a sorted property list of the same form as gWFSOpenMultiSpriteList which contains entries for each window or menu that theSpriteNum is within. For instance, if theSpriteNum=8 and sprite 8 is fully within a window managed by sprite 11 (which has locZ 234) and sprite 8 is fully within a window managed by sprite 3 (which has locZ 444) then wfsSpriteIsWithin(8) returns [234: 11, 444: 3]. Consequently, wfsSpriteIsWithin(8).getLast() returns 3, which is the spritenum of the topmost manager that sprite 8 is within. Note that what is checked for is whether theSpriteNum is within the second sprite of the window, the background sprite of the window or menu.

theListResult = wfsSpriteIsWithin(theSpriteNum)

wfsSpriteIntersects (theSpriteNum)

This returns a sorted property list of the same form as gWFSOpenMultiSpriteList which contains entries for each window or menu that theSpriteNum intersects. For instance, if theSpriteNum=8 and sprite 8 intersects with a window managed by sprite 11 (which has locZ 234) and sprite 8 intersects with a window managed by sprite 3 (which has locZ 444) then wfsSpriteIsWithin(8) returns [234: 11, 444: 3]. Consequently, wfsSpriteIsWithin(8).getLast() returns 3, which is the spritenum of the topmost manager that sprite 8 intersects. Note that what is checked for is whether theSpriteNum is within the second sprite of the window, the background sprite of the window or menu.

theListResult = wfsSpriteIntersects(theSpriteNum)

DETERMINING
ANCESTORS/DESCENDANTS
wfsIsADescendant
wfsGetTheRootSpriteNum

wfsIsADescendant  (theManager, theDescendantManager)

This returns an integer indicating whether theDescendantManager is indeed a descendant of theManager. theManager can be a manager's name or spritenum. Same with theDescendantManager. A manager is not a descendant of itself. If you call this with bad parameters, ie, either theManager or theDescendantManager are not instantiated, an alert dialog box is raised and 0 is returned. If theDescendantManager is indeed a descentdant of theManager, then the spritenum of the child of theManager from which theDescendantManager descends is returned.

theIntegerResult = wfsIsADescendant(theManager, theDescendantManager)

wfsGetTheRootSpriteNum (theManager)

This returns the spritenum of the root manager of theManager or returns 0 and raises an alert dialog if theManager is not an instantiated manager.

theIntegerResult = wfsGetTheRootSpriteNum(theManager)

ELEMENT NAME SEARCH
wfsGetElementNamed

wfsGetElementNamed (theName, returnList, theDomain)

FUNCTION

Searches theDomain of multi-sprites for elements named theName. Do not confuse what is searched for with the Director ability to name sprites and channels. The WFS search is independent of these Director features. You name an element when you drop the "4: Window/Menu Element" behavior on a sprite, and any name you give it is independent of the name of the channel or the name of the sprite assignable via Director features.

Also, the names of elements are not the same as the names of Managers. When you drop the "3: Window Manager" behavior on a sprite, you must name the Manager. But you don't have to name elements. Also, Manager names have to be unique among instantiated Managers. There is no such constraint concerning the names of elements. You can have as many repeats in the names of instantiated elements as you like.

PARAMETERS

theName: The name of the element(s) you want to search for.

returnList: If this is unspecified or VOID or 0, then the handler will search theDomain of multi-sprites for the first occurence of an element named theName. If returnList =1, then the handler will search theDomain of multi-sprites for all occurrences of elements named theName.

theDomain: if theDomain is unspecified or VOID or 0, then the domain of multi-sprites to be searched will be all multi-sprites. If theDomain=1, theDomain will be only open multi-sprites. If theDomain=2, then theDomain will be the multi-sprite that currently has focus (ie, is topmost in locZ)

RETURN VALUE

If returnList is unspecified or VOID or 0, then the handler will return an integer indicating the spritenum of the element first encountered that is named theName among theDomain of multi-sprites. If no such element is found, the handler returns 0.

The search is conducted in such a way that the lowest-numbered channel containing an element named theName will be returned.

If returnList = 1, then the handler will return a linear list of all the spritenums of elements in theDomain of multi-sprites that are named theName. If no such elements are encountered, an empty linear list [ ].

EXAMPLES

Suppose that sprite 1 is a Manager that has sprites 6,7,8 as elements, and sprite 100 is a Manager that has sprites 101,102,103 as elements. Suppose also that sprites 6, 101, and 103 are named "bobo" (and that no other sprites are named "bobo"). Suppose that the multi-sprite managed by sprite 100 has focus, ie, is topmost among multi-sprites. Suppose, finally, that the multi-sprite managed by sprite 1 is not open (not visible).

theResult=wfsGetElementNamed("bobo")

The above will return 6. Since returnList is unspecified, the handler defaults to returning the first element named "bobo". Since theDomain is unspecified, it defaults to setting theDomain to all multi-sprites. This would be the same as calling wfsGetElementNamed("bobo", 0, 0) or also wfsGetElementNamed("bobo", VOID, VOID) or wfsGetElementNamed("bobo", 0) etc.

theResult=wfsGetElementNamed("bobo", 1)

The above will return [6, 101, 103], in other words, all elements named theName. Since theDomain is unspecified, the handler defaults to setting theDomain to all multi-sprites. This would be the same as calling wfsGetElementNamed("bobo", 1, VOID) or also wfsGetElementNamed("bobo", 1, 0).

theResult=wfsGetElementNamed("bobo", 0, 1)

The above will return 101. returnList=0, so the search is for the first occurrence of "bobo". theDomain=1, so only open multi-sprites will be searched. This would be the same as calling wfsGetElementNamed("bobo", VOID, 1)

theResult=wfsGetElementNamed("bobo", 0, 2)

The above will return 101. theDomain=2 means that only the multi-sprite with focus will be searched, and that is the multi-sprite managed by sprite 100.

theResult=wfsGetElementNamed("bobo", 1, 2)

The above will return [101, 103]

NOTES

If you want to search a particular multi-sprite that isn't necessarily the multi-sprite with focus, then use the same-named wfsGetElementNamed handler in the "3: Window Manager" and "Menu Manager" behaviors.

The "4: Window/Menu Element" behavior has two handlers relevant to element names: wfsGetElementName and wfsSetElementName.