How it Works
Quark
Loading...
Apple Events Scripting
User Manual
166 pgs1.17 Mb0

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
Script Writing Sample 11
The Layout Construction Script 12
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
Selection Object Properties, Data Types, and Descriptions 58
Character Events and Examples 58
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 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
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 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 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
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 appli­cations 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 com­posed 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 iden­tifies 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; lay­outs 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 manip­ulate 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 layer­related 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 follow­ing 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 sup­ports. 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, for­matting 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...
+ 136 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use