Macromedia Bridge - CS2 User Manual
2
Creative Suite
®
Bridge JavaScript Reference
Adobe
bbc
© 2005 Adobe Systems Incorporated. All rights reserved.
Adobe® Creative Suite 2
Bridge JavaScript Reference for Windows® and Macintosh®.
NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or
electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or
otherwise, without the prior written consent of Adobe Systems Incorporated. The software described in this document is furnished under
license and may only be used or copied in accordance with the terms of such license.
This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or
inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and
all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights.
Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual
organization.
Adobe, the Adobe logo, Acrobat, GoLive, Illustrator, Photoshop, InDesign, and Version Cue are either registered trademarks or trademarks of
Adobe Systems Incorporated in the United States and/or other countries.
Apple, Mac, Macintosh, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft,
and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. JavaScript
and all Java-related marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is
a registered trademark of The Open Group.
All other trademarks are the property of their respective owners.
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.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Contents
Welcome ..................................................................................................................................... 19
About This Book............................................................................................................................................................................19
Who should read this book ................................................................................................................................................19
What is in this book ...............................................................................................................................................................19
Document conventions .......................................................................................................................................................20
Typographical conventions .........................................................................................................................................20
JavaScript conventions..................................................................................................................................................20
Where to go for more information ..................................................................................................................................21
1 Scripting Bridge .........................................................................................................................22
Scripting Overview ......................................................................................................................................................................22
Executing Scripts....................................................................................................................................................................22
Communicating with Other Applications.....................................................................................................................23
The Bridge Document Object Model ...................................................................................................................................23
The application and documents.......................................................................................................................................24
Thumbnails in documents..................................................................................................................................................25
Thumbnails as node references .................................................................................................................................25
Using and accessing thumbnails ...............................................................................................................................25
User interface objects...........................................................................................................................................................26
Navigation bars ................................................................................................................................................................26
Dialogs.................................................................................................................................................................................26
Menus ..................................................................................................................................................................................27
Events.........................................................................................................................................................................................27
Application preferences ......................................................................................................................................................27
The Bridge DOM and the Bridge Browser Window..........................................................................................................28
2 Event Handling and Script-Defined Browse Schemes ............................................................ 31
Event Handling in Bridge...........................................................................................................................................................31
Defining event handlers......................................................................................................................................................31
Registering event handlers.................................................................................................................................................32
Event handling examples....................................................................................................................................................32
User-interface events............................................................................................................................................................35
Script-Defined Browse Schemes.............................................................................................................................................36
Defining and registering a browse scheme .................................................................................................................36
3 Creating a User Interface ..........................................................................................................38
User Interface Options for Scripts...........................................................................................................................................38
Navigation Bars.......................................................................................................................................................................38
Dialogs Boxes ..........................................................................................................................................................................39
Content Pane...........................................................................................................................................................................39
ScriptUI User Interfaces ..............................................................................................................................................................40
Displaying ScriptUI Dialogs ................................................................................................................................................40
Displaying ScriptUI elements in a navigation bar ......................................................................................................40
Displaying HTML in Bridge........................................................................................................................................................42
Defining callbacks for HTML scripts ................................................................................................................................42
Executing script functions defined on HTML UI pages ............................................................................................43
Displaying HTML in Bridge Dialogs........................................................................................................................................44
3
Adobe Creative Suite 2
Bridge JavaScript Reference 4
Communicating with Bridge from dialog JavaScript................................................................................................44
Using callbacks in an HTML dialog ..................................................................................................................................45
Calling functions defined in an HTML dialog ........................................................................................................47
Displaying HTML in a Navigation Bar ....................................................................................................................................47
Using callbacks from an HTML navigation bar............................................................................................................47
Calling functions defined in an HTML navigation bar..............................................................................................48
Displaying HTML in the Content Pane..................................................................................................................................50
Callback example: Requesting specific metadata value for a file.........................................................................50
Passing Complex Values in Remote Calls ............................................................................................................................51
Passing an object from Bridge to HTML/JavaScript ..................................................................................................52
Scheduling tasks from callbacks .............................................................................................................................................53
Scheduling a remote function execution......................................................................................................................54
4 Using File and Folder Objects ................................................................................................... 56
Overview .........................................................................................................................................................................................56
Specifying Paths............................................................................................................................................................................56
Absolute and relative path names...................................................................................................................................56
Character interpretation in paths.....................................................................................................................................57
The home directory...............................................................................................................................................................57
Volume and drive names ....................................................................................................................................................58
Mac OS volumes...............................................................................................................................................................58
Windows drives ................................................................................................................................................................58
Aliases.........................................................................................................................................................................................59
Portability issues.....................................................................................................................................................................59
Unicode I/O ....................................................................................................................................................................................59
File Error Handling ......................................................................................................................................................................60
5 Using ScriptUI ............................................................................................................................61
Overview .........................................................................................................................................................................................61
ScriptUI Programming Model ..................................................................................................................................................61
Creating a window ...............................................................................................................................................................61
Container elements...............................................................................................................................................................62
Window layout .......................................................................................................................................................................62
Adding elements to containers ........................................................................................................................................63
Creation properties.........................................................................................................................................................64
Accessing child elements ............................................................................................................................................64
Removing elements ..............................................................................................................................................................65
Types of controls ...................................................................................................................................................................65
Containers ..........................................................................................................................................................................65
Panel...................................................................................................................................................................................65
Group .................................................................................................................................................................................65
User interface controls...................................................................................................................................................65
StaticText ..........................................................................................................................................................................66
EditText .............................................................................................................................................................................66
Button ................................................................................................................................................................................66
IconButton .......................................................................................................................................................................66
Image .................................................................................................................................................................................67
Checkbox ..........................................................................................................................................................................67
RadioButton.....................................................................................................................................................................67
Progressbar......................................................................................................................................................................67
Slider...................................................................................................................................................................................67
Scrollbar ............................................................................................................................................................................68
Adobe Creative Suite 2
Bridge JavaScript Reference 5
ListBox................................................................................................................................................................................68
DropDownList.................................................................................................................................................................68
ListItem..............................................................................................................................................................................68
Displaying icons......................................................................................................................................................................68
Prompts and alerts ...............................................................................................................................................................69
Modal dialogs .........................................................................................................................................................................69
Creating and using modal dialogs ............................................................................................................................69
Dismissing a modal dialog ...........................................................................................................................................70
Default and cancel elements.......................................................................................................................................70
Resource Specifications ............................................................................................................................................................71
Defining Behavior for Controls with Event Callbacks .....................................................................................................73
Defining event handler functions ....................................................................................................................................73
Simulating user events.........................................................................................................................................................73
Automatic Layout ........................................................................................................................................................................75
Default layout behavior .......................................................................................................................................................75
Automatic layout properties..............................................................................................................................................76
Container orientation.....................................................................................................................................................76
Aligning children .............................................................................................................................................................76
Setting margins ................................................................................................................................................................78
Spacing between children ...........................................................................................................................................79
Determining a preferred size.......................................................................................................................................79
Creating more complex arrangements ...................................................................................................................79
Creating dynamic content............................................................................................................................................81
Custom layout manager example....................................................................................................................................82
The AutoLayoutManager algorithm ...............................................................................................................................84
Automatic layout restrictions ............................................................................................................................................85
Example scripts .............................................................................................................................................................................86
Alert box builder.....................................................................................................................................................................86
Resource specification example.................................................................................................................................89
Localization in ScriptUI Objects ..............................................................................................................................................91
Variable values in localized strings ..................................................................................................................................91
Enabling automatic localization .......................................................................................................................................91
6 Bridge DOM Object Reference.................................................................................................. 93
App Object......................................................................................................................................................................................94
App object properties ..........................................................................................................................................................94
displayDialogs.................................................................................................................................................................94
document .........................................................................................................................................................................94
documents .......................................................................................................................................................................94
eventHandlers.................................................................................................................................................................94
favorites.............................................................................................................................................................................94
language ...........................................................................................................................................................................94
locale ..................................................................................................................................................................................95
name...................................................................................................................................................................................95
preferences ......................................................................................................................................................................95
version ...............................................................................................................................................................................95
App object functions ............................................................................................................................................................95
beep....................................................................................................................................................................................95
browseTo ..........................................................................................................................................................................95
buildFolderCache ..........................................................................................................................................................96
cancelTask ........................................................................................................................................................................96
Adobe Creative Suite 2
Bridge JavaScript Reference 6
hide.....................................................................................................................................................................................96
preflightFiles....................................................................................................................................................................96
purgeAllCaches ..............................................................................................................................................................96
purgeFolderCache.........................................................................................................................................................96
quit......................................................................................................................................................................................97
registerBrowseScheme................................................................................................................................................97
scheduleTask...................................................................................................................................................................97
system................................................................................................................................................................................97
Dialog Object ................................................................................................................................................................................98
Dialog object constructor ...................................................................................................................................................98
Dialog object properties......................................................................................................................................................98
active ..................................................................................................................................................................................98
closing................................................................................................................................................................................98
height.................................................................................................................................................................................98
modal .................................................................................................................................................................................98
title ......................................................................................................................................................................................98
width ..................................................................................................................................................................................98
Dialog object functions .......................................................................................................................................................98
center .................................................................................................................................................................................98
close....................................................................................................................................................................................98
execJS.................................................................................................................................................................................99
open ..................................................................................................................................................................................99
place ...................................................................................................................................................................................99
print ....................................................................................................................................................................................99
Document Object...................................................................................................................................................................... 100
Document object properties .......................................................................................................................................... 100
allowDrags .................................................................................................................................................................... 100
contentPaneMode ..................................................................................................................................................... 100
context............................................................................................................................................................................ 100
id ....................................................................................................................................................................................... 100
jsFuncs ............................................................................................................................................................................ 100
maximized..................................................................................................................................................................... 100
minimized...................................................................................................................................................................... 100
navbars ........................................................................................................................................................................... 101
noItems........................................................................................................................................................................... 101
owner .............................................................................................................................................................................. 101
previewLooping.......................................................................................................................................................... 101
selections....................................................................................................................................................................... 101
showThumbnailName .............................................................................................................................................. 101
sorts ................................................................................................................................................................................. 102
status............................................................................................................................................................................... 102
thumbnail ...................................................................................................................................................................... 102
thumbnailViewMode ................................................................................................................................................ 102
visible .............................................................................................................................................................................. 102
visibleThumbnails ...................................................................................................................................................... 103
visitUrl ............................................................................................................................................................................. 103
Document object functions ............................................................................................................................................ 103
bringToFront ................................................................................................................................................................ 103
close................................................................................................................................................................................. 103
deselect .......................................................................................................................................................................... 104
deselectAll..................................................................................................................
................................................... 104
Adobe Creative Suite 2
Bridge JavaScript Reference 7
execJS.............................................................................................................................................................................. 104
maximize........................................................................................................................................................................ 104
minimize ........................................................................................................................................................................ 104
refresh............................................................................................................................................................................. 104
resetToDefaultWorkspace ....................................................................................................................................... 104
restore............................................................................................................................................................................. 104
reveal............................................................................................................................................................................... 105
select ............................................................................................................................................................................... 105
selectAll .......................................................................................................................................................................... 105
Event Object................................................................................................................................................................................ 106
Event object properties .................................................................................................................................................... 106
appPath.......................................................................................................................................................................... 106
document ...................................................................................................................................................................... 106
favorites.......................................................................................................................................................................... 106
isContext........................................................................................................................................................................ 106
location........................................................................................................................................................................... 106
object .............................................................................................................................................................................. 107
type.................................................................................................................................................................................. 107
url...................................................................................................................................................................................... 107
where .............................................................................................................................................................................. 107
Event Object Types............................................................................................................................................................. 107
App events ...................................................................................................................................................................... 107
close................................................................................................................................................................................. 107
destroy............................................................................................................................................................................ 107
Document events ......................................................................................................................................................... 108
complete........................................................................................................................................................................ 108
create .............................................................................................................................................................................. 108
deselect .......................................................................................................................................................................... 108
destroy............................................................................................................................................................................ 108
empty.............................................................................................................................................................................. 108
failed................................................................................................................................................................................ 108
loaded............................................................................................................................................................................. 108
loading............................................................................................................................................................................ 108
open ................................................................................................................................................................................ 108
select ............................................................................................................................................................................... 108
stopped .......................................................................................................................................................................... 108
uploading ...................................................................................................................................................................... 108
Thumbnail events......................................................................................................................................................... 109
add ................................................................................................................................................................................... 109
deselect .......................................................................................................................................................................... 109
hover ............................................................................................................................................................................... 109
modify............................................................................................................................................................................. 109
move................................................................................................................................................................................ 109
open ................................................................................................................................................................................ 109
openWith ....................................................................................................................................................................... 109
preview........................................................................................................................................................................... 109
remove............................................................................................................................................................................ 110
select ............................................................................................................................................................................... 110
PreferencesDialog events.......................................................................................................................................... 110
cancel .............................................................................................................................................................................. 110
create .......................................................................................................................
....................................................... 110
Adobe Creative Suite 2
Bridge JavaScript Reference 8
destroy............................................................................................................................................................................ 110
ok ...................................................................................................................................................................................... 110
Favorites Object......................................................................................................................................................................... 111
Favorites object properties ............................................................................................................................................. 111
length.............................................................................................................................................................................. 111
section ............................................................................................................................................................................ 111
Favorites object functions ............................................................................................................................................... 111
addChild......................................................................................................................................................................... 111
clearAll ............................................................................................................................................................................ 111
insert................................................................................................................................................................................ 111
remove............................................................................................................................................................................ 112
Metadata Object ........................................................................................................................................................................ 113
Metadata object properties............................................................................................................................................. 113
Label ................................................................................................................................................................................ 113
namespace.................................................................................................................................................................... 114
xmpPropertyName ...................................................................................................................................................... 114
Examples.......................................................................................................................................................................... 114
Metadata object functions .............................................................................................................................................. 115
applyMetadataTemplate ......................................................................................................................................... 115
NavBar Object............................................................................................................................................................................. 116
NavBar object properties ................................................................................................................................................. 116
file..................................................................................................................................................................................... 116
height.............................................................................................................................................................................. 116
jsFuncs ........................................................................................................................................................................... 116
type.................................................................................................................................................................................. 117
visible .............................................................................................................................................................................. 117
NavBar object functions ................................................................................................................................................... 117
add ................................................................................................................................................................................... 117
execJS.............................................................................................................................................................................. 118
print ................................................................................................................................................................................. 118
Preferences Object.................................................................................................................................................................... 119
Preferences object properties ........................................................................................................................................ 119
extraMetadata.............................................................................................................................................................. 119
showName .................................................................................................................................................................... 119
BackgroundColor........................................................................................................................................................ 120
FileSize............................................................................................................................................................................ 120
HideEmptyFields......................................................................................................................................................... 120
Label1.............................................................................................................................................................................. 120
Label2.............................................................................................................................................................................. 120
Label3.............................................................................................................................................................................. 120
Label4.............................................................................................................................................................................. 120
Label5.............................................................................................................................................................................. 120
Language....................................................................................................................................................................... 120
MRUCount..................................................................................................................................................................... 120
ShowLabels................................................................................................................................................................... 120
ShowName.................................................................................................................................................................... 120
UseLocalCaches........................................................................................................................................................... 121
anyPropertyName........................................................................................................................................................ 121
Preferences object functions ...................................................................................................
....................................... 121
clear ................................................................................................................................................................................. 121
PreferencesDialog Object ...................................................................................................................................................... 122
Adobe Creative Suite 2
Bridge JavaScript Reference 9
PreferencesDialog object functions............................................................................................................................. 122
addPanel ........................................................................................................................................................................ 122
close................................................................................................................................................................................. 122
Thumbnail Object ..................................................................................................................................................................... 123
Thumbnail object constructor ....................................................................................................................................... 123
Node specifiers .............................................................................................................................................................. 123
Multiple references to the same node .................................................................................................................. 124
Thumbnail object properties .......................................................................................................................................... 125
aliasType ........................................................................................................................................................................ 125
children .......................................................................................................................................................................... 125
container........................................................................................................................................................................ 125
creationDate................................................................................................................................................................. 125
displayMode ................................................................................................................................................................. 125
displayPath.................................................................................................................................................................... 125
hidden............................................................................................................................................................................. 125
lastModifiedDate ........................................................................................................................................................ 125
location........................................................................................................................................................................... 126
metadata........................................................................................................................................................................ 126
mimeType...................................................................................................................................................................... 126
name................................................................................................................................................................................ 126
parent.............................................................................................................................................................................. 126
path.................................................................................................................................................................................. 126
spec.................................................................................................................................................................................. 126
synchronousMetadata.............................................................................................................................................. 126
type.................................................................................................................................................................................. 126
Thumbnail object functions............................................................................................................................................ 126
copyTo ............................................................................................................................................................................ 126
moveTo .......................................................................................................................................................................... 127
open ................................................................................................................................................................................ 127
openWith ....................................................................................................................................................................... 127
refresh............................................................................................................................................................................. 127
remove............................................................................................................................................................................ 128
resolve............................................................................................................................................................................. 128
7 File and Folder Object Reference ...........................................................................................129
Overview ...................................................................................................................................................................................... 129
File Object .................................................................................................................................................................................... 129
File object constructors .................................................................................................................................................... 129
File class properties............................................................................................................................................................ 130
fs........................................................................................................................................................................................ 130
File class functions.............................................................................................................................................................. 130
decode............................................................................................................................................................................ 130
encode............................................................................................................................................................................ 130
isEncodingAvailable .................................................................................................................................................. 130
openDialog ................................................................................................................................................................... 131
saveDialog..................................................................................................................................................................... 131
File object properties......................................................................................................................................................... 132
absoluteURI................................................................................................................................................................... 132
alias .................................................................................................................................................................................. 132
created............................................................................................................................................................................ 132
creator............................................................................................................................................................................. 132
Adobe Creative Suite 2
Bridge JavaScript Reference 10
encoding........................................................................................................................................................................ 132
eof .................................................................................................................................................................................... 132
error ................................................................................................................................................................................. 132
exists................................................................................................................................................................................ 132
fsName............................................................................................................................................................................ 132
hidden............................................................................................................................................................................. 132
length.............................................................................................................................................................................. 132
lineFeed.......................................................................................................................................................................... 132
modified......................................................................................................................................................................... 132
name................................................................................................................................................................................ 132
parent.............................................................................................................................................................................. 132
path.................................................................................................................................................................................. 133
readonly ......................................................................................................................................................................... 133
relativeURI ..................................................................................................................................................................... 133
type.................................................................................................................................................................................. 133
File object functions........................................................................................................................................................... 133
close................................................................................................................................................................................. 133
copy ................................................................................................................................................................................. 133
createAlias..................................................................................................................................................................... 133
execute ........................................................................................................................................................................... 133
getRelativeURI ............................................................................................................................................................. 133
open ................................................................................................................................................................................ 134
openDlg ......................................................................................................................................................................... 135
read.................................................................................................................................................................................. 135
readch ............................................................................................................................................................................. 135
readln .............................................................................................................................................................................. 135
remove............................................................................................................................................................................ 135
rename............................................................................................................................................................................ 136
resolve............................................................................................................................................................................. 136
saveDlg........................................................................................................................................................................... 136
seek.................................................................................................................................................................................. 136
tell..................................................................................................................................................................................... 136
write................................................................................................................................................................................. 137
writeln............................................................................................................................................................................. 137
Folder Object ............................................................................................................................................................................. 138
Folder object constructors............................................................................................................................................... 138
Folder class properties ...................................................................................................................................................... 138
appData.......................................................................................................................................................................... 138
commonFiles................................................................................................................................................................ 138
current ............................................................................................................................................................................ 138
fs........................................................................................................................................................................................ 138
myDocuments ............................................................................................................................................................. 138
startup............................................................................................................................................................................. 138
system............................................................................................................................................................................. 139
temp ................................................................................................................................................................................ 139
trash................................................................................................................................................................................. 139
userData......................................................................................................................................................................... 139
Folder class functions ........................................................................................................................................................ 139
decode............................................................................................................................................................................ 139
encode............................................................................................................................................................................ 139
isEncodingAvailable ..........................................................................................................
........................................ 139
Adobe Creative Suite 2
Bridge JavaScript Reference 11
selectDialog .................................................................................................................................................................. 140
Folder object properties................................................................................................................................................... 140
absoluteURI................................................................................................................................................................... 140
alias .................................................................................................................................................................................. 140
created............................................................................................................................................................................ 140
error ................................................................................................................................................................................. 140
exists................................................................................................................................................................................ 140
fsName............................................................................................................................................................................ 140
modified......................................................................................................................................................................... 140
name................................................................................................................................................................................ 140
parent.............................................................................................................................................................................. 140
path.................................................................................................................................................................................. 140
relativeURI ..................................................................................................................................................................... 140
Folder object functions..................................................................................................................................................... 141
create .............................................................................................................................................................................. 141
execute ........................................................................................................................................................................... 141
getFiles ........................................................................................................................................................................... 141
getRelativeURI ............................................................................................................................................................. 141
remove............................................................................................................................................................................ 141
rename............................................................................................................................................................................ 141
resolve............................................................................................................................................................................. 141
selectDlg ........................................................................................................................................................................ 142
File and Folder Error Messages ............................................................................................................................................ 143
File and Folder Supported Encoding Names .................................................................................................................. 144
Additional encodings ........................................................................................................................................................ 144
8 ScriptUI Object Reference ....................................................................................................... 146
Overview ...................................................................................................................................................................................... 146
Window Class.............................................................................................................................................................................. 147
Window class properties .................................................................................................................................................. 147
coreVersion ................................................................................................................................................................... 147
version ............................................................................................................................................................................ 147
Window class functions .................................................................................................................................................... 147
alert.................................................................................................................................................................................. 147
confirm ........................................................................................................................................................................... 147
find................................................................................................................................................................................... 147
getResourceText ......................................................................................................................................................... 148
prompt............................................................................................................................................................................ 148
Window Object .......................................................................................................................................................................... 148
Window object constructor ............................................................................................................................................ 148
Window object properties ............................................................................................................................................... 149
defaultElement............................................................................................................................................................ 149
cancelElement ............................................................................................................................................................. 149
frameBounds................................................................................................................................................................ 149
frameLocation.............................................................................................................................................................. 149
frameSize ....................................................................................................................................................................... 149
Container properties.......................................................................................................................................................... 150
alignChildren................................................................................................................................................................ 150
children .......................................................................................................................................................................... 150
layout .............................................................................................................................................................................. 150
margins........................................................................................................................................................................... 150
Adobe Creative Suite 2
Bridge JavaScript Reference 12
orientation..................................................................................................................................................................... 151
spacing ........................................................................................................................................................................... 151
Window object functions................................................................................................................................................. 151
add ................................................................................................................................................................................... 151
center .............................................................................................................................................................................. 151
close................................................................................................................................................................................. 151
hide.................................................................................................................................................................................. 152
notify ............................................................................................................................................................................... 152
remove............................................................................................................................................................................ 152
show ................................................................................................................................................................................ 152
Window event-handling callbacks ............................................................................................................................... 152
onClose........................................................................................................................................................................... 152
onMove .......................................................................................................................................................................... 152
onMoving ...................................................................................................................................................................... 152
onResize ......................................................................................................................................................................... 152
onResizing..................................................................................................................................................................... 153
onShow .......................................................................................................................................................................... 153
Control Objects ......................................................................................................................................................................... 154
Control object constructors ............................................................................................................................................ 154
add ................................................................................................................................................................................... 154
Control types and creation parameters................................................................................................................ 154
button ............................................................................................................................................................................. 154
checkbox........................................................................................................................................................................ 154
dropdownlist................................................................................................................................................................ 155
edittext ........................................................................................................................................................................... 155
group............................................................................................................................................................................... 156
iconbutton .................................................................................................................................................................... 156
image .............................................................................................................................................................................. 156
item.................................................................................................................................................................................. 156
listbox.............................................................................................................................................................................. 157
panel................................................................................................................................................................................ 157
progressbar................................................................................................................................................................... 157
radiobutton................................................................................................................................................................... 158
scrollbar.......................................................................................................................................................................... 158
slider ................................................................................................................................................................................ 159
statictext ........................................................................................................................................................................ 159
Control object properties................................................................................................................................................. 160
active ............................................................................................................................................................................... 160
alignment ...................................................................................................................................................................... 160
bounds............................................................................................................................................................................ 160
enabled .......................................................................................................................................................................... 160
helpTip............................................................................................................................................................................ 160
icon .................................................................................................................................................................................. 161
index................................................................................................................................................................................ 161
items................................................................................................................................................................................ 161
itemSize.......................................................................................................................................................................... 161
jumpdelta ...................................................................................................................................................................... 161
justify............................................................................................................................................................................... 161
location........................................................................................................................................................................... 161
maxvalue ....................................................................................................................................................................... 161
minvalue .....................................................................................................................
................................................... 162
Adobe Creative Suite 2
Bridge JavaScript Reference 13
parent.............................................................................................................................................................................. 162
preferredSize ................................................................................................................................................................ 162
properties ...................................................................................................................................................................... 162
selected .......................................................................................................................................................................... 162
selection......................................................................................................................................................................... 162
size ................................................................................................................................................................................... 162
stepdelta ........................................................................................................................................................................ 162
text ................................................................................................................................................................................... 163
textselection ................................................................................................................................................................. 163
type.................................................................................................................................................................................. 163
value ................................................................................................................................................................................ 163
value ................................................................................................................................................................................ 163
visible .............................................................................................................................................................................. 163
Control object functions................................................................................................................................................... 164
add ................................................................................................................................................................................... 164
find................................................................................................................................................................................... 164
hide.................................................................................................................................................................................. 164
notify ............................................................................................................................................................................... 164
remove............................................................................................................................................................................ 164
removeAll ...................................................................................................................................................................... 164
show ................................................................................................................................................................................ 164
toString........................................................................................................................................................................... 165
valueOf ........................................................................................................................................................................... 165
Control event-handling callbacks................................................................................................................................. 165
onClick ............................................................................................................................................................................ 165
onChange ...................................................................................................................................................................... 165
onChanging.................................................................................................................................................................. 165
Size and Location Objects ...................................................................................................................................................... 166
Bounds............................................................................................................................................................................ 166
Dimension ..................................................................................................................................................................... 166
Margins........................................................................................................................................................................... 167
Point ................................................................................................................................................................................ 167
LayoutManager Object ........................................................................................................................................................... 168
AutoLayoutManager object constructor.................................................................................................................... 168
AutoLayoutManager object properties ...................................................................................................................... 168
AutoLayoutManager object functions ........................................................................................................................ 168
layout .............................................................................................................................................................................. 168
MenuElement Object............................................................................................................................................................... 169
MenuElement class functions......................................................................................................................................... 169
create .............................................................................................................................................................................. 169
find................................................................................................................................................................................... 170
remove............................................................................................................................................................................ 170
Creating new menu elements.................................................................................................................................. 170
MenuElement object properties ................................................................................................................................... 171
altDown.......................................................................................................................................................................... 171
checked .......................................................................................................................................................................... 171
cmdDown ...................................................................................................................................................................... 171
ctrlDown ........................................................................................................................................................................ 171
enabled .......................................................................................................................................................................... 171
id ....................................................................................................................................................................................... 172
onDisplay....................................................................................................................
................................................... 172
Adobe Creative Suite 2
Bridge JavaScript Reference 14
optionDown ................................................................................................................................................................. 172
onSelect.......................................................................................................................................................................... 172
shiftDown ...................................................................................................................................................................... 172
text ................................................................................................................................................................................... 172
type.................................................................................................................................................................................. 172
Bridge menu and command identifiers...................................................................................................................... 172
Bridge menu identifiers.............................................................................................................................................. 172
Bridge submenu and command identifiers ....................................................................................................... 173
9 Interapplication Communication with Scripts ...................................................................... 180
Cross-DOM Functions .............................................................................................................................................................. 181
Cross-DOM API Reference...................................................................................................................................................... 181
executeScript ............................................................................................................................................................... 181
open ................................................................................................................................................................................ 181
openAsNew .................................................................................................................................................................. 182
print ................................................................................................................................................................................. 182
quit................................................................................................................................................................................... 182
reveal............................................................................................................................................................................... 182
Application-Specific Exported Functions ......................................................................................................................... 182
Communicating Through Interapplication Messages ................................................................................................ 184
Sending messages.............................................................................................................................................................. 184
Receiving messages ........................................................................................................................................................... 186
Handling unsolicited messages ..................................................................................................................................... 186
Handling responses from the message target......................................................................................................... 187
Passing values between applications.......................................................................................................................... 190
Passing simple types ................................................................................................................................................... 190
Passing complex types ............................................................................................................................................... 191
Interapplication Message API Reference .......................................................................................................................... 193
BridgeTalk Class................................................................................................................................................................... 193
BridgeTalk class properties ....................................................................................................................................... 193
appLocale ...................................................................................................................................................................... 193
appName ....................................................................................................................................................................... 193
appVersion .................................................................................................................................................................... 193
onReceived ................................................................................................................................................................... 194
BridgeTalk class functions ......................................................................................................................................... 194
bringToFront ................................................................................................................................................................ 194
getSpecifier................................................................................................................................................................... 194
getTargets ..................................................................................................................................................................... 195
isRunning....................................................................................................................................................................... 196
launch ............................................................................................................................................................................. 196
pump............................................................................................................................................................................... 196
BridgeTalk Message Object ............................................................................................................................................. 197
BridgeTalk message object constructor ............................................................................................................... 197
BridgeTalk message object properties ................................................................................................................. 197
body................................................................................................................................................................................. 197
headers........................................................................................................................................................................... 197
sender ............................................................................................................................................................................. 197
target............................................................................................................................................................................... 198
timeout........................................................................................................................................................................... 198
type.................................................................................................................................................................................. 198
BridgeTalk message object callbacks .................................................................................................................... 198
Adobe Creative Suite 2
Bridge JavaScript Reference 15
onError............................................................................................................................................................................ 198
onReceived ................................................................................................................................................................... 199
onResult ......................................................................................................................................................................... 199
BridgeTalk message object functions ................................................................................................................... 200
send ................................................................................................................................................................................. 200
sendResult..................................................................................................................................................................... 200
Messaging Error Codes ..................................................................................................................................................... 201
Sample Workflow Automation Scripts .............................................................................................................................. 202
10 ExtendScript Tools and Features............................................................................................203
The ExtendScript Toolkit......................................................................................................................................................... 203
Configuring the Toolkit window ................................................................................................................................... 204
Selecting a debugging target ........................................................................................................................................ 205
Selecting scripts................................................................................................................................................................... 206
Tracking data ........................................................................................................................................................................ 206
The JavaScript console ..................................................................................................................................................... 207
The call stack ........................................................................................................................................................................ 208
The Script Editor .................................................................................................................................................................. 209
Mouse navigation and selection ............................................................................................................................. 209
Keyboard navigation and selection ....................................................................................................................... 209
Syntax checking ............................................................................................................................................................ 210
Debugging in the Toolkit ................................................................................................................................................. 210
Evaluation in help tips................................................................................................................................................. 210
Controlling code execution ...................................................................................................................................... 210
Visual indication of execution states ..................................................................................................................... 211
Setting breakpoints .................................................................................................................................................... 212
Profiling .................................................................................................................................................................................. 213
Dollar ($) Object ........................................................................................................................................................................ 215
Dollar ($) object properties ............................................................................................................................................. 215
build................................................................................................................................................................................. 215
buildDate ....................................................................................................................................................................... 215
error ................................................................................................................................................................................. 215
flags ................................................................................................................................................................................. 215
global .............................................................................................................................................................................. 215
level.................................................................................................................................................................................. 215
locale ............................................................................................................................................................................... 215
localize............................................................................................................................................................................ 216
memCache .................................................................................................................................................................... 216
objects ............................................................................................................................................................................ 216
os ...................................................................................................................................................................................... 216
screens............................................................................................................................................................................ 216
strict................................................................................................................................................................................. 216
version ............................................................................................................................................................................ 216
Dollar ($) object functions ............................................................................................................................................... 216
about............................................................................................................................................................................... 216
bp ..................................................................................................................................................................................... 216
clearbp............................................................................................................................................................................ 216
gc ...................................................................................................................................................................................... 216
getenv............................................................................................................................................................................. 216
list ..................................................................................................................................................................................... 216
setbp................................................................................................................................................................................ 217
Adobe Creative Suite 2
Bridge JavaScript Reference 16
sleep ................................................................................................................................................................................ 217
summary ........................................................................................................................................................................ 217
write................................................................................................................................................................................. 217
writeln............................................................................................................................................................................. 217
Object statistics ............................................................................................................................................................. 217
ExtendScript Reflection Interface ........................................................................................................................................ 219
Reflection Object................................................................................................................................................................. 219
Reflection object properties ..................................................................................................................................... 219
description .................................................................................................................................................................... 219
help.................................................................................................................................................................................. 219
methods......................................................................................................................................................................... 219
name................................................................................................................................................................................ 219
properties ...................................................................................................................................................................... 219
Reflection object functions ....................................................................................................................................... 219
find................................................................................................................................................................................... 219
ReflectionInfo Object......................................................................................................................................................... 220
ReflectionInfo object properties ............................................................................................................................. 220
arguments ..................................................................................................................................................................... 220
dataType ........................................................................................................................................................................ 220
defaultValue ................................................................................................................................................................. 220
description .................................................................................................................................................................... 220
help.................................................................................................................................................................................. 221
isCollection.................................................................................................................................................................... 221
max .................................................................................................................................................................................. 221
min ................................................................................................................................................................................... 221
name................................................................................................................................................................................ 221
type.................................................................................................................................................................................. 221
Localizing ExtendScript Strings............................................................................................................................................ 222
Variable values in localized strings ............................................................................................................................... 222
Enabling automatic localization .................................................................................................................................... 222
Locale names........................................................................................................................................................................ 223
Testing localization ............................................................................................................................................................ 224
Global localize function .................................................................................................................................................... 225
localize............................................................................................................................................................................ 225
User Notification Helper Functions..................................................................................................................................... 226
Global alert function .......................................................................................................................................................... 226
alert.................................................................................................................................................................................. 226
Global confirm function.................................................................................................................................................... 227
confirm ........................................................................................................................................................................... 227
Global prompt function.................................................................................................................................................... 227
prompt............................................................................................................................................................................ 227
Specifying Measurement Values ........................................................................................................................................ 229
UnitValue Object ................................................................................................................................................................. 229
UnitValue object constructor ................................................................................................................................... 229
UnitValue object properties...................................................................................................................................... 230
baseUnit ......................................................................................................................................................................... 230
type.................................................................................................................................................................................. 230
value ................................................................................................................................................................................ 230
UnitValue object functions........................................................................................................................................ 230
as....................................................................................................................................................................................... 230
convert......................................................................................................................
...................................................... 230
Adobe Creative Suite 2
Bridge JavaScript Reference 17
Converting pixel and percentage values ................................................................................................................... 230
Computing with unit values ........................................................................................................................................... 231
Modular Programming Support .......................................................................................................................................... 233
Preprocessor directives..................................................................................................................................................... 233
#engine name .............................................................................................................................................................. 233
#include file ................................................................................................................................................................... 233
#includepath path...................................................................................................................................................... 234
#script name ................................................................................................................................................................. 234
#strict on ........................................................................................................................................................................ 234
#target name ................................................................................................................................................................ 234
Importing and exporting between scripts................................................................................................................. 234
Operator Overloading ............................................................................................................................................................ 236
Application and Namespace Specifiers............................................................................................................................. 237
Application specifiers ........................................................................................................................................................ 237
Namespace specifiers ........................................................................................................................................................ 238
Script Locations and Checking Application Installation ............................................................................................. 238
Index .........................................................................................................................................240
Adobe Creative Suite 2
Bridge JavaScript Reference 18
Wel com e
Welcome to the Bridge JavaScript Reference. This book describes how to use JavaScript to manipulate and
extend Adobe® Bridge for Adobe Creative Suite 2.
About This Book
The Bridge JavaScript Reference describes how to use the scripting API to extend and manipulate Adobe
Bridge, but it is not a user’s guide for the Bridge application and its user interface.
This book provides complete reference information for the JavaScript objects, properties, and functions
defined by Adobe Bridge, and for various utilities and tools that are part of ExtendScript, the Adobe
extended implementation of JavaScript.
This book also describes how to use the interapplication communication framework that is defined by
Adobe Bridge and included in each Adobe Creative Suite 2 application. You can use this framework to
write scripts that call on functionality from different applications, or to send scripts and data from one
application to another. A set of Sample Workflow Automation Scripts
Suite 2, which demonstrate how scripts can be used to create a workflow that takes advantage of
functionality in different applications.
is provided with Adobe Creative
Who should read this book
This book is for developers who want to extend the capabilities of Adobe Bridge using JavaScript, call
Bridge functionality from scripts, and use scripts to communicate between Adobe Creative Suite 2
applications. It assumes a general familiarity with the following:
● JavaScript
● C and C++ programming
● Adobe Bridge
● Any other Adobe Creative Suite 2 applications you are using, such as Illustrator® CS2, Photoshop® CS2,
or InDesign® CS2. The scripting API details for each application are included with the scripting
documentation for that product.
What is in this book
This book provides conceptual information about the scripting Adobe Bridge and detailed reference
information about the JavaScript objects that Adobe Bridge provides. It also provides both usage and
reference information for the tools, utilities, and objects that are part of ExtendScript, the Adobe extended
implementation of JavaScript.
This book contains the following chapters:
● Chapter 1, “Scripting Bridge,” introduces some important concepts in Adobe Bridge scripting and
describes the Bridge JavaScript document object model (DOM).
● Chapter 2, “Event Handling and Script-Defined Browse Schemes,” describes how Adobe Bridge
generates user-interaction events, and how you can respond to these events by defining handlers in
19
Adobe Creative Suite 2
Bridge JavaScript Reference Welcome 20
your scripts. In addition, it describes how to define browse schemes that allow you to extend or modify
what is shown in the Bridge Favorites pane.
● Chapter 3, “Creating a User Interface,” describes the various options available to scripts for interaction
with Bridge users, such as dialog boxes and navigation bars.
● Chapter 4, “Using File and Folder Objects,” describes how to use the ExtendScript objects that provide
platform-independent access to the underlying file system.
● Chapter 5, “Using ScriptUI,” describes how to use the ExtendScript user interface module, a set of
objects which provide windows and user-interface controls for the scripting environment.
● Chapter 6, “Bridge DOM Object Reference,” provides a complete API reference for the objects,
properties, and functions defined in the Bridge document object model.
● Chapter 7, “File and Folder Object Reference,” provides a complete API reference for the ExtendScript
file-system access objects, properties, and functions.
● Chapter 8, “ScriptUI Object Reference,” provides a complete API reference for the ExtendScript
user-interface objects, properties, and functions.
● Chapter 9, “Interapplication Communication with Scripts,” describes how to use the interapplication
communication framework, and provides a complete API reference for the Cross-DOM and for the
messaging framework.
● Chapter 10, “ExtendScript Tools and Features,” describes the ExtendScript Toolkit debugging
environment, and provides a complete API reference for the ExtendScript utilities and features that are
available to all Adobe Creative Suite 2 applications.
Document conventions
Typographical conventions
Monospaced font
Italics Variables or placeholders in code. For example, in
Blue underlined text
Sans-serif bold font The names of Bridge UI elements (menus, menu items, and buttons).
Note: Notes highlight important points that deserve extra attention.
A hyperlink you can click to go to a related section in this book or to a URL in
Literal values and code, such as JavaScript code, HTML code, filenames, and
pathnames.
name="myName", the text
myName represents a value you are expected to supply, such as name="Fred".
Also indicates the first occurrence of a new term.
your web browser.
> symbol is used as shorthand notation for navigating to menu items. For
The
example,
Edit > Cut refers to the Cut item in the Edit menu.
JavaScript conventions
This reference does not list properties and methods provided by the JavaScript language itself. For
example, it is common for JavaScript objects to provide a
the SDK supplies implement this method. However, this book does not describe such methods unless they
differ from the standard JavaScript implementation.
toString method, and many of the objects
Adobe Creative Suite 2
Bridge JavaScript Reference Welcome 21
Similarly, because most objects provided by the SDK have a name property, the reference does not list
name properties explicitly.
When a JavaScript function returns a value, it is listed.When there is no return value listed, the function
does not return a value.
Where to go for more information
This book does not describe the JavaScript language. For documentation of the JavaScript language or
descriptions of how to use it, see any of numerous works on this subject, including the following:
JavaScript: The Definitive Guide, 4th Edition; Flanagan, D.; O’Reilly 2001; ISBN 0-596-00048-0
JavaScript Programmer’s Reference; Wootton, C.; Wrox 2001; ISBN 1-861004-59-1
JavaScript Bible. 5th Edition; Goodman, D. and Morrison, M.; John Wiley and Sons1998; ISBN
0-7645-57432
1
Scripting Bridge
This chapter introduces some important concepts in Adobe Bridge scripting and describes the Bridge
JavaScript document object model (DOM).
Scripting Overview
Adobe Bridge provides a configurable, extensible browser platform that allows users to search for and
select files by navigating among files and folders in the local file system, those on remote file systems, and
also web pages accessible over the Internet.
Bridge is integrated with Adobe Creative Suite 2, and various applications bring up the Bridge browser
window in response to specific user actions that require file selection. You can also bring up a Bridge
browser window independently, by invoking it interactively or through a script.
The Bridge browser is highly configurable and extensible, using ExtendScript, the Adobe extended
implementation of JavaScript. ExtendScript files are distinguished by the
offers all standard JavaScript features, plus additional features and utilities, such as:
● Platform-independent file and folder representation
● Tools for building a user interface to a script
.jsx extension. ExtendScript
● An interactive development and debugging environment (the ExtendScript Toolkit)
You can use ExtendScript to manipulate browser windows and their contents programmatically, and to
change and extend their functionality. This manual describes what you can do, and provides a complete
reference for the ExtendScript objects and functions that you can use to program Bridge.
Executing Scripts
Bridge executes scripts in any of these ways:
● On startup, Bridge executes all JSX files that it finds in the startup folders.
● In Windows
%APPDATA%\Adobe\StartupScripts
%APPDATA%\Adobe\StartupScripts\bridge\version
● In Mac OS
~/Library/Application Support/Adobe/StartupScripts/
~/Library/Application Support/Adobe/StartupScripts/bridge/version/
Note: If your script is in the main startup folder, it is also executed by all other Adobe Creative Suite 2
applications at startup; see Script Locations and Checking Application Installation
The version portion of the Bridge-specific folder path is an exact version number. That is, scripts in the
bridge/1.5 are executed only by Bridge version 1.5, and so on.
folder
®
, the startup folders are:
®
, the startup folders are:
.
● You can pass a script to the Bridge executable to be executed on startup, by dragging the JSX file icon
onto the Bridge executable file icon or shortcut. This script is executed after all startup scripts.
22
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 23
● When the Bridge browser window displays a JSX file, you can double-click that file thumbnail to run the
script in its target application. It runs in Bridge if the script specifies Bridge as its target application by
including the directive:
#target "bridge"
If the script specifies another Adobe Creative Suite 2 application as its target, ExtendScript starts that
application if necessary. If the script does not specify a target application, it opens in the ExtendScript
Toolkit. For details, see Preprocessor directives
● You can load and run a script in the ExtendScript Toolkit, specifying Bridge as the target application.
For details, see The ExtendScript Toolkit
● You can add a menu command that runs a script to a menu or submenu in the Bridge browser, using
the MenuElement Object
.
and The ExtendScript Toolkit.
.
Communicating with Other Applications
Adobe Bridge provides an interapplication communication framework, a way for scripts to communicate
with other Adobe applications, from Bridge or among themselves.
● A script can call certain basic functions exported by all Adobe Creative Suite 2 applications. For
example, a Bridge script could ask the user to select an image file, then open that file in Photoshop
Illustrator
® by calling the photoshop.open or illustrator.open function. These basic exported
functions are called the Cross DOM.
® or
● Individual applications export additional functions to make more complex functionality available to
scripts. For example, a Bridge script can request a photo-merge operation in Photoshop by calling
photoshop.photomerge with a set of selected image files. The set of functions available for each
application varies widely.
● A messaging protocol provides a general and extensible framework for passing any kind of data
between messaging enabled applications. All Creative Suite 2 applications are messaging enabled. You
can send messages that contain JavaScript scripts. The target application can evaluate a script that it
receives, and send results back in a response message.
For additional information, see Chapter 9, “
Interapplication Communication with Scripts."
The Bridge Document Object Model
A document object model (DOM) is an application programming interface (API), which allows you to
programmatically access various components of a document (as defined for that application) through a
scripting language such as JavaScript.
Each application in the Creative Suite 2 has its own DOM, which consists of a hierarchical representation of
the application, and of the documents used in the application. The DOM allows you to programmatically
access and manipulate the document and its components. Since the use of a document varies for each
application, the DOM terminology varies for each application. For example, each application's DOM
includes a
class has different properties and methods for each application.
Document class, but the object referred to is different for each application, and the Document
Applications typically define a
images, or PDF documents. However, Bridge uses a different approach. In the Bridge DOM, the
class refers to a Bridge browser window, and the properties and methods of
Document class to deal with files of a particular type, such as HTML pages,
Document
Document refer to various
components of the Bridge user interface (UI). The browser window displays icons that reference the files
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 24
that other applications consider documents—HTML pages, images, PDFs, and so on. In the Bridge DOM,
these icons are represented by the
Thumbnail class.
Having a good understanding of the Bridge DOM, and how each aspect of the API relates to the Bridge
browser, will greatly enhance your ability to write scripts. In the Bridge DOM shown below, each node in
the hierarchy represents a class in the Bridge DOM API.
AppApp
Document
Event
Dialog
MenuElement
Preferences
PreferencesDialog
Favorites
Thumbnail
NavBar
Thumbnail
File, Folder
MetaData
BrowseSchemeEvent
ScriptUI Element
The application and documents
The Bridge App Object is the root of the hierarchy, and represents the Bridge application. A single global
instance of the
global values. Even though the user can create multiple Bridge browser windows by selecting the File >
New Window command, making it appear that separate Bridge applications are running in parallel, only a
single instance of the application is running, which is reflected by a single instance of the
The Document Object
document object is created. When multiple Bridge browser windows are open, the user can select
a new
which window to use by clicking the window to make it active. In a script, you can access the active, or
most recently used, browser window through the
windows is available through the
App class, named app, is created when the application is started, and provides access to
represents a Bridge browser window. Each time a user selects File > New Window,
app.documents array.
app object.
app.document property. The set of all open browser
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 25
Thumbnails in documents
The Thumbnail Object type represents a node in the browser navigation hierarchy. It typically represents a
a file or folder, but can also be associated with a web page. A document contains various collections of
Thumbnail objects.
Thumbnail objects can contain other Thumbnail objects, as for example, when a folder contains files. In
this case, the
represent files and folders contained in the folder.
The Folders pane shows the full navigation hierarchy of folders and subfolders for the local file system. A
script cannot add nodes to the Folders pane (except by creating new folders on disk), but your script can
access the selected thumbnail through the
navigation hierarchy by accessing the
The Favorites pane shows a selection of high-level nodes, some predefined and some chosen by the user.
These can represent web pages and remote folders, as well as local folders. The Favorites Object
represents the navigation nodes in the Favorites pane. A document contains a single
which is an array of
children property of the Thumbnail contains a hierarchy of Thumbnail objects that
app.document.thumbnail property. It can walk the
parent and children properties of each Thumbnail object.
Favorites object,
Thumbnail objects. Access the Favorites object through app.favorites.
A script can add thumbnails to the lower part of the Favorites pane by using the
Favorites object’s
insert method, and one level of sub-nodes using the addChild method. A subnode can be any
thumbnail; it does not have to be part of the root node’s
children hierarchy.
Thumbnails as node references
The Thumbnail Object represents a navigation node. Thumbnails can represent entities such as files and
folders, accessed through a local or remote file system, or web pages accessed over the internet and
displayed in an embedded web browser. Each
types of node identifier, which determines what happens when the user selects the icon:
● File or folder objects; see Chapter 4, “Using File and Folder Objects," and Chapter 7, “File and Folder
Object Reference." Clicking a folder thumbnail in the Folders or Favorites pane displays the contents of
the folder in the Content pane.
● URLs. Clicking the thumbnail in the Folders or Favorites pane displays the web page associated with
the URL in the Content pane. This can be a local or remote HTML page. See Displaying HTML in the
Content Pane.
● Version Cue® nodes. Clicking a thumbnail in the Folders pane displays the contents of the Version Cue
workspace in the Content pane.
● Script-defined navigation nodes, which are associated with script-defined browse schemes. The display
in the Content pane is determined by the browse scheme’s associated handler. See Script-Defined
Browse Schemes.
Thumbnail object is associated with one of the following
Using and accessing thumbnails
Thumbnails are used in a number of ways within a browser window, and the objects are referenced
according to their use. For example:
● Access thumbnails that appear in the Favorites pane through app.favorites
● Access a thumbnail that is selected in the Folders pane through app.document.thumbnail
● Access thumbnails that appear in the Content pane through
app.document.thumbnail.children
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 26
● Access thumbnails that have been selected in the Content pane through app.document.selected
● Access thumbnails that are associated with a context menu through app.document.context
A Thumbnail object is associated with a Metadata Object, which allows you to access the external data
associated with the associated file, such a copyright owner, author, or camera settings. The
metadata
object also allows access to an image thumbnail’s label string, which you can define and set through the
Bridge browser.
User interface objects
Your script can display information to or collect information from the user by configuring the supplied
navigation bars, or by creating and displaying dialogs.
ExtendScript provides a set of user-interface objects in the ScriptUI module, which defines windows and
user-interface controls. You can use these objects to define a user interface for your application, in the
form of popup dialogs, persistent dialogs (called palettes), or as part of navigation bars. The usage of the
ScriptUI objects is discussed in Chapter 5, “
Chapter 8, “
ScriptUI Object Reference."
You can also define a user interface using standard HTML. When integrating your user interface with the
Bridge browser, you can use either ScriptUI or HTML controls for any window or pane, but cannot mix the
two. For a complete discussion, see Chapter 3, “
Using ScriptUI," and complete syntax details are provided in
Creating a User Interface."
In addition to displaying a user interface for your script, you can script user interactions by extending the
Bridge menus.
Navigation bars
The Bridge navigation bar immediately below the menubar cannot be scripted, but there are two
configurable navigation bars, above and below the Content pane. They are represented by NavBar
Objects, which you can access through the Document object’s navbars property.
By default, the navigation bars are hidden and empty.
● You can show and hide a navigation bar by setting the object’s visible property.
● You can configure a navigation bar to display either ScriptUI user-interface controls, or straight HTML
controls. It cannot mix the two.
● To display ScriptUI controls, set the type property to "scriptui", then use the NavBar.add
method to add controls.
● To display HTML controls, set the type property to "html", and the file property to the HTML
file that defines the page you want to display.
You can program the controls to display information to or collect information from the user. For additional
details, see Navigation Bars
.
Dialogs
Your script can define dialogs to display information to or get information from the user. There are two
ways to define these:
● ScriptUI Dialogs: Use the ScriptUI Window Object to define a dialog that displays ScriptUI controls.
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 27
● Bridge Dialogs: The Dialog Object represents a window that displays an HTML page, rather than
ScriptUI controls.
You can invoke ScriptUI dialogs from a script as modal or nonmodal dialogs.
● A modal dialog retains the input focus, and does not allow the user to interact with any other
application windows until the dialog is dismissed. The function that invokes it does not return until the
dialog is dismissed.
● A nonmodal dialog (known in ScriptUI as a palette), does not keep the input focus. The user can interact
with other application windows while the dialog is up. The function that invokes it returns
immediately, leaving the dialog on screen until the user or script closes it.
Menus
Events
For details of programming dialogs, see Chapter 5, “
Using ScriptUI," a n d Displaying HTML in Bridge
Dialogs.
The MenuElement Object allows you to add new menus and commands. A script cannot remove or alter
the behavior of predefined menu items, but you can add, remove, and modify script-defined menus and
commands.
Most menubar menus and context menus can be extended by creating new
MenuElement objects that
reference existing menus and menu items. The identifiers of all menus and menu items that are accessible
to scripts are listed with the description of the
MenuElement object.
When interacting with Bridge, a user takes actions such as copying a file, or creating a new Bridge browser
window. For most of these actions, Bridge triggers a user-interaction event, represented by an Event Object
of a particular event type, with a particular target object, such as an
App, Document, or Thumbnail object.
Some function calls can also trigger events.
Bridge defines default behavior for user-interaction events. You can extend or override the default
behavior by defining and registering an event-handler function. This function receives the
Event object as
an argument, and returns a value that tells Bridge whether to continue with the default behavior or to
ignore it.
For more information on event handling, see Event Handling in Bridge
Application preferences
The Preferences Object allows a script to access Bridge application preferences. These are the values that
can be viewed interactively in the Preferences dialog, in response to the Edit > Preferences command.
The settings are stored and persist across sessions. Your script can use the
set existing preferences, or to add new preference fields. In general, when you modify persistent
preference values, the new settings are not reflected in the browser window until the Bridge application is
restarted.
When the user brings up a Preferences dialog, Bridge invokes a ScriptUI dialog window, and generates a
create event with the PreferencesDialog Object as its target. You can define and register an event
handler for this event that uses the object’s
controls that show and allow the user to modify script-defined preference values.
.
Preferences object to view or
add method to add a ScriptUI panel containing ScriptUI
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 28
The Bridge DOM and the Bridge Browser Window
The following figure identifies parts of the Bridge browser window in a default configuration.
Menu bar
Upper
navigation bar
Favorites and
Folder panes
User section of
Favori tes pane
Preview pane
Metadata and
Keywords panes
Flyout menus
Status line
Content pane
ThumbnailsThumbnails
Viewing mode
The following table describes how the Bridge API maps to the various parts and features of the Bridge
browser window, and how a script can access each part or feature through the Bridge DOM.
Bridge window area Purpose Bridge DOM control
Browser window Displays files, folders, and web
pages.
Favorites pane Provides a place for users to
drag and drop favorite items
(in the bottom half of the
pane).
Displays only top-level
containers and one level of
subnodes.
Represented by the
browser window is in
Document object. Current
app.document.
Access the visible thumbnails through the
app.favorites property, and traverse the
hierarchy through the
Thumbnail.children
properties.
Favorites object allows you to add
The
thumbnails to this pane.
User interaction with a thumbnail in this
pane generates an
target object and a location of
event with a Thumbnail
favorites.
You can define your own browse scheme for a
thumbnail in this pane, which allows you to
extend or redefine the thumbnail’s behavior.
See Script-Defined Browse Schemes
.
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 29
Folders pane Displays the navigation
hierarchy and controls
navigation.
Displays only containers (such
as folders and subfolders).
Access the currently selected thumbnail in
the Folder pane through the
Document.thumbnail property. Traverse the
hierarchy through the
Thumbnail.children properties.
Thumbnail.parent and
User interaction with a thumbnail in this
pane generates an
target object and a location of
event with a Thumbnail
document.
Preview pane Displays image previews. User interaction with a thumbnail in this
Metadata pane Displays metadata
information.
pane generates an
target object and a location of
Metadata is displayed and written for a
specific thumbnail. Access metadata from
the
Thumbnail.metadata property.
event with a Thumbnail
preview.
Keywords pane Displays keyword information. Not accessible to scripts.
Content pane Displays navigation results
when you select a node in the
Folders or Favorites pane, or
when you click on a navigable
node (such as a folder) in the
Content pane itself.
Controlled by the browse scheme associated
with the thumbnail selected in the Folders or
Favorites pane. The browse scheme uses the
Thumbnail properties displayMode and
displayPath to determine what appears the
Content pane, and how it appears.
Displays both containers (such
as subfolders) and leaf nodes
(such as files and images).
Can display HTML pages for
web-type thumbnails.
Thumbnails The labelled icons that appear
in the Folders/Favorites panes
as navigation nodes, and in
the Content pane to represent
files and folders.
● When the selected thumbnail has
displayMode="filesystem", its children
appear as icons in the Content pane.
When a folder is selected in the Folders
pane, access the current contents of the
Content pane through
app.document.thumbnail.children[].
● When the selected thumbnail has
displayMode="web", the associated HTML
page (local or remote) appears in the
Content pane.
User interaction with a thumbnail in this
pane generates an
target object and a location of
event with a Thumbnail
document. The
selected thumbnails are available through
Document.selections.
The
Thumbnail object represents a node in
the browser navigation hierarchy.
Thumbnails can represent
File or Folder
objects, Version Cue nodes, URLs, or
script-defined nodes associated with
script-defined browse schemes.
Adobe Creative Suite 2
Bridge JavaScript Reference Scripting Bridge 30
Menubar The menubar at the top of the
Bridge browser window.
Context menus The right-click menus
associated with thumbnails,
and flyout menus for some tab
panels.
Browser window upper
navigation bar
The navigation bar
immediately under the
menubar. Not configurable.
Status line The bottom bar on the Bridge
browser window.
Content Pane Viewing
Control
The bar next to the status line,
where the viewing mode of
the Content pane is controlled.
Top and bottom
navigation bar s
Two configurable navigation
bars that can appear above
and below the Content pane.
While this is not an object under direct
Document control, you can add menus and
commands using the
MenuElement object, by
referring to existing menus and commands.
You can add submenus and commands to
these menus using the
MenuElement object,
by referring to existing commands.
Not accessible to scripts.
Controlled by
The view mode is controlled by
app.document.thumbnailViewMode
Represented by predefined
accessed through the
Document.status.
.
NavBar objects,
Document.navbars
property. By default, the navigation bars are
invisible. You can make a bar visible, and add
ScriptUI or HTML UI controls to it.
Loading...