Quark QuarkXPress - 2017 Apple Events Scripting

A Guide to

Apple Events Scripting

A Guide to Apple Events Scripting

Introduction	1
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
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

II |

TABLE OF CONTENTS

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 CONTENTS

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 |

TABLE OF CONTENTS

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 CONTENTS

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 |

TABLE OF CONTENTS

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 CONTENTS

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 |

TABLE OF CONTENTS

INTRODUCTION

This guide provides information about Apple® events scripting with QuarkXPress®. Apple event properties that are specific to East Asian features are identified as such.

ABOUT THIS GUIDE

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: www.quark.com/service/forums/, and e-mail: scriptsupport@quark.com).

To learn more about Apple events scripting, you may want to purchase a third-party book such as The AppleScript Handbook, AppleScript for Dummies, or AppleScripting QuarkXPress. Many other third-party books exist, some of which include scripting software. You can also visit www.apple.com to ﬁnd electronic resources and URLs for Apple events scripting.

WHAT YOU NEED

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™, or Pascal.

To run AppleScript scripts that communicate with QuarkXPress, you must have Script XTensions® software loaded. For information about this software, refer to A Guide to QuarkXPress 2016.

| IX

INTRODUCTION

Script XTensions software is not required to run scripts that communicate with versions of QuarkXPress prior to QuarkXPress 5.0.

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.

WHAT THIS GUIDE PROVIDES

This guide provides background information on Apple events, an analysis of a sample script, and speciﬁc 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 OVERVIEW

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

SCRIPTS

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 deﬁned in the Apple Events Registry.

SYSTEM-LEVEL SCRIPTING

Scripting software is developed speciﬁcally 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 |

INTRODUCTION

You can do everything from simple formatting tasks to complex database publishing with scripts. For example, you might have a script that alphabetizes 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 MODEL

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 speciﬁc capabilities. For example, a text box can be moved, resized, copied, and linked to other boxes. A text box has item speciﬁcations that can be changed (such as background color, number of columns, and text inset) and it can contain formatted text.

OBJECTS

An object is a distinct item (in an application) that can be manipulated by an Apple event. Objects are deﬁned 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 speciﬁc 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 ﬁle 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 APPLE EVENTS SCRIPTING | 1

ABOUT THIS GUIDE

OBJECT HIERARCHY

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 speciﬁc 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.

OBJECT REFERENCES

An Apple events message must identify a speciﬁc object in an application to communicate. Objects are identiﬁed by a reference. For example, the message might reference the second text box on the ﬁrst page. The reference ﬁrst identiﬁes the container (the page) enclosing the object (the text box) that you’re specifying. It then uses a reference form to separate a speciﬁc object (the second text box) from all possible objects in the container.

REFERENCE FORMS

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 ﬁrst 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).

2 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPTING OVERVIEW

•Range: used to identify a range of objects (for example, text boxes three through ﬁve).

•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 ﬁrst text box with a red background).

A GUIDE TO APPLE EVENTS SCRIPTING | 3

SCRIPTING OVERVIEW

INSERTION POINTS IN THE HIERARCHY

An insertion point speciﬁes 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: Used to insert or create an object at the beginning of the speciﬁed container (for example, to create a text box at the beginning of page one).

•Ending: Used to insert or create an object at the end of the speciﬁed container (for example, to create a page at the end of a layout).

•After: Used to insert or create an object after a speciﬁed object (for example, to move the ﬁrst page of a layout after the fourth page).

•Before: Used to insert or create an object before the speciﬁed object (for example, to move the last page of a layout before the ﬁrst page).

•Replace: Used to replace the speciﬁed object with a new object (for example, to replace one text box with another text box).

EVENTS

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 deﬁned by Apple.

SUITES

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 speciﬁc to QuarkXPress are deﬁned 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.

REQUIRED SUITE

•Events: All of the events in the Required Suite are handled by events in the Standard Suite.

•Objects: The Required Suite does not deﬁne any objects.

4 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPTING OVERVIEW

STANDARD SUITE

•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, ﬁle, insertion point, selection object, and window.

MISCELLANEOUS STANDARDS SUITE

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

CUSTOM BLEEDS SUITE

•Events: The Custom Bleeds Suite does not deﬁne any events.

•Objects: The custom bleeds setup object encapsulates custom bleeds settings.

The events deﬁned by the Custom Bleeds Suite is only available if Custom Bleeds XTensions software is running.

CMS SUITE

•Events: The CMS Suite does not deﬁne any events.

•Objects: The print setup record object encapsulates an output setup (for use in color management).

LAYERS SUITE

•Events: The Layers Suite includes the merge event, for merging layers.

•Objects: 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.

OPI SETUP RECORDSUITE

•Events: The OPI Setup Record Suite does not deﬁne any events.

•Objects: 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 deﬁned by the OPI Setup Record Suite is only available if OPI XTensions software is running.

A GUIDE TO APPLE EVENTS SCRIPTING | 5

SCRIPTING OVERVIEW

QUARKXPRESS SUITE

•Events: The QuarkXPress Suite includes two events: coerce and do updates.

•Objects: The QuarkXPress Suite objects are speciﬁc to the application: character 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.

QUARKXPRESS ANCILLARY OBJECTS

•Events: The QuarkXPress Ancillary Objects Suite does not include any events.

•Objects: The QuarkXPress Ancillary Objects Suite contains objects that are used for inheritance, returned as records, or data types: base class, box properties, blend record, character properties, containing box properties, ﬁxed point, ﬁxed rectangle, font record, frame record, justiﬁcation 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.

QUARKXPRESS TERMS AND OBJECTS

The “Deﬁnitions and Examples” section of this document provides deﬁnitions and sample syntax for each event that QuarkXPress supports. The AppleScript dictionary deﬁnes each event and object that QuarkXPress supports. The following objects in the hierarchy are not familiar QuarkXPress terms. Their properties are deﬁned fully in the AppleScript dictionary.

•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 justiﬁcation speciﬁcations

(H&Js), layout settings speciﬁed 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 speciﬁc 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.

6 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPTING OVERVIEW

•Insertion point: The location where new text will be entered; identiﬁed 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 speciﬁed. 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 speciﬁc purpose.

•Vertex: A vertex is a point on a Bézier line. A vertex is deﬁned by its position, and can be modiﬁed by its anchor point or handles.

TABLE SUITE

•Events: The Table Suite does not deﬁne any events.

•Objects: Table column, generic cell, horizontal gridline, graphic cell, picture cell, table row, table box, text cell, and vertical gridline.

TEXT SUITE

•Events: The Text Suite does not deﬁne any events.

•Objects: The Text Suite objects are the text-related objects common to most applications: character, line, paragraph, story, text, text style info, and word.

WORD FILTER SUITE

•Events: The Word Filter Suite events are export and import.

•Objects: The Word Filter Suite does not deﬁne any objects.

The events deﬁned by the Word Filter Suite is only available if the MS-Word ﬁlter is running.

QUARKXPRESS OBJECT HIERARCHY

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 justiﬁcation speciﬁcations. You then add picture boxes and images, text boxes and text, and line boxes at the page level.

QUARKXPRESS SCRIPTING CONTAINMENT HIERARCHY OBJECT LIMITATIONS

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 APPLE EVENTS SCRIPTING | 7

SCRIPTING OVERVIEW

•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® colors, print styles, and 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 WRITING SYNTAX

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 speciﬁed by the scripting language. AppleScript syntax is similar to the English language.

SAMPLE APPLESCRIPT SYNTAX
EVENT	PROPERTY	OBJECT	DATA

set	the color of	text box 1 to	“Red”

set	the runaround of	picture	manual
		box 5 to

SPACES

In AppleScript, you can use the names of all objects and properties as shown in the AppleScript dictionary. AppleScript is not case-sensitive.

QUOTATION MARKS

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 THE PERFORMANCE OF SCRIPTS

These suggestions, and any techniques advocated by your scripting software, will help you write more efﬁcient scripts.

8 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPTING OVERVIEW

PROCESS IN QUARKXPRESS

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:

DOset the color of every generic box to "Red"

DON’Tset 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:

DOset color of every generic box whose color equals "Green" to "Red"

DON’Tset 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

SPECIFYmakeINITIAL PROPERTIES WHEN PERFORMING A MAKE EVENTset

Use the event to specify initial properties rather than using subsequent events. You can also set multiple properties. In AppleScript, you specify the initial properties within the make statement.

DOmake picture box at beginning of last page with properties {rotation:90,color:"Cyan",shade:80}

Set multiple properties:

DOtell layout space 1 of project 1 set properties of picture box 1 to {rotation:90,color:"Cyan",shade:80} end tell

A GUIDE TO APPLE EVENTS SCRIPTING | 9

SCRIPTING OVERVIEW

tellDON’Tpage 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

COMPILEdoSCRIPTS

Using the script event sends a compiled script directly to QuarkXPress 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" --the script goes here

end tell end script

tell application "QuarkXPress" do script {theRealScript}

end tell

SCRIPT WRITING SAMPLE

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 speciﬁes the properties of these objects and their elements to produce a ﬁnal layout.

10 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPTING OVERVIEW

THE LAYOUT CONSTRUCTION SCRIPT

Before reading this section, run the “Layout Construction” AppleScript script to familiarize yourself with its actions. The script and the ﬁles it requires are in the “Apple Events Scripting” folder within the “Documents” folder inside the QuarkXPress application folder.

APPLESCRIPTtell applicationSYNTAX:"QuarkXPress"LAYOUT CONSTRUCTION SCRIPT 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 APPLE EVENTS SCRIPTING | 11

SCRIPT WRITING SAMPLE

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 ﬁt 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

12 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING 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 justiﬁcation to bottom justiﬁed 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

tryset story 1 to alias (thepath & "ASB Text") on error

A GUIDE TO APPLE EVENTS SCRIPTING | 13

SCRIPT WRITING SAMPLE

set story 1 to (choose ﬁle with prompt "Please select the ﬁle \"ASB Text.\"" of type {"TEXT"})

end try

set size of story 1 to 11

set leading of every paragraph of story 1 to 43

set justiﬁcation 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" 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

14 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

set rotation to -25

tryset image 1 to alias (thepath & "Shirts.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select the ﬁle \"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

tryset image 1 to alias (thepath & "Helmet.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select" & end try "the ﬁle \"Helmet.TIFF\"" of type {"TIFF"})

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 APPLE EVENTS SCRIPTING | 15

SCRIPT WRITING SAMPLE

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

tryset image 1 to alias (thepath & "Glove.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select the ﬁle \"Glove.TIFF.\"" of type {"TIFF"})

end try

set bounds of image 1 to exact ﬁt end tell

duplicate picture box 3 to after picture box 3 tell picture box 4

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"}}

16 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING 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 ﬁlePath to (choose ﬁle name with prompt "Where would you like to save the ﬁle?" default name "Constructed Layout.qxp") as string

save project 1 in ﬁlePath 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 APPLE EVENTS SCRIPTING | 17

SCRIPT WRITING SAMPLE

return end try

end tell

ABOUT THE SCRIPT BREAKDOWN

This section ﬁrst 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:

codeA STEP IN THE LAYOUT CONSTRUCTION PROCESS

CONCEPTS

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 CONSTRUCTION SCRIPT

LOCATE THE TERMINOLOGY FOR QUARKXPRESS OBJECTS tellAND applicationEVENTS "QuarkXPress"

CONCEPTS

This statement speciﬁes 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 speciﬁc objects.

• In the remainder of this section, the previous format will be used to reference

the location of items in AppleScripttell. Thelayoutfollowingspaceformats1 of projectwill be used1 ofto applicationreference the "QuarkXPress"loc tion of items:

DECLARE THE VARIABLES CONCEPTS

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.

18 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

ACTIVATEactivate QUARKXPRESS

CONCEPTS

This statement is similar to choosing QuarkXPress from the QuarkXPress

menu.

Activate is a standard command used with AppleScript.

ESTABLISHset thepathTHEto (ChoosePATH folder with prompt "Select the Sample Documents folder inside the Apple Events Scripting folder of your QuarkXPress folder:") as text

CONCEPTS

This statement establishes a path for sample text and image ﬁles 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 ﬁles.

SAVEtell defaultCURRENTdocumentLAYOUT’S1 DEFAULT SPECIFICATIONS 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

CONCEPTStell

• The 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 justiﬁcation settings, layout settings speciﬁed in the New Layout dialog box, and all preferences.)

•AppleScript does not require that get be speciﬁed; get is assumed if it is not speciﬁed.

A GUIDE TO APPLE EVENTS SCRIPTING | 19

it will.

SCRIPT WRITING SAMPLE

SETsetDEFAULTpage heightSPECIFICATIONSto "30 cm" FOR A NEW LAYOUT 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

CONCEPTS

The ﬁrst three set statements are similar to setting default speciﬁcations 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 ﬁrst two set events specify the page height and page width properties.

•The third set event determines whether the layout will have an automaticfalse text box, depending on the Boolean operator. If the Boolean operator is true, the layout will not have an automatic text box. If the Boolean operator is ,

• The fourth set event determines whether the layout will displaytrue guides, depend-

ing on the Boolean operator. If thefalseBoolean operator is , all guides will display. If the Boolean operator is , all guides will be hidden.

• The ﬁfth set event truedet rmines whether the guides will display in front of the page elements. The Boolean operator indicates that the guides will display

•The last two set events specify the default horizontal and vertical measurement

system as centimeters. makeCREATEnew AprojectNEW LAYOUTat end WITH DEFAULT SPECIFICATIONSin front.

CONCEPTSmake

This event is similar to clicking OK in the New Layout dialog box.

•The ﬁrst 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.

20 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

SETtellTHElayoutVIEWspaceSCALE1

set view scale to ﬁt page in window end tell

CONCEPTS

The lines above are similar to choosing Fit in Window from the View menu for the active layout.

•The tell statement references the left-most layout space.

•The set event changes the view scale property to the data ﬁt page in window.

The view scale property100can be a percentage or speciﬁc view. For example, to specifythumbnails100% view, use for the second parameter. To specify thumbnails, use for the second parameter.

CREATEtell pageGUIDES1 of layout space 1 of project 1

make horizontal guide at beginning with properties {position:"4.218 cm"}

make horizontal guide at end with properties {position:"8.447 cm"} make horizontal guide at end 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

CONCEPTSmake

The events above simulate clicking the horizontal and vertical rulers to

create guides, and then dragging the guides into position.

•The tell statement references the layout by index [1]. The index value [1] refers to the left-most layout space.

•Each make event makes a horizontal guide or vertical guide. The guides are created with the properties speciﬁed in the properties record.

•The ﬁrst guide is created at the beginning of page 1 in the object hierarchy according to the fourth parameter. Subsequent guides are created at the end of page 1.

A GUIDE TO APPLE EVENTS SCRIPTING | 21

SCRIPT WRITING SAMPLE

tellCREATEpageTHE1 ofFIRSTlayoutTEXTspaceBOX1

make text box at beginning with properties {bounds:{"2 cm", "5 cm", "8 cm", "19 cm"}}

CONCEPTS

The lines above are similar to creating a text box with the rectangular Text Box

tool, and then sizing and positioning it using the Measurements palette.

• The tell statement references the ﬁrst page of the left-most layout space; both are referenced by index [1].

• If you want toshowsee anshow(it)object after it is created (and while the script is running), add the line or . This places the current object in the upper-left

corner of the layout window.

tellENTERtextTHEboxHEADLINE1 INTO A TEXT BOX

set vertical justiﬁcation to bottom justiﬁed set color to "None"

end tell

tell story 1 of text box 1 of page 1 of layout space 1 set contents of it to "Biking Gear"

end tell

CONCEPTS

The statements above are similar to specifying a vertical alignment and background color in the Text tab of the Modify dialog box, and then entering “Biking Gear” in the text box.

•The tell statement references the ﬁrst text box by index [1].

•The next two set events change the vertical justiﬁcation to bottom and the background color to None.

•The tell statement references the story in the active text box; both are referenced by index [1]. (Only one story is possible per text box or chain of

linked text boxes.)

set it it

• Thewithevent speciﬁes ( refers to the story, the last object referenced in the statement). The text “Biking Gear” is entered into the text box. It is then formatted with properties deﬁned in the Normal style sheet for the default layout.

22 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

FORMATset fontTHEto HEADLINE"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

CONCEPTS

The set statements above are comparable to the Font, Size, Type Style, Color, Baseline Shift, Track, and Kern commands in the Style menu.

•The ﬁrst set event changes the font for the story to Times.

•The next four set events reference the ﬁrst word by index [1]. The size, text style, baseline shift, and track properties of the word “Biking” are changed.

•The next set event references the last character of the ﬁrst word; the character is referenced by relative position. The kern property is changed to –100. (To kern the space between two words, reference the last character of the ﬁrst word.)

•The next three set events reference the second word by index [2]. The size, color, and type style properties of the word “Gear” are changed.

•The last two set events reference the ﬁrst and second character of the second word; all are referenced by index. The kern property of each character is changed to –5. (To kern a pair of characters, you only need to reference the ﬁrst character.)

CREATEtell pageTHE1 ofSECONDlayout TEXTspace BOX1

make text box at end with properties

{bounds:{"8.5 cm", "5 cm", "29.959 cm", "18.472 cm"}} end tell

A GUIDE TO APPLE EVENTS SCRIPTING | 23

SCRIPT WRITING SAMPLE

CONCEPTS

The lines above are similar to creating a text box with the rectangular Text Box tool, and then sizing and positioning it using the Measurements palette.

tellLOCATEtextANDbox IMPORT2 A TEXT FILE try

set story 1 to alias (thepath & "ASB Text") on error

set story 1 to (choose ﬁle with prompt "Please select the ﬁle \"ASB Text\"" of type {"TEXT"})

end try end tell

CONCEPTS

The statements above are similar to locating and importing a text ﬁle in the Get Text dialog box.

• The try stathepathement looks for the “ASB Text” ﬁle in the location previously deﬁned by (see the “Establish the path” portion near the beginning

of the “Breakdown of the Layout Constructionset Script” section of this document). If the ﬁle exists in this location, the event imports the “ASB Text” ﬁle,

replacing the story in the text box.

• If “ASB Text” doesonoterrorexist in the location deﬁned by thepath, the scriptthepathwill continue with the statement. (The ﬁle will only be located bythepath if your hard drive and folders are named the same as those deﬁned in .)

•The ﬁrst parameter is a message to the user shown at the bottom of the dialog box, “Open the ﬁle named ‘ASB Text.’” The second parameter stores the path to the text ﬁle in an address — this path is used to import the text ﬁle. The third parameter is the signature for a text ﬁle (ﬁle type). Once the user locates the text ﬁle and clicks OK, the set event imports the text.

•If you want to open a QuarkXPress layout using the getFileDialog script, the signature would be “XDOC.” This limits the displayed ﬁles to QuarkXPress layouts. This is an optional parameter.

FORMATset sizeTHEof BODYstory 1COPYto 11 set leading of story 1 to 43

set justiﬁcation of story 1 to fully justiﬁed set font of story 1 to "Times"

end tell

24 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

CONCEPTS

The set statements above are comparable to choosing Font, Size, Leading, and Alignment from the Style menu.

The four set events reference the entire story by index [1]. The font, size, leading, and justiﬁcation properties of the story are set.

CREATEtell paragraphA COLORED1 of storyDROP1CAPof 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

CONCEPTS

The statements above are similar to checking Drop Cap in the Formats tab of the Paragraph Attributes dialog box. The color Blue is then applied to the drop cap character.

•The tell statement references the ﬁrst paragraph of the story in the second text box; the objects are all referenced by index.

•The ﬁrst setsetvent speciﬁes that the ﬁrst character will be a drop cap. The second event speciﬁes that it will be a three-line drop cap.

set

•The third

the ﬁrst word; both are referenced by index [1]. The color property is changed to Blue. event references the drop cap, which is the ﬁrst character of

CREATEtell lastANparagraphINITIAL CAPof story 1 of text box 2 set color of character 1 of word 1 to "Blue" set size of character 1 of word 1 to 28

CONCEPTS

The lines above are similar to creating a decorative initial cap with local formatting.

•The tell statement references the last paragraph of story in the second text box. The story and text box are referenced by index; the paragraph is referenced by relative position.

•The two set statements reference the ﬁrst character of the ﬁrst word; they are referenced by index. The color property is changed to Blue and the size property is changed to 28.

A GUIDE TO APPLE EVENTS SCRIPTING | 25

SCRIPT WRITING SAMPLE

SPECIFYset ruleA RULEon ofABOVErule 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

CONCEPTS

The set events above are comparable to settings in the expanded Rules tab of the Paragraph Attributes dialog box.

• The ﬁrst set event uses a Boolean operatortrueto determine if the paragraph’s rule above will be turned on (rule on). The Boolean operator indicates that the paragraph will have a rule above it.

• The second set event uses falsea Boolean operator to determine if the rule will match the text length. The Boolean operator indicates that it will not

match the length of the text. The rule will extend the width of the text box

•The last four set events specify the width, position, color, and shade properties of the rule.(minus any deﬁned text inset).

tellCREATEpageTHE1 ofFIRSTlayoutPICTUREspace BOX1 of project 1 make picture box at beginning with properties

{bounds:{"10.386 cm", "20.758 cm", "27.636 cm","33.508 cm"}, color:"None"}

CONCEPTS

The lines above are similar to creating a picture box, sizing and positioning it, and then specifying a background color as you would in the Picture tab of the Modify dialog box.

The tell statement references the ﬁrst page of the left-most layout; both are referenced by index [1].

26 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

IMPORTtell pictureTHE FIRSTbox PICTURE1 set rotation to -25 try

set image 1 to alias (thepath & "Shirts.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select the ﬁle \'Shirts.TIFF\'." of type {"TIFF"})

end try tell image 1

set scale to {115, 115} end tell

end tell end tell

CONCEPTS

The statements above are similar to locating and importing an image ﬁle in the Get Picture dialog box (File menu).

•The with statement references the ﬁrst picture box by index [1].

•The ﬁrst set event speciﬁes the rotation property of the picture box.

•The try stathepathement looks for the “Shirts.tiff” ﬁle in the locationset previously deﬁned by . If the ﬁle exists in this location, the event speciﬁes

“Shirts.tiff” as the image in the picture box. (A picture box can only have

one image.)

• If “Shirts.tiff” doesonoterrorexist in the location deﬁned by thepath, the script will continue with the statement. This statement handles error conditions by providing another set of instructions if an error occurs.

•The ﬁrst string is a message to the user shown at the bottom of the dialog box, “Open the image named ‘Shirts.tiff.’” Once the user locates the image ﬁle and clicks OK, the set event imports the image.

•The second tell statement references the image by index [1].

CREATEtell pageTHE1 ofSECONDlayout PICTUREspace 1 ofBOXprojectAND IMPORT1 A PICTURE make picture box at end with properties

{bounds:{"8.471 cm", "2 cm", "9.971 cm", "3.5 cm"}, color:"None"} tell picture box 2

try

A GUIDE TO APPLE EVENTS SCRIPTING | 27

“Glove.tiff” as the image in the second picture box.

SCRIPT WRITING SAMPLE

set image 1 to alias (thepath & "Glove.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select the ﬁle \"Glove.TIFF\"." of type {"TIFF"})

end try

set bounds of image 1 to exact ﬁt end tell

CONCEPTS

The ﬁrst seven lines above are similar to creating a picture box, sizing and positioning it, and then specifying a background color as you would in the Picture tab of the Modify dialog box. The last six statements are similar to locating and importing an image ﬁle in the Get Picture dialog box.

•The tell statement references the ﬁrst page of the active layout; both are referenced by index [1].

•The make event makes a picture box using the speciﬁed properties.

•The tell statement references the second picture box by index [2].

•The try stathepathement looks for the “Glove.tiff” ﬁle in the locationset previously deﬁned by . If the ﬁle exists in this location, the event speciﬁes

• If “Glove.tiff” doesonoterrorexist in the location deﬁned by thepath, the script will continue with the statement. This statement handles error conditions by providing another set of instructions if an error occurs.

•The ﬁrst string is a message to the user shown at the bottom of the dialog box,

“Please select thesetﬁle ‘Glove.tiff.’” Once the user locates the image ﬁle and clicks OK, the event imports the image.

set

• The last	event references	the image by index [1]. The bounds property of
the image is set to exact ﬁt.

CREATEduplicateANDpicturePOSITIONbox COPIES2 to afterOF pictureTHE PICTUREbox 2 BOX tell picture box 3

set bounds to {"12.471 cm", "2 cm", "13.971 cm", "3.5 cm"} end tell

duplicate picture box 2 to after picture box 3 tell picture box 4

set bounds to {"16.471 cm", "2 cm", "17.971 cm", "3.5 cm"} end tell

28 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

duplicate picture box 2 to after picture box 4 tell picture box 5

set bounds to {"20.471 cm", "2 cm", "21.971 cm", "3.5 cm"} end tell

end tell

CONCEPTSduplicate set

The and events above are similar to using the Step and

Repeat feature.

• The ﬁrst duplicate event references the second picture box by index [2]. A copy of the picture box is placed after the second picture box.

• The ﬁrst set statement sets numerical values for the picture box boundaries. The four parameters indicate how far from the top-left corner of the layout page the top, left, bottom, and right sides of the box will be positioned.

• The following lines use the object hierarchy to duplicate picture box 2 after picture box 3, then after picture box 4. Each new picture box is referenced by index and positioned.

Create the third picture box and import a picture tell page 1 of layout space 1 of project 1

make picture box at end with properties

{bounds:{"6.875 cm", "18.425 cm", "12.729 cm", "26.4 cm"}, color:"None"}

tell picture box 6 try

set image 1 to alias (thepath & "Helmet.TIFF") on error

set image 1 to (choose ﬁle with prompt "Please select the ﬁle \'Helmet.TIFF\'." of type {"TIFF"})

end try tell image 1

set scale to {70, 70}

set offset to {"0.557 cm", "1.254 cm"} end tell

end tell end tell

A GUIDE TO APPLE EVENTS SCRIPTING | 29

“Helmet.tiff” as the image in the second picture box.

SCRIPT WRITING SAMPLE

CONCEPTS

The statements above are similar to creating asetpicture box and importing a picture. The properties are then speciﬁed with events.

•The tell statement references the ﬁrst page of the left-most layout; both are referenced by index [1].

•The make event makes a picture box using the speciﬁed properties.

•The second tell statement references the third picture box by index [3].

•The four parameters indicate how far from the top-left corner of the layout page the top, left, bottom, and right sides of the box will be positioned.

•makeThe background color property of the picture box is set to None in the statement.

•The try stathepathement looks for the “Helmet.tiff” ﬁle in the locationset previously deﬁned by . If the ﬁle exists in this location, the event speciﬁes

• If “Helmet.tiff” doesonnoterrorexist in the location deﬁned by thepath, the script will continue with the statement. This statement handles error conditions by providing another set of instructions if an error occurs.

•The ﬁrst string is a message to the user shown at the bottom of the dialog box,

“Please select thsetﬁle ‘Helmet.tiff.’” Once the user locates the image ﬁle and clicks OK, the event imports the image.

set set

• The third	event sets the scale property of the image to	70%. The last
event sets the offset property of the image in centimeters.

tellCREATEpageA 1VERTICALof layoutLINEspace 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"}} tell line box 1

set color to "Magenta" set width to 3

set style to dotted end tell

30 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

CONCEPTS

The statements above are similar to creating and positioning a vertical line with the Orthogonal Line tool + and choosing Color, Width, and Line

Style from the Style menu.

• The "tell" statement references the ﬁrst page of the left-most layout; both are referenced by index [1].

• The make event makes a line box with the speciﬁed settings and in the speciﬁed location, and speciﬁes the left point and right point of the line in centimeters.

CREATEmake lineA HORIZONTALbox at end LINE

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

CONCEPTS

The statements above are similar to creating and positioning a horizontal line with the Orthogonal Line tool + and choosing a Width from the Style

menu.

• The make event makes a line box with the speciﬁed settings and in the speciﬁed location.

• The next two set events specify the left point and right point of the line in centimeters.

• The last set event sets the line width property of the line box to “0.5.” Line widths are set according to points, the default line measurement system in QuarkXPress.

HIDEset guidesGUIDESshowingAND SAVEof layoutTHE LAYOUTspace 1 to false save project 1 in (thepath & "Constructed Layout")

CONCEPTS

The scripts above simulate choosing Hide Guides from the View menu

and Save As from the File menu.

• The ﬁrst set event hides the guides by setting guides showing to false.

• The save event saves the project in thepath with the name “Constructed Layout.”

A GUIDE TO APPLE EVENTS SCRIPTING | 31

SCRIPT WRITING SAMPLE

tellRESETdefaultDEFAULTdocumentSPECIFICATIONS1 FOR FUTURE LAYOUTS 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 oldGuidePos

set horizontal measure to xDocMeasure set vertical measure to yDocMeasure

end tell end tell

CONCEPTSset

The statements above replace the layout default speciﬁcations with your original speciﬁcations.

•The tell statement references the current default document by index [1].

•Each set statement speciﬁes a property of the default document according

to the localoldHeightvar able. For example, the page height property is speciﬁed as the variable . The original page size, automatic text box setting, guide

display, the guide locations, and the default measurement system are reset.

DEFINITIONS AND EXAMPLES — APPLE EVENTS TERMINOLOGY

This section provides AppleScript deﬁnitions and examples for object references, insertion points, and each event that QuarkXPress supports.

Once you are familiar with the scripting language’s syntax, you should be able to write scripts for QuarkXPress by referring to the information in the AppleScript dictionary.

This section also includes deﬁnitions of object reference forms and insertion points, including descriptions of their usage and examples in AppleScript. The examples are taken from various scripts and are shown out of context.

32 | A GUIDE TO APPLE EVENTS SCRIPTING

SCRIPT WRITING SAMPLE

FORMAT

Each event is listed with a description of its usage, a prototype in AppleScript, and any applicable possible values and results. The terms and events are shown in the following format:

TERM OR EVENT

Usage: description of when to use this term or event.

AppleScript prototype parameters in italics

Possible values: variable options

Result: result (for example, integer, text string, and so on)

OBJECT REFERENCE FORMS

To communicate, an Apple event message must reference a speciﬁc object in an application. The reference ﬁrst identiﬁes the container enclosing the object you’re specifying. It then uses a reference form to separate a speciﬁc object from all possible objects in the container. The reference form can be deﬁned by index, ID, name, range, relative position, or test.

INDEX

Usage: to identify ordered elements in a container with an integer number. set the kern of character 1 of word 2 to -14

Usage: to identify objects that have a unique ID. set color of text box id 7 to "Red"

NAME

Usage: to identify named objects with a text string.

set runaround of picture box "Pear" to manual runaround

RANGE

Usage: to identify a range of objects.

set color of words 2 through 5 to "Cyan"

RELATIVE POSITION

Usage: to identify objects that are before or after other objects.

set the rotation of the picture box after picture box 2 to 45

TEST

Usage: to identify objects that meet certain conditions.

set the color of (every word whose color = "Red") to "Blue"

A GUIDE TO APPLE EVENTS SCRIPTING | 33

DEFINITIONS AND EXAMPLES — APPLE EVENTS TERMINOLOGY

INSERTION POINTS IN THE HIERARCHY

An insertion point speciﬁes where you want to place an object within the container hierarchy. As you create and insert objects in the hierarchy, the index reference form for existing objects may change.

AFTER

Usage: to insert or create an object after a speciﬁedafter object (the speciﬁed object will not be the container). For example, use to move the ﬁrst paragraph

in a story so that it follows the seventh paragraph. move paragraph 1 to after paragraph 7

BEFORE

Usage: to insert or create an object before the speciﬁed object (the speciﬁed object will not be the container). For example, use “before” to paste a copy of

the ﬁfth word before the ﬁrst word in a sentence. duplicate word 5 to before word 1

BEGINNING

Usage: to insert or create an object at the beginning of the speciﬁed container.

For example, use “beginning” to insert a word as the ﬁrst word of a paragraph. move word 1 to beginning of paragraph 1

ENDING

Usage: to insert or create an object at the end of the speciﬁed container. For example, use “ending” to create a text box that is the last text box on

the layout page.

make text box at end

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

This section provides deﬁnitions and examples for object references, insertion points, and each event that QuarkXPress supports.

This section also covers the important events in the Suites supported by QuarkXPress: the Required, Standard, Miscellaneous, CMS, Custom Bleeds, Layers, OPI Setup Record, Text, Table, QuarkXPress, and Word Filter Suites.

STANDARD SUITE

The Standard Suite consists of basic events most applications use to communicate.

34 | A GUIDE TO APPLE EVENTS SCRIPTING

DEFINITIONS AND EXAMPLES — APPLE EVENTS TERMINOLOGY

CLOSE Close

Usage: to close a speciﬁed object and determine whether to save it. is

usually used for a window or layout.

close reference saving save options saving in alias

Possible values: saving: yes, no, ask saving in: alias

DUPLICATE

Usage: to copy the data and properties of a speciﬁed object and create a new object with the same data and properties. You can specify an insertion point for the new object. (If you don’t specify a new insertion point, the new object

is placed inDuplicatethe same container as themakeinitial object, at the end of the container’s elements.) is similar to .

duplicate reference to insertion location

Possible values: to: location reference (See the “Apple Events Terminology” section of this layout for insertion point information.)

Result: reference (to the duplicated object)

COUNT

Usage: to determine how many elements of a particular class are contained in

a speciﬁed object.

Count of object class in reference

Possible values: each: type class (any object class)

Result: integer

MAKE

Usage: to make a new element of an object. You can specify the type of object you want to make, set properties in the new object, and specify an

insertion point.

make new object type at insertion location with data with properties {properties}

Possible values: new: type class (any object class)

at: location reference (See the “Apple Events Terminology” section of this layout for insertion point information.)

with data: anything (the initial data for the element)

with properties: record

Results: Reference (to the new object)

A GUIDE TO APPLE EVENTS SCRIPTING | 35

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

DATA SIZE

Usage: to obtain an object’s size in bytes. data size reference as type

Possible values: as: type class

Result: integer

DELETE

Usage: to remove a speciﬁed element from an object or application. delete reference

EXISTS

Usage: to check for the existence of a speciﬁed object. exists reference

Result: Boolean

GET get set

Usage: to determine the data structure for an object. and are usually used to read and write an object’s internal data and properties, rather than

the whole object.

Get reference

Result: the properties of the object you reference

GET AS

Usage: to determine the data structure for an object in a speciﬁc data type.

Get property of reference as type

Possible values: as: data type (See the “Data Coercion Chart.”)

Result: the properties of the object you reference in the data type you specify

MOVE

Usage: to change an object’s position in an application’s container hierarchy. The speciﬁed object is moved from its current location to a speciﬁed insertion point. “Move” is not used to change thesetphysical location of an object. To change

the physical location, you would use to change its properties.

Move reference to insertion location

Possible values: to: location reference (See the “Apple Events Terminology” section of this layout for insertion point information.)

Result: reference (to the object in its new location)

36 | A GUIDE TO APPLE EVENTS SCRIPTING

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

OPEN

Usage: to open a speciﬁed object or ﬁle.

Open reference use doc prefs remap fonts do auto picture import with reﬂow

Possible values: use doc prefs: yes, no, ask remap fonts: no, ask

do auto picture import: yes, no, ask reﬂow: with reﬂow, without reﬂow

Usage: to print a speciﬁed object.

print reference copies copies OPI OPI cover page cover page paper source paper source to alias plates list of plates print dialog

Possible values: copies: integer

cover page: no, ﬁrst page, last page

OPI: omit TIFF, omit TIFF and EPS, include images paper source: paper cassette, manual feed

plates: a list of strings (names of process/spot color specs)

PostScript ﬁle: alias (a ﬁle path) print dialog: no, yes

QUIT

Usage: to quit QuarkXPress and close all open layout spaces. quit reference saving

Possible values: saving: yes, no, ask

SAVE

Usage: to save a speciﬁed object to a speciﬁed ﬁle on disk.

save reference in alias as ﬁle type EPS format EPS format EPS data EPS data OPI OPI bleed bleed

Possible values: in: alias

as: type class

template: Boolean

include preview: Boolean

EPS Format: Standard EPS, Multiple File DCS, Single File DCS

Output Setup: string

A GUIDE TO APPLE EVENTS SCRIPTING | 37

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

EPS data: ASCII EPS, binary EPS, clean EPS transparent page: Boolean

OPI: omit TIFF, omit TIFF and EPS, include images bleed: vertical measurement

scale: percent

version: vers 70, vers 80, vers current

vers 60 JAPANESE (East Asian only) vers 60 KOREAN (East Asian only)

SET/GET set get

Usage: to change an object’s data structure. and are usually used to write

and read an object’s internal data and properties, rather than the whole object.

Set data of reference to replace with

Possible values: data: object speciﬁc data

replacing*: ask/ignore/replace/rename

*Replacing is used for importing text with style sheets in any text ﬁle format supported by QuarkXPress.

The set and get events are not explicitly speciﬁedset in the QuarkXPress dictionary with these parameters. Therefore, the basic event of AppleScript is used to set the properties of objects.

WORD FILTER SUITE

The Word ﬁlter Suite contains functions related to Microsoft® Word documents.

EXPORT

Usage: to export selected text

export reference as ﬁlter type in alias

Possible values: as: string

in: alias

IMPORT

Usage: to import selected Microsoft Word document import reference from alias as ﬁlter type

Possible values: from: alias

as: string

stylesheets: Boolean

convert quotes: Boolean

38 | A GUIDE TO APPLE EVENTS SCRIPTING

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

MISCELLANEOUS SUITE

The Miscellaneous Suite consists of functions related to the clipboard and other menu-driven functions.

COPY

Usage: to place a copy of the selected object on the clipboard. copy

CUT

Usage: to place the selected object on the Clipboard. cut

DO SCRIPT

Usage: to execute a script entirely before showing the results. do script data script type type

Possible values: script type: type class

Result: anything (result of the script execution)

PASTE

Usage: to place the data on the Clipboard into a designated/selected container. paste

REVERT

Usage: to restore an object to its last saved state. revert reference

SHOW

Usage: to bring an object into view; also changes the object’s index

reference form. show reference

QUARKXPRESS SUITE

The QuarkXPress Suite consists of two events: coerce and do updates.

COERCE

Usage: To change data from one type to another type. coerce property of reference to type

Possible values: to: type class (see the “Data Coercion Chart” later in this section)

Result: anything (result of script execution)

DO UPDATES

Usage: To redraw the screen after the execution of a script. do updates

A GUIDE TO APPLE EVENTS SCRIPTING | 39

DEFINITIONS AND EXAMPLES — EVENTS SUPPORTED BY QUARKXPRESS

DATA COERCION CHART

The following table lists the possible data structure you can request with a get as event. The € indicates that both data types can be coerced into each other. The left-facing arrow ‹ indicates that the data types on the right can be coerced into the data types on the left.

text	€	alias
integer	€	Boolean
		text
color spec	‹	string
		integer
		list
		RGB Color
style spec	‹	string
		integer
h and j spec	‹	string
		integer

Color Models	Rectangle Units
CMYK color	centimeters rectangle
HSB color	ciceros rectangle
list	ﬁxed rectangle
RGB color	inches rectangle
Numbers	list
	list
agate units	measurements rectangle
agate units	millimeters rectangle
angle measurement	picas rectangle
centimeter units	points rectangle
ﬁxed	Points Units
cicero units
font units	centimeters point
horizontal measurement	ciceros point
grid increment units	ﬁxed point
inch units	inches point
inset units	list
integer	measurements point
leading units	millimeters point
millimeter units	picas point
percent	points point
pica units
point units
real
text
thick units
trap units
vertical measurement

40 | A GUIDE TO APPLE EVENTS SCRIPTING

+ 116 hidden pages