An Unofficial FaceSpan FAQ

Revision 1.1

Updated February 1, 2000

Contents

1. Basic Information

  1. What is FaceSpan?
  2. What is AppleScript?
  3. Why would I use FaceSpan?
  4. What is the current version of FaceSpan?

2. Design Questions

  1. I'm seeing a white box when my application is launched. How do I get rid of it?
  2. How can I avoid the "Where is application 'xxxx'?" dialog?
  3. My idle handler is never called. Why is that?
  4. What's safe to use on a Windoid I want to float on other applications?
  5. Is it safe to create and/or make extensive changes to storage items at runtime?
  6. How do I make a button that closes its window and then does something?

3. Scripting Questions

  1. How do I "type as user" the tab, enter, or return keys?
  2. My application won't quit, no matter how I tell it to. How can I fix it?
  3. How can I make sure the application I want to tell to is there?
  4. How can I get the time of a date? ("time of (current date)" returns an error)
  5. How can I prevent the "Where is application xxx?" dialog?

4. Development Environment Questions

  1. Why can I open a Run-Only Application in the Development Environment?
  2. I imported some icons, deleted them, then imported more and my old icons are back. What happened?

5. Other FaceSpan Questions

  1. How do I give my application a unique creator code?
  2. How do I make a windoid float on all apps?

6. Resources

  1. Where can I go to get FaceSpan information?
    1. Websites and FTP
    2. Mailing Lists
  2. Where can I go to get AppleScript information?
    1. Websites and FTP
    2. Mailing Lists

Appendix A: About this FAQ

  1. What is a FAQ?
  2. Where can I get the FAQ?
  3. What are these funny symbols in the text?
  4. Legal Notes

(* indicates new/updated sections)


1. Basic Information

  1. What is FaceSpan?

    FaceSpan(TM) is a development environment and user interface enhancement for AppleScript made by Digital Technology International.

  2. What is AppleScript?>

    AppleScript is a scripting language that allows you to easily control applications that are designed for it. Many current Macintosh applications are scriptable. AppleScript generally reads like English (at least, for those of you with English systems). Here's a simple AppleScript that will put a file in the Trash:

    tell application "Finder"
      set theFile to choose file with prompt "Which file should I Trash?"
      delete theFile
    end tell
    
  3. Why would I use FaceSpan?

    FaceSpan has many attractive features for making larger script applications:

    FS gives scripts an easy way to have a complex user interface. Most scripts are very limited in ways they can interact with the user, and without additional scripting additions can only choose files, folders, or a 1-3 button dialog with or without a text input field. FaceSpan gives you the ability to create many types of windows and menus. You can make a script application that looks and behaves like a "real app".

    AppleScripts can be limited to 32k, if you are using the Script Editor. FaceSpan lets you have 32k per object, giving almost unlimited script sizes.

  4. What is the current version of FaceSpan?

    FaceSpan's latest version is 3.0.1, and this FAQ is written with users of that version in mind. An updater from version 3.0 is available from DTI at ftp://www.facespan.com/facespan/FaceSpan3.0update.hqx.

    You must buy an upgrade to move from version 2.1 or below to 3.x.

    FaceSpan is still in development by DTI; hopefully a new version will be released soon.

2. Design Questions

  1. I'm seeing a white box when my application is launched. How do I get rid of it?

    Probably your app brought up a "Where is application xxx?" dialog when it was in the background (or when it's floating on another app). Two things cause "Where is application xxx?" dialogs in FaceSpan:

    1. tell application "Application Name" in a script
    2. Miniature apps asking for the FaceSpan Extension.

    Other non-FaceSpan Dialogs (choose file, display dialog) may also cause this problem if they are called from a Floating Windoid and your application isn't frontmost.

    There is no good solution other than coding around it. Make sure you include the FaceSpan Extension in apps that are being distributed which are commonly launched in the background. Make sure any apps you tell to by name are already running, or code around this using the methods discussed in the next question.

  2. How can I avoid the "Where is application 'xxxx'?" dialog?

    In FaceSpan scripts, the normal methods of double-telling discussed on many Applescript websites won't work. There are a few ways you can use in FaceSpan to avoid the "Where is application xxx" dialog:

    1. Using Raw Events

      One way to prevent the "Where is application xxx" dialog is to exchange all of your 'tell application "MyApp"' statements with tell statements targeting an application by variable. Then you use the raw event language of your app or the faux OSAX technique to write the scripts your app uses.

      Also, MacOS 9 has a new feature that makes it easier to write in this fashion. The new feature is "using terms from". Unfortunately, it will only work in OS 9.

      These techniques are discussed fully on the AppleScript Sourcebook's Tips section. Look for Launching by Creator and Telling by Variable.

    2. Using a property

      While this won't prevent the dialog, it will force it to only appear the first time the app is run on a machine. If you put a property in your Project Script that lists all the applications your app uses:

      property kAppList:{application "Netscape Communicator™", application "BBEdit"}
      

      FaceSpan will be forced to ask immediately on startup where the apps are (if they can't be found) and will store them in the property automatically.

      The downside to this is that your app will more than likely ask where the apps are the first time it's run. On occasion, you may get an "unable to save changes" error when your app quits (which could happen any time you have properties or globals in the Project Script).

    3. Using Aliaii (Aliases?)

      If you create an alias in the same directory as your FaceSpan app, and the alias is named the same as an application referenced from your FS app, and the alias actually points to an application, FaceSpan will not give you the "Where is application xxx?" dialog. This brings up an interesting theory for a technique that should always avoid the "Where is application xxx?" dialog.

      FaceSpan 3 doesn't load any scripts until they're needed. It won't pop up the "Where is application xxx?" until it finds a script with an app reference it can't resolve. If you avoid letting any scripts load that tell to another app before you ensure the proper aliases have been created, then your app will never bring up the "Where is application xxx?" dialog.

  3. My idle handler is never called. Why is that?

    The idle event is actually a window event, which gets passed to the Project Script when your windows don't handle it. You probably don't have a window open, or your open windows are Modal/Error Dialogs, or all your open windows are not continuing idle.

    If you want idle events to always reach your Project Script, open a non-modal dialog when you initialize your application. One good window to use for this check is your Splash Screen. Here's an example script:

    on run
      InitApp()
    end run
    
    on InitApp()
     -- if the window isn't open...
     if not (exists window "Splash Screen") then
      open window "Splash Screen" with properties {position:centered in main}
      -- do app init stuff here
      set visible of window "Splash Screen" to false
      set position of window "Splash Screen" to offscreen
      -- overkill
     end if
    end InitApp
    
  4. What's safe to use on a Windoid I want to float on other applications?

    Floating Windoids (palettes) on other applications is one of the most interesting features of FaceSpan. Unfortunately, it's also the most hit and miss.

    Things that don't work at all:

    Things that work unreliably:

    Other controls, like buttons, popups, and gauges, will work just fine.

  5. Is it safe to create and/or make extensive changes to storage items at runtime?

    According to FaceSpan technical support, no. While the commands are there and will work, you might corrupt your application if you create and/or make extensive changes to storage items when you aren't in the development environment. There are a few alternatives, including the read/write and load script/store script commands installed with the system, and the PreferenceIO scripting addition that lets you read and write another file's resource fork.

  6. How do I make a button that closes its window and then does something?

    This sounds like a scripting question but is often more of a design decision. A window told to close by a script executing in that window will not close until after the script that is executing finishes. The close handler for the window is executed when the close window line appears. (This is similar to how quit works.)

    Often, this situation comes about when the OK button of a settings dialog triggers the work of the application. A better way to do that is to return the settings to the function that opened the dialog, so the window can close and the calling function can do the work. You can do that by setting global variables to your settings or by returning them to the calling function via returning properties:

     -- in the calling script:
     set theSettings to (open window "Get Settings" returning properties {closing item:0, pFileName:"", pDestName:"", pReplacing:false})
    
     if name of closing item of theSettings = "pshOK" then
       tell app "The App In Question"
         open file (pFileName of theSettings)
         save document 1 in file (pDestName of theSettings) replacing (pReplacing of theSettings)
       end tell
     end if
     
    
     -- in the window's script:
     property pFileName:""
     property pDestName:""
     property pReplacing:false
     
     on close theObj per theClosingItem
      set pFileName to contents of textbox "txtFileName"
      set pDestName to contents of textbox "txtDestName"
      set pReplacing to hilite of checkbox "chkReplaceFile"
    
      continue close theObj per theClosingItem
     end close
    

    If that won't handle your situation, you could also try putting the list of files in a property or global of your application, and having an idle handler grab them for you and open them. Another solution is to hide the window, proceed with the rest of the script, then close the window at the end. As long as this window doesn't get opened again, it won't look any different to the user or to your scripts.

3. Scripting Questions

  1. How do I "type as user" the tab, enter, or return keys?

    FaceSpan's "type as user" ability doesn't extend to those keys, unfortunately. However, many applications recognize the ASCII equivalents of tab and return. Try:

    type as user "i" with control down  -- tab
    type as user "m" with control down  -- return
    

    If this doesn't work, then you'll have to use something like Sändi's Additions that gives you a typing command that supports special characters. You can get Sändi's Additions from the ScriptWeb or Info-Mac archives.

  2. My application won't quit, no matter how I tell it to. How can I fix it?

    If your app isn't quitting when you pick Quit from the menu or tell it to quit from AppleScript, then you are probably not continuing a message on somewhere. If you have any close or quit handlers anywhere in your application, make sure they continue the message:

    on close theObj per theClosingItem
      -- blah blah blah
      continue close theObj per theClosingItem
    end close
    
  3. How can I make sure the application I want to tell to is there?

    Here's a routine you can use to determine if an application is running. It should work on all systems.

    on CheckForApp(appCode)
      set itExists to false
      set itsRunning to false
      set itsName to ""
    	
      try
        tell application "Finder"
          set itExists to exists application file id appCode
          set itsRunning to exists (first process whose creator type is appCode)
          if itExists then set itsName to name of application file id appCode
        end tell
      on error
      end try
    	
      return {itExists, itsRunning, itsName}
    end CheckForApp
    

    Download this routine.

  4. How can I get the time of a date? ("time of (current date)" returns an error)

    This is a bug in FaceSpan. A workaround is to tell another app to get it for you:

    tell application "Finder" to set theTime to time of current date
    

4. Development Environment Questions

  1. Why can I open a Run-Only Application in the Development Environment?

    This was allowed for those who are Localizing a FaceSpan Application. If the text on, say, a push button is suddenly too long to fit in the space that was originally allowed, the Localizer can resize the button and everything's fine. Your Scripts are still protected (try opening one from a Run-Only App).

    Another use for it would be to reuse windows and resources from a previous application when you've lost the source.

  2. I imported some icons, deleted them, then imported more and my old icons are back. What happened?

    FaceSpan 3.0.x has a bug where it doesn't delete some resources completely when you delete them from within the Development Environment. If you open your project in ResEdit (make a backup first) and look at the various icon resources, you will find duplicates. You can delete the extras from in ResEdit or just use ResEdit to add them in the first place and avoid the problem.

5. Other FaceSpan Questions

  1. How do I give my application a unique creator code?

    This is a multiple-step process that requires a program that lets you edit the resources in your app. Apple's ResEdit is one such app.

    Your application should now have its own icon and files linked to its Creator Code will appear with the document icons you chose (if any).

  2. How do I make a windoid float on all apps?

    Here's how to set it to float on all apps using ResEdit:

    Any windoids in your app should now float on all applications.

6. Resources

  1. Where can I go to get FaceSpan information?

    Websites and FTP

    Mailing Lists

    DTI runs a FaceSpan mailing list. You can sign up for it by going to their webpage, sending an email to requests@facespan.com with "subscribe facespan-digest" in the body of the message. You can subscribe in digest mode by sending an email to requests@facespan.com with "subscribe digest facespan-digest" in the body.

    You can also use these E-Mail links to subscribe in Single Message Mode or Digest Mode.

  2. Where can I go to get AppleScript information?

    Websites and FTP

    Mailing Lists

    These two are the most popular general ones:

    Apple's AppleScript Users list

    Apple runs two lists related to AppleScripting; one for users and one for developers. To sign up for the AppleScript Users list, either head to lists.apple.com.

    MACSCRPT

    MacScripting is a mailing list run from Dartmouth College. While most questions are AppleScript-related, it gets questions about FaceSpan, Frontier, MacPerl, and others. To sign up for MACSCRPT, send an email to LISTSERV@dartmouth.edu with a subject of subscribe and a body of subscribe macscrpt Your Name.

Appendix A: About this FAQ

  1. What is a FAQ?

    FAQ is short for Frequently Asked Questions. Many USENET newsgroups, mailing lists, and other special interest groups compile lists of the most Frequently Asked Questions so that new members of their group don't repeat the same requests over and over. They're also useful for experienced people looking for more information.

  2. Where can I get the FAQ?

    This FAQ is posted periodically to the FaceSpan-Digest mailing list, and is also located on the web at http://www.esglabs.com/.

  3. What are these funny symbols in the text?

    AppleScript uses a number of special symbols that don't translate to email or web text very well. These have been replaced with text forms that may not compile. Here's a handy translation table (with key equivalents on my US Apple Extended Keyboard II):

    -- Script-related:
    
    «event Foo1Bar2»    -- Chevrons, Opt-Backslash (\) and
                           Opt-Shift-Backslash
    <<event Foo1Bar2>>  -- Often written as << and >> (does not compile)
    
    1 ≠ 2               -- Not Equal, Opt-Equals (=)
    1 /= 2              -- Often written as /= (which compiles)
    
    1 ≤ 2               -- Less Than or Equal, Opt-Comma (,)
    1 <= 2              -- often written as <= (which compiles)                 
    
    1 ≥ 2               -- greater than or equal, opt-period (.)
    1 >= 2              -- Often written as >= (which compiles)
    
    1 ÷ 2               -- Division, Opt-Slash (/)
    1 / 2               -- Almost always written as / (which compiles)
    
    then ¬              -- Line Continuation, Opt-Return
                        -- (No good substitute?)
    
    -- Not as important, but these are sometimes seen in names:
    
    "BlahEdit™"         -- Trademark, Opt-2
    "BlahEdit(TM)"      -- Sometimes dropped; otherwise TM or (TM)
    
    "FooBar©"           -- Copyright, Opt-G
    "FooBar(C)"         -- Sometimes dropped; otherwise (C)
    
    "OurApp®"           -- Registered Trademark, Opt-R
    "OurApp(R)"         -- Sometimes dropped; otherwise (R)
    
    "Another ƒ"         -- Short for Folder, Opt-F
    "Another F"         -- Replace with "F" or "Folder"?
    

    All of the script snippets in this FAQ are available for download as a package from the FAQ's home at the FaceSpan Snippets page (see Appendix A for more information).

  4. Legal Notes

    FaceSpan is a trademark of Digital Technology International. Apple Macintosh and AppleScript are trademarks of Apple Computer, Incorporated. QuarkXPress is a trademark of Quark, Inc. Multi-Ad Creator2 is a trademark of Multi-Ad Services, Inc. Netscape Navigator and Communicator are trademarks of Netscape Communications Corporation. All other copyrights and trademarks are acknowledged that are not specifically mentioned above.

    This FAQ is Copyright (C) 1999, 2000 Michael Jay Miller. Permission is granted for reproduction, distribution, transmission, or storage for non-commercial purposes only, on the condition that the contents are not changed in any way. Permission for any other use or distribution of this file must be obtained from the author.

Back to Index