See Also
|
The "Dynamism" Destructors The "Dynamism" DestructorsThe destructors in the
Though WFS does garbage collection of dynamic sprites at the end of the movie, you may want to destroy elements and/or multi-sprites and/or families of multi-sprites when you are done with them, before the end of the movie. When dynamic sprites are destroyed by the destructors, their channels are returned to the WFS Dynamic Channel Manager and they can be reused by the Dynamic Channel Manager. This handler destroys dynamic sprites. If the sprite isn't dynamic, then all it does is make the sprite invisible. If the sprite is dynamic, then the handler runs the endSprite handler(s), if elementSpriteNum has any, and then destroys the sprite, wipes it out of existence and makes the channel reusable.This handler is called in the stopMovie handler to do garbage collection of dynamic sprites at the end of the movie. It is also called in wfsDestroyDynamicElements and wfsDestroyMultiSprite. Use wfsDestroyDynamicSprite to destroy individual dynamic sprites. They don't have to be elements of multi-sprites for this handler to cleanly destroy them. Also, the sprite channel is returned to the Dynamic Channel Manager for later reuse. elementSpriteNum is the spriteNum of the element you want destroyed. destryoyDynamicMember is a boolean that is optional. If you don't include this parameter, then it is assumed to be FALSE, in which case the sprite's member is not destroyed. If you set destroyDynamicMember to TRUE or 1, then if the member was dynamically created, it is destroyed. If you set destroyDynamicMember to TRUE or 1 and the member was not created dynamically, it isn't destroyed. Normally you set this parameter to 1. WFS keeps a list of dynamically created members. Returns a positive value if the sprite was dynamic and therefore was destroyed successfully. Returns 0 if the sprite is not dynamic (and so cannot be destroyed) or if the elementSpriteNum is a dynamic channel but there's no dynamic sprite in it to destroy. In this case, the channel is cleared for reuse anyway, ie, whatever is there is destroyed. theReturnValue = wfsDestroyDynamicSprite(678, 1) The above destroys sprite 678 and also destroys the member, if it is dynamic. If the member is not dynamic (ie, not created by WFS), it is not destroyed. theReturnValue = wfsDestroyDynamicSprite(678) These above two examples do exactly the same thing: destroy sprite 678 but, unlike the first example, not its member. To see wfsDestroyDynamicSprite used in working code, open the demo source and go to scene 11. Note that when you drag an element onto the garbage can in scene 11, it is destroyed. There's a behavior attached to the numbered gray sprite 18 called "destroy element". That'd be the destroyer. There's a discussion of that code here. You can also see wfsDestroyDynamicSprite in action in tutorial 9
This destroys the dynamic elements of a multi-sprite (by making calls to wfsDestroyDynamicSprite). The multi-sprite manager can be static or dynamic. In either case, only the dynamic elements are destroyed. The manager is not destroyed and neither are the static elements. managerNameOrSpriteNum is an integer or a string. If it's an integer, it refers to the spritenum of a manager of a multi-sprite; if it's a string, it's the name of a manager. If the manager is not instantiated, then wfsDestroyDynamicElements does nothing. destryoyDynamicMembers is a boolean that is optional. If you don't include this parameter, then it is assumed to be FALSE, in which case the dynamic members, if there are any, are not destroyed. If you set destroyDynamicMembers to TRUE or 1, then if any of the members of any of the multi-sprite's dynamic elements were dynamically created, they are destroyed. If you set destroyDynamicMember to TRUE or 1 and a member of a dynamic element was not created dynamically, it isn't destroyed. Normally you would set this parameter to 1. WFS keeps a list of dynamically created members. wfsDestroyDynamicElements("some multi-sprite") In the above and following examples, suppose that there is a multi-sprite named "some multi-sprite" and its manager is sprite 876. It doesn't matter if the manager is dynamic or static.The above two lines would do the same thing: destroy the dynamic elements of "some multi-sprite", but not destroy the dynamic members of the dynamic elements. wfsDestroyDynamicElements("some multi-sprite", 1) The above two lines would do the same thing: destroy the dynamic elements of "some multi-sprite" and also destroy the dynamic members of the dynamic elements. wfsDestroyDynamicElements never destroys non-dynamic members of dynamic elements, ie, you don't have to worry about it destroying your members. It will just destroy dynamic members if instructed.
This destroys a dynamic multi-sprite. A dynamic multi-sprite has a dynamic manager. If the manager is dynamic, all the dynamic elements are destroyed and the manager is destroyed and 1 is the return value. All the endSprite handlers run if they are present. You can assign the child multi-sprites a new parent by assigning a value to newParentOfChildren. If the dynamic multi-sprite has some static members, you can give them a new manager by assigning a value to newManagerOfStaticElements. If the manager is static, wfsDestroyMultiSprite does nothing except close the multi-sprite and return 0. Static multi-sprites (ie, that have a drag and drop manager) cannot be destroyed by the destructor handlers. Nor can any drag and drop sprite be destroyed by the destructor handlers. Drag and drop sprites are destroyed by Director when the playback head enters a frame in which they are no longer instantiated in the Score. Whereas dynamic sprites are instantiated in every frame of the Score until they are destroyed by a destructor or the movie ends and WFS does garbage collection on dynamic sprites in the stopMovie handler. theNameOrManagerSpriteNum is the name of the multi-sprite you want to destroy or the spritenum of the manager. destryoyDynamicMembers is a boolean that is optional. If you don't include this parameter, then it is assumed to be FALSE, in which case the dynamic members, if there are any, are not destroyed. If you set destroyDynamicMembers to TRUE or 1, then if any of the members of any of the multi-sprite's dynamic elements were dynamically created, they are destroyed. If you set destroyDynamicMember to TRUE or 1 and a member of a dynamic element was not created dynamically, it isn't destroyed. Normally you would set this parameter to 1 because if a member was dynamically created, then unless you've done some fancy footwork, it is only allocated to one sprite, and you're destroying that sprite, so you generally have no use to keep the dynamic member around. WFS keeps a list of dynamically created members. If you want to specify newManagerOfStaticElements, you have to specify a value for destroyDynamicMembers. newManagerOfStaticElements This parameter is optional. If you don't specify this parameter or specify it as VOID or 0, then if the multi-sprite has static elements, nothing is done to them. The WFS behaviors are such that elements check to see if their manager is instantiated before they do anything requiring an instantiated manager. If newManagerOfStaticElements is the spriteNum or name of an instantiated manager, then wfsDestroyMultiSprite assigns the static elements this new manager. But the dynamic elements will be toast at the end of wfsDestroyMultiSprite. if you want to specify newParentOfChildren, you have to specify a value for newManagerOfStaticElements. newParentOfChildren This parameter is optional. If it isn't specified ( is VOID) or is is 0, then the child multi-sprites are assigned to have no parent. If, on the other hand, you specify a value (spritenum or name) of an instantiated manager, then the children are given this new parent. Returns a boolean that indicates whether the destruction was successful. If it returns 0, that means that the multi-sprite was not instantiated or the multi-sprite is static (has a static manager). Assume there is a multi-sprite named "ae" and its manager is sprite 486. theReturnValue=wfsDestroyMultiSprite("ae") The above two lines would do the same thing: destroy all the dynamic sprites (including the manager) in "ae" but none of the members. If the manager of "ae" is static, it would do nothing and return 0. If the manager was dynamic and the multi-sprite had some dynamic elements and some static elements, the manager would be destroyed and so would the dynamic elements, but the static elements would be unchanged. theReturnValue=wfsDestroyMultiSprite("ae", 1) The above would destroy all the dynamic sprites in "ae" and also destroy the dynamic members of the dynamic elements. Dynamic members are members created by WFS. It will never destroy static members, ie, you don't have to worry about it destroying your members. In the below examples, assume that "ou" is the name of an instantiated manager. theReturnValue=wfsDestroyMultiSprite("ae", 1, "ou") This would do the same as wfsDestroyMultiSprite("ae", 1) except if there were any static elements in "ae" (not including the manager), they would become managed by "ou". In the below example, suppose that "iy" is the name of an instantiatiated manager. theReturnValue=wfsDestroyMultiSprite("ae", 1, "ou", "iy") The above would do the same as wfsDestroyMultiSprite("ae", 1, "ou") except that if "ae" had any child multi-sprites, they would become managed by "iy". You can see wfsDestroyMultiSprite in action in tutorial 10 and in the feature tour in scene 11.
This destroys a dynamic family of multi-sprites from managerNameOrSpriteNum through all descendants. It destroys the remotest descendants first. After all the descendants have been destroyed, it destroys the managerNameOrSpriteNum multi-sprite. The optional newManagerOfStaticElements parameter allows you to assign static elements (if there are any) a new manager. All dynamic elements and managers in the family are destroyed. This handler does nothing to static multi-sprites (a static multi-sprite has a static manager) or the descendants of static multi-sprites except close them (make them invisible). theNameOrManagerSpriteNum is the name of the window you want to destroy or the spritenum of the manager. wfsDestroyMultiSprite checks this value in gWFSMultiSpriteList to see if it corresponds with an instantiated Manager. If there is no such instantiated Manager, wfsDestroyMultiSprite returns 0. destryoyDynamicMembers is a boolean that is optional. If you don't include this parameter, then it is assumed to be FALSE, in which case the dynamic members, if there are any, are not destroyed. If you set destroyDynamicMembers to TRUE or 1, then if any of the members of any of the multi-sprite's dynamic elements were dynamically created, they are destroyed. If you set destroyDynamicMember to TRUE or 1 and a member of a dynamic element was not created dynamically, it isn't destroyed. Normally you would set this parameter to 1 because if a member was dynamically created, then unless you've done some fancy footwork, it is only allocated to one sprite, and you're destroying that sprite, so you generally have no use to keep the dynamic member around. WFS keeps a list of dynamically created members. If you want to specify newManagerOfStaticElements, you have to specify a value for destroyDynamicMembers. newManagerOfStaticElements This parameter is optional. If it is the name or spritenum of an instantiated manager, then wfsDestroyMultiSpriteFamily gives static elements this new manager. If you do not specify this parameter, nothing is done to the static elements, if there are any. Returns a boolean that indicates whether the destruction was successful. If it returns 0, that can mean that the window was not instantiated or the Window Manager is static. To see wfsDestroyMultiSpriteFamily used in code, look at scene 10. If you click the button at top right of the window before you click "create", you are operating on a static family. What happens, since it's a static family, is that the family is simply made invisible by wfsDestroyMultiSpriteFamily. wfsDestroyMultiSpriteFamily cannot destroy static sprites. However, if you click "create" to create a dynamic family and then click the button at top right of the window, wfsDestroyMultiSpriteFamily runs to destroy the entire family. Look in the demo source code at the "Destroy family on mouseup" behavior attached to the button to see the handler that calls wfsDestroyMultiSpriteFamily. wfsDestroyMultiSpriteFamily is also used in the code of scene 11. Note that in scene 11 you can click "create" (not "create element") to create a dynamic window. The window has no children or parent. It is a family of one multi-sprite. The blue button at the top right of the window has the "Destroy family on mouseup" behavior attached to it. This behavior calls wfsDestroyMultiSpriteFamily. Let's look at some other examples that examine the parameters in more detail. In the below examples, assume that "ae" is the name of a multi-sprite (though we could as well use the spritenum of its manager). theResult = wfsDestroyMultiSpriteFamily("ae") The above destroys "ae" and all its descendants (assuming they are all dynamic), but no members. theResult = wfsDestroyMultiSpriteFamily("ae",1) The above destroys "ae" and all its descendants (assuming they are all dynamic) and all dynamic members of dynamic elements. Dynamic members are members created by WFS. Don't worry: WFS will never destroy members from your cast that you have created regardless of how you configure the second parameter. theResult = wfsDestroyMultiSpriteFamily("ae",1, "ou") In the above example, suppose "ou" is the name of an instantiated manager. The above does the same as wfsDestroyMultiSpriteFamily("ae",1) except if there are any static elements among the multi-sprites, they are assigned to have a new manager: "ou". Assuming that their manager had been dynamic--because wfsDestroyMultiSpriteFamily does nothing to multi-sprites (or their descendants) that have static managers. You can see wfsDestroyMultiSpriteFamily in action in scene 10 of the feature tour. When you click the button at top right of a dynamic copy of the family, wfsDestroyMultiSpriteFamily runs.
You should not have to call this if you use the above destructors, which call wfsDestroyMemberCopy if so configured via the destroyDynamicMembers parameter. wfsDestroyMemberCopy destroys a member created by wfsCreateMemberCopy. theMemberNumber is an integer as in member(whichMember).number Suppose 12345 is the member number of some member. Then
|
| The
"Dynamism" Destructors |
|
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
"Dynamism"