css drop down menu by Css3Menu.com
Script Writer wfsWriteMultiSprite
wfsWriteMultiSprite generates and returns a handler that you
use to create a dynamic copy of a static multi-sprite. You call wfsWriteMultiSprite
from the Director Message Window while the movie is running and the
target multi-sprite is instantiated like so:
put wfsWriteMultiSprite(managerNameOrSpriteNumToCopy, doNotCreateNewMembers)
Lingo code is then output to the Message Window which you copy and
paste into a movie script.
wfsWriteMultiSprite will only write code for elements that are currently
instantiated in the static multi-sprite you aim it at.
The wfsWriteMultiSprite handler is in the "Script
Writer" movie script.
managerNameOrSpriteNumToCopy is an integer
or string. If it is an integer, it must be the spriteNum of the Manager
of the multi-sprite you want to copy. If it is a string, it must be
the name of the multi-sprite you want to copy.
doNotCreateNewMembers determines whether
the generated code will create copies of the members of the multi-sprite
you want to copy, or whether the generated code will use the same members
used by the multi-sprite. If you do not specify this parameter then
new copies of members will be created. If you specify any integer value
at all for this parameter, no new members will be created when the generated
code is run.
wfsWriteMultiSprite returns the code necessary to dynamically create
the multi-sprite you aim wfsWriteMultiSprite at.
When you paste that code into a Movie Script and run it, a dynamic
multi-sprite is created and the spritenum of the newly created manager
sprite is returned. Or, if there aren't enough available sprite channels
to create the entire multi-sprite, none of it is created and 0 is returned.
When you run the code output by wfsWriteMultiSprite, you specify no
You can see an example of the use of wfsWriteMultiSprite in the feature
demo source code in scene 11.
When you click the gray text that says "create" (not "create
member") a dynamic copy of the window 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 tour source code, gWFSLastStaticSpriteChannel=84,
ie, the drag and drop sprite with the highest channel number is sprite
84 (in scene 10). The feature tour contains 1000 sprite channels.
So there are 1000 - 84 = 916 channels that are allocatable for dynamic
- The static model of the window named "11.1" was created
in the Score. If you start the movie and then navigate to scene 11
in the source code, and then stop the movie, you see all the sprites
are static, ie, you can see them in the Score and on the stage. When
you stop a movie with dynamic WFS sprites in it, WFS destroys all
the dynamic sprites (you can't see them anymore). The "11.1"
window is your normal WFS 3.0 type of window.
- Start the movie and navigate to a frame where the static model of
the target window "11.1" is instantiated. In the case of
this example, we navigate to scene 11 in the movie.
- Now we run wfsWriteMultiSprite from the Message Window. It takes
two parameters. The first parameter is the name of the manager ("11.1")
or the manager's spritenum (9). Either will do. The second parameter
determines whether the dynamic multi-sprite'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 wfsWriteMultiSprite(9, 1)
in the Message Window and, consequently, we see a handler appear in
the Message Window. wfsWriteMultiSprite output a handler named "wfsCreate111E10F630"
(which is stored in the "generated1" script in the WFS 4
cast). The form of the name of the handlers produced by wfsMultiSprite
is as follows. It starts with "wfsCreate". Then it contains
the name of the multi-sprite copied. The name of the multi-sprite
copied was "11.1". But a handler name cannot contain the
"." symbol. wfsWriteMultiSprite strips out all characters
that can't be part of a handler name. So the handler name contains
"111". Then the handler name contains the "E"
symbol followed by the spritenum of the static model's manager (10).
Then it contains the "F" symbol followed by the frame number
in which wfsWriteMultiSprite ran (630).
- The "wfsCreate111E10F630" handler was copied from the
Message Window and pasted into a movie script. In particular, it was
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 wfsWriteMultiSprite(9,1). The second
parameter means that the members of the dynamic multi-sprite will
be the same ones as the members of the static model multi-sprite.
But there's one sprite which we want to have its own new member. Note
that in scene 11
when you click "create multisprite" to create a new window,
the name of the dynamic window 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 15 in scene 11
is the sprite that displays the name of the window. We also note that
sprite 15 has a member called "11: Label".
Now we open up the source code of the "wfsCreate111E10F630"
handler. We look for the line that mentions the "11: Label"
member. The relevant line looks like this, before editing:
theNewSpriteNum = wfsCreateSprite(["11: Label", "11: wfsWriteElement", 36, 100, 321,
16, 16, 30, 1])
--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 member.
Note that the list of parameters ends with doNotCreateNewMember,
and that the it has a value specified for it in the line of code
(namely doNotCreateNewMember=1). That means that when the sprite
is created, a new member will not be created; the new sprite will
use the same copy of the "11: Label" member as the static
model used. But we do want a new member to be created because we
want to give the dynamic sprite text that can be different from
the static model's text. So we change it like so:
theNewSpriteNum = wfsCreateSprite(["11: Label", "11: wfsWriteElement", 36, 100, 331, 20, 16, 30])
The little edit we've done (getting rid of the "1" at
the end) will result in a new copy of the "11: Label"
member being created each time the "wfsCreate111E10F630"
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 "wfsCreate111E10F630"
handler. The code generated by the wfsWriteMultiSprite handler, if
you look at it, takes a parameter called "familyIdentifier".
However, as is mentioned in the comments in "wfsCreate111E10F630",
"Don't specify any value for the 'familyidentifier' parameter.
The 'familyIdentifier' parameter is used by wfsWriteMultiSpriteFamily
output in calls to wfsWriteMultiSprite output."
If you look at the code for the "create window" behavior
attached to the gray text that says "create multisprite"
(sprite 7 in the Score) you see the below code:
on mouseup me
the clickon = spritenum then
--The below line calls a handler generated
--The 'E10F631' part of the name indicates
that the manager of the
--static model upon which wfsCreate111E10F630
is based was
--located in channel 9 of frame 641.
theNewSpriteNum = wfsCreate111E10F630()
When you click the text that says "create multisprite",
the above handler runs, which calls "wfsCreate111E10F630"
and a dynamic multi-sprite is created. theNewSpriteNum will hold
the spritenum of the newly created manager or 0 if the multi-sprite
could not be created.
As you can see if you run the movie and navigate to scene 11
you can click "create multisprite" repeatedly and, each
time, a new window will be created as long as there are enough dynamic
sprite channels to create the whole multi-sprite. If there aren't,
"wfsCreate111E10F630" will return 0 and no part of the
multi-sprite will be created.
Each instantiated multi-sprite must have a name that is unique among
other instantiated multi-sprites. The convention used by wfsWriteMultiSprite
is pictured below.
If the name of original multi-sprite is q, then the name of the
first copy is q+1, and the name of the second copy is q+2, etc.
of q will remain children of q; they will not be children of q+n
unless you use wfsSetParent or wfsSetChild
change the parent-child relationships. Also, if q has a behavior
that opens some multi-sprite
x, then q+n will open x also. Contrast this with the code produced
- Note also that if you click the blue button at top right of scene
windows, the window 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
We could as well have called wfsDestroyMultiSprite,
rather than wfsDestroyMultiSpriteFamily.
We are simply destroying a single multi-sprite. The reason wfsDestroyMultiSpriteFamily
was used was because the "Destroy Family on Mouseup" behavior
had already been developed for use in scene 10
and sufficed also for scene 11.
in the above code is part of the "4: Window/Menu Element"
Note that if you change the static model, you need to call wfsWriteMultiSprite
again to regenerate the code. Otherwise, the generated code will produce
the old version.
You can delete the "Script Writer" script from the cast when
you are finished generating code. It is a tool for authoring. None of
its handlers are called at run-time.
You can also delete the static model from the Score of a COPY(!) of
your project when it is ready to be published, if you want. The code
that wfsWriteMultiSprite 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 wfsWriteMultiSprite needs those