Window (SUI)

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.

Methods:

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

Objects:

Boolean, Bounds (SUI), Dimension (SUI), LayoutManager (SUI), Number, Object, Point (SUI), ScriptUIGraphics (SUI), String, Window (SUI)

Property Listing

Property

Type

Access

Description

active

Boolean

read/write

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

read/write

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

read/write

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 (SUI)

read/write

The bounds of the window's drawable area, excluding the frame, in screen coordinates.

cancelElement

Object

read/write

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

read/write

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

read/write

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

Boolean

read/write

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 (SUI)

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 (SUI)

read/write

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 (SUI)

readonly

The size and location of the window's frame in screen coordinates.

graphics

ScriptUIGraphics (SUI)

readonly

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

helpTip

String

read/write

The help text that is displayed when the mouse hovers over the element.

indent

Number

read/write

The number of pixels to indent the element.

justify

String

read/write

The default text justification style for child text elements.

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

layout

LayoutManager (SUI)

read/write

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 (SUI)

read/write

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

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

margins

Number

read/write

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

Boolean

read/write

True if the window is expanded.

maximumSize

Dimension (SUI)

read/write

The largest rectangle to which the window can be resized.

minimized

Boolean

read/write

True if the window is minimized or iconified.

minimumSize

Dimension (SUI)

read/write

The smallest rectangle to which the window can be resized.

opacity

Number

read/write

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.

orientation

String

read/write

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

 

readonly

The immediate parent element.

preferredSize

Dimension (SUI)

read/write

The preferred size of the window.

Used in automatic layout and resizing. To set a specific value for only one dimension, specify the other dimension as -1.

properties

Object

read/write

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

read/write

The keypress combination that invokes this element's onShortcutKey() callback.

size

Dimension (SUI)

read/write

The current size and location of the content area of the window in screen coordinates.

spacing

Number

read/write

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

read/write

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

visible

Boolean

read/write

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 (SUI)

readonly

The window that this element belongs to.

windowBounds

Bounds (SUI)

readonly

The bounds of this window relative to the top-level parent window.

Property Listing

Name

Type

Access

Description

frameworkName

String

readonly

Deprecated. Use ScriptUI.frameworkName instead.

version

VariesSUI

readonly

Deprecated. Use ScriptUI.version instead.

Method Listing

Constructor

undefined Window (type:String, [title:String], [bounds:BoundsSUI], [properties:Object])

Creates a new window.

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.

title

String

The window title, a localizable string.

bounds

Bounds (SUI)

The window's position and size.

properties

Object

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. borderless: When true, the window has no title bar or borders. Properties that control those features are ignored.

Object add (type:String, [bounds:BoundsSUI], [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 (SUI)

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.

Boolean addEventListener (eventName:String, handler:Function, [capturePhase:Boolean=Boolean])

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

Parameter

Type

Description

eventName

String

The name of the event.

Predefined event names are: change, changing, move, moving, resize, resizing, show , enterKey, focus, blur, keydown, keyup, mousedown, mouseup, mousemove, mouseover, mouseout, click (detail = 1 for single, 2 for double).

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

Boolean

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.

(default: false)

undefined alert (message:String, [title:String], errorIcon:Boolean=Boolean)

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

Boolean

When true, the platform-standard alert icon is replaced by the platform-standard error icon in the dialog.

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

(default: false)

undefined center ([window:WindowSUI])

Centers this window on screen or with repect to another window.

Parameter

Type

Description

window

Window (SUI)

The relative window. If not specified, centers on the screen.

undefined close ([return:VariesSUI])

Closes this window.

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

Parameter

Type

Description

return

VariesSUI

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

Boolean confirm (message:String, noAsDefault:Boolean=Boolean, [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

Boolean

When true, the No button is the default choice, selected when the user types Enter.

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

(default: false)

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 (SUI) 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 (SUI) 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.

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

undefined notify ([eventName:String])

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

Parameter

Type

Description

eventName

String

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

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

undefined onActivate ()

An event-handler callback function, called when the window acquires the keyboard focus.

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

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

undefined onDeactivate ()

An event-handler callback function, called when the window loses the keyboard focus.

Called when the user moves the keyboard focus from the previously active window to another window.

undefined onMove ()

An event-handler callback function, called when the window has been moved

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

undefined onResize ()

An event-handler callback function, called after the window has been resized

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

undefined onShortcutKey ()

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

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

undefined remove (what:VariesSUI)

Removes the specified child control from this window’s children array.

No error results if the child does not exist.

Parameter

Type

Description

what

VariesSUI

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

Boolean removeEventListener (eventName:String, handler:Function, capturePhase:Boolean=Boolean)

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

Boolean

Whether to call the handler only in the capturing phase of the event propagation.

(default: false)

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

Object of

Window (SUI).window

StaticText (SUI).window

Button (SUI).window

IconButton (SUI).window

EditText (SUI).window

ListBox (SUI).window

DropDownList (SUI).window

Checkbox (SUI).window

Scrollbar (SUI).window

RadioButton (SUI).window

Slider (SUI).window

Progressbar (SUI).window

TreeView (SUI).window

FlashPlayer (SUI).window

Group (SUI).window

Panel (SUI).window

Return

Window (SUI).find()