Word adds four objects, one event, and many properties that extend the standard suites that Word supports, identified earlier in this appendix and described in your AppleScript documentation. This section provides a reference to these Word-specific objects, events, and properties.
Word defines four new objects: Paragraph Style, Range, Section, and Sentence.
Paragraphs within Word documents all have an associated "style," which determines many of their default properties. This is different than the AppleScript notion of style, which only describes a few basic text properties (such as bold and italic). To avoid conflict with AppleScript's notion of style, Word defines the object Paragraph Style to be a named set of most text properties.
A Paragraph Style object has all the properties of any text object, but does not have any text elements. To change a property for all the paragraphs of a particular style, you can simply change that property of the appropriate paragraph style object.
tell app "Microsoft Word"
set font of paragraph style "Heading 1" to "Helvetica"
end tell
Note that every paragraph has a Paragraph Style property, which is the name of that paragraph's Word style. A script can change any paragraph's style by setting this property:
tell app "Microsoft Word"
set paragraph style of second paragraph to "Heading 2"
end tell
Microsoft Excel defines a Range object to simplify access to Table objects. The standard Table, Row, and Column objects use complex records for returning their data. The Range object, however, returns a simple list of the cells of the given range.
Within word, a Range can be any contiguous part of a table: a row, a column, the whole table, or some rectangular part of the table. A Range object is referenced through the Name form.
tell app "Microsoft Word"
get range "R2C3:R4C5" of table 1
end tell
Word exposes the Section object as a simple extension to all the other standard text objects (for example, Word and Paragraph). In the text stream of a document, a section is bounded by section breaks or a section break and the beginning or end of the document. A document with no section breaks contains one section.
Word exposes the Sentence object as simple extension to all the other standard text objects (for example, Word and Paragraph). In the text stream of a document, a sentence is usually bounded by terminating punctuation (period, exclamation point, question mark), excluding any leading white space. However, a paragraph composed of a stream of text and no punctuation (for example, a heading) is considered to contain one sentence (all of the text).
Word defines one new event: Select.
The Select event applies to any text object. The Select event is just a shorthand for setting the selection of the application to a particular AppleScript object.
The two instructions in the following script are equivalent:
tell app "Microsoft Word"
set selection to second paragraph
select second paragraph
end tell
Here is the syntax for the Select event:
select reference
The reference argument is a valid reference to the object to select.
The Select event is supported by Word because the usual purpose of WordBasic macros is to manipulate the current selection. The most efficient way to perform actions on text within Word is to select the text with the Select event, and then perform complex formatting using WordBasic through the Do Script event. With this scenario, a user can use AppleScript's expressive object references while also taking advantage of WordBasic's efficiency. For more information on using the Do Script event with WordBasic, see "Extending WordBasic with AppleScript" later in this appendix.
Virtually all text properties in Word are exposed to native AppleScript. These properties can be broken down into three categories: character, paragraph, and section. Character properties are generally those available in the Font dialog box (Format menu); paragraph properties are usually found in the Paragraph dialog box (Format menu); section properties are found scattered throughout other dialog boxes (such as Columns on the Format menu and Page Setup on the File Menu).
All of these properties can be accessed from any text object. That is, a paragraph property can be read from a word or sentence object. However, changing these properties often implies changing them for an entire parent object. For example, setting the Justification property of a word object actually changes the justification of the entire paragraph object that contains the word. Similarly, getting the Number Columns property of a paragraph actually returns the number of columns for the section that contains the paragraph. Character properties only affect the exact text object being referenced.
The following topics describe the character, paragraph, and section properties that are exposed by Word.
Note
You can set Word properties that take Boolean values with one of the following three values: true, false, or toggle. The toggle value reverses the current value of the property; for example, if the bold property of the specified text object is true, the following instruction sets it to false:
set bold of textobject to toggle
All of the properties described in the following table apply to each character of the referenced object in a Word document.
Property | Description | Data type |
|---|---|---|
All Caps | Returns or sets a value that specifies whether the object is formatted with all capital letters. | Boolean |
Bold | Returns or sets a value that specifies whether the object is formatted as bold. | Boolean |
Character Position | Returns or sets the vertical position of characters for the object. | Points |
Character Spacing | Returns or sets the amount of spacing between characters for an object. | Points |
Property | Description | Data type |
|---|---|---|
Hidden | Returns or sets a value specifying whether the text of the object is hidden. | Boolean |
Italic | Returns or sets a value that specifies whether the text of the object is italic. | Boolean |
Kerning Size | Returns or specifies the smallest font size to kern for the object. | Points |
Language | Returns or specifies the language for the object. | String |
Length | Returns the number of characters contained in the object | Integer |
Outline | Returns or sets a value that specifies whether the object is formatted as outline. | Boolean |
Plain | Returns or sets a value that specifies whether there are no character styles applied to the object. | Boolean |
Shadow | Returns or sets a value that specifies whether the object is formatted with shadow. | Boolean |
Small Caps | Returns or sets a value that specifies whether the object is formatted with small capital letters. | Boolean |
Strikethrough | Returns or sets a value that specifies whether the object is formatted with strikethrough. | Boolean |
Subscript | Returns or sets a value that specifies whether the object is formatted as subscript. | Boolean |
Superscript | Returns or sets a value that specifies whether the object is formatted as superscript. | Boolean |
Underline | Returns or specifies the type of underlining for the object. | One of the following values: none, single, words only, double, dotted, hidden |
All of the properties described in the following table apply to the paragraph or paragraphs related to the referenced object in a Word document.
Property | Description | Data type |
|---|---|---|
After Spacing | Returns or sets the spacing after paragraphs for the object. | Points |
Before Spacing | Returns or sets the spacing before paragraphs for the object. | Points |
Top Border Color, Left Border Color, Bottom Border Color, Right Border Color, and Between Border Color | Return or set the color of a border of the object. | An RGB color |
Top Border Distance, Left Border Distance, Bottom Border Distance, Right Border Distance, and Between Border Distance | Return or set the distance from text of a border of the object. | Points |
Border Shadow | Returns or sets a value that specifies whether the object has shadowed borders. | Boolean |
Top Border, Left Border, Bottom Border, Right Border, and Between Border | Return or set the type of a border for an object. | One of the following values: none, hair, thin, medium, thick, thicker, thickest, double, thick double, thicker double, dotted, dashed |
Dont Hyphenate | Returns or sets a value that specifies whether automatic hyphenation is suppressed for the object. | Boolean |
First Line Indent | Returns or sets the amount of indent for the first line of the paragraph (also known as the hanging indent) for the object. | Current application units (points, picas, centimeters, inches) |
Justification | Returns or specifies the paragraph justification for the object. | One of the following values: left, right, center, full |
Property | Description | Data type |
|---|---|---|
Keep Lines Together | Returns or sets a value that specifies whether the lines in a paragraph or paragraphs of the object are kept together. | Boolean |
Keep With Next | Returns or sets a value that specifies whether a paragraph or paragraphs of the object are kept on the same page with their following paragraphs. | Boolean |
Left Indent | Returns or specifies the width of the left paragraph indent for the object. | Current application units (points, picas, centimeters, inches) |
Line Spacing Amount | Returns or specifies the line spacing for the object (when Line Spacing Type is multiple). | Lines |
Line Spacing Type | Returns or specifies the type of line spacing for the object. | One of the following values: single, lines1pt5, double, at least, exactly, multiple |
Page Break Before | Returns or sets a value that specifies whether page breaks are made before paragraphs for the object. | Boolean |
Right Indent | Returns or specifies the width of the right paragraph indent for the object. | Current application units (points, picas, centimeters, inches) |
Shade Background Color | Returns or specifies the background color of paragraph shading for the object. | An RGB color |
Shade Foreground Color | Returns or specifies the foreground color of paragraph shading for the object. | An RGB color |
Property | Description | Data type |
|---|---|---|
Shade Pattern | Returns or specifies the shading pattern for the object. | One of the following values: clear, solid, p5, p10, p20, p25, p30, p40, p50, p60, p70, p75, p80, p90, dark horizontal, dark vertical, dark down diagonal, dark up diagonal, dark grid, dark trellis, light horizontal, light vertical, light down diagonal, light up diagonal, light grid, light trellis |
Suppress Line Numbers | Returns or sets a value that specifies whether line numbers are suppressed for the object. | Boolean |
Tab Alignments | Returns or specifies the alignment of each nondefault tab stop for the object. | A list of the following values: left, center, right, decimal, bar |
Tab Leaders | Returns or specifies the leader style of each nondefault tab stop for the object. | A list of the following values: none, dot, hyphen, single, heavy |
Tab Positions | Returns or specifies the position of each nondefault tab stop for the object. | Current application units (points, picas, centimeters, inches) |
Widow Orphan Control | Returns or sets a value that specifies whether widow and orphan control is active for the object. | Boolean |
All of the properties described in the following table apply to the section or sections related to the referenced object in a Word document.
Property | Description | Data type |
|---|---|---|
Bottom Margin | Returns or sets the width of the bottom margin for the object. | Current application units (points, picas, centimeters, or inches) |
Column Spacings | Returns or sets the sizes of spaces between columns for an object. | Current application units (points, picas, centimeters, or inches) |
Property | Description | Data type |
|---|---|---|
Column Widths | Returns or sets the widths of columns for an object. | Current application units (points, picas, centimeters, or inches) |
Equal Width Columns | Returns or sets a value that specifies whether the columns are the same width for the object. | Boolean |
First Paper Source | Returns the paper source for the first page of the object. Read only. | One of the following values: none, upper, lower, middle, manual, envelope, envelope manual, auto, tractor, small format, large format, large capacity, cassette, manual PostScript |
Gutter Margin | Returns or sets the width of the gutter margin for the object. | Current application units (points, picas, centimeters, inches) |
Left Margin | Returns or specifies the width of the left margin for the object. | Current application units (points, picas, centimeters, inches) |
Line Between Columns | Returns or sets a value that specifies whether there are lines between columns for the object. | Boolean |
Number Columns | Returns or specifies the number of columns for the object. | Integer |
Other Paper Source | Returns the paper source for pages other than the first page for the object. Read only. | One of the following values: none, upper, lower, middle, manual, envelope, envelope manual, auto, tractor, small format, large format, large capacity, cassette, manual PostScript |
Page Height | Returns the height of the page for the object. Read only. | Current application units (points, picas, centimeters, inches) |
Page Orientation | Returns the orientation of the page for the object. Read only. | One of the following values: none, portrait, landscape, mixed |
Property | Description | Data type |
|---|---|---|
Page Width | Returns the page width for the object. Read only. | Current application units (points, picas, centimeters, inches) |
Right Margin | Returns or specifies the width of the right margin for the object. | Current application units (points, picas, centimeters, inches) |
Top Margin | Returns or specifies the width of the top margin for the object. | Current application units (points, picas, centimeters, inches) |