css drop down menu by Css3Menu.com
Script Writer wfsWriteMultiSpriteFamily
wfsWriteMultiSpriteFamily generates and returns handlers that
you use to create a dynamic copy of a static family of multi-sprites.
You call wfsWriteMultiSpriteFamily from the Director Message Window
while the movie is running and the target family is instantiated like
put wfsWriteMultiSpriteFamily(managerNameOrSpriteNumToCopy, doNotCreateNewMembers)
Lingo code is then output to the Message Window which you copy and
paste into a movie script.
wfsWriteMultiSpriteFamily will only write code for elements that are
currently instantiated in the static model family you aim it
The wfsWriteMultiSpriteFamily handler is in the "Script
Writer" movie script.
is an integer or string. If it is an integer, it is the spriteNum
of the Manager of the multi-sprite you want to start the family copy
at. If it is a string, it must be the name of the multi-sprite you want
to start the family copy at.
determines whether, when the family is created, new members are created
or whether members used by the static version are used. If you specify
any integer value at all for this parameter, new members will not be
created. If you omit this parameter altogether, or specify 0 or VOID,
new members will be created.
Code is returned by wfsWriteMultiSpriteFamily
wfsWriteMultiSpriteFamily returns the handlers necessary to create
and initialize a family of multi-sprites.
If the family you aim wfsWriteMultiSpriteFamily at has n multi-sprites
in it, then n+1 handlers are generated. The first one that appears in
the message window is the handler you call to generate the family. It
takes no parameters. It contains calls to the other n handlers generated
by wfsWriteMultiSpriteFamily. The latter n handlers have been produced
by wfsWriteMultiSpriteFamily making calls to wfsWriteMultiSprite, ie,
one for each multi-sprite in the family.
The form of the name of the first handler output by wfsWriteMultiSpriteFamily
is as follows. It starts with "wfsCreate". Then it contains
the name of the multi-sprite you aimed wfsWriteMultiSpriteFamily at.
Characters that are illegal in handler names are stripped out. Then
it contains the symbol "E". Then the sprite channel in which
the manager was located. Then the frame number in which wfsWriteMultiSpriteFamily
was executed. Finally, it contains the string "Family". So,
for example, if wfsWriteMultiSpriteFamily was aimed at a manager named
"main window" that was in sprite channel 10 and frame 572,
then the first handler would be named wfsCreatemainwindowE10F572Family.
The other n handlers are named according to the naming conventions
which are the same as the above except "Family" is not appended
at the end.
A property list is returned by code generated by wfsWriteMultiSpriteFamily
Now let's discuss what is returned when you run the first handler generated
by a call to wfsWriteMultiSpriteFamily.
A dynamic multi-sprite family is created and a property list is returned.
Or it returns 0 if there weren't enough available dynamic channels to
create the full family and, in that case, it does not create anything.
Each property name in the returned property list is the spriteNum of
a manager in the newly created family; each property value in the returned
property list is the name of a newly created manager. So, for instance,
if the created family consisted of just one multi-sprite, and the dynamic
multi-sprite was managed by sprite 345 and the name of the newly created
dynamic multi-sprite was "A", then the returned property list
would be [345:"A"]. The order in which the property list lists
the dynamic multi-sprites reflects a depth-first traversal of the family
Recall that the names of simultaneously instantiated multi-sprites
must all be different. So when you create dynamic multi-sprites, their
names will not be the same as the names of their corresponding static
models. wfsWriteMultiSpriteFamily returns code that names dynamic multi-sprites
according to the following rules.
Multi-sprites generated by code returned by wfsWriteMultiSpriteFamily
have names that have three components separated by the "+"
symbol. So these names are not really appropriate for display to the
user. The first component is the name of the static model multi-sprite.
The second component is the name of the multi-sprite at which you aimed
wfsWriteMultiSpriteFamily. The third component is a number indicating
the number of dynamic copies of this family.
In the above graphic, the lines joining multi-sprites
indicate parent-child relationships: r and s are the names of two multi-sprites,
and q is
the name of the
multi-sprite that is the parent of r and s.
If we were to point wfsWriteMultiSpriteFamily at q, it
would generate code to reproduce the family. When we ran that code,
we would get a dynamic family named as in the first copy of the family.
If we ran the generated code again, while the first copy was still
instantiated, we'd get a second family named like the multi-sprites
in the second copy of the family.
Suppose q has the "Open a Window" behavior attached to
it, and that behavior opens window r. The wfsWriteMultiSpriteFamily
handler is smart enough to write code so that q+q+1 will open r+q+1.
WFS adjusts links within the family.
It does not adjust links outside
the family, though. For instance, if an "Open a Window" behavior
was attached to q and the behavior was supposed to open x, some multi-sprite
not in the family, then q+q+1 would open x also.
You can see an example of the use of wfsWriteMultiSpriteFamily in the
feature demo source code in scene 10.
When you click the gray text that says "create multisprite family",
a dynamic copy of the family is generated. Let's look step-by-step at
how this was done. The steps below follow the same order as the generic
steps in using any of the three Script Writer handlers.
- We make sure the movie has a copy of the "1:
and "Script Writer" movie
scripts in a cast.
- We edit the value of gWFSLastStaticSpriteChannel in the 'initializeDynamism'
handler of the "Dynamism" script, as per instructions,
if you haven't already. gWFSLastStaticSpriteChannel determines how
many sprite channels in your movie are allocatable for dynamic sprite
creation. In the feature demo source code, gWFSLastStaticSpriteChannel=84,
ie, the drag and drop sprite with the highest channel number is sprite
84 (in scene 10). The feature demo contains 1000 sprite channels.
So there are 1000 - 84 = 916 channels that are allocatable for dynamic
- The static model of the family was created in the Score.This is
quite an extensive family. It consists of about 70 sprites and many
windows and menus. If you start the movie and then navigate to scene
in the source code, and then stop the movie, you are in the right
- Start the movie and navigate to a frame where the static model of
the target family is instantiated. In the case of this example, we
navigate to scene 10
in the movie.
- Now we run wfsWriteMultiSpriteFamily from the Message Window. It
takes two parameters. The first parameter is the name of the manager
at which we want to start the family copy ("main window")
or this manager's spritenum (10). Either will do. The second parameter
determines whether the dynamic family's members will be the same as
the static model's members, or whether the members will be new copies
of the static model's members. If you don't need to create new members,
it's best not to because they take up extra resources. We want most
of the dynamic sprites to use the same member as the sprites
in the static model, so the second parameter will be 1, and we will
edit the generated code, later on, concerning the sprites whose members
we want to be new copies. So we type
put wfsWriteMultiSpriteFamily(10, 1)
in the Message Window and, consequently, we see many handlers appearing
in the Message Window. It takes a while for all the code for this
family to appear in the Message Window. Wait for it.
wfsWriteMultiSpriteFamily will first output a handler named something
like "wfsCreatemainwindowE10F570Family". This first handler
is the one we will call to produce a dynamic family. Read the Return
Value section of this document for the rationale concerning how
the handler is named. Other handlers will also be produced: one for
each multi-sprite in the family.
- All the generated handlers were copied from the Message Window and
pasted into a movie script. In particular, they were pasted into the
movie script named "generated1" that is in the WFS 4 cast.
I tend to keep the handlers generated by the Script Writer in one
movie script, just so that I know where they all are.
- Now that we have the generated code in a movie
script, we may wish to do a bit of customization of the generated
code. Why and how? Well, we ran wfsMultiSpriteFamily(10,1). The second
parameter means that the members of the dynamic family will be the
same ones as the members of the static model family. But there's one
sprite which we want to have its own new member. Note that when you
click "create multisprite family" to create a new family,
the name of a dynamic multi-sprite is displayed at top left of the
window. If this text used the same member as the static model used,
then the text of the name would have to be the same among sprites
that use that member. Because sprites that share the same text/field
member necessarily display the same text. But we want different dynamic
multi-sprites to display their own name.
We note that that sprite 13 in scene 10
is the sprite that displays the name of the window. We also note that
sprite 13 has a member called "main window label".
Now we open up the source code of the 'generated' movie script in
the WFS 4 cast. Search for "main window label" in that script.
We see that "main window label" occurs in the below code:
theNewSpriteNum = wfsCreateSprite(["main
window label", "7:
Normal Menus", 36, 100,
294, 32, 78, 38])
--parameters: [member, cast, ink, blend,
width, height, locH, locV, doNotCreateNewMember]
--If you don't specify a value for doNotCreateNewMember,
then a copy of the member will be created.
--If you specify any value for doNotCreateNewMember,
then the sprite will be created using the same
The thing to note is that no value for doNotCreateNewMember is
specified. The comments indicate that the parameter list can take
9 things, but there are only 8 things in the line with the call
to wfsCreateSprite. Note also that all the other lines that call
wfsCreateSprite have 9 things in the parameter list. I edited the
above line, deleting the "1" specified elsewhere for the
doNotCreateNewMember parameter. Because when the "main window
label" sprite is created, I want it to have its own member.
For more information on editing code produced by the "Script
Writer" handlers, read the section entitled "Editing
code generated by the Script Writer handlers".
- We need to write some Lingo that calls the "wfsCreatemainwindowE10F570Family"
handler. If you look at the gray text that says "create multisprite
family " in scene 10 of the feature demo, you see it has attached
to it a behavior called "tester". If you open up that behavior
in the script window, you see the below code:
on mouseup me
the clickon =spritenum then
generated by the
in the Script Writer movie script.
a dynamic copy of
--the family of multi-sprites rooted
by the manager named "main window"
--located in channel 10, frame 570.
--typed in the Message Window while
the movie was playing and the
--playback head was in a frame where
the target (static) family was
--instantiated, namely frame 570.
theBigList = wfsCreatemainwindowE10F570Family()
When you click the text that says "create multisprite family",
the above handler runs, which calls "wfsCreatemainwindowE10F570Family"
and a dynamic family is created.
- As you can see if you run the movie and navigate to scene 10,
you can click "create multisprite family" repeatedly and,
each time, a new family will be created as long as there are enough
dynamic sprite channels to create the whole multi-sprite. If there
aren't, "wfsCreatemainwindowE10F570Family" will return 0.
- Note also that if you click the blue button at top right of scene
windows, the family is destroyed. The blue button has a behavior attached
to it called "Destroy Family On Mouseup". That behavior
contains the below handler:
on mouseup me
the clickon = spritenum then
See the documentation on the destructors
for more information on using destructors. WFS does garbage collection
of all dynamic sprites at the end of the movie, ie, they are all
destroyed and garbage collected, but you can use the destructors
during the movie to free up dynamic channels.
Note that if you change the static model, you need to call wfsWriteMultiSpriteFamily
again to regenerate the code. Otherwise, the generated code will produce
the old version.
You can delete the "Script Writer" handler from the cast
when you are finished generating code. That is all it does.
You can also delete the static model from the Score when your project
is all finished, if you want. The code that wfsWriteMultiSpriteFamily
generates does not depend on the static model being present in the Score.
But don't delete the cast members of the static model. The code generated
by wfsWriteMultiSpriteFamily needs those cast members.
But it is a good idea to keep a copy of your project that has the static
model in it and the Script Writer in it also, so that you can edit it
easily later on, ie, regenerate the code and so on.