bc

JavaScript™ for Acrobat® API Reference

Adobe® Acrobat® SDK

April 2007 Version 8.1
© 2007 Adobe Systems Incorporated. All rights reserved.
Adobe® Acrobat® SDK 8.1 JavaScript for Acrobat API Reference for Microsoft® Windows® and Mac OS®.
Edition 2.0, April 2007
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, company logos and user names in sample material or sample forms included in this documentation
and/or software are for demonstration purposes only and are not intended to refer to any actual organization or persons.
Adobe, the Adobe logo, Acrobat, Distiller, FrameMaker, LiveCycle, PostScript and Reader are either registered trademarks or trademarks of
Adobe Systems Incorporated in the United States and/or other countries.
Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries.
JavaScript is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
All other trademarks are the property of their respective owners.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101,
consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R.
§12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable,
the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users
(a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA
95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if
appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of
1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60,
60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
 Contents

Preface ........................................................................................................................................ 28
What’s in this guide? ...................................................................................................................................................................28
Who should read this guide? ...................................................................................................................................................28
Related documentation .............................................................................................................................................................28
1 Introduction ............................................................................................................................... 30
Syntax ...............................................................................................................................................................................................30
Paths..................................................................................................................................................................................................31
Safe path..........................................................................................................................................................................................31
Privileged context ........................................................................................................................................................................31
Privileged versus non-privileged context ...........................................................................................................................32
User preferences...........................................................................................................................................................................32
Quick bars........................................................................................................................................................................................33
Domain names in code samples.............................................................................................................................................34
2 JavaScript API ............................................................................................................................ 35
ADBC .................................................................................................................................................................................................36
ADBC properties.....................................................................................................................................................................36
SQL types ............................................................................................................................................................................36
JavaScript types................................................................................................................................................................37
ADBC methods........................................................................................................................................................................38
getDataSourceList ...........................................................................................................................................................38
newConnection................................................................................................................................................................38
Alerter...............................................................................................................................................................................................40
Alerter methods......................................................................................................................................................................40
dispatch...............................................................................................................................................................................40
AlternatePresentation ................................................................................................................................................................43
AlternatePresentation properties ....................................................................................................................................43
active ....................................................................................................................................................................................43
type.......................................................................................................................................................................................43
AlternatePresentation methods .......................................................................................................................................44
start .......................................................................................................................................................................................44
stop .......................................................................................................................................................................................44
Annotation......................................................................................................................................................................................45
Annotation types ...................................................................................................................................................................45
Annotation properties..........................................................................................................................................................47
alignment ...........................................................................................................................................................................47
AP ..........................................................................................................................................................................................48
arrowBegin.........................................................................................................................................................................49
arrowEnd.............................................................................................................................................................................50
attachIcon...........................................................................................................................................................................50
author...................................................................................................................................................................................51
borderEffectIntensity .....................................................................................................................................................51
borderEffectStyle .............................................................................................................................................................52
callout ..................................................................................................................................................................................52
caretSymbol.......................................................................................................................................................................52

3
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 4

2 JavaScript API (Continued)

Annotation (Continued)
Annotation properties (Continued)
contents ..............................................................................................................................................................................53
creationDate......................................................................................................................................................................53
dash ......................................................................................................................................................................................54
delay .....................................................................................................................................................................................54
doc ........................................................................................................................................................................................55
doCaption...........................................................................................................................................................................56
fillColor ................................................................................................................................................................................56
gestures...............................................................................................................................................................................57
hidden..................................................................................................................................................................................57
inReplyTo............................................................................................................................................................................58
intent....................................................................................................................................................................................58
leaderExtend .....................................................................................................................................................................59
leaderLength .....................................................................................................................................................................59
lineEnding ..........................................................................................................................................................................60
lock........................................................................................................................................................................................60
modDate .............................................................................................................................................................................61
name.....................................................................................................................................................................................61
noteIcon ..............................................................................................................................................................................62
noView.................................................................................................................................................................................63
opacity .................................................................................................................................................................................63
page......................................................................................................................................................................................64
point .....................................................................................................................................................................................64
points ...................................................................................................................................................................................65
popupOpen .......................................................................................................................................................................66
popupRect..........................................................................................................................................................................66
print ......................................................................................................................................................................................67
quads....................................................................................................................................................................................67
rect ........................................................................................................................................................................................68
readOnly..............................................................................................................................................................................68
refType.................................................................................................................................................................................68
richContents ......................................................................................................................................................................69
richDefaults........................................................................................................................................................................70
rotate....................................................................................................................................................................................70
seqNum ...............................................................................................................................................................................71
soundIcon...........................................................................................................................................................................71
state ......................................................................................................................................................................................72
stateModel .........................................................................................................................................................................72
strokeColor.........................................................................................................................................................................72
style.......................................................................................................................................................................................73
subject .................................................................................................................................................................................73
textFont...............................................................................................................................................................................74
textSize ................................................................................................................................................................................75
toggleNoView ...................................................................................................................................................................75
type.......................................................................................................................................................................................76
vertices ................................................................................................................................................................................76
width ....................................................................................................................................................................................77
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 5

2 JavaScript API (Continued)

Annotation (Continued)
Annotation methods ............................................................................................................................................................77
destroy.................................................................................................................................................................................77
getProps..............................................................................................................................................................................78
getStateInModel ..............................................................................................................................................................79
setProps...............................................................................................................................................................................79
transitionToState .............................................................................................................................................................80
Annot3D ..........................................................................................................................................................................................82
Annot3D properties ..............................................................................................................................................................82
activated .............................................................................................................................................................................82
context3D...........................................................................................................................................................................82
innerRect.............................................................................................................................................................................83
name.....................................................................................................................................................................................83
page......................................................................................................................................................................................83
rect ........................................................................................................................................................................................84
app.....................................................................................................................................................................................................85
app properties.........................................................................................................................................................................85
activeDocs ..........................................................................................................................................................................85
calculate ..............................................................................................................................................................................86
constants ............................................................................................................................................................................86
focusRect ............................................................................................................................................................................87
formsVersion .....................................................................................................................................................................87
fromPDFConverters ........................................................................................................................................................88
fs.............................................................................................................................................................................................88
fullscreen ............................................................................................................................................................................89
language .............................................................................................................................................................................89
media ...................................................................................................................................................................................90
monitors..............................................................................................................................................................................90
numPlugIns........................................................................................................................................................................91
openInPlace .......................................................................................................................................................................91
platform...............................................................................................................................................................................92
plugIns .................................................................................................................................................................................92
printColorProfiles.............................................................................................................................................................93
printerNames ....................................................................................................................................................................93
runtimeHighlight .............................................................................................................................................................94
runtimeHighlightColor ..................................................................................................................................................94
thermometer .....................................................................................................................................................................94
toolbar .................................................................................................................................................................................95
toolbarHorizontal ............................................................................................................................................................95
toolbarVertical ..................................................................................................................................................................96
viewerType.........................................................................................................................................................................96
viewerVariation ................................................................................................................................................................97
viewerVersion....................................................................................................................................................................97
app methods ...........................................................................................................................................................................97
addMenuItem ...................................................................................................................................................................97
addSubMenu.....................................................................................................................................................................99
addToolButton............................................................................................................................................................... 100
alert.................................................................................................................................................................................... 101
beep................................................................................................................................................................................... 103
beginPriv.......................................................................................................................................................................... 104
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 6

2 JavaScript API (Continued)

app (Continued)
app methods (Continued)
browseForDoc................................................................................................................................................................ 104
clearInterval .................................................................................................................................................................... 106
clearTimeOut.................................................................................................................................................................. 106
endPriv.............................................................................................................................................................................. 106
execDialog....................................................................................................................................................................... 107
execMenuItem............................................................................................................................................................... 120
getNthPlugInName...................................................................................................................................................... 124
getPath ............................................................................................................................................................................. 124
goBack .............................................................................................................................................................................. 125
goForward....................................................................................................................................................................... 125
hideMenuItem ............................................................................................................................................................... 126
hideToolbarButton....................................................................................................................................................... 126
launchURL ....................................................................................................................................................................... 127
listMenuItems ................................................................................................................................................................ 127
listToolbarButtons ........................................................................................................................................................ 128
mailGetAddrs ................................................................................................................................................................. 129
mailMsg............................................................................................................................................................................ 130
newDoc ............................................................................................................................................................................ 131
newFDF ............................................................................................................................................................................ 133
openDoc .......................................................................................................................................................................... 133
openFDF........................................................................................................................................................................... 136
popUpMenu ................................................................................................................................................................... 136
popUpMenuEx............................................................................................................................................................... 137
removeToolButton....................................................................................................................................................... 139
response........................................................................................................................................................................... 139
setInterval........................................................................................................................................................................ 140
setTimeOut...................................................................................................................................................................... 141
trustedFunction............................................................................................................................................................. 143
trustPropagatorFunction ........................................................................................................................................... 146
app.media .................................................................................................................................................................................... 150
app.media properties ........................................................................................................................................................ 150
align ................................................................................................................................................................................... 150
canResize ......................................................................................................................................................................... 151
closeReason .................................................................................................................................................................... 151
defaultVisible.................................................................................................................................................................. 152
ifOffScreen....................................................................................................................................................................... 152
layout ................................................................................................................................................................................ 153
monitorType................................................................................................................................................................... 153
openCode........................................................................................................................................................................ 154
over .................................................................................................................................................................................... 155
pageEventNames.......................................................................................................................................................... 155
raiseCode ......................................................................................................................................................................... 156
raiseSystem ..................................................................................................................................................................... 156
renditionType................................................................................................................................................................. 157
status ................................................................................................................................................................................. 157
trace................................................................................................................................................................................... 158
version .............................................................................................................................................................................. 158
windowType................................................................................................................................................................... 159
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 7

2 JavaScript API (Continued)

app.media (Continued)
app.media methods........................................................................................................................................................... 159
addStockEvents............................................................................................................................................................. 159
alertFileNotFound ........................................................................................................................................................ 160
alertSelectFailed............................................................................................................................................................ 160
argsDWIM ........................................................................................................................................................................ 161
canPlayOrAlert............................................................................................................................................................... 161
computeFloatWinRect ................................................................................................................................................ 162
constrainRectToScreen............................................................................................................................................... 163
createPlayer .................................................................................................................................................................... 163
getAltTextData .............................................................................................................................................................. 165
getAltTextSettings........................................................................................................................................................ 166
getAnnotStockEvents ................................................................................................................................................. 167
getAnnotTraceEvents.................................................................................................................................................. 167
getPlayers ........................................................................................................................................................................ 167
getPlayerStockEvents.................................................................................................................................................. 168
getPlayerTraceEvents.................................................................................................................................................. 169
getRenditionSettings .................................................................................................................................................. 169
getURLData..................................................................................................................................................................... 169
getURLSettings.............................................................................................................................................................. 170
getWindowBorderSize................................................................................................................................................ 172
openPlayer ...................................................................................................................................................................... 172
removeStockEvents ..................................................................................................................................................... 174
startPlayer........................................................................................................................................................................ 174
Bookmark ..................................................................................................................................................................................... 175
Bookmark properties ......................................................................................................................................................... 175
children ............................................................................................................................................................................ 175
color................................................................................................................................................................................... 175
doc ..................................................................................................................................................................................... 176
name.................................................................................................................................................................................. 176
open................................................................................................................................................................................... 177
parent................................................................................................................................................................................ 177
style.................................................................................................................................................................................... 177
Bookmark methods............................................................................................................................................................ 178
createChild ...................................................................................................................................................................... 178
execute ............................................................................................................................................................................. 178
insertChild ....................................................................................................................................................................... 179
remove.............................................................................................................................................................................. 180
setAction.......................................................................................................................................................................... 180
catalog........................................................................................................................................................................................... 181
catalog properties............................................................................................................................................................... 181
isIdle................................................................................................................................................................................... 181
jobs..................................................................................................................................................................................... 181
catalog methods ................................................................................................................................................................. 182
getIndex ........................................................................................................................................................................... 182
remove.............................................................................................................................................................................. 182
CatalogJob................................................................................................................................................................................... 183
CatalogJob properties....................................................................................................................................................... 183
path.................................................................................................................................................................................... 183
type.................................................................................................................................................................................... 183
status ................................................................................................................................................................................. 183
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 8

2 JavaScript API (Continued)

Certificate ..................................................................................................................................................................................... 184
Certificate properties......................................................................................................................................................... 184
binary ................................................................................................................................................................................ 184
issuerDN ........................................................................................................................................................................... 184
keyUsage.......................................................................................................................................................................... 185
MD5Hash ......................................................................................................................................................................... 185
privateKeyValidityEnd................................................................................................................................................. 185
privateKeyValidityStart ............................................................................................................................................... 186
SHA1Hash........................................................................................................................................................................ 186
serialNumber.................................................................................................................................................................. 186
subjectCN ........................................................................................................................................................................ 187
subjectDN........................................................................................................................................................................ 187
ubRights........................................................................................................................................................................... 187
usage ................................................................................................................................................................................. 188
validityEnd....................................................................................................................................................................... 190
validityStart..................................................................................................................................................................... 190
Collab............................................................................................................................................................................................. 191
Collab methods ................................................................................................................................................................... 191
addStateModel .............................................................................................................................................................. 191
documentToStream..................................................................................................................................................... 192
removeStateModel ...................................................................................................................................................... 192
color ............................................................................................................................................................................................... 193
Color arrays ........................................................................................................................................................................... 193
color properties ................................................................................................................................................................... 193
color methods ...................................................................................................................................................................... 194
convert.............................................................................................................................................................................. 194
equal.................................................................................................................................................................................. 195
colorConvertAction .................................................................................................................................................................. 196
colorConvertAction properties ...................................................................................................................................... 196
action ................................................................................................................................................................................ 196
alias .................................................................................................................................................................................... 196
colorantName ................................................................................................................................................................ 197
convertIntent ................................................................................................................................................................. 197
convertProfile................................................................................................................................................................. 198
embed............................................................................................................................................................................... 198
isProcessColor................................................................................................................................................................ 198
matchAttributesAll....................................................................................................................................................... 199
matchAttributesAny .................................................................................................................................................... 200
matchIntent .................................................................................................................................................................... 200
matchSpaceTypeAll ..................................................................................................................................................... 201
matchSpaceTypeAny .................................................................................................................................................. 202
preserveBlack ................................................................................................................................................................. 202
useBlackPointCompensation ................................................................................................................................... 203
Column.......................................................................................................................................................................................... 204
Column properties.............................................................................................................................................................. 204
columnNum.................................................................................................................................................................... 204
name.................................................................................................................................................................................. 204
type.................................................................................................................................................................................... 204
typeName ........................................................................................................................................................................ 205
value .................................................................................................................................................................................. 205
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 9

2 JavaScript API (Continued)

ColumnInfo.................................................................................................................................................................................. 206
ColumnInfo properties...................................................................................................................................................... 206
name.................................................................................................................................................................................. 206
description ...................................................................................................................................................................... 206
type.................................................................................................................................................................................... 206
typeName ........................................................................................................................................................................ 207
Connection .................................................................................................................................................................................. 208
Connection methods......................................................................................................................................................... 208
close................................................................................................................................................................................... 208
getColumnList ............................................................................................................................................................... 208
getTableList .................................................................................................................................................................... 209
newStatement ............................................................................................................................................................... 209
console .......................................................................................................................................................................................... 210
console methods................................................................................................................................................................. 210
clear ................................................................................................................................................................................... 210
hide .................................................................................................................................................................................... 210
println ............................................................................................................................................................................... 210
show .................................................................................................................................................................................. 211
Data ................................................................................................................................................................................................ 212
Data properties .................................................................................................................................................................... 212
creationDate................................................................................................................................................................... 212
description ...................................................................................................................................................................... 212
MIMEType........................................................................................................................................................................ 213
modDate .......................................................................................................................................................................... 213
name.................................................................................................................................................................................. 213
path.................................................................................................................................................................................... 214
size ..................................................................................................................................................................................... 214
DataSourceInfo .......................................................................................................................................................................... 215
DataSourceInfo properties .............................................................................................................................................. 215
name.................................................................................................................................................................................. 215
description ...................................................................................................................................................................... 215
dbg.................................................................................................................................................................................................. 216
dbg properties ..................................................................................................................................................................... 216
bps...................................................................................................................................................................................... 216
dbg methods ........................................................................................................................................................................ 217
c........................................................................................................................................................................................... 217
cb ........................................................................................................................................................................................ 217
q .......................................................................................................................................................................................... 217
sb ........................................................................................................................................................................................ 218
si.......................................................................................................................................................................................... 219
sn ........................................................................................................................................................................................ 219
so ........................................................................................................................................................................................ 219
sv......................................................................................................................................................................................... 219
Dialog............................................................................................................................................................................................. 220
Dialog methods ................................................................................................................................................................... 220
enable ............................................................................................................................................................................... 220
end ..................................................................................................................................................................................... 220
load .................................................................................................................................................................................... 221
store................................................................................................................................................................................... 221
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 10

2 JavaScript API (Continued)

DirConnection ............................................................................................................................................................................ 222
DirConnection properties ................................................................................................................................................ 222
canList............................................................................................................................................................................... 222
canDoCustomSearch................................................................................................................................................... 222
canDoCustomUISearch .............................................................................................................................................. 223
canDoStandardSearch ................................................................................................................................................ 223
groups............................................................................................................................................................................... 224
name.................................................................................................................................................................................. 224
uiName ............................................................................................................................................................................. 224
DirConnection methods................................................................................................................................................... 225
search................................................................................................................................................................................ 225
setOutputFields............................................................................................................................................................. 226
Directory ....................................................................................................................................................................................... 228
Directory properties........................................................................................................................................................... 228
info ..................................................................................................................................................................................... 228
Directory methods.............................................................................................................................................................. 230
connect............................................................................................................................................................................. 230
Doc.................................................................................................................................................................................................. 232
Doc properties ..................................................................................................................................................................... 233
alternatePresentations ............................................................................................................................................... 233
author................................................................................................................................................................................ 234
baseURL............................................................................................................................................................................ 234
bookmarkRoot ............................................................................................................................................................... 234
calculate ........................................................................................................................................................................... 235
creationDate................................................................................................................................................................... 235
creator............................................................................................................................................................................... 236
dataObjects..................................................................................................................................................................... 236
delay .................................................................................................................................................................................. 237
dirty.................................................................................................................................................................................... 237
disclosed .......................................................................................................................................................................... 238
docID ................................................................................................................................................................................. 239
documentFileName ..................................................................................................................................................... 239
dynamicXFAForm ......................................................................................................................................................... 240
external............................................................................................................................................................................. 240
filesize ............................................................................................................................................................................... 241
hidden............................................................................................................................................................................... 241
hostContainer ................................................................................................................................................................ 242
icons .................................................................................................................................................................................. 242
info ..................................................................................................................................................................................... 243
innerAppWindowRect ................................................................................................................................................ 244
innerDocWindowRect................................................................................................................................................. 245
isModal ............................................................................................................................................................................. 245
keywords.......................................................................................................................................................................... 245
layout ................................................................................................................................................................................ 246
media ................................................................................................................................................................................ 246
metadata.......................................................................................................................................................................... 247
modDate .......................................................................................................................................................................... 248
mouseX............................................................................................................................................................................. 249
mouseY............................................................................................................................................................................. 249
noautocomplete ........................................................................................................................................................... 250
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 11

2 JavaScript API (Continued)

Doc (Continued)
Doc properties (Continued)
nocache............................................................................................................................................................................ 250
numFields........................................................................................................................................................................ 251
numPages........................................................................................................................................................................ 251
numTemplates............................................................................................................................................................... 252
path.................................................................................................................................................................................... 252
outerAppWindowRect ................................................................................................................................................ 253
outerDocWindowRect ................................................................................................................................................ 253
pageNum......................................................................................................................................................................... 253
pageWindowRect ......................................................................................................................................................... 254
permStatusReady ......................................................................................................................................................... 254
producer .......................................................................................................................................................................... 255
requiresFullSave............................................................................................................................................................ 255
securityHandler ............................................................................................................................................................. 255
selectedAnnots.............................................................................................................................................................. 256
sounds .............................................................................................................................................................................. 256
spellDictionaryOrder ................................................................................................................................................... 257
spellLanguageOrder.................................................................................................................................................... 257
subject .............................................................................................................................................................................. 258
templates......................................................................................................................................................................... 258
title ..................................................................................................................................................................................... 259
URL ..................................................................................................................................................................................... 259
viewState ......................................................................................................................................................................... 259
xfa ....................................................................................................................................................................................... 261
XFAForeground............................................................................................................................................................. 262
zoom.................................................................................................................................................................................. 263
zoomType........................................................................................................................................................................ 263
Doc methods ........................................................................................................................................................................ 264
addAnnot......................................................................................................................................................................... 264
addField ........................................................................................................................................................................... 266
addIcon............................................................................................................................................................................. 267
addLink............................................................................................................................................................................. 267
addRecipientListCryptFilter ...................................................................................................................................... 269
addRequirement ........................................................................................................................................................... 270
addScript.......................................................................................................................................................................... 271
addThumbnails.............................................................................................................................................................. 272
addWatermarkFromFile ............................................................................................................................................. 272
addWatermarkFromText............................................................................................................................................ 274
addWeblinks................................................................................................................................................................... 276
bringToFront .................................................................................................................................................................. 276
calculateNow.................................................................................................................................................................. 277
closeDoc........................................................................................................................................................................... 277
colorConvertPage......................................................................................................................................................... 278
createDataObject.......................................................................................................................................................... 279
createTemplate ............................................................................................................................................................. 280
deletePages .................................................................................................................................................................... 281
deleteSound ................................................................................................................................................................... 281
embedDocAsDataObject........................................................................................................................................... 282
embedOutputIntent.................................................................................................................................................... 282
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 12

2 JavaScript API (Continued)

Doc (Continued)
Doc methods (Continued)
encryptForRecipients .................................................................................................................................................. 283
encryptUsingPolicy ...................................................................................................................................................... 285
exportAsFDF ................................................................................................................................................................... 287
exportAsFDFStr ............................................................................................................................................................. 288
exportAsText .................................................................................................................................................................. 289
exportAsXFDF ................................................................................................................................................................ 290
exportAsXFDFStr........................................................................................................................................................... 291
exportDataObject......................................................................................................................................................... 292
exportXFAData .............................................................................................................................................................. 293
extractPages ................................................................................................................................................................... 295
flattenPages.................................................................................................................................................................... 296
getAnnot.......................................................................................................................................................................... 296
getAnnot3D .................................................................................................................................................................... 297
getAnnots........................................................................................................................................................................ 297
getAnnots3D .................................................................................................................................................................. 298
getColorConvertAction .............................................................................................................................................. 299
getDataObject ............................................................................................................................................................... 299
getDataObjectContents ............................................................................................................................................. 300
getField............................................................................................................................................................................. 301
getIcon.............................................................................................................................................................................. 302
getLegalWarnings ........................................................................................................................................................ 303
getLinks ............................................................................................................................................................................ 307
getNthFieldName ......................................................................................................................................................... 308
getNthTemplate............................................................................................................................................................ 309
getOCGs ........................................................................................................................................................................... 309
getOCGOrder ................................................................................................................................................................. 310
getPageBox..................................................................................................................................................................... 310
getPageLabel ................................................................................................................................................................. 311
getPageNthWord.......................................................................................................................................................... 311
getPageNthWordQuads............................................................................................................................................. 312
getPageNumWords ..................................................................................................................................................... 312
getPageRotation ........................................................................................................................................................... 313
getPageTransition ........................................................................................................................................................ 313
getPrintParams .............................................................................................................................................................. 314
getSound ......................................................................................................................................................................... 314
getTemplate ................................................................................................................................................................... 314
getURL .............................................................................................................................................................................. 315
gotoNamedDest............................................................................................................................................................ 316
importAnFDF.................................................................................................................................................................. 316
importAnXFDF............................................................................................................................................................... 317
importDataObject ........................................................................................................................................................ 317
importIcon....................................................................................................................................................................... 318
importSound .................................................................................................................................................................. 319
importTextData ............................................................................................................................................................. 320
importXFAData.............................................................................................................................................................. 321
insertPages...................................................................................................................................................................... 321
mailDoc ............................................................................................................................................................................ 322
mailForm.......................................................................................................................................................................... 323
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 13

2 JavaScript API (Continued)

Doc (Continued)
Doc methods (Continued)
movePage........................................................................................................................................................................ 324
newPage .......................................................................................................................................................................... 325
openDataObject............................................................................................................................................................ 325
print ................................................................................................................................................................................... 326
removeDataObject....................................................................................................................................................... 328
removeField.................................................................................................................................................................... 328
removeIcon..................................................................................................................................................................... 329
removeLinks ................................................................................................................................................................... 329
removeRequirement ................................................................................................................................................... 330
removeScript .................................................................................................................................................................. 330
removeTemplate .......................................................................................................................................................... 330
removeThumbnails...................................................................................................................................................... 331
removeWeblinks ........................................................................................................................................................... 331
replacePages .................................................................................................................................................................. 332
resetForm ........................................................................................................................................................................ 332
saveAs ............................................................................................................................................................................... 333
scroll .................................................................................................................................................................................. 335
selectPageNthWord..................................................................................................................................................... 336
setAction.......................................................................................................................................................................... 336
setDataObjectContents.............................................................................................................................................. 337
setOCGOrder .................................................................................................................................................................. 339
setPageAction................................................................................................................................................................ 339
setPageBoxes ................................................................................................................................................................. 340
setPageLabels ................................................................................................................................................................ 340
setPageRotations.......................................................................................................................................................... 341
setPageTabOrder.......................................................................................................................................................... 342
setPageTransitions ....................................................................................................................................................... 343
spawnPageFromTemplate ........................................................................................................................................ 343
submitForm .................................................................................................................................................................... 345
syncAnnotScan.............................................................................................................................................................. 349
Doc.media .................................................................................................................................................................................... 351
Doc.media properties........................................................................................................................................................ 351
canPlay.............................................................................................................................................................................. 351
Doc.media methods........................................................................................................................................................... 352
deleteRendition............................................................................................................................................................. 352
getAnnot.......................................................................................................................................................................... 352
getAnnots........................................................................................................................................................................ 353
getOpenPlayers............................................................................................................................................................. 354
getRendition................................................................................................................................................................... 355
newPlayer ........................................................................................................................................................................ 355
Embedded PDF .......................................................................................................................................................................... 357
Embedded PDF properties .............................................................................................................................................. 357
messageHandler ........................................................................................................................................................... 357
Embedded PDF methods................................................................................................................................................. 358
postMessage................................................................................................................................................................... 358
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 14

2 JavaScript API (Continued)

Error................................................................................................................................................................................................ 359
Error properties.................................................................................................................................................................... 360
fileName........................................................................................................................................................................... 360
lineNumber ..................................................................................................................................................................... 360
extMessage ..................................................................................................................................................................... 360
message ........................................................................................................................................................................... 361
name.................................................................................................................................................................................. 361
Error methods....................................................................................................................................................................... 361
toString............................................................................................................................................................................. 361
event .............................................................................................................................................................................................. 362
Event type/name combinations .................................................................................................................................... 362
Document Event Processing........................................................................................................................................... 371
Form event processing ..................................................................................................................................................... 372
Multimedia event processing......................................................................................................................................... 372
event properties .................................................................................................................................................................. 373
change .............................................................................................................................................................................. 373
Example............................................................................................................................................................................ 373
changeEx ......................................................................................................................................................................... 373
commitKey ...................................................................................................................................................................... 375
fieldFull............................................................................................................................................................................. 375
keyDown.......................................................................................................................................................................... 376
modifier............................................................................................................................................................................ 377
name.................................................................................................................................................................................. 377
rc ......................................................................................................................................................................................... 378
richChange...................................................................................................................................................................... 378
richChangeEx ................................................................................................................................................................. 379
richValue .......................................................................................................................................................................... 380
selEnd................................................................................................................................................................................ 381
selStart .............................................................................................................................................................................. 381
shift .................................................................................................................................................................................... 382
source................................................................................................................................................................................ 382
target................................................................................................................................................................................. 383
targetName..................................................................................................................................................................... 383
type.................................................................................................................................................................................... 384
value .................................................................................................................................................................................. 384
willCommit...................................................................................................................................................................... 385
EventListener .............................................................................................................................................................................. 386
EventListener methods..................................................................................................................................................... 387
afterBlur............................................................................................................................................................................ 387
afterClose......................................................................................................................................................................... 387
afterDestroy .................................................................................................................................................................... 388
afterDone......................................................................................................................................................................... 388
afterError.......................................................................................................................................................................... 389
afterEscape...................................................................................................................................................................... 389
afterEveryEvent ............................................................................................................................................................. 389
afterFocus........................................................................................................................................................................ 390
afterPause........................................................................................................................................................................ 390
afterPlay ........................................................................................................................................................................... 391
afterReady ....................................................................................................................................................................... 391
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 15

2 JavaScript API (Continued)

EventListener (Continued)
EventListener methods (Continued)
afterScript ........................................................................................................................................................................ 392
afterSeek .......................................................................................................................................................................... 393
afterStatus ....................................................................................................................................................................... 394
afterStop .......................................................................................................................................................................... 394
onBlur................................................................................................................................................................................ 395
onClose............................................................................................................................................................................. 395
onDestroy ........................................................................................................................................................................ 396
onDone............................................................................................................................................................................. 396
onError.............................................................................................................................................................................. 396
onEscape.......................................................................................................................................................................... 397
onEveryEvent ................................................................................................................................................................. 397
onFocus............................................................................................................................................................................ 398
onGetRect........................................................................................................................................................................ 398
onPause............................................................................................................................................................................ 399
onPlay ............................................................................................................................................................................... 399
onReady ........................................................................................................................................................................... 399
onScript ............................................................................................................................................................................ 400
onSeek .............................................................................................................................................................................. 400
onStatus ........................................................................................................................................................................... 400
onStop .............................................................................................................................................................................. 401
Events ............................................................................................................................................................................................ 402
Events methods ................................................................................................................................................................... 402
add ..................................................................................................................................................................................... 402
dispatch............................................................................................................................................................................ 403
remove.............................................................................................................................................................................. 404
FDF.................................................................................................................................................................................................. 405
FDF properties...................................................................................................................................................................... 405
deleteOption .................................................................................................................................................................. 405
isSigned............................................................................................................................................................................ 405
numEmbeddedFiles..................................................................................................................................................... 406
FDF methods ........................................................................................................................................................................ 406
addContact ..................................................................................................................................................................... 406
addEmbeddedFile ........................................................................................................................................................ 407
addRequest..................................................................................................................................................................... 408
close................................................................................................................................................................................... 408
mail .................................................................................................................................................................................... 409
save .................................................................................................................................................................................... 410
signatureClear................................................................................................................................................................ 410
signatureSign ................................................................................................................................................................. 411
signatureValidate.......................................................................................................................................................... 412
Field................................................................................................................................................................................................ 413
Field versus widget attributes ........................................................................................................................................ 414
Field properties.................................................................................................................................................................... 415
alignment ........................................................................................................................................................................ 415
borderStyle ..................................................................................................................................................................... 415
buttonAlignX.................................................................................................................................................................. 416
buttonAlignY.................................................................................................................................................................. 417
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 16

2 JavaScript API (Continued)

Field (Continued)
Field properties (Continued)
buttonFitBounds........................................................................................................................................................... 418
buttonPosition............................................................................................................................................................... 418
buttonScaleHow ........................................................................................................................................................... 419
buttonScaleWhen......................................................................................................................................................... 419
calcOrderIndex .............................................................................................................................................................. 420
charLimit .......................................................................................................................................................................... 421
comb ................................................................................................................................................................................. 421
commitOnSelChange.................................................................................................................................................. 422
currentValueIndices..................................................................................................................................................... 422
defaultStyle..................................................................................................................................................................... 424
defaultValue ................................................................................................................................................................... 425
doNotScroll ..................................................................................................................................................................... 425
doNotSpellCheck .......................................................................................................................................................... 426
delay .................................................................................................................................................................................. 426
display............................................................................................................................................................................... 427
doc ..................................................................................................................................................................................... 428
editable ............................................................................................................................................................................ 428
exportValues................................................................................................................................................................... 429
fileSelect........................................................................................................................................................................... 429
fillColor ............................................................................................................................................................................. 430
hidden............................................................................................................................................................................... 431
highlight........................................................................................................................................................................... 431
lineWidth ......................................................................................................................................................................... 432
multiline ........................................................................................................................................................................... 433
multipleSelection.......................................................................................................................................................... 433
name.................................................................................................................................................................................. 434
numItems......................................................................................................................................................................... 434
page................................................................................................................................................................................... 435
password.......................................................................................................................................................................... 436
print ................................................................................................................................................................................... 436
radiosInUnison............................................................................................................................................................... 436
readonly ........................................................................................................................................................................... 437
rect ..................................................................................................................................................................................... 437
required............................................................................................................................................................................ 438
richText............................................................................................................................................................................. 439
richValue .......................................................................................................................................................................... 440
rotation............................................................................................................................................................................. 441
strokeColor...................................................................................................................................................................... 442
style.................................................................................................................................................................................... 442
submitName ................................................................................................................................................................... 443
textColor .......................................................................................................................................................................... 444
textFont............................................................................................................................................................................ 444
textSize ............................................................................................................................................................................. 446
type.................................................................................................................................................................................... 446
userName ........................................................................................................................................................................ 447
value .................................................................................................................................................................................. 448
valueAsString ................................................................................................................................................................. 448
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 17

2 JavaScript API (Continued)

Field (Continued)
Field methods....................................................................................................................................................................... 449
browseForFileToSubmit............................................................................................................................................. 449
buttonGetCaption ........................................................................................................................................................ 449
buttonGetIcon ............................................................................................................................................................... 450
buttonImportIcon......................................................................................................................................................... 451
buttonSetCaption......................................................................................................................................................... 452
buttonSetIcon ................................................................................................................................................................ 452
checkThisBox.................................................................................................................................................................. 453
clearItems ........................................................................................................................................................................ 454
defaultIsChecked .......................................................................................................................................................... 454
deleteItemAt................................................................................................................................................................... 455
getArray............................................................................................................................................................................ 456
getItemAt......................................................................................................................................................................... 456
getLock............................................................................................................................................................................. 457
insertItemAt.................................................................................................................................................................... 457
isBoxChecked ................................................................................................................................................................. 458
isDefaultChecked.......................................................................................................................................................... 458
setAction.......................................................................................................................................................................... 459
setFocus ........................................................................................................................................................................... 460
setItems............................................................................................................................................................................ 460
setLock.............................................................................................................................................................................. 461
signatureGetModifications ....................................................................................................................................... 462
signatureGetSeedValue.............................................................................................................................................. 464
signatureInfo .................................................................................................................................................................. 464
signatureSetSeedValue .............................................................................................................................................. 465
signatureSign ................................................................................................................................................................. 473
signatureValidate.......................................................................................................................................................... 475
FullScreen..................................................................................................................................................................................... 477
FullScreen properties......................................................................................................................................................... 477
backgroundColor.......................................................................................................................................................... 477
clickAdvances................................................................................................................................................................. 477
cursor ................................................................................................................................................................................ 478
defaultTransition........................................................................................................................................................... 478
escapeExits...................................................................................................................................................................... 479
isFullScreen ..................................................................................................................................................................... 479
loop.................................................................................................................................................................................... 479
timeDelay ........................................................................................................................................................................ 480
transitions........................................................................................................................................................................ 480
usePageTiming.............................................................................................................................................................. 481
useTimer .......................................................................................................................................................................... 481
global............................................................................................................................................................................................. 482
Creating global properties............................................................................................................................................... 482
Deleting global properties .............................................................................................................................................. 483
Global object security policy........................................................................................................................................... 483
global methods.................................................................................................................................................................... 484
setPersistent ................................................................................................................................................................... 484
subscribe.......................................................................................................................................................................... 484
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 18

2 JavaScript API (Continued)

HostContainer ............................................................................................................................................................................ 486
HostContainer properties ................................................................................................................................................ 486
messageHandler ........................................................................................................................................................... 486
HostContainer methods ................................................................................................................................................... 488
postMessage................................................................................................................................................................... 488
Icon ................................................................................................................................................................................................. 489
Icon Stream.................................................................................................................................................................................. 490
identity .......................................................................................................................................................................................... 491
identity properties.............................................................................................................................................................. 491
corporation ..................................................................................................................................................................... 491
email.................................................................................................................................................................................. 491
loginName....................................................................................................................................................................... 491
name.................................................................................................................................................................................. 492
Index .............................................................................................................................................................................................. 493
Index properties .................................................................................................................................................................. 493
available ........................................................................................................................................................................... 493
name.................................................................................................................................................................................. 493
path.................................................................................................................................................................................... 494
selected ............................................................................................................................................................................ 494
Index methods ..................................................................................................................................................................... 494
build................................................................................................................................................................................... 494
Link ................................................................................................................................................................................................. 496
Link properties ..................................................................................................................................................................... 496
borderColor .................................................................................................................................................................... 496
borderWidth ................................................................................................................................................................... 496
highlightMode............................................................................................................................................................... 496
rect ..................................................................................................................................................................................... 497
Link methods........................................................................................................................................................................ 497
setAction.......................................................................................................................................................................... 497
Marker............................................................................................................................................................................................ 498
Marker properties ............................................................................................................................................................... 498
frame ................................................................................................................................................................................. 498
index.................................................................................................................................................................................. 498
name.................................................................................................................................................................................. 498
time.................................................................................................................................................................................... 499
Markers.......................................................................................................................................................................................... 500
Markers properties.............................................................................................................................................................. 500
player................................................................................................................................................................................. 500
Markers methods ................................................................................................................................................................ 500
get ...................................................................................................................................................................................... 500
MediaOffset ................................................................................................................................................................................. 502
MediaOffset properties..................................................................................................................................................... 502
frame ................................................................................................................................................................................. 502
marker............................................................................................................................................................................... 502
time.................................................................................................................................................................................... 503
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 19

2 JavaScript API (Continued)

MediaPlayer................................................................................................................................................................................. 504
MediaPlayer properties..................................................................................................................................................... 504
annot ................................................................................................................................................................................. 504
defaultSize....................................................................................................................................................................... 504
doc ..................................................................................................................................................................................... 505
events................................................................................................................................................................................ 505
hasFocus .......................................................................................................................................................................... 505
id ......................................................................................................................................................................................... 506
innerRect.......................................................................................................................................................................... 506
isOpen............................................................................................................................................................................... 507
isPlaying ........................................................................................................................................................................... 507
markers............................................................................................................................................................................. 507
outerRect ......................................................................................................................................................................... 508
page................................................................................................................................................................................... 508
settings ............................................................................................................................................................................. 509
uiSize ................................................................................................................................................................................. 509
visible ................................................................................................................................................................................ 510
MediaPlayer methods ....................................................................................................................................................... 511
close................................................................................................................................................................................... 511
open................................................................................................................................................................................... 511
pause................................................................................................................................................................................. 512
play..................................................................................................................................................................................... 512
seek.................................................................................................................................................................................... 513
setFocus ........................................................................................................................................................................... 514
stop .................................................................................................................................................................................... 515
triggerGetRect ............................................................................................................................................................... 515
where ................................................................................................................................................................................ 516
MediaReject................................................................................................................................................................................. 517
MediaReject properties..................................................................................................................................................... 517
rendition .......................................................................................................................................................................... 517
MediaSelection........................................................................................................................................................................... 518
MediaSelection properties .............................................................................................................................................. 518
selectContext ................................................................................................................................................................. 518
players............................................................................................................................................................................... 519
rejects................................................................................................................................................................................ 519
rendition .......................................................................................................................................................................... 520
MediaSettings............................................................................................................................................................................. 521
MediaSettings properties................................................................................................................................................. 521
autoPlay ........................................................................................................................................................................... 521
baseURL............................................................................................................................................................................ 521
bgColor............................................................................................................................................................................. 522
bgOpacity ........................................................................................................................................................................ 522
data .................................................................................................................................................................................... 523
duration............................................................................................................................................................................ 523
endAt................................................................................................................................................................................. 524
floating ............................................................................................................................................................................. 525
layout ................................................................................................................................................................................ 526
monitor............................................................................................................................................................................. 526
monitorType................................................................................................................................................................... 527
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 20

2 JavaScript API (Continued)

MediaSettings (Continued)
MediaSettings properties (Continued)
page................................................................................................................................................................................... 528
palindrome...................................................................................................................................................................... 528
players............................................................................................................................................................................... 529
rate ..................................................................................................................................................................................... 530
repeat................................................................................................................................................................................ 530
showUI.............................................................................................................................................................................. 531
startAt ............................................................................................................................................................................... 531
visible ................................................................................................................................................................................ 532
volume.............................................................................................................................................................................. 533
windowType................................................................................................................................................................... 533
Monitor ......................................................................................................................................................................................... 535
Monitor properties ............................................................................................................................................................. 535
colorDepth ...................................................................................................................................................................... 535
Example............................................................................................................................................................................ 535
isPrimary .......................................................................................................................................................................... 535
Example............................................................................................................................................................................ 536
rect ..................................................................................................................................................................................... 536
workRect .......................................................................................................................................................................... 536
Monitors........................................................................................................................................................................................ 537
Monitors methods .............................................................................................................................................................. 537
bestColor.......................................................................................................................................................................... 537
bestFit ............................................................................................................................................................................... 538
desktop............................................................................................................................................................................. 538
document ........................................................................................................................................................................ 539
filter.................................................................................................................................................................................... 539
largest ............................................................................................................................................................................... 540
leastOverlap.................................................................................................................................................................... 540
mostOverlap................................................................................................................................................................... 541
nonDocument................................................................................................................................................................ 541
primary ............................................................................................................................................................................. 542
Example............................................................................................................................................................................ 542
secondary ........................................................................................................................................................................ 542
select ................................................................................................................................................................................. 542
tallest................................................................................................................................................................................. 543
widest................................................................................................................................................................................ 543
Net .................................................................................................................................................................................................. 545
Net properties ...................................................................................................................................................................... 545
SOAP.................................................................................................................................................................................. 545
Discovery ......................................................................................................................................................................... 546
HTTP .................................................................................................................................................................................. 546
Net methods ......................................................................................................................................................................... 547
Net.HTTP....................................................................................................................................................................................... 548
Net.HTTP methods.............................................................................................................................................................. 548
request.............................................................................................................................................................................. 548
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 21

2 JavaScript API (Continued)

OCG ................................................................................................................................................................................................ 551
OCG properties .................................................................................................................................................................... 551
constants ......................................................................................................................................................................... 551
initState ............................................................................................................................................................................ 552
locked................................................................................................................................................................................ 552
name.................................................................................................................................................................................. 552
state ................................................................................................................................................................................... 553
OCG methods ....................................................................................................................................................................... 554
getIntent .......................................................................................................................................................................... 554
setAction.......................................................................................................................................................................... 554
setIntent........................................................................................................................................................................... 555
PlayerInfo ..................................................................................................................................................................................... 556
PlayerInfo properties ......................................................................................................................................................... 556
id ......................................................................................................................................................................................... 556
mimeTypes...................................................................................................................................................................... 556
name.................................................................................................................................................................................. 557
version .............................................................................................................................................................................. 557
PlayerInfo methods ............................................................................................................................................................ 558
canPlay.............................................................................................................................................................................. 558
canUseData..................................................................................................................................................................... 558
honors............................................................................................................................................................................... 559
PlayerInfoList............................................................................................................................................................................... 563
PlayerInfoList methods ..................................................................................................................................................... 563
select ................................................................................................................................................................................. 563
PlugIn............................................................................................................................................................................................. 564
PlugIn properties................................................................................................................................................................. 564
certified ............................................................................................................................................................................ 564
loaded ............................................................................................................................................................................... 564
name.................................................................................................................................................................................. 564
path.................................................................................................................................................................................... 565
version .............................................................................................................................................................................. 565
PrintParams ................................................................................................................................................................................. 566
PrintParams properties ..................................................................................................................................................... 566
binaryOK .......................................................................................................................................................................... 566
bitmapDPI ....................................................................................................................................................................... 566
booklet.............................................................................................................................................................................. 567
colorOverride ................................................................................................................................................................. 569
colorProfile...................................................................................................................................................................... 570
constants ......................................................................................................................................................................... 571
downloadFarEastFonts............................................................................................................................................... 571
fileName........................................................................................................................................................................... 572
firstPage ........................................................................................................................................................................... 573
flags.................................................................................................................................................................................... 573
fontPolicy......................................................................................................................................................................... 575
gradientDPI..................................................................................................................................................................... 576
interactive........................................................................................................................................................................ 576
lastPage ............................................................................................................................................................................ 577
nUpAutoRotate ............................................................................................................................................................. 577
nUpNumPagesH............................................................................................................................................................ 578
nUpNumPagesV............................................................................................................................................................ 578
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 22

2 JavaScript API (Continued)

PrintParams (Continued)
PrintParams properties (Continued)
nUpPageBorder............................................................................................................................................................. 579
nUpPageOrder............................................................................................................................................................... 579
pageHandling ................................................................................................................................................................ 580
pageSubset ..................................................................................................................................................................... 581
printAsImage.................................................................................................................................................................. 582
printContent................................................................................................................................................................... 582
printerName ................................................................................................................................................................... 583
psLevel.............................................................................................................................................................................. 584
rasterFlags ....................................................................................................................................................................... 584
reversePages .................................................................................................................................................................. 586
tileLabel............................................................................................................................................................................ 586
tileMark............................................................................................................................................................................. 586
tileOverlap....................................................................................................................................................................... 587
tileScale ............................................................................................................................................................................ 587
transparencyLevel ........................................................................................................................................................ 588
usePrinterCRD................................................................................................................................................................ 588
useT1Conversion .......................................................................................................................................................... 589
RDN................................................................................................................................................................................................. 590
ReadStream ................................................................................................................................................................................. 592
Rendition ...................................................................................................................................................................................... 593
Rendition properties.......................................................................................................................................................... 593
altText ............................................................................................................................................................................... 593
doc ..................................................................................................................................................................................... 593
fileName........................................................................................................................................................................... 594
type.................................................................................................................................................................................... 594
uiName ............................................................................................................................................................................. 595
Rendition methods............................................................................................................................................................. 595
getPlaySettings.............................................................................................................................................................. 595
select ................................................................................................................................................................................. 596
testCriteria....................................................................................................................................................................... 597
Report ............................................................................................................................................................................................ 598
Report properties................................................................................................................................................................ 598
absIndent......................................................................................................................................................................... 598
color................................................................................................................................................................................... 598
size ..................................................................................................................................................................................... 599
style.................................................................................................................................................................................... 599
Report methods................................................................................................................................................................... 600
breakPage........................................................................................................................................................................ 600
divide................................................................................................................................................................................. 600
indent................................................................................................................................................................................ 600
mail .................................................................................................................................................................................... 601
open................................................................................................................................................................................... 601
outdent............................................................................................................................................................................. 602
Report ............................................................................................................................................................................... 602
save .................................................................................................................................................................................... 602
writeText .......................................................................................................................................................................... 603
Row................................................................................................................................................................................................. 605
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 23

2 JavaScript API (Continued)

ScreenAnnot ............................................................................................................................................................................... 606
ScreenAnnot properties ................................................................................................................................................... 606
altText ............................................................................................................................................................................... 606
alwaysShowFocus ........................................................................................................................................................ 606
display............................................................................................................................................................................... 607
doc ..................................................................................................................................................................................... 607
events................................................................................................................................................................................ 607
extFocusRect .................................................................................................................................................................. 608
innerDeviceRect ............................................................................................................................................................ 608
noTrigger ......................................................................................................................................................................... 609
outerDeviceRect............................................................................................................................................................ 609
page................................................................................................................................................................................... 610
player................................................................................................................................................................................. 610
rect ..................................................................................................................................................................................... 610
ScreenAnnot methods ...................................................................................................................................................... 611
hasFocus .......................................................................................................................................................................... 611
setFocus ........................................................................................................................................................................... 611
search............................................................................................................................................................................................. 612
search properties ................................................................................................................................................................ 612
attachments.................................................................................................................................................................... 612
available ........................................................................................................................................................................... 612
bookmarks....................................................................................................................................................................... 613
docInfo.............................................................................................................................................................................. 613
docText............................................................................................................................................................................. 613
docXMP ............................................................................................................................................................................ 614
ignoreAccents................................................................................................................................................................ 614
ignoreAsianCharacterWidth ..................................................................................................................................... 614
indexes ............................................................................................................................................................................. 615
jpegExif............................................................................................................................................................................. 615
legacySearch .................................................................................................................................................................. 615
markup ............................................................................................................................................................................. 616
matchCase....................................................................................................................................................................... 616
matchWholeWord ........................................................................................................................................................ 616
maxDocs .......................................................................................................................................................................... 617
objectMetadata ............................................................................................................................................................. 617
proximity.......................................................................................................................................................................... 617
proximityRange............................................................................................................................................................. 618
refine ................................................................................................................................................................................. 618
soundex............................................................................................................................................................................ 618
stem ................................................................................................................................................................................... 619
thesaurus ......................................................................................................................................................................... 619
wordMatching ............................................................................................................................................................... 620
search methods ................................................................................................................................................................... 620
addIndex .......................................................................................................................................................................... 620
getIndexForPath ........................................................................................................................................................... 621
query ................................................................................................................................................................................. 621
removeIndex .................................................................................................................................................................. 622
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 24

2 JavaScript API (Continued)

security.......................................................................................................................................................................................... 623
security constants ............................................................................................................................................................... 623
security properties.............................................................................................................................................................. 624
handlers............................................................................................................................................................................ 624
validateSignaturesOnOpen ...................................................................................................................................... 625
security methods................................................................................................................................................................. 626
chooseRecipientsDialog............................................................................................................................................. 626
chooseSecurityPolicy .................................................................................................................................................. 628
exportToFile.................................................................................................................................................................... 629
getHandler ...................................................................................................................................................................... 629
getSecurityPolicies....................................................................................................................................................... 630
importFromFile.............................................................................................................................................................. 632
SecurityHandler ......................................................................................................................................................................... 633
SecurityHandler properties ............................................................................................................................................. 633
appearances ................................................................................................................................................................... 633
digitalIDs.......................................................................................................................................................................... 634
directories........................................................................................................................................................................ 635
directoryHandlers......................................................................................................................................................... 635
docDecrypt ..................................................................................................................................................................... 636
docEncrypt ...................................................................................................................................................................... 636
isLoggedIn....................................................................................................................................................................... 636
loginName....................................................................................................................................................................... 637
loginPath.......................................................................................................................................................................... 637
name.................................................................................................................................................................................. 637
signAuthor ...................................................................................................................................................................... 638
signFDF............................................................................................................................................................................. 638
signInvisible.................................................................................................................................................................... 638
signValidate .................................................................................................................................................................... 639
signVisible ....................................................................................................................................................................... 639
uiName ............................................................................................................................................................................. 639
validateFDF ..................................................................................................................................................................... 640
SecurityHandler methods ................................................................................................................................................ 640
login................................................................................................................................................................................... 640
logout................................................................................................................................................................................ 643
newDirectory.................................................................................................................................................................. 643
newUser ........................................................................................................................................................................... 644
setPasswordTimeout................................................................................................................................................... 645
SecurityPolicy.............................................................................................................................................................................. 647
SecurityPolicy properties ................................................................................................................................................. 647
SignatureInfo .............................................................................................................................................................................. 648
SignatureInfo properties .................................................................................................................................................. 648
SOAP .............................................................................................................................................................................................. 657
SOAP properties .................................................................................................................................................................. 657
wireDump........................................................................................................................................................................ 657
SOAP methods ..................................................................................................................................................................... 657
connect............................................................................................................................................................................. 657
queryServices ................................................................................................................................................................. 660
resolveService ................................................................................................................................................................ 662
request.............................................................................................................................................................................. 664
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 25

2 JavaScript API (Continued)

SOAP (Continued)
SOAP methods (Continued)
response........................................................................................................................................................................... 672
streamDecode................................................................................................................................................................ 673
streamDigest .................................................................................................................................................................. 674
streamEncode ................................................................................................................................................................ 674
streamFromString ........................................................................................................................................................ 675
stringFromStream ........................................................................................................................................................ 675
Sound............................................................................................................................................................................................. 676
Sound properties ................................................................................................................................................................ 676
name.................................................................................................................................................................................. 676
Sound methods ................................................................................................................................................................... 676
pause................................................................................................................................................................................. 676
play..................................................................................................................................................................................... 676
stop .................................................................................................................................................................................... 676
Span................................................................................................................................................................................................ 677
Span properties ................................................................................................................................................................... 677
alignment ........................................................................................................................................................................ 677
fontFamily ....................................................................................................................................................................... 677
fontStretch ...................................................................................................................................................................... 678
fontStyle........................................................................................................................................................................... 678
fontWeight ...................................................................................................................................................................... 679
strikethrough.................................................................................................................................................................. 679
subscript........................................................................................................................................................................... 679
superscript....................................................................................................................................................................... 679
text ..................................................................................................................................................................................... 680
textColor .......................................................................................................................................................................... 681
textSize ............................................................................................................................................................................. 681
underline.......................................................................................................................................................................... 681
spell ................................................................................................................................................................................................ 683
spell properties .................................................................................................................................................................... 683
available ........................................................................................................................................................................... 683
dictionaryNames........................................................................................................................................................... 683
dictionaryOrder ............................................................................................................................................................. 684
domainNames................................................................................................................................................................ 684
languages ........................................................................................................................................................................ 685
languageOrder .............................................................................................................................................................. 686
spell methods....................................................................................................................................................................... 687
addDictionary ................................................................................................................................................................ 687
addWord .......................................................................................................................................................................... 687
check ................................................................................................................................................................................. 688
checkText......................................................................................................................................................................... 689
checkWord ...................................................................................................................................................................... 689
customDictionaryClose .............................................................................................................................................. 690
customDictionaryCreate ............................................................................................................................................ 691
customDictionaryDelete ............................................................................................................................................ 692
customDictionaryExport ............................................................................................................................................ 692
customDictionaryOpen .............................................................................................................................................. 693
ignoreAll........................................................................................................................................................................... 694
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 26

2 JavaScript API (Continued)

spell (Continued)
spell methods (Continued)
removeDictionary......................................................................................................................................................... 694
removeWord................................................................................................................................................................... 695
userWords ....................................................................................................................................................................... 695
Statement..................................................................................................................................................................................... 697
Statement properties ........................................................................................................................................................ 697
columnCount ................................................................................................................................................................. 697
rowCount......................................................................................................................................................................... 697
Statement methods ........................................................................................................................................................... 698
execute ............................................................................................................................................................................. 698
getColumn ...................................................................................................................................................................... 698
getColumnArray............................................................................................................................................................ 699
getRow ............................................................................................................................................................................. 699
nextRow ........................................................................................................................................................................... 700
TableInfo....................................................................................................................................................................................... 702
Template....................................................................................................................................................................................... 703
Template properties .......................................................................................................................................................... 703
hidden............................................................................................................................................................................... 703
name.................................................................................................................................................................................. 703
Template methods ............................................................................................................................................................. 704
spawn................................................................................................................................................................................ 704
Thermometer.............................................................................................................................................................................. 706
Thermometer properties.................................................................................................................................................. 706
cancelled.......................................................................................................................................................................... 706
duration............................................................................................................................................................................ 707
text ..................................................................................................................................................................................... 707
value .................................................................................................................................................................................. 707
Thermometer methods .................................................................................................................................................... 708
begin ................................................................................................................................................................................. 708
end ..................................................................................................................................................................................... 708
this .................................................................................................................................................................................................. 709
TTS .................................................................................................................................................................................................. 711
TTS properties ...................................................................................................................................................................... 711
available ........................................................................................................................................................................... 711
numSpeakers.................................................................................................................................................................. 711
pitch................................................................................................................................................................................... 712
soundCues....................................................................................................................................................................... 712
speaker ............................................................................................................................................................................. 712
speechCues..................................................................................................................................................................... 713
speechRate...................................................................................................................................................................... 713
volume.............................................................................................................................................................................. 713
TTS methods ......................................................................................................................................................................... 713
getNthSpeakerName................................................................................................................................................... 713
pause................................................................................................................................................................................. 714
qSilence............................................................................................................................................................................ 714
qSound ............................................................................................................................................................................. 714
qText.................................................................................................................................................................................. 715
reset ................................................................................................................................................................................... 715
Adobe Acrobat SDK Contents
JavaScript for Acrobat API Reference 27

2 JavaScript API (Continued)

TTS (Continued)
TTS methods (Continued)
resume .............................................................................................................................................................................. 715
stop .................................................................................................................................................................................... 715
talk...................................................................................................................................................................................... 715
util ................................................................................................................................................................................................... 716
util methods.......................................................................................................................................................................... 716
crackURL........................................................................................................................................................................... 716
iconStreamFromIcon................................................................................................................................................... 717
printd................................................................................................................................................................................. 718
printf.................................................................................................................................................................................. 720
printx ................................................................................................................................................................................. 722
scand ................................................................................................................................................................................. 723
spansToXML ................................................................................................................................................................... 724
streamFromString ........................................................................................................................................................ 724
stringFromStream ........................................................................................................................................................ 725
xmlToSpans .................................................................................................................................................................... 726
XFA.................................................................................................................................................................................................. 727
XMLData ....................................................................................................................................................................................... 728
XMLData methods.............................................................................................................................................................. 728
applyXPath...................................................................................................................................................................... 728
parse .................................................................................................................................................................................. 732
3 New Features and Changes.....................................................................................................736
Acrobat 8.1 changes................................................................................................................................................................. 736
Acrobat 8.0 changes................................................................................................................................................................. 736
Acrobat 7.0.5 changes ............................................................................................................................................................. 740
Acrobat 7.0 changes................................................................................................................................................................. 741
Introduced in Acrobat 7.0.......................................................................................................................................... 742
Modified in Acrobat 7.0 .............................................................................................................................................. 744
Acrobat 6.0 changes................................................................................................................................................................. 746
Introduced in Acrobat 6.0.......................................................................................................................................... 746
Modified in Acrobat 6.0 .............................................................................................................................................. 753
Deprecated in Acrobat 6.0......................................................................................................................................... 754
Introduced in Acrobat 6.0.2 ...................................................................................................................................... 755
Acrobat 5.0 changes................................................................................................................................................................. 761
Introduced in Acrobat 5.0.......................................................................................................................................... 761
Modified in Acrobat 5.0 .............................................................................................................................................. 768
Deprecated in Acrobat 5.0......................................................................................................................................... 768
Modified in Acrobat 5.05............................................................................................................................................ 769
Modified in Adobe Reader 5.1 ................................................................................................................................. 769
 Preface

This reference contains the documentation of the objects, properties and methods of the JavaScript™
extensions for Adobe® Acrobat® Professional, Acrobat Standard and Adobe Reader®.

What’s in this guide?

This guide describes the JavaScript for Acrobat API:
● “JavaScript API” on page 35 describes the JavaScript API in detail. All objects, properties and methods
are documented and extensive code examples are presented.
● “New Features and Changes” on page 736 summarizes the new features and changes introduced in
recent versions of Acrobat.

Note: Certain properties and methods that may be discoverable through JavaScript's introspection
facilities are not documented here. Undocumented properties and methods should not be used.
They are entirely unsupported and subject to change without notice at any time.

Who should read this guide?

This document is intended for users familiar with core JavaScript 1.6. The intended audience includes, but
is not limited to, authors of interactive PDF documents, form designers of intelligent documents, and
Acrobat plug-in developers.

A knowledge of the Acrobat user interface is essential. Familiarity with the PDF file format is helpful.

The use of JavaScript to control additional Acrobat features such as ADBC, multimedia, SOAP, XML, and
various security protocols requires knowledge of the corresponding technologies.

Related documentation
This document refers to the following sources for additional information about JavaScript and related
technologies. The Acrobat documentation is available through the Acrobat Family Developer Center,
http://www.adobe.com/go/acrobat_developer.

For information about See

A guide to the documentation in the Acrobat SDK. Acrobat SDK Documentation Roadmap
Known issues and implementation details. Readme
Answers to frequently asked questions about the Acrobat SDK. Developer FAQ
New features in this Acrobat SDK release. What’s New
A general overview of the Acrobat SDK. Overview
A guide to the sections of the Acrobat SDK that pertain to Developing for Adobe Reader
Adobe Reader.

28
Adobe Acrobat SDK Preface
JavaScript for Acrobat API Reference Related documentation 29

For information about See

A guide to the sample code included with the Acrobat SDK. Guide to SDK Samples
Using DDE, OLE, Apple events, and AppleScript to control Developing Applications Using
Acrobat and Adobe Reader and to render PDF documents. Interapplication Communication
Detailed descriptions of DDE, OLE, Apple event, and Interapplication Communication
AppleScript APIs for controlling Acrobat and Adobe Reader or API Reference
for rendering PDF documents.
Detailed descriptions of JavaScript APIs for adding interactivity JavaScript for Acrobat 3D Annotations
to 3D annotations within PDF documents. API Reference
Using JavaScript to develop and enhance standard workflows Developing Acrobat Applications
in Acrobat and Adobe Reader. Using JavaScript
Using RSS to track remote resources in an Acrobat Tracker
occasionally-connected environment.
A detailed description of an extension to the PostScript® pdfmark Reference
language which allows the description of PDF features not
found in standard PostScript.
A detailed description of the PDF file format. PDF Reference
Using JavaScript to perform repetitive operations on a Batch Sequences
collection of files.
A detailed description of the parameters for opening PDF files Parameters for Opening PDF Files
and for performing actions on them using a URL or command.
Describes the XFA specification. XFA Specification
Describes the specific language for describing patterns utilized XFA-Picture Clause 2.0 Specification
for formatting or parsing data.
This document is the XFDF specification. XML Form Data Format Specification
This document describes the different models available in the Adobe XML Form Object Model
XML Form Object Model for scripting. It provides detailed Reference
information about the different objects in each of those
models, and their associated properties and methods.
This document describes methods of converting Acrobat Converting Acrobat JavaScript for
forms to Adobe LiveCycle® Designer forms, and explains the Use in LiveCycle Designer Forms
differences between the Acrobat and LiveCycle Designer
form object models.
This document describes the digital signature capabilities of Acrobat 8.0 Security Feature
Acrobat, which document authors can use to create certified User Reference
documents, signable forms, and custom workflows and
appearances.
 1 Introduction

JavaScript is the cross-platform scripting language of the Adobe Acrobat family of products that includes
Acrobat Professional, Acrobat Standard, and Adobe Reader. Through JavaScript extensions, the viewer
application and its plug-ins expose much of their functionality to document authors, form designers, and
plug-in developers.

This functionality includes the following features, among others:

● Processing forms within the document
● Batch processing collections of PDF documents
● Developing and maintaining online collaboration schemes
● Communicating with local databases
● Controlling multimedia events

In addition to being available in Acrobat and Adobe Reader, the objects, properties, and methods for the
Acrobat extensions for JavaScript can also be accessed through Microsoft Visual Basic to automate the
processing of PDF documents. See the Interapplication Communication API Reference for details.

Syntax
Some JavaScript objects are static objects that can be used as is and must be spelled as indicated. For
example, the app object represents the JavaScript application. There is only one such object and it must
be spelled app (case-sensitive).

Other objects are dynamic objects that can be assigned to a variable. For example, a Doc object may be
obtained and assigned to a variable:
var myDoc = app.newDoc();

In this example, myDoc can access all methods and properties of the Doc object. For example:
myDoc.closeDoc();

Method arguments
Many of the JavaScript methods provided by Acrobat accept either a list of arguments, as is customary in
JavaScript, or a single object argument with properties that contain the arguments. For example, these
two calls are equivalent:
app.alert( "Acrobat Multimedia", 3);

app.alert({ cMsg: "Acrobat Multimedia", nIcon: 3});

Note: The JavaScript methods defined in support of multimedia do not accept these two argument
formats interchangeably. Use the exact argument format described for each method.

30
Adobe Acrobat SDK Introduction
JavaScript for Acrobat API Reference Paths 31

Parameter help
When using Acrobat Professional, if you give an Acrobat method an argument of acrohelp and execute
that method in the JavaScript Debugger console (or any internal JavaScript editor), the method returns a
list of its own arguments.

For example, enter the following code in the console window.

app.response(acrohelp)

While the cursor is still on the line just entered, press either Ctrl + Enter or the Enter key on the numeric
pad. The console displays the following message.
HelpError: Help.
app.response:1:Console undefined:Exec
====> [cQuestion: string]
====> [cTitle: string]
====> [cDefault: string]
====> [bPassword: boolean]
====> [cLabel: string]

Parameters listed in square brackets indicate optional parameters.

Note: Parameter help is not implemented for every JavaScript method. For example, it is not implemented
for methods defined in the App JavaScript folder.

Paths
Several methods take device-independent paths as arguments. See the PDF Reference, version 1.7, for
details about the device-independent path format.

Safe path
Acrobat 6.0 introduced the concept of a safe path for JavaScript methods that write data to the local hard
drive based on a path passed to it by one of its parameters.

A path cannot point to a system critical folder, for example a root, windows or system directory. A path is
also subject to other unspecified tests.

For many methods, the file name must have an extension appropriate to the type of data that is to be
saved. Some methods may have a no-overwrite restriction. These additional restrictions are noted in the
documentation.

Generally, when a path is judged to be not safe, a NotAllowedError exception is thrown (see Error
object) and the method fails.

Privileged context
A context in which you have the right to do something that is normally restricted. Such a right (or
privilege) could be granted by executing a method in a specific way (through the console or batch
process), by some PDF property, or because the document was signed by someone you trust. For example,
trusting a document certifier’s certificate for executing JavaScript creates a privileged context which
enables the JavaScript to run where it otherwise would not.
Adobe Acrobat SDK Introduction
JavaScript for Acrobat API Reference Privileged versus non-privileged context 32

Privileged versus non-privileged context

Some JavaScript methods, marked in this book by S in the third column of the quick bar, have security
restrictions. These methods can be executed only in a privileged context, which includes console, batch and
application initialization events. All other events (for example, page open and mouse-up events) are
considered non-privileged.

The description of each security-restricted method indicates the events during which the method can be
executed.

Beginning with Acrobat 6.0, security-restricted methods can execute without restrictions if the document
certifier’s certificate is trusted for running embedded high privilege JavaScript.

In Acrobat versions earlier than 7.0, menu events were considered privileged contexts. Beginning with
Acrobat 7.0, execution of JavaScript through a menu event is no longer privileged. You can execute
security-restricted methods through menu events in one of the following ways:
● By opening the JavaScript category of the Acrobat preferences and checking the item named “Enable
Menu Items JavaScript Execution Privileges”.
● By executing a specific method through a trusted function (introduced in Acrobat 7.0). Trusted
functions allow privileged code—code that normally requires a privileged context to execute—to
execute in a non-privileged context. For details and examples, see app.trustedFunction.

User preferences
There are many references in this document to the Acrobat user preferences. The preferences dialog box is
accessed through the following menu commands, depending on platform:
Microsoft® Windows®: Edit > Preferences
Mac OS: Acrobat > Preferences

The preferences dialog box contains several categories that have relevant commands, including Forms,
General, and JavaScript.
The following methods, if run from a document-level script, no longer affect the user preferences:
● app.fs.defaultTransition, app.fsTransition
● app.fs.useTimer, app.fsUseTimer
● app.fs.usePageTiming, app.fsUsePageTiming
● app.fs.loop, app.fsLoop
● app.fs.escapeExits, app.fsEscape
● app.fsClick, app.fs.clickAdvances
● app.fsTimeDelay, app.fs.timeDelay
● app.fsColor, app.fs.backgroundColor
● app.fsCursor, app.fs.cursor
● app.openInPlace
These methods still affect user preferences if run from an application-level script.
Also note that app.fs.escapeExits and app.fsEscape can now only be set to false when running
in a privileged context.
Adobe Acrobat SDK Introduction
JavaScript for Acrobat API Reference Quick bars 33

Quick bars
At the beginning of most property and method descriptions, a small table or quick bar provides a
summary of the item’s availability and usage recommendations.

The quick bar shown here has descriptive column headings that are not shown in the reference.
Deprecated
Version or
Preferences
Save and
Security

Availability

6.0 D S C
The following tables show the symbols that can appear in each column and their meanings.

Column 1: Version or deprecated

#.# A number indicates the version of the software in which a property or method became available. If
the number is specified, the property or method is available only in versions of the Acrobat
software greater than or equal to that number.
For Acrobat 8.0, there are some compatibility issues with older versions. Before accessing the
property or method, the script should check that the forms version is greater than or equal to that
number to ensure backward compatibility. For example:
if (typeof app.formsVersion != "undefined" && app.formsVersion >= 8.0)
{
// Perform version specific operations.
}
If the first column is blank, no compatibility checking is necessary.

X The property or method is deprecated.

Column 2: Save and Preferences

D Writing to this property or method dirties (modifies) the PDF document. If the document is
subsequently saved, the effects of this method are saved as well. (In Adobe Reader, the document
requires specific rights to be saved.)

P Even though this property does not change the document, it can permanently change a user’s
application preferences.
Adobe Acrobat SDK Introduction
JavaScript for Acrobat API Reference Domain names in code samples 34

Column 3: Security

S For security reasons, this property or method may be available only during certain events. These
events include batch processing, application start, or execution within the console. (See the
event object for details of the Acrobat events.)
Beginning with Acrobat 7.0, to execute a security-restricted method through a menu event, one of
the following must be true:
● The JavaScript user preferences item Enable Menu Items JavaScript Execution Privileges is
checked.
● The method is executed through a trusted function. For details and examples, see the
app.trustedFunction method.
See “Privileged versus non-privileged context” on page 32 for more information.

Note: (Acrobat 6.0 or later) Methods marked with S will execute without restriction in a certified
document provided the certifier’s certificate is trusted for running embedded high privilege
JavaScript and other limitations in the quick bar fields are met.

Column 4: Availability

If the column is blank, the property or method is allowed in Adobe Reader, Acrobat Professional or
Acrobat Standard.

X The property or method is not allowed in Adobe Reader but is available in Acrobat Professional
and Acrobat Standard.

F The property or method is allowed in Acrobat Professional and Acrobat Standard. It can be
accessed in Adobe Reader (version 5.1 or later) depending on additional usage rights that have
C been applied to the document:
S ● F — Requires forms rights
D ● C — Requires the right to manipulate comments
G
● S — Requires the document save right
● D — Requires file attachment rights
● G — Requires digital signature rights

P The property or method is available only in Acrobat Professional

Domain names in code samples

Throughout this document there are numerous code samples that use URLs. Such examples use the
domain names example.com, example.net, and example.org, which are reserved for the purpose of
illustration. Some examples use IP addresses, these addresses come from the range 172.16.0.0 through
172.31.255.255, which are reserved for private networks.
2 JavaScript API

This chapter is a complete reference to the Acrobat extensions to JavaScript, its objects, methods, and
properties. The chapter is organized alphabetically by object name.

The Acrobat extensions to core JavaScript date back to Adobe Exchange 3.01. JavaScript functionality was
added to this version by means of the “Acrobat Forms Author Plug-in 3.5 Update”. Initially, JavaScript
version 1.2 was used, as the table below shows. In Acrobat 5.0, there was a major effort to extend core
JavaScript, then version 1.5, to include much of the functionality of the application and its plug-ins. The
most recent version of Acrobat now uses JavaScript 1.6.

Acrobat version 3.01 4.0 5.0 6.0 7.0 8.0

JavaScript version 1.2 1.2 1.5 1.5 1.5 1.6

When developing a JavaScript solution, you must have a minimal Acrobat (or Adobe Reader) version in
mind. The choice of target application determines, by the table above, the version of JavaScript you should
use.

Most JavaScript API function are documented in all versions of Acrobat and Adobe Reader, while others
are only defined in later versions. Still, some APIs are restricted to Acrobat Professional and some cannot
be used by Adobe Reader, while others can be used in Adobe Reader only when the document has the
appropriate Reader Extension Rights. Again, for a JavaScript solution, all these factors must be considered.

See “Quick bars” on page 33 for a description of the symbols that appear at the beginning of property and
method descriptions. The quick bar reflects the version number where the method was first defined,
security restrictions, limitations on Adobe Reader, and needed Adobe Reader usage rights.

For documentation on core JavaScript, the reader is directed to the Mozilla Developer Center,
http://developer.mozilla.org/en/docs/JavaScript.

35
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference ADBC 36

ADBC
5.0 X

The ADBC plug-in allows JavaScript in PDF documents to access databases through a consistent object
model. ADBC is a Windows-only feature and requires ODBC to be installed on the client machine.

The object model is based on general principles used in the object models for the ODBC and JDBC APIs.
Like ODBC and JDBC, ADBC is a means of communicating with a database through SQL.

Note: ADBC provides no security for any of the databases it is programmed to access. It is the
responsibility of the database administrator to keep all data secure.

The ADBC object is a global object whose methods allow a script to create database connection contexts
or connections. Related objects used in database access are described separately.

Related object Brief description Page

Connection An object through which a list of tables in the connected page 208
database can be obtained.

Statement An object through which SQL statements can be executed and page 697
rows retrieved based on the query.

ADBC properties
SQL types
5.0 X

The ADBC object has the following constant properties representing various SQL types:

Constant property name Value Version

SQLT_BIGINT 0

SQLT_BINARY 1

SQLT_BIT 2

SQLT_CHAR 3

SQLT_DATE 4

SQLT_DECIMAL 5

SQLT_DOUBLE 6

SQLT_FLOAT 7

SQLT_INTEGER 8
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference JavaScript types 37

Constant property name Value Version

SQLT_LONGVARBINARY 9

SQLT_LONGVARCHAR 10

SQLT_NUMERIC 11

SQLT_REAL 12

SQLT_SMALLINT 13

SQLT_TIME 14

SQLT_TIMESTAMP 15

SQLT_TINYINT 16

SQLT_VARBINARY 17

SQLT_VARCHAR 18

SQLT_NCHAR 19 6.0

SQLT_NVARCHAR 20 6.0

SQLT_NTEXT 21 6.0

The type properties of the Column object and ColumnInfo object use these properties.

JavaScript types
5.0 X

The ADBC object has the following constant properties representing various JavaScript data types.

Constant property name Value

Numeric 0

String 1

Binary 2

Boolean 3

Time 4

Date 5

TimeStamp 6

The Statement object methods getColumn and getColumnArray use these types.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference getDataSourceList 38

ADBC methods
getDataSourceList
5.0 X

Obtains information about the databases accessible from a given system.

Returns
An array containing a DataSourceInfo object for each accessible database on the system. The method
never fails but may return a zero-length array.

Example
See ADBC.newConnection.

newConnection
5.0 S X

Creates a Connection object associated with the specified database. Optionally, you can supply a user ID
and a password.

Note: (Acrobat 6.0 and later) It is possible to connect to a database using a connection string with no Data
Source Name (DSN), but this is only permitted, beginning with Acrobat 6.0, during a console or
batch event. See also “Privileged versus non-privileged context” on page 32.

Parameters
cDSN The data source name (DSN) of the database
cUID (optional) User ID
cPWD (optional) Password

Returns
A Connection object, or null on failure.

Example
Get the array of DataSourceInfo objects available on the system, and display them to the console, while
searching for the data source named q32000data.
/* First, get the array of DataSourceInfo objects available on the system */
var aList = ADBC.getDataSourceList();
console.show(); console.clear();
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference newConnection 39

try {
/* Now display them, while searching for the one named
"q32000data". */
var DB = "", msg = "";
if (aList != null) {
for (var i=0; i < aList.length; i++) {
console.println("Name: "+aList[i].name);
console.println("Description: "+aList[i].description);
// and choose one of interest
if (aList[i].name=="q32000data")
DB = aList[i].name;
}
}

// Did we find the database?

if (DB != "") {
// Yes, establish a connection.
console.println("The requested database has been found!");
var Connection = ADBC.newConnection(DB);
if (Connection == null) throw "Not Connected!";
} else
// No, display message to console.
throw "Could not find the requested database.";
} catch (e) {
console.println(e);
}

// Alternatively, we could simple connect directly.

var Connection = ADBC.newConnection("q32000data");
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference Alerter 40

Alerter
7.0

The Acrobat multimedia plug-in displays error alerts under various conditions such as a missing media file.
JavaScript code can customize these alerts, either for an entire document or for an individual media player.

In an alert situation, the internal function app.media.alert is called with parameters containing
information about the alert. The app.media.alert method handles the alert by looking for alerter
objects and calling their dispatch methods, in this order:
args.alerter
doc.media.alerter
doc.media.stockAlerter

To handle alerts for a specific player, provide an alerter object in args.alerter when you call
app.media.createPlayer or app.media.openPlayer.

To handle alerts for an entire document, set doc.media.alerter to an alerter object.

All alerts can be suppressed for a player or document by setting args.alerter or

doc.media.alerter to null.

doc.media.stockAlerter provides the default alerts that are used if a custom alerter is not specified.
This property is initialized automatically by app.media.alert. Normally, doc.media.stockAlerter
would not be referenced in developer code.

Alerter methods
dispatch
7.0

Called by app.media.alert to handle alert situations.

Parameters
alert An Alert object (see below).

Returns
A Boolean value, true to stop further alert processing, false to continue processing.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference dispatch 41

Alert object
Properties Type Description

type String All alert types

doc Doc object All alert types

fromUser Boolean All alert types

error Object Available for the Exception type alert. The error
object has a message property:
error: { message: String }

errorText String Available for the PlayerError type alert.

fileName String Available for the FileNotFound type alert.

selection MediaSelection object Available for the SelectFailed type alert.

Example 1
Open a media player and suppress all alerts for this player.
app.media.openPlayer({ alerter: null });

// A more elaborate way to do the same thing

app.media.openPlayer(
{
alerter:
{
dispatch() { return true; }
}
});

Example 2
For all players in this document, log any alerts to a text field and allow the normal alert box to be displayed.
function logAlerts( doc )
{
count = 0;
doc.alerter =
{
dispatch( alert )
{
doc.getField("AlertLog").value += "Alert #"
+ ++count + ": " + alert.type + "\n";
}
}
}
logAlerts( this );
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference dispatch 42

// Another way to keep the counter

function logAlerts( doc )
{
doc.alerter =
{
count = 0,
dispatch( alert )
{
doc.getField("AlertLog").value += "Alert #"
+ ++this.count + ": " + alert.type + "\n";
}
}
}
logAlerts( this );

Example 3
Handle the PlayerError alert here, with defaults for other alerts.
this.media.alerter =
{
dispatch( alert )
{
switch( alert.type )
{
case "PlayerError":
app.alert( "Player error: " + alert.errorText );
return true;
}
}
}
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference AlternatePresentation 43

AlternatePresentation
This object provides an interface to the document's particular alternate presentation. Use the Doc object
method alternatePresentations to acquire an AlternatePresentation object.

See the PDF Reference version 1.7 for additional details on alternate presentations.

AlternatePresentation properties
active
6.0

This property is true if the presentation is currently active and false otherwise. When a presentation is
active, it controls how the document that owns it is displayed.

Type
Boolean

Access
R

Example
See the start method for an example.

type
6.0

The type of the alternate presentation. Currently, the only supported type is “SlideShow”.

Type
String

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference start 44

AlternatePresentation methods
start
6.0

Switches the document view into the alternate presentation mode and sets the active property to true.
An exception is thrown if this or any other alternate presentation is already active.

Parameters
cOnStop (optional) An expression to be evaluated by Acrobat when the presentation
completes for any reason (as a result of a call to stop, an explicit user action, or the
presentation logic itself ).
cCommand (optional) A command or script to pass to the alternate presentation.
Note: This command is presentation-specific (not a JavaScript expression).

Example
Assume there is a named presentation called “MySlideShow” within the document.
// oMySlideShow is an AlternatePresentation object
oMySlideShow = this.alternatePresentations.MySlideShow;
if (!oMySlideShow.active) oMySlideShow.start();

Note that this.alternatePresentations is used to access the specified presentation by property

name.

stop
6.0

Stops the presentation and switches the document into normal (PDF) presentation. An exception is
thrown if this presentation is not active.

Example
In this example, oMySlideShow is an AlternatePresentations object. See start for a related example.
// Stop the show if already active
if (oMySlideShow.active) oMySlideShow.stop();
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference Annotation 45

Annotation
This object represents an Acrobat annotation. Annotations can be created using the Acrobat annotation
tool or by using the Doc object method addAnnot.

Before an annotation can be accessed, it must be bound to a JavaScript variable through a Doc object
method such as getAnnot:
var a = this.getAnnot(0, "Important");

The script can then manipulate the annotation named “Important” on page 1 (0-based page numbering
system) by means of the variable a. For example, the following code first stores the type of annotation in
the variable thetype, then changes the author to “John Q. Public”.
var thetype = a.type; // read property
a.author = "John Q. Public"; // write property

Another way of accessing the Annotation object is through the Doc object getAnnots method.

Note: In Adobe Reader 5.1 or later, you can get the value of any annotation property except contents.
The ability to set these properties depends on Comments document rights, as indicated by the C
icon.
The user interface in Acrobat refers to annotations as comments.

Annotation types
Annotations are of different types, as reflected in the type property. Each type is listed in the table below,
along with all documented properties returned by the getProps method.

Annotation type Properties

Caret author, borderEffectIntensity, borderEffectStyle,

caretSymbol, contents, creationDate, delay, hidden, inReplyTo,
intent, lock, modDate, name, noView, opacity, page, popupOpen,
popupRect, print, readOnly, rect, refType, richContents, rotate,
seqNum, strokeColor, style, subject, toggleNoView, type, width

Circle author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, dash, delay, fillColor, hidden, inReplyTo, intent,
lock, modDate, name, noView, opacity, page, popupOpen, popupRect,
print, readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

FileAttachment attachIcon, author, borderEffectIntensity, borderEffectStyle,

contents, creationDate, delay, hidden, inReplyTo, intent, lock,
modDate, name, noView, opacity, page, point, print, readOnly, rect,
refType, richContents, rotate, seqNum, strokeColor, style,
subject, toggleNoView, type, width
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference Annotation 46

Annotation type Properties

FreeText alignment, author, borderEffectIntensity, borderEffectStyle,

callout, contents, creationDate, dash, delay, fillColor, hidden,
inReplyTo, intent, lineEnding, lock, modDate, name, noView,
opacity, page, print, readOnly, rect, refType, richContents,
richDefaults, rotate, seqNum, strokeColor, style, subject,
textFont, textSize, toggleNoView, type, width

Highlight author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, opacity, page, popupOpen, popupRect, print, quads,
readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

Ink author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, dash, delay, gestures, hidden, inReplyTo, intent,
lock, modDate, name, noView, opacity, page, popupOpen, popupRect,
print, readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

Line arrowBegin, arrowEnd, author, borderEffectIntensity,

borderEffectStyle, contents, creationDate, dash, delay,
doCaption, fillColor, hidden, inReplyTo, intent, leaderExtend,
leaderLength, lock, modDate, name, noView, opacity, page, points,
popupOpen, popupRect, print, readOnly, rect, refType,
richContents, rotate, seqNum, strokeColor, style, subject,
toggleNoView, type, width

Polygon author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, dash, delay, fillColor, hidden, inReplyTo, intent,
lock, modDate, name, noView, opacity, page, popupOpen, popupRect,
print, readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, vertices, width

PolyLine arrowBegin, arrowEnd, author, borderEffectIntensity,

borderEffectStyle, contents, creationDate, dash, delay,
fillColor, hidden, inReplyTo, intent, lock, modDate, name, noView,
opacity, page, popupOpen, popupRect, print, readOnly, rect,
refType, richContents, rotate, seqNum, strokeColor, style,
subject, toggleNoView, type, vertices, width

Sound author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, opacity, page, point, print, readOnly, rect, refType,
richContents, rotate, seqNum, soundIcon, strokeColor, style,
subject, toggleNoView, type, width

Square author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, dash, delay, fillColor, hidden, inReplyTo, intent,
lock, modDate, name, noView, opacity, page, popupOpen, popupRect,
print, readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference alignment 47

Annotation type Properties

Squiggly author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, opacity, page, popupOpen, popupRect, print, quads,
readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

Stamp AP, author, borderEffectIntensity, borderEffectStyle,

contents, creationDate, delay, hidden, inReplyTo, intent, lock,
modDate, name, noView, opacity, page, popupOpen, popupRect, print,
readOnly, rect, refType, rotate, seqNum, strokeColor, style,
subject, toggleNoView, type

StrikeOut author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, opacity, page, popupOpen, popupRect, print, quads,
readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

Text author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, noteIcon, opacity, page, point, popupOpen,
popupRect, print, readOnly, rect, refType, richContents, rotate,
seqNum, state, stateModel, strokeColor, style, subject,
toggleNoView, type, width

Underline author, borderEffectIntensity, borderEffectStyle, contents,

creationDate, delay, hidden, inReplyTo, intent, lock, modDate,
name, noView, opacity, page, popupOpen, popupRect, print, quads,
readOnly, rect, refType, richContents, rotate, seqNum,
strokeColor, style, subject, toggleNoView, type, width

Annotation properties
The PDF Reference version 1.7 documents all Annotation properties and specifies how they are stored.

Some property values are stored in the PDF document as names and others are stored as strings (see the
PDF Reference version 1.7 for details). A property stored as a name can have only 127 characters.

Examples of properties that have a 127-character limit include AP, beginArrow, endArrow,
attachIcon, noteIcon, and soundIcon.

alignment
5.0 D C
Controls the alignment of the text for a FreeText annotation.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference AP 48

Alignment Value

Left aligned 0

Centered 1

Right aligned 2

Type
Number

Access
R/W

Annotations
FreeText

AP
5.0 D C
The named appearance of the stamp to be used in displaying a stamp annotation. The names of the
standard stamp annotations are given below:
Approved
AsIs
Confidential
Departmental
Draft
Experimental
Expired
Final
ForComment
ForPublicRelease
NotApproved
NotForPublicRelease
Sold
TopSecret

Type
String

Access
R/W
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference arrowBegin 49

Annotations
Stamp

Example
Programmatically add a stamp annotation.
var annot = this.addAnnot({
page: 0,
type: "Stamp",
author: "A. C. Robat",
name: "myStamp",
rect: [400, 400, 550, 500],
contents: "Try it again, this time with order and method!",
AP: "NotApproved" });

Note: The name of a particular stamp can be found by opening the PDF file in the Stamps folder that
contains the stamp in question. For a list of stamp names currently in use in the document, see the
Doc object icons property.

arrowBegin
5.0 D C
Determines the line cap style that specifies the shape to be used at the beginning of a line annotation.
Permissible values are:
None (default)
OpenArrow
ClosedArrow
ROpenArrow // Acrobat 6.0
RClosedArrow // Acrobat 6.0
Butt // Acrobat 6.0
Diamond
Circle
Square
Slash // Acrobat 7.0

Type
String

Access
R/W

Annotations
Line, PolyLine

Example
See the setProps method.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference arrowEnd 50

arrowEnd
5.0 D C
Determines the line cap style that specifies the shape to be used at the end of a line annotation. The
following list shows the allowed values:
None (default)
OpenArrow
ClosedArrow
ROpenArrow // Acrobat 6.0
RClosedArrow // Acrobat 6.0
Butt // Acrobat 6.0
Diamond
Circle
Square
Slash // Acrobat 7.0

Type
String

Access
R/W

Annotations
Line, PolyLine

Example
See the setProps method.

attachIcon
5.0 D C
The name of an icon to be used in displaying the annotation. Recognized values are listed below:
Paperclip
PushPin (default)
Graph
Tag

Type
String
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference author 51

Access
R/W

Annotations
FileAttachment

author
5.0 D C
Gets or sets the author of the annotation.

Type
String

Access
R/W

Annotations
All

Example
See the contents property.

borderEffectIntensity
6.0 D C
The intensity of the border effect, if any. This represents how cloudy a cloudy rectangle, polygon, or oval is.

Type
Number

Access
R/W

Annotations
All
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference borderEffectStyle 52

borderEffectStyle
6.0 D C
If non-empty, the name of a border effect style. Currently, the only supported border effects are the empty
string (nothing) or “C” for cloudy.

Type
String

Access
R/W

Annotations
All

callout
7.0 D C
An array of four or six numbers specifying a callout line attached to the free text annotation. See the PDF
Reference version 1.7 for additional details.

Type
Array

Access
R/W

Annotations
FreeText

caretSymbol
6.0 D C
The symbol associated with a Caret annotation, which is a visual symbol that indicates the presence of text

edits. Valid values are “” (nothing), “P” (paragraph symbol) or “S” (space symbol).
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference contents 53

Type
String

Access
R/W

Annotations
Caret

contents
5.0 D C
Accesses the contents of any annotation that has a pop-up window. For sound and file attachment
annotations, specifies the text to be displayed as a description.

Type
String

Access
R/W

Annotations
All

Example
Create a text annotation, with author and contents specified.
var annot = this.addAnnot({
page: 0,
type: "Text",
point: [400,500],
author: "A. C. Robat",
contents: "Call Smith to get help on this paragraph.",
noteIcon: "Help"
});

See also the Doc object addAnnot method.

creationDate
6.0 C
The date and time when the annotation was created.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference dash 54

Type
Date

Access
R

Annotations
All

dash
5.0 D C
A dash array defining a pattern of dashes and gaps to be used in drawing a dashed border. For example, a
value of [3, 2] specifies a border drawn with 3-point dashes alternating with 2-point gaps.

To set the dash array, the style property must be set to D.

Type
Array

Access
R/W

Annotations
FreeText, Line, PolyLine, Polygon, Circle, Square, Ink

Example
Assuming annot is an Annotation object, this example changes the border to dashed.
annot.setProps({ style: "D", dash: [3,2] });

See also the example following the delay property.

delay
5.0 C
If true, property changes to the annotation are queued and then executed when delay is set back to
false. (Similar to the Field object delay property.)
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference doc 55

Type
Boolean

Access
R/W

Annotations
All

Example
Assuming annot is an Annotation object, the code below changes the border to dashed.
annot.delay=true;
annot.style = "D";
annot.dash = [4,3];
annot.delay = false;

doc
5.0 C
The Doc object of the document in which the annotation resides.

Type
Doc object

Access
R

Annotations
All

Example
Construct an annotation, and illustrate the use of the doc property.
var inch = 72;
var annot = this.addAnnot({
page: 0,
type: "Square",
rect: [1*inch, 3*inch, 2*inch, 3.5*inch]
});
/* displays, for example, "file:///C|/Adobe/Annots/myDoc.pdf" */
console.println(annot.doc.URL);
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference doCaption 56

doCaption
7.0 D C
If true, draws the rich contents in the line appearance itself.

Type
Boolean

Access
R/W

Annotations
Line

Example
See the example following the points property, page 65.

fillColor
5.0 D C
Sets the background color for circle, square, line, polygon, polyline, and free text annotations. Values are
defined by using transparent, gray, RGB or CMYK color. See “Color arrays” on page 193 for information
on defining color arrays and how values are used with this property.

Type
Color

Access
R/W

Annotations
Circle, Square, Line, Polygon, PolyLine, FreeText
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference gestures 57

Example
Create a Circle annotation and set the background color.
var annot = this.addAnnot(
{
type: "Circle",
page: 0,
rect: [200,200,400,300],
author: "A. C. Robat",
name: "myCircle",
popupOpen: true,
popupRect: [200,100,400,200],
contents: "Hi World!",
strokeColor: color.red,
fillColor: ["RGB",1,1,.855]
});

gestures
5.0 D C
An array of arrays, each representing a stroked path. Each array is a series of alternating x and y coordinates
in default user space, specifying points along the path. When drawn, the points are connected by straight
lines or curves in an implementation-dependent way. See the PDF Reference version 1.7 for more details.

Type
Array

Access
R/W

Annotations
Ink

hidden
5.0 D C
If true, the annotation is not shown and there is no user interaction, display, or printing of the annotation.

Type
Boolean
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference inReplyTo 58

Access
R/W

Annotations
All

inReplyTo
6.0 D C
If non-empty, specifies the name value of the annotation that this annotation is in reply to.

Type
String

Access
R/W

Annotations
All

intent
7.0 D C
This property allows a markup annotation type to behave differently, depending on the intended use of
the annotation. For example, the Callout Tool is a free text annotation with intent set to
FreeTextCallout.

Though this property is defined for all annotations, currently, only free text, polygon, and line annotations
have non-empty values for intent.

Type
String

Access
R/W
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference leaderExtend 59

Annotations
All

The table below lists the tools available through the UI for creating annotations with special appearances.

UI Annotation type Intent

Callout Tool FreeText FreeTextCallout

Cloud Tool Polygon PolygonCloud

Arrow Tool Line LineArrow

Dimensioning Tool Line LineDimension

leaderExtend
7.0 D C
Specifies the length of leader line extensions that extend from both endpoints of the line, perpendicular to
the line. These lines extend from the line proper 180 degrees from the leader lines. The value should
always be greater than or equal to zero.

The default is zero (no leader line extension).

Type
Number

Access
R/W

Annotations
Line

leaderLength
7.0 D C
Specifies the length of leader lines that extend from both endpoints of the line, perpendicular to the line.
The value may be negative to specify an alternate orientation of the leader lines.

The default is 0 (no leader line).

Type
Number
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference lineEnding 60

Access
R/W

Annotations
Line

lineEnding
7.0 D C
This property determines how the end of a callout line is stroked. It is relevant only for a free text
annotation when the value of intent is FreeTextCallout. Recognized values are listed below:
None (default)
OpenArrow
ClosedArrow
ROpenArrow // Acrobat 6.0
RClosedArrow // Acrobat 6.0
Butt // Acrobat 6.0
Diamond
Circle
Square
Slash // Acrobat 7.0

Type
String

Access
R/W

Annotations
FreeText

lock
5.0 D C
If true, the annotation is locked, which is equivalent to readOnly except that the annotation is
accessible through the properties dialog box in the UI.

Type
Boolean
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference modDate 61

Access
R/W

Annotations
All

modDate
5.0 C
The last modification date for the annotation.

Type
Date

Access
R/W

Annotations
All

Example
Print the modification date to the console.
console.println(util.printd("mmmm dd, yyyy", annot.modDate));

name
5.0 D C
The name of an annotation. This value can be used by the Doc object getAnnot method to find and
access the properties and methods of the annotation.

Type
String

Access
R/W
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference noteIcon 62

Annotations
All

Example
Locate the annotation named myNote and appends a comment.
var gannot = this.getAnnot(0, "myNote");
gannot.contents += "\r\rDon’t forget to check with Smith";

noteIcon
5.0 D C
The name of an icon to be used in displaying the annotation. Recognized values are given below:
Check
Circle
Comment
Cross
Help
Insert
Key
NewParagraph
Note(default)
Paragraph
RightArrow
RightPointer
Star
UpArrow
UpLeftArrow

Type
String

Access
R/W

Annotations
Text

Example
See the contents property.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference noView 63

noView
5.0 D C
If true, the annotation is hidden, but if the annotation has an appearance, that appearance should be
used for printing only.

Type
Boolean

Access
R/W

Annotations
All

Example
See the toggleNoView property.

opacity
5.0 D C
The constant opacity value to be used in painting the annotation. This value applies to all visible elements
of the annotation in its closed state (including its background and border), but not to the pop-up window
that appears when the annotation is opened. Permissible values are 0.0 - 1.0. A value of 0.5 makes the
annotation semitransparent.

Type
Number

Access
R/W

Annotations
All
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference page 64

page
5.0 D C
The page on which the annotation resides.

Type
Integer

Access
R/W

Annotations
All

Example
The following code moves the Annotation object annot from its current page to page 3 (0-based page
numbering system).
annot.page = 2;

point
5.0 D C
An array of two numbers, [xul, yul] that specifies the upper left-hand corner in default user space of the icon
for a text, sound or file attachment annotation.

Type
Array

Access
R/W

Annotations
Text, Sound, FileAttachment
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference points 65

Example
Place a help note icon at specified coordinates. The icon is located at the upper right corner of the popup
note.
var annot = this.addAnnot({
page: 0,
type: "Text",
point: [400,500],
contents: "Call Smith to get help on this paragraph.",
popupRect: [400,400,550,500],
popupOpen: true,
noteIcon: "Help"
});

See also the noteIcon property and the Doc object addAnnot method.

points
5.0 D C
An array of two points, [[x1, y1], [x2, y2]], specifying the starting and ending coordinates of the line in default
user space.

Type
Array

Access
R/W

Annotations
Line

Example
Draw a line between two specified points.
var annot = this.addAnnot({
type: "Line",
page: 0,
author: "A. C. Robat",
doCaption: true,
contents: "Look at this again!",
points: [[10,40],[200,200]],
});

See the arrowBegin and arrowEnd properties, the setProps method, and the Doc object addAnnot
method.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference popupOpen 66

popupOpen
5.0 D C
If true, the pop-up text note appears open when the page is displayed.

Type
Boolean

Access
R/W

Annotations
All except FreeText, Sound, FileAttachment

Example
See the print property.

popupRect
5.0 D C
An array of four numbers [xll, yll, xur, yur] specifying the lower-left x, lower-left y, upper-right x, and
upper-right y coordinates—in default user space—of the rectangle of the pop-up annotation associated
with a parent annotation. It defines the location of the pop-up annotation on the page.

Type
Array

Access
R/W

Annotations
All except FreeText, Sound, FileAttachment

Example
See the print property.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference print 67

print
5.0 D C
Indicates whether the annotation should be printed (true) or not (false).

Type
Boolean

Access
R/W

Annotations
All

quads
5.0 D C
An array of 8 x n numbers specifying the coordinates of n quadrilaterals in default user space. Each
quadrilateral encompasses a word or group of contiguous words in the text underlying the annotation.
See the PDF Reference version 1.7 for more details. The quads for a word can be obtained through calls to
the Doc object getPageNthWordQuads method.

Type
Array

Access
R/W

Annotations
Highlight, StrikeOut, Underline, Squiggly

Example
See the Doc object getPageNthWordQuads method.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference rect 68

rect
5.0 D C
The rect array consists of four numbers [xll, yll, xur, yur] specifying the lower-left x, lower-left y, upper-right
x, and upper-right y coordinates—in default user space—of the rectangle defining the location of the
annotation on the page. See also the popupRect property.

Type
Array

Access
R/W

Annotations
All

readOnly
5.0 D C
If true, the annotation should display but not interact with the user.

Type
Boolean

Access
R/W

Annotations
All

refType
7.0 D C
The reference type of the annotation. The property distinguishes whether inReplyTo indicates a plain
threaded discussion relationship or a group relationship. Recognized values are “R” and “Group”. See the
PDF Reference version 1.7 for additional details.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference richContents 69

Type
String

Access
R/W

Annotations
All

richContents
6.0 D C
This property gets the text contents and formatting of an annotation. The rich text contents are
represented as an array of Span objects containing the text contents and formatting of the annotation.

Type
Array of Span objects

Access
R/W

Annotations
All except Sound, FileAttachment

Example
Create a text annotation and give it some rich text contents.
var annot = this.addAnnot({
page: 0,
type: "Text",
point: [72,500],
popupRect: [72, 500,6*72,500-2*72],
popupOpen: true,
noteIcon: "Help"
});

var spans = new Array();

spans[0] = new Object();
spans[0].text = "Attention:\r";
spans[0].textColor = color.blue;
spans[0].textSize = 18;
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference richDefaults 70

spans[1] = new Object();

spans[1].text = "Adobe Acrobat 6.0\r";
spans[1].textColor = color.red;
spans[1].textSize = 20;
spans[1].alignment = "center";

spans[2] = new Object();

spans[2].text = "will soon be here!";
spans[2].textColor = color.green;
spans[2].fontStyle = "italic";
spans[2].underline = true;
spans[2].alignment = "right";

// Now give the rich field a rich value

annot.richContents = spans;

See also the Field object richValue method and the event object methods richValue, richChange,
and richChangeEx for examples of using the Span object.

richDefaults
6.0 D C
This property defines the default style attributes for a free text annotation. See the description of the Field
object defaultStyle property for additional details.

Type
Span object

Access
R/W

Annotations
FreeText

rotate
5.0 D C
The number of degrees (0, 90, 180, 270) the annotation is rotated counterclockwise relative to the page.
This property is only significant for free text annotations.

Type
Integer
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference seqNum 71

Access
R/W

Annotations
FreeText

seqNum
5.0 C
A read-only sequence number for the annotation on the page.

Type
Integer

Access
R

Annotations
All

soundIcon
5.0 D C
The name of an icon to be used in displaying the sound annotation. A value of “Speaker” is recognized.

Type
String

Access
R/W

Annotations
Sound
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference state 72

state
6.0 D C
The state of the text annotation. The values of this property depend on the stateModel. For a state model
of Marked, values are Marked and Unmarked. For a Review state model, the values are Accepted, Rejected,
Cancelled, Completed and None.

Type
String

Access
R/W

Annotations
Text

stateModel
6.0 D C
Beginning with Acrobat 6.0, annotations may have an author-specific state associated with them. The state
is specified by a separate text annotation that refers to the original annotation by means of its IRT entry
(see the inReplyTo property). There are two types of state models, “Marked” and “Review”.

Type
String

Access
R/W

Annotations
Text

See also the getStateInModel method.

strokeColor
5.0 D C
Sets the appearance color of the annotation. Values are defined by using transparent, gray, RGB or
CMYK color. In the case of a free text annotation, strokeColor sets the border and text colors. See “Color
arrays” on page 193 for information on defining color arrays and how values are used with this property.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference style 73

Type
Color

Access
R/W

Annotations
All

Example
Make a text note red.
var annot = this.addAnnot({type: "Text"});
annot.strokeColor = color.red;

style
5.0 D C
This property gets and sets the border style. Recognized values are S (solid) and D (dashed). The style
property is defined for all annotation types but is only relevant for line, free text, circle, square, polyline,
polygon and ink annotations.

Type
String

Access
R/W

Annotations
All

See the dash property for an example.

subject
6.0 D C
Text representing a short description of the subject being addressed by the annotation. The text appears
in the title bar of the pop-up window, if there is one, or the properties dialog box.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference textFont 74

Type
String

Access
R/W

Annotations
All

textFont
5.0 D C
Determines the font that is used when laying out text in a free text annotation. Valid fonts are defined as
properties of the font object (see the Field object textFont property).

An arbitrary font can be used when laying out a free text annotation by setting the value of textFont
equal to a string that represents the PostScript name of the font.

Type
String

Access
R/W

Annotations
FreeText

Example
Create a FreeText annotation using the Helvetica font.
var annot = this.addAnnot({
page: 0,
type: "FreeText",
textFont: font.Helv, // or, textFont: "Viva-Regular",
textSize: 10,
rect: [200, 300, 200+150, 300+3*12], // height for three lines
width: 1,
alignment: 1 });
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference textSize 75

textSize
5.0 D C
The text size (in points) for a free text annotation. Valid text sizes include zero and the range from 4 to 144,
inclusive. Zero indicates the largest point size that allows all the text to fit in the annotation’s rectangle.

Type
Number

Access
R/W

Annotations
FreeText

Example
See the textFont property.

toggleNoView
6.0 D C
If true, the noView flag is toggled when the mouse hovers over the annotation or the annotation is
selected.

If an annotation has both the noView and toggleNoView flags set, the annotation is usually invisible.
However, when the mouse is over it or it is selected, it becomes visible.

Type
Boolean

Access
R/W

Annotations
All
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference type 76

type
5.0 C
The type of annotation. The type of an annotation can only be set within the object-literal argument of the
Doc object addAnnot method. The valid values are:
Text
FreeText
Line
Square
Circle
Polygon
PolyLine
Highlight
Underline
Squiggly
StrikeOut
Stamp
Caret
Ink
FileAttachment
Sound

Type
String

Access
R

Annotations
All

vertices
6.0 D C
An array of coordinate arrays representing the alternating horizontal and vertical coordinates, respectively,
of each vertex, in default user space of a polygon or polyline annotation. See the PDF Reference version 1.7
for details.

Type
Array of arrays
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference width 77

Access
R/W

Annotations
Polygon, PolyLine

width
5.0 D C
The border width in points. If this value is 0, no border is drawn. The default value is 1.

Type
Number

Access
R/W

Annotations
Square, Circle, Line, Ink, FreeText

Annotation methods
destroy
5.0 D C
Destroys the annotation, removing it from the page. The object becomes invalid.

Example
Remove all "FreeText" annotations on page 0.
var annots = this.getAnnots({ nPage:0 });
for (var i = 0; i < annots.length; i++)
if (annots[i].type == "FreeText") annots[i].destroy();
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference getProps 78

getProps
5.0

Get the collected properties of an annotation. Can be used to copy an annotation.

Returns
An object literal of the properties of the annotation. The object literal is just like the one passed to the Doc
object addAnnot method.

Example 1
Copy a given annotation to every page in the document.
var annot = this.addAnnot({
page: 0,
type: "Text",
rect: [40, 40, 140, 140]
});

// Make a copy of the properties of annot

var copy_props = annot.getProps();

// Now create a new annot with the same properties on every page
var numpages = this.numPages;
for (var i=0; i < numpages; i++) {
var copy_annot = this.addAnnot(copy_props);
// but move it to page i
copy_annot.page=i;
}

Example 2
Display all properties and values of an annotation.
var a = this.getAnnots(0); // get all annots on page 0
if ( a != null ) {
var p = a[0].getProps();// get the properties of first one
for ( o in p ) console.println( o + " : " + p[o] );
}
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference getStateInModel 79

getStateInModel
6.0

Gets the current state of the annotation in the context of a state model. See also the
transitionToState method.

Parameters
cStateModel The state model to determine the state of the annotation.

Returns
The result is an array of the identifiers for the current state of the annotation:
● If the state model was defined to be exclusive, there is only a single state (or no states if the state has
not been set).
● If the state model is non-exclusive, there may be multiple states (or no entries if the state has not been
set and there is no default).

Example
Report on the status of all annotations on all pages of this document.
annots = this.getAnnots()
for ( var i= 0; i< annots.length; i++) {
states = annots[i].getStateInModel("Review");
if ( states.length > 0 ) {
for(j = 0; j < states.length; j++)
{
var d = util.printd(2, states[j].modDate);
var s = states[j].state;
var a = states[j].author;

console.println(annots[i].type + ": " + a + " "

+ s + " " + d + "on page "
+ (annots[i].page+1) );
}

}
}

setProps
5.0 D C
Sets many properties of an annotation simultaneously.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference transitionToState 80

Parameters
object literal A generic object that specifies the properties of the Annotation object to be
created (such as type, rect, and page). This object is the same as the parameter of
the Doc object addAnnot method.

Returns
The Annotation object

Example
Set various properties of a Line annotation.
var annot = this.addAnnot({type: "Line"})
annot.setProps({
page: 0,
points: [[10,40],[200,200]],
strokeColor: color.red,
author: "A. C. Robat",
contents: "Check with Jones on this point.",
popupOpen: true,
popupRect: [200, 100, 400, 200], // Place rect at tip of the arrow
arrowBegin: "Diamond",
arrowEnd: "OpenArrow"
});

transitionToState
6.0 D C
Sets the state of the annotation to cState by performing a state transition. The state transition is
recorded in the audit trail of the annotation.

See also the getStateInModel method.

Note: For the states to work correctly in a multiuser environment, all users must have the same state
model definitions. Therefore, it is best to place state model definitions in a folder-level JavaScript file
that can be distributed to all users or installed on all systems.

Parameters
cStateModel The state model in which to perform the state transition. cStateModel must
have been previously added by calling the Collab method addStateModel.
cState A valid state in the state model to transition to.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference transitionToState 81

Example
Define a custom set of transition states, then set the state of an annotation.
try {
// Create a document
var myDoc = app.newDoc();
// Create an annot
var myAnnot = myDoc.addAnnot
({
page: 0,
type: "Text",
point: [300,400],
name: "myAnnot",
});
// Create the state model
var myStates = new Object();
myStates["initial"] = {cUIName: "Haven't reviewed it"};
myStates["approved"] = {cUIName: "I approve"};
myStates["rejected"] = {cUIName: "Forget it"};
myStates["resubmit"] = {cUIName: "Make some changes"};
Collab.addStateModel({
cName: "ReviewStates",
cUIName: "My Review",
oStates: myStates,
cDefault: "initial"
});
} catch(e) { console.println(e); }
// Change the states
myAnnot.transitionToState("ReviewStates", "resubmit");
myAnnot.transitionToState("ReviewStates", "approved");
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference Annot3D 82

Annot3D
An Annot3D object represents a particular Acrobat 3D annotation; that is, an annotation created using the
Acrobat 3D Tool. The Annot3D object can be acquired from the Doc object methods getAnnot3D and
getAnnots3D.

Annot3D properties
activated
7.0

A Boolean value that indicates whether the annotation is displaying the 3D artwork (true) or just the
posterboard picture (false).

See the context3D property.

Type
Boolean

Access
R/W

context3D
7.0

If activated is true, this property returns the context of the 3D annotation (a global object
containing the 3D scene.) (See the JavaScript for Acrobat 3D Annotations API Reference for more
information.) If activated is false, this property returns undefined.

Type
global object

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference innerRect 83

innerRect
7.0

An array of four numbers [xll, yll, xur, yur] specifying the lower-left x, lower-left y, upper-right x and
upper-right y coordinates, in the coordinate system of the annotation (lower-left is [0, 0], top right is
[width, height]), of the 3D annotation’s 3DB box, where the 3D artwork is rendered.

Type
Array

Access
R

name
7.0

The name of the annotation.

Type
String

Access
R

page
7.0

The 0-based page number of the page containing the annotation.

Type
Integer

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference rect 84

rect
7.0

Returns an array of four numbers [xll, yll, xur, yur] specifying the lower-left x, lower-left y, upper-right x and
upper-right y coordinates, in default user space, of the rectangle defining the location of the annotation
on the page.

Type
Array

Access
R/W
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference app 85

app
A static JavaScript object that represents the Acrobat application. It defines a number of Acrobat-specific
functions plus a variety of utility routines and convenience functions.

app properties
activeDocs
5.0 S
An array containing the Doc object for each active document. If no documents are active, activeDocs
returns nothing; that is, it has the same behavior as d = new Array(0) in core JavaScript.

In versions of Acrobat earlier than 7.0, executing the script d = app.activeDocs in the console
returned [object Global] to the console. Beginning with Acrobat 7.0, no toString() value is output
to the console.

Note: You should be aware of the following version-related information:

● In Acrobat 5.0, this property returns an array containing the Doc object for each active document.
● In Acrobat 5.0.5, this property was changed to return an array of Doc objects of only those open
documents that have the Doc object disclosed property set to true.
● Beginning with the Acrobat 5.0.5 Accessibility and Forms Patch and continuing with Acrobat 6.0 and
later, the behavior is as follows: During a batch, console or menu event, activeDocs ignores the
disclosed property and returns an array of Doc objects of the active documents. During any other
event, activeDocs returns an array of Doc objects of only those active documents that have
disclosed set to true.
● Beginning with Acrobat 7.0, execution of JavaScript through a menu event is no longer privileged. See
“Privileged versus non-privileged context” on page 32 for details.

The array returned by app.activeDocs includes any documents opened by app.openDoc with the
bHidden parameter set to true, subject to the security restrictions described above.

Type
Array

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference calculate 86

Example
This example searches among the open documents for the document with a title of myDoc, then inserts a
button in that document using the Doc object addField method. Whether the documents must be
disclosed depends on the version of Acrobat executing this code and on the placement of the code (for
example, console versus mouse-up action).
var d = app.activeDocs;
for (var i=0; i < d.length; i++)
if (d[i].info.Title == "myDoc") {
var f = d[i].addField("myButton", "button", 0 , [20, 100, 100, 20]);
f.setAction("MouseUp","app.beep(0)");
f.fillColor=color.gray;
}

calculate

If true (the default value), calculations can be performed. If false, calculations are not permitted.

The use of this property is discouraged; the Doc object property calculate is preferred.

Type
Boolean

Access
R/W

constants
7.0

A wrapper object for holding various constant values. Currently, this property returns an object with a
single property, align.

app.constants.align is an object that has the possible properties left, center, right, top, and
bottom, indicating the type of alignment. These values can be used to specify alignment, such as when
adding a watermark.

Type
Object

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference focusRect 87

Example
See the Doc object methods addWatermarkFromFile and addWatermarkFromText for examples.

focusRect
4.05 P

Turns the focus rectangle on and off. The focus rectangle is the faint dotted line around buttons, check
boxes, radio buttons, and signatures to indicate that the form field has the keyboard focus. A value of true
turns on the focus rectangle.

Type
Boolean

Access
R/W

Example
Turn off the focus rectangle.
app.focusRect = false;

formsVersion
4.0

The version number of the viewer forms software. Check this property to determine whether objects,
properties, or methods in newer versions of the software are available if you want to maintain backward
compatibility in your scripts.

Type
Number

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference fromPDFConverters 88

Example
if (typeof app.formsVersion != "undefined" && app.formsVersion >= 5.0)
{
// Perform version specific operations here.
// For example, toggle full screen mode
app.fs.cursor = cursor.visible;
app.fs.defaultTransition = "";
app.fs.useTimer = false;
app.fs.isFullScreen = !app.fs.isFullScreen;
}
else app.fullscreen = !app.fullscreen;

fromPDFConverters
6.0

An array of file type conversion ID strings. A conversion ID string can be passed to the Doc object saveAs
method.

Type
Array

Access
R

Example
List all currently supported conversion ID strings.
for ( var i = 0; i < app.fromPDFConverters.length; i++)
console.println(app.fromPDFConverters[i]);

fs
5.0

A FullScreen object, which can be used to access the fullscreen properties.

Type
Object

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference fullscreen 89

Example
// This code puts the viewer into fullscreen (presentation) mode.
app.fs.isFullScreen = true;

See also fullScreenObject.isFullScreen.

fullscreen

The use of this property is discouraged; it has been superseded by the FullScreen object property
isFullScreen. The fs method returns a FullScreen object that can be used to access the fullscreen
properties.

Controls whether the viewer is in full screen mode or regular viewing mode.

Note: A PDF document being viewed from within a web browser cannot be put into full screen mode. Full
screen mode can be initiated from within the browser, but applies only to a document open in the
Acrobat viewer application, if any, not to the browser itself.

Type
Boolean

Access
R/W

language
3.01

The language of the running Acrobat viewer. It can be one of the following strings.

String Language

CHS Chinese Simplified

CHT Chinese Traditional

DAN Danish

DEU German

ENU English

ESP Spanish

FRA French

ITA Italian
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference media 90

String Language

KOR Korean

JPN Japanese

NLD Dutch

NOR Norwegian

PTB Brazilian Portuguese

SUO Finnish

SVE Swedish

Type
String

Access
R

media
6.0

Defines an extensive number of properties and methods useful for setting up and controlling a
multimedia player.
See the app.media object for a listing of the properties and methods of this object, as well as numerous
examples of use.

Type
Object

Access
R

monitors
6.0

A Monitors object, which is an array containing one or more Monitor objects representing each of the
display monitors connected to the user’s system. Each access to app.monitors returns a new, up-to-date
copy of this array.
A Monitors object also has several methods that can be used to select a display monitor. Alternatively,
JavaScript code can look through the array explicitly.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference numPlugIns 91

Type
Monitors object

Access
R

Example
Count the number of display monitors connected to the user’s system.
var monitors = app.monitors;
console.println("There are " + monitors.length
+ " monitor(s) connected to this system.");

numPlugIns

Note: This method has been superseded by the plugIns property.

Indicates the number of plug-ins that have been loaded by Acrobat.

Type
Number

Access
R

openInPlace
4.0 P

Specifies whether cross-document links are opened in the same window or opened in a new window.

Type
Boolean

Access
R/W
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference platform 92

Example
Open cross-document links in the same window.
app.openInPlace = true;

platform
4.0

The platform that the script is currently executing on. There are three valid values:
WIN
MAC
UNIX

Type
String

Access
R

plugIns
5.0

An array of PlugIn objects representing the plug-ins that are currently installed in the viewer.

Type
Array

Access
R

Example
// Get array of PlugIn objects
var aPlugins = app.plugIns;
// Get number of plug-ins
var nPlugins = aPlugins.length;
// Enumerate names of all plug-ins
for ( var i = 0; i < nPlugins; i++)
console.println("Plugin \#"+i+" is " + aPlugins[i].name);
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference printColorProfiles 93

printColorProfiles
6.0 X

A list of available printer color spaces. Each of these values is suitable to use as the value of the
colorProfile property of a PrintParams object.

Type
Array of Strings

Access
R

Example
Print out a listing of available printer color spaces:
var l = app.printColorProfiles.length
for ( var i = 0; i < l; i++)
console.println("(" + (i+1) + ") " + app.printColorProfiles[i]);

printerNames
6.0

A list of available printers. Each of these values is suitable to use in the printerName property of the
PrintParams object. If no printers are installed on the system, an empty array is returned.

Type
Array of Strings

Access
R

Example
Print out a listing of available printers:
var l = app.printerNames.length
for ( var i = 0; i < l; i++)
console.println("(" + (i+1) + ") " + app.printerNames[i]);
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference runtimeHighlight 94

runtimeHighlight
6.0 P

If true, the background color and hover color for form fields are shown.

Type
Boolean

Access
R/W

Example
If run-time highlighting is off (false), do nothing, otherwise change the preferences.
if (!app.runtimeHighlight)
{
app.runtimeHighlight = true;
app.runtimeHighlightColor = color.red;
}

runtimeHighlightColor
6.0 P

Sets the color for runtime highlighting of form fields.

The value of this property is a color array. (See “Color arrays” on page 193 for details.)

Type
Color array

Access
R/W

Example
See the runtimeHighlight property.

thermometer
6.0

A Thermometer object, which is a combined status window/progress bar that indicates to the user that a
lengthy operation is in progress.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference toolbar 95

Type
Object

Access
R

Example
See the Thermometer object.

toolbar
3.01 P

Allows a script to show or hide both the horizontal and vertical Acrobat toolbars. It does not hide the
toolbar in external windows (that is, in an Acrobat window within a web browser).

Type
Boolean

Access
R/W

Example
Hide the toolbar.
app.toolbar = false;

toolbarHorizontal

X P

Note: This property has been deprecated in Acrobat 5.0 and later. If accessed, it acts like toolbar.

Allows a script to show or hide the Acrobat horizontal toolbar. It does not hide the toolbar in external
windows (that is, in an Acrobat window within a web browser).

Type
Boolean
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference toolbarVertical 96

Access
R/W

toolbarVertical

X P

Note: This property has been deprecated in Acrobat 5.0 and later. If accessed, it acts like toolbar.

Allows a script to show or hide the Acrobat vertical toolbar. It does not hide the toolbar in external
windows (that is, in an Acrobat window within a web browser).

Type
Boolean

Access
R/W

viewerType
3.01

A string that indicates which viewer application is running. It can be one of these values.

Value Description

Reader Acrobat Reader version 5.0 or earlier / Adobe Reader version 5.1 or later

Exchange Adobe Acrobat earlier than version 6.0 / Acrobat Standard version 6.0 or later

Exchange-Pro Acrobat Professional version 6.0 or later

Type
String

Access
R
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference viewerVariation 97

viewerVariation
5.0

Indicates the packaging of the running viewer application. It can be one of these values:
Reader
Fill-In
Business Tools
Full

Type
String

Access
R

viewerVersion
4.0

Indicates the version number of the current viewer application.

Type
Number

Access
R

app methods
addMenuItem
5.0 S

Adds a menu item to a menu.

Note: This method can only be executed during application initialization or console events. See the
event object for a discussion of JavaScript events.

See also the addSubMenu, execMenuItem, hideMenuItem, and listMenuItems methods.

Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference addMenuItem 98

Parameters
cName The language-independent name of the menu item. This name can be used by other
methods (for example, hideMenuItem) to access the menu item.
cUser (optional) The user string (language-dependent name) to display as the menu item name.
If cUser is not specified, cName is used.
cParent The name of the parent menu item. Its submenu will have the new menu item added to it.
If cParent has no submenu, an exception is thrown.
Menu item names can be obtained with the listMenuItems method.
nPos (optional) The position within the submenu to locate the new menu item. The default
behavior is to append to the end of the submenu. Specifying nPos as 0 adds the menu to
the top of the submenu. Beginning with Acrobat 6.0, the value of nPos can also be the
language-independent name of a menu item.
(Acrobat 6.0) If the value nPos is a string, this string is interpreted as a named item in the
menu (a language-independent name of a menu item). The named item determines the
position at which the new menu item is to be inserted. See bPrepend for additional details.
The nPos parameter is ignored in certain menus that are alphabetized. The alphabetized
menus are
● The first section of View > Navigation Panels.
● The first section of View > Toolbars.
● The first section of the Advanced submenu.
Note: When nPos is a number, nPos is not obeyed in the Tools menu. A menu item
introduced into the Tools menu comes in at the top of the menu. nPos is obeyed
when it is a string referencing another user-defined menu item.
cExec An expression string to evaluate when the menu item is selected by the user.
Note: Beginning with Acrobat 7.0, execution of JavaScript through a menu event is no
longer privileged. See “Privileged versus non-privileged context” on page 32 for
details.
cEnable (optional) An expression string that is evaluated to determine whether to enable the
menu item. The default is that the menu item is always enabled. This expression should
set event.rc to false to disable the menu item.
cMarked (optional) An expression string that determines whether the menu item has a check mark
next to it. The expression should set event.rc to false to uncheck the menu item and
true to check it. The default is that the menu item is not marked.

bPrepend (optional, Acrobat 6.0) Determines the position of the new menu item relative to the
position specified by nPos. The default value is false. If bPrepend is true, the rules for
insertion are as follows:
● If nPos is a string, the new item is placed before the named item.
● If nPos is a number, the new item is placed before the numbered item.
● If the named item cannot be found or nPos is not between zero and the number of
items in the list, inclusive, the new item is inserted as the first item in the menu (rather
than at the end of the menu).
bPrepend is useful when the named item is the first item in a group.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference addSubMenu 99

Example 1
At the top of the File menu, add a menu item that opens an alert dialog box displaying the active
document title. This menu is only enabled if a document is opened.
app.addMenuItem({ cName: "Hello", cParent: "File",
cExec: "app.alert(event.target.info.title, 3);",
cEnable: "event.rc = (event.target != null);",
nPos: 0
});

Example 2 (Acrobat 6.0)

Place two menu items in the File menu, one before the Close item and the other after the Close item.
// Insert after the "Close" item (the default behavior)
app.addMenuItem( { cName: "myItem1", cUser: "My Item 1", cParent:
"File", cExec: "_myProc1()", nPos: "Close"});
// Insert before the "Close" item, set bPrepend to true.
app.addMenuItem( { cName: "myItem2", cUser: "My Item 2", cParent:
"File", cExec: "_myProc2()", nPos: "Close", bPrepend: true });

addSubMenu
5.0 S

Adds a menu item with a submenu to the application.

See also the addMenuItem, execMenuItem, hideMenuItem, and listMenuItems methods.
Note: This method can only be executed during application initialization or console events. See the
event object for a discussion of JavaScript events.

Parameters
cName The language-independent name of the menu item. This language-independent name is
used to access the menu item (for example, for hideMenuItem).
cUser (optional) The user string (language-dependent name) to display as the menu item name.
If cUser is not specified, cName is used.
cParent The name of the parent menu item to receive the new submenu.
Menu item names can be discovered with listMenuItems.
nPos (optional) The position within the parent’s submenu to locate the new submenu. The
default is to append to the end of the parent’s submenu. Specifying nPos as 0 adds the
submenu to the top of the parent’s submenu.
The nPos parameter is ignored in certain menus that are alphabetized. The alphabetized
menus are
● The first section of View > Navigational Panels.
● The first section of View > Toolbars.
● The first section of the Advanced submenu.
Note: When nPos is a number, nPos is not obeyed in the Tools menu. A menu item
introduced into the Tools menu comes in at the top of the menu. nPos is obeyed
when nPos is a string referencing another user-defined menu item.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference addToolButton 100

Example
See the newDoc method.

addToolButton
6.0

Adds a button to the “Add-on” toolbar of Acrobat.

If there is an active document (for example, docA.pdf) open in Acrobat when this method is called to
add a button, Acrobat will remove the button when docA.pdf is either no longer active or is closed. In
the former case, the button will be automatically added to the toolbar if docA.pdf becomes the active
document again.

The icon size is restricted to 20 by 20 pixels. If an icon of larger dimensions is used, an exception is thrown.

Note: (Acrobat 7.0) A number of changes have been made with regard to the secure use of this method.
Execution of addToolButton in the console and application initialization is considered privileged
execution and is trusted.
If this method is called from nonprivileged script, the warning “JavaScript Window” appears on the
“Add-on” toolbar, which will not be dockable. (See “Privileged versus non-privileged context” on
page 32.)

See also removeToolButton.

Parameters
cName A unique language-independent identifier for the button. The
language-independent name is used to access the button for other methods (for
example, removeToolButton).
Note: The value of cName must be unique. To avoid a name conflict, check
listToolbarButtons, which lists all toolbar button names currently
installed.
oIcon An Icon Stream object.
Beginning with Acrobat 7.0, this parameter is optional if a cLabel is provided.
cExec The expression string to evaluate when the button is selected.
cEnable (optional) An expression string that determines whether to enable the toolbutton.
The default is that the button is always enabled. This expression should set
event.rc to false to disable the button.

cMarked (optional) An expression string that determines whether the toolbutton is marked.
The default is that the button is not marked. This expression should set event.rc to
true to mark the button.

cTooltext (optional) The text to display in the button help text when the mouse is over the
toolbutton. The default is not to have a tool tip.
Note: Avoid the use of extended characters in the cTooltext string as the string
may be truncated.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference alert 101

nPos (optional) The button number to place the added button before in the toolbar. If
nPos is -1 (the default), the button is appended to the toolbar.

cLabel (optional, Acrobat 7.0) A text label to be displayed on the button to the right of the
icon. The default is not to have a label.

Returns
undefined

Example
Create a button from an icon graphic on the user’s hard drive. This script is executed from the console.
// Create a document
var myDoc = app.newDoc();

// import icon (20x20 pixels) from the file specified

myDoc.importIcon("myIcon", "/C/myIcon.jpg", 0);

// convert the icon to a stream.

oIcon = util.iconStreamFromIcon(myDoc.getIcon("myIcon"));

// close the doc now that we have grabbed the icon stream
myDoc.closeDoc(true);

// add a toolbutton
app.addToolButton({
cName: "myToolButton",
oIcon: oIcon,
cExec: "app.alert('Someone pressed me!')",
cTooltext: "Push Me!",
cEnable: true,
nPos: 0
});

app.removeToolButton("myToolButton")

See also the example following util.iconStreamFromIcon.

alert
3.01

Displays an alert dialog box.

Note: If this method is called on a button click event using LiveCycle Designer 7 or 8, it appends the title
"Warning: JavaScript Window - " in Acrobat 8.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference alert 102

Parameters
cMsg A string containing the message to be displayed.
nIcon (optional) An icon type. Possible values are these:
0 — Error (default)
1 — Warning
2 — Question
3 — Status
Note: In Mac OS, there is no distinction between warnings and questions.
nType (optional) A button group type. Possible values are these:
0 — OK (default)
1 — OK, Cancel
2 — Yes, No
3 — Yes, No, Cancel

cTitle (optional, Acrobat 6.0) The dialog box title. If not specified, the title “Adobe Acrobat” is used.
oDoc (optional, Acrobat 6.0) The Doc object that the alert should be associated with.
oCheckbox (optional, Acrobat 6.0) If specified, a check box is created in the lower left region of the
alert box. oCheckbox is a generic JavaScript object that has three properties. The first
two property values are passed to the alert method; the third property returns a
Boolean value.
cMsg — (optional) A string to display with the check box. If not specified, the default
string is “Do not show this message again”.
bInitialValue — (optional) If true, the initial state of the check box is checked.
The default is false.
bAfterValue — When the alert method exits, contains the state of the check box
when the dialog box is closed. If true, the check box was checked when the alert
box is closed.

Returns
nButton, the type of the button that was pressed by the user:
1 — OK
2 — Cancel
3 — No
4 — Yes

Example 1
Display a simple alert box:
app.alert({
cMsg: "Error! Try again!",
cTitle: "Acme Testing Service"
});
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference beep 103

Example 2
Close the document with the user’s permission:
// A MouseUp action
var nButton = app.alert({
cMsg: "Do you want to close this document?",
cTitle: "A message from A. C. Robat",
nIcon: 2, nType: 2
});
if ( nButton == 4 ) this.closeDoc();

Example 3 (Acrobat 6.0)

One document creates an alert box in another document. There are two documents, DocA and DocB, one
open in a browser and the other in the viewer.
// The following is a declaration at the document level in DocA
var myAlertBoxes = new Object;
myAlertBoxes.oMyCheckbox = {
cMsg: "Care to see this message again?",
bAfterValue: false
}

The following is a mouse-up action in DocA. The variable theOtherDoc is the Doc object of DocB. The
alert box asks if the user wants to see this alert box again. If the user clicks the check box, the alert does not
appear again.
if ( !myAlertBoxes.oMyCheckbox.bAfterValue )
{
app.alert({
cMsg: "This is a message from the DocA?",
cTitle: "A message from A. C. Robat",
oDoc:theOtherDoc,
oCheckbox: myAlertBoxes.oMyCheckbox
});
}

beep
3.01

Causes the system to play a sound.

Note: On Mac OS and UNIX systems the beep type is ignored.

Parameters
nType (optional) The sound type. Values are associated with sounds as follows:
0 — Error
1 — Warning
2 — Question
3 — Status
4 — Default (default value)
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference beginPriv 104

beginPriv
7.0 S

Raises the execution privilege of the current stack frame such that methods marked secure can execute
without security exceptions. For the method to succeed, there must be a frame on the stack representing
the execution of a trusted function, and all frames (including the frame making the call) between the
currently executing frame and that frame must represent the execution of trust propagator functions.

Use app.endPriv to revoke privilege. The app.trustedFunction method can create a trusted
function, and app.trustPropagatorFunction can create a trust propagator function. The term stack
frame is discussed following the description of app.trustedFunction.

Returns
undefined on success, exception on failure

Example
For examples of usage, see trustedFunction and trustPropagatorFunction.

browseForDoc
7.0 S 7.0

Presents a file system browser and returns an object containing information concerning the user’s
response.

Note: This method can only be executed during a batch or console event. See the event object for a
discussion of JavaScript events. See “Privileged versus non-privileged context” on page 32 for
details.

Parameters
bSave (optional) A Boolean value that, if true, specifies that the file system browser should
be presented as it would be for a save operation. The default is false.
cFilenameInit (optional) A string that specifies the default file name for the file system browser to
be populated with.
cFSInit (optional) A string that specifies the file system that the file system browser operates
on initially. Two values are supported: “” (the empty string) representing the default
file system and “CHTTP”. The default is the default file system. This parameter is only
relevant if the web server supports WebDAV.
Adobe Acrobat SDK JavaScript API
JavaScript for Acrobat API Reference browseForDoc 105

Returns
On success, returns an object that has three properties.

Property Description
cFS A string containing the resulting file system name for the chosen file.
cPath A string containing the resulting path for the chosen file.
cURL A string containing the resulting URL for the chosen file

If the user cancels, the return value is undefined. On error, throws an exception.

Example 1
Browse for a document and report the results to the console.
var oRetn = app.browseForDoc({
cFilenameInit: "myComDoc.pdf",
cFSInit: "CHTTP",
});
if ( typeof oRetn != "undefined" )
for ( var o in oRetn )
console.println( "oRetn." + o + "=" + oRetn[o]);
else console.println("User cancelled!");

If the user selects a file on a WebDAV server, a possible output of this code is given below:
oRetn.cFS=CHTTP
oRetn.cPath=http://www.example.com/WebDAV/myComDoc.pdf
oRetn.cURL=http://www.example.com/WebDAV/myComDoc.pdf

Should the user select a file in the default file system, a typical output of this code is given below:
oRetn.cFS=DOS
oRetn.cPath=/C/temp/myComDoc.pdf
oRetn.cURL=file:///C|/temp/myComDoc.pdf

The script can go on to open the selected file using app.openDoc.

var myURL = (oRetn.cFS=="CHTTP") ? encodeURI(oRetn.cPath) : oRetn.cPath;
var oDoc = app.openDoc({cPath: myURL, cFS: oRetn.cFS});

Note: app.openDoc requires cPath to be an escaped string when retrieving a file from a WebDAV
server. See app.openDoc for a brief description and example.

Example 2
Browse and save a document.
var oRetn = app.browseForDoc({
bSave: true,
cFilenameInit: "myComDoc.pdf",
cFSInit: "CHTTP",
});
if ( typeof oRetn != "undefined" ) this.saveAs({
cFS: oRetn.cFS, cPath: oRetn.cPath, bPromptToOverwrite: false});