The rest of this chapter describes each text-related TextEdit class and gives examples of how to use them in your scripts. As always, to keep up-to-date about any scriptable program on your computer, use Script Editor's Open Dictionary... menu item to view the software's dictionary of commands and classes. Chapter 2, describes application dictionaries.

Dictionary classes

attribute run

A subdivision of a block of text, an attribute run is a group of characters that all have the same attributes, such as font or size. An attribute run is just a different way of abstracting or grouping parts of a text block. For example, if the first paragraph of a document's text has some characters that are 12 points in size and others that are 18 points, then getting the attribute runs of that paragraph would return two separate chunks of text in a list (one group would be 12 points in size and the other would be 18 points). However, getting paragraph 1 of that text would return one chunk of characters of different sizes. In other words, the paragraph would contain the two attribute runs. The following example gets every attribute run of a document's text (a list containing three attribute runs). The first line of the text contains the characters "hi here is some more text k," but the last "k" character is in a different font and size than the sentence's other characters. Consequently, the "k" and its following carriage return character is considered a separate attribute run then its preceding characters. The return value of the code every attribute run of text of document 1 is at the bottom of the script displayed within comment characters:

tell application "TextEdit"

   activate

   every attribute run of text of document 1

   (* returns a list of three attribute runs:

   {"hi here is more text ", "k

   ", "

   Meeting notes:

   Wednesday, October 11, 2000 12:58:16 PM"}

   *)

end tell

The following are attribute run elements:

character

An attribute run can contain characters, such as:

(count characters of attribute 1 of text of document 1)

If an attribute run is "Hi here is some text" then the latter code fragment would return an integer 20, or the number of characters in the sentence. See the character class.

paragraph

An attribute run or chunk of text could contain one or more paragraphs, as in (count paragraphs of attribute run 1 of text of document 1). See the paragraph class.

word

An attribute run or chunk of text can contain one or more words, as in:

(count words of attribute run 1 of text of document 1)

See the word class.

The following are attribute run properties:

font string

Each attribute run has a font property, as in Arial. Code such as:

font of attribute run 1 of text of document 1

returns a string such as Geneva.

color color

Although appearing in the TextEdit dictionary, the color property (representing the color of the text in the attribute run) was not accessible in the Mac OS X.

size integer

The size property is accessible from code such as size of attribute run 1 of text of document 1. It represents the size of the first character in the attribute run's text.

class integer (read-only)

This attribute returns the word string.

character

A character object is what you would expect it to be, a single character inside of a word or string. The following example returns the first word of a document as a list of character objects. If you instead used the following code then the return value would be a string like "F":

get character 1 of word 1 of text of document 1

tell app "TextEdit"

   get characters of word 1 of text of document 1

end tell

(* Example return value:

{"F", "i", "r", "s", "t"}  *)

The following are character elements:

attribute run

The code:

attribute run 1 of character 1 of text of document 1

usually returns the character itself as a string, as in N. See the attribute run class.

character

It doesn't make sense for a character to have a character element, however, the following code returns the character as a string (e.g., "j"):

character  1 of character 1 of text of document 1

paragraph

A character's paragraph element returns itself. So if the character is "j," then its paragraph 1 element returns the string "j."

word

A character's word element returns itself. So if the character is "j," then its word 1 element returns the string "j."

The following are character properties:

font string

Getting the font property returns a string like Helvetica, representing the character's font.

color color

Accessing the color property of a character object returns a data value such as <<data RGB FFFF433951F7>>.

size integer

Trying to access the character size property returns the font size of the character, as in 14.

class integer (read-only)

The class property returns the word string.

document

A document object represents an open TextEdit document, as depicted in Figure 35-1. You can get a reference to one or more documents by grabbing the TextEdit application's document elements, as in tell app "TextEdit" to get documents. This code returns a list that looks like:

{document 1 of application "TextEdit", document 2 of application "TextEdit"}

The following example gets the various properties of a document. You can view the values of these properties using the Event Log of Script Editor. This example shows some Event Log output at the bottom of the script:

tell application "TextEdit"

   set doc to document 1 (* the front document is stored in doc variable *)

   (* a document's properties revealed *)

   doc's path -- the Unix path

   doc's modified

   doc's name

   set txt to text of doc (* returns the content of the document 

if any (if the document is empty, returns an empty string "") *)

   set parcount to (count of txt's paragraphs)

   set wdcount to (count of txt's words)

   (* Event Log output:

   get document 1

   --> document 1

   get path of document 1

   --> "/Users/bruceper/Documents/newfile.rtf"

   get modified of document 1

   --> 0

   get name of document 1

   --> "newfile.rtf"

   get every text of document 1

   --> "Hi, I'm pleased to be the first paragraph of this document. 

My font is  \

   Verdana."

   *)

end tell

The following are document elements:

text

The text of a TextEdit document can be seized with code such as:

tell app "TextEdit" to get text of document 1

You can also write to a document, without using the open for access, write, or close access scripting additions, by using code such as:

set the text of document 1 to "My chunk of text"

This code shows how to append text, such as a date string, to an existing TextEdit document:

tell app "TextEdit"

   set cr to ASCII character 13 (* use as a return or new line character *)

   set tmessage to cr & "Meeting notes:" & cr &¬

   ((current date) as string)

   set docs to documents -- docs contains a list of open TextEdit documents

   repeat with d in docs

      if ((name of d) contains "memo log") then (* only add text to "memo log"

file *)

         set text of d to (text of d) & tmessage (* append the text stored

in var tmessage to end of file *)

         (* the path looks like "/users/oneuser/library/desktop/myfile.rtf" *)

         set pth to path of d

   exit repeat

      end if

   end repeat

   display dialog "the memo file is at: " & pth

end tell

The following are document properties:

path string

This property returns a string that looks like "/users/oneuser/desktop/myfile.rtf." This Unix-style pathname identifies where the document is stored on the computer. The back-slash ("/") character that begins path says "begin at the startup disk or root." The standard disk, file, and folder delimiter for AppleScript, the colon (":"), is still used by many AppleScript commands (such as choose folder) to represent where the file is stored. If the TextEdit document has not yet been saved, then its path property returns nothing in OS X, not even an empty string (""). You can set the path property of a document (this will not raise an error in my testing), then use TextEdit's save command to save the file to the new path.

modified integer (read-only)

This property returns 1 if the document has been modified since it was last saved or if the document has not been modified. The following example finds out if a document has been saved, then saves the document (using the save command) if the document has unsaved changes:

tell application "TextEdit"

   activate

   (* if the document has been changed since it was last saved its 'modified' 

property will return 1 *)

   if (modified of document 1) > 0 then

      save document 1

      close document 1

   else

      close document 1

   end if

end tell

name string

name returns a string that is the name of the document file. If you have just created the document in TextEdit but have not yet saved it, the name property returns nothing (not even a string such as "untitled"). Trying to find out whether the document has a valid name (such as by accessing the length of name to see if the name has more than zero characters) raises an error at least in Mac OS X. You might try this document name test in future releases, or use a try block to catch and examine the error. Chapter 7, describes error trapping with the try statement.

class integer (read-only)

Accessing the class property for the document object raises an error in Mac OS X.

paragraph

A paragraph object is a chunk of text that is terminated by a new line or paragraph character. You can set the paragraphs of a document's text with code such as:

tell app "TextEdit" to set paragraph 3 of text of document 1 to¬

 "new paragraph"

If you try to get paragraphs of text of document 1, for example, and the document does not contain any content, then a script error is raised. An easy way to find out whether a TextEdit document contains any text yet is to check the length of the number of words in the document, as in the following example:

tell app "TextEdit"

   activate

   set l to (text of document 1)

   if (length of 1) > 0 then

      set notEmpty to true

   end if

end tell

The following are paragraph elements:

attribute run

A paragraph can contain one or more attribute runs, which are chunks of text that share attributes such as font and size. For example, if a paragraph contained two bits of styled text that had different fonts, then each of these text chunks would be considered an attribute run within a paragraph. See the attribute run class.

character

Paragraphs can contain one or more characters (unless the paragraph is only an empty string and return character). You can get all of the characters of a paragraph inside of a list with code such as:

tell app "TextEdit" to get characters of paragraph 1 of text of document 1

The return value would look like:

{"a", " ", "v", "e", "r", "y", " ", "s", "h", "o", "r", "t", "

 ", "p", "a", "r", "a", "g", "r", "a", "p", "h"}

paragraph

Paragraphs do not contain other paragraphs (philosophically), but the TextEdit dictionary still lists paragraph as an element of the paragraph object.

word

A word is a series of characters unbroken by a space character. You can get all the words of the paragraph inside of a list with code, such as:

tell app "TextEdit" to get words of paragraph 1 of text of document 1

This kind of code phrase can be very handy in searching for letters, symbols, words, or phrases inside of text. See the word class.

The following are paragraph properties:

font string

This property returns the font name for the first character of a paragraph, such as Helvetica.

color color

This property returns the color object for the first character of a paragraph, with a return value in Mac OS X 10.0 that looks like <<data RGB FFFF433951F7>>.

size integer

The size property is the size of the font of the paragraph's first character.

class integer

This property returns the word string, not an integer as the dictionary definition specifies.

text

text represents the body or content of a document. The whole chunk of content will be returned as a string from code such as:

tell app "TextEdit" to get text of document 1

If the document does not yet have any content, then its text element returns an empty string (""). Once you have the text in memory, you can get or set the values of its characters, words, or paragraphs. The following example finds out whether the existing content of a document contains the word Copyright; if it does not, then Copyright 2001 is appended to the end of the document:

tell application "TextEdit "

   activate

   set cr to ASCII character 13

   set txt to text of document 1

   set wd to (words of txt)

   set len to length of wd

   if (len > 0) then

      if wd does not contain "Copyright" then

         set (text of document 1) to txt & cr & "Copyright 2001"

      else

         display dialog "copyright included"

      end if

   end if

end tell

The following are text elements:

attribute run

text can contain one or more attribute runs, which are chunks of text that share attributes such as font and size. To get the attribute runs inside of text, use code such as:

get attribute runs of text of document 1

If the text does not have any attribute runs, then this code returns an empty list ({}). See the attribute run class.

character

text can contain zero or more characters. You can get all of the characters inside of text with code such as:

tell app "TextEdit" to get characters of text of document 1

This returns a list of characters that looks like {"a", "b", "c"} (it will be a giant list if the document has a lot of text). You can also get a range of characters with the following syntax:

get characters 3 thru 17 of text of document 1

This code raises an error if the document does not have 17 characters. If the document is empty, then the following code returns nothing (at least in OS X), not even an empty list:

get characters of text of document 1

See the character class.

paragraph

text contains zero or more paragraphs, which are delineated in TextEdit by paragraph marks or new line characters. You can get a paragraph count for a document, for instance, by using code such as:

count paragraphs of text of document 1

See the paragraph class.

word

You can get all of the words of a document with the code:

words of text of document 1

This returns a list of words that looks like {"list", "of", "words"}. See the word class.

The following are text properties:

font string

This returns a string such as "ArialMT." This string is the name of the font of the text block's first character. In other words, if the first character of the text of document 1 is of the font "ArialMT" and the second character is "Apple Chancery," then the code phrase font of text of document 1 returns "ArialMT."

color color

This property will raise an error if you try to access its value from a text object, but you can get the color of individual characters in text. See the character class.

size integer

This property will return an integer representing the point size of the text's first character (such as 14).

class integer (read-only)

The TextEdit dictionary identifies this property's return value as integer, but my testing reveals that it returns the word string.

word

A word (e.g., "sentence") is a series of characters unbroken by a space character. A word contains a character object. The syntax words of text of document 1, for example, will return a (potentially long) list of words. The space characters separating the words will be left out of the list. This syntax makes it very easy to search a document's words for a specific word, as in

Set found to ((text of document 1) contains "Copyright")

The following is a word element:

character

This element is a subdivision of a word. For instance, the following code returns all of the characters of the document's first word as a list, as in {"F", "i", "r", "s", "t"}:

characters of word 1 of text of document 1

See the character class.

The following are word properties:

font string

This property will return a string like "Helvetica."

color color

This property will return a color object representing the text color the return value in Mac OS X looks like <<data RGB FFFF433951F7>>.

size integer

This property will return an integer representing the point size of the text's first character (such as 14).

class integer (read-only)

This property returns the word string.

application

This class represents the TextEdit application itself. In TextEdit's dictionary, you can find the TextEdit application object described under the TextEdit Suite (Chapter 1 describes AppleScript dictionaries). The application has four properties or attributes (i.e., the value of its name property is "TextEdit"). You can get references to all of TextEdit's documents with code such as:

tell app "TextEdit" to get documents

The following example queries the property values of the copy of TextEdit running on the machine where the script executes. You can view the output (the property values) in Script Editor's Event Log window. Display this window by typing Command-E when Script Editor is the frontmost application, then make sure that the checkboxes labeled "Show Events" and "Show Event Results" are checked.

tell application "TextEdit"

   frontmost

   name

   version

 (* Example Event Log output:

   tell application "TextEdit"

      get frontmost

      --> 0

      get name

      --> "TextEdit"

      get version

      --> 0

   end tell

   *)

end tell

The following are application elements:

document

TextEdit can have zero or more open documents. Each one of these documents is considered a document object with its own properties or attributes. Each open document is indexed from front to back in the manner of document 1 (the frontmost document if you make TextEdit the active application), document 2, and so on. For example, to count the open documents use:

tell app "TextEdit to count documents

To close an open document, use:

tell TextEdit to close document 1

(or whatever its index is). See the document class description for a demonstration of how to get a document's properties.

window

A TextEdit window is a desktop window that is showing a TextEdit document. You can get references to all the names of the open TextEdit windows by using the code:

tell app "TextEdit" to get name of windows

This code returns a list that might look like:

{"newfile.rtf", "newfile 2.rtf"}

The latter list contains the name of one window (i.e., the filename of the document contained by the window) as a string.

The following are application properties:

frontmost integer (read-only)

This property returns 1 only if TextEdit is the active application (if you click on a TextEdit window then TextEdit becomes the active application); it returns otherwise.

name string (read-only)

This property returns "TextEdit."

version integer (read-only)

This property represents the application's version number, which returns in Mac OS X 10.0.

class integer (read-only)

Getting the class property caused a script error with TextEdit and Mac OS X.

color

color objects have just one property: class. Most of the other TextEdit classes, such as character, word, paragraph, and text, have color properties that can be queried using AppleScript. They return data value types, as in <<data RGB FFFF433951F7>>.

The following is a color property:

class integer (read-only)

The TextEdit color object has a class property whose value is <<class RGB >>.