Click to go to the home page.
 

Site Nav

css drop down menu by Css3Menu.com

Tutorial 4

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:

  1. you need to attach to such sprites the "4: Window/Menu Element" behavior, which makes them initially part of some multi-sprite;
  2. you need to make the sprites draggable via the "Drag Element" behavior;
  3. you will probably want to drop the "Cursor Control" behavior on such sprites to indicate their draggability;
  4. 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.

The "Add to Manager (intersect)" behavior is just like the "Add to Manager (containment)" behavior except it uses wfsSpriteIntersects rather than wfsSpriteIsWithin.

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.

 
Click to go to the home pageTutorial 4