You are not logged in.
Every scripter, at some time or other, has been faced with performing some particular function with no clue how to do it. The dictionary, written cryptic-style, doesn't help. They can't find any reference on any BBS to their specific issue, and they can find no examples anywhere addressing their question. The technique I'm going to outline in this article is how I figure out for myself how to script any scriptable application. For our purposes here I will use QuarkXPress as an example but these principles can be applied to most, if not all, scriptable applications. The way to control an application is through setting its objects' properties, therefore, creating an object and using AppleScript to return its properties is the best way to quickly figure out for ourselves how to script the application.
First let me make clear, this is not a "how-to" for scripting QuarkXPress. A number of far more qualified folks have written extensively on this subject already. Shirley Hopkins, Danny Goodman and Sal Soghoian, to name just a few. The goal of this piece will be to help you broaden your resourcefulness in finding answers on your own, without relying on finding or not finding, as the case may be, exact answers to your questions.
There are essentially two types of properties in any application; what I will call "Public" and "Private" property. Private property is those properties that the application reserves exclusively for its own use in the same way your home is your private property for your own use. Public property, much like a park, can be used by anyone, given certain rules are followed. This article will help you determine how to use these "public" properties and what rules govern their use.
Using Object Properties
So let's begin. First, with an open document in QuarkXPress (or your favorite application), you can enter the following code in Script Editor:
Applescript:
tell application "QuarkXPressâ�??¢"
tell document 1
return properties of picture box 1 of page 1
end tell
end tell
The returned result looks like this:
Applescript:
{best type:null, class:picture box, default type:null, object reference:generic box 2 of spread 1 of document "bw_test.qxd" of application "QuarkXPressâ�??¢", anchored:false, background trap:default, color:null, content:picture content, index:1, locked:false, name:"", rotation:"0�?°", runaround:none runaround, selected:false, shade:"100%", box shape:rectangular, suppress printing:false, uniqueID:-2.147483646E+9, blend:{style:solid}, bounds:{"9.574\"","0.375\"","10.625\"","4.037\""}, corner radius:null, flipped horizontal:false, flipped vertical:false, frame:{color:color spec "Black" of document "bw_test.qxd" of application "QuarkXPressâ�??¢", gap color: null, gap shade:"100%", inside trap: default, outside trap:default, shade:"100%", style:solid, width:"0 pt"}, skew:"0�?°", text outset:"1 pt"}
QuarkXPress will return a record of all of the properties of "picture box 1". This record tells us everything we need to know about controlling and manipulating picture boxes (or any other object) via AppleScript. It is important to know, however, which properties in the record are public and which are private. The rule of thumb that I use is that any of these properties that I can manually change within QuarkXPress via some dialog box are public property and can be changed with AppleScript. The properties hi-lited in yellow do not appear in any control in QuarkXPress and therefore are private property (cannot be changed via AppleScript).
Parameter Types
In determining what types of parameters the application requires, you simply look at what type of parameters your application has returned. I can tell from the returned properties pictured belowshown above that QuarkXPress prefers the "bounds" (hi-lited in blue) of a picture box to be a list; that it prefers "suppress printing" (hi-lited in green) to be either true or false (boolean); that it prefers "box shape" (hi-lited in purple) to be a class; and that it prefers "blend" (hi-lited in red) to be a record.
In the case of measurements, however, you can usually pass an integer or real number as well. It is also important to note, in the case of a string parameter, whether the string is enclosed in quotation marks or not. If the returned property's parameters are not enclosed in quotation marks, the parameter is a class, defined either by the application or the system.
Applescript:
tell application "QuarkXPressâ�??¢"
tell document 1
tell page 1
set width of frame of picture box 1 to 2
end tell
end tell
end tell
Manipulating Object Properties
Once I understand the properties associated with each object, what type of parameter is required for each property, and what the acceptable parameters are, I am almost ready to unleash my imagination, empowered by my new-found understanding of my application. However, there are some further issues, an understanding of which, will help make scripting my application even easier.
First, when creating or modifying objects, it is generally a good idea to not try to do too much at once. Setting properties individually is safer than trying to set them all at once. In my experience, QuarkXPress does not respond well, or sometimes at all, when trying to set all of the properties of an object at once. When creating new objects, I generally create the object, a picture box for instance, with the bare minimum properties such as the bounds. I then set each property individually. This is, admittedly slower if I intend to change all of the properties, but it can also avoid potential errors. I am not certain of this, but it may be that when defining multiple properties, the application prefers them in a certain order. Feel free to correct me if you know for certain why this happens.
Second, you only need to specifically set those properties which either have no defaults or whose defaults are not what you want. As in the case of the width of the frame of a picture box, the default is "0" and therefore, if I want a visible frame, I have to specify it.
And last, using object references as much as possible is a very reliable way to refer to an object to be manipulated. This insures that the changes are made to the intended recipient. It also allows for fewer lines of code. If I tell QuarkXPress to set myObject to "object reference of picture box 1 of page 1 of document 1", I do not need to enclose the commands inside nested "tell" statements (see figurecode below).
Applescript:
tell application "QuarkXPressâ�??¢"
set myObject to object reference of picture box 1 of page 1 of document 1
set width of frame of myObject to 3
end tell
This article has hopefully given you some good tools for figuring out the basics of scripting almost any scriptable application. You should be ready to unleash your imagination to create powerful automation solutions. As stated in the beginning of this article, I have used QuarkXPress to demonstrate the techniques that I use to quickly figure out how to script applications with which I have never worked. These techniques have worked very well for me and I hope they will for you as well.
One last point I will make is that the most valuable resource for any scripter is script code made available by other scripters who may be more advanced or more experienced with a particular application. When looking at others' code, try to deconstruct, line-by-line if necessary, the concepts behind what is being done, rather than follow the specifics of the code. This is, in my humble opinion, the best way to not only learn how to script, but to improve scripting abilities and expand your repertoire of ideas.
A reasonable man adapts himself to the world he sees. An unreasonable man tries to adapt the world he sees to himself. Therefore, all advancement in society is achieved by unreasonable men. --Paraphrase of a quote by George Bernard Shaw
Offline