(*

    File:       AddOnScripts.applescript

    Description:

    These are the AppleScripts called by the main program.  This file is compiled

    at build time into the file AddOnScripts.scpt.  We have added two new build

    phases to accomplish this.

    Author:     JM

    Copyright:  Copyright (c) 2003 Apple Computer, Inc. All rights reserved.

    Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.

                ("Apple") in consideration of your agreement to the following terms, and your

                use, installation, modification or redistribution of this Apple software

                constitutes acceptance of these terms.  If you do not agree with these terms,

                please do not use, install, modify or redistribute this Apple software.

                In consideration of your agreement to abide by the following terms, and subject

                to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs

                copyrights in this original Apple software (the "Apple Software"), to use,

                reproduce, modify and redistribute the Apple Software, with or without

                modifications, in source and/or binary forms; provided that if you redistribute

                the Apple Software in its entirety and without modifications, you must retain

                this notice and the following text and disclaimers in all such redistributions of

                the Apple Software.  Neither the name, trademarks, service marks or logos of

                Apple Computer, Inc. may be used to endorse or promote products derived from the

                Apple Software without specific prior written permission from Apple.  Except as

                expressly stated in this notice, no other rights or licenses, express or implied,

                are granted by Apple herein, including but not limited to any patent rights that

                may be infringed by your derivative works or by other works in which the Apple

                Software may be incorporated.

                The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO

                WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED

                WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR

                PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

                COMBINATION WITH YOUR PRODUCTS.

                IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR

                CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

                GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

                ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

                OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT

                (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN

                ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Change History (most recent first):

        Fri, Aug 29, 2000 -- created

*)

(* AddOnScripts.applescript

These are the AppleScripts called by the main program.  This file is compiled

at build time into the file AddOnScripts.scpt.  We have added two new build

phases to accomplish this.

1. The first build phase executes this command:

    osacompile -d -o AddOnScripts.scpt AddOnScripts.applescript

This command compiles this source file 'AddOnScripts.applescript' saving the result

in the data fork of the file 'AddOnScripts.scpt'.

2. The second build phase simply copies both of the files 'AddOnScripts.scpt'

and 'AddOnScripts.applescript' into the final application's resources directory.

IMPORTANT:  I have noticed that you need to 'clean' the build

before it will copy the compiled versions of these files over

to the resources directory.  

Some interesting points to make here are:

(a) if at any time you want to reconfigure your application so that the scripts

do different things you can do so by editing this file and recompiling it to the

.scpt file using this command:

    osacompile -d -o AddOnScripts.scpt AddOnScripts.applescript

(b) everything here is datafork based and does not require any resource forks.  As

such,  it's easily transportable to other file systems.

(c) Recompiling this script file does not require recompilation of your main

program, but it can significantly enhance the configurability of your application.

As well, it can defer some design and interoperability decisions until later in

the development cycle.  Want to swap in a different app for some special task?

Just rewrite the script, your main program doesn't have to know about it...

(d) recompiling this script is even something that daring advanced users

with special requirements may want to do.

(c) because the main program only loads the precompiled

'AddOnScripts.scpt' your application does not bear any of the runtime

compilation costs that are involved.  From the application's point of

view, it's just 'Load and go...'.

*)

(* gMyVariable 

global variable we define and set in our startup and shutdown

routines.  No particular value really, other than to illustrate

that a script can contain persistent state that lasts through

program execution. *)

property gMyVariable : "nods..."

(* appstartup 

our app calls this script at application startup time.  Here, we could

do some special startup tasks such as initalizing script globals,

opening connections to data bases, opening files, etc...  here,

we display a dialog and initialize one of our global variables. *)

on appstartup()

    -- show the startup state

    display dialog "here's our startup script, global = " & gMyVariable

    -- change the variable

    set gMyVariable to "spits!"

end appstartup

(* appshutdown 

our app calls this script at application shutdown time.  Here, we could

do some special shutdown tasks such as closing data base connections,

closing files, etc...  here, we display a dialog showing the value we set

the global to in our startup script and then we change it

to something else before quitting. *)

on appshutdown()

    -- show the state we set it to at startup

    display dialog "here's our shutdown script, global = " & gMyVariable

    -- change it for kicks...

    set gMyVariable to "barrel!"

end appshutdown

(* displaystring 

display a messaage string in a dialog. *)

on displaystring(message)

    -- show our message

    display dialog message

end displaystring

(* selectfile 

displays a file selection dialog box allowing the user to select

a file of type text. the prompt string appears to be ignored by

the 'choose file' command, but I put it there anyway just to

show how to pass a string parameter from the application to

the script. 

NOTE:  it would be just as simple to ask the finder

for the current selection and then use that! *)

on selectfile(promptstring)

    -- select a file, save it in variable 'theFile'

    set theFile to choose file of type {"TEXT"} with prompt promptstring

    -- return the alias to the caller

    return theFile

end selectfile

(* filetostring 

we use this routine to convert a file alias into a string for display

in a window. *)

on filetostring(theFile)

    -- simply coerce the file alias to a string

    return (theFile as string)

end filetostring

(* displayfile 

We use this routine to display a file.  right now, it asks the finder

to select and display the item in a window. By adding the 

'ignoring application responses', we are basically saying that the

script will not wait for the finder to finish before returning to

the main application.  i.e. we get control of the pc back possibly

before the finder has finished displaying the file.  *)

on displayfile(theFile)

    -- don't wait for the finder to send back any results

    ignoring application responses

        -- Finder 'FULL ON!!!'

        tell application "Finder"

            -- switch to the Finder process

            activate

            -- select the file

            select theFile

        end tell

    end ignoring

end displayfile

(* getfilecomment 

retrieves the 'Get Info...' Finder comment associated

with the item referenced by the alias 'theFile'. *)

on getfilecomment(theFile)

    -- with the Finder...

    tell application "Finder"

        -- copy the Finder comment to the local

        -- variable theComment

        set thecomment to comment of theFile

    end tell

    -- return the comment

    return thecomment

end getfilecomment

(* setfilecomment 

changes the 'Get Info...' Finder comment associated

with the item referenced by the alias 'theFile' to the

new comment text. It also returns the new comment text,

but we ignore that in our application (and we did that

on purpose to illustrate that it is okay to do that and

it won't cause a memory leak!). *)

on setfilecomment(theFile, thecomment)

    -- with the Finder...

    tell application "Finder"

        -- set the file's comment property comment

        set (comment of theFile) to thecomment

    end tell

    -- return the new comment to the caller

    -- which, of course, we promptly ignore

    -- in our application...

    return thecomment

end setfilecomment

(* getfolderItems 

illustrates how a script can return a complex set of many

values to the calling application.  Here, we prompt the

user to select a folder.  If they do so, then we build a

list of all of the items in the folder.  For each item

that we include in the list, we save a list containing

two items: the name of the item, and an alias referring to it.

So basically, we return a list of two item lists like so:

{

 { name of item 1, alias to item 1 },

 { name of item 2, alias to item 2 },

 ...

 { name of item n, alias to item n }

}

In our application, we use the names to display the names

of the items in the list, and we use the alias records to

retrieve the get info comments.  *)

on getfolderItems(promptstring)

    -- initialize our list result to empty

    set theList to {}

    -- ask the user to pick a folder

    set theFolder to choose folder with prompt promptstring

    -- using the Finder...

    tell application "Finder"

        -- enumerate all of the items in the folder

        set folderItems to contents of folder theFolder

        -- for each of the items returned...

        repeat with nthItem in folderItems

            -- create a new list element (a two element list

            -- composed of the item name and an alias referring

            -- to the item

            set nthListElement to {name of nthItem, (nthItem as alias)}

            -- copy the new element to the end of the list

            copy nthListElement to the end of theList

        end repeat

    end tell

    -- return the new list

    return theList

end getfolderItems

(* getfinderselection 

returns exactly the same results as the getfolderItems

routine, except it returns a list of all of the items

that are selected in the Finder rather than prompting

the user to select a folder.  *)

on getfinderselection()

    -- initialize our list result to empty

    set theList to {}

    -- using the Finder...

    tell application "Finder"

        -- enumerate all of the items in the current selection

        set folderItems to the selection

        -- for each of the items returned...

        repeat with nthItem in folderItems

            -- create a new list element (a two element list

            -- composed of the item name and an alias referring

            -- to the item

            set nthListElement to {name of nthItem, (nthItem as alias)}

            -- copy the new element to the end of the list

            copy nthListElement to the end of theList

        end repeat

    end tell

    -- if there's no result, explain why so everyone's

    -- not confused by the lack of meaningful feedback

    -- they will receive when nothing is selected in

    -- the Finder.

    if length of theList is 0 then

        display dialog "There are no items in the Finder selection.  Select some items in the Finder and try again."

    end if

    -- return the new list

    return theList

end getfinderselection