Click to go to the home page.

See Also
"Script Writer" Movie Script
wfsWriteMultiSpriteFamily
wfsWriteMultiSprite
"Dynamism" Movie Script

 

Site Nav

css drop down menu by Css3Menu.com

Script Writer wfsWriteElement Handler

wfsWriteElement  (spriteToCopy, doNotCreateNewMember)

Click to go to top of section. Function

wfsWriteElement generates and returns a handler that you use to create a dynamic copy of a static element of a multi-sprite. You call wfsWriteElement from the Director Message Window while the movie is running and the target sprite is instantiated like so:

put wfsWriteElement(spriteToCopy, doNotCreateNewMember)

Lingo code is then output to the Message Window which you copy and paste into a movie script.

The wfsWriteElement handler is in the "Script Writer" movie script.

Click to go to top of section. Parameters

spriteToCopy is an integer. It is the spriteNum of the element you want to copy. It must be an element of a multi-sprite.

doNotCreateNewMember determines whether the generated code will create a copy of the member of spriteToCopy, or whether the generated code will use the same member used by spriteToCopy. If you do not specify this parameter then a new copy of the member of spriteToCopy will be used. If you specify any integer value at all for this parameter, then the same member used by spriteToCopy will be used by the new dynamic sprite.

Click to go to top of section. Return Value

wfsWriteElement returns a handler that you paste into a movie script. The name of the returned handler

  • starts with "wfsCreate".
  • Then the name contains the name of the member of the sprite you aimed wfsWriteElement at.
  • Then the name contains the string "Element".
  • Then it contains the sprite channel number of the static model (ie, spriteToCopy).
  • Then the name contains the string "Frame".
  • Finally, the name contains the frame number in which wfsWriteElement was executed.

So, for instance, a call to

put wfsWriteElement(17)

where sprite 17 has member "copyme" might produce a handler named wfsCreatecopymeElement17Frame638 if wfsWriteElement was executed in frame 638.

The handlers generated by wfsWriteElement, when run, will create a dynamic copy of the element you aimed wfsWriteElement at. And the sprite will be added as an element of the multisprite you specify in the parameter.

For instance, if you called

put wfsWriteElement(17)

and that produced a handler named wfsCreatecopymeElement17Frame638 then the following call from somewhere in your movie would create a new sprite that's a copy of sprite 17 and would add it as an element to the multi-sprite named "yobaby".

theNewSpriteNum = wfsCreatecopymeElement17Frame638("yobaby")

theNewSpriteNum would hold the spriteNum of the newly created sprite or 0 if there were no available dynamic channels to create it it.

Click to go to top of section. Example

You can see an example of the use of wfsWriteElement in the feature demo source code in scene 11. When you click the text that says "create element" a dynamic copy of the element 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.

  1. We make sure the movie has a copy of the "1: prepareMovie", "Dynamism", and "Script Writer" movie scripts in a cast.

  2. We edit the value of gWFSLastStaticSpriteChannel in the 'initializeDynamism' handler of the "Dynamism" script, as per instructions, if we haven't already done so. 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 sprite creation.

  3. The static model of the window named "11.1" was created in the Score, including sprite 18, which we will aim wfsWriteElement at.

  4. Start the movie and navigate to a frame where the static model of the target sprite 18 is instantiated. In the case of this example, we navigate to scene 11 in the movie.

  5. Now we run wfsWriteElement from the Message Window. It takes two parameters. The first parameter is the spriteNum of element we want to create dynamic copies of. The second parameter determines whether the dynamic element's member will be the same as the static model's member, or whether the members of the dynamic elements will be new copies of the static model's member. If you don't need to create new members, it's best not to because they take up extra resources. But we need the dynamic members to have their own member, because if you click "create element" in scene 11, you see that each newly created dynamic element has a different text. This would be impossible if the dynamic elements shared the same member. So we type

    put wfsWriteElement(18)

    in the Message Window and, consequently, we see a handler appear in the Message Window.

    wfsWriteElement output a handler named "wfsCreatecopymeElement18Frame630". The form of the name of the handlers produced by wfsWriteElement is described in the Return Value section.

  6. The "wfsCreatecopymeElement18Frame630" 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.

  7. Unlike the wfsWriteMultiSprite and wfsWriteMultiSpriteFamily handlers, we won't need to edit the output code.

  8. We need to write some Lingo that calls the "wfsCreatecopymeElement18Frame630" handler. The code generated by the wfsWriteElement handler, if you look at it, takes a parameter called "managerNameOrSpriteNum". This lets us specify the multi-sprite to which we want to add the newly created element.

    If you look at the code for the "create element" behavior attached to the text that says "create element" (sprite 16 in the Score) you see the below code:

    on beginsprite me

      pCounter=1

      --The value of this counter is the text of newly created elements.

    end

     

    on mouseup me

      if the clickOn = spritenum then

        --If spritenum is the sprite that was clicked, then proceed.

        myManagerSpritenum=sprite(spritenum).wfsGetMyManagerSpriteNum()

        --The sprite this script is attached to has to be an element of a multi-sprite

        --for the above line to work.

        theNewSpriteNum = wfsCreatecopymeElement18Frame630(myManagerSpritenum)

        --Here is where the new element is created.

        --wfsCreatecopymeElement18Frame630 is in the 'generated1' movie script in the 'WFS 4' cast.

        if theNewSpritenum > 0 then

          --If a sprite was created, then set its text

          pCounter = pCounter + 1

          sprite(theNewSpritenum).member.text = string(pCounter)

        end if

      end if

    end

    When you click the text that says "create element", the above mouseUp handler runs, which calls "wfsCreatecopymeElement18Frame630" and a dynamic multi-sprite is created. theNewSpriteNum will hold the spritenum of the newly created element or 0 if the element could not be created.

    wfsGetMyManagerSpriteNum is documented in the "4: Window/Menu Element" API.

  9. As you can see if you run the movie and navigate to scene 11, you can click "create element" repeatedly and, each time, a new element will be created as long as there is a dynamic channel available. If there isn't, "wfsCreatecopymeElement18Frame630" will return 0 and not create anything.

  10. Note also that if you drag dynamic elements onto the trash can in scene 11, they are destroyed. Dynamic elements have a behavior attached to them named "destroy element". That behavior (attached to sprite 18 in our example) contains the below code, which calls the wfsDestroyDynamicSprite destructor:

    --This behavior (named "destroy element") is attached to the
    --static model of the dynamic element in scene 11 (sprite 18).
    --Note that this behavior is the last behavior attached to sprite
    --18. When you attach a behavior that destroys the sprite
    --to which it is attached, best to make it the last behavior
    --attached to the sprite.

    property spritenum

    on mouseup me
      --This runs wfsDestroyDynamicSprite and destroys the sprite that
      --this behavior is attached to.  It also destroys the sprite's member
      --if the member was created by WFS. When wfsDestroyDynamicSprite
      --is executed on static sprites, they are made invisible, not destroyed.
      if the clickon = spritenum then
        --Proceed only if this sprite was clicked on.
        myManager=sprite(spritenum).wfsGetMyManagerSpritenum()
        --wfsGetMyManagerSpritenum is a handler in the
        --"4: Window/Menu Element" behavior which is
        --attached to sprite 18.
        trashCanSpritenum=sprite(myManager).wfsGetElementNamed("trash can")
        --In the Score, the trash can is sprite 17. But, in scene 11, when we click
        --"create multisprite", a dynamic copy of the window is created, and the
        --trash can in the dynamic copy will not be sprite 17. Still, we have to check
        --if the dynamic draggable sprite was dropped on the trash can in its
        --window. How do we know what sprite the trash can is? Both sprite 17
        --and dynamic copies of it are named "trash can" (via the "4: Window/Menu
        --Element" behavior). And any given copy of the window has one and only
        --one element named "trash can". So, in the above line, we find the spritenum
        --of the element named "trash can" in the current window managed by
        --myManager. In the above line, we see the value of the new WFS ability
        --to name elements. It makes referring to sprites easier once we start creating
        --dynamic multi-sprites. For more info on naming elements, see the doc on
        --the "4: Window/Menu Element" behavior.
        if sprite spritenum intersects trashCanSpritenum then
          --If the current sprite intersects with the trash can
          --in its own window, then destroy the current sprite.
          --Do a search in the WFS HTML docs on
          --wfsDestroyDynamicSprite for more info on this handler
          --stored in the "Dynamism" script.
          cursor 0
          theResult=wfsDestroyDynamicSprite(spritenum, 1)
        end if
      end if
    end

    The primary thing about the above handler is that it calls wfsDestroyDynamicSprite. The second parameter in the call to wfsDestroyDynamicSprite being 1 means that if the destroyed sprite has a dynamic member (a dynamic member means it was created by WFS) then the member is destroyed too.

    wfsGetMyManagerSpriteNum is a handler you can run from code attached to an element to determine what the spritenum of its manager is.

    Note that the above code takes advantage of the ability to name elements in WFS. For more information on naming elements, see the discussion about it in the doc on the "4: Window/Menu Element" behavior. There are several handlers you can use related to the naming of elements including the wfsGetElementNamed handler used above.

Note that if you change the static model, you need to call wfsWriteElement again to regenerate the code. Otherwise, the generated code will produce the old version of the static model.

You can delete the "Script Writer" handler from the cast when you are finished generating code. All it does is generate code. None of the handlers are called at run-time.

You can also delete the static model from the Score when your project is all finished, if you want, though you don't have to. The code that wfsWriteElement generates does not depend on the static model being present in the Score. But don't delete the cast member of the static model. The code generated by wfsWriteElement needs that cast member.

If you want to delete the Script Writer and static model before publishing your project, best to make a copy of the .DIR that DOES contain the static model, because if you want to go back and edit the project, you'll want that static model around rather than having to rebuild it.

 
Click to go to the home pageScript Writer wfsWriteElement Handler