Adobe InDesign CS4 User guide

ADOBE

®

INDESIGN

®

CS4

ADOBE INDESIGN CS4 PRODUCTS

PROGRAMMING GUIDE

Adobe InDesign CS4 Products Programming Guide

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, Acrobat, Bridge, Creative Suite, Illustrator, InCopy, InDesign, Photoshop, and Reader are either registered trademarks or trademarks of

Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are either 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. Java is a trademark of Sun Microsystems, Incorporated 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.

3

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

For experienced InDesign developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

For new InDesign developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Persistent Data and Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . 29

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Persistent objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Using persistent objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Implementing persistent objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

IPMStream methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Implementing a new stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Missing plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Warning levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Missing plug-in alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Guidelines for handling a missing plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Data handling for missing plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Conversion of persistent data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

When to convert persistent data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Converting data with the conversion manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Converting data without the conversion manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

PluginVersion resource, format numbers, and their macros . . . . . . . . . . . . . . . . . . . . . . 53

Setting up resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

SchemaList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

DirectiveList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Advanced schema topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Arrays of values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

FieldArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Conditional-field inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Contents

4 Adobe InDesign CS4 Products Programming Guide

Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Command pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Databases and undoability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Command parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Command undoability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Command processing and the CmdUtils class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Command sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Command managers, databases, and undo support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

The command processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Scheduled commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Snapshots and interface implementation types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Command history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Merging changes with an existing step in the command history . . . . . . . . . . . . . . . . . . . 81

Undo and redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Extension patterns involved in undo and redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Notification within commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Protective shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Key client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Command facades and utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Command-processing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Error string service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Persistent interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Persistent boss. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Snapshot interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Inval handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Snapshot view interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Adobe InDesign CS4 Products Programming Guide 5

Contents

Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Observer pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Responder pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Observers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103

Observers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Message protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Subject and observer types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Regular and lazy notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Observers and undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Relating observers to subjects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

Document notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Observers and the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Responders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

Signal manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

Responders and the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

Responders and global error state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118

Ordering of responders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118

Responders and undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Key client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

User-interface widget observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

Model observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

Selection observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

Document observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

Active context observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

Subject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Selection format and target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Design patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126

Selection architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127

Abstract selection bosses and suites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Contents

6 Adobe InDesign CS4 Products Programming Guide

Concrete selection bosses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Layout selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Table selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133

Text selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134

Galley text selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Story-editor text selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Note text selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

XML selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138

Document defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

Application defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

Integrator suites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142

CSB suites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142

Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Suites and the user interface: an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Basic client-code responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Selection-observer responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Custom-suite responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144

Custom suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Selection extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Selection change notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146

Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Communication with Integrator suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Selection observers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147

Selection-utility interface (ISelectionUtils) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

Layout Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150

Documents and the layout hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152

Parent and child objects and IHierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

Spreads and pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157

Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Layers in a basic document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162

Layer options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165

Navigating spread content using ISpread. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Adobe InDesign CS4 Products Programming Guide 7

Contents

Master spreads and master pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

Master spreads and master pages in a basic document . . . . . . . . . . . . . . . . . . . . . . . . .169

Master-page item overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Basing one master page on another . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172

Page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Frames and paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173

Graphic page items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177

Text page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177

Interactive page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178

Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178

Abstract page items and kPageItemBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179

Guides and grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180

Ruler guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180

Margin and column guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180

Document grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

Baseline grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

Snap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181

Layout-related preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182

Coordinate systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Transformation matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183

Pasteboard coordinate space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184

Inner coordinate space and parent coordinate space . . . . . . . . . . . . . . . . . . . . . . . . . .185

Spread coordinate space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188

Page coordinate space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

Page-item coordinate space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

Bounding box and IGeometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

Transformation and ITransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191

Measurement units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192

Geometrical data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

The layout presentation and view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

Layout presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

Layout view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196

Current spread and active layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197

Layout-presentation and layout-view coordinate spaces . . . . . . . . . . . . . . . . . . . . . . . .198

Key client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202

New-page-item responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202

Custom page item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203

Custom unit-of-measure service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203

Contents

8 Adobe InDesign CS4 Products Programming Guide

Commands that manipulate page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204

Page-item creation commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204

Page-item update commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205

Page-item deletion commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209

Graphics Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211

Path concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211

Paths data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213

Path operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215

Graphic page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

Graphic page-item types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

Graphic page-item settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219

Graphic page-item data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223

Graphic page-item examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226

Graphics import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238

Export to graphics file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243

Colors and swatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246

Swatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250

Solid colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250

Gradients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

Swatch lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

Inks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

Color management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252

ICC profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

Color-management workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

Data model for color management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

Graphic attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256

Graphic-attribute data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256

Representation of graphic attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258

Graphic styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258

Graphic state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259

Mapping graphic attributes between domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260

Rendering attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261

Color-rendering attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261

Gradient attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

Adobe InDesign CS4 Products Programming Guide 9

Contents

Stroke effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

Path stroker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

Path corners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

Path-end strokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

Transparency effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

Flattening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272

Transparency data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272

Data model for drawing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276

Presentation views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276

Graphics context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277

Viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277

Dynamics of drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278

Drawing the layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278

Drawing page items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281

Drawing in user-interface widget windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283

Offscreen drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284

Client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285

Path-related client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285

Graphic page-item client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286

Key color-related client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287

Graphic-attribute client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Custom graphic attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Custom path-stroker effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Custom corner effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

Custom path-end effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

Custom page-item adornments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

Custom drawing-event handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294

Swatch-list state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296

Initial state of swatch list and ink list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296

State of swatch list and ink list after adding a custom stop color . . . . . . . . . . . . . . . . . . .297

Swatch list and ink list after adding a gradient swatch. . . . . . . . . . . . . . . . . . . . . . . . . .299

Swatch list and ink list after applying an unnamed color to an object . . . . . . . . . . . . . . . .300

Color spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300

Catalog of graphic attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .301

Mappings between attribute domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306

Spread-drawing sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307

Contents

10 Adobe InDesign CS4 Products Programming Guide

Controlling the settings in a graphics port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309

Drawing sequence for a page item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310

Text Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Text content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315

Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315

Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324

Class associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330

Text presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331

Text layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331

Text frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .331

Frame list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333

Threading and text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336

Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339

Span . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342

Text frames and the wax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343

Text-frame options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345

Text-frame geometry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345

Text Inset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346

Text wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347

Text on a path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350

The wax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354

Wax strand, wax line, and wax run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354

Examples of the wax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355

Text adornments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358

Text composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364

Phases of text composition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366

Damage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367

Recomposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369

Wax strand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370

Paragraph composers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371

Shuffling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371

Vertical justification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371

Background composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371

Recomposition transactional model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372

Recomposition notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372

Implementation notes for paragraph composers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372

Adobe InDesign CS4 Products Programming Guide 11

Contents

Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389

Font-subsystem architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390

Fonts within the document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392

Composite fonts and international-font issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397

Table structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397

Design and architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .402

Table model versus text model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .402

Table data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404

Cell data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406

Table attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407

Table and cell styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .409

Formatting tables, cells, and table text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413

Essential APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414

Table commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414

ITableSuite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414

ITableStyleSuite and ITableStylesFacade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415

ICellStyleSuite and ICellStylesFacade. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415

Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417

Printing is simply drawing to the printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417

Control can be shared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417

Inks and colors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417

Overprinting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418

Trapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418

Color management and proofing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418

Preflight and packaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418

Exporting to EPS and PDF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

Printing data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

Print settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419

Print preset styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420

Trap styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420

Utility APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420

The print action sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421

Common print interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .422

Contents

12 Adobe InDesign CS4 Products Programming Guide

Print user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423

Print dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423

Print Presets dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435

Extending the Print dialog box or the Print Presets selectable dialog box . . . . . . . . . . . . .435

Printing extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435

Print-setup provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435

Print-insert-PostScript proc provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436

Print-data helper-strategy provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437

Draw-event handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438

Printing solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438

Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438

Working with print-preset styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .439

Working with trap styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441

Participating in the print process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443

Bosses that aggregate IPrintData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448

Print-action and supporting commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448

Japanese page-mark files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .449

Exporting to EPS and PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450

Exporting to EPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450

Exporting to PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453

PDF Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

PDF import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455

PDF export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459

InDesign/InCopy document export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459

InDesign book export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468

Selected page-items export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .469

PDF-style import and export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .470

Adding, deleting, and editing styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471

Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472

How does the PDF export provider determine whether it should start the viewer

after the export? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472

How do I set the PDF clipboard setting as seen in the File Handling preferences? . . . . . . . .472

How do I control which layer of a document should be exported? . . . . . . . . . . . . . . . . . .472

How do I make the two-page spreads in my document export as two separate PDF pages? .473

Why does kPDFExportCmdBoss give me an assert after the command is processed

(ASSERT 'db != nil' in PDFExportController.cpp)? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473

How do I set up line ranges for output in InCopy Galley or Story mode? . . . . . . . . . . . . . .473

Is it possible to export only selected text from an InDesign document? . . . . . . . . . . . . . .473

Adobe InDesign CS4 Products Programming Guide 13

Contents

Implementing Preflight Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .475

About preflight in InDesign CS4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .475

About rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .475

Rule IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .476

Rule service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .476

IPreflightRuleService example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .477

Rule bosses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .478

IPreflightRuleVisitor interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .479

IPreflightRuleVisitor method examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .480

IPreflightRuleVisitor::GetClassesToVisit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .480

IPreflightRuleVisitor::Visit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .481

IPreflightRuleVisitor::AggregateResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483

IPreflightRuleVisitor::UpdateRuleData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .490

IPreflightRuleVisitor::ValidateRuleData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .490

More on specific objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491

Native, UID-based objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .491

Artwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .492

Text runs and ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .494

Tables, rows, columns, and cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .495

XML Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497

XML-based workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497

Using XML with InDesign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .498

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .498

XML features at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .499

XML extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .499

Tagging in tables and inline graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .499

Throw away unmatched existing (right). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .499

Throw away unmatched incoming (left). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Importing repeating elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Importing CALS table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Support for DOM core level 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Support table- and cell-styles import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Support XML-rules processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Snippets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500

Contents

14 Adobe InDesign CS4 Products Programming Guide

The user interface for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .501

Structure view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .501

Tags in layout view and story view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .501

Tags panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .502

Mapping between tags and styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .503

Validation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .504

Other. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .504

XML model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .505

Native document model and logical structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .505

Elements and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .505

Content items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .506

References to elements and content items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507

Document element and root element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .508

Backing store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509

Persistence and the backing store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510

Importing XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511

Import architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .512

Importing a minimal XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .515

Unplaced content versus placed content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518

XML template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519

Matching against an XML template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519

Importing repeating elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519

Throwing away unmatched existing elements on import (delete unmatched right). . . . . . .520

Throwing away unmatched incoming elements on XML import . . . . . . . . . . . . . . . . . . .522

Attribute-style mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .522

Creating links on XML import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .523

Sparse import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .523

Importing a CALS table as an InDesign table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .524

Support table and cell styles when importing an InDesign table . . . . . . . . . . . . . . . . . . .524

Exporting XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .524

Export architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .525

Document order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .526

Tagged graphic placeholder, exported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .527

Tagged text range, exported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .528

Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .529

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530

Tag-to-style mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .531

Style-to-tag mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .532

Adobe InDesign CS4 Products Programming Guide 15

Contents

Elements and content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .534

Tagged graphic placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .534

Tagged images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .536

Tagged stories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .537

Tagged text ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .538

Tagged inline graphics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .542

Tagged tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .543

DTD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .545

Processing instructions and comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .547

Structural (container) elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549

XML-related preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549

Workspace-level XML preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549

Service-level XML preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .551

Key client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .552

XML suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .552

Command facades and utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .553

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .553

XML acquirer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .553

XML transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .554

XMl-import matchmaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .555

Post-import responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .555

Custom suite for the structure view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556

SAX-content handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556

SAX DOM serializer handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557

Custom-tag service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557

SAX-entity resolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .557

XML-export handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558

Commands and notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558

Backing store and notification of changes in logical structure. . . . . . . . . . . . . . . . . . . . .558

Entities supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .559

Assets from XSLT example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .560

Limitations of the InDesign XML architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .561

Contents

16 Adobe InDesign CS4 Products Programming Guide

Scriptable Plug-in Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . 563

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .563

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565

Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565

Benefits of making a plug-in scriptable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565

Scripting and IDML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .566

Making a plug-in scriptable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .566

Tools for making a plug-in scriptable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .567

Scripting architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .567

Scripting DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .568

Versioning the scripting DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .569

Scripting plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .570

Script interaction with the scripting DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .571

Scripting process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572

Script managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .573

Scriptable plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .573

Scripting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .574

Script providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .574

Scriptable boss classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .574

How to make your plug-in scriptable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .575

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .575

Defining IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .576

Adding a new property to an existing script object . . . . . . . . . . . . . . . . . . . . . . . . . . .576

Adding a new event to an existing script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .576

Adding a new script object to make preferences scriptable . . . . . . . . . . . . . . . . . . . . . .577

Adding a new singleton script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .578

Adding a new script object to make a boss with a UID scriptable. . . . . . . . . . . . . . . . . . .578

Adding a new script object to make a boss with no UID scriptable. . . . . . . . . . . . . . . . . .579

Adding a new script object to make a C++ object with no boss scriptable . . . . . . . . . . . . .580

Adding a new script object to make a panel scriptable . . . . . . . . . . . . . . . . . . . . . . . . .581

Adding an error-string service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .582

Handling multiple concurrent requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .582

Reviewing scripting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .583

Running versioned scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .586

Supporting IDML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .588

Maintaining IDML forward and backward compatibility . . . . . . . . . . . . . . . . . . . . . . . .589

Verifying your plug-in’s data is round-tripped through IDML . . . . . . . . . . . . . . . . . . . . .590

Tips for debugging the scripting architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .591

Adobe InDesign CS4 Products Programming Guide 17

Contents

Scripting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .591

VersionedScriptElementInfo resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .592

Object element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .593

Event element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .595

Property element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .597

Struct element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .601

TypeDef element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .602

Enum element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603

Enumerator element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604

Metadata element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604

Provider element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .606

Suite element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .609

ScriptElementIDs, ScriptIDs, names, descriptions, and GUIDs . . . . . . . . . . . . . . . . . . . . .610

ScriptID/name registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .612

Scripting data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .615

Script-object inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .619

Overloading an existing event or property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .621

Versioning of scripting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .621

Client-specific scripting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .632

Elements that are not applicable to a particular object . . . . . . . . . . . . . . . . . . . . . . . . .638

Key scripting APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .639

Scripting DOM reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .641

Scripting DOM versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .641

Dumping the scripting DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .642

Snippet Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

Conceptual overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .643

Snippets as self-contained assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .643

Snippet types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .644

Features that depend on snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .644

User interface for snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .644

Drag and drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .644

Asset library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .645

Export snippet from selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .645

Snippet model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .645

INX, IDML, and snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .645

Boss DOM overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .646

Scripting DOM overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .647

From boss DOM to scripting DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .647

Contents

18 Adobe InDesign CS4 Products Programming Guide

Snippet types and policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .648

Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .648

Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .650

Snippet examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .652

Filled-rectangle snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .652

Image-item snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .657

XML element snippet, tagged placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .660

Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .663

Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .663

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .663

Extension patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664

Adding persistent data to snippet files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664

Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664

What is a snippet, and how do I create one? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664

What happens if I export a snippet of a placed image? . . . . . . . . . . . . . . . . . . . . . . . . .664

What features are based on snippets? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .665

How accurately is data round-tripped through snippets?. . . . . . . . . . . . . . . . . . . . . . . .665

When do I have to care about snippets?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .665

Can I export spreads or pages as snippets?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .665

Should we generate snippet files from scratch? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .665

Can I import a snippet directly into a library? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666

Can I import a snippet into the scrap database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666

Can we add our own new snippet types? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666

Shared Application Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667

How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .668

ISnippetExport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .668

IAppPrefsExportDelegate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .669

ISnippetImport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .669

IAppPrefsImportOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .669

IAppPrefsImportDelegate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .670

Adobe InDesign CS4 Products Programming Guide 19

Contents

Working with snippet APIs: frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . .670

How do I create streams for reading and writing snippets?. . . . . . . . . . . . . . . . . . . . . . .670

How do I limit my export to those items in the preference panel? . . . . . . . . . . . . . . . . . .670

How do I export all text styles, object styles, XML tags, or swatches in the

application workspace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671

How do I import a snippet into the application? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671

How do I control whether existing objects like paragraph styles are replaced or

deleted on import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671

How do I determine the correct ScriptID to use for a preference I’m trying to include

or exclude? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671

How do I know which list element types will be exported by default?. . . . . . . . . . . . . . . .671

User-Interface Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .673

Key concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .674

Design objectives for user-interface API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .674

Idioms and naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .674

Abstractions and re-use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .675

Widgets versus platform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .676

Commands, model plug-ins, and user-interface plug-ins . . . . . . . . . . . . . . . . . . . . . . .676

Suites and the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .677

Finding widgets in the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .678

Notifications about control events or changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .678

Sample user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .679

Type binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .680

Factorization of the user-interface model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .683

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .683

Control views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .684

Control data models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .684

Event handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685

Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685

Relevant design patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .686

Observer pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .686

How event handlers implement controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .687

The role of MVC in the user-interface model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .688

Chain of responsibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .689

Facade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .689

Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .690

Widget-observer pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .690

Persistence and widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .691

Contents

20 Adobe InDesign CS4 Products Programming Guide

Resource roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .692

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .692

OpenDoc framework (ODF) resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .693

Top-level framework resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .694

Localizing framework resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .694

Resource compilers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .695

Customizing a widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .696

Advanced event handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .696

Writing a proxy event handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .696

Watching events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .697

Key abstractions in the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .697

Suppressed User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .699

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .699

XML-based implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .700

XML file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .701

SuppressedWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .702

SuppressedAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .702

SuppressedMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .703

SuppressedDragDrop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .703

SuppressPlatformDialogControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .704

SuppressedUI tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .704

SuppressedUI tool limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .706

Working with the ISuppressedUI API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .706

Other user-interface “suppression” mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .707

Using Adobe File Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .709

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .709

Adobe File Library architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .711

Adobe File Library classes and utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .711

Common file API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .713

File API specific to InDesign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .714

Debugging IDFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .716

Porting guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .716

Creative Suite 2 porting concerns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .716

Creative Suite 3 porting concerns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .716

Adobe InDesign CS4 User guide

Related papers

Other documents