Quark Apple Events Scripting User Manual
A Guide to Apple Events Scripting
A Guide to Apple Events Scripting
ntroduction 1
I
About this Guide 1
What You Need 1
Scripting Overview 2
Introduction to Apple Events 2
The Object Model 3
Script Writing Syntax 9
Optimizing the Performance of Scripts 9
Script Writing Sample 11
The Layout Construction Script 12
About the Script Breakdown 19
Breakdown of the Layout Construction Script 19
Definitions and Examples — Apple
Events Terminology 33
Format 34
Object Reference Forms 34
II |
Insertion Points in the Hierarchy 35
Definitions and Examples — Events
Supported by QuarkXPress 35
Standard Suite 35
Word Filter Suite 39
Miscellaneous Suite 40
QuarkXPress Suite 40
Data Coercion Chart 41
Data Coercion Using the AppleScript Dictionary 42
Events, Objects, and Parameters 42
Elements and Properties 43
Inherited Properties 43
Reference Material for QuarkXPress Objects 44
Application Events and Examples 44
Application Elements and Reference Forms 44
TA BL E OF C ONTENTS
Application Properties, Data Types,
and Descriptions 45
Project Events and Examples 48
Project Elements and Reference Forms 48
Project Properties, Data Types, and Descriptions 49
Layout Space Events and Examples 50
Layout Space Elements and Reference Forms 50
Layout Space Properties, Data Types,
and Descriptions 51
Window Events and Examples 57
Window Elements and Reference Forms 57
Window Properties, Data Types, and Descriptions 57
Selection Object Properties, Data Types,
and Descriptions 58
Character Events and Examples 58
Character Properties, Data Types, and Descriptions 59
Line Events and Examples 61
Line Elements and Reference Forms 61
Line Properties, Data Types, and Descriptions 61
Paragraph Events and Examples 63
Paragraph Elements and Reference Forms 64
Paragraph Properties, Data Types,
and Descriptions 64
Story Events and Examples 68
Story Elements and Reference Forms 68
Story Properties, Data Types, and Descriptions 68
Text Events and Examples 71
Text Elements and Reference Forms 71
Text Properties, Data Types, and Descriptions 72
Word Events and Examples 74
Word Elements and Reference Forms 74
Word Properties, Data Types, and Descriptions 75
III
|
TABLE OF CON TE NT S
Open Type Style Record Properties, Data
Types, and Descriptions 77
Menu Events and Examples 77
Menu Elements and Reference Forms 78
Menu Properties, Data Types, and Descriptions 78
Character Spec Events and Examples 78
Character Spec Elements and Reference Forms 78
Character Spec Properties, Data Types,
and Descriptions 78
Color Spec Events and Examples 80
Color Spec Elements and Reference Forms 80
Color Spec Properties, Data Types,
and Descriptions 80
Color System Events and Examples 81
Color System Elements and Reference Forms 81
Color System Properties, Data Types,
and Descriptions 81
Table Column Events and Examples 82
Table Column Elements and Reference forms 82
Table Column Properties, Data Types,
and Descriptions 82
Table Row Events and Examples 82
Table Row Elements and Reference forms 82
Table Row Properties, Data Types,
and Descriptions 83
Horizontal Gridline Events and Examples 83
Horizontal Gridline Properties, Data Types,
and Descriptions 83
Vertical Gridline Events and Examples 84
Vertical Gridline Properties, Data Types,
and Descriptions 84
Contour Events and Examples 84
Contour Elements and Reference Forms 85
IV
|
TA BL E OF C ONTENTS
Contour Properties, Data Types, and Descriptions 85
Shape Path Events and Examples 85
Shape Path Elements and Reference Forms 85
Shape Path Properties, Data Types,
and Descriptions 85
Default Document Events and Examples 85
Default Document Elements and Reference Forms 86
Default Document Properties, Data Types,
and Descriptions 86
Delimit Item Events and Examples 91
Delimit Item Elements and Reference Forms 91
Delimit Item Properties, Data Types,
and Descriptions 92
Delimit Table Events and Examples 92
Delimit Table Elements and Reference Forms 92
Delimit Table Properties, Data Types,
and Descriptions 92
Fontset Spec Events and Examples
(East Asian Only) 93
Fontset Spec Elements and Reference Forms
(East Asian Only) 93
Fontset Spec Properties, Data Types, and
Descriptions (East Asian only) 93
Generic Box Events and Examples 94
Generic Box Elements and Reference Forms 94
Generic Box Properties, Data Types,
and Descriptions 94
Generic Cell Events and Examples 97
Generic Cell Properties, Data Types,
and Descriptions 97
Graphic Box Events and Examples 98
Graphic Box Elements and Reference Forms 99
Graphic Box Properties, Data Types,
and Descriptions 99
V
|
TABLE OF CON TE NT S
Graphic Cell Events and Examples 102
Graphic Cell Properties, Data Types,
and Descriptions 102
Group Box Events and Examples 102
Group Box Elements and Reference Forms 103
Group Box Properties, Data Types,
and Descriptions 103
H and J Spec Events and Examples 103
H and J Spec Elements and Reference Forms 104
H and J Spec Properties, Data Types,
and Descriptions 104
Image Events and Examples 105
Image Elements and Reference Forms 105
Image Properties, Data Types, and Descriptions 106
Layer Events and Examples 108
Layer Elements and Reference Forms 108
Layer Properties, Data Types, and Descriptions 109
Line box Events and Examples 109
Line box Elements and Reference Forms 109
Line box Properties, Data Types, and Descriptions 110
Master Layout space Events and Examples 113
Master Layout space Elements and
Reference Forms 113
Master Layout space Properties, Data Types,
and Descriptions 114
Page Events and Examples 120
Page Elements and Reference Forms 120
Page Properties, Data Types, and Descriptions 121
Clipping Path Events and Examples 122
Clipping Path Elements and Reference Forms 122
Clipping Path Properties, Data Types,
and Descriptions 122
VI
|
TA BL E OF C ONTENTS
Picture Box Events and Examples 122
Picture Box Elements and Reference Forms 123
Picture Box Properties, Data Types,
and Descriptions 123
Picture Cell Events and Examples 126
Picture Cell Elements and Reference Forms 126
Picture Cell Properties, Data Types,
and Descriptions 126
Spread Events and Examples 127
Spread Elements and Reference Forms 127
Spread Properties, Data Types, and Descriptions 128
Style Spec Events and Examples 128
Style Spec Elements and Reference Forms 128
Style Spec Properties, Data Types,
and Descriptions 129
Table Box Events and Examples 130
Table Box Elements and Reference forms 130
Table Box Properties, Data Types,
and Descriptions 130
Text Box Events and Examples 133
Text box Elements and Reference Forms 133
Text box Properties, Data Types, and Descriptions 134
Text Cell Events and Examples 138
Text Cell Elements and Reference Forms 139
Text Cell Properties, Data Types, and Descriptions 139
Text Style Range Events and Examples 140
Text Style Range Elements and Reference Forms 141
Text Style Range Properties, Data Types,
and Descriptions 141
Vertex Events and Examples 144
Vertex Elements and Reference Forms 144
Vertex Properties, Data Types, and Descriptions 144
|
VII
TABLE OF CON TE NT S
Vertical Guide Events and Examples 145
Vertical Guide Elements and Reference Forms 145
Vertical Guide Properties, Data Types,
and Descriptions 145
Xtension Events and Examples 146
Xtension Elements and Reference Forms 146
Xtension Properties, Data Types, and Descriptions 146
Custom Bleeds Setup Properties, Data Types,
and Descriptions (Requires Custom Bleeds
QuarkXTensions Software) 146
Blend Record Events and Examples 147
Blend Record Elements and Reference Forms 147
Blend Record Properties, Data Types,
and Descriptions 147
Fixed Point Properties, Data Types,
and Descriptions 147
Fixed Rectangle Properties, Data Types,
and Descriptions 147
Font Record Properties, Data Types,
and Descriptions 148
Frame Record Properties, Data Types,
and Descriptions 148
Justification Record Properties, Data Types,
and Descriptions 149
OPI Setup Record Properties, Data Types,
and Descriptions(Requires OPI
QuarkXTensions software) 150
OPI Setup object 150
Print Setup record Properties, Data Types,
and Descriptions 150
Rule Record Properties, Data Types,
and Descriptions 152
Tab Record Properties, Data Types,
and Descriptions 153
Glossary
VIII
|
TA BL E OF C ONTENTS
INTRODUCTION
This guide provides information about Apple®events scripting with
uarkXPress
Q
are identified as such.
ABOUT THIS G UIDE
This document is for people who are ready to create scripts that communicate
with QuarkXPress. If you need assistance writing or debugging scripts, consult
the documentation provided with your scripting application and the scripting
forums on the online services. Quark also provides additional online scripting
support (Forum:
scriptsupport@quark.com).
To learn more about Apple events scripting, you may want to purchase a
third-party book such as The
Dummies,
exist, some of which include scripting software. You can also visit
www.apple.com to find electronic resources and URLs for Apple events script-
ing.
WHAT YOU NEE D
To write scripts, you need the following:
• Mac OS
®
X or later.
• A scripting application such as AppleScript
• The documentation (included with your scripting application) that teaches
you the scripting language. You should familiarize yourself with the scripting
language before attempting to write scripts for QuarkXPress.
• A basic understanding of programming (including concepts such as loops,
conditional processing, if-then-else constructs, and variables) gained through
writing HyperTalk scripts or macros, or working in programming languages
such as C, BASIC, Java
®
Apple event properties that are specific to East Asian features
.
www.quark.com/service/forums/, and e-mail:
AppleScript Handbook, AppleScript for
or
AppleScripting QuarkXPress.
™
, or Pascal.
Many other third-party books
®
.
To run AppleScript scripts that communicate with QuarkXPress, you must
have Script XTensions
refer to
A Guide to QuarkXPress 2016
®
software loaded. For information about this software,
.
|
IX
INTRODUCTION
Script XTensions software is not required to run scripts that communicate with
ersions of QuarkXPress prior to QuarkXPress 5.0.
v
A basic understanding of programming is optional. AppleScript is a relatively
easy language to learn. You can begin by writing basic scripts, and add to them
when your understanding of the language is more advanced.
WH AT THIS G UIDE PR OVI DE S
This guide provides background information on Apple events, an analysis of a
sample script, and specific information about writing scripts for QuarkXPress.
If you are unfamiliar with Apple events terminology, read the chapters
sequentially and refer to the glossary as necessary.
SCRIPTING OV ERVIE W
This section provides an overview of Apple events scripting with QuarkXPress.
First, it introduces the concepts and terminology involved, including: the object
model, objects, object hierarchy, object references, reference forms, insertion
points in the hierarchy, events, suites, and the QuarkXPress object hierarchy.
You should understand these concepts and terms before you attempt to write
scripts for QuarkXPress.
The second part of this section provides information on optimizing the
performance of scripts.
INTRODUCTION TO A PPLE EVENTS
Apple events, a Mac OS feature, allows interapplication communication on a
local system or across a network. Applications communicate through standard
Apple events messages that give instructions, respond to instructions, and send
or receive data. The terminology for Apple events messages is listed in the Apple
Events Registry for each application, which is maintained by Apple.
SC RI PTS
Apple events can be generated by scripts, which are a series of statements sent
to applications that tell them to do a series of tasks. The scripting language is
provided by scripting software such as AppleScript. Scripts combine the scripting
language syntax with the standard Apple events terminology defined in the
Apple Events Registry.
SY ST EM-LE VE L SCR IP TIN G
Scripting software is developed specifically for script writing. It is more powerful
than scripting systems built into applications because it allows you to use one
scripting language to write scripts for any application that supports Apple events.
You can even write scripts to link applications that are Apple events-aware.
X
|
IN TR OD UC TION
You can do everything from simple formatting tasks to complex database
ublishing with scripts. For example, you might have a script that alphabetizes
p
paragraphs or formats texts. You can also write a script to merge addresses from
a database into a QuarkXPress letter template. It’s even possible to produce an
entire catalog automatically by linking a QuarkXPress layout to a database of
pictures and text.
THE OBJECT M ODEL
The Apple events object model is a message protocol that allows Mac OS applications to communicate. Messages built according to the object model consist
of events and objects, but can include data. Objects are distinct items in an
application, such as a text box. Events are the actions that objects are capable
of performing.
If you’re familiar with QuarkXPress, you understand that an application is composed of objects. QuarkXPress layouts contain pages, pages contain text boxes,
text boxes contain text, and text has various styles associated with it. Each
object has specific capabilities. For example, a text box can be moved, resized,
copied, and linked to other boxes. A text box has item specifications that can
be changed (such as background color, number of columns, and text inset)
and it can contain formatted text.
OB JE CTS
An object is a distinct item (in an application) that can be manipulated by an
Apple event. Objects are defined according to their class, properties, elements,
and the events they can respond to. QuarkXPress users are familiar with objects
such as layouts, pages, text boxes, picture boxes, and lines.
•
Object class:
Objects that share specific characteristics are categorized into object
classes. For example, all layouts belong to the “layout” object class.
•
Properties:
Properties are the characteristics shared by objects in the same object
class. For example, the object class for layout has properties such as file path,
name, print setup, and version.
•
Elements:
Elements are the objects directly accessible from within another
object. For example, a page is an element of a layout.
•
Events:
Events are the actions an object is capable of performing. Objects in
the same object class respond to the same events. For example, the set event
can be used to change the tool mode of all layouts.
QuarkXPress uses the layout and project object classes; however, the document
object class is included in the QuarkXPress dictionary for AppleScript, so scripts
that refer to documents should still operate correctly.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 1
ABOUT THIS G UI DE
OB JE CT HI ER ARCHY
The Apple events object hierarchy is based on the simple concept of placing
things inside other things. An application’s object hierarchy usually consists
of objects such as windows, layouts, boxes, and contents. A specific hierarchy
in QuarkXPress might include a layout that contains a page. The page contains
a text box and the text box contains a story. The story contains paragraphs, and
the paragraphs contain lines. The lines contain words and the words con tain
characters. Characters are at the end of the hierarchy because they can’t
contain anything.
Objects that enclose other objects are referred to as containers. Objects that are
enclosed by other objects are referred to as elements. For example, a layout is
a container for a page; the page is an element of the layout.
OB JE CT RE FE RENCE S
An Apple events message must identify a specific object in an application to
communicate. Objects are identified by a reference. For example, the message
might reference the second text box on the first page. The reference first identifies the container (the page) enclosing the object (the text box) that you’re
specifying. It then uses a reference form to separate a specific object (the second
text box) from all possible objects in the container.
RE FE RENCE F ORMS
Objects in QuarkXPress can be referred to by six reference forms: index, ID,
name, range, relative position, or test. See the “Apple Events Terminology”
portion of the “Reference Materials” section of this document for an example
of how to use each reference form.
•
Index:
used to identify an ordered element in a container with an integer
number (for example, the first text box on a page).
Windows, text boxes, and picture boxes are numbered from front to back; layouts are numbered from left to right. The left-most layout or front window is
always number [1]; the frontmost picture box or text box in the layout is always
number [1]. (The frontmost picture box or text box may change as you manipulate and create other boxes.) Pages are numbered according to their absolute
page numbers rather than section page numbers.
As you create and insert objects in the hierarchy, the index reference form
for existing objects may change. For example, if you insert a text box before
“text box 1,” then “text box 1” becomes “text box 2.”
ID:
used to identify objects that have unique IDs. A unique ID is good for the
•
life of the layout.
•
Name:
used to identify objects that are named with a text string (for example,
a layout named “Ad Layout” by a user).
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
2
|
SC RI PT IN G OVERVIEW
•
Range:
used to identify a range of objects (for example, text boxes three
through five).
Relative Position:
•
used to identify objects that are before or after other
objects (for example, the text box before the last text box on the page).
Test:
used to identify objects that meet certain conditions, (for example, the first
•
text box with a red background).
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 3
SCRIPTING OV ER VI EW
IN SE RTION P OINTS I N T HE H IER AR CH Y
An insertion point specifies where to place an object within the container
hierarchy. For an example of how to use each insertion point, see the
“Apple Events Terminology” portion of the “Reference Materials” section
of this document.
•
Beginning:
fied container (for example, to create a text box at the beginning of page
one).
•
Ending:
(for example, to create a page at the end of a layout).
•
After:
to move the first page of a layout after the fourth page).
•
Before:
to move the last page of a layout before the first page).
•
Replace:
ple, to replace one text box with another text box).
EV EN TS
Events are the actions that an object is capable of performing. In an English
sentence, an event is com parable to a verb and an object is comparable to a
noun. Events are used to tell objects what to do. QuarkXPress uses most of the
standard events defined by Apple.
Used to insert or create an object at the beginning of the speci-
Used to insert or create an object at the end of the specified container
Used to insert or create an object after a specified object (for example,
Used to insert or create an object before the specified object (for example,
Used to replace the specified object with a new object (for exam-
SU IT ES
Groups of events and objects that relate to a similar purpose are arranged
in suites. The Required Suite, Standard Suite, and Miscellaneous Standards
Suite include the events and objects that most Mac OS applications support.
In addition, events and objects specific to QuarkXPress are defined in the
Custom Bleeds Suite, the QuarkCMS Suite, the Layers Suite, the OPI Setup
Record Suite, the QuarkXPress Suite, the QuarkXPress Ancillary Objects Suite,
the Table Suite, the Text Suite, and the Word Filter Suite.
QuarkXPress supports the events and objects in the Required, Standard,
Miscellaneous, and QuarkXPress Suites, as well as objects in the Custom
Bleeds Suite, the CMS Suite, the Layers Suite, the OPI Setup Record Suite,
the QuarkXPress Ancillary Objects Suite, the Table Suite, the Text Suite, and
the Word Filter suite. An object can respond to events from a variety of suites,
and events can apply to objects from a variety of suites. For example, objects
in the QuarkXPress Suite are generally manipulated using events in the
Standard Suite.
RE QU IRED SU ITE
•
Events:
All of the events in the Required Suite are handled by events in the
Standard Suite.
•
Objects:
The Required Suite does not define any objects.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
4
|
SC RI PT IN G OVERVIEW
ST AN DARD SU ITE
•
Events:
The Standard Suite events are common to most applications: duplicate,
close, count, make, data size, delete, exists, get, move, open, print, save, set,
and quit.
•
Objects:
The Standard Suite objects are common to most applications:
application, document, file, insertion point, selection object, and window.
MI SC ELLAN EO US ST AN DAR DS S UIT E
•
Events:
The Miscellaneous Standards Suite events are related to the Clipboard
and other menu-related functions: copy, cut, do script, paste, revert, show,
and select.
•
Objects:
The only objects in the Miscellaneous Suite are those related to menus:
menu and menu item.
CU ST OM BL EE DS SU IT E
•
Events:
Objects:
•
The Custom Bleeds Suite does not define any events.
The custom bleeds setup object encapsulates custom bleeds settings.
The events defined by the Custom Bleeds Suite is only available if Custom
Bleeds XTensions software is running.
CM S SUITE
•
Events:
Objects:
•
The CMS Suite does not define any events.
The print setup record object encapsulates an output setup (for use
in color management).
LA YE RS SU IT E
•
Events:
Objects:
•
The Layers Suite includes the merge event, for merging layers.
The layer object represents a layer. The Layers Suite also adds layerrelated elements and properties to document, generic box, layout space, page,
and table box objects.
OP I SETUP R ECORD SU ITE
•
Events:
Objects:
•
The OPI Setup Record Suite does not define any events.
The OPI setup object encapsulates OPI settings for print output. The OPI
Setup Record Suite also adds the OPI swap object to the picture box object.
The events defined by the OPI Setup Record Suite is only available if OPI
XTensions software is running.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 5
SCRIPTING OV ER VI EW
QU AR KXPRE SS SUIT E
•
Events:
Objects:
•
spec, clipping path, color spec, color system, contour, default document, delimit
item, delimit table, generic box, graphic box, group box, h and j spec, horizontal
guide, image, line box, layout space, master layout space, page, picture box,
project, runaround path, shape path, spread, style spec, text box, text style range,
user box, vertex, vertical guide, and xtension.
QU AR KXPRE SS ANCI LL ARY O BJ ECT S
•
Events:
Objects:
•
for inheritance, returned as records, or data types: base class, box properties,
blend record, character properties, containing box properties, fixed point, fixed
rectangle, font record, frame record, justification record, non containing box
properties, open type style record, paragraph properties, print setup record, rule
record, tab record, text container properties, text path properties, text properties,
and text and paragraph properties.
QU AR KXPRE SS TERM S AND O BJ ECT S
The “Definitions and Examples” section of this document provides definitions
and sample syntax for each event that QuarkXPress supports. The AppleScript
dictionary defines each event and object that QuarkXPress supports. The following objects in the hierarchy are not familiar QuarkXPress terms. Their properties
are defined fully in the AppleScript dictionary.
The QuarkXPress Suite includes two events: coerce and do updates.
The QuarkXPress Suite objects are specific to the application: character
The QuarkXPress Ancillary Objects Suite does not include any events.
The QuarkXPress Ancillary Objects Suite contains objects that are used
• Color systems: the color models that QuarkXPress supports.
• Contour: a continuous path. Shape paths, clipping paths, and runaround paths
are made up of contours. For instance, if you had a Bézier element in the shape
of a bagel, you would have two contours: one contour for the outside shape and
one contour for the inside shape.
• Default document: the object that contains all default layout settings
including colors, style sheets, hyphenation and justification specifications
(H&Js), layout settings specified in the New Layout dialog box, and all
layout-related preferences.
• Delimit item: each character has an associated delimit item that QuarkXPress
uses to determine whether a character should be part of a word.
• Delimit table: a container for 256 “delimit items.”
• Generic box: any type of box on a page. Use generic box if you want to change
the properties of a box in a specific location, regardless of what type of box it is.
• Group box: An item that consists of a group of boxes. A group box can be
either a “true” group, for example, boxes that have been grouped, or it can
be a selection of multiple boxes.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
6
|
SC RI PT IN G OVERVIEW
• Insertion point: The location where new text will be entered; identified by the
text insertion point icon i.
• Master layout: A container for master pages. The master layout allows access to
master pages and master page objects.
• Path: A path is a Bézier element, and can be either a shape path, clipping path,
or a runaround path.
• Text style range: A range of text with a single set of styles specified. Use text
style range for functions such as Find/Change.
• User box: A user box is a box that is created by an XTensions module to serve a
specific purpose.
• Vertex: A vertex is a point on a Bézier line. A vertex is defined by its position,
and can be modified by its anchor point or handles.
TA BL E SUI TE
•
Events:
Objects:
•
The Table Suite does not define any events.
Table column, generic cell, horizontal gridline, graphic cell, picture cell,
table row, table box, text cell, and vertical gridline.
TE XT SUIT E
•
Events:
Objects:
•
The Text Suite does not define any events.
The Text Suite objects are the text-related objects common to most
applications: character, line, paragraph, story, text, text style info, and word.
WO RD FILT ER SUIT E
•
Events:
Objects:
•
The Word Filter Suite events are export and import.
The Word Filter Suite does not define any objects.
The events defined by the Word Filter Suite is only available if the MS-Word
filter is running.
QU AR KXPRE SS OBJE CT HI ER AR CHY
When you create a layout in QuarkXPress, you are working within the
QuarkXPress object hierarchy. At the application level, you set default values
and create layouts. At the layout level, you create pages, spreads, style sheets,
colors, and hyphenation and justification specifications. You then add picture
boxes and images, text boxes and text, and line boxes at the page level.
QU AR KXPRE SS SCRI PT ING C ON TAI NM EN T H IE RARCH Y
OB JE CT LIM IT ATION S
The Apple events implementation in QuarkXPress does not currently support
the following:
• Long-document features: Books, libraries, lists, indexing, and section
page numbers
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 7
SCRIPTING OV ER VI EW
• Text: Editing auxiliary dictionaries and hyphenation exceptions
• Pictures: Editing clipping paths
• Items: Merge/split functions, box creation default settings, and anchored boxes
• Color and printing: Multi-Ink colors, Hexachrome
the PPD Manager
• XTensions Manager and most QuarkXTensions®software distributed by Quark
Apple events are supported by some third-party XTensions software, including
XData and BeyondPress. Future versions of QuarkXPress may support the
objects listed above. This document will be updated and distributed with new
versions of QuarkXPress as necessary.
SCRIPT WRITI NG SY NTAX
To write a script, you need to learn the scripting language of the scripting
application. Scripts combine events, objects, properties, and data in the
order specified by the scripting language. AppleScript syntax is similar to
the English language.
SA MP LE AP PL ESCRI PT SY NT AX
EVENT PROPERTY OBJEC T DATA
set the color of text box 1 to “Red”
set the runaround of picture manual
box 5 to
®
colors, print styles, and
SP AC ES
In AppleScript, you can use the names of all objects and properties as shown
in the AppleScript dictionary. AppleScript is not case-sensitive.
QU OT ATION M ARKS
In AppleScript, you should enclose data in straight quotation marks and use
typographer’s quotation marks as foot and inch marks. For example, to specify
six inches, use “6” rather than "6" or '6'. You can also use a back slash to precede
a straight quotation mark when indicating feet or inches. For example, to
specify six inches, you can use "6\"". The back slash can be used any time you
want to tell AppleScript that the following character is not to be used as a
control character.
OPTIMIZING T HE PE RFORMANCE OF SCRIP TS
These suggestions, and any techniques advocated by your scripting software,
will help you write more efficient scripts.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
8
|
SC RI PT IN G OVERVIEW
PR OC ESS I N QUARK XP RES S
Allow QuarkXPress to do calculations using its own built-in functions, and
minimize context switches between QuarkXPress and the scripting application.
For example, to set the color of all generic boxes to red:
DO
set the color of every generic box to "Red"
DO N’ T
set numberOfBoxes to count of generic boxes
repeat with i from 1 to numberOfBoxes
set color of generic box i to "Red"
end repeat
To change the color of all green generic boxes to red:
DO
set color of every generic box whose color equals "Green" to "Red"
DO N’ T
set numberOfBoxes to count of generic boxes
repeat with i from 1 to numberOfBoxes
if name of color of generic box i equals "Green" then set color of
generic box i to "Red"
end repeat
SP EC IFY I NI TIAL PR OPE RT IE S W HE N PER FO RMING A MAKE E VENT
Use the
make
event to specify initial properties rather than using subsequent
set
events. You can also set multiple properties. In AppleScript, you specify the
initial properties within the make statement.
DO
make picture box at beginning of last page with properties
{rotation:90,color:"Cyan",shade:80}
Set multiple properties:
DO
tell layout space 1 of project 1
set properties of picture box 1 to
{rotation:90,color:"Cyan",shade:80}
end tell
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 9
SCRIPTING OV ER VI EW
DO N’ T
tell page 1 of layout space 1 of project 1
tell picture box 1
set rotation to 90
set color to "Cyan"
set shade to 80
end tell
end tell
CO MP ILE S CR IPTS
Using the
where it is pro cessed completely within the application before anything
appears on-screen.
Add the following lines to AppleScript scripts to have them automatically
compile and execute within QuarkXPress:
script theRealScript
tell application "QuarkXPress"
do
script event sends a compiled script directly to QuarkXPress
--the script goes here
end tell
end script
tell application "QuarkXPress"
do script {theRealScript}
end tell
SCRIPT WRITI NG SA MPLE
To illustrate how scripts interact with QuarkXPress objects, we have dissected
a script that uses a representative sample of the objects that QuarkXPress supports. The breakdown discusses creating objects, specifying initial properties,
and chang ing properties. In addition, the various aspects of the scripting
environment, including suites, events, the object model, the object hierarchy,
and object references, are discussed in the context of the objects in this script.
You can apply similar syntactical constructs to other objects in other scripts.
The sample script, “Layout Construction,” written in AppleScript, illustrates how
Apple events control objects within QuarkXPress. The script sets guides, makes
text and picture boxes, imports text and images, then specifies the properties
of these objects and their elements to produce a final layout.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
10
|
SC RI PT IN G OVERVIEW
THE LAYOUT C ONSTR UCTION SCRIPT
Before reading this section, run the “Layout Construction” AppleScript script to
familiarize yourself with its actions. The script and the files it requires are in
the “Apple Events Scripting” folder within the “Documents” folder inside the
QuarkXPress application folder.
AP PL ESCRI PT SYNT AX : L AY OU T C ON ST RUC TI ON SC RI PT
tell application "QuarkXPress"
activate
try
set thepath to (choose folder with prompt "Choose Sample " &
"Documents folder in Documents:Apple Events Scripting:")
as text
tell default document 1
set oldHeight to page height
set oldWidth to page width
set oldAutoTextBox to automatic text box
set oldGuidesShowing to guides showing
set oldGruidesFront to guides in front
set xDocMeasure to horizontal measure
set yDocMeasure to vertical measure
set page height to "30 cm"
set page width to "34 cm"
set automatic text box to false
set guides showing to true
set guides in front to true
set horizontal measure to centimeters
set vertical measure to centimeters
end tell
make new project at beginning
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 11
SCRIPT WRITI NG S AM PL E
tell default document 1
set page height to oldHeight
set page width to oldWidth
set automatic text box to oldAutoTextBox
set guides showing to oldGuidesShowing
set guides in front to oldGruidesFront
set horizontal measure to xDocMeasure
set vertical measure to yDocMeasure
end tell
tell layout space 1 of project 1
set view scale to fit page in window
end tell
--CREATE GUIDES TO LAYOUT ELEMENTS ON THE PAGE
tell page 1 of layout space 1 of project 1
make horizontal guide at beginning with properties
{position: "3.875 cm"}
make horizontal guide at end with properties
{position: "8.447 cm"}
make horizontal guide at beginning with properties
{position: "27.152 cm"}
make vertical guide at end with properties {position:"2 cm"}
make vertical guide at end with properties
{position:"4.962 cm"}
make vertical guide at end with properties
{position:"18.742 cm"}
make vertical guide at end with properties {position:"32 cm"}
end tell
--CREATE FIRST TEXT BOX
tell page 1 of layout space 1 of project 1
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
12
|
SC RI PT W RI TING SAMPLE
set HeadlineBox to make text box at beginning with properties
{bounds:{"3.875 cm", "4.962 cm", "8 cm", "18.742 cm"}}
tell text box 1
set vertical justification to bottom justified
set color to "none"
end tell
end tell
tell story 1 of HeadlineBox
set contents of it to "Biking Gear"
set font to "Times"
set size of word 1 to 30
set style of word 1 to all caps
set base shift of word 1 to 60
set track of word 1 to 50
set kern of last character of word 1 to -100
set size of word 2 to 120
set color of word 2 to "Blue"
set style of word 2 to italic
set kern of character 1 of word 2 to -5
set kern of character 2 of word 2 to -5
end tell
--CREATE SECOND TEXT BOX
tell page 1 of layout space 1 of project 1
set BodyCopyBox to make text box at end with properties
{bounds:{"8.5 cm", "5 cm", "29.959 cm", "18.472 cm"}}
tell BodyCopyBox
try
set story 1 to alias (thepath & "ASB Text")
on error
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 13
SCRIPT WRITI NG S AM PL E
set story 1 to (choose file with prompt "Please select
end try
set size of story 1 to 11
set leading of every paragraph of story 1 to 43
set justification of every paragraph of story 1 to full
set font of story 1 to "Times"
end tell
tell paragraph 1 of story 1 of text box 2
set drop cap characters to 1
set drop cap lines to 3
set color of character 1 of word 1 to "Blue"
end tell
tell last paragraph of story 1 of text box 2
set color of character 1 of word 1 to "Blue"
the file \"ASB Text.\"" of type {"TEXT"})
set size of character 1 of word 1 to 28
set rule on of rule above to true
set text length of rule above to false
set width of rule above to 0.5
set position of rule above to "1 cm"
set color of rule above to "Cyan"
set shade of rule above to 100
end tell
end tell
--CREATE FIRST PICTURE BOX
tell page 1 of layout space 1 of project 1
make picture box at beginning with properties
{bounds:{"11.886 cm", "21.79 cm", "29.136 cm",
"34.54 cm"}, color:"None"}
tell picture box 1
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
14
|
SC RI PT W RI TING SAMPLE
set rotation to -25
try
set image 1 to alias (thepath & "Shirts.TIFF")
on error
set image 1 to (choose file with prompt "Please select the
file \"Shirts.TIFF.\"" of type {"TIFF"})
end try
tell image 1
set scale to {"115", "115"}
end tell
end tell
end tell
--CREATE SECOND PICTURE BOX
tell page 1 of layout space 1 of project 1
make picture box at beginning with properties {bounds:
{"8.447 cm", "18.742 cm", "14.301 cm", "26.747 cm"},
color:"None", runaround:none runaround}
tell picture box 1
try
set image 1 to alias (thepath & "Helmet.TIFF")
on error
set image 1 to (choose file with prompt "Please select" &
"the file \"Helmet.TIFF\"" of type {"TIFF"})
end try
tell image 1
set scale to {"74", "74"}
set offset to {"0.557 cm", "1.254 cm"}
end tell
end tell
end tell
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 15
SCRIPT WRITI NG S AM PL E
--CREATE THIRD PICTURE BOX
tell page 1 of layout space 1 of project 1
make picture box at end with properties {bounds:
{"8.471 cm", "2 cm", "9.971 cm", "3.5 cm"}, color:"None"}
tell picture box 3
try
set image 1 to alias (thepath & "Glove.TIFF")
on error
set image 1 to (choose file with prompt "Please select the
end try
set bounds of image 1 to exact fit
end tell
duplicate picture box 3 to after picture box 3
tell picture box 4
file \"Glove.TIFF.\"" of type {"TIFF"})
set bounds to {"12.471 cm", "2 cm", "13.971 cm", "3.5 cm"}
end tell
duplicate picture box 4 to after picture box 4
tell picture box 5
set bounds to {"16.471 cm", "2 cm", "17.971 cm", "3.5 cm"}
end tell
duplicate picture box 5 to after picture box 5
tell picture box 6
set bounds to {"20.471 cm", "2 cm", "21.971 cm", "3.5 cm"}
end tell
end tell
--CREATE LINES
tell page 1 of layout space 1 of project 1
make line box at end with properties {left point:
{"0 cm", "21.406 cm"}, right point:{"8 cm", "21.406 cm"}}
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
16
|
SC RI PT W RI TING SAMPLE
tell line box 1
set color to "Magenta"
set width to 3
set style to dotted
end tell
make line box at end
tell line box 2
set left point to {"8 cm", "2 cm"}
set right point to {"8 cm", "32 cm"}
set width to 0.5
end tell
end tell
set guides showing of layout space 1 of project 1 to false
try
save project 1 in (thepath & "Constructed Layout.qxp")
on error
set filePath to (choose file name with prompt "Where would you
like to save the file?" default name "Constructed Layout.qxp")
as string
save project 1 in filePath
end try
beep 2
on error errmsg number errnum
if errnum ≠ -128 then
beep
display dialog errmsg & " [" & errnum & "]" buttons {"OK"}
default button 1 with icon stop
end if
-- For compatibility with non-US English operating systems
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 17
SCRIPT WRITI NG S AM PL E
return
end try
end tell
ABOUT THE SC RIPT BREAKDOWN
This section first discusses how to direct a script to QuarkXPress. The script is
then divided into the steps a user would perform when constructing a layout.
The steps include creating a new layout, creating a text box, importing text, formatting the text, and so on. The script syntax is then displayed in the Courier
font. Following the syntax is a concept line that translates the scripting language
into actions in QuarkXPress. The events, objects, and properties set in the script
are then analyzed line by line. The script breakdown follows this format:
A ST EP IN T HE LA YO UT CO NS TRU CT IO N P RO CESS
code
CO NC EPTS
The code above is described in terms of actions in QuarkXPress.
Each event, object, or property is discussed line by line.
BREAKDOWN OF THE LAYOUT CONSTRUCTIO N SCRIPT
LO CA TE TH E TERMI NO LOG Y FO R Q UA RK XPR ES S OBJ EC TS
AN D E VENTS
tell application "QuarkXPress"
CO NC EPTS
This statement specifies the location of QuarkXPress terminology.
• Use the
tell
statement to identify which object is being addressed. Using this
statement is necessary because certain actions and properties only apply to
specific objects.
• In the remainder of this section, the previous format will be used to reference
the location of items in AppleScript. The following formats will be used to
reference the location of items:
application "QuarkXPress"
DE CL ARE T HE VARI AB LES C ON CEP TS
This statement declares local variables for the script.
Although it is not essential to declare local variables, it makes scripts much safer.
Making variables local ensures that QuarkXPress table entries will not be altered
inadvertently if they have the same name as a variable used in a script.
Declaring local variables is not required in AppleScript.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
18
|
tell layout space 1 of project 1 of
.
SC RI PT W RI TING SAMPLE
AC TI VATE QU ARKXP RE SS
activate
CO NC EPTS
This statement is similar to choosing QuarkXPress from the QuarkXPress
menu.
Activate
is a standard command used with AppleScript.
ES TA BLISH T HE PA TH
set thepath to (Choose folder with prompt "Select the Sample
Documents folder inside the Apple Events Scripting folder of
your QuarkXPress folder:") as text
CO NC EPTS
This statement establishes a path for sample text and image files that will be
used later in the script.
• The AppleScript example uses the choose folder command, which displays an
Open dialog box that you can use to specify the desired folder.
• This statement gives the variable thepath a string value that is the path to the
location of the text and image files.
SA VE CURR EN T LAY OU T’S D EF AUL T SP ECI FI CA TIO NS
tell default document 1
set oldHeight to page height
set oldWidth to page width
set oldAutoTextBox to automatic text box
set oldGuidesShowing to guides showing
set oldGuidePos to guides in front
set xDocMeasure to horizontal measure
set yDocMeasure to vertical measure
CO NC EPTS
• The
tell
statement references the current default document by index [1].
(The default document is the object that contains all default layout settings
including colors, style sheets, hyphenation and justification settings, layout
settings specified in the New Layout dialog box, and all preferences.)
• AppleScript does not require that get be specified; get is assumed if it is
not specified.
A GUIDE TO A PP LE E VE NT S SC RI PT IN G | 19
SCRIPT WRITI NG S AM PL E
SE T DEFAU LT SPEC IF ICA TI ON S F OR A NE W LAYOU T
set page height to "30 cm"
set page width to "34 cm"
set automatic text box to false
set guides showing to true
set guides in front to true
set horizontal measure to centimeters
set vertical measure to centimeters
end tell
CO NC EPTS
The first three set statements are similar to setting default specifications in
the New Layout dialog box. The next set statement is similar to choosing
Show Guides from the View menu. The last three statements are settings
in the General pane of the Preferences dialog box.
• The first two
• The third
box, depending on the Boolean operator. If the Boolean operator is
layout will not have an automatic text box. If the Boolean operator is
set
events specify the page height and page width properties.
set
event determines whether the layout will have an automatic text
false
, the
true
it will.
• The fourth
ing on the Boolean operator. If the Boolean operator is
display. If the Boolean operator is
• The fifth
page elements. The
set
event determines whether the layout will display guides, depend-
true
, all guides will
false
, all guides will be hidden.
set
event determines whether the guides will display in front of the
true
Boolean operator indicates that the guides will display
in front.
set
• The last two
events specify the default horizontal and vertical measurement
system as centimeters.
CR EA TE A NE W LAY OU T W IT H DEF AU LT SP EC IFICA TI ONS
make new project at end
CO NC EPTS
This
make
event is similar to clicking OK in the New Layout dialog box.
• The first parameter, layout, refers to the object that will be created.
• You can make an object at any insertion point: beginning, ending, after, before,
or replace. However, layouts are always created at the end.
,
A GUIDE TO A PP LE E VE NT S SC RI PT IN G
20
|
Loading...