Tutorial
4: wfsAddElementToManager and wfsSpriteIsWithin

This tutorial explains how to implement the sort of functionality you
see in scene
8 of the feature tour. In this scene, when you do what a text says,
namely "drag me into window and then drag window", you see
that the text becomes an element of the window onto which it is dropped.

This tutorial shows you how to use the "Add to Manager (containment)"
behavior and also shows you how that behavior was written using the
wfsAddElementToManager and wfsSpriteIsWithin
handlers that are part of the WFS API.

Looking at the Score and stage of scene
8, the source code for which is in WFS48x.DIR in the 'samples' folder
of your copy of WFS 4, we see the following:

First, notice that if you have done tutorial
1, you are familiar with almost all of the behaviors we see in the
Score. There are only two you haven't seen before: "set title"
on sprite 6 and "Add to Manager (containment)" on sprites
14 and 15.

"set title" is not really relevant to this tutorial. Sprite
6 is the sprite at the top of the stage that says "8: wfsAddElementToManager".
The "set title" behavior just sets the text in sprite 6, makes
it be the text of the marker we see in the Score.

But the "Add to Manager (containment)" behavior on sprites
14 and 15 is the focus of this tutorial. It contains all the code associated
with allowing sprites 14 and 15 to become elements of different windows.
The "Add to Manager (containment)" behavior is in the Cast
named "8: wfsAddElementToManager" in WFS48x.DIR.

Notice also that the red arrows in the above diagram are chosen so
that the above diagram clues you in to the correspondence between the
Score and the Stage. Sprites 8-15 form the big window. Sprites 17-19
form the lighter gray window on the left, and sprites 21-23 form the
other window on the right.

Basically all you need to know, unless you are interested in the details,
is that to make an element of a multi-sprite such that you can drag
it into a window and make it become an element of that window is this:

you need to attach to such sprites the "4:
Window/Menu Element" behavior, which makes them initially
part of some multi-sprite;

you need to make the sprites draggable via the "Drag
Element" behavior;

you will probably want to drop the "Cursor
Control" behavior on such sprites to indicate their draggability;

and you need to drop the "Add to Manager (containment)"
behavior on such sprites.

The rest of this tutorial provides you with details.

The "Add to Manager (containment)" behavior makes the sprite
be a part of the highest (in terms of locZ) window it is contained within
when you drop it in a window or a bunch of overlapping windows. For
instance, if you drop it in a window A and that window is above some
other overlapping window B, then the sprite will become part of window
A, not window B, even though the sprite is contained by both windows.
Because the background sprite of Window A is higher in locZ than the
background sprite of window B. Also, for the sprite to become part of
window A, the sprite must be wholely within the background sprite of
window A.

Whereas the "Add to Manager (intersect)" behavior (which
isn't used in WFS48x.DIR but is there if you need it) does not require
complete containment, but only intersection. It will make the sprite
be an element of the highest multi-sprite with which it intersects when
the sprite is dragged and dropped. The "Add to Manager (intersect)"
behavior is in the "8: wfsAddElementToManager" cast in WFS48x.DIR.

For both of these behaviors, if the sprites they're attached to are
dropped in an area where there are no multi-sprites, the sprite becomes
a part of no multi-sprite, ie, its pWFSManagerSpritenum=0 and pWFSManagerName=""
and it is removed from being an element of whatever multi-sprite it
may have been an element of.

Now let's have a look at the code of the "Add to Manager (containment)"
behavior on sprites 14 and 15 to see how easily this behavior was created
via use of the WFS API.

property spritenum

--This behavior is a bit different from
the "Add to Manager (intersect)"

--behavior. The current behavior checks
for containment with multisprites,

--not intersection. It makes the sprite
an element of the top multi-sprite

--(in LocZ) the sprite is contained
within. If the sprite is not contained by

--any multi-sprites, this behavior makes
the sprite part of no multi-sprite,

--ie, gives it a pWFSManagerSpritenum=0
and pWFSManagerName="".

on mouseup me

if
the clickOn = spritenum then

theTopWindowIAmWithin=wfsSpriteIsWithin(spritenum) .getLast()

--The wfsSpriteIsWithin handler is defined
in the "1: prepareMovie" script.

--It returns a sorted list of the windows
that spriteNum is within. See the doc

--on "1: prepareMovie" for
info on wfsSpriteIsWithin.

if theTopWindowIAmWithin <> VOID then

sprite(spritenum).wfsAddElementToManager(theTopWindowIAmWithin)

--The wfsAddElementToManager handler
is defined in the "4: Window/Menu Element"

--behavior, which is attached to this
sprite. It adds spritenum to the multi-sprite

--managed by the sprite with spritenum
theTopWindowIAmWithin.

--For more information, look at the
public handlers section of "4: Window/Menu Element"

--or open up that behavior in this movie.

else

--Else the sprite is within no multi-sprite.

sprite(spritenum).wfsAddElementToManager(0)

--This makes the sprite part of no multi-sprite
at all.

end if

end
if

end mouseup

The above mostly consists of comments, so you can read those and get
all the info you need. But let me give you some links. The wfsSpriteIsWithin
handler it calls returns VOID if the sprite intersects with no multi-sprites.
The wfsAddElementToManager handler
is defined in the "4: Window/Menu Element" behavior. A sprite
can be an element of, at most, one multi-sprite at any given moment.
In other words, when you use wfsAddElementToManager
to change the element's manager, it no longer is managed by the old
manager (which I guess is obvious).

If you have done tutorial 1, you will be
aware that elements need to be below their manager in the Score. When
static elements first come into existence, they need to find their manager
instantiated and above them in the Score. However, after a static element
comes into existence, the wfsAddElementToManager
handler lets you make the element be an element of any instantiated
Manager regardless of whether it is above or below the element in the
Score.

By the way, if you have WFS48x.DIR open in Director and the movie is
stopped and you are looking at the part of the Score shown in the above
graphic, you can start the movie without errors by clicking in the frame
with the marker named "8: wfsAddElementToManager" and then
starting the movie.

The same idea applies to the other section of WFS48X.DIR: to start
a particular section, click in the Score on the frame that begins the
section and then start the movie.