| Dynamism Constructors
The "Dynamism" Constructors
The first two of these constructors are called by code generated by
the handlers in the Script Writer script.
The last three are not called anywhere in the WFS code. You shouldn't
have to call any of these constructors if you use the Script
Writer handlers, which are more powerful than these constructors.
The "Dynamism" constructors:
wfsCreateSprite (theMemberParams)
FUNCTION
This handler creates a dynamic sprite. It doesn't attach any behaviors
to it. This handler is called in the code generated by wfsWriteMultiSprite
and wfsWriteElement in the 'Script
Writer' script. These latter two handlers are for generating code
to generate copies of dynamic multi-sprites. You shouldn't need to call
wfsCreateSprite if you use the handlers in the 'Script
Writer' script.
PARAMETERS
theMemberParams This is a linear list like
so:
[memberNameOrNumber, castNameOrNumber, ink, blend, width, height, locH,
locV, doNotCreateNewMember]
memberNameOrNumber: The name (string)
or number (as in member(name).membernum) of the cast.
castNameOrNumber: The cast name (string)
or number. member("6: Handle").castLibNum returns the cast
number of member "6: Handle". castlib(member("6: Handle").castLibNum).name
returns the name of the cast of member "6: Handle".
ink: See the Director documentation for
the integer values that correspond with different inks.
blend: A numeric value between 0 and 100.
100 means the sprite will be opaque. 50 means the sprite will be quite
'see through'. 0 means the sprite will be invisible.
width: The width of the sprite
height: the height of the sprite
locH, locV: The location of the sprite.
doNotCreateNewMember is optional. If
you include any value at all for doNotCreateNewMember, then the created
sprite will use the same member specified by theMemberNameOrNumber and
theMemberCastNameOrNumber. If you don't include a value for doNotCreateNewMember,
a copy of the member will be created and used.
RETURN VALUE
The handler returns the spritenum of the new sprite or returns 0 if
the member cannot be found in a cast or there are no available dynamic
channels to create the sprite in. The spritenum of the new sprite is
assigned by the Dynamic Channel Manager.
EXAMPLES
theReturnValue=wfsCreateSprite(["oh","vah",36,100,50,50,10,20])
The above creates a dynamic sprite. The member is a copy of member("oh","vah"),
ie, a new member is created, exactly the same as member("oh","vah").
It is assigned the 'background transparent' ink (36), a blend of 100,
a width and height of 50, and locH of 10 and locV of 20. No value is
assigned to the doNotCreateNewMember parameter, so a new member is created.
After the above line of code has run, theReturnValue will be the spriteNum
of the newly created sprite or 0 if it could not be created.
theReturnValue=wfsCreateSprite(["oh","vah",36,100,50,50,10,20,
1])
Does the same as the first example, only no new member is created.
The member of the newly created sprite is member("oh","vah")
(not a copy of it).
wfsCreateMemberCopy (theMember)
FUNCTION
You should not have to call this handler if you use the public handlers
in the Script Writer script.
wfsCreateMemberCopy creates a copy of the member specified by theMember
parameter. wfsCreateMemberCopy is called by wfsCreateSprite
(which is called by the Script Writer
handlers) if its doNotCreateNewMember parameter is omitted. When wfsCreateMemberCopy
creates a copy of a member, it adds the member.number to a list named
gWFSCreatedMembers.
To destroy members created with wfsCreateMemberCopy, use wfsDestroyMemberCopy.
PARAMETERS
theMember: is the member you want to copy.
As in member(whichMember)
EXAMPLE
wfsCreateMemberCopy(member("bebop"))
creates a copy of member("bebop"), names it the same, and
places it in the same cast as member("bebop").
wfsCreateWindowManager (Name, InitialVisibility, CenterWindow,
ModalStatus, BringToFrontWhenClickedStatus, BringChildrenToFrontWhenClickedStatus,
ParentName, MoveWhenParentMovesStatus, doNotCreateNewMember)
FUNCTION
You shouldn't have to use this if you use the scripts in the Script
Writer script. wfsCreateWindowManager is not called
by any of the WFS code. wfsCreateWindowManager creates a Window Manager.
It doesn't create Window Elements. wfsCreateWindowManager finds an empty
sprite channel, puts the '2: Window Manager' bitmap in that channel,
attaches the '3: Window Manager' behavior to it, and initializes that
behavior according to the parameters.
The wfsCreateWindowManager handler is harder to use than the wfsWriteMultiSprite
handler, which does all the work for you, since you just aim it at a
drag and drop manager and wfsWriteMultiSprite writes the code for you
that creates not only the Window Manager but the whole window.
Why is wfsCreateWindowManager included in WFS then? The Script
Writer handlers are for making copies of entities that you create
static models of. If you don't want to create a static model but create
dynamic windows anyway, you use wfsCreateWindowManager and the below
handlers. They are more work than the Script Writer handlers, but I
thought I'd include them.
PARAMETERS
See documentation on the Window
Manager Parameter Dialog Box for more info on the parameters.
Name: The string
name of the Window Manager you want to create.
InitialVisibility:
A boolean that says whether the window will be visible upon creation.
CenterWindow: A boolean
that says whether the window will be centered on the stage when created.
If so, then the background element of the window (the first element
after the Manager) is centered and all other elements are moved accordingly.
ModalStatus:
An integer in 0-100. 0 means the window is non-modal. 1-100 means the
window is modal.
BringToFrontWhenClickedStatus:
A boolean that determines whether the window is automatically brought
to front when the user clicks on any exposed part of it.
BringChildrenToFrontWhenClickedStatus:
A boolean that determines whether the children are brought to front
when the multi-sprite is clicked.
ParentName:
The string name of the parent window, if it has one. If it has no parent,
ParentName="" (the empty string) or don't specify this parameter.
If you don't specify this parameter, don't specify MoveWhenParentMovesStatus
either.
MoveWhenParentMovesStatus:
A boolean that indicates whether the window is to be moved when the
parent is moved. If the window has no parent, don't specify this parameter.
If you want to specify this parameter, of course you also have to specify
ParentName.
doNotCreateNewMember:
If you specify no value for this parameter, then the manager's member
will be a copy of member("2: Window Manager"). If you specify
1 for this parameter (which is usually what you'd like) then no copy
of member("2: Window Manager ") is made and the manager's
member is the first member("2: Window Manager") encountered.
RETURN VALUE
Returns a positive integer or 0. If it returns a positive integer,
the integer indicates the channel in which the Window Manager was created.
If it returns 0, this indicates that the Window Manager was not successfully
created. If 0 is returned, then a dialog box will be raised to tell
you why, unless it is because there are no more open channels to use.
EXAMPLE
theNewSpriteNum= wfsCreateWindowManager("my window", 1, 30,
1, 1, "my window's parent", 1)
The above creates a Window Manager named "my window". The
window (assuming you add some elements to it) will be visible initially
(1); it is a modal window (30); the window will be brought to front
when any of its elements are clicked (1); the open children will be
brought to front in front of "my window" when "my window"
is clicked (1); the parent of "my window" is "my window's
parent"; "my window" will be dragged along when "my
window's parent" is moved. theNewSpriteNum will be the spriteNum
of the newly created manager.
wfsCreateMenuManager (theName, theInitialVisibility, theMenuRootStatus,
theCloseRootOnSelectionStatus, theParentName, doNotCreateNewMember)
FUNCTION
As with wfsCreateWindowManager, you shouldn't have to use this at all
if you use the handlers in the Script Writer
script. This creates a Menu Manager. wfsCreateMenuManager gets an empty
sprite channel, puts the 'Menu Manager bitmap' bitmap in that channel,
attaches the 'Menu Manager' behavior to it, and initializes that behavior
according to the supplied parameters. It then runs the beginSprite handler
of the 'Menu Manager' behavior. The wfsCreateMenuManager handler is
a bit harder to use than the wfsWriteMultiSprite handler, which does
all the work for you, since you just aim it at a drag and drop manager
and wfsWriteMultiSprite writes the code for you.
PARAMETERS
The parameters you specify are the same as the parameters
you specify when you create a Menu Manager via drag and drop.
theName The
string name of the Menu Manager you want to create. This string must
be unique among the names of currently instantiated multi-sprites or
WFS will issue an alert dialog informing you of the problem. This parameter
is required.
theInitialVisibility:
A boolean involved in the visibility of the menu. If you're creating
the root menu, then set this to 1 if you want the root menu to be visible
initially. Non-root menus are not visible initially. Only the root menu
can be visible initially. So if you're not creating the root menu, set
this to 0. This parameter is required.
theMenuRootStatus:
A boolean that says whether this is the menu root or not. Each menu
system must have one and only one menu root. It is the first menu visible
in the menu system. A movie can have multiple menu systems, but each
one has one and only one menu root. This parameter is required.
theCloseRootOnSelectionStatus:
Set this boolean to 1, if at all, only when you are configuring the
root menu. It does not hurt to set it to 1 if you are not configuring
the root menu, but neither does it have effect, in such case. It only
matters concerning configuration of the root menu. If this parameter
is 1, then when the user selects a menu item, the whole menu system
will be made invisible. If this is 0, then all but the root menu will
be made invisible when the user selects a menu item.
theParentName:
You specify the name of the parent of the menu here. The root menu of
the system may have a window as parent or no parent at all, in which
case you set this parameter to the empty string "". If the
root menu has a window as its parent, then when the user moves the window
around (if they can), the menu system will maintain its position relative
to the window parent. If the root menu has no parent, then the menu
system will stay put absolutely. If you are configuring a non-root menu,
then it must have a menu as parent. Submenus of the root menu should
have the root menu as parent. Submenus of submenu X should have submenu
X as parent. A menu X cannot have menu X as parent. Nor can menu X have
one of its submenus as parent, nor one of the descendents of its submenus
as parent. If this sort of time-travel self-incest were possible, it
would create infinite loops when menus were closed, for instance. WFS
will prompt you to correct such things should you accidentally specify
such sci-fi ancestries. This parameter is required.
doNotCreateNewMember:
If you specify no value for this parameter, then the manager's member
will be a copy of member("Menu Manager bitmap"). If you specify
1 for this parameter (which is usually what you'd like) then no copy
of member("Menu Manager bitmap") is made and the manager's
member is the first member("Menu Manager bitmap") encountered.
RETURN VALUE
Returns a positive integer or 0. If it returns a positive integer,
the integer indicates the channel in which the Menu Manager was created.
If it returns 0, this indicates that the Menu Manager was not successfully
created. If 0 is returned, then a dialog box will be raised to tell
you why, unless it is because there are no more open channels to use.
EXAMPLE
newSpriteNum= wfsCreateMenuManager("my menu", 1, 1, 1, "my
window")
The above is one way to configure a root menu. It's name is "my
menu". It will be visible initially (assuming you add elements
to the manager) because the second parameter is 1; the third parameter
(1) indicates that this is the root menu; the fourth parameter (1) indicates
that when the user selects a menu item, the whole menu will be made
invisible; the last parameter, "my window", indicates that
the parent of the menu is a window named "my window".
wfsCreateElement (memberParams, managerNameOrSpriteNum, initialVisibility)
FUNCTION
You should not need to use this if you use the handlers in the Script
Writer script. This creates a dynamic element of a multi-sprite.
This is a bit different from using wfsWriteElement
to generate code to create a dynamic sprite. wfsCreateElement does not
write code. It uses memberParams to create a sprite with the specified
memberParams. Then it attaches the "4: Window/Menu Element"
behavior to the new sprite. Then it gives the element the specified
manager and initial visibility. Then it runs the beginSprite handler
of the "4: Window/Menu Element"
behavior. Then it returns the spritenum of the new sprite. You can use
wfsCreateElement to make a copy of a dynamic element, for instance.
Whereas wfsWriteElement cannot
copy dynamic elements. Mind you, wfsCreateElement only attaches the
"4: Window/Menu Element" behavior to the sprite. Whereas wfsWriteElement
does more. So wfsCreateElement is more work to use and does less than
wfsWriteElement. wfsCreateElement does not attach other behaviors to
the element, just the "4: Window/Menu Element" behavior. Whereas
wfsWriteElement attaches and initializes all the behaviors attached
to the sprite you're copying.
If you use wfsCreateElement and want to attach other behaviors additional
to the "4: Window/Menu Element"
behavior, then you'd attach them using the wfsAttachBehavior
handler, for your own behaviors, or, concerning attaching other WFS
behaviors, one of the other attachers.
You can destroy elements with the wfsDestroyDynamicSprite
handler or let them be garbage collected at the end of the movie.
PARAMETERS
memberParams
[member name or number, cast name or number, ink, blend, width, height,
locH, locV, doNotCreateMemberCopy] These parameters specify the member
the sprite is to have and the ink etc.
ManagerNameOrSpriteNum:
This can be a positive integer or a string. If it is a positive integer,
it indicates the spritenum of the intended manager of the element to
be created. If a string, then it indicates the name of the intended
manager. The manager should be instantiated.
initialVisibility:
When you attach the "4: Window/Menu Element" behavior via
a drag and drop operation, you specify this parameter in the parameter
dialog box. Note that this does not specify whether the element is visible
upon creation, but whether the element is initially visible *when the
window of which it is a member* becomes visible. Some window elements
are such that you do not want them to be initially visible when the
window or menu becomes visible. Some you do.
RETURN VALUE
Returns an integer indicating the channel the element was created in,
or 0 if the operation failed. If the operation failed, the sprite was
not created. Failure indicates there are no more open channels. If you
specify an uninstantiated managerNameOrSpriteNum, the sprite is assigned
to have no manager.
EXAMPLE
newSpriteNum=wfsCreateElement([45, 3, 36, 100, 10, 20, 30, 40], "my
window", 1)
The above creates a new sprite using member(45, 3). newSpriteNum holds
the spritenum of the newly created sprite. The ink is 36 (background
transparent). The blend is 100 (opaque). The width is 10, the height
is 20, the locH is 30, the locV is 40, and doNotCreateMemberCopy is
unspecified, so the new sprite's member will be a copy of member(45,3).
The element is added to the manager named "my window" and
the element becomes visible (1) when the window becomes visible.
newSpriteNum=wfsCreateElement([45, 3, 36, 100, 10, 20, 30, 40, 1],
"my window", 1)
The above example is exactly the same as the first example except that
doNotCreateMemberCopy is specified as 1. Consequently, the new sprite
will have member(45,3), not a copy of it.
|
1: prepareMovie
2: Window Manager
3: Window Manager
4: Win/Menu Element
5: Close My Window
6b: Handle
Menu Manager
Menu Manager
Menu Verb
Menu item highlight