Appendix D. Scripting Basics MACROS VERSUS SCRIPTING

Size: px

Start display at page:

Download "Appendix D. Scripting Basics MACROS VERSUS SCRIPTING"

Kenneth Alan Lawrence
5 years ago
Views:

1 1 Appendix D Scripting Basics Completing repetitive tasks in QuarkXPress drives me crazy. There are two things that can alleviate all these woes: macros and scripting. In this appendix, I ll discuss the difference and provide some basic information on how to write a script. For editing and running scripts that ship with QuarkXPress 7 see Appendix B, Scripting in Real World QuarkXPress 7. Before I get started, there s one other thing you need to know: Scripting in QuarkXPress is Macintosh only. One day the folks at Quark will update XPress for Windows to be scriptable. Until then, if you only use Windows, you won t be able to script. However, you will be able to use macros if you buy a separate macro utility. MACROS VERSUS SCRIPTING While some folks use the terms macro and script interchangeably, they re very different critters. Let s take a quick look at how macros and scripting are similar and different. Macros. Let s just get one thing perfectly clear: If you don t own and use a copy of Startly Technologies (formerly CE Software s) QuicKeys, you re just not being efficient in your work. QuicKeys (there are versions for both the Macintosh and Windows) lets you create macros to tell QuarkXPress and any other program or utility you use, including the Finder what to do. A macro can be an action or sequence of actions. It can be triggered by a keystroke, by the time of day, or by selecting it from a menu. I have lots of QuicKey macros on my computer. To start QuarkXPress, I just press Control-Shift-Q. To create a new text box, put it six picas from the top of the page, and automatically jump into the measurement palette, I can press Control-Option-N. To clone

2 2 APPENDIX D: SCRIPTING BASICS an object (Step and Repeat with zero offsets), I like Command/Ctrl-=. All of these work on my machine because I ve made QuicKeys macros. Any menu item you can select, any key you can press, any printer or server you can choose on the network, any event you can cause to happen can be assigned a macro keystroke or be built in to a sequence macro. They re incredibly helpful and can speed up work enormously because they re easy to create and use. While I like QuicKeys, there are several other utilities that do the same or similar things, including Westcode s OneClick for the Macintosh and Wilson WindowWare s WinBatch for Windows. Scripting. There are two basic differences between macros and scripts. First, macros are entirely dependent on the user interface the menus, dialog boxes, keyboard shortcuts, and so on. Scripts, however, let you sneak in the back door of the program and control it from behind the scenes, almost like a puppeteer pulling the strings of a marionette and there are things you can do behind the scenes for which there is no interface in XPress (like locking guides). Second, scripts have flow control. Flow control is a programming term that means you can set up decision trees and loops, like keep doing this until such-andsuch happens; plus, scripts often contain variables. You can do much more complex and interesting things with scripting than you can with simple macros. When people talk about scripting, they re usually talking about either program-specific scripting or AppleEvents. AppleEvents is a Macintosh feature that lets programs communicate with and control one another. The rest of this appendix focuses on AppleEventsbased scripts and scripting. WRITING A SCRIPT Although AppleScripting is programming, it s much easier to pick up than most other programming languages because it uses natural language commands. Nevertheless, it still may take you a while to start to understand the concepts. I know it s a cop-out, but there s neither time nor space truly to teach you how to program here. What I can do here is give you a pretty solid foundation on which to build your scripting knowledge. Then you can go off, look through the scripts I ve included in this appendix and on the Web, and try your own. The main concepts you ve got to understand are the object model, hierarchies, properties, and events.

3 WRITING A SCRIPT 3 The Object Model Let s get one thing clear: The object model is not a feminist theory regarding the objectification of fashion models in magazines. Rather, the object model describes the way AppleEvent scripting works. That is, in order to get scripting, you have to think in terms of the object model. The object model says that everything is an object that you can talk to. For example, an object might be a text box, or a word, or a picture, or a whole layout. Objects can (and usually do) contain other objects; for instance, a page can contain text boxes, which can contain paragraphs, which can contain words. There are over four dozen kinds of objects in QuarkXPress. Each of these can be controlled or queried through basic scripting commands. Although some objects are intuitively similar to items you know in the program, others are a little more obscure. For example, text boxes and words are clear and you can easily get a handle on what they are, but Master Document and Delimit Table may be confusing at first (see Difficult Objects, later in this appendix). Tip: Naming Objects. One of the coolest things about scripting XPress is that you can name most objects. You can always identify text box 1 (the topmost text box on the page) or line box 3, but it s much easier to choose and manipulate a text box named Lead story or a line box called VerticalLine. For example, you can type set the name of text box 1 to "My Text Box". The more complicated your script, the more important it is to name your objects. Hierarchies, Elements, and Containers You can t understand the object model and scripting without understanding hierarchies, elements, and containers. As I said earlier, most objects in QuarkXPress contain other objects; for example, a paragraph contains words, which contain characters. Hierarchies only get complicated when you can t remember what contains what (see Figure D-1). That s when you really need to rely on the documentation and QuarkXPress AppleScript dictionary. In working with hierarchies, two terms are helpful to keep in mind: elements and containers. An element is an object that is contained inside another object. A text box is an element of a page, for instance. A container is simply an object that has elements. The QuarkXPress application is a container for windows, layouts, and so on.

4 4 APPENDIX D: SCRIPTING BASICS Figure D-1 Much of the AppleScript hierarchy in QuarkXPress Properties Every object in QuarkXPress has properties that you can look at and usually change. A property is a characteristic of an object. For example, picture boxes have the properties of background color, rotation, placement on the page (called bounds), and many more. Difficult Objects As I noted earlier, some objects in QuarkXPress are pretty confusing if you haven t seen them before. Objects such as document and picture box are pretty simple, so I m just going to focus on the objects in QuarkXPress that may raise your eyebrow. Please note that although QuarkXPress documents are now referred to as layouts, in scripting language document is the correct terminology.

5 WRITING A SCRIPT 5 Application. The highest object in the hierarchy is application. You can think of the QuarkXPress application as being the program with or without a layout open; changes made here are application-wide and affect any layout that is open or is created from then on. Note that if you ve renamed your copy of QuarkXPress, then the application s name might be different for you. Window. When I first saw the window object, I thought it was the same as document. However, that s not the case. Documents are only open layouts, but you can control all the windows in QuarkXPress. That includes the palettes and dialog boxes. You can t do a lot to them, but you might want to write a script that brings all the palettes up and then sets their sizes and positions on the screen. Default document. The default document contains all the preferences and settings for the New dialog box, the H&Js, colors, and style sheets whether a layout is open or closed. For example, with no layout open, you can set the default document s settings; when you create a new layout, it will be configured in that way. Spread. Spreads are pretty obvious, but here s an important point you should know: Items on the pasteboard fall in the domain of the spread, but not the page. So if you change all the text boxes in a spread to red, then the text boxes on the pasteboard get changed, too. If you do it to all the objects on a page, only the ones that are touching the page get changed. Also note that a spread includes all the pages that are next to each other. So you can have a one-, two-, three-, or more page spread. Master document. The master document is the object that contains the master pages. What does that mean? Dave Shaver, one of the engineers at Quark who worked on scripting, describes the master document as being a shadow of the document. You can talk to its light side (the actual layout pages), or you can talk to its dark side (the master pages). For example, if you want to change something on a master page, you need to address a page or spread in the master document. You can t change a master page from within the document itself. Of course, master document 1 and document 1 are just different parts of the same document. Note that if you re going to change something throughout a document, it s best to change it on the master document pages first, then, if necessary, on the document pages. Color spec. There are no color objects in QuarkXPress, only color specs (or color spec objects, to be precise). Color specs don t contain anything, but have various properties. Just to confuse you, the property of an object is called color, but the color itself is a color spec. For instance, you can say set color of text box 1 to "Red" because you re setting a property of a box. However, if you want to change the values of Red then you ll need to address it as a color spec of the document, like: set the color type of color spec "Red" to CMYK type.

6 6 APPENDIX D: SCRIPTING BASICS There are several other specs like this in XPress. For instance, to edit or create a style sheet, you have to talk to a style spec (make new style spec at end) and to edit an H&J setting you have to talk to an object called an h and j spec. Horizontal and vertical guide. You can create and manipulate ruler guides through scripts by working with horizontal and vertical guides. In fact, you can even do things to guides that you can t do in the program itself, such as make them undeletable or immobile. Line. Don t get fooled: a line is not a rule. That is, the line object is a line of text, not a graphic on the page. The line extends from one margin to another in a column of text. Line box. For some obscure reason which I haven t figured out yet, lines (graphic rules) are considered line boxes. I suppose that makes it all consistent under the hood, but it can kind of mess you up if you re not careful. Image. Even though each picture box can contain only one image, you still have to type image 1. For instance, you can import a picture into a picture box by setting the image to a file on disk. For example: set image 1 to alias "myharddisk:picture1". Generic box. A generic box is any page item in QuarkXPress, whether a picture box, a text box, or a rule (see Line box, above). This can be helpful, especially when you re telling a whole bunch of items to do the same thing. Note that generic boxes take the lowest common denominator properties of all objects. For instance, line boxes don t have a bounds property, so neither do generic boxes. Story. A story is, as you may have guessed, all the text in a chain of boxes. Each text box has only one story (but, of course, a story can go through many text boxes). The nice thing about stories is that you can find and change things in them really quickly (much faster than if you specify changes by word), for instance set the font of every word of story 1 of text box 1 where it is "Moose" to "Helvetica". Text style range. Most people who use QuarkXPress don t think in terms of ranges of text. However, there are times when you want to select a block of text that contains all the characters with the same text formatting. This block is called a text style range. Note that the same formatting includes color, font, style, kerning, tracking, and so on. As soon as the style changes in any way, QuarkXPress breaks the text down into another style range. For example, if you set the color of every word whose color is Red to Blue, it won t catch the words whose first three characters happen to be green (because QuarkXPress only looks at the first character of a word when assessing color). However, if you set all the text style ranges whose color is Red to Blue then, all the red characters change.

7 LOOKING AT A SCRIPT 7 Events The way you alter an object is by sending QuarkXPress an event, which is AppleEvents-ese for a command. If you want to set the tint of a line on page four, you need to send an event. In AppleScript format, the event would be a set command (such as set shade of line box 1 of page 4 to 30). Events are relatively simple, and there aren t that many of them, but there are enough so that I can t really discuss them here. My suggestion is that you pick them up as you go along by looking at other scripts and seeing how they work. Tip: Scripting Web Layouts. I ve been searching high and low and I ve come to the sad conclusion that at least at the time of this writing not one of QuarkXPress s Web features is scriptable. No hyperlinks, no rollovers, no menus, no exporting HTML. It s like the engineers just plain forgot about those features. So until Quark gets their act together, you ll have to just focus on print layouts. LOOKING AT A SCRIPT The next step in learning how to script with QuarkXPress is to look at a few actual, real, live AppleScripts and see how they work. Add a Dingbat Many magazines and newsletters end every story with a little dingbat character. However it can take a lot of time going through every story in a layout just to add a single character. This script does it for you. tell document 1 of application "QuarkXPress" --this script adds a dingbat character make character at end of every story with properties {contents:"n",font:"zapf Dingbats", size:11} end tell If you ve never programmed, looking at that script is probably somewhat unnerving. But I assure you that scripting is not as difficult as it looks, especially in the AppleScript language. There are two conventions that you should be aware of. First, all comments in this script have two hyphens before them. AppleScript just ignores those lines (they re included to help scripters remember what is being done). Second, the character that looks like a sideways L is a line-break character (its printable character is made by pressing Option-L in most PostScript fonts, or by pressing Option-Return in the Script Editor). You only have to use one of these if you break a single line of code into two or more lines (it s especially helpful in a book format like this).

8 8 APPENDIX D: SCRIPTING BASICS Opening and closing. You always need to specify in the script what application you re talking to with the tell application command. In this case, QuarkXPress is the way that my copy of QuarkXPress is named. If you change the name of the program without changing the name in the code, AppleScript won t be able to find it. When you re done talking to an object (in this case the application itself), you have to use an end tell command. Every tell must be followed by an end tell, just like a closing parenthesis or a closing quotation mark in a sentence. In this script, I m actually being more specific, and the tell command says that I m talking to the frontmost layout that is currently open in XPress. Make character. The meat of the script is the make character command, which simply tells XPress to add an 11-point n character in the Zapf Dingbats font as the last character of every story in the layout. Every story means every story, even empty text boxes! You have to be careful with the every command, because it is very powerful. Change to Superior What if one of your esteemed colleagues decides to create superscript characters using a 3-point baseline shift rather than the proper Superior or Superscript styles? This would be a hassle to change because you can t search for characters with baseline shift. Here s a quick script that does the search for you. tell application "QuarkXPress" activate if not (exists document 1) then return tell document 1 try tell every story set the properties of (every character whose base shift is "3 pt") to {base shift:"0 pt", style:{on styles:superior}} end tell on error beep display dialog "There are no letters with a Baseline Shift of 3." buttons {"Cancel"} default button 1 end try end tell end tell

9 STUFF YOU SHOULD KNOW ABOUT 9 There are several weird things going on here. First, the activate command at the beginning of the script tells QuarkXPress to come to the front of all other applications. Also, note the error-handling using try and if/then. The first if statement checks to make sure there is at least one document open. If there is no document 1 then it stops the script. Otherwise, you d get an error when you tried to talk to document 1. The try statement says try to do the following and if there s an error at any time, then jump to the on error statement. When applying text styles, there are on styles and off styles. In this case, I m turning on the Superior style. If there is an error, the script makes a dialog box appear with an error message. You can make the error say anything you want. In this case, there is only one button in the dialog box: Cancel. You can make more complex dialog boxes, too, with a little extra code. STUFF YOU SHOULD KNOW ABOUT Now, before you go off half-cocked with scripting ideas, let me throw in a few things you should know about. This list is going to get bigger and bigger as we all learn more about scripting. Not completed yet. Unfortunately, not everything in XPress is scriptable. As I said earlier, you can t script the Web features yet. Also, you can t script libraries, auxiliary dictionaries, box creation defaults, color pair trapping, and sections. Interrupting and canceling. You can always interrupt a script while it s running by pressing Command-period. Note that moving the mouse or typing on the keyboard usually won t do anything, so don t get paranoid about it. Also, remember that you can t Undo a script after it s run, so be careful and make backups. Page names. Pages are named so you can quickly access them even if you ve set sections with different pages numbers. If you want to do something to the fourth page, you can script page 4; however, if your numbering system is in roman numerals, you can also call it page iv. The name of the page (in quotation marks) is whatever is in the lower-left corner of the layout window in QuarkXPress. This goes for master pages within the master layout, too. Variables. Watch out for what variables you specify within your scripts. Many of the words are already taken by QuarkXPress itself. In fact, when using AppleScript, I like to set the formatting for different identifiers so that when I compile or run the script, I can quickly see what is a variable, what is an object, what is an event, and so on. You do this by selecting the Formatting tab of the Preferences dialog menu in the Script Editor.

10 10 APPENDIX D: SCRIPTING BASICS Hidden text. You may notice while browsing through the scripting docs that you can make text hidden. Even though it s tempting, resist it. First of all, it doesn t really do anything to the text. Second, hidden text is complicated enough so that it should be kept out of scripting and left to XTension developers (who do use it occasionally). One more thing about hidden text. There are times that you might search and replace text throughout a story and you might accidentally change some text that was hidden by QuarkXPress or an XTension. For example, anchored picture boxes have hidden text around them, and if you screw it up accidentally, weird things can happen. I can t say what you should and shouldn t do, but it s something to watch out for. FINAL THOUGHTS We ve only just scratched the surface of AppleScripting in general, and AppleScripting QuarkXPress in particular. There are hundreds of Web sites with articles and sample scripts. A good place to start is Quark s own Web site. As of this writing, the URL is: Apple s page is also a good starting point: Remember, learning scripting, like learning any language, will take some time. Don t get discouraged if your first few attempts don t work. Remember even Thomas Edison s first AppleScripts probably didn t work correctly (this is conjecture, since any AppleScripts he might have written have never been found).

A Guide to 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