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}]);
|
The window type. The value is:
This argument can be a ScriptUI resource specification; in this case, all other arguments are ignored. See Resource specifications. |
|
Optional. The window title. A localizable string. |
|
Optional. The window’s position and size. |
|
Optional. An object that can contain any of these properties:
|
Window object properties¶
The following element properties apply specifically to Window elements:
active¶
Type: Boolean
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.
cancelElement¶
Type: Object
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).
defaultElement¶
Type: Object
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).
frameBounds¶
Type: Bounds
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. Read only.
frameLocation¶
Type: Point
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.
frameSize¶
Type: Dimension
A Dimension object for the size and location of the Window’s frame in screen coordinates. Read only.
maximized¶
Type: Boolean
When true, the window is expanded.
minimized¶
Type: Boolean
When true, the window is minimized or iconified.
opacity¶
Type: Number
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.
shortcutKey¶
Type: String
The key sequence that invokes this window’s ref:control-event-onshortcutkey callback (in Windows only).
Container properties¶
The following table shows properties that apply to Window objects and container objects (controls of type panel, tabbedpanel, tab, and group).
alignChildren¶
Type: String, or Array of 2 Strings
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.
alignment¶
Type: String, or Array of 2 Strings
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.
bounds¶
Type: Bounds
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.
Read only.
children¶
Type: Array of Object
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.
Read only.
graphics¶
Type: ScriptUIGraphics object
A ScriptUIGraphics object that can be used to customize the window’s appearance, in response to the onDraw event.
layout¶
Type: LayoutManager object
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.
location¶
Type: Point
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].
margins¶
Type: Margins
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.
maximumSize¶
Type: Dimension
A Dimension object for the largest rectangle to which the window can be resized, used in automatic layout and resizing.
minimumSize¶
Type: Dimension
A Dimension object for the smallest rectangle to which the window can be resized, used in automatic layout and resizing.
orientation¶
Type: String
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.
parent¶
Type: Object
The immediate parent object of this element, a window or
container element. The value is null
for Window objects.
Read only.
preferredSize¶
Type: Dimension
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
.
properties¶
Type: Object
An object that contains one or more creation properties of the container (properties used only when the element is created).
selection¶
Type: tab
For a tabbedpanel 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.
size¶
Type: Dimension
A Dimension object for the current size and location of a group or panel element, or of the content area of a window.
spacing¶
Type: Number
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.
text¶
Type: String
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.
visible¶
Type: Boolean
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¶
Type: Window
The top-level parent window of this container, a Window object.
windowBounds¶
Type: Bounds
A Bounds object for the size and location of this container relative to its top-level parent window.
Window object functions¶
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> } ]);
|
The control type. See Control types and creation parameters. |
|
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. |
|
Optional. 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. |
|
Optional. Object. The properties of this object specify creation parameters, which are specific to each object type. See Control types and creation parameters. |
Creates and returns a new control or container object and adds it to the children of this window or container.
Returns the new object, or null
if unable to create the object.
addEventListener()¶
windowObj.addEventListener (eventName, handler[, capturePhase]);
|
The event name string. Predefined event names include:
|
|
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. |
|
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. |
Registers an event handler for a particular type of event occurring in this window.
Returns undefined
.
center()¶
windowObj.center ([window])
|
Optional. A Window object. |
Centers this window on the screen, or with respect to another specified window.
Returns undefined
.
close()¶
windowObj.close ([result])
|
Optional. A number to be returned from the show method that invoked this window as a modal dialog. |
Closes this window. If an onClose callback is defined for the window, calls that function before closing the window.
Returns undefined.
dispatchEvent()¶
windowObj.dispatchEvent(eventObj)
|
A UIEvent base class. |
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.
Returns false
if any of the registered listeners that handled the event called the event object’s
preventDefault() method, true
otherwise.
findElement()¶
windowOrContainerObj.findElement(name)
|
The name of the element, as specified in the name creation property. |
Searches for the named element among the children of this window or container, and returns the object if found.
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 undefined
.
notify()¶
windowObj.notify([event])
|
Optional. The name of the window event handler to call. One of:
|
Sends a notification message, simulating the specified user interaction event. For example, to simulate a dialog being moved by a user:
myDlg.notify("onMove")
Returns undefined
.
remove()¶
windowOrContainerObj.remove(index)
windowOrContainerObj.remove(text)
windowOrContainerObj.remove(child)
|
The child control to remove, specified by 0-based index, the contained text value, or as a control object. |
Removes the specified child control from this window’s or container’s children array. No error results if the child does not exist.
Returns undefined
.
removeEventListener()¶
windowObj.removeEventListener(eventName, handler[, capturePhase])
|
The event name string. |
|
The function that was registered to handle the event. |
|
Optional. Whether the handler was to respond only in the capture phase. |
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.
Returns undefined
.
show()¶
windowObj.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.
update()¶
windowObj.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.
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
).
Callback |
Description |
---|---|
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. |