Using AppleScript

AppleScript is a simple but powerful scripting language built into Mac OS X. With AppleScript, you can automate repetitive tasks and transfer data from one application to another. Life Balance includes a complete AppleScript dictionary that allows you to open and close documents, create and modify tasks in the outline, schedule tasks in the calendar, update the to-do list, check off completed tasks, and much more. Almost anything you can do manually in Life Balance can also be done using AppleScript.

Before sitting down to write your own AppleScript, take a look at Sharing Data with Other Applications to see if there is some simpler way to solve your problem. Since Automator is generally easier to use than AppleScript, you might also consider writing most of your script as an Automator workflow, and then using an AppleScript action just for the parts that Automator can't handle.

Learning AppleScript

Before you start scripting Life Balance, you'll need to know a little about AppleScript and the various scripting tools that come with Mac OS X. This manual only provides very basic information about AppleScript. More information is available in AppleScript Help, which you can reach by selecting “Mac Help” from the Finder's Help menu, and then selecting “AppleScript Help” from the Library menu in Help Viewer. This help contains links to important reference manuals including the AppleScript Language Guide and the Script Editor web site. If you search the internet for “AppleScript tutorial” you will find many other introductions to Macintosh scripting.

You write AppleScripts using the Script Editor application, which is located in the /Applications/AppleScript folder on Mac OS X. When you launch the Script Editor, it will open an empty window where you can edit your script, compile and run it. You can also save scripts that you have written, and open existing scripts written by yourself or others.

While AppleScript itself provides basic scripting tools, most of the objects and commands you will use in your scripts are provided by other applications like Life Balance. Most of the applications included with Mac OS X are also scriptable, including the Finder, Mail, and Safari. One of the most useful features of AppleScript is its ability to automate these applications and transfer data from one application to another.

Before you can script an application, you need to know what classes (nouns) and commands (verbs) it responds to. You do this by opening the application's AppleScript dictionary, either using the “Open Dictionary...” command in the Script Editor's File menu, or by dragging the application to the Script Editor's icon in the dock. There is also a “Library” palette where you can store AppleScript dictionaries for quick access.

For convenience, the AppleScript dictionary for Life Balance is included later in this chapter.

Running AppleScripts

While you can always open scripts in the Script Editor and run them from there, Mac OS X provides several other convenient ways to run scripts.

The Script Menu

Apple provides a handy system menu for running scripts. This menu is not enabled by default, but you can turn it on using the AppleScript Utility application in the /Applications/AppleScript folder.

When you turn on the Script Menu, a new icon will appear on the right side of the menu bar. This menu will automatically display scripts that you have saved in special folders on your Macintosh, which you can locate using the "Open Scripts Folder" command at the top of the Script Menu. You can read more about the Script Menu in AppleScript Help.

Look for this icon in the menu bar near the clock.

When you're writing a script for the Script Menu, it is often helpful to make use of the current selection so that the script will act on the selected object. For example, here is a script that copies the URLs of the selected items in the Finder to the notes field of the selected task in Life Balance:

tell application "Finder"
  set theSelection to selection
  set theURLs to ""
  repeat with theItem in theSelection
    set theURLs to theURLs & "\n" & (URL of theItem)
  end repeat
end tell
tell application "Life Balance"
  tell (selected task of document 1)
    set notes to notes & theURLs
  end tell
end tell

Once you've copied a URL to the Life Balance notes, a command-click on the URL will open the corresponding file. The same trick works with web sites:

tell application "Safari"
  set theURL to URL of document 1
end tell
tell application "Life Balance"
  tell (selected task of document 1)
    set notes to notes & "\n" & theURL
  end tell
end tell

Tip: Holding down the option key when you select a script from the Script Menu will open it in the Script Editor rather than running it. Holding down the shift key will reveal the script in the Finder.

You can also store Automator workflows in the Script Menu folders and run them just like scripts.

Mail Rule Scripts

Apple's Mail program lets you create rules for organizing your incoming email, and you can use these rules to run AppleScripts. Scripts that you intend to use for Mail rules need to be written a little differently from other scripts so that the script can tell which email messages matched the rule. Here's a sample script that creates a new task in Life Balance for each email message selected by the rule:

using terms from application "Mail"
  on perform mail action with messages theMessages for rule theRule
    tell application "Mail"
      repeat with eachMessage in theMessages
        set theSubject to subject of eachMessage
        set theContent to content of eachMessage
        tell application "Life Balance"
          make new task at end of task "Earn a living" of document 1 with properties {name:theSubject, notes:theContent}
        end tell
      end repeat
    end tell
  end perform mail action with messages
end using terms from

Once you have created a Mail rule script in the Script Editor and saved it, you can create a rule using the Rules section of the Mail Preferences window, and attach the script to the rule.

You can learn more about Mail rules and writing scripts for them by searching for “rules” in Mail Help.

Running an AppleScript when a Task is Completed

Life Balance includes a hidden feature that allows you to run an AppleScript each time you check off a task. To use this feature, create a script that looks like this:

on CompletedTask(theTask)
  tell application "Life Balance"
    display dialog (name of theTask) & " is done!"
  end tell
end CompletedTask

Of course, instead of displaying a dialog, you may want your script to play a sound or send an email — whatever you can think of that you can do with AppleScript.

Save this script in ~/Library/Application Support/Life Balance/Actions.scpt, and it will be run automatically each time you check off a task.

Note: To avoid endless looping, the script is not run if you check off a task using AppleScript, only if you check it off manually.

Applescript dictionary for Life Balance

exists v : Verify if an object exists.

exists specifier : the object in question: → boolean : true if it exists, false if not

move v : Move object(s) to a new location.

When moving a task relative to another task, the "before" and "after" keywords will make the task a sibling (same outline level) as the other task. The "beginning of" and "end of" keywords will make the task a subtask of the other task.

move specifier : the object(s) to move: to location specifier : The new location for the object(s).; → object : to the object(s) after they have been moved

open v : Open an object.

open object : The file(s) to be opened.

quit v : Quit an application.

quit: [saving yes/no/ask] : Specifies whether changes should be saved before quitting.

count v : Return the number of elements of a particular class within an object.

count specifier : the object whose elements are to be counted: [each type] : The class of objects to be counted.; → integer : the number of elements

close v : Close an object.

close specifier : the object to close: [saving yes/no/ask] : Specifies whether changes should be saved before closing.; [saving in file] : The file in which to save the object.

make v : Make a new object.

When making a new task relative to another task, the "before" and "after" keywords will make the new task a sibling (same outline level) as the other task. The "beginning of" and "end of" keywords will make the new task a subtask of the other task.

make: new type : The class of the new object.; [at location specifier] : The location at which to insert the object.; [with data any] : The initial contents of the object.; [with properties record] : The initial values for properties of the object.; → specifier : to the new object

save v : Save an object.

save specifier : the object to save, usually a document or window: [in file] : The file in which to save the document.

update v : Update the todo list.

update todo list : The todo list to be updated.

complete v : Mark a task as completed, award credit, and reschedule it if it repeats.

complete task : The task to be completed.

application n : An application's top level scripting object.: Elements

contains documents, windows.

Properties

name (text, r/o) : The name of the application.

frontmost (boolean) : Is this the frontmost (active) application?

version (text, r/o) : The version of the application.

Responds to

open, quit.

document n : A document.: Elements

contains subtasks, tasks, places, events; contained by applications.

Properties

modified (boolean, r/o) : Has the document been modified since the last save?

todo list (todo list, r/o)

selected task (task)

name (text, r/o) : The document's name.

Responds to

close, count, save.

window n : A window.: Elements

contained by applications.

Properties

name (text, r/o) : The full title of the window.

id (number, r/o) : The unique identifier of the window.

bounds (rectangle) : The bounding rectangle of the window.

document (document, r/o) : The document whose contents are being displayed in the window.

closeable (boolean, r/o) : Whether the window has a close box.

titled (boolean, r/o) : Whether the window has a title bar.

index (number) : The index of the window in the back-to-front window ordering.

floating (boolean, r/o) : Whether the window floats.

miniaturizable (boolean, r/o) : Whether the window can be miniaturized (minimized).

miniaturized (boolean) : Whether the window is currently miniaturized (minimized).

modal (boolean, r/o) : Whether the window is the application's current modal window.

resizable (boolean, r/o) : Whether the window can be resized.

visible (boolean) : Whether the window is currently visible.

zoomable (boolean, r/o) : Whether the window can be zoomed.

zoomed (boolean) : Whether the window is currently zoomed.

Responds to

close, print, save.

todo list n : The current list of tasks sorted by priority and filtered by place.: Elements

contains tasks.

Properties

include closed places (boolean)

current place (place)

update automatically (boolean)

Responds to

update.

task n : A task, project or goal from the Life Balance outline.: Elements

contains subtasks, tasks, events; contained by documents, todo lists, tasks.

Properties

project (task, r/o) : The parent project of this task.

name (text)

notes (text) : The notes for this task.

id (text, r/o) : The unique identifier of the task.

importance (real) : The relative importance of this task to the completion of its parent task, from 0.0 to 1.0

lead time (integer) : The amount of time before the scheduled time that the task should have full priority, in minutes.

level (integer, r/o) : The indentation level of the task in the outline. Toplevel tasks have level 1.

effort (real) : The amount of credit awarded when this task is completed, from 0.0 to 2.0

place (place) : The place where you need to be to complete the task.

completed (boolean, r/o) : Is the task currently checked off?

completed time (date, r/o) : The last time that the task was completed, regardless of whether the task is currently checked off or not. If the task has never been completed, then 'missing value' is returned.

Note that this property cannot be set directly. However, you can use the "complete" command to mark a task as completed and assign credit for completing the task.

schedule type (once/by due date/routinely/by calendar)

scheduled time (date) : The next time that a task is scheduled to occur. Tasks that happen 'once' are scheduled to happen immediately. If there is no scheduled time for the task, then 'missing value' is returned.

Note that you may only change the scheduled time of a task if its schedule type is 'by due date'. For all other schedule types, this property is read-only.

complete subtasks in order (boolean) : Whether the immediate subtasks of this task must be completed in order. If true, only the first incomplete subtask will be placed in the to-do list. If false, all incomplete subtasks will be place in the to-do list.

desired slice size (real) : The relative size of this toplevel task in the 'Desired' pie chart. This property is ignored for non-toplevel tasks.

Because the Palm version of Life Balance has a limited arithmetic range, we recommend keeping the total desired slice sizes of all toplevel tasks equal to the number of toplevel tasks. In other words, the average desired slice size should be 1.0, using numbers greater than 1.0 for larger slices and numbers smaller than 1.0 for smaller slices. This is the system the Life Balance uses when the desired pie chart is adjusted manually.

actual slice size (real, r/o) : The total amount of credit accumulated for this task and its subtasks. For toplevel tasks, this determines the relative size of the corresponding slice in the Actual pie chart.

Note that since the credit for completed tasks decays over time, this value may change even if the document has not been modified.

Responds to

count, move.

subtask n : A subtask of a document or task that is one level down in the outline.: Elements

contained by documents, tasks.

place n : a Life Balance place: Elements

contained by documents.

Properties

name (text) : The name of the place.

notes (text) : The notes of the place.

id (text, r/o) : The unique identifier of the place.

included places (list of place, r/o) : A list of other places that are also shown in the todo list when this place is selected.

Responds to

count.

event n : an event scheduled in the Life Balance calendar: Elements

contained by documents, tasks.

Properties

task (task, r/o) : The task associated with this event.

id (text, r/o) : The unique identifier of the event.

start date (date) : The start date of the event.

recurrence (text) : The iCalendar (RFC 2445) string describing the event recurrence, if defined

allday event (boolean) : True if the event is an all-day event

duration (integer) : The duration of the event, in minutes.

excluded dates (list of date) : A list of dates that are excluded from the recurrence.

Responds to

count, make.