Macromedia InCopy - CS6 User Guide
ADOBE® INCOPY® CS6
ADOBE INCOPY CS6
SCRIPTING GUIDE:
VBSCRIPT
2012 Adobe Systems Incorporated. All rights reserved.
Adobe® InCopy® CS6 Scripting Guide: VBScript
Document Update Status
(for entire document; see each chapter for chapter-specific update status)
CS6 Updated Throughout document, changed CS5 to CS6 and version 7.0 to 8.0.
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software
described in it, is furnished under license and may be used or copied only in accordance with the terms of such license.
Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written
permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law
even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to change without notice, and should not be
construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or
liability for any errors or inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under
copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of
the copyright owner. Please be sure to obtain any permission required from the copyright owner.
Any references to company names in sample templates are for demonstration purposes only and are not intended to
refer to any actual organization.
Adobe, the Adobe logo, Creative Suite, InCopy, InDesign, Illustrator, and Photoshop are registered trademarks or
trademarks of Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are
registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple and
Mac OS are trademarks of Apple Computer, Incorporated, registered in the United States and other countries. All other
trademarks are the property of their respective owners.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users.
The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of
“Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48
C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through
227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are
being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted
to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright
laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S.
Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the
provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act
of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR
Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding
sentence shall be incorporated by reference.
Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How to use the scripts in this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About the structure of the scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
About InCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Relationships between InCopy and InDesign files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Page geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The document model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
User-interface differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Design and architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Installing scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Running scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Using the scripts panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
VBScript language details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Using the scripts in this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Your first InCopy script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Walking through the script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Scripting terminology and the InCopy object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Scripting terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Understanding the InDesign and InCopy object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Measurements and positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3 Scripting Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Script preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Getting the current script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Script versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Targeting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Using the DoScript method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Sending parameters to DoScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Returning values from DoScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Running scripts at start-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3
4
4 Text and Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Entering and importing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Stories and text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding text to a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Replacing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Inserting special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Placing text and setting text-import preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Exporting text and setting text-export preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Text objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Moving and copying text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Text objects and iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Formatting text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Setting text defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Applying a font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Changing text properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Changing text color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Creating and applying styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Deleting a style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Importing paragraph and character styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Finding and changing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Find/change preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Finding text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Finding and changing formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Using grep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Using glyph search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Autocorrect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5 User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Dialog-box overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Your first InCopy dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Adding a user interface to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Creating a more complex user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Working with ScriptUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Creating a progress bar with ScriptUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Creating a button-bar panel with ScriptUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Understanding the menu model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Localization and menu names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Running a menu action from a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Adding menus and menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5
Menus and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Working with script menu actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Understanding the event scripting model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
About event properties and event propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Working with eventListeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
A sample “afterNew” eventListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
8 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Entering and importing a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Adding a note to a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Replacing text of a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Converting between notes and text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Converting a note to text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Converting text to a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Expanding and collapsing notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Collapsing a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Expanding a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Removing a note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Navigating among notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Going to the first note in a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Going to the next note in a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Going to the previous note in a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Going to the last note in a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9 Tracking Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Tracking Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Navigating tracked changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Accepting and reject tracked changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Information about tracked changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Preferences for tracking changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
10 Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Assignment object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Opening assignment files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Iterating through assignment properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Assignment packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
An assignment story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Assigned-story object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Iterating through the assigned-story properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
11 XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
The best approach to scripting XML in InCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6
Scripting XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Setting XML preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Setting XML import preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Importing XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating an XML tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Loading XML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Saving XML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Creating an XML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Moving an XML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Deleting an XML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Duplicating an XML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Removing items from the XML structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Creating an XML comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Creating an XML processing instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Working with XML attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Working with XML stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Exporting XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Adding XML elements to a story . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Associating XML elements with text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Applying styles to XML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Working with XML tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
1
Chapter Update Status
CS6 Unchanged
Introduction
This document shows how to do the following:
Work with the Adobe® InCopy® scripting environment.
Use advanced scripting features.
Work with text and type in an InCopy document, including finding and changing text.
Create dialog boxes and other user-interface items.
Customize and add menus and create menu actions.
Respond to user-interface events.
Work with XML, from creating XML elements and importing XML to adding XML elements to a layout.
How to use the scripts in this document
For the most part, the scripts shown in this document are not complete scripts. They are only fragments of
scripts, and are intended to show only the specific part of a script relevant to the point being discussed in
the text. You can copy the script lines shown in this document and paste them into your script editor, but
you should not expect them to run without further editing. Note, in addition, that scripts copied out of this
document may contain line breaks and other characters (due to the document layout) that will prevent
them from executing properly.
A zip archive of all of the scripts shown in this document is available at the InCopy scripting home page, at:
http://www.adobe.com/products/InCopy/scripting/index.html
expanded the archive, move the folders corresponding to the scripting language(s) of your choice into the
Scripts Panel folder inside the Scripts folder in your InCopy folder. At that point, you can run the scripts
from the Scripts panel inside InCopy.
About the structure of the scripts
The script examples are all written using a common template that includes the functions “main,”
“mySetup,” “mySnippet,” and “myTeardown.” We did this to simplify automated testing and
publication—there’s no reason for you to construct your scripts this way. Most of the time, the part of the
script you’ll be interested in will be inside the “mySnippet” function.
. After you have downloaded and
7
CHAPTER Introduction For more information 8
For more information
For more information on InCopy scripting, you also can visit the InCopy Scripting User to User forum, at
http://www.adobeforums.com
newest scripts. The forum contains hundreds of sample scripts.
. In the forum, scripters can ask questions, post answers, and share their
About InCopy
InCopy is a collaborative, text-editing application developed for integrated use with Adobe InDesign®.
InCopy enables you to track changes, add editorial notes, and fit copy tightly into the space designed for it.
InCopy uses the same text-composition engine as InDesign, so InCopy and InDesign fit copy within a
layout with identical composition.
InCopy is for the editorial environment. It allows editorial workflow participants to collaborate on
magazines, newspapers, and corporate publishing, enabling concurrent text and layout editing. Its users
are editors, writers, proofreaders, copy editors, and copy processors.
InCopy shares many panels and palettes with InDesign but also provides its own user-interface items.
Relationships between InCopy and InDesign files
Relationships between InDesign and InCopy files are important because of the division of labor in a
publication workflow that occurs when much of the same material is opened and modified in both
applications.
There are two common scenarios for exporting from InCopy:
You can export an (IDML based) ICML file.
You can export an (INX based) INCX file.
There are two common scenarios for exporting from InDesign that involve InCopy in some way:
Stories exported from InDesign as InCopy files are XML files or streams; the InCopyExport and
InCopyWorkflow plug-ins loaded into InDesign provide this function. Some practical implications of
this approach for InCopy files are that they are much smaller, they are faster over the network, they do
not contain any page geometry, and data within the XML file or stream is available outside
InDesign/InCopy (for search engines, database tools, and so on).
Groupings within an article (such as a headline, byline, copy, graphics, or captions) also can be
exported. InDesign and Incopy support the creation of groupings with assignment files, which handle
file management by adding an additional file that tracks the other files. In essence, an assignment is a
set of files whose contents are assigned to one person for some work to be done (for example, copy
edit, layout, and/or writing). Any stories in an assignment are exported as InCopy files. Geometry
information and the relationship of the files are held in the assignment file. InDesign allows the user to
export a given set of stories by exporting into an assignment. InCopy opens all stories that are in an
assignment together (as one unit). For details, see
Chapter 10, “Assignments.”
Stories
Each InCopy file represents one story. An InDesign document containing several stories can be
modularized to the same number of InCopy documents, through export. Those exported InDesign stories
CHAPTER Introduction Relationships between InCopy and InDesign files 9
contain a link, which may be viewed in the Links panel (InDesign) or the Assignments palette as
assignment files (InCopy).
InCopy does not maintain a link to the InDesign document it is associated with (if one exists). InDesign
maintains any links with InCopy files as bidirectional links.
Stories can be structured in XML. This means XML data can be contained within XML data. This feature can
be used to design a data structure in which the raw text of a story is contained within an outer structure
that contains data specific to InCopy (like styles).
Within InCopy, content can be saved in an ICML/INCX format or, if there is structure in the story, the logical
structure can be exported in XML.
An ICML or INCX file can contain both InCopy data and marked-up text. If the file is exported as XML data,
the data specific to InCopy is stripped out, leaving the marked-up content minus the information about
how it is to be styled.
Page geometry
InCopy files do not contain page geometry. When geometry is needed, it must be obtained from the
InDesign document. InCopy can open InDesign documents and extract design information and links to
the exported stories where needed. When page geometry is desired from within InCopy, assignment files
can be supplied with it.
Metadata
The Adobe Extensible Metadata Platform (XMP) provides a practical method for creating, interchanging,
and managing metadata. InCopy files support XMP.
Just as InDesign provides the File > File Info command to view XMP data, InCopy provides the File >
Content File Info command. System integrators can retain this data or strip it out during export.
Metadata added to stories by third-party software developers is preserved when incorporated into
InDesign documents. Added metadata can be viewed within InDesign (from the File Info dialog box,
available from the Links panel menu), as well as viewed within InCopy. Further, third-party software
developers can add functionality to InDesign to view that metadata in a custom user interface.
An extensibility point exists for service providers to add metadata content to InCopy files. For more
information, see Chapter 11, “XML
The document model
InDesign documents are the basis for all content in InDesign. InCopy also uses InDesign documents, but
they are not the default document type.
In both InDesign and InCopy, the basic document always is a database; in InCopy, however, this document
may be an incomplete document. In InDesign, the main document typically is an opened InDesign file, but
it also can be an opened INX or IDML file, which typically appears to be an unsaved InDesign document.
.”
InCopy has other permutations. There is the basic InDesign file, as well as a new document with an InCopy
story (or plain or RTF text) imported into it. Also, there are IDML- and INX-based assignment files, which
have some part of an InDesign file stored in an XML file. The InDesign/InCopy document model
corresponds to the base required model plug-in set, versioned against changes over time. It is important
CHAPTER Introduction Design and architecture 10
that all IDML/INX scripting work in both InDesign and InCopy, so documents can be moved with high
fidelity between the applications.
User-interface differences
InDesign and InCopy share most of their panels, but InCopy has a smaller set and several additional
toolbars along the top, left, and bottom screen borders. Most InCopy panels also can be docked on these
bars, providing a smaller but always-visible view of the panel.
InCopy also has a custom window layout with multiple views, in a main window with three tabs: Galley
view, Story view, and Layout view. Layout view is the InDesign window view. Galley and story views are
simply the story-editor view, with and without accurate line endings, respectively.
Design and architecture
Story/file relationship
ICML is an IDML-based representation of an InCopy story. It represents the future direction of
InDesign/InCopy and is an especially good choice if you need to edit a file outside of InDesign.
ICML format
Each InCopy file or stream is in XML. An advantage of this is that InCopy files can be parsed easily and
opened by any text editor.
INCX format
INCX is an INX-based representation of an InCopy story. This format is not as readable as ICML, but it is still
available to support INCX-based workflows.
Document operations
InCopy provides default implementations of document operations (file actions) like New, Save, Save As,
Save A Copy, Open, Close, Revert, and Update Design. All these InCopy file actions are in one plug-in
(InCopyFileActions) in source-code form. Software developers or system integrators are expected to
replace this with their own implementations, to customize the interaction for their workflow system.
Using XMP metadata
Users can enter and edit metadata by choosing File > Content File Info. This metadata is saved in the
InCopy file. Software developers and system integrators can create and store their own metadata using
the XMP SDK.
2
Chapter Update Status
CS6 Updated Removed or changed specific references to CS5. .
Getting Started
Scripting is the most powerful feature in Adobe® InCopy®. No other feature—no tool, panel, or dialog box
you see in the program’s user interface—can save you as much time, trouble, and money as scripting.
This document is for every InCopy user. It does not matter if you havenever created a script before; this
manual shows you how to get started. If you wrote scripts before for other applications, this manual shows
you how to apply your knowledge to InCopy scripting. It covers installing and running an InCopy script,
and it describes what InCopy scripting can and cannot do. It also discusses the software you need to get
started writing your own scripts.
Almost anything you can do with the InCopy user interface, you can do with a script. You can enter and
format text, find and change text, add notes, and print or export the pages of the document. Any action
that can change a document or its contents can be scripted. There are even a few things that you can do in
scripting that you cannot do using the user interface.
Scripts can create menus, add menu items, create and display dialogs and panels, and respond to your
user-interface selections. Scripts can read and write text files, parse XML data, and communicate with
other applications. Scripts can do everything from very small tasks (like setting a tab stop at the location of
the text cursor) to providing complete features. You can start with very simple scripts that do only one
thing and move on to scripts that automate your entire publishing workflow.
Most of the things scripting cannot do—like setting up a workspace or defining a set of keyboard
shortcuts—are related to the user interface. In addition, scripts cannot add new kinds of objects to an
InCopy document or add new, fundamental capabilities to the program, like a new text-composition
engine. For that type of extensibility, you must to turn to the InCopy Software Development Kit (SDK),
which shows you how to write compiled plug-ins using C++.
This document talks about Adobe InDesign® as well as InCopy, because InCopy almost always is used in
conjunction with InDesign documents. In addition, InDesign and InCopy scripting are very similar. For
more on InDesign scripting, see Adobe InDesign Scripting Tutorial and Adobe InDesign Scripting Guide.
Installing scripts
To install an InCopy script, just put the script file in the Scripts Panel folder in the Scripts folder in your
InCopy application folder.
Alternately, put the script in the Scripts Panel folder in your user-preferences folder. You can find your user
preferences folder at the following locations, where
system volume:
Windows® XP:
Windows® Vista: C:\Users\<username>\App Data\Roaming\Adobe\InCopy\
<username> is your user name and ~ (tilde) is your
C:\Documents and Settings\<username>\Application Data\Adobe\InCopy\
Version
Version
8.0\<locale>\Scripts
8.0\<locale>\Scripts
11
Getting Started Running scripts 12
Once the script is in the folder, it appears in the Scripts panel inside InCopy (choose Window > Scripts to
display the panel).
You also can put in the Scripts Panel folder aliases/shortcuts to scripts or folders containing scripts, and
they will appear in the Scripts panel.
Running scripts
To run a script, display the Scripts panel (choose Window > Scripts), then double-click the script name in
the Scripts panel. Many scripts display user-interface items (like dialogs or panels) and display alerts if
necessary.
Using the scripts panel
The Scripts panel can run compiled or uncompiled AppleScripts (files with the file extension .spt, .as, or
.applescript), JavaScripts (files with the file extension .js or .jsx), VBScripts (files with the extension
.vbs), or executable programs from the Scripts panel.
To edit a script shown in the Scripts panel, hold down Option (Mac OS) or Alt (Windows) key and
double-click the script’s name. This opens the script in the editor you defined for the script file type.
To open the folder containing a script shown in the Scripts panel, hold down the Command (Mac OS) or
Ctrl-Shift (Windows) keys and double-click the script’s name. Alternately, choose Reveal in Finder (Mac OS)
or Reveal in Explorer (Windows) from the Scripts panel menu. The folder containing the script opens in the
Finder (Mac OS) or Explorer (Windows).
Scripts run as a series of actions, which means you can undo the changes the script made to a document
by choosing Undo from the Edit menu. This can help you troubleshoot a script, as you can step backward
through each change.
To add a keyboard shortcut for a script, choose Edit > Keyboard Shortcuts, select an editable shortcut set
from the Set menu, then choose Product Area > Scripts. A list of the scripts in your Scripts panel appears.
Select a script and assign a keyboard shortcut as you would for any other InCopy feature.
VBScript language details
Visual Basic tutorial scripts are written in VBScript. We chose VBScript because no added software is
required to run or edit VBScripts; you can edit them with any text editor (like Notepad) and run them using
the InCopy Scripts panel.
Other versions of Visual Basic include Visual Basic 5 Control Creation Edition (CCE), Visual Basic 6, Visual
Basic .NET, and Visual Basic 2008 Express Edition. Versions of Visual Basic prior to Visual Basic .NET work
well with InCopy scripting; Visual Basic .NET and newer versions work less well (because they lack the
Variant data type, which is used extensively in InCopy scripting).
Many applications contain Visual Basic for Applications (VBA), like Microsoft® Word, Microsoft Excel,
Microsoft Visio, and AutoCAD. Although you can use VBA to create InCopy scripts, InCopy does not include
VBA.
To use VBScript or Visual Basic for InCopy scripting in Windows, you must install InCopy from a user
account that has Administrator privileges. After you complete the installation, any user can run InCopy
Getting Started Using the scripts in this document 13
scripts, and any user with Power User or Administrator privileges can add scripts to the InCopy Scripts
panel.
Using the scripts in this document
To use any script from this document, you can either open the tutorial script file (the filename is given
before each script) or copy the code shown in this chapter.
The script files are stored in a zip archive, InCopyCS6ScriptingGuideScripts.zip. When you
uncompress the archive, you can move the folder containing the scripts written in the scripting language
you want to use (AppleScript, JavaScript, or VBScript) to your Scripts Panel folder. Working with the script
files is much easier than entering the script yourself or copying and pasting from this document.
If you do not have access to the script archive, you can enter the scripting code shown in this chapter. To
do this:
1. Copy the script from this Adobe PDF document and paste it into a text editor (such as Notepad) or a
VBScript editor (such as VBSEdit).
2. Save the script as a plain-text file in the Scripts Panel folder (see “Installing scripts” on page 11), using
the file extension .vbs.
3. Choose Windows > Scripts to display the Scripts panel.
4. Double-click the script name in the Scripts panel to run the script.
Entering scripts manually will work only for the scripts shown in this chapter. The scripts shown in the
other chapters are script fragments, not complete scripts. To run these scripts, you must use the scripts
from the script archive.
OTE: If you are copying and pasting scripts from this document, be aware that line breaks caused by the
N
layout of the document can cause errors in your script. As it can be very difficult to find such errors, we
recommend hat you use the scripts in the zip archive.
Your first InCopy script
Next, we create an InCopy script that creates a new document, adds a text frame, then enters text in the
text frame. While this seems trivial, it demonstrates how to do the following:
Establish communication with InCopy.
Create a new document.
Add text to a story.
Start a text editor (for example, Notepad) and enter the following script (or open the HelloWorld.vbs
tutorial script):
Set myInCopy = CreateObject("InCopy.Application")
Set myDocument = myInCopy.Documents.Add
Set myStory = myDocument.Stories.Item(1)
myStory.Contents = "Hello World!"
Save the script as a plain-text file with the file extension .vbs in the Scripts Panel folder (see “Installing
scripts” on page 11). To run the script, double-click the script name in the Scripts panel.
Getting Started Scripting terminology and the InCopy object model 14
Walking through the script
Here is a step-by-step analysis of what the Hello World script does.
1. Establish communication with the InCopy application object:
Set myInCopy = CreateObject("InCopy.Application")
2. Create a new document and a reference to the document:
Set myDocument = myInCopy.Documents.Add
3. Get a reference to the first story in the document (a standalone document always contains a story):
Set myStory = myDocument.Stories.Item(1)
4. Add text to the story by setting the contents property to a string.
myStory.Contents = "Hello World!"
Scripting terminology and the InCopy object model
Now that you created your first InCopy script, it is time to learn more about the terminology of scripting
languages in general and InCopy scripting in particular.
Scripting terminology
First, let’s review a few common scripting terms and concepts.
Comments
Comments give you a way to add descriptive text to a script. The scripting system ignores comments as
the script executes; this prevents comments from producing errors when you run your script. Comments
are useful when you want to document the operation of a script (for yourself or someone else). In this
document, we use comments in the tutorial scripts.
To include a comment in VBScript, type
comment. To make an entire line a comment, type the comment marker at the beginning of a line. For
example:
Rem this is a comment
' and so is this
Values
The point size of a text character, the contents of a note, and the filename of a document are examples of
values used in InCopy scripting. Values are the data your scripts use to do their work.
Rem (for “remark”) or ' (one straight quote) to the left of the
The type of a value defines what sort of data the value contains. For example, the value type of the
contents of a word is a text string; the value type of the leading of a paragraph is a number. Usually, the
values used in scripts are numbers or text. The following table explains the value types most commonly
used in InCopy scripting:
Getting Started Scripting terminology and the InCopy object model 15
Value Type What it is Example
Boolean Logical True or False.
Integer Whole numbers (no decimal
True
14
points). Integers can be positive or
negative.
Double A high-precision number that can
13.9972
contain a decimal point.
String A series of text characters. Strings
"I am a string"
appear inside (straight) quotation
marks.
Array A list of values (the values can be
Array("0p0", "0p0", "16p4", "20p6")
any type).
Converting values from one type to another
VBScript provides ways to convert variable values from one type to another. The most common
converstions involved converting numbers to strings (so you can enter them in text or display them in
dialogs) or converting strings to numbers (so you can use them to set a point size or page location).
Rem To convert from a number to a string:
myNumber = 2
myString = cstr(myNumber)
Rem To convert from a string to an integer:
myString = "2"
myNumber = cInt(myString)
Rem If your string contains a decimal value, use "cDbl" rather than "cInt":
myNumber = cDbl(myString)
Variables
A variable is a container for a value. They are called “variables” because the values they contain might
change. A variable might hold a number, a string of text, or a reference to an InCopy object. Variables have
names, and you refer to a variable by its name. To put a value into a variable, you assign the data to the
variable.
In all examples and tutorial scripts that come with InCopy, all variables start with
easily differentiate variables we created in a script from scripting-language terms.
Assigning a value to a variable
Assigning values or strings to variables is fairly simple, as shown in these examples:
myNumber = 10
myString = "Hello, World!"
Set myTextFrame = myDocument.Pages.Item(1).TextFrames.Add
Try to use descriptive names for your variables, like firstPage or corporateLogo, rather than x or c. This
makes your script easier to read. Longer names do not affect the execution speed of the script.
my. This enables you to
Getting Started Scripting terminology and the InCopy object model 16
Variable names must be one word, but you can use internal capitalization (like myFirstPage) or
underscore characters (
my_first_page) to create more readable names. Variable names cannot begin
with a number, and they cannot contain punctuation or quotation marks.
Array variables
An Array is a container for a series of values:
myArray = Array(1, 2, 3, 4)
Rem In Visual Basic.NET: myArray = New Double (1, 2, 3, 4)
To refer to an item in an array, refer to its index in the array.In VBScript, the first item in an array is item 0:
myFirstArrayItem = myArray(0)
NOTE: The Visual Basic OptionBase statement can be used to set the first item of an array to item 1. In the
examples in this document, the first item in an array is item 0, not item 1, because that is the default. If you
OptionBase to 1, you must adjust all array references in the sample scripts accordingly.
set
Arrays can include other arrays, as shown in the following examples:
myArray = Array(Array(0,0), Array(72, 72))
Rem In Visual Basic.NET: myArray = New Array(New Double(0,0), NewDouble (0,0))
Finding the value type of a variable
Sometimes, your scripts must make decisions based on the value type of an object. If you are working on a
script that operates on a text selection, for example, you might want that script to stop if nothing is
selected.
Rem Given a variable of unknown type, "myMysteryVariable"...
myType = TypeName(myMysteryVariable)
Rem myType will be a string corresponding to the variable type (e.g., "Rectangle")
Operators
Operators use variables or values to perform calculations (addition, subtraction, multiplication, and
division) and return a value. For example:
MyWidth/2
returns a value equal to half of the content of the variable myWidth.
You also can use operators to perform comparisons (equal to (
<)). For example:
than (
MyWidth > myHeight
returns the value true (or 1) if myWidth is greater than myHeight; otherwise, false (0).
=), not equal to(<>), greater than (>), or less
In VBScript, use the ampersand (
"Pride " & "and Prejudice"
returns the string:
"Pride and Prejudice"
&) to concatenate (or join) two strings. For example:
Getting Started Scripting terminology and the InCopy object model 17
Conditional statements
“If the size of the selected text is 12 points, set the point size to 10 points.” This is an example of a
conditional statement. Conditional statements make decisions; they give your scripts a way to evaluate
something (like the color of the selected text, number of pages in the document, or date), then act
according to the result. Most conditional statements start with
if.
Control structures
If you could talk to InCopy, you might say, “Repeat the following procedure 20 times.” In scripting terms,
this is a control structure. Control structures provide repetitive processes, or loops. The idea of a loop is to
repeat an action over and over again, with or without changes between instances (or iterations) of the
loop, until a specific condition is met. Control structures usually start with the
for.
Functions
Functions are scripting modules to which you can refer from within your script. Typically, you send a value
or series of values to a function and get back another value or values. There is nothing special about the
code used in functions; they are simply conveniences to avoid having to type the same lines of code
repeatedly in your script. Functions start with
function.
Understanding the InDesign and InCopy object model
When you think about InCopy and InDesign documents, you probably organize the programs and their
components in your mind. You know that paragraphs are contained by text frames, which in turn appear
on a page. A page is a part of a spread, and one or more spreads make up a document. Documents contain
colors, styles, layers, and master spreads. As you think about the objects in the documents you create, you
intuitively understand that there is an order to them.
InDesign and InCopy “think” about the contents of a document the same way you do. A document
contains pages, which contain page items (text frames, rectangles, ellipses, and so on). Text frames contain
characters, words, paragraphs, and anchored frames; graphics frames contain images, EPSs, or PDFs;
groups contain other page items. The things we mention here are the objects that make up an InDesign
publication, and they are what we work with when we write InDesign and InCopy scripts.
Objects in your publication are arranged in a specific order: paragraphs are inside a story, which is inside a
document, which is inside the InCopy application object. When we speak of an object model or a hierarchy,
we are talking about this structure. Understanding the object model is key to finding the object you want
to work with. Your best guide to InCopy scripting is your knowledge of InCopy itself.
Objects have properties (attributes). For example, the properties of a text object include the font used to
format the text, point size, and leading applied to the text.
Properties have values; for example, the point size of text can be either a number (in points) or the string
“Auto” for auto leading. The fill-color property of text can be set to a color, gradient, mixed ink, or swatch.
Properties also can be read/write or read only. Read/write properties can be set to other values; read-only
properties cannot.
Objects also have methods. Methods are the verbs of the scripting world, the actions an object can
perform. For example, the document object has print, export, and save methods.
Getting Started Scripting terminology and the InCopy object model 18
documents
libraries
application defaults
application
books
application preferences
application events
application menus
application methods
application properties
a document
document defaults
document preferences
document events
document methods
document properties
pages or spreads
page
page itemsstories
text objects
document elements
Methods have parameters, or values that define the effect of the method. The open method, for example,
has a parameter that defines the file you want to open.
The following block diagram is an overview of the InCopy object model. The diagram is not a
comprehensive list of objects available to InCopy scripting; instead, it is a conceptual framework for
understanding the relationships between the types of objects.
The objects in the diagram are explained in the following table:
Term What it represents:
Application InCopy.
Application
defaults
Application
events
Application
menus
Application
methods
Application
preferences
Application default settings, such as colors, paragraph styles, and object styles.
Application defaults affect all new documents.
The things that happen as a user or script works with the application. Events are
generated by opening, closing, or saving a document or choosing a menu item. Scripts
can be triggered by events.
The menus, submenus, and context menus displayed in the InCopy user interface.
Scripts can be attached to menu choices and can execute menu actions.
The actions the application can take; for example, finding and changing text, copying
the selection, creating new documents, and opening libraries.
Examples are text preferences, PDF export preferences, and document preferences.
Many preferences objects also exist at the document level. Just as in the user interface,
application preferences are applied to new documents; document preferences change
the settings of a specific document.
Getting Started Scripting terminology and the InCopy object model 19
Term What it represents:
Application
properties
Books A collection of open books.
Document An InCopy document.
Document
defaults
Document
elements
Document
events
Document
methods
Document
preferences
Document
properties
The properties of the application; for example, the full path to the application, the locale
of the application, and the user name.
Document default settings, such as colors, paragraph styles, and text formatting
defaults.
For example, the stories, imported graphics, and pages of a document. The figure above
shows pages and stories, because those objects are extremely important containers for
other objects; however, document elements also include rectangles, ovals, groups, XML
elements, and any other type of object you can import or create.
Events that occur at the document level, such as importing text. See application events in
this table.
The actions the document can take; for example, closing a document, printing a
document, and exporting a document.
The preferences of a document, such as guide preferences, view preferences, or
document preferences.
For example, the document filename, number of pages, and zero-point location.
Documents A collection of open documents.
Libraries A collection of open libraries.
Page One page in an InCopy document.
Page item Any object you can create or place on a page. There are many types of page items, such
as text frames, rectangles, graphic lines, and groups.
Pages or
spreads
Stories The text in an InCopy document.
Text objects Characters, words, lines, paragraphs, and text columns are examples of text objects in an
The pages or spreads in an InCopy document.
InCopy story.
Looking at the InCopy object model
You can view the InCopy object model from inside your script-editing application. All reference
information on objects and their properties and methods is stored in the model and can be viewed,
To view the InCopy object model, you need a VBScript editor/debugger, some version of Visual Basic, or an
application that incorporates Visual Basic for Applications.
Visual Basic 6
To view the object model using Visual Basic 6:
Getting Started Scripting terminology and the InCopy object model 20
1. Create a new Visual Basic project, then choose Project > References. Visual Basic displays the
References dialog:
2. From the list of available references, select the Adobe InCopy CS6 Type Library option, and click OK. If
the library does not appear in the list of available references, click Browse, then find and select the
Resources for Visual Basic.tlb file. Usually this file is in
Settings\<username>\Application Data\Adobe\InCopy\Version 8.0\<locale>\Scripting
Support\ (where <username> is your user name and ~ is your system volume). If necessary, search for
~\Documents and
the file. Once you find the file, click Open to add the reference to your project.
3. Choose View > Object Browser. Visual Basic displays the Object Browser dialog.
4. From the list of open libraries shown in the Project/Library menu, select InCopy. Visual Basic displays
the objects that make up the InCopy object model.
5. Click an object class. Visual Basic displays the object’s properties and methods. For more information
on a property or method, select the item; Visual Basic displays the definition of the item at the bottom
of the Object Browser window:
Visual Basic Express 2008/Visual Basic.NET
To view the object model using Visual Basic Express 2008/Visual Basic.NET:
Getting Started Scripting terminology and the InCopy object model 21
1. Create a new Visual Basic project, then choose Project > Add Reference. Visual Basic displays the Add
Reference dialog.
2. Select the COM tab.
3. From the list of available references, select Adobe InCopy CS6 Type Library. Visual Basic adds the
reference to the Selected Components list. If the library does not appear in the list of available
references, click Browse, then find and select the Resources for Visual Basic.tlb file. Usually this file is in
~\Documents and Settings\<username>\Application Data\Adobe\InCopy\Version
8.0\<locale>\Scripting Support\ (where <username> is your user name). Once you find the file,
click Open to add the reference to your project.
4. Click OK.
5. Choose View > Object Browser. Visual Basic displays the Object Browser tab.
6. From the list of open libraries shown in the Objects window, choose interop.incopy. Visual Basic
displays the objects that make up the InCopy object model.
7. Click an object class. Visual Basic displays the object’s properties and methods. For more information
on a property or method, select the item; Visual Basic displays the definition of the item at the bottom
of the Object Browser window:
Getting Started Scripting terminology and the InCopy object model 22
Visual Basic for Applications
To view the object model using Visual Basic for Applications from Microsoft Excel:
1. Start Excel.
2. Choose Tools > Macros > Visual Basic Editor. Excel displays the Visual Basic Editor window.
3. Choose Tools > References. The Visual Basic Editor displays the Add References dialog:
4. From the list of available references, select the Adobe InCopy CS6 Type Library, and click OK. Visual
Basic adds the reference to the Selected Components list. If the library does not appear in the list of
available references, click Browse, then find and select the Resources for Visual Basic.tlb file. Usually
this file is in
8.0\<locale>\Scripting Support\ (where <username> is your user name). Once you find the file,
~\Documents and Settings\<username>\Application Data\Adobe\InCopy\Version
click OK to add the reference to your project.
5. Choose View > Object Browser. The Visual Basic editor display the Object Browser window.
Getting Started Scripting terminology and the InCopy object model 23
6. Choose InCopy from the Libraries pop-up menu. The Visual Basic editor displays a list of the objects in
the InCopy object library.
7. Click an object name. The Visual Basic Editor displays the object’s properties and methods of the
object. For more information on a property or method, select the item; Visual Basic displays the
definition of the item at the bottom of the Object Browser window:
Measurements and positioning
All items and objects in InCopy are positioned on the page according to measurements you specify. It is
useful to know how the InCopy coordinate system works and what measurement units it uses.
Coordinates
InCopy, like every other page-layout and drawing program, uses simple, two-dimensional geometry to set
the position of objects on a page or spread. The horizontal component of a coordinate pair is referred to as
x; the vertical component, y. You can see these coordinates in the Transform panel or Control when you
select an object using the Selection tool. As in the InCopy user interface, coordinates are measured relative
to the current location of the ruler’s zero point.
There is one difference between the coordinates used in InCopy and the coordinate system used in a
Geometry textbook: on the InCopy vertical (or y) axis, coordinates below the zero point are positive
numbers; coordinates above the zero point are negative numbers.
Measurement units
When you send measurement values to InCopy, you can send numbers (for example, 14.65) or
measurement strings (for example, “1p7.1”). If you send numbers, InCopy uses the publication’s current
units of measurement; if you send measurement strings (see the table below), InCopy uses the units of
measurement specified in the string.
InCopy returns coordinates and other measurement values using the publication’s current measurement
units. In some cases, these units do not resemble the measurement values shown in the InCopy Transform
panel. For example, if the current measurement system is picas, InCopy returns fractional values as
decimals, rather than using the picas-and-points notation used by the Transform panel. So, for example,
Getting Started Adding features to “Hello World” 24
“1p6,” is returned as “1.5.” InCopy does this because your scripting system would have trouble trying to
perform arithmetic operations using measurement strings. For instance, trying to add “0p3.5” to “13p4”
produces a script error, while adding .2916 to 13.333 (the converted pica measurements) does not.
If your script depends on adding, subtracting, multiplying, or dividing specific measurement values, you
might want to set the corresponding measurement units at the beginning of the script. At the end of the
script, you can set the measurement units back to whatever they were before you ran the script.
Alternately, you can use measurement overrides, like many of the sample scripts. A measurement override
is a string containing a special character, as shown in the following table:
Override Meaning Example
c ciceros (add didots after the c, if necessary) 1.4c
cm centimeters .635cm
i (or in) inches .25i
mm millimeters 6.35mm
p picas (add points after the p, if necessary) 1p6
pt points 18pt
Adding features to “Hello World”
Next, we create a new script that makes changes to the “Hello World” publication we created with our first
script. Our second script demonstrates how to do the following:
Get the active document.
Change the formatting of the text in the first story.
Add a note.
Either open the ImprovedHelloWorld tutorial script or follow these steps to create the script:
1. Start any text editor (for example, Notepad).
2. Make sure you have the document you created earlier open. If you closed the document without
saving it, simply run the
3. Enter the following code:
HelloWorld.vbs script again to make a new document.
Getting Started Adding features to “Hello World” 25
Set myInCopy = CreateObject("InCopy.Application")
Rem Disable normal error handling (trying to get a nonRem existent font can cause errors).
On Error Resume Next
Rem Enter the name of a font on your system, if necessary.
Set myFont = myInCopy.Fonts.Item("Arial")
If Error.Number <> 0 Then
Error.Clear
End If
Rem Resume normal error handling.
On Error Goto 0
Rem Get the active document and assign the result to the variable "myDocument"
Set myDocument = myInCopy.Documents.Item(1)
Set myStory = myDocument.Stories.Item(1)
Rem Change the font, size, and paragraph alignment.
If TypeName(myFont) <> "Nothing" Then
myStory.AppliedFont = myFont
End If
myStory.PointSize = 48
myStory.Justification = idJustification.idCenterAlign
Rem Enter the note at the last insertion point of the story.
Set myInsertionPoint = myStory.InsertionPoints.Item(-1)
Set myNote = myInsertionPoint.Notes.Add
myNote.Texts.Item(1).Contents = "This is a Note."
4. Save the text as a plain-text file with the file extension .vbs in the Scripts folder (see “Installing scripts”
on page 11).
Double-click the script name in the Scripts panel to run the new script.
3
Chapter Update Status
CS6 Edited “Script versioning” on page 27 and its three subsections have been updated, corrected, and clarified.
Scripting Features
This chapter covers scripting techniques that relate to InCopy’s scripting environment. Almost every other
object in the InCopy scripting model controls a feature that can change a document or the application
defaults. By contrast, the features in this chapter control how scripts operate.
This document discusses the following:
The ScriptPreferences object and its properties.
Getting a reference to the executing script.
Running scripts in prior versions of the scripting object model.
Using the DoScript method to run scripts.
Running scripts at InCopy start-up.
We assume that you have already read Chapter 2, “Getting Started” and know how to write, install, and run
InCopy scripts in the scripting language of your choice.
Script preferences
The ScriptPreferences object provides objects and properties related to the way InCopy runs scripts.
The following table provides more detail on each property of the ScriptPreferences object:
Property Description
EnableRedraw Turns screen redraw on or off while a script is running from the Scripts
ScriptsFolder The path to the scripts folder.
ScriptsList A list of the available scripts. This property is an array of arrays, in the
panel.
following form:
[[fileName, filePath], …]
Where fileName is the name of the script file and filePath is the full path
to the script. You can use this feature to check for the existence of a script
in the installed set of scripts.
26
Scripting Features Getting the current script 27
Property Description
UserInteractionLevel This property controls the alerts and dialogs that InCopy presents to the
user. When you set this property to
idUserInteractionLevels.idNeverInteract, InCopy does not display
any alerts or dialogs; set it to
idUserInteractionLevels.idInteractWithAlerts to enable alerts but
disable dialogs; and set it to
idUserInteractionLevels.idInteractWithAll to restore the normal
display of alerts and dialogs. The ability to turn off alert displays is very
useful when you are opening documents via script; often, InCopy displays
an alert for missing fonts or linked graphics files. To avoid this alert, set the
user-interaction level to
idUserInteractionLevels.idNeverInteract
before opening the document, then restore user interaction (set the
property to
idUserInteractionLevels.idInteractWithAll) before
completing script execution.
Version The version of the scripting environment in use. For more information, see
“Script versioning” on page 27
. Note that this property is not the same as
the version of the application.
Getting the current script
You can get a reference to the current script using the ActiveScript property of the application object.
You can use this property to help you locate files and folders relative to the script, as shown in the
following example (from the ActiveScript tutorial script):
Set myInCopy = CreateObject("InCopy.Application")
myActiveScript = myInCopy.ActiveScript
MsgBox ("The current script is: " & myActiveScript)
Set myFileSystemObject = CreateObject("Scripting.FileSystemObject")
myParentFolder = myFileSystemObject.GetFile(myActiveScript).ParentFolder
MsgBox ("The folder containing the active script is: " & myParentFolder)
When you debug scripts using a script editor, the ActiveScript property returns an error. Only scripts run
from the Scripts palette appear in the
Script versioning
InCopy can run scripts using earlier versions of the InCopy scripting object model. To run an older script in
a newer version of InCopy, you must consider the following:
Targeting — Scripts must be targeted to the InCopy version in which they are being run (that is, the
current version). The mechanics of targeting are language specific as described in
page 28.
ActiveScript property.
“Targeting” on
Compilation — This involves mapping the names in the script to the underlying script IDs, which are
what InCopy understands. The mechanics of compilation are language specific as described in
“Compilation” on page 28.
Interpretation — This involves matching the IDs to the appropriate request handler within InCopy so
that InCopy correctly interprets a script written for an earlier version of the scripting object model. To
do this, either explicitly set the application’s script preferences to the old object model within the
Scripting Features Script versioning 28
script (as shown in “Interpretation” on page 28) or run the script from a folder in the Scripts panel
folder as follows:
Folder For InCopy version of scripts
Version 8.0 Scripts
Version 7.0 Scripts
Version 6.0 Scripts
Version 5.0 Scripts
Version 2.0 Scripts
Targeting
A script must always target the version of InCopy under which it is running (the current version), either
explicitly or implicitly. Targeting is implicit when the script is launched from the Scripts panel.
Otherwise, explicit targeting for Visual Basic applications and VBScripts is done using the CreateObject
method:
Rem Target InCopy CS6 Roman:
Set myApp = CreateObject("InCopy.Application.CS6")
Rem Target InCopy CS6 J:
Set myApp = CreateObject("InCopy.Application.CS6_J")
Rem Target the last version of InCopy that was launched:
Set myApp = CreateObject("InCopy.Application")
CS6
CS5 and CS5.5
CS4
CS3
CS2
Compilation
Compilation of Visual Basic applications may be versioned by referencing an earlier version of the type
library. To generate an earlier version of the type library, use the PublishTerminology method, which is
exposed on the Application object. The type library is generated into a folder (named with the version of
the DOM) that is in the
generate the CS5 dictionary into the
Data\Adobe\InCopy\Version 8.0\<locale>\Scripting Support\7.0 folder:
Set myApp = CreateObject("InCopy.Application")
Rem Publish the InCopy CS5 type library (version 7.0 DOM)
myApp.PublishTerminology(7.0)
VBScripts are not precompiled. For compilation, InCopy generates and references the appropriate type
library automatically, based on the version of the DOM that is set for interpretation.
Interpretation
The InCopy application object contains a ScriptPreferences object, which allows a script to get or set
the version of the scripting object model to use for interpreting scripts. The version defaults to the current
version of the application and persists.
For example, to change the version of the scripting object model to CS5:
Scripting Support folder in your application’s preferences folder. For example, to
C:\Documents and Settings\<username>\Application
Scripting Features Using the DoScript method 29
Set myInCopy = CreateObject("InCopy.Application")
Rem Set to 7.0 DOM
myInCopy.ScriptPreferences.Version = 7.0
Using the DoScript method
The DoScript method gives a script a way to execute another script. The script can be a string of valid
scripting code or a file on disk. The script can be in the same scripting language as the current script or
another scripting language. The available languages vary by platform: on Mac OS, you can run either an
AppleScript or a JavaScript; on Windows, you can run a VBScript or a JavaScript.
DoScript method has many possible uses:
The
Running a script in another language that provides a feature missing in your main scripting language.
For example, VBScript lacks the ability to display a file or folder browser, which JavaScript has.
AppleScript can be very slow to compute trigonometric functions (sine and cosine), but JavaScript
performs these calculations rapidly. JavaScript does not have a way to query Microsoft® Excel for the
contents of a specific spreadsheet cell, but both AppleScript and VBScript have this capability. In all
these examples, the
to overcome a limitation of the language used for the body of the script.
DoScript method can execute a snippet of scripting code in another language,
Creating a script “on the fly.” Your script can create a script (as a string) during its execution, which it
can then execute using the
DoScript method. This is a great way to create a custom dialog or panel
based on the contents of the selection or the attributes of objects the script creates.
Embedding scripts in objects. Scripts can use the DoScript method to run scripts that were saved as
strings in the
label property of objects. Using this technique, an object can contain a script that
controls its layout properties or updates its content according to certain parameters. Scripts also can
be embedded in XML elements as an attribute of the element or as the contents of an element. See
“Running scripts at start-up” on page 30.
Sending parameters to DoScript
To send a parameter to a script executed by DoScript, use the following form (from the
DoScriptParameters tutorial script):
Set myInCopy = CreateObject("InCopy.Application")
myJavaScript = "alert(""First argument: "" + arguments[0] + ""\rSecond argument: "" +
arguments[1]);"
myInCopy.DoScript myJavaScript, idScriptLanguage.idJavascript, Array("Hello from
DoScript", "Your message here.")
myVBScript = "msgbox arguments(1), vbOKOnly, ""First argument: "" & arguments(0)"
myInCopy.DoScript myVBScript, idScriptLanguage.idVisualBasic, Array("Hello from
DoScript", "Your message here.")
Returning values from DoScript
To return a value from a script executed by DoScript, you can use the ScriptArgs (short for “script
arguments”) object of the application. The following script fragment shows how to do this (for the
complete script, see the DoScriptReturnValue tutorial script):
Scripting Features Running scripts at start-up 30
Set myInCopy = CreateObject("InCopy.Application")
myJavaScript = "app.scriptArgs.setValue(""ScriptArgumentA"", ""This is the first
script argument value."");" & vbCr
myJavaScript = myJavaScript & "app.scriptArgs.setValue(""ScriptArgumentB"", ""This is
the second script argument value."");" & vbCr
myInCopy.DoScript myJavaScript, idScriptLanguage.idJavascript
myScriptArgumentA = myInCopy.ScriptArgs.GetValue("ScriptArgumentA")
myScriptArgumentB = myInCopy.ScriptArgs.GetValue("ScriptArgumentB")
MsgBox "ScriptArgumentA: " & myScriptArgumentA & vbCr & "ScriptArgumentB: " &
myScriptArgumentB
myVBScript = "Set myInCopy = CreateObject(""InCopy.Application"")" & vbCr
myVBScript = myVBScript & "myInCopy.ScriptArgs.SetValue ""ScriptArgumentA"", ""This is
the first script argument value.""" & vbCr
myVBScript = myVBScript & "myInCopy.ScriptArgs.SetValue ""ScriptArgumentB"", ""This is
the second script argument value."""
myInCopy.DoScript myVBScript, idScriptLanguage.idVisualBasic
myScriptArgumentA = myInCopy.ScriptArgs.GetValue("ScriptArgumentA")
myScriptArgumentB = myInCopy.ScriptArgs.GetValue("ScriptArgumentB")
MsgBox "ScriptArgumentA: " & myScriptArgumentA & vbCr & "ScriptArgumentB: " &
myScriptArgumentB
Running scripts at start-up
To run a script when InCopy starts, put the script in the Startup Scripts folder in the Scripts folder (for more
information, see “Installing scripts” on page 11
).
Loading...