|
4: Window/Menu Element
The "4: Window/Menu Element" Behavior
What it does
This behavior turns sprites into elements of windows or menus.
Static sprites (drag and drop sprites you can see in the Score) with
this behavior figure out which sprite is their Manager on beginSprite
and send a message to the Manager saying 'here I am, I'm yours, add
me to your list of elements'. When sprites have this behavior attached
to them, they know the name (pWFSManagerName) and spriteNum (pWFSManagerSpriteNum)
of their own Manager. And when they end in the Score, they delete themselves
from the list of elements of their Manager.
Dynamic elements (elements created via puppeting channels that you
can't see in the Score) are told by WFS routines who their manager is.
Static elements look for the closest Manager that is above them in the
Score; that's their Manager. But the Managers of dynamic elements aren't
necessarily in such a position, which is why WFS routines tell dynamic
elements who their Manager is.
What to attach it to
Attach this behavior to every Window Element and every Menu
Element.
A Window Element is a sprite that is part of a window. A Menu Element
is a sprite that is part of a menu. Every Window Element and every Menu
Element must have a copy of the "4: Window/Menu Element" behavior
attached to them.
Except Managers. Managers never have this behavior attached to them.
One to 0 or 1
A sprite can be an element of, at most, one window or menu at any
given point in time.
Vertical placement in the Score
When you drop the "4: Window/Menu Element" behavior on a
static sprite, it thinks that its Manager is the Window or Menu Manager
closest to it in the Score but higher in the Score than itself.
To look at it from another angle, all static elements of a window or
menu must be below their Manager in the Score, and above the next Manager
in the Score, if you have multiple windows and/or menus.
The rule is a bit different concerning dynamic elements, and simpler:
the Manager simply has to be created before the element is created.
Horizontal placement in the Score
All static elements that have Manager A must start on the same frame
as Manager A or a later frame during which Manager A is still instantiated.
It doesn't really matter where window elements end in the Score. But
you will generally want them to start and end when the Manager of the
window starts and ends in the Score.
To make your code manageable visually and logically, it is typical
to make a static window look like a rectangle in the Score, as shown
below, though elements do not have to be contiguous.
Sprites 1-4 form the window.
Note for Programmers
An element, on beginSprite, figures out which sprite is its Manager
and sends a message to its Manager saying 'here I am, add me to your
pElementList of elements to manage.' And when an element dies, it checks
(in its 'on endSprite' handler) to see if its Manager is still alive.
If the Manager is still alive, the element sends its Manager a message
saying 'You don't need to manage me anymore. Delete me from your pElementList
of elements to manage.'
In this way, you could have a Manager stretch a long way across the
Stage and have several horizontal rectangles of sprites that occupy
certain disjoint cycles of the Manager's existence. That is fairly esoteric,
however. Usually, a Window or Menu will just be a block of sprites that
form a rectangle with the Manager at the top of the rectangle and the
elements below it.
See tutorial 3 for more information on
this topic.
As is made clear by the existence of the wfsAddElementToManager public
handler (see below), if you are a Lingo programmer you can add and delete
elements dynamically. And in that case, windows and menus will probably
not look like rectangles in the Score, at any given time. When static
elements become instantiated, they must be below their manager. However,
during the rest of their existence, you can use wfsAddElementToManager
to change their manager, and the manager can be anywhere in the Score.
Parameter Dialog Box
When you drop the "4: Window/Menu Element" behavior on a
sprite, the following dialog box opens for you to configure the element:
Make visible when the window/menu becomes visible
Leave the box checked if you want this element to be visible when the
window or menu is initially opened. With some elements, you don't want
this to be the case. For example, if you make a drop-down box that is
part of a window, you don't want parts of it visible when the window
is initially opened.
The "4: Window/Menu Element" behavior has a property called pWFSInitialVisibility
that stores this property.
The API into it is
- wfsGetInitialVisibility -- in the "4: Window/Element" behavior
Retrieves initial visibility boolean.
- wfsSetInitialVisibility -- in the "4: Window/Element" behavior
Sets initial visibility boolean. This doesn't make the element
visible or invisible. It only affects whether the element is visible
or invisible when the multi-sprite is opened.
Name
this sprite (or leave blank)
You can name the elements of multi-sprites. DMX 2004 lets you name
sprites and channels. I looked into those features to see if I could
use them in WFS. But the Director features have problems: they have
to be set during a score recording session, and dynamic sprites cannot
have sprite names or channel names. So I thought I'd implement a WFS
version that I think is far more flexible and useful. It's important
to note that the WFS element naming system is completely independent
of the built in Director channel and sprite naming system. For instance,
if you have named a channel "bobo", that doesn't mean that the WFS
element in that channel is named "bobo".
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.
The default name, as in the Director implementation, is the empty
string.
An element name is stored as a property named pWFSElementName in the
"4: Window/Menu Element" behavior. Like all properties that
appear in the Parameter Dialog Box, it is initilaized by the getPropertyDescriptionList
handler in the behavior itself. The API into element names consists of the following handlers:
- wfsGetElementName -- in the "4: Window/Menu
Element" behavior
Returns the name of the specified element.
- wfsSetElementName -- in the "4: Window/Menu
Element" behavior
Sets the name of the specified element (whether
the sprite is dynamic or not).
- wfsGetElementNamed -- in the
"3: Window Manager" and "Menu Manager" behaviors
Returns an integer or linear list of element spritenums that have
the specified name. Searches
a specified single multi-sprite.
- wfsGetElementNamed -- in the
"1: prepareMovie" movie script
Returns an integer or linear list of element spritenums that
have the specified name. Searches multiple multi-sprites.
The ability to name elements is particularly useful in referring
to sprites when using the Dynamic capabilities of WFS. For an example
of its usefulness
in this regard, see the discussion in
the tutorial about wfsWriteElement in the tutorial on wfsWriteElement.
|
4:
Window/Menu Element 
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