CS3 JS: Window

CS3 ScriptUI

previous page next page

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

Property	Type	Access	Description
active	bool	r/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.
alignChildren	String	r/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.
alignment	String	r/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`
bounds	Bounds	r/w	The bounds of the window's drawable area, excluding the frame, in screen coordinates.
cancelElement	Object	r/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).
characters	Number	r/w	A number of characters for which to reserve space when calculating the preferred size of the window.
children	Array of Object	readonly	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.
defaultElement	Object	r/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).
enabled	bool	r/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.
frameBounds	Bounds	readonly	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.
frameLocation	Point	r/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.
frameSize	Dimension	readonly	The size and location of the window's frame in screen coordinates.
frameworkName	String	readonly	>Deprecated. Use ScriptUI.frameworkName instead.
graphics	ScriptUIGraphics	readonly	The graphics object that can be used to customize the window’s appearance, in response to the onDraw event.
helpTip	String	r/w	The help text that is displayed when the mouse hovers over the element.
indent	Number	r/w	The number of pixels to indent the element.
justify	String	r/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.
layout	LayoutManager	r/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.
location	Point	r/w	The upper left corner of the window's drawable area. The same as [bounds.x, bounds.y].
margins	Number	r/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.
maximized	bool	r/w	True if the window is expanded.
maximumSize	Dimension	r/w	The largest rectangle to which the window can be resized.
minimized	bool	r/w	True if the window is minimized or iconified.
minimumSize	Dimension	r/w	The smallest rectangle to which the window can be resized.
orientation	String	r/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.
parent	Object	readonly	The immediate parent element.
preferredSize	Dimension	r/w	The preferred size of the window. Used in automatic layout and resizing.
properties	Object	r/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.
shortcutKey	String	r/w	The keypress combination that invokes this element's `onShortcut` callback.
size	Dimension	r/w	The current size and location of the content area of the window in screen coordinates.
spacing	Number	r/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.
text	String	r/w	The title, label, or displayed text, a localizeable string. Does not apply to containers of type group.
type	String	readonly	The element type; "dialog", "palette", or "window".
version	Any	readonly	>Deprecated. Use ScriptUI.version instead.
visible	bool	r/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.
window	Window	readonly	The window that this element belongs to.
windowBounds	Bounds	readonly	The 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.

Parameter Type Description

type

String

Parameter	Type	Description
type	String	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.

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.

Parameter	Type	Description
type	String	The type of the child element, as specified for the type property. Control types are listed in the JavaScript Tools Guide.
bounds	Bounds	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.
text	String	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.
properties	Object	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.

Parameter	Type	Description
eventName	String	The name of the event. Event names are listed in the JavaScript Tools Guide.
handler	Function	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.
capturePhase	bool	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.

Parameter

Type

Description

eventName

String

The name of the event.

Event names are listed in the JavaScript Tools Guide.

handler

Function

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.

capturePhase

bool

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.

Parameter	Type	Description
message	String	TThe string for the displayed message.
title	String	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".
errorIcon	bool	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.

Parameter

Type

Description

message

String

TThe string for the displayed message.

title

String

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".

errorIcon

bool

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.

Parameter	Type	Description
window	Window	The 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.

Parameter	Type	Description
return	Any	A 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.

Parameter	Type	Description
message	String	The string for the displayed message.
noAsDefault	bool	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.
title	String	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".

Parameter

Type

Description

message

String

The string for the displayed message.

noAsDefault

bool

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.

title

String

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.

Parameter	Type	Description
type	String	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.
title	String	The window title.

Parameter

Type

Description

type

String

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.

title

String

The 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.

Parameter Type Description

eventName

String

Parameter	Type	Description
eventName	String	The event name; if omitted, the default event is sent. One of: `onClose`, `onMove`, `onMoving`, `onResize`, `onResizing`, `onShow`

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.

Parameter	Type	Description
prompt	String	The string for the displayed message.
default	String	The initial value to be displayed in the text edit field.
title	String	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".

Parameter

Type

Description

prompt

String

The string for the displayed message.

default

String

The initial value to be displayed in the text edit field.

title

String

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.

Parameter	Type	Description
what	Any	The 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.

Parameter	Type	Description
eventName	String	The name of the event.
handler	Function	The function that handles the event.
capturePhase	bool	Whether 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.