# 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:

   - Drag and drop between listboxes.

   Things that work unreliably:

   - Editable Text

     A palette with an editable textbox/table may or may not work depending on how the app currently being floated on works. Some applications it won't work at all, some applications are spotty. Unfortunately, there's nothing much you can do about this. Applications known to not work include Netscape Communicator and Multi-Ad Creator2.

   - Clicking on the Windoid

     Occasionally clicks on a windoid will not reach the windoid and will fall through to whatever application is behind the windoid. While you can't always avoid this, here's a few things to try.

     - Install TSM Fix 1.0.3, which will show the bug less.
     - Move the Windoid so it overlaps a window of the application being floated upon.
     - Float the Windoid on all applications, or float it on the Finder and as many other applications as possible, so your Windoid is less likely to disappear when you click.

   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.

   - First, register your creator code with Apple. You can do that by going to http://developer.apple.com/dev/cftype/ and filling out the form there. It takes a day or two to get confirmation.
   - If you haven't already, add the Icon you want your application to have to your application (via the Development Environment's Import Artwork or ResEdit).
   - Save your project as an application. (At this point, you may want to make a copy in case something gets messed up.)
   - Open the Application in ResEdit.
   - Double-click on "BNDL" to open the "BNDL" resource.
   - Double-click on the line whose ID is 128.
   - Pull down the BNDL menu and pick Extended View.
   - Change the Signature to match your Creator Code.
   - For each icon type you want to change, click on the res ID under "Finder Icons" and change it to the ID number of the icon you want to use. (it may help to open one of the icon resources as well, so you can see the IDs of the various available icons.)
   - Close all the resources you have open. (Don't close the file, however.)
   - Open the "vers" resource. Your "vers" resource list should have two entries. The vers 1 resource's text is what appears next to Version in the Finder Get Info window. The vers 2 resource's text appears under the file name in the Get Info window.
   - Edit the two "vers" resources, changing the version number and text as appropriate.
   - Close all the resources you have open. (Again, don't close the file.)
   - Save your changes.
   - Pull down the File Menu and pick "Get Info for (your app name)".
   - Change the Creator Code to the code you want.
   - Uncheck "INITed" in the Flags area below.
   - Close the Info Window and Save.
   - Quit ResEdit.

   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:

   - Open the Application in ResEdit.
   - Double-click on "Flot" to open the "Flot" resource.
   - Double-click on the line whose ID is 128 (it should be the only one).
   - Select all the text on the right-hand side of the hex view, then type ****.
   - Close everything, saving your changes when asked.

   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

   - FaceSpan - the home site for FaceSpan.
   - Steve's AppleScript Site - Steve has a number of AppleScripts and a couple FaceSpan projects, including a system for localized menus.
   - Matt Ridley.com - Matt has a couple FaceSpan tools to help you make your FaceSpan applications.
   - ESG Labs - the home of this FAQ.

   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

   - AppleScript - Apple's official AppleScript site.
   - AppleScript Sourcebook - The premier AppleScript information site.
   - ScriptWeb - A collection of many resources for scripting.
   - AppleScript This Week - A news site and gathering of AppleScript information.
   - AppleScript BBS - A news site and gathering of AppleScript information.
   - Info-Mac Archives - The Info-Mac Archive is a collection of Macintosh files. Its mirrors can be found in many places. This link takes you to Mirrors.apple.com.

   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