-- XTRA BROKER -- -- -- © September 2003, OpenSpark Interactive Ltd -- -- ---------------------------------------------------------------------- -- 050512 JN: XtraInfo() now accepts a string parameter, to limit the -- creation of xtra info fields to those xtras whose name -- starts with the given string. -- 050403 JN: XtraInstance(#FileXtra) now returns a singleton instance -- as does FileXtra() -- 050208 JN: Corrected call to mFileXtraInstance() in mXtraInstance() -- 041026 JN: XtraInfo() added -- 040301 JN: XtraInstance() now correctly shows an alert if only the -- xtra string is given, but the xtra is absent. -- 040226 JN: #FileXtra and "FileXtra" added as aliases for FileXtra3 -- or FileXtra4 ---------------------------------------------------------------------- -- This broker script provides four global handlers that allow you to -- check what Lingo xtras are present, and to instantiate any instance -- of any Lingo xtra in a clean manner. -- -- XtraInstance() -- -------------- -- -- If you use a direct call... -- -- vInstance = xtra("Missing Xtra") -- -- ... the Director Player will report a script error and halt. If -- you use an indirect call... -- -- vInstance = XtraInstance("Missing Xtra") -- -- ... vInstance will take the value 0. Your code can then check for -- (not vInstance). This script will automatically show an alert if -- the xtra is missing, unless you explicitly use FALSE as a second -- parameter to the call. -- -- XtraMissing() -- ------------- -- -- You can also use this script at the beginning of a movie to check -- if all the Lingo xtras required by the movie are present: -- -- on startMovie() -- vXtras = [#fileIO, #MUI, #BudAPI] -- if XtraMissing(vXtras, TRUE) then -- halt -- end if -- end startMovie -- -- XtraListing() -- ------------- -- -- You can determine which Lingo xtras are available to the Director -- Player by asking for the name of each xtra in turn. Alternatively, -- a call to XtraListing() will return an alphabetical list of names -- of all the available Lingo xtras as symbols -- -- XtraInfo() -- ---------- -- -- This creates a series of field members, each containing the -- interface() information for a Scripting Xtra. ---------------------------------------------------------------------- -- "PUBLIC METHODS" -- on XtraInstance(anXtra, aParameter, showAlert) ----------------------- -- INPUT: should be a string or symbol xtra name -- can be any Lingo value required for the -- xtra's new() method. If aParameter is 0, and -- is VOID, the 0 will be taken as the value of showAlert. -- only has an effect if it is FALSE, in which -- case an alert will not be shown if the xtra cannot be -- instantiated. To avoid showing an alert in a projector, -- use: -- vInstance = XtraInstance("aXtra", the runmode = "Author") -- OUTPUT: Returns an instance of the given xtra, or 0 if the -- instance cannot be created -------------------------------------------------------------------- vBroker = mXtraBroker() return vBroker.mXtraInstance(anXtra, aParameter, showAlert) end XtraInstance on FileXtra(aClear) ------------------------------------------------ -- ACTION: Creates a singleton instance of FileXtra, or deletes it -- if aClear is #clear -- OUTPUT: Returns the singleton instance of FileXtra, or 0 if the -- instance is cleared or cannot be created -------------------------------------------------------------------- vBroker = mXtraBroker() return vBroker.mXtraInstance(#FileXtra, aClear, 1) end XtraInstance on XtraMissing(anXtra, showAlert) ------------------------------------ -- INPUT: may be a string or symbol xtra name, or it may be -- a list of such strings or symbols. Symbols are -- recommended since symbol comparison is not case- -- sensitive. -- only has an effect if it is FALSE, in which -- case an alert will not be shown if the xtra cannot be -- instantiated. To avoid showing an alert in a projector, -- use: -- vInstance = XtraInstance("aXtra", the runmode = "Author") -- ACTION: If is a list, all the available xtras are -- removed from the list so that only the missing names -- remain. -- OUTPUT: Returns the number of missing xtras. -------------------------------------------------------------------- vBroker = mXtraBroker() return vBroker.mXtraMissing(anXtra, showAlert) end XtraMissing on XtraListing() ----------------------------------------------------- -- OUTPUT: Returns an alphabetical list of names of all the -- available Lingo xtras as symbols -------------------------------------------------------------------- vBroker = mXtraBroker() return vBroker.pXtraList end XtraListing on XtraInfo(aString) ------------------------------------------------- -- INPUT: may be the beginning of an xtra name. If this -- is the case, only xtras whose names start with aString -- will be dealt with. -- ACTION: Creates a field member for each of the Scripting Xtras -- available to Director. Each field will contain the -- data returned by xtra(i).interface() -------------------------------------------------------------------- if not stringP(aString) then aString = "" end if vCount = the number of xtras onMac = the platform starts "Mac" repeat with i = 1 to vCount vXtra = xtra(i) vName = vXtra.name if vName starts aString then vField = new(#field) vField.name = vName vField.rect = rect(0, 0, 640, 0) -- height adjusts automatically if onMac then vField.font = "Monaco" vField.fontSize = 9 else vField.font = "Courier New" vField.fontSize = 12 end if vField.text = vXtra.interface() end if end repeat end XtraInfo -- ================================================================ -- -- SCRIPT PROPERTY AND METHOD -- property broker on mXtraBroker() ----------------------------------------------------- -- SOURCE: Called by all Public Methods except XtraInfo() -- ACTION: Creates an instance of this script, if none exists, and -- stores it as the .broker property of the script itself. -- OUTPUT: Returns a pointer to the .broker instance -------------------------------------------------------------------- vScript = script("Xtra Broker") -- HARD-CODED script name vBroker = vScript.broker if voidP(vBroker) then vBroker = vScript.new() -- implicit handler vBroker.mInitialize() vScript.broker = vBroker end if return vBroker end mXtraBroker -- ================================================================ -- -- PRIVATE PROPERTIES AND METHODS -- property pXtraList -- list of Lingo xtra names as symbols property pFileXtra -- singleton instance of FileXtra on mInitialize(me) --------------------------------------------------- -- SOURCE: Sent by mXtraBroker() -- ACTION: Creates an alphabetical list of names of all the -- available Lingo xtras as symbols (to avoid case- -- sensitivity) -------------------------------------------------------------------- pXtraList = [] pXtraList.sort() i = the number of xtras repeat while i pXtraList.add(symbol(xtra(i).name)) i = i - 1 end repeat end mInitialize -- ================================================================ -- -- PRIVATE METHODS on mXtraInstance(me, anXtra, aParameter, showAlert) ------------------ -- SOURCE: Called by XtraInstance() -- INPUT: should be a string or symbol xtra name -- can be any Lingo value required for the -- xtra's new() method. If aParameter is 0, and -- is VOID, the 0 will be taken as the value of showAlert. -- only has an effect if it is FALSE, in which -- case an alert will not be shown if the xtra cannot be -- instantiated. -- OUTPUT: Returns an instance of the given xtra, or 0 if the -- instance cannot be created -------------------------------------------------------------------- -- Allow showAlert as the second and last parameter if integerP(aParameter) then -- not VOID if not aParameter then if voidP(showAlert) then -- The xtra needs no parameter and no alert should be shown aParameter = VOID showAlert = 0 end if end if end if -- Special cases case anXtra of #FileXtra, #FileXtra3, #FileXtra4, \ "FileXtra", "FileXtra3", "FileXtra4": return me.mFileXtraInstance(aParameter, showAlert) #DirectImage, "DirectImage": if voidP(aParameter) then aParameter = 0 end if -- Add other special cases here end case if me.mXtraMissing(anXtra, showAlert) then vInstance = 0 else -- Try to instantiate the xtra if not stringP(anXtra) then anXtra = string(anXtra) end if if voidP(aParameter) then vInstance = xtra(anXtra).new() else vInstance = xtra(anXtra).new(aParameter) end if if ilk(vInstance) <> #instance then -- The xtra exists, but instantiation failed vInstance = 0 if not (integerP(showAlert) and (not showAlert)) then alert "The xtra ""E&anXtra"E&" could not be instantiated." end if end if end if return vInstance end mXtraInstance on mFileXtraInstance(me, aClear, showAlert) -------------------------- -- SOURCE: Called by mXtraInstance() if anXtra is one of the -- versions of FileXtra -- INPUT: may be #clear, in which case the singleton -- instance is cleared from memory -- only has an effect if it is FALSE, in which -- case an alert will not be shown if the xtra cannot be -- instantiated. -- OUTPUT: an instance of FileXtra4, or failing that an instance of -- FileXtra3, or failing that, 0. -- NOTE: Since the same FileXtra instances can be used and reused -- without any conflicts, a singleton instance is retained -- for the duration of the movie. -------------------------------------------------------------------- if aClear = #clear then pFileXtra = VOID return 0 end if if not pFileXtra then -- FileXtra has not yet been instanciated: create and store a -- singleton instance. vFileXtras = [#FileXtra3, #FileXtra4] if me.mXtraMissing(vFileXtras, 0) then -- At least one of the FileXtras is missing... if not vFileXtras.getPos(#FileXtra4) then -- ... but it isn't FileXtra4 pFileXtra = xtra("FileXtra4").new() else if not vFileXtras.getPos(#FileXtra3) then -- Only FileXtra3 is available pFileXtra = xtra("FileXtra3").new() else -- Both xtras are missing pFileXtra = 0 end if else -- We have a choice: we'll use FileXtra4 pFileXtra = xtra("FileXtra4").new() end if if ilk(pFileXtra) <> #instance then pFileXtra = 0 if not (integerP(showAlert) and (not showAlert)) then alert "Unable to create an instance of FileXtra." end if end if end if return pFileXtra end mFileXtraInstance on mXtraMissing(me, anXtra, showAlert) ------------------------------- -- SOURCE: Called by XtraMissing(), mXtraInstance() or -- mFileXtraInstance() -- INPUT: may be a string or symbol xtra name, or it may be -- a list of such strings or symbols. Symbols are -- recommended since symbol comparison is not case- -- sensitive. -- only has an effect if it is FALSE, in which -- case an alert will not be shown if the xtra cannot be -- instantiated. -- ACTION: If is a list, all the available xtras are -- removed from the list so that only the missing names -- remain. -- OUTPUT: Returns the number of missing xtras. -------------------------------------------------------------------- case ilk(anXtra) of #symbol: vResult = not pXtraList.getPos(anXtra) #string: vResult = not pXtraList.getPos(symbol(anXtra)) #list: i = anXtra.count repeat while i vXtra = anXtra[i] if not symbolP(vXtra) then vXtra = symbol(vXtra) end if if pXtraList.getPos(vXtra) then anXtra.deleteAt(i) end if i = i - 1 end repeat vResult = anXtra.count otherwise: -- anXtra is an invalid expression return TRUE end case if vResult then -- One or more xtras are missing if not (integerP(showAlert) and (not showAlert)) then if vResult = 1 then if listP(anXtra) then vAlert = "The following xtra is missing:"&RETURN&anXtra[1] else vAlert = "The following xtra is missing:"&RETURN&anXtra end if else vAlert = "The following xtras are missing:" repeat with i = 1 to vResult put RETURN&anXtra[i] after vAlert end repeat end if alert vAlert end if end if return vResult end mXtraMissing