window-object

Window object

Window Object constructor

The constructor creates and returns a new Window object, or null if window creation failed.

new Window (type [, title, bounds, {creation_properties}]);

Parameter	Type	Description
`type`	String	The window type. One of:
		- `"dialog"` - Creates a modal dialog.
		- `"palette"` - Creates a modeless dialog, also called a floating palette. (Not supported by Photoshop CC.)
		- `"window"` - Creates a simple window that can be used as a main window for an application. (Not supported by Photoshop CC.)
		This argument can be a ScriptUI resource specification; in this case, all other arguments are ignored. See Resource specifications.
`title`	String	Optional. The window title. A localizable string.
`bounds`	Bounds object.	Optional. The window’s position and size.
`creation_properties`	Object	Optional. An object that contains any of the properties below.

Creation Properties

Parameter	Type	Description
`resizeable`	Boolean	When `true`, the window can be resized by the user.
		Default is `false`.
`su1PanelCoordinates`	Boolean	(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).
		Individual panels can override the parent window’s setting.
		Default is `false`.
`closeButton`	Boolean	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. Not used for dialogs.
		Default is `true`.
`maximizeButton`	Boolean	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. Not used for dialogs.
		Default is `false` for type palette, `true` for type window.
`minimizeButton`	Boolean	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. Main windows cannot have a minimize button in Mac OS. Not used for dialogs.
		Default is `false` for type palette, `true` for type window.
`independent`	Boolean	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`.
`borderless`	Boolean	When `true`, the window has no title bar or borders. Properties that control those features are ignored.

Window Object Attributes

The following element properties apply specifically to Window elements:

active

windowOrContainerObj.active

Description

When true, the object is active, false otherwise. Set to true to make a given control or dialog 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.

Type

Boolean

cancelElement

windowOrContainerObj.cancelElement

Description

For a window of type dialog, the control to notify when a user types the ESC key.

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

Type

Control object

defaultElement

windowOrContainerObj.defaultElement

Description

For a window of type dialog, the control to notify when a user types the ENTER key.

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

Type

Control object

frameBounds

windowOrContainerObj.frameBounds

Description

A Bounds object for the boundaries of the Window’s 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.

Type

Bounds. Read only.

frameLocation

windowOrContainerObj.frameLocation

Description

A Point object for the location of the top left corner of the Window’s frame. 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.

Type

Point

frameSize

windowOrContainerObj.frameSize

Description

A Dimension object for the size and location of the Window’s frame in screen coordinates.

Type

Dimension. Read only.

maximized

windowOrContainerObj.maximized

Description

When true, the window is expanded.

Type

Boolean

minimized

windowOrContainerObj.minimized

Description

When true, the window is minimized or iconified.

Type

Boolean

opacity

windowOrContainerObj.opacity

Description

The opacity of the window, in the range [0..1].

A value of 1.0 (the default) makes the window completely opaque, a value of 0 makes it completely transparent.

Intermediate values make it partially transparent to any degree.

Type

Number

shortcutKey

windowOrContainerObj.shortcutKey

Description

The key sequence that invokes this window’s ControlEvent.onShortcutKey callback.

Type

String

Container Attributes

The following table shows properties that apply to Window objects and container objects (controls of type panel, tabbedpanel, tab, and group).

alignChildren

windowOrContainerObj.alignChildren

Description

Tells the layout manager how unlike-sized children of a 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.

For a single string value, allowed values depend on the orientation value.

For orientation=row:

top
bottom
center (default)
fill

For orientation=column:

left
right
center (default)
fill

For orientation=stack:

top
bottom
left
right
center (default)
fill

For an array value, the first string element defines the horizontal alignment and the second element defines the vertical alignment. The horizontal alignment value must be one of left, right, center or fill. The vertical alignment value must be one of top, bottom, center, or fill.

Values are not case sensitive.

Type

String, or Array of 2 Strings

alignment

windowOrContainerObj.alignment

Description

Applies to child elements of a container. If defined, this value overrides the alignChildren setting for the parent container.

For a single string value, allowed values depend on the orientation value.

For orientation = row:

top
bottom
center (default)
fill

For orientation=column:

left
right
center (default)
fill

For orientation = stack:

top
bottom
left
right
center (default)
fill

For an array value, the first string element defines the horizontal alignment and the second element defines the vertical alignment.

The horizontal alignment value must be one of left, right, center or fill. The vertical alignment value must be one of top, bottom, center, or fill.

Values are not case sensitive.

Type

String, or Array of 2 Strings

bounds

windowOrContainerObj.bounds

Description

A Bounds object for the boundaries of the window’s drawable area in screen coordinates. Compare frameBounds.

Does not apply to containers of type tab, whose bounds are determined by the parent tabbedpanel container.

Type

Bounds. Read only.

children

windowOrContainerObj.children

Description

The collection of user-interface elements that have been added to this window or 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.

Type

Array of Objects. Read only.

graphics

windowOrContainerObj.graphics

Description

A ScriptUIGraphics object that can be used to customize the window’s appearance, in response to the onDraw event.

Type

ScriptUIGraphics object

layout

windowOrContainerObj.layout

Description

A LayoutManager object for a window or 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.

Type

LayoutManager object

location

windowOrContainerObj.location

Description

A Point object for the location of the top left corner of the Window’s drawable area, or the top left corner of the frame for a panel.

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

Type

Point

margins

windowOrContainerObj.margins

Description

A Margins object describing the number of pixels between the edges of this 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 user-interface guidelines.

Type

Margins

maximumSize

windowOrContainerObj.maximumSize

Description

Dimension

A Dimension object for the largest rectangle to which the window can be resized, used in automatic layout and resizing.

Type

minimumSize

windowOrContainerObj.minimumSize

Description

Dimension

A Dimension object for the smallest rectangle to which the window can be resized, used in automatic layout and resizing.

Type

orientation

windowOrContainerObj.orientation

Description

How elements are organized within this container.

Interpreted by the layout manager for the container.

The default LayoutManager object accepts the (case-insensitive) values:

row
column
stack

The default orientation depends on the type of container. 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.

Type

String

parent

windowOrContainerObj.parent

Description

The immediate parent object of this element, a window or container element. The value is null for Window objects.

Type

Object. Read only.

preferredSize

windowOrContainerObj.preferredSize

Description

A Dimension object for the preferred size of the window, used in automatic layout and resizing. To set a specific value for only one dimension, specify other dimension as -1.

Type

Dimension

properties

windowOrContainerObj.properties

Description

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

Type

Object

selection

windowOrContainerObj.selection

Description

For TabbedPanel objects only.

The currently active Tab child. Setting this property changes the active tab. The value can only be null when the panel has no children; setting it to null is an error.

When the value changes, either by a user selecting a different tab, or by a script setting the property, the onChange callback for the panel is called.

Type

tab

size

windowOrContainerObj.size

Description

A Dimension object for the current size and location of a group or panel element, or of the content area of a window.

Type

Dimension

spacing

windowOrContainerObj.spacing

Description

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 user-interface guidelines.

Type

Number

text

windowOrContainerObj.text

Description

The title, label, or displayed text. Does not apply to containers of type group or tabbedpanel.

This is a localizable string: see Localization in ScriptUI objects.

Type

String

visible

windowOrContainerObj.visible

Description

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.

Type

Boolean

window

windowOrContainerObj.window

Description

The top-level parent window of this container, a Window object.

Type

Window

windowBounds

windowOrContainerObj.windowBounds

Description

A Bounds object for the size and location of this container relative to its top-level parent window.

Type

Bounds

Window Object Methods

These functions are defined for Window instances, and as indicated for container objects of type Panel and Group.

add()

windowOrContainerObj.add(type[, bounds, text, { creation_props } ]);

Description

Creates and returns a new control or container object and adds it to the children of this window or container.

Parameters

Parameter	Type	Description
`type`	String	The control type. See Control types and creation parameters.
`bounds`	Bounds object	Optional. A bounds specification that describes the size and position of the new control or container, relative to its parent. See Bounds object for specification formats. If supplied, this value creates a new Bounds object which is assigned to the new object’s bounds property.
`text`	String	Optional. 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.
`creation_props`	Object.	Optional. The properties of this object specify creation parameters, which are specific to each object type. See Control types and creation parameters.

Returns

The new object, or null if unable to create the object.

addEventListener()

windowObj.addEventListener(eventName, handler[, capturePhase=false]);

Description

Registers an event handler for a particular type of event occurring in this window.

Parameters

Parameter	Type	Description
`eventName`	String	The event name string. Predefined event names include:
		- `"change"`
		- `"changing"`
		- `"move"`
		- `"moving"`
		- `"resize"`
		- `"resizing"`
		- `"show"`
		- `"enterKey"`
		- `"focus"`
		- `"blur"`
		- `"mousedown"`
		- `"mouseup"`
		- `"mousemove"`
		- `"mouseover"`
		- `"mouseout"`
		- `"click"` (detail = 1 for single, 2 for double)
`handler`	Function	The function to register for the specified event in this target. 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 base class. See Registering event listeners for windows or controls.
`capturePhase`	Boolean	Optional. When `true`, the handler is called only in the capturing phase of the event propagation. 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.

Returns

Nothing

center()

windowObj.center([window])

Description

Centers this window on the screen, or with respect to another specified window.

Parameters

Parameter	Type	Description
`window`	Window object	Optional. A Window object.

Returns

Nothing

close()

windowObj.close([result])

Description

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

Parameters

Parameter	Type	Description
`result`	Number	Optional. A number to be returned from the show method that invoked this window as a modal dialog.

Returns

Nothing

dispatchEvent()

windowObj.dispatchEvent(eventObj)

Description

Simulates the occurrence of an event in this target. A script can create a UIEvent base class for a specific event and pass it to this method to start the event propagation for the event.

Parameters

Parameter	Type	Description
`eventObj`	UIEvent base class	A UIEvent base class.

Returns

Boolean. false if any of the registered listeners that handled the event called the event object’s preventDefault() method, true otherwise.

findElement()

windowOrContainerObj.findElement(name)

Description

Searches for the named element among the children of this window or container, and returns the object if found.

Parameters

Parameter	Type	Description
`name`	String	The name of the element, as specified in the name creation property.

Returns

The control object or null.

hide()

windowObj.hide()

Hides this window. 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.

Returns

Nothing

notify()

windowObj.notify([event])

Description

Sends a notification message, simulating the specified user interaction event.

Parameters

Parameter	Type	Description
`event`	String	Optional. The name of the window event handler to call. One of:
		- `onClose`
		- `onMove`
		- `onMoving`
		- `onResize`
		- `onResizing`
		- `onShow`

Returns

Nothing

Example

To simulate a dialog being moved by a user:

myDlg.notify("onMove")

remove()

windowOrContainerObj.remove(index)

windowOrContainerObj.remove(text)

windowOrContainerObj.remove(child)

Description

Removes the specified child control from this window’s or container’s children array. No error results if the child does not exist.

Parameters

Parameter	Type	Description
`index`/`text`/`child`	Number, String, or Control object	The child control to remove, specified by 0-based index, the contained text value, or as a control object.

Returns

Nothing

removeEventListener()

windowOrContainerObj.removeEventListener(eventName, handler[, capturePhase])

Description

Unregisters an event handler for a particular type of event occurring in this window. All arguments must be identical to those that were used to register the event handler.

Parameters

Parameter	Type	Description
`eventName`	String	The event name string.
`handler`	Function	The function that was registered to handle the event.
`capturePhase`	Boolean	Optional. Whether the handler was to respond only in the capture phase.

Returns

Nothing

show()

windowOrContainerObj.show()

Shows this window, container, or control. 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.

Returns

Nothing

update()

windowOrContainerObj.update()

Allows a script to run a long operation (such as copying a large file) and update UI elements to show the status of the operation.

Normally, drawing updates to UI elements occur during idle periods, when the application is not doing anything and the OS event queue is being processed, but during a long scripted operation, the normal event loop is not running. Use this method to perform the necessary synchronous drawing updates, and also process certain mouse and keyboard events in order to allow a user to cancel the current operation (by clicking a Cancel button, for instance).

During the update() operation, the application is put into a modal state, so that it does not handle any events that would activate a different window, or give focus to a control outside the window being updated. The modal state allows drawing events for controls in other windows to occur (as is the case during a modal show() operation), so that the script does not prevent the update of other parts of the application’s UI while in the operation loop.

It is an error to call the update() method for a window that is not currently visible.

Returns

Nothing

Window event-handling callbacks

The following callback functions can be defined to respond to events in windows. To respond to an event, define a function with the corresponding name in the Window instance. These callbacks are not available for other container types (controls of type panel or group).

onActivate

Called when the user make the window active by clicking it or otherwise making it the keyboard focus.

onClose

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.

onDeactivate

Called when the user makes a previously active window inactive; for instance by closing it, or by clicking another window to change the keyboard focus.

onDraw

Called when a container or control is about to be drawn. Allows the script to modify or control the appearance, using the control’s associated ScriptUIGraphics object object. Handler takes one argument, a DrawState object object.

onMove

Called when the window has been moved.

onMoving

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

onResize

Called when the window has been resized.

onResizing

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

onShortcutKey

(In Windows only)

Called when a shortcut-key sequence is typed that matches the shortcutKey value for this window.

onShow

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.