"Menu Manager" Public Handlers (for Programmers)
The "Menu Manager" API is almost identical to the "3:
Window Manager" API.
This section is for programmers who want to do things beyond what the
WFS drag and drop behaviors permit you to do with windows and menus.
The "Menu Manager" behavior contains the below public handlers
that are useful for opening, closing and changing the locZ of menus.
The public handlers also permit developers to move menus and also families
of menus around and to align them.
The public handlers also provide handlers for setting parent-child
relationships between Managers. These last handlers are the most powerful
of the public handlers. Why? Because they go beyond the notion of windows
and menus. WFS is actually not so much about windows and menus as multi-sprite
objects. Being able to set parent-child relationships amongst multi-sprite
objects allows you to combine multi-sprite objects to make larger objects.
All WFS handlers start with "wfs". This is to ensure no intrusions
into your own programming name space. Just don't name your own handlers
such that they start with "wfs" and you're guaranteed no handler
name-space intrusion. All WFS globals start with "gWFS". All
WFS properties start with "pWFS". So you are guaranteed no
name-space intrusions in your globals and properties as long as they
don't start with "gWFS" or "pWFS".
OPENING, CLOSING, AND LOCZ OF MENUS
wfsOpenWindow ()
This opens the menu whose Manager's spriteNum is the integer managerSpriteNum
and brings it to front. This handler is called by any WFS behaviors
that open menus. Make sure the menu is instantiated. This handler has
a tiny (but important) bit more code in it than the same-named handler
in the "3: Window Manager" behavior. Look at the source code
for the difference if you are modifying WFS.
sprite(managerSpriteNum).wfsOpenWindow()
or
sendSprite(managerSpriteNum,
#wfsOpenWindow)
wfsBringWindowToFront ()
This brings the window to the front. It is called when the window is
opened. It's also called when you click on a Window Element and you
have the window configured to come to front when clicked. Even if you
don't have it so configured, this handler is called when you click an
Element that has the "6: Handle" behavior attached to it. This handler
also brings the children to front--in front of the current window. The
idea is that children stay in front of their parents. If you call this
handler with a positive integer parameter for doNotBringChildrenToFront,
the children will not be brought to front.
sprite(managerSpriteNum).wfsBringWindowToFront()
or
sendSprite(managerSpriteNum,
#wfsBringWindowToFront)
The above also brings the children
to front.
sprite(managerSpriteNum).wfsBringWindowToFront(1)
or
sendSprite(managerSpriteNum,
#wfsBringWindowToFront,
1)
The above brings the window to front
but does not bring the children to front.
wfsCloseMenuSystem ()
Menus are closed a bit different than windows are closed. You use the
wfsCloseWindow handler to close a window but you use the wfsCloseMenuSystem
handler to close a menu.
The Menu Manager Parameter Dialog Box contains an item that is labelled
"If this is a root menu, close menu root when user selects from
menu?" If this is checked then when you call wfsCloseMenuSystem, the
entire menu system of which the current sprite is part will be made
invisible. If the above mentioned check box is not checked, then when
you call wfsCloseMenuSystem, all but the root menu of the current menu
system will be made invisible.
sprite(managerSpriteNum).wfsCloseMenuSystem()
or
sendSprite(managerSpriteNum,
#wfsCloseMenuSystem)
wfsRestoreWindowLocZ ()
This restores the LocZ of each sprite in the menu. It is called in
the wfsCloseWindow handler.
sprite(managerSpriteNum).wfsRestoreWindowLocZ()
or
sendSprite(managerSpriteNum,
#wfsRestoreWindowLocZ)
MOVING MENUS, FAMILIES OF MENUS, AND ALIGNMENT
wfsCenterMultiSprite ()
This handler moves the referenced menu to the center of the stage,
and moves descendant menus (that are configured to be moved with their
parents) accordingly, not necessarily centering them, but moving them
so that their position relative to the centered menu is preserved.
This handler first calculates the current position of the menu. But
what is that, since the menu is really just an aggragate of sprites
with possibly different locations? So it is a bit arbitrary: it defines
the position of the menu as the left (horizontal) and top (vertical)
values of the first menu element (not the menu manager). Hence it is
a good idea to make that menu element be the top leftmost element in
the menu since, by convention, that is generally what we mean when we
move something to a point. Note that the menu Manager sprite is not
moved.
sprite(managerSpriteNum).wfsCenterMultiSprite()
or
sendSprite(managerSpriteNum,
#wfsCenterMultiSprite)
wfsMoveFamilyBy (deltaPoint)
deltaPoint is a parameter of type Point. This handler moves the referenced
menu and its descendent menus by deltaPoint.locH pixels horizontally
and deltaPoint.locV pixels vertically. These can be negative or positive
integers or 0. This handler is recursive; it moves descendants, not
just children.
sprite(managerSpriteNum).wfsMoveFamilyBy(deltaPoint)
or
sendSprite(managerSpriteNum,
#wfsMoveFamilyBy,
deltaPoint)
wfsMoveFamilyTo (absolutePoint)
absolutePoint is a parameter of type Point. This handler moves the
top left point of this menu to absolutePoint and moves all its descendent
menus (that are configured to be moved with their parents) accordingly
so that they are in the same position relative to the referenced menu.
The top left point of this menu is considered to be the top left point
of the second menu element of the menu. This handler is recursive; it
moves descendants, not just children.
sprite(managerSpriteNum).wfsMoveFamilyTo(absolutePoint)
or
sendSprite(managerSpriteNum,
#wfsMoveFamilyTo,
absolutePoint)
wfsMoveMultiSpriteTo (absolutePoint)
absolutePoint is a parameter of type Point. This handler moves this
menu to the point specified by absolutePoint. This handler first calculates
the current position of the menu. But what is that, since the menu is
really just an aggragate of sprites with possibly different locations?
So it is a bit arbitrary: it defines the position of the menu as the
left (horizontal) and top (vertical) values of the first menu element
(not the menu manager). Hence it is a good idea to make that menu element
be the top leftmost element in the menu since, by convention, that is
generally what we mean when we move something to a point. Note that
the menu Manager sprite is not moved.
sprite(managerSpriteNum).wfsMoveMultiSpriteTo(absolutePoint)
or
sendSprite(managerSpriteNum,
#wfsMoveMultiSpriteTo,
absolutePoint)
wfsMoveMultiSpriteBy (deltaPoint)
deltaPoint is a parameter of type Point. This handler moves the referenced
menu and all its menu elements by deltaPoint.locH pixels horizontally
and deltaPoint.locV pixels vertically. These can be negative integers
as well as positive or 0. It doesn't move the menu Manager sprite.
sprite(managerSpriteNum).wfsMoveMultiSpriteby(deltaPoint)
or
sendSprite(managerSpriteNum,
#wfsMoveMultiSpriteby,
deltaPoint)
wfsCenterElementLocH (elementSpriteNum)
elementSpriteNum is an integer parameter indicating the spritenum
of the menu element to center horizontally. This handler checks where
the regpoint is in elementSpritenum and centers the element horizontally
relative to the menu's background, which is assumed to be the first
menu element in the menu (after the menu Manager, which isn't considered
to be an element of the menu).
sprite(managerSpriteNum).wfsCenterElementLocH(elementSpriteNum)
or
sendSprite(managerSpriteNum,
#wfsCenterElementLocH,
elementSpriteNum)
wfsCenterElementLocV (elementSpriteNum)
elementSpriteNum is an integer parameter indicating the spritenum
of the menu element to center vertically. This handler checks where
the regpoint is in elementSpritenum and centers the element vertically
relative to the menu's background, which is assumed to be the first
menu element in the menu (after the menu Manager, which isn't considered
to be an element of the menu).
sprite(managerSpriteNum).wfsCenterElementLocV(elementSpriteNum)
or
sendSprite(managerSpriteNum,
#wfsCenterElementLocV,
elementSpriteNum)
wfsPositionElementLocVRelative (elementSpritenum, theLocV)
This handler positions the locv of elementSpritenum theLocv pixels
below the menu's background, which is assumed to be the first menu element
(below the Menu Manager in the Score).
sprite(managerSpriteNum).wfsPositionElementLocVRelative(elementSpritenum,
theLocV)
or
sendSprite(managerSpriteNum,
#wfsPositionElementLocVRelative,
elementSpritenum,
theLocV)
wfsPositionElementLocVAbsolute (elementSpritenum, theLocV)
This handler positions the locV of elementSpritenum at theLocV.
sprite(managerSpriteNum).wfsPositionElementLocVAbsolute(elementSpritenum,
theLocV)
or
sendSprite(managerSpriteNum,
#wfsPositionElementLocVAbsolute,
elementSpritenum,
theLocV)
PARENT-CHILD OPERATIONS
wfsGetParentName ()
This handler returns the name of the parent or "" if it has
no parent.
sprite(managerSpriteNum).wfsGetParentName()
or
sendSprite(managerSpriteNum,
#wfsGetParentName)
wfsGetParentSpriteNum ()
This handler returns the spritenum of the parent or 0 if it has no
parent.
sprite(managerSpriteNum).wfsGetParentSpriteNum()
or
sendSprite(managerSpriteNum,
#wfsGetParentSpriteNum)
wfsSetChild (theChild, moveTheChildWhenIMove)
Calling
theResult= sprite(parentSpriteNum).wfsSetChild(theChild,
moveChildWhenIMove)
results in theChild becoming a child multi-sprite of the multi-sprite
with manager spritenum = parentSpriteNum. In other words, theChild becomes
a child of the parent.
Almost like people, a multi-sprite can have many children
but, at most, one parent.
theChild parameter is an integer or string. If it is a string, it denotes
the name of a multi-sprite. If it is an integer, it denotes the spriteNum
of a manager of a multi-sprite.
The moveChildWhenIMove parameter is a boolean. If it is TRUE, then
the child will move when the parent is moved. If it is FALSE, then the
child will not be moved when the parent is moved.
wfsSetChild returns 1 (TRUE) if the operation was successful, and 0
(FALSE) if the operation was not successful and was cancelled. If wfsSetChild
returns 0, that means that the child was identical to the parent (a
child cannot be its own parent) or the child or the parent were not
instantiated or theChild spriteNum <=0 or parentManagerSpritenum
< 0. Setting parentManagerSpriteNum=0 is OK; it results in theChild
having no parent. But it might be more intutive to use wfsDeleteChild
for such an operation.
We see in the below diagram that a call to wfsSetChild is equivalent
to a call to wfsSetParent, only with the parameters reversed. The moveChildWhenIMove
parameter has been omitted to clarify the main point. The "I"
in 'moveChildWhenIMove' refers to the parent.
A Manager is not allowed to be among its own ancestors. In other words,
a Manager cannot be its own parent or grandparent etc. It would cause
infinite loops when you move or close families of multi-sprites. The
diagram below illustrates how wfsSetChild handles such a situation.
What we see in the above diagram is how the call sprite(G).wfsSetChild(B)
is handled. It does indeed result in B becoming a child of G. But the
parent of B is changed to be G (as you would expect) and, also, D is
no longer a child of B. The relation between B and D has had to be severed,
or B would become its own granddaddy. The above operation returns 1.
The moveChildWhenIMove parameter is omitted from the above diagram to
make the main points clearer.
This handler sets the child's data and also the parent's data, so that
if you want to set a child, this is the only call you need to make.
Note that if the child already has a parent, this handler changes the
parent. A child can have, at most, one parent though a parent can have
multiple children.
See the included .DIR for example usage of wfsSetChild and wfsSetParent.
theResult=sprite(parentManagerSpriteNum).wfsSetChild(theChild,
moveTheChildWhenIMove) or
theResult=sendSprite(parentManagerSpriteNum,
#wfsSetChild,
theChild, moveTheChildWhenIMove)
wfsDeleteChild (theChild)
This handler deletes theChild from the Manager whose spriteNum is parentManagerSpriteNum
(see below), ie, it makes the child no longer a child of the parent
and sets the child so that it has no parent.
This handler returns 1 if the operation was successful, 0 if the operation
was not successful and the operation was cancelled. It will return 0
if theChild is not instantiated or is not a child of the parent.
theChild can be a string or an integer. If it is an integer, it refers
to the spriteNum of the Manager of the child. If it is a string, it
refers to the name of the child.
This handler adjusts data in the child and in the parent Manager, so
if you want to delete a child, this is the only call you need to make.
theResult=sprite(parentManagerSpriteNum).wfsDeleteChild(theChild)
or
theResult=sendSprite(parentManagerSpriteNum,
#wfsDeleteChild,
theChild)
wfsSetParent (theParent, moveWhenParentMoves)
Calling
theResult= sprite(childSpriteNum).wfsSetParent(theParent,
moveWhenParentMoves)
results in theParent becoming the parent of the multi-sprite managed
by sprite childSpriteNum.
theParent is a string or integer. If it is a string, it is the name
of the proposed parent window or menu. If it is an integer, it is the
spriteNum of the proposed parent window or menu's Manager.
If you want to set the current window or menu to have no parent, then
use theParent="" or theParent=0. Or call wfsDeleteChild.
MoveWhenParentMoves is a boolean indicating whether the current window
should be dragged when its proposed new parent is moved.
A call to wfsSetParent is equivalent to a call to wfsSetChild, only
the parameters are different. In other words, if you make window A the
parent of window B, you also make window B the child of window A. Use
whichever one you like. See the documentation (above) on wfsSetChild.
It is more detailed than the documentation on wfsSetParent. In particular,
look at the diagrams.
wfsSetParent returns 1 if the operation was successful, 0 if the operation
was not successful and was cancelled. A Manager is not allowed to be
one of its own ancestors. Make sure that the Manager with spritenum=managerSpriteNum
and theParent are instantiated when you call this.
A Manager can have, at most, one parent. If the Manager with spritenum=managerSpritenum
already has a parent, then wfsSetParent makes theParent the sole parent.
This handler sets data in both the managerSpritenum and theParent.
You don't need to call any other handlers to set the parent.
theResult=sprite(managerSpriteNum).wfsSetParent(theParent,
moveWhenParentMoves) or
theResult=sendSprite(managerSpriteNum,
#wfsSetParent,
theParent, moveWhenParentMoves)
wfsGetNumberOfChildren ()
This returns an integer indicating the number of children.
theReturnValue=sprite(managerSpriteNum).wfsGetNumberOfChildren()
wfsGetChildList ()
This returns a linear list containing the spritenums of the managers
of child multi-sprites. This list is a duplicate of pWFSChildList, a
property of each manager. Since the list is a duplicate of pWFSChildList,
changing it does not change the status of the multi-sprite's children.
theReturnValue=sprite(managerSpriteNum).wfsGetChildList()
wfsSetMoveWithParent (theBoolean)
If theBoolean is TRUE (or 1) then wfsSetMoveWithParent sets the manager
to move when its parent moves. If theBoolean is FALSE (or 0) then wfsSetMoveWithParent
sets the manager to not move when its parent moves.
Returns 0 if there is no parent or it is not instantiated. Even so,
should the manager acquire a parent at a later time, wfsSetMoveWithParent(1)
sets it so that it will indeed move with its new parent, should it acquire
one.
Returns 1 otherwise.
theReturnValue=sprite(managerSpriteNum).wfsSetMoveWithParent(theBoolean)
MISCELLANEOUS PUBLIC HANDLERS
wfsGetElementList ()
Returns a duplicate of the element list, a linear list that contains
the spritenums of the elements of the multi-sprite. The first entry
in the list is always the spritenum of the manager of the multi-sprite,
which you shouldn't move.
theReturnValue=sprite(managerSpriteNum).wfsGetElementList()
wfsGetElementNamed
(theName, returnList)
FUNCTION
Finds an element or all elements named theName. If returnList=VOID
(or is not specified), then the handler will search for the first occurrence
amid the elements of the multi-sprite for an element named theName.
If returnList<>VOID, then the handler will search for all occurrences
of elements named theName. This handler does not look at the names
of managers. It looks at the names of elements, which in this context
are never managers.
RETURN VALUE
If returnList=VOID (or is unspecified), then returns an integer indicating
the spritenum of the first element in the multi-sprite named theName.
If there is no element named theName, then the handler returns 0. If
returnList <> VOID, then returns a linear list indicating the
spritenums of all elements in the multi-sprite named theName. Returns
the empyty list [ ] if there are no elements named theName.
PARAMETERS
theName: A string denoting the name of
the element
returnList: is an optional parameter.
If returnList=VOID or is unspecified, then the handler will look for
only the first occurrence of an element in the multi-sprite named theName
and the handler will return an integer. If returnList <> VOID,
then the handler will return a linear list indicating the spritenums
of elements in the multi-sprite named theName.
EXAMPLES
Suppose that sprite 5 is a Manager of a multi-sprite, and that two
of its elements, sprites 9 and 11, are named "bobo".
theReturnValue=sprite(5).wfsGetElementNamed("bobo") or
theReturnValue=sendSprite(5,
#wfsGetElementNamed, "bobo")
will return 9
theReturnValue=sprite(5).wfsGetElementNamed("bobo",
1) or
theReturnValue=sendSprite(5,
#wfsGetElementNamed, "bobo",
1)
will return [9, 11]
SEE ALSO
You set the name of elements when you drop the "4: Window/Menu
Element" behavior on a sprite and you can change the name at run
time. That behavior contains two handlers relevant to element names: wfsGetElementName and wfsSetElementName.
The "1: prepareMovie" script contains a handler named wfsGetElementNamed.
This is a bit different from the current handler. It will search multiple
multi-sprites for elements with a specified name (in various ways)
wfsGetIAmVisible ()
This returns a boolean that indicates whether the referenced menu is
currently open. Open is TRUE.
theReturnValue=sprite(managerSpriteNum).wfsGetIAmVisible()
wfsGetWindowRect ()
This returns the rect of the window. What is that? It is the rect of
the background element, which is the first element below the manager.
theReturnValue=sprite(managerSpriteNum).wfsGetWindowRect()
wfsGetBackgroundSpriteNum ()
The background of a multi-sprite is, by WFS convention, defined as
pWFSElementList[2]. In other words, it's the element right after the
manager. If pWFSElementList contains only one entry, 0 is returned.
theReturnValue=sprite(managerSpriteNum).wfsGetBackroundSpriteNum()
|
Menu
Manager Behavior
1: prepareMovie
2: Window Manager
3: Window Manager
4: Win/Menu Element
5: Close My Window
6b: Handle
Menu Manager
Menu Manager
Menu Verb
Menu item highlight
"Menu Manager" behavior
"3: Window Manager"
"Menu Manager bitmap"
