This Document
"4: Window/Menu Element" Behavior
Parameter Dialog Box
Public Handlers

Site Nav

4: Window/Menu Element 

The "4: Window/Menu Element" Behavior

• What it does
• What to attach it to
• One to 0 or 1
• Vertical Placement in the Score
• Horizontal Placement in the Score
• Note for Programmers

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.

Public Handlers

wfsGetInitialVisibility
wfsSetInitialVisibility
wfsGetElementName
wfsSetElementName
wfsGetMyManagerName
wfsGetMyManagerSpriteNum
wfsAddElementToManager
wfsChangeRegPointToTopLeft

"4: Window/Menu Element" Public Handlers

To see code in which these handlers are called, open up the DIR that comes with WFS and do a search for the handler name.

wfsGetInitialVisibility ()

Returns the boolean indicating whether the element is visible when the multi-sprite it's an element of is opened.

theBoolean=sprite(elementSpriteNum).wfsGetInitialVisibility() or
theBoolean=sendSprite(elementSpriteNum, #wfsGetInitialVisibility)

wfsSetInitialVisibility (theBoolean)

Sets the boolean indicating whether the element is visible when the multi-sprite it's an element of is opened. This doesn't affect the visibility of the element until the multi-sprite is opened.

sprite(elementSpriteNum).wfsSetInitialVisibility(theBoolean) or
sendSprite(elementSpriteNum, #wfsSetInitialVisibility, theBoolean)

wfsGetElementName ()

Returns the (string) name of the element. The default value is the empty string.

elementName=sprite(elementSpriteNum).wfsGetElementName() or
elementName=sendSprite(elementSpriteNum, #wfsGetElementName)

wfsSetElementName (theName)

Sets the (string) value of the element name.

sprite(elementSpriteNum).wfsSetElementName(theName) or
sendSprite(elementSpriteNum, #wfsSetElementName, theName)

wfsGetMyManagerName ()

Returns the name (string) of the manager of the element with spritenum=elementSpriteNum. There is a similar handler called wfsGetManagerName in "1: prepareMovie". It is called differently, however. Here we have two ways of getting the same information. The difference is in the information you feed these handlers to get what you want.

This handler is called in the "Show Manager Name 1" behavior in the demo. The "Show Manager Name 1" behavior is attached to the text in windows where you see the name of the window.

managerName=sprite(elementSpriteNum).wfsGetMyManagerName() or
managerName=sendSprite(elementSpriteNum, #wfsGetMyManagerName)

wfsGetMyManagerSpriteNum ()

Returns the spriteNum (integer) of the manager of the element with spritenum=elementSpriteNum.There is a similar handler called wfsGetManagerSpriteNum in "1: prepareMovie". It is called differently, however. Here we have two ways of getting the same information. The difference is in the information you feed these handlers to get what you want.

managerSpritenum=sprite(elementSpriteNum).wfsGetMyManagerSpriteNum() or
managerSpritenum=sendSprite(elementSpriteNum, #wfsGetMyManagerSpriteNum)

wfsAddElementToManager (managerNameOrSpriteNum)

See scene 8 in the demo for an example of this handler and check out tutorial 4 for exposition about this handler.

This handler is also called on beginsprite of window and menu elements.

It adds the window or menu element to the Manager specified by managerNameOrSpriteNum. It returns 1 if the operation was successful, 0 if the operation was unsuccessful and was cancelled. The operation can be unsuccessful if the specified managerNameOrSpriteNum is not instantiated when the call is made. managerNameOrSpriteNum is the name or spriteNum of the Manager of the window or menu you want to add the element to.

An element can only be an element of at most one window or menu. This handler also deletes the element from any other window or menu it's part of before it adds it to the specified multi-sprite.

This handler also updates the data in the Manager that you add the element to. In other words, it does all that needs doing if you want to add an element to a Manager.

If you want to make the element part of no window or menu, then use managerNameOrSpriteNum="" or managerNameOrSpriteNum=0 as the parameter for this handler. But it is better to do the following: if you want to delete a window or menu element from a window or menu, add it to a dummy window in which you store unused elements, basically an unused element Manager. That way, you don't lose track of unused elements.

Window and menu elements are not normally added and deleted. But, as noted elsewhere, WFS is not just about windows and menus, but about multi-sprite objects.

booleanResult=sprite(elementSpriteNum).wfsAddElementToManager(managerNameOrSpriteNum) or
booleanResult=sendSprite(elementSpriteNum, #wfsAddElementToManager, managerNameOrSpriteNum)

wfsChangeRegPointToTopLeft ()

This is automatically executed on the background sprite of a window or menu, which is the first element after the Manager. This handler changes the regPoint of the element to be the top left point of the element.

Note that this cannot execute on some media types in Director such as Shapes created with the ToolBar. This means that Shapes created with the ToolBar cannot be WFS backgrounds to windows or menus. Instead, use Vector Shapes created via Window>Insert>Vector Shape.

sprite(elementSpriteNum).wfsChangeRegPointToTopLeft() or
sendSprite(elementSpriteNum, #wfsChangeRegPointToTopLeft)