Broker Script

A Broker Script is a Movie Script which stores an instance of itself as a property. As a Movie Script, the Broker is able to accept handler calls from anywhere in the movie. These calls are forwarded to handlers with similar names in the instance of the script. The instance of the script is able to store properties.

A Broker Script can thus act as a singleton object with both Public and Private handlers.

Example

Here is a simplistic example to demonstrate the Public, Script and Private parts of a Broker Script.

-- PUBLIC METHODS --

on PublicMethod(aParameter) -----------------------------------------
  -- INPUT: <aParameter> can be any Lingo value
  -- ACTION: Stores aParameter for later retrieval
  -- OUTPUT: Returns the previously stored value of pPrivateProperty
  -- NOTE:   There must be no other Movie Script with a handler named
  --         PublicMethod.
  --------------------------------------------------------------------

 vBroker = mUniqueBrokerHandlerName()
  return vBroker.mPrivateMethod(aParameter)
end PublicMethod

-- SCRIPT PROPERTY AND METHOD --

property broker

on mUniqueBrokerHandlerName() ---------------------------------------
  -- SOURCE: Called by all Public Methods
  -- ACTION: Checks if this Broker has been instantiated yet, and if
  --         not, instantiated the Broker on a Just-In-Time basis.
  -- OUTPUT: Returns a pointer to instance of this script stored as
  --         the .broker property of the script
  -- NOTES:  There must be no other Movie Script with a handler named
  --         mUniqueBrokerHandlerName.  The script name used in the
  --         first line of this handler must correspond to the name
  --         of this script member.
  -------------------------------------------------------------------

  vScript = script("Name of this Script") -- HARD-CODED string name
  vBroker = vScript.broker

  if voidP(vBroker) then
    vBroker = vScript.new() -- implicit handler
    vBroker.mInitialize()
    vScript.broker = vBroker
  end if

  return vBroker
end mUniqueBrokerHandlerName

-- "PRIVATE" PROPERTIES AND METHODS --

property pPrivateProperty

on kill(me) ----------------------------------------------------------
  -- SOURCE: Called by a Garbage Collection script
  -- ACTION: Ensures that all reciprocal pointers are cleaned up, in
  --         order to avoid memory leaks
  --------------------------------------------------------------------

  -- Custom code here
end kill

on mInitialize(me) ---------------------------------------------------
  -- SOURCE: Called by mUniqueBrokerHandlerName() the first time a
  --         Public Method of this script is called
  -- ACTION: Initializes any private properties of the .broker
  --         instance
  --------------------------------------------------------------------

  pPrivateProperty = #default -- or some more useful value
end mInitialize

on mPrivateMethod(me, aParameter) ------------------------------------
  -- SOURCE: Called by PublicMethod
  -- INPUT: <aParameter> can be any Lingo value
  -- ACTION: Stores aParameter in pPrivateProperty
  -- OUTPUT: Returns the previously stored value of pPrivateProperty
  --------------------------------------------------------------------

  vTemp = pPrivateProperty
  pPrivateProperty = aParameter

  return vTemp
end mPrivateMethod

put PublicMethod("some Lingo value")
-- #default

put PublicMethod("retrieve the previous value")
-- "some Lingo value"

Usage

Broker Scripts are useful where you want to control a unique aspect of a movie from a single script, while allowing any script in the movie to access the handlers in that script.

You might, for instance, want to develop a Cursor Broker, a Menu Broker, or even a Debug Broker to handle exceptions.

A Broker Script will retain the values of its properties even when you run clearGlobals.

Resetting a Broker Script

The properties of a Script Member are set to VOID when the script is recompiled. Director sends no events to a Movie Script before it is recompiled, so there you may be unable to avoid a memory leak (See Garbage Collection, unless you manually call a handler in the Broker before you recompile.

Here's a movie script that could be used to reset all Brokers in a movie that have an on kill() handler.

-- RESET BROKERS --

on ResetBrokers(aShowResetFlag) --------------------------------------
  -- ACTION: Seeks out all Movie Scripts with a property named broker,
  --         cleans up any .broker instance and sets its value to VOID
  --------------------------------------------------------------------

  if voidP(aShowResetFlag) then
    aShowResetFlag = 1
  else
    aShowResetFlag = (aShowResetFlag <> 0)
  end if

  vLastLib = the number of castLibs
  repeat with vLastLib = 1 to vLastLib
    vCastName = QUOTE&castLib(vLastLib).name&QUOTE

    vLastMember = the number of members of castLib vLastLib
    repeat with vNum = 1 to vLastMember

      vMember = member(vNum, vLastLib)
      if vMember.type = #script then
        if vMember.scriptType = #movie then
          vScriptText = vMember.scriptText

          if offset(RETURN&"property broker", vScriptText) then
            -- We have found a Movie Script with a .broker property
            vScript = script(vMember)

            if objectP(vScript.broker) then
              if vScript.handler(#kill) then
                vScript.kill()
              end if

              vScript.broker = VOID

              if aShowResetFlag then
                vName = vMember.name
                put "Reset "&vName&": script("&vNum&", "&vCastName&")"
              end if
            end if
          end if
        end if
      end if
    end repeat
  end repeat
end ResetBrokers

Examples

Xtra Broker for Macintosh or Windows