Class

Window

 

The instance represents a top-level window or dialog box, which contains user-interface elements.

The globally available Window object provides access to predefined and script-defined windows.

QuickLinks

Window, add, addEventListener, alert, center, close, confirm, dispatchEvent, find, hide, notify, onClose, onDraw, onMove, onMoving, onResize, onResizing, onShortcutKey, onShow, prompt, remove, removeEventListener, show

Properties

PropertyTypeAccessDescription
activeboolr/w

Set to true to make this window active.

- A modal dialog that is visible is by definition the active dialog.

- An active palette is the front-most window.

- An active control is the one with focus—that is, the one that accepts keystrokes, or in the case of a Button, be selected when the user types Return or Enter.

alignChildrenStringr/w

Tells the layout manager how unlike-sized children of this container should be aligned within a column or row.

Order of creation determines which children are at the top of a column or the left of a row; the earlier a child is created, the closer it is to the top or left of its column or row. If defined, alignment for a child element overrides the alignChildren setting for the parent container. See alignment property for values.

alignmentStringr/w

The alignment style for child elements of a container. If defined, this value overrides the alignChildren setting for the parent container.

This can be a single string, which indicates the alignment for the orientation specified in the parent container, or an array of two strings, indicating both the horizontal and vertical alignment (in that order). Allowed values depend on the orientation value of the parent container. They are not case sensitive.

- For orientation=row:top, bottom, fill

- For orientation=column: left, right, fill

- For orientation=stack:top, bottom, left, right, fill

boundsBoundsr/wThe bounds of the window's drawable area, excluding the frame, in screen coordinates.
cancelElementObjectr/w

For windows of type dialog, the UI element to notify when the user presses a cancellation key combination.

The cancellation key is the Esc key. By default, looks for a button whose name or text is "cancel" (case disregarded).

charactersNumberr/wA number of characters for which to reserve space when calculating the preferred size of the window.
childrenArray of Objectreadonly

The collection of UI elements that have been added to this container.

An array indexed by number or by a string containing an element's name. The length property of this array is the number of child elements for container elements, and is zero for controls.

defaultElementObjectr/w

For windows of type dialog, the UI element to notify when the user presses a Enter key.

By default, looks for a button whose name or text is "ok" (case disregarded).

enabledboolr/w

True if this element is enabled.

An enabled element can accept input, according to its type. When false, control elements do not accept input, and all types of elements have a dimmed appearance.

frameBoundsBoundsreadonly

The bounds of the window frame in screen coordinates.

The frame consists of the title bar and borders that enclose the content region of a window, depending on the windowing system.

frameLocationPointr/w

The top left corner of the window frame in screen coordinates.

The same as [frameBounds.x, frameBounds.y]. Set this value to move the window frame to the specified location on the screen. The frameBounds value changes accordingly.

frameSizeDimensionreadonlyThe size and location of the window's frame in screen coordinates.
frameworkNameStringreadonly>Deprecated. Use ScriptUI.frameworkName instead.
graphicsScriptUIGraphicsreadonlyThe graphics object that can be used to customize the window’s appearance, in response to the onDraw event.
helpTipStringr/wThe help text that is displayed when the mouse hovers over the element.
indentNumberr/wThe number of pixels to indent the element.
justifyStringr/w

The default text justification style for child text elements. (default: left)

One of left, center, or right. Justification only works if this value is set on creation of the element.

layoutLayoutManagerr/w

The layout manager for this container.

The first time a container object is made visible, ScriptUI invokes this layout manager by calling its layout() function. Default is an instance of the LayoutManager class that is automatically created when the container element is created.

locationPointr/w

The upper left corner of the window's drawable area.

The same as [bounds.x, bounds.y].

marginsNumberr/w

The number of pixels between the edges of a container and the outermost child elements.

You can specify different margins for each edge of the container. The default value is based on the type of container, and is chosen to match the standard Adobe UI guidelines.

maximizedboolr/wTrue if the window is expanded.
maximumSizeDimensionr/wThe largest rectangle to which the window can be resized.
minimizedboolr/wTrue if the window is minimized or iconified.
minimumSizeDimensionr/wThe smallest rectangle to which the window can be resized.
orientationStringr/w

The layout orientation of children in a container.

Interpreted by the layout manager for the container. The default LayoutManager Object accepts the (case-insensitive) values row, column, or stack. For window and panel, the default is column, and for group the default is row. The allowed values for the container’s alignChildren and its children’s alignment properties depend on the orientation.

parentObjectreadonlyThe immediate parent element.
preferredSizeDimensionr/w

The preferred size of the window.

Used in automatic layout and resizing.

propertiesObjectr/w

An object that contains one or more creation properties of the container (properties used only when the element is created).

Creation properties of a Window object can include:

- resizeable: When true, the window can be resized by the user. Default is false.

- su1PanelCoordinates: Photoshop only. When true, the child panels of this window automatically adjust the positions of their children for compatability with Photoshop CS (in which the vertical coordinate was measured from outside the frame). Default is false. Individual panels can override the parent window’s setting.

- closeButton: Bridge only. When true, the title bar includes a button to close the window, if the platform and window type allow it. When false, it does not. Default is true. Not used for dialogs.

- maximizeButton: Bridge only. When true, the title bar includes a button to expand the window to its maximum size (typically, the entire screen), if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Not used for dialogs.

shortcutKeyStringr/wThe keypress combination that invokes this element's onShortcut callback.
sizeDimensionr/wThe current size and location of the content area of the window in screen coordinates.
spacingNumberr/w

The number of pixels separating one child element from its adjacent sibling element.

Because each container holds only a single row or column of children, only a single spacing value is needed for a container. The default value is based on the type of container, and is chosen to match standard Adobe UI guidelines.

textStringr/w

The title, label, or displayed text, a localizeable string.

Does not apply to containers of type group.

typeStringreadonlyThe element type; "dialog", "palette", or "window".
versionAnyreadonly>Deprecated. Use ScriptUI.version instead.
visibleboolr/w

When true, the element is shown, when false it is hidden.

When a container is hidden, its children are also hidden, but they retain their own visibility values, and are shown or hidden accordingly when the parent is next shown.

windowWindowreadonlyThe window that this element belongs to.
windowBoundsBoundsreadonlyThe bounds of this window relative to the top-level parent window.

Methods

void Window (type:String, title:String, bounds:Bounds, properties:Object)
Creates a new window.

ParameterTypeDescription
typeString

The window type.

One of:

- window: Creates a simple window that can be used as a main window for an application. (Not supported by Photoshop CS3.)

- palette: Creates a modeless dialog, also called a floating palette. (Not supported by Photoshop CS3.)

- dialog: Creates a modal dialog.

This argument can also be a ScriptUI resource specification; in that case, all other arguments are ignored.

titleStringThe window title, a localizable string.
boundsBoundsThe window's position and size.
propertiesObject

An object containing creation-only properties.

Can contain any of these properties:

- resizeable: When true, the window can be resized by the user. Default is false.

- su1PanelCoordinates: Photoshop only. When true, the child panels of this window automatically adjust the positions of their children for compatability with Photoshop CS (in which the vertical coordinate was measured from outside the frame). Default is false. Individual panels can override the parent window’s setting.

- closeButton: When true, the title bar includes a button to close the window, if the platform and window type allow it. When false, it does not. Default is true. Not used for dialogs.

- maximizeButton: When true, the title bar includes a button to expand the window to its maximum size (typically, the entire screen), if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Not used for dialogs.

- minimizeButton: When true, the title bar includes a button to minimize or iconify the window, if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Main windows cannot have a minimize button in Mac OS. Not used for dialogs.

- independent: When true, a window of type window is independent of other application windows, and can be hidden behind them in Windows. In Mac OS, has no effect. Default is false.

Object add (type:String, bounds:Bounds, text:String, properties:Object)
Creates and returns a new control or container object and adds it to the children of this window.

ParameterTypeDescription
typeString

The type of the child element, as specified for the type property.

Control types are listed in the JavaScript Tools Guide.

boundsBounds

A bounds specification that describes the size and position of the new control or container, relative to its parent.

If supplied, this value creates a new Bounds object which is assigned to the new object’s bounds property.

textString

The text or label, a localizable string.

Initial text to be displayed in the control as the title, label, or contents, depending on the control type. If supplied, this value is assigned to the new object’s text property.

propertiesObject

An object that contains one or more creation properties of the new child (properties used only when the element is created).

The creation properties depend on the element type. See properties property of each control type.

bool addEventListener (eventName:String, handler:Function [, capturePhase:bool=false])
Registers an event handler for a particular type of event occuring in this window.

ParameterTypeDescription
eventNameString

The name of the event.

Event names are listed in the JavaScript Tools Guide.

handlerFunction

The function that handles the event.

This can be the name of a function defined in the extension, or a locally defined handler function to be executed when the event occurs. A handler function takes one argument, the UIEvent object.

capturePhasebool

When true, the handler is called only in the capturing phase of the event propagation. (default: false)

Default is false, meaning that the handler is called in the bubbling phase if this object is an ancestor of the target, or in the at-target phase if this object is itself the target.

void alert (message:String, title:String [, errorIcon:bool=false])
Displays a platform-standard dialog containing a short message and an OK button.

ParameterTypeDescription
messageStringTThe string for the displayed message.
titleString

A string to appear as the title of the dialog, if the platform supports a title.

Ignored in Mac OS, which does not support titles for alert dialogs. The default title string is "Script Alert".

errorIconbool

When true, the platform-standard alert icon is replaced by the platform-standard error icon in the dialog. (default: false)

Ignored in Mac OS, which does not support icons for alert dialogs.

void center (window:Window)
Centers this window on screen or with repect to another window.

ParameterTypeDescription
windowWindowThe relative window. If not specified, centers on the screen.

void close (return:Any)
Closes this window.

. If an onClose callback is defined for the window, calls that function before closing the window.

ParameterTypeDescription
returnAnyA number to be returned from the show() method that invoked this window as a modal dialog.

bool confirm (message:String [, noAsDefault:bool=false], title:String)
Displays a platform-standard dialog containing a short message and two buttons labeled Yes and No.

Returns true if the user clicked Yes, false if the user clicked No.

ParameterTypeDescription
messageStringThe string for the displayed message.
noAsDefaultbool

When true, the No button is the default choice, selected when the user types Enter. (default: false)

Default is false, meaning that Yes is the default choice.

titleString

A string to appear as the title of the dialog, if the platform supports a title.

Ignored in Mac OS, which does not support titles for alert dialogs. The default title string is "Script Alert".

UIEvent dispatchEvent ()
Simulates the occurrence of an event in this target.

A script can create a UIEvent object for a specific event and pass it to this method to start the event propagation for the event.

Window find (type:String, title:String)
Use this method to find an existing window.

This includes windows defined by ScriptUI resource strings, windows already created by a script, and windows created by the application (if the application supports this case). This function is not supported by all applications. Returns a Window object found or generated from the resource, or null if no such window or resource exists.

ParameterTypeDescription
typeString

The name of a predefined resource available to JavaScript in the current application; or the window type.

If a title is specified, the type is used if more than one window with that title is found. Can be null or the empty string.

titleStringThe window title.

void hide ()
Hides this windows.

When a window is hidden, its children are also hidden, but when it is shown again, the children retain their own visibility states.

- For a modal dialog, closes the dialog and sets its result to 0.

void notify (eventName:String)
Sends a notification message to all listeners, simulating the specified user interaction event.

ParameterTypeDescription
eventNameString

The event name; if omitted, the default event is sent.

One of: onClose, onMove, onMoving, onResize, onResizing, onShow

bool onClose ()
An event-handler callback function, called when the window is about to be closed.

Called when a request is made to close the window, either by an explicit call to the close() function or by a user action (clicking the OS-specific close icon in the title bar). The function is called before the window actually closes; it can return false to cancel the close operation.

void onDraw ()
An event-handler callback function, called when the window is about to be drawn.

Allows the script to modify or control the appearance, using the control’s associated ScriptUIGraphics object. Handler takes one argument, a DrawState object.

void onMove ()
An event-handler callback function, called when the window has been moved

void onMoving ()
An event-handler callback function, called when the window is being moved

Called while a window in being moved, each time the position changes. A handler can monitor the move operation.

void onResize ()
An event-handler callback function, called after the window has been resized

void onResizing ()
An event-handler callback function, called while a window is being resized

Called while a window is being resized, each time the height or width changes. A handler can monitor the resize operation.

void onShortcutKey ()
In Windows only, an event-handler callback function, called a shortcut-key sequence is typed that matches the shortcutKey value for this window.

void onShow ()
An event-handler callback function, called just before the window is displayed

Called when a request is made to open the window using the show() method, before the window is made visible, but after automatic layout is complete. A handler can modify the results of the automatic layout.

String prompt (prompt:String, default:String, title:String)
Displays a modal dialog that returns the user’s text input.

Returns the value of the text edit field if the user clicked OK, null if the user clicked Cancel.

ParameterTypeDescription
promptStringThe string for the displayed message.
defaultStringThe initial value to be displayed in the text edit field.
titleString

A string to appear as the title of the dialog.

In Windows, this appears in the window’s frame; in Mac OS it appears above the message. The default title string is "Script Prompt".

void remove (what:Any)
Removes the specified child control from this window’s children array.

No error results if the child does not exist.

ParameterTypeDescription
whatAnyThe child control to remove, specified by 0-based index, text property value, or as a control object.

bool removeEventListener (eventName:String, handler:Function [, capturePhase:bool=false])
Unregisters an event handler for a particular type of event occuring in this window.

All arguments must be identical to those that were used to register the event handler.

ParameterTypeDescription
eventNameStringThe name of the event.
handlerFunctionThe function that handles the event.
capturePhaseboolWhether to call the handler only in the capturing phase of the event propagation. (default: false)

void show ()
Makes this window visible.

If an onShow callback is defined for a window, calls that function before showing the window.When a window or container is hidden, its children are also hidden, but when it is shown again, the children retain their own visibility states.

- For a modal dialog, opens the dialog and does not return until the dialog is dismissed. If it is dismissed via the close() method, this method returns any result value passed to that method. Otherwise, returns 0.

Element of

Button.window

Checkbox.window

DropDownList.window

EditText.window

FlashPlayer.window

Group.window

IconButton.window

Image.window

ListBox.window

Panel.window

Progressbar.window

RadioButton.window

Scrollbar.window

Slider.window

StaticText.window

TreeView.window

Window.window

Used in

Window.center (window:Window)

Return

Window Window.find (type:String, title:String)

Contents :: Index