ADOBE SYSTEMS INCORPORATED
Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
(408) 536-6000
http://partners.adobe.com
bbc
Adobe Dialog Manage
r
MA
D
September, 2002
Adobe Dialog
Manager
Programmer’s Guide
and Reference
Copyright 2002 Adobe Systems Incorporated. All rights reserved.
NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in
hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying,
recording, or otherwise, without the prior written consent of the Adobe Systems Incorporated.
PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in the text are references to
the PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a
product trademark for Adobe Systems’ implementation of the PostScript language interpreter.
Except as otherwise stated, any reference to a “PostScript printing device,” “PostScript display device,” or similar item refers to a printing
device, display device or item (respectively) that contains PostScript technology created or licensed by Adobe Systems Incorporated
and not to devices or items that purport to be merely compatible with the PostScript language.
Adobe, the Adobe logo, Acrobat, the Acrobat logo, Acrobat Capture, Acrobat Catalog, Acrobat Exchange, Acrobat Reader, Acrobat
Search, Distiller, PostScript, and the PostScript logo are trademarks of Adobe Systems Incorporated.
Apple, Macintosh, and Power Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries.
PowerPC is a registered trademark of IBM Corporation in the United States. ActiveX, Microsoft, Windows, and Windows NT are either
registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. UNIX is a registered trademark
of The Open Group. All other trademarks are the property of their respective owners.
This publication and the information herein is furnished AS IS, 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, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims
any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights.
Adobe Dialog Manager Programmer’s Guide and Reference 3
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Accessing Suites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Supporting Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Chapter 1 ADM Overview . . . . . . . . . . . . . . . . . . . . . . . .25
About Adobe Dialog Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
ADM Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PICA Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
ADM Objects in General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
A Quick Summary of Using ADM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
The Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ADM Object Specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
ADM Dialog Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Dialog Item Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Composite Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ADM Item Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ADM Item Numeric Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ADM Lists and Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ADM Hierarchy Lists and List Entries . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Macintosh and Windows ADM Item Resource Lists . . . . . . . . . . . . . . . . . . . 56
Event Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Using Event Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Using Init Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using Drawer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using Notifier Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using Tracker Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using Destroy Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using Resizable Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Contents
4 Adobe Dialog Manager Programmer’s Guide and Reference
Custom Item Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Using Custom Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Using Timer Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Using the C++ Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Getting Started With ADM Plug-In Development . . . . . . . . . . . . . . . . . . . . . . 72
The General Development Process . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Chapter 2 Using ADM with Adobe Acrobat . . . . . . . . . . . . . . .75
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using ADM with Acrobat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Initializing ADM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Acquiring and Using ADM Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Using Modal Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Handling Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Macintosh Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Carbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
‘carb’ Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Development Environment and Documentation . . . . . . . . . . . . . . . . . . . . . 80
Chapter 3 Using ADM with Adobe Photoshop . . . . . . . . . . . . .81
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Frame Select Photoshop Plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Platform-Specific Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Acquiring the Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Building, Presenting, and Using the Dialog . . . . . . . . . . . . . . . . . . . . . . . . . 88
Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Chapter 4 Using ADM with Adobe Illustrator . . . . . . . . . . . . . .99
A Modeless Dialog Example Using Illustrator . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 5 Using ADM with Adobe After Effects . . . . . . . . . . . 113
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Implementation notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Easy_Cheese Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Chapter 6 The ADM Basic Suite . . . . . . . . . . . . . . . . . . . 115
Adobe Dialog Manager Programmer’s Guide and Reference 5
Contents
About the ADM Basic Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Accessing the Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
ADM Basic Suite Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Resource Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
sADMBasic->GetIndexString() . . . . . . . . . . . . . . . . . . . . . . . . . . .116
sADMBasic->SetPlatformCursor(). . . . . . . . . . . . . . . . . . . . . . . . . .117
User Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
sADMBasic->AboutBox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
sADMBasic->AreToolTipsEnabled(). . . . . . . . . . . . . . . . . . . . . . . . .118
sADMBasic->AreToolTipsSticky() . . . . . . . . . . . . . . . . . . . . . . . . . .119
sADMBasic->Beep(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
sADMBasic->ChooseColor() . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
sADMBasic->EnableToolTips() . . . . . . . . . . . . . . . . . . . . . . . . . . .120
sADMBasic->ErrorAlert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
sADMBasic->GetToolTipDelays() . . . . . . . . . . . . . . . . . . . . . . . . . .121
sADMBasic->HideToolTip() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
sADMBasic->LightweightErrorAlert() . . . . . . . . . . . . . . . . . . . . . . . .122
sADMBasic->MessageAlert() . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
sADMBasic->PluginAboutBox() . . . . . . . . . . . . . . . . . . . . . . . . . . .123
sADMBasic->QuestionAlert() . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
sADMBasic->SetAlertButtonText() . . . . . . . . . . . . . . . . . . . . . . . . .125
sADMBasic->ShowToolTip() . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
sADMBasic->StandardGetFileDialog() . . . . . . . . . . . . . . . . . . . . . . .126
sADMBasic->StandardGetDirectoryDialog() . . . . . . . . . . . . . . . . . . . .128
sADMBasic->StandardPutFileDialog() . . . . . . . . . . . . . . . . . . . . . . .129
sADMBasic->YesNoAlert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
sADMBasic->ADMColorToRGBColor() . . . . . . . . . . . . . . . . . . . . . . .131
sADMBasic->GetAppFPS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
sADMBasic->GetAppUnits(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
sADMBasic->GetDefaultIncrements() . . . . . . . . . . . . . . . . . . . . . . . .132
sADMBasic->GetLastADMError() . . . . . . . . . . . . . . . . . . . . . . . . . .133
sADMBasic->GetNumbersArePoints() . . . . . . . . . . . . . . . . . . . . . . .133
sADMBasic->GetPaletteLayoutBounds() . . . . . . . . . . . . . . . . . . . . . .134
sADMBasic->GetScreenDimensions() . . . . . . . . . . . . . . . . . . . . . . .134
sADMBasic->GetWorkspaceBounds() . . . . . . . . . . . . . . . . . . . . . . .135
sADMBasic->LookUpZString() . . . . . . . . . . . . . . . . . . . . . . . . . . .135
sADMBasic->SetAppFPS() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
sADMBasic->SetAppUnits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
sADMBasic->SetDefaultIncrements() . . . . . . . . . . . . . . . . . . . . . . . .137
sADMBasic->SetNumbersArePoints(). . . . . . . . . . . . . . . . . . . . . . . .138
sADMBasic->StringToValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
sADMBasic->ValueToString() . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Contextual Menu Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
sADMBasic->CreateMenu() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
