AppleScript Explained in Plain English

An AppleScript Editor Dictionary Window
An AppleScript Editor Dictionary Window

Getting to know AppleScript Commands and Parameters

Ever gone to look at an AppleScript Dictionary in AppleScript Editor and tried to implement the various commands only to find that with the limited explanation of parameters etc, no matter how many variations you try, you still get error dialogs, most of which aren't very helpful?

This site will show you dictionary entries for some of the most frequently used commands with some snippets of example code to get you started building the scripts you need.

Tips on Reading and Understanding AppleScript Dictionaries

Before you Get Started, I Highly Recommend that you Take a Quick Look at these Comments on Dictionaries

Source

An entry taken from the AppleWorks 6 Dictionary:

make v : Make a new element

make new type : the class of the new element. at location specifier : the location at which to insert the element [with data any] : the initial data for the element [with properties record] : the initial values for the properties of the element --> specifier : to the new object(s)

Some things to note about dictionary entries

1) The first line, make v : Make a new element, is the basic definition of the term

2) The second item in the first line in italics (v here) describes the term as an English part of speech, here, a verb. This is significant, because AppleScript is written basically like sentences in English.

3) Text in bold is to be written literally

4) All plain text is not to be taken literally and is a description of the element or term in bold.

5) Text within straight brackets are optional parameters that may not apply for what you want to do.

6) Blue, underlined text is a link to a further definition of the term or attribute. In the 'make' example above (omitting optional stuff), you could say:

make new document at desktop

Finder's Standard Suite; Basic AppleScript that most Applications should understand

First the definition of a term as it appears in the Finder Dictionary, then an example or two of its use.

This is rather lengthy. The items covered here are:

Open, Print, Quit, Activate, Close, Count, Data Size, Delete, Duplicate, Exists, Make, Move, Select

Note that parameters enclosed in square brackets '[]' are optional (this is a common convention).

open v : Open the specified object(s)

open specifier : list of objects to open
[using specifier] : the application file to open the object with
[with properties record] : the initial values for the properties, to be included with the open command sent to the application that opens the direct object

Examples:

tell application "Finder" to open home

tell application "Finder"
open item "Document 1.cwk"
end tell

print v : Print the specified object(s)

print specifier : list of objects to print
[with properties record] : optional properties to be included with the print command sent to the application that prints the direct object

Example:

tell application "TextEdit"
	print the front document with properties ¬
		{copies:2, collating:true, starting page:1, ending page:1, pages across:1, pages down:1, error handling:standard} ¬
			without print dialog
end tell

quit v : Quit an application

Although the definition comes with the annotation 'Quit the Finder', it can be directed to other applications as well:

tell application "FileMaker Pro" to quit

activate v : Activate the specified window (or the Finder)

activate [specifier] : the window to activate (if not specified, activates the Finder)

Examples:

tell application "Finder" to activate
activate application "Finder"

tell application "Microsoft Word"
	activate
	set createDoc to make new document
	set name of font object of text object of createDoc to "Trebuchet"
	--etc
end tell

close v : Close an object

close specifier : the object to close

Example:

tell application "Finder"
set frontWind to (get name of front window)
close window frontWind
end tell

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 the elements to be counted
--> integer : the number of elements

Examples:

repeat with x from 1 to (count records)
...
end repeat

count text items

data size v : Return the size in bytes of an object

data size specifier : the object whose data size is to be returned
[as type] : the data type for which the size is calculated
-->integer : the size of the object in bytes

Example:

tell application "Finder" to get data size of front window

delete v : Move an item from its container to the trash

delete specifier : the item to delete
--> specifier : to the item that was just deleted

Example:

select (every file of front Finder window)
delete selection

duplicate v : Duplicate one or more object(s)

duplicate specifier : the object(s) to duplicate [to location specifier] : the new location for the object(s) [replacing boolean] : Specifies whether or not to replace items in the destination that have the same name as items being duplicated [routing suppressed boolean] : Specifies whether or not to autoroute items (default is false). Only applies when copying to the system folder.

--> specifier : to the duplicated object(s)

Example:

tell application "Finder"
activate
duplicate item 1 of front Finder window to desktop
end tell

exists v : Verify if an object exists

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

Example:

if not (folder "Database Backups" exists) then...

make v : Make a new element

make new type : the class of the new element
at location specifier : the location at which to insert the element
[to specifier] : when creating an alias file, the original item to create an alias to or when creating a file viewer window, the target of the window
[with properties record] : the initial values for the properties of the element
--> specifier : to the new object(s)

Example:

tell application "Finder" to make new folder at desktop with properties {name:"New Folder", label index:1}

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

move specifier : the object(s) to move
to location specifier : the new location for the object(s)
[replacing boolean] : Specifies whether or not to replace items in the destination that have the same name as items being moved
[positioned at list] : Gives a list (in local window coordinates) of positions for the destination items
[routing suppressed boolean] : Specifies whether or not to autoroute items (default is false). Only applies when moving to the system folder.
--> specifier : to the object(s) after they have been moved

Example:

tell application "Finder"
	set targetFolder to the target of front Finder window
	set targetFiles to (every document file of targetFolder)
	move targetFiles to desktop
end tell

select v : Select the specified object(s)

select specifier : the object to select

Examples:

select text 1 thru 36 of paragraph 10

tell application "Finder"
set desktopPath to (path to desktop)
select folder "untitled folder" of desktopPath
open the selection
end tell

AppleWorks Suite

Commands that Should be Understood by all AppleWorks 6 Document Types

Be sure to precede statement with tell application "AppleWorks 6" and activate, if the application is not currently running. What is covered here: select, copy to clipboard, cut, paste, insert, revert, start slides, stop slides, speak, menu, menu item.

select v : Select the specified object

select specifier : the object to be selected

An AppleWorks 6 text document:

tell document 1
select (paragraphs 1 thru 5)
end tell

copy to clipboard v : Copy the current selection to the clipboard [Application must be 'active'/at front]

copy to clipboard [specifier] : optional object to be selected (else the current selection is used)

As the entry implies, AppleWorks must be activated:

tell document 1
select paragraph 5
copy to clipboard
end tell

cut v : Cut the current selection to the clipboard [Application must be 'active'/at front]

cut [specifier] : optional object to be selected (else the current selection is used)

tell document 1
select paragraph 2
cut
end tell

paste v : Paste from the clipboard to the current selection [Application must be 'active'/at front]

paste [values/formulas/formats] : special things that can be pasted
[transpose boolean] : transpose the data diagonally?

select word 1 of paragraph 1
copy to clipboard
paste after paragraph -1

insert v : Insert a file into a document

insert alias : the file to insert
[at location specifier] : the location at which to insert the file
[using translator text] : the name of the translator to use to import the document
[with fields list of text] : the field order to use when inserting into a database (use "" to skip a field)

tell application "Finder"
set insertDoc to (choose file "Get data:")
tell application "AppleWorks 6"
activate
tell document 1
insert insertDoc
end tell
end tell
end tell

Revert v : Revert to the Last Saved Version of a Document

revert document : the document to be reverted

tell application "AppleWorks 6"
activate
tell document 1 to revert
end tell

start slides v : Start the slideshow for the current document

.

start slides

stop slides v : Stop the slideshow, returning to the normal application state

.

stop slides

These are shown together for obvious reasons:

tell application "AppleWorks 6"
activate
tell document 1 to start slides
delay 20
tell document 1 to stop slides
end tell

To move to the next page (slide), you click on the current page

speak v : Use PlainTalk to speak some text

speak specifier : the text to speak
[using voice text] : the name of the PlainTalk voice to use

tell document 1 to speak (paragraphs 1 thru 5) using voice "Junior"

Menu N : A Menu

elements
contains menu items.
properties
name (text, r/o) : the name of the menu
id (integer, r/o) : the menu id

menu item n : a menu item. Use "select" to perform a menu item action

elements
contained by menus.
properties
name (text, r/o) : the name of the menu
index (integer, r/o) : the menu item number
enabled (boolean, r/o) : is the menu item enabled?
checked (boolean, r/o) : is the menu item checked?
check character (text, r/o) : the character used to check this menu item

tell application "AppleWorks 6"
activate
tell document 1 to select menu item "Open…" of menu "File"
end tell

For more on AppleWorks 6 go to: Free AppleScripts for AppleWorks 6

TextEdit About Window
TextEdit About Window | Source

TextEdit Standard Suite

Although TextEdit is a fairly basic text application, it can be used very effectively in conjunction with AppleWorks 6 to 'fill in the gaps' in AppleWorks' (and others) scripting capabilities. Since my focus here is TextEdit, I wont get into the details on how to integrate TextEdit scripting with other programs, but if you have read the section above on AppleWorks, you should have a pretty good idea of how to go about this. If you haven't looked at it, please do. Now lets look at TextEdit's Standard Suite:

close v : Close an object.

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

Example:

tell application "TextEdit"
activate
set defaultDocName to (choose file name with prompt "Enter a name for this document before closing")
close document 1 saving yes saving in defaultDocName
end tell

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

count specifier : the object for the command [each type] : The class of objects to be counted.

--> integer

Examples:

set countWords to (count words in front document)
display dialog countWords

count characters in word 1 of document 2

delete v : Delete an object

delete specifier : the object for the command

Example:

delete word 1 of document 1

duplicate v : Copy object(s) and put the copies at a new location

duplicate specifier : the object for the command [to location specifier] : The location for the new object(s). [with properties record] : Properties to be set in the new duplicated object(s)

tell front document of application "TextEdit"
	duplicate word 1 of paragraph 1 to before paragraph 2
end tell

exists v : Verify if an object exists

exists specifier : the object for the command

--> boolean

Example:

tell application "TextEdit"
activate
exists document 1
end tell 

--> true because, when TextEdit is activated, it creates a new empty document ie 'Document 1'

get v : Get the data for an object

get specifier : the object for the command

--> any

Example:

get word 3 of document 1

make v : Make a new object

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 data for the object. [with properties record] : The initial values for properties of the object.

--> specifier

Example:

make new document with properties {text:"New Text Document"}

open v : Open an object

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

--> document

Example:

set openFile to (choose file)
open openFile

print v : Print an object

print alias : The file(s) or document(s) to be printed. [print dialog boolean] : Should the application show the Print dialog? [with properties print settings] : the print settings

Example:

print front document with properties {copies:2, collating:true, starting page:1, ending page:1, pages across:1, pages down:1, error handling:standard} without print dialog

quit v : Quit an application

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

Example:

tell application "TextEdit"
activate
set defaultDocName to (choose file name with prompt "Enter a name for this document before quitting")
quit saving yes
end tell

save v : Save an object

save specifier : the object for the command [as text] : The file type in which to save the data. [in alias] : The file in which to save the object.

Example:

save front document as text in "New Text File"

set v : Set an object's data

set specifier : the object for the command to any : The new value.

Example:

set docName to document 1
--Result: document "Untitled" of application "TextEdit"

Essential FileMaker Pro Advanced Terms with Snippets


There are many commands and keywords for FileMaker which are part of standard AppleScript and work exactly the same or nearly the same. Below are some of the definitions of keywords that are more specific to FileMaker with some examples of how to implement them:

go to v : Go to an object

go to specifier : The object to which to go

Examples:


go to (create record) 
-->creates a new record and a reference to the new record to navigate to the record
				
go to cell "Notes" of current record
go to record 5 of current layout
go to layout "List Layout" of database "Appointments.fp7"

create v : Create a new element

create
new type : The class of the new element
[at location specifier] : The location at which to insert the element
[with data any] : The initial data for the element
[with properties record] : The initial data for the properties of the element
→ specifier : To the new object(s)

Examples:

set newRecord to (create new record)
go to newRecord
--> Creates a new record and assigns a reference to the location of the new record and goes to the referenced record, see 'go to' above

create new record at database "Costa Rica Images.fp7"
create new record at database "Contacts Database.fp7" with data {"Jim Smith", "1234 Anywhere St", "Big City", "GA", "25643"}
--> Creates a new record at the database "Contacts Database" and sets initial values for the first five fields, in tabbing order

show v : Bring an object into view

show specifier : The object to be made visible

Examples:

show (every record where cell "AppointmentDate" contains "01/24/2014")
show (every record of database 1 whose cell "GraphicName" contains ".jpg")
show every record of database 1
show every record of current table
show (every record where its cell "Name" begins with "A")

A different example of the use of show:

show database "myDatabase.fp7"

find v : Perform a FileMaker Pro Find given current requests

find specifier : The window in which to find

Example:

delete every request
create request --initiate new find
set cell "Name" of request 1 to "James Thomas"
find
 --Search for a record whose cell "Name" contains "James Thomas"

sort v : Sort the records in a layout

sort specifier : The layout to sort
[by specifier] : The fields to sort by
[in order ascending/descending/custom] : The sort type

Examples:

sort every record  by field "City" -- sort by a specific field
sort layout "Scrolling" by field "Name" in order ascending

open v : Open an object

open specifier : The object to open
[with passwords text] : The password to use
[for Accounts text] : The account name

Examples:

open file "Macintosh HD:FileMaker Library" with passwords "Encrypted Password"
open "/Users/userAccount/Desktop/Outstanding Accounts.fp7"

close v : Close an object

close specifier : The object to close

Examples:

close document 1
close window "Accounts"
close database "Startup Log"

For more on FileMaker Pro Advanced go to: AppleScript and FileMaker

Selected Entries from Microsoft Word

These are essential commands for creating, saving opening and closing Word documents. Many of these work about the same way as they do in other applications, some do not, others have additional options that are specific to Word Applescripting. The Word AppleScript Dictionary is based on Visual Basic and is, therefore much more complex and not as easy to read as what you'd expect from scripting other applications, particularly ones from Apple.

make v : Make a new element

make
new type : the class of the new element.
at location specifier : the location at which to insert the element
[with data any] : the initial data for the element
[with properties record] : the initial values for the properties of the element
→ specifier : to the new object(s)

set createDoc to make new document at desktop
--> create a new document with a reference to the newly created document

set targetImage to choose file with prompt "Please select an image to insert into this document:"
tell active document
		set textRange to create range start 0 end 0
		make new inline picture at textRange with properties {file name: targetImage as string}
end tell
--> put an image into a document 

 make new hyperlink object at end with properties ¬
			{text to display:"Apple,Inc", hyperlink address:"https://www.apple.com", text object:hLinkRange}
--> create a  hyperlink to go to: "https://www.apple.com"

create new document v : Create a new document

create new document
[attached template template] : Reference or path to template to base new document on.
[new template boolean] : Set to true if the document to be created is to become a template for other new documents.
[new document type new blank document/new web page/new notebook document/new publishing document] : Sets the type of document to be created.
→ document : A reference to the newly created document.

create new document attached template "Macintosh HD:Users:username:Library:Application Support:Microsoft:Office:User Templates:My Templates:Blank Web Page.dotx" new document type new web page with new template)
--> create a web document using an existing template as basis for a new template

open v : Open the specified object(s). Returns a reference to the opened file when using the file name parameter.

open specifier : list of objects to open
[file name text] : name of the file to open

set chosenFile to (choose file with prompt "Locate a file to open:")
open file name (chosenFile as string)
--> document "Resume.docx" of application "Microsoft Word"

open file name (alias "Macintosh HD:Users:userName:Resume.docx" as string)

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 alias] : the file in which to save the object

close thisDoc saving no
close active document saving yes

save v : Save an object

save specifier : the object to save
[in alias] : the file in which to save the object
[as type] : the file type of the document in which to save the data

save active document

set doc2Save to (choose file name with prompt "Give new Word document a name:")
save active document in alias doc2Save as type document

save as v : Saves the document with a new name or format. save as document

[file name text] : The name for the document. The default is the current folder and file name. If a document with the specified file name already exists, the document is overwritten without the user being prompted first.
[file format format document/format template/format text/format text line breaks/format dostext/format dostext line breaks/format rtf/format Unicode text/format HTML/format web archive/format stationery/format custom dictionary/format exclude dictionary/ format xml/format documentME/format templateME/format document97/format template97/format PDF/format documentAuto/format templateAuto] : The format in which the document is saved.

save as newDoc file name documentName

set activeDoc to active document
save as activeDoc file name "Business Contacts"
--> a text document

save as "New Resume.docx" file format format document
--> another text document
save as thisDoc file format format HTML file name  "Index.htm" with HTML display only output
--> an HTML document
save as active document file name docPath file format format rtf
--> an 'rtf' document

© 2013 AppleScripter

More by this Author

  • Advanced AppleScript Code
    0

    Advanced AppleScripts. For reasons of logic, because the original site was becoming rather large, some of the posts you find here were moved from the primer site for those who are beyond the basics

  • More Advanced AppleScript Code
    0

    For those of you who still cannot get enough AppleScript to feed your fix, some more free applescript code,Finder,Microsoft Word,Pages,AppleWorks,PowerPoint,TextEdit,iTunes,POSIX paths,database events

  • Free AppleScript Code Examples
    1

    Write AppleScript Code,free AppleScripts of display dialog,display alert,choose from list,finder,choose file,choose file name,choose folder,choose application,choose color,Finder,TextEdit


Comments on 'AppleScript Explained in Plain English'

No comments yet.

    Sign in or sign up and post using a HubPages Network account.

    0 of 8192 characters used
    Post Comment

    No HTML is allowed in comments, but URLs will be hyperlinked. Comments are not for promoting your articles or other sites.


    Click to Rate This Article
    working