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
>>.
|
