Control objects¶
UI elements that belong to windows can be containers or controls. Containers share some aspects of top-level windows, and some aspects of controls, and so are described here with controls.
Control object constructors¶
Use the add
method to create new containers and controls. The add
method is available on window
and container (panel
and group
) objects. (See also add() for DropDownList and ListBox controls.)
add()¶
containerObj.(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. 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¶
Returns the new object, or null
if unable to create the object.
Control types and creation parameters¶
The following keywords can be used in string literals as the type specifier for the add
method, available on Window
and container (Panel
and Group
) objects. The class names can be used in resource specifications to define controls within a container element (Window
, Panel
, or Group
).
All types of controls, including containers, have an optional creation parameter name
that allows you to give the object a unique name.
button¶
Class Name: Button
Description¶
A pushbutton containing a mouse-sensitive text string. Calls the onClick callback if the control is clicked or if its notify() method is called.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. For a modal dialog, the special name "ok" makes this defaultElement, and the special name "cancel" makes this the cancelElement of the parent dialog. |
Example¶
To add to a window w
:
w.add("button"[, bounds, text, {creation_properties}]);
checkbox¶
Class Name: Checkbox
Description¶
A dual-state control showing a box with a checkmark when value is true
, empty when value
is false
.
Calls the onClick callback if the control is clicked or if its notify() method is called.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("checkbox"[, bounds, text, {creation_properties}]);
dropdownlist¶
Class Name: DropDownList
Description¶
A drop-down list with zero or more items. Calls the onChange callback if the item selection is changed by a script or the user, or if the object's notify() method is called.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
items |
Array of strings | Optional. Supply this argument or the creation_properties argument, not both. The text of each list item. A ListItem object is created for each item. An item with the text string "-" creates a separator item. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
items |
Array of strings | The text of each list item. See the Parameters table for more info. |
Example¶
To add to a window w
:
w.add( "dropdownlist", bounds[, items, {creation_properties}] );
editnumber¶
Class Name: EditNumber
Note
This functionality was added in Photoshop 20.0 (CC 2019), and may not exist in other hosts.
Description¶
An editable text field the user can enter decimal numbers into. Fractions are allowed.
Calls the onChange callback if the text is changed and the user types ENTER
or the control loses focus, or if its notify() method is called.
Calls the onChanging callback when any change is made to the text.
The textselection
property contains currently selected text.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
minValue |
Number | Optional. Minimum accepted value of number to be entered. |
maxValue |
Number | Optional. Maximum accepted value of number to be entered. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
readonly |
Boolean | Optional. When false (the default), the control accepts text input. When true , the control does not accept input but only displays the contents of the text property. |
noecho |
Boolean | Optional. When false (the default), the control displays input text. When true , the control does not display input text (used for password input fields). |
enterKeySignalsOnChange |
Boolean | Optional. When false (the default), the control signals an onChange event when the editable text is changed and the control loses the keyboard focus (that is, the user tabs to another control, clicks outside the control, or types ENTER ). When true , the control only signals an onChange event when the editable text is changed and the user types ENTER ; other changes to the keyboard focus do not signal the event. |
borderless |
Boolean | Optional. When true , the control is drawn with no border. Default is false . |
Example¶
To add to a window w
:
w.add("editnumber"[, bounds, text, minValue, maxValue, {creation_properties}]);
edittext¶
Class Name: EditText
Description¶
An editable text field that the user can change. Calls the onChange callback if the text is changed and the user types ENTER
or the control loses focus, or if its notify() method is called. Calls the onChanging callback when any change is made to the text.
The textselection
property contains currently selected text.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
readonly |
Boolean | When false (the default), the control accepts text input. When true , the control does not accept input but only displays the contents of the text property. |
noecho |
Boolean | When false (the default), the control displays input text. When true , the control does not display input text (used for password input fields). |
enterKeySignalsOnChange |
Boolean | When false (the default), the control signals an onChange event when the editable text is changed and the control loses the keyboard focus (that is, the user tabs to another control, clicks outside the control, or types ENTER ). When true , the control only signals an onChange event when the editable text is changed and the user types ENTER ; other changes to the keyboard focus do not signal the event. |
borderless |
Boolean | When true , the control is drawn with no border. Default is false . |
multiline |
Boolean | When false (the default), the control accepts a single line of text. When true , the control accepts multiple lines, in which case the text wraps within the width of the control. |
scrollable |
Boolean | (For multiline elements only) When true (the default), the text field has a vertical scrollbar that is enabled when the element contains more text than fits in the visible area. When false , no vertical scrollbar appears; if the element contains more text than fits in the visible area, the arrow keys can be used to scroll the text up and down. |
Example¶
To add to a window w
:
w.add("edittext"[, bounds, text, {creation_properties}]);
flashplayer¶
Class Name: FlashPlayer
Description¶
A control that contains a Flash Player, which can load and play Flash movies stored in SWF files.
The ScriptUI FlashPlayer element runs the Flash application within an Adobe application. The Flash application runs ActionScript, a different implementation of JavaScript from the ExtendScript version of JavaScript that Adobe applications run.
A control object of this type contains functions that allow your script to load SWF files, control movie playback, and communicate with the ActionScript environment. See FlashPlayer control functions.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
moveToLoad |
String or File object | Optional. A path or URL string or File for the SWF file to load into the player. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("flashplayer"[, bounds, movieToLoad, {creation_properties}]);
group¶
Class Name: Group
Description¶
A container for other controls. Containers have additional properties that control the children; see Container Attributes.
Hiding a group hides all its children. Making it visible makes visible those children that are not individually hidden.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("group"[, bounds, {creation_properties}]);
iconbutton¶
Class Name: IconButton
Description¶
A mouse-sensitive pushbutton containing an icon. Calls the onClick callback if the control is clicked or if its notify() method is called.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
icon |
Named resource, pathname, or File object | Optional. The named resource for the icon or family of icons displayed in the button control, or a pathname or File for an image file. Images must be in PNG format. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property |
Type |
Description |
---|---|---|
|
String |
A unique name for the control. |
|
String |
A string for the visual style, one of:
|
|
Boolean |
For a button-style control, a value of |
Example¶
To add to a window w
:
w.add("iconbutton"[, bounds, icon, {creation_properties}]);
image¶
Class Name: Image
Description¶
Displays an icon or image.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
icon |
Named resource, pathname, or File object | Optional. The named resource for the icon or family of icons displayed in the button control, or a pathname or File for an image file. Images must be in PNG format. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("image"[, bounds, icon, {creation_properties}]);
item¶
Class Name: Array of ListItem
Description¶
The choice items in a list box or drop-down list. The objects are created when items are specified on creation of the parent list object, or afterward using the list control's add() method.
Items in a drop-down list can be of type separator
, in which case they cannot be selected, and are shown as a horizontal line.
Item objects have these properties which are not found in other controls:
listbox¶
Class Name: ListBox
Description¶
A list box with zero or more items. Calls the onChange callback if the item selection is changed by a script or the user, or if the object's notify() method is called. A double click on an item selects that item and calls the onDoubleClick callback.
Parameters¶
Parameter | Type | Description | |
---|---|---|---|
bounds |
Bounds object | Optional. The control's position and size. | |
items |
Array of Strings | Optional. The text of each list item. A ListItem object is created for each item. Supply this argument, or the items property in creation_properties , not both. A ListItem object is created for each item. An item with the text string "-" creates a separator item. |
|
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
multiselect |
Boolean | When false (the default), only one item can be selected. When true , multiple items can be selected. |
items |
Array of Strings | The text of each list item. Supply this property, or the items argument, not both. This form is most useful for elements defined using Resource specifications. |
numberOfColumns |
Number | A number of columns in which to display the items; default is 1. When there are multiple columns, each ListItem object represents a single selectable row. Its text and image values supply the label for the first column, and the subitems property specifies labels for additional columns. |
showHeaders |
Boolean | true to display column titles. |
columnWidths |
Array of Numbers | An array of numbers for the preferred width in pixels of each column. |
columnTitles |
Array of Strings | A corresponding array of strings for the title of each column, to be shown if showHeaders is true . |
Example¶
To add to a window w
:
w.add("listbox", bounds[, items, {creation_properties}]);
panel¶
Class Name: Panel
Description¶
A container for other types of controls, with an optional frame.
Containers have additional properties that control the children; see Container Attributes. Hiding a panel hides all its children. Making it visible makes visible those children that are not individually hidden.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the border of the panel. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property |
Type |
Description |
---|---|---|
|
String |
A unique name for the control. |
|
String |
A string that specifies the appearance of the border drawn around the panel. Default is
Warning The |
|
Boolean |
When |
Example¶
To add to a window w
:
w.add("panel"[, bounds, text, {creation_properties}]);
progressbar¶
Class Name: Progressbar
Description¶
A horizontal rectangle that shows progress of an operation.
All progressbar
controls have a horizontal orientation. The value
property contains the current position of the progress indicator; the default is 0. There is a minvalue
property, but it is always 0; attempts to set it to a different value are silently ignored.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
value |
Number | Optional. The initial position of the progress indicator. Default is 0. |
minvalue |
Number | Optional. The minimum value that the value property can be set to. Default is 0. Together with maxvalue , defines the range. |
maxvalue |
Number | Optional. The maximum value that the value property can be set to. Default is 100. Together with minvalue , defines the range. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("progressbar"[, bounds, value, minvalue, maxvalue, creation_properties}]);
radiobutton¶
Class Name: RadioButton
Description¶
A dual-state control, grouped with other radiobuttons, of which only one can be in the selected state. Shows the selected state when value
is true
, empty when value is false
. Calls the onClick callback if the control is clicked or if its notify() method is called.
All radiobuttons in a group must be created sequentially, with no intervening creation of other element types. Only one radiobutton
in a group can be set at a time; setting a different radiobutton
unsets the original one.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("radiobutton"[, bounds, text, {creation_properties}]);
scrollbar¶
Class Name: Scrollbar
Description¶
A scrollbar with a draggable scroll indicator and stepper buttons to move the indicator. The scrollbar
control has a horizontal orientation if the width
is greater than the height
at creation time, or vertical if its height
is greater than its width
.
Calls the onChange callback after the position of the indicator is changed or if its notify() method is called. Calls the onChanging callback repeatedly while the user is moving the indicator.
Properties¶
Property | Type | Description |
---|---|---|
value |
Number | Contains the current position of the scrollbar's indicator within the scrolling area, within the range of minvalue and maxvalue . |
stepdelta |
Number | Determines the scrolling unit for the up or down arrow. Default is 1 . |
jumpdelta |
Number | Determines the scrolling unit for a jump (as when the bar is clicked outside the indicator or arrows); default is 20% of the range between minvalue and maxvalue . |
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
value |
Number | Optional. The initial position of the scroll indicator. Default is 0. |
minvalue |
Number | Optional. The minimum value that the value property can be set to. Default is 0. Together with maxvalue , defines the scrolling range. |
maxvalue |
Number | Optional. The maximum value that the value property can be set to. Default is 100. Together with minvalue , defines the scrolling range. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("scrollbar"[, bounds, value, minvalue, maxvalue, {creation_properties}]);
slider¶
Class Name: Slider
Description¶
A slider with a moveable position indicator. All slider
controls have a horizontal orientation. Calls the onChange callback after the position of the indicator is changed or if its notify() method is called.
Calls the onChanging
callback repeatedly while the user is moving the indicator.
The value
property contains the current position of the indicator within the range of minvalue
and maxvalue
.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
value |
Number | Optional. The initial position of the scroll indicator. Default is 0. |
minvalue |
Number | Optional. The minimum value that the value property can be set to. Default is 0. Together with maxvalue , defines the range. |
maxvalue |
Number | Optional. The maximum value that the value property can be set to. Default is 100. Together with minvalue , defines the range. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("slider"[, bounds, value, minvalue, maxvalue, {creation_properties}]);
statictext¶
Class Name: StaticText
Description¶
A text field that the user cannot change.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property |
Type |
Description |
---|---|---|
|
String |
A unique name for the control. |
|
Boolean |
When |
|
Boolean String |
When
If |
Example¶
To add to a window w
:
w.add("statictext"[, bounds, text, {creation_properties}]);
tab¶
Class Name: Tab
Description¶
A container for other types of controls. Differs from a panel element in that is must be a direct child of a tabbedpanel element, the title is shown in the selection tab, and it does not have a script-definable border. The currently active tab is the value of the parent's selection
property.
Containers have additional properties that control the children; see Container Attributes. Hiding a panel hides all its children. Making it visible makes visible those children that are not individually hidden.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add a tab to a tabbed panel t
in window w
:
w.t.add("tab"[, bounds, text, {creation_properties}]);
tabbedpanel¶
Class Name: TabbedPanel
Description¶
A container for selectable tab containers. Differs from a panel element in that it can contain only tab elements as direct children.
Containers have additional properties that control the children; see Container Attributes. Hiding a panel hides all its children. Making it visible makes visible those children that are not individually hidden.
The selected tab child is the value of the parent's selection
property. One and only one of the tab
children must be selected; selecting one deselects the others. When the value of the selection
property changes, either by a user selecting a different tab, or by a script setting the property, the tabbedpanel
receives an onChange notification.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
text |
String | Optional. The text displayed in the control. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
Example¶
To add to a window w
:
w.add("tabbedpanel"[, bounds, text, {creation_properties}]);
treeview¶
Class Name: TreeView
Description¶
A hierarchical list whose items can contain child items. Items at any level of the tree can be individually selected. Calls the onChange callback if the item selection is changed by a script or the user, or if the object's notify() method is called.
Parameters¶
Parameter | Type | Description |
---|---|---|
bounds |
Bounds object | Optional. The control's position and size. |
items |
Array of Strings | Optional. The text of each top-level list item. A ListItem object is created for each item. An item with the type node can contain child items. Supply this argument, or the items property in creation_properties , not both. |
creation_properties |
Object | Optional. An object that contains any of the properties below. |
Creation Properties¶
Property | Type | Description |
---|---|---|
name |
String | A unique name for the control. |
items |
Array of Strings | The text of each top-level list item. A ListItem object is created for each item. An item with the type node can contain child items. Supply this property, or the items argument, not both. This form is most useful for elements defined using Resource specifications. |
Example¶
To add to a window w
:
w.add("treeview"[, bounds, items, {creation_properties}])
Control object properties¶
The following table shows the properties of ScriptUI control elements. Some values apply only to controls of particular types, as indicated.
See Container Attributes for properties that apply to container elements (controls of type panel, tabbedpanel, tab, and group).
active¶
controlObj.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 ENTER in Windows, or presses the spacebar in Mac OS.
Type¶
Boolean
alignment¶
controlObj.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 in the parent container.
|
Allowed values |
---|---|
|
|
|
|
|
|
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"
.
Note
Values are not case sensitive.
Type¶
String or Array of 2 Strings
bounds¶
controlObj.bounds
Description¶
A Bounds object describing the boundaries of the element, in screen coordinates for Window elements, and parent-relative coordinates for child elements (compare windowBounds). For windows, the bounds refer only to the window's content region.
Type¶
characters¶
controlObj.characters
Description¶
Used by the LayoutManager object to determine the default preferredSize for a StaticText or EditText control.
The control will be made wide enough to display the given number of X
characters in the font used by the control. Setting this property is the best way to reserve space in a control for a maximum number of characters to display.
Type¶
Number
checked¶
controlObj.checked
Description¶
Info
For ListItem objects only.
- When
true
, the item is marked with the platform-appropriate checkmark. - When
false
, no checkmark is drawn, but space is reserved for it in the left margin, so that the item lines up with other checkable items. - When
undefined
, no space is reserved for a checkmark.
Type¶
Boolean
columns¶
controlObj.columns
Description¶
Info
For ListBox objects only.
A JavaScript object with two read-only properties whose values are set by the creation parameters.
Properties¶
Property | Type | Description |
---|---|---|
titles |
Array of Strings | An array of column title strings, whose length matches the number of columns specified at creation. |
preferredWidths |
Array of Numbers | An array of column widths, whose length matches the number of columns specified at creation. |
Type¶
Object
enabled¶
controlObj.enabled
Description¶
- When
true
, the control is enabled, meaning that it accepts input. - When
false
, control elements do not accept input, and all types of elements have a dimmed appearance.
Note
A disabled ListItem is not selectable in a ListBox, DropDownList, or TreeView object.
Type¶
Boolean
expanded¶
controlObj.expanded
Description¶
For ListItem objects of type node
in TreeView list controls. When true
, the item is in the expanded state and its children are shown, when false
, it is collapsed and children are hidden.
Type¶
Boolean
graphics¶
controlObj.graphics
Description¶
A ScriptUIGraphics object that can be used to customize the control's appearance, in response to the onDraw event.
Type¶
helpTip¶
controlObj.helpTip
Description¶
A brief help message (also called a tool tip) that is displayed in a small floating window when the mouse cursor hovers over a user-interface control element.
Set to an empty string or null
to remove help text.
Type¶
String
icon¶
controlObj.icon
Description¶
Danger
Deprecated. Use Image instead.
Type¶
String or File object
image¶
controlObj.image
Description¶
A ScriptUIImage object, or the name of an icon resource, or the pathname or File object for a file that contains a platform-specific image in PNG or JPEG format, or for a shortcut or alias to such a file.
- For an IconButton, the icon appears as the content of the button.
- For an Image, the image is the entire content of the image element.
- For a ListItem, the image is displayed to the left of the text.
- If the parent is a multi-column ListBox, this is the display image for the label in the first column, and labels for further columns are specified in the subitems array.
- See Creating multi-column lists.
Type¶
indent¶
controlObj.indent
Description¶
A number of pixels by which to indent the element during automatic layout. Applies for column
orientation and left
alignment, or row
orientation and top
alignment.
Type¶
Number
index¶
controlObj.index
Description¶
Info
For ListItem objects only.
The index of this item in the items
collection of its parent list control.
Type¶
Number. Read only.
items¶
controlObj.items
Description¶
Info
For ListBox, DropDownList, or TreeView objects only.
A collection of ListItem objects for the items in the list. Access by 0-based index.
Tip
To obtain the number of items in the list, use items.length
.
Type¶
Array of Objects. Read only.
itemSize¶
controlObj.itemSize
Description¶
Info
For ListBox, DropDownList, or TreeView objects only.
A Dimension object describing the width and height in pixels of each item in the list.
Used by auto-layout to determine the preferredSize
of the list, if not otherwise specified.
If not set explicitly, the size of each item is set to match the largest height and width among all items in the list.
Type¶
Dimension object
jumpdelta¶
controlObj.jumpdelta
Description¶
Info
For Scrollbar objects only.
The amount to increment or decrement a Scrollbar indicator's position when the user clicks ahead or behind the moveable element.
Default is 20% of the range between the maxvalue
and minvalue
property values.
Type¶
Number
justify¶
controlObj.justify
Description¶
The justification of text in StaticText and EditText controls.
One of:
"left"
(default)"center"
"right"
Note
Justification only works if the value is set on creation, using a resource specification or creation parameters.
Type¶
String
location¶
controlObj.location
Description¶
A Point object describing the location of the element as an array, [x, y]
, representing the coordinates of the upper left corner of the element. These are screen coordinates for Window
elements, and parent-relative coordinates for other elements.
The location
is defined as [bounds.x, bounds.y]
.
By default, location
is undefined
until the parent container's layout manager is invoked.
Type¶
maximumSize¶
controlObj.maximumSize
Description¶
A Dimension object that specifies the maximum height and width for an element.
The default is 50 pixels less than the screen size in each dimension. In Windows, this can occupy the entire screen; you must define a maximumSize
to be large enough for your intended usage.
Type¶
minimumSize¶
controlObj.minimumSize
Description¶
A Dimension object that specifies the minimum height and width for an element. Default is [0,0]
.
Type¶
maxvalue¶
controlObj.maxvalue
Description¶
The maximum value that the value
property can have.
- If
maxvalue
is reset less thanvalue
,value
is reset tomaxvalue
. - If
maxvalue
is reset less thanminvalue
,minvalue
is reset tomaxvalue
.
Type¶
Number
minvalue¶
controlObj.minvalue
Description¶
The minimum value that the value
property can have.
- If
minvalue
is reset greater thanvalue
,value
is reset tominvalue
. - If
minvalue
is reset greater thanmaxvalue
,maxvalue
is reset tominvalue
.
Type¶
Number
parent¶
controlObj.parent
Description¶
The immediate parent object of this element.
Type¶
Control Object. Read only.
preferredSize¶
controlObj.preferredSize
Description¶
A Dimension object used by layout managers to determine the best size for each element. If not explicitly set by a script, value is established by the user-interface framework in which ScriptUI is employed, and is based on such attributes of the element as its text, font, font size, icon size, and other user-interface framework-specific attributes.
A script can explicitly set preferredSize
before the layout manager is invoked in order to establish an element size other than the default. To set a specific value for only one dimension, specify the other dimension as -1
.
Type¶
properties¶
controlObj.properties
Description¶
An object that contains one or more creation properties of the element (properties used only when the element is created).
Type¶
Object
selected¶
controlObj.selected
Description¶
Info
For ListItem objects only.
- When
true
, the item is part of theselection
for its parent list. - When
false
, the item is not selected.
Set to true
to select this item in a single-selection list, or to add it to the selection array for a multi-selection list.
Type¶
Boolean
selection¶
controlObj.selection
Description¶
Info
For ListBox objects only.
For a ListBox, an array of ListItem objects for the current selection in a multi-selection list. Setting this value causes the selected item to be highlighted and to be scrolled into view if necessary. If no items are selected, the value is null
. Set to null
to deselect all items.
The value can also change because the user clicked or double-clicked an item, or because an item was removed with remove() or removeAll(). Whenever the value changes, the onChange callback is called. If the value is changed by a double click, calls the onDoubleClick callback.
You can set the value using the index of an item or an array of indices, rather than object references. If set to an index value that is out of range, the operation is ignored. When set with index values, the property still returns object references.
- If you set the value to an array for a single-selection list, only the first item in the array is selected.
- If you set the value to a single item for a multi-selection list, that item is added to the current selection.
Type¶
Array of ListItem objects
selection¶
controlObj.selection
Description¶
Info
For DropDownList, or TreeView objects only.
The currently selected ListItem object.
Setting this value causes the selected item to be highlighted and to be scrolled into view if necessary. If no item is selected, the value is null
. Set to null
to deselect all items.
The value can also change because the user clicked on an item, or because an item was removed with remove() or removeAll().
Whenever the value changes, the onChange callback is called.
You can set the value using the index of an item or an array of indices, rather than object references. If set to an index value that is out of range, the operation is ignored. When set with an index value, the property still returns an object reference.
Type¶
ListItem
shortcutKey¶
controlObj.shortcutKey
Description¶
The key sequence that invokes the onShortcutKey callback for this element (in Windows only).
Type¶
String
size¶
controlObj.size
Description¶
A Dimension object that defines the actual dimensions of an element.
Initially undefined
, and unless explicitly set by a script, it is defined by a LayoutManager object.
Although a script can explicitly set size before the layout manager is invoked to establish an element size other than the preferredSize
or the default size, this is not recommended.
Defined as [bounds.width, bounds.height]
.
Type¶
Dimension object
stepdelta¶
controlObj.stepdelta
Description¶
The amount by which to increment or decrement a Scrollbar element's position when the user clicks a stepper button.
Type¶
Number
subitems¶
controlObj.subitems
Description¶
Info
For ListItem objects only.
When the parent is a multi-column ListBox, the ListItem.text and ListItem.image values describe the label in the first column, and this specifies additional labels for that row in the remaining columns.
This contains an array of JavaScript objects, whose length is one less than the number of columns. Each member specifies a label in the corresponding column, with the first member (subitems[0]
) describing the label in the second column.
Properties¶
Each object has two properties, of which one or both can be supplied:
Property | Type | Description |
---|---|---|
text |
String | A localizable display string for this label. |
image |
Image | An Image object for this label. |
Type¶
Array
text¶
controlObj.text
Description¶
The title, label, or displayed text. Ignored for containers of type group
.
For controls, the meaning depends on the control type. Buttons use the text
as a label, for example, while edit fields use the text to access the content.
For ListItem objects, this is the display string for the list choice. If the parent is a multi-column list box, this is the display string for the label in the first column, and labels for further columns are specified in the subitems array. See Creating multi-column lists.
This is a localizable string: see Localization in ScriptUI objects.
Type¶
String
textselection¶
controlObj.textselection
Description¶
The currently selected text in a control that displays text, or the empty string if there is no text selected.
Setting the value replaces the current text selection and modifies the value of the text
property. If there is no current selection, inserts the new value into the text
string at the current insertion point. The textselection
value is reset to an empty string after it modifies the text
value.
Note
Setting the textselection
property before the EditText control's parent Window exists is an undefined operation.
Type¶
String
title¶
controlObj.title
Description¶
Info
For DropDownList, FlashPlayer, IconButton, Image, or TabbedPanel objects only.
A text label for the element. The title can appear to the left or right of the element, or above or below it, or you can superimpose the title over the center of the element. The placement is controlled by the titleLayout value.
Type¶
String
titleLayout¶
controlObj.titleLayout
Description¶
Info
For DropDownList, FlashPlayer, IconButton, Image, or TabbedPanel objects only.
For a control with a title value, the way the text label is shown in relation to the element.
Properties¶
Property | Type | Description |
---|---|---|
alignment |
Array or Numbers | The position of the title relative to the element, an array of [horizontal_alignment, vertical_alignment]. For possible alignment values, see alignment. Note that fill is not a valid alignment value for either horizontal or vertical alignment in this context. |
characters |
Number | If 1 or greater, reserves a title width wide enough to hold the specified number of "X" characters in the font for this element. If 0, the title width is calculated based on the value of the title property during layout operations. |
spacing |
Number | 0 or greater. The number of pixels separating the title from the element. |
margins |
Array of Numbers, [left, top, right, bottom] |
The number of pixels separating each edge of an element and the visible content within that element. This overrides the default margins. |
justify |
String | One of "left" , "center" , or "right" , how to justify the text when the space allocated for the title width is greater than the actual width of the text. |
truncate |
String | If "middle" or "end" , defines where to remove characters from the text and replace them with an ellipsis ("...") if the specified title does not fit within the space reserved for it. If "none" , and the text does not fit, characters are removed from the end, without any replacement ellipsis character. |
Type¶
Object
type¶
controlObj.type
Description¶
Contains the type name of the element, as specified on creation.
- For
Window
objects, one of the type names window, palette, or dialog. - For
controls
, the type of the control, as specified in the add method that created it.
Type¶
String. Read only.
value¶
controlObj.value
Description¶
Info
For Checkbox or RadioButton objects only.
true
if the control is in the selected or set state, false
if it is not.
Type¶
Boolean
value¶
controlObj.value
Description¶
The current position of the indicator. If set to a value outside the range specified by minvalue and maxvalue, it is automatically reset to the closest boundary.
Type¶
Number
visible¶
controlObj.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¶
controlObj.window
Description¶
The Window that contains this control.
Type¶
Window object. Read only.
windowBounds¶
controlObj.windowBounds
Description¶
A Bounds object that contains the bounds of this control in the containing window's coordinates. Compare to this control object's .bounds
property, in which coordinates are relative to the immediate parent container.
Type¶
Bounds object. Read only.
function_name¶
controlObj.function_name
Description¶
For the FlashPlayer control, a function definition for a callback from the Flash ActionScript environment.
There are no special naming requirements, but the function must take and return only the supported data types:
- Array
- Boolean
- Null
- Number
- Object
- String
- undefined
Note
The ActionScript class
and date
objects are not supported as parameter values.
Type¶
Function
Control object functions¶
The following table shows the methods defined for each element type, and for specific control types as indicated.
addEventListener()¶
controlObj.addEventListener(eventName, handler[, capturePhase=false]);
Description¶
Registers an event handler for a particular type of event occurring in this control.
Parameter¶
Parameter |
Type |
Description |
---|---|---|
|
String |
The event name string. Predefined event names include:
|
|
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, an object of the UIEvent base class. See Registering event listeners for windows or controls. |
|
Boolean |
Optional. When |
Returns¶
Nothing
dispatchEvent()¶
controlObj.dispatchEvent(eventObj)
Description¶
Simulates the occurrence of an event in this target. A script can create an event object for a specific event, using ScriptUI.events.createEvent(), and pass it to this method to start the event propagation for the event.
Parameters¶
Parameter | Type | Description |
---|---|---|
eventObj |
Object | An object of the 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.
hide()¶
controlObj.hide()
Description¶
Hides this container or control. 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.
Returns¶
Nothing
notify()¶
controlObj.notify([event])
Description¶
Sends a notification message, simulating the specified user interaction event.
Parameters¶
Parameter |
Type |
Description |
---|---|---|
|
String |
Optional. The name of the control event handler to call. One of:
By default, simulates the onChange event for an EditText control, an onClick event for controls that support that event. |
Returns¶
Nothing
removeEventListener()¶
controlbj.removeEventListener(eventName, handler[, capturePhase]);
Description¶
Unregisters an event handler for a particular type of event occurring in this control. All arguments must be identical to those that were used to register the event handler.
Parameters¶
Parameter | Type | Description |
---|---|---|
eventName |
String | The event name. |
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()¶
controlObj.show()
Description¶
Shows this container or control.
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.
Returns¶
Nothing
toString()¶
listItemObj.toString()
Description¶
Info
For ListItem objects only.
Retrieves the value of this item's text property as a string.
Returns¶
String
valueOf()¶
listItemObj.valueOf()
Description¶
Info
For ListItem objects only.
Retrieves the index number of this item in the parent list's items array.
Returns¶
Number
List control object functions¶
The following table shows the methods defined for list objects only.
add()¶
listObj.add(type, text[, index=listObj.numItems])
Description¶
Info
For ListBox, DropDownList, or TreeView objects only.
Adds an item
to the items array at the given index.
Parameters¶
Parameter |
Type |
Description |
---|---|---|
|
String |
The type of item to add. One of:
|
|
String |
The localizable text label for the item. |
|
Number |
Optional. The index into the current item list after which this item is inserted. If not supplied, or greater than the current list length, the new item is added at the end. |
Returns¶
Item object for type = "item"
, or null
for type = "separator"
.
find()¶
listObj.find(text)
Description¶
Info
For ListBox, DropDownList, or TreeView objects only.
Looks in this object's items
array for an item object with the given text
value.
Parameters¶
Parameter | Type | Description |
---|---|---|
text |
String | The text of the item to find. |
Returns¶
The ListItem object if found; otherwise null
.
remove()¶
containerObj.remove(index)
containerObj.remove(text)
containerObj.remove(child)
Description¶
- For containers (Panel, Group): removes the specified child control from the container's
children
array. - For ListBox, DropDownList, or TreeView objects: removes the specified item from this object's items array.
No error results if the item does not exist.
Parameters¶
Parameter | Type | Description |
---|---|---|
index , text , child |
Number of String or Control object | The item or child to remove, specified by 0 -based index, text value, or as a control object. |
Returns¶
Nothing
removeAll()¶
listObj.removeAll()
Description¶
Info
For ListBox, DropDownList, or TreeView objects only.
Removes all items from the object's items
array.
Returns¶
Nothing
revealItem()¶
listObj.revealItem(item)
Description¶
Info
For ListBox objects only.
Scrolls the list to make the specified item visible, if necessary.
Parameters¶
Parameter | Type | Description |
---|---|---|
item |
Control object | The item or child to reveal, a control object. |
Returns¶
Nothing
FlashPlayer control functions¶
Info
For FlashPlayer objects only.
Limitations¶
There are limitations on how these functions can be used to control playback of Flash movies:
- Do not use stopMovie() and playMovie() to suspend and subsequently resume or restart an SWF file produced by Flex™.
- The stopMovie() and playMovie() sequence does not make sense for some SWF files produced by Flash Authoring, depending on the exact details of how they were implemented. The sequence may not correctly reset the file to the initial state (when the
rewind
argument to playMovie() istrue
) nor suspend then resume the execution of the file (whenrewind
isfalse
). - Using stopMovie() from the player's hosting environment has no effect on an SWF file playing in a ScriptUI Flash Player element. It is, however, possible to produce an SWF using Flash Authoring that can stop itself in response to user interaction.
- Do not call playMovie() when an SWF file is already playing.
invokePlayerFunction()¶
flashPlayerObj.invokePlayerFunction(fnName, [arg1[,...argN]] )
Description¶
Invokes an ActionScript function defined in the Flash application.
Parameters¶
Parameter |
Type |
Description |
---|---|---|
|
String |
The name of a Flash ActionScript function that has been registered with the ExternalInterface object by the currently loaded SWF file; see Calling ActionScript functions from a ScriptUI script. |
|
Any |
Optional. One or more arguments to pass through to the function, of these types:
|
Returns¶
The result of the invoked function, which must be one of the allowed types. The ActionScript class
and date
objects are not supported as return values.
loadMovie()¶
flashPlayerObj.loadMovie(file)
Description¶
Loads a movie into the Flash Player, and begins playing it. If you do not specify an associated movie file when creating the control, you must use this function to load one.
Parameters¶
Parameter | Type | Description |
---|---|---|
file |
File object | The SWF file to load. |
Returns¶
Nothing
playMovie()¶
flashPlayerObj.playMovie(rewind)
Description¶
Restarts a movie that has been stopped.
Warning
Do not call when a movie is currently playing.
Parameters¶
Parameter | Type | Description |
---|---|---|
rewind |
Boolean | When true , restarts the movie from the beginning; otherwise, starts playing from the point where it was stopped. |
Returns¶
Nothing
stopMovie()¶
flashPlayerObj.stopMovie()
Description¶
Halts playback of the current movie.
Note
Does not work when called from the player's hosting environment.
Returns¶
Nothing
Control event-handling callbacks¶
The following events are signalled in certain types of controls. To handle the event, define a function with the corresponding name in the control object. Handler functions take no arguments and have no expected return values; see Defining behavior with event callbacks and listeners.
onActivate¶
Called when the user gives a control the keyboard focus by clicking it or tabbing into it.
onClick¶
Called when the user clicks one of the following control types:
onChange¶
Called when the user finishes making a change in one of the following control types:
- DropDownList
- EditNumber
- EditText
- ListBox
- Scrollbar
- Slider
-
For EditNumber and EditText controls, called only when the change is complete-that is, when focus moves to another control, or the user types
ENTER
.- The exact behavior depends on the creation parameter
enterKeySignalsOnChange
; see the EditText description.
- The exact behavior depends on the creation parameter
- For a Slider or Scrollbar, called when the user has finished dragging the position marker or has clicked the control.
- For a ListBox, DropDownList or TreeView control, called whenever the selection property changes.
- This can happen when a script sets the property directly or removes a selected item from the list, or when the user changes the selection.
onChanging¶
Called for each incremental change in one of the following control types:
- EditNumber
- EditText
- Scrollbar
-
For EditNumber and EditText controls, called for each keypress while the control has focus.
- For a Slider or Scrollbar, called for any motion of the position marker.
onCollapse¶
Called when the user collapses (closes) a node in a TreeView control.
The parameter to this function is the ListItem node object that was collapsed.
onDeactivate¶
Called when the user removes keyboard focus from a previously active control by clicking outside it or tabbing out of it.
onDoubleClick¶
Called when the user double clicks an item in a ListBox control.
The list's selection
property is set to the clicked item.
onEnterKey¶
Warning
This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!
Called when the user presses return or enter in a EditText control.
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. Handler takes one argument, a DrawState object.
onExpand¶
Called when the user expands (opens) a node in a TreeView control. The parameter to this function is the ListItem node object that was expanded.
onShortcutKey¶
Info
For Windows objects only.
Called when a shortcut-key sequence is typed that matches the shortcutKey value for an element in the active window.
DrawState object¶
A helper object that describes an input state at the time of the triggering onDraw event. Contains properties that report whether the current control has the input focus, and the particular mouse button and key-press state.
There is no object constructor.
DrawState object properties¶
The object contains the following read-only properties:
Property | Type | Behaviour |
---|---|---|
altKeyPressed |
Boolean | When true , the ALT key was pressed. (In Windows OS only.) |
capsLockKeyPressed |
Boolean | When true , the CAPSLOCK key was pressed. |
cmdKeyPressed |
Boolean | When true , the CMD key was pressed. (In Mac OS only.) |
ctrlKeyPressed |
Boolean | When true , the CTRL key was pressed. |
hasFocus |
Boolean | When true , the control containing this object has the input focus. |
leftButtonPressed |
Boolean | When true , the left mouse button was pressed. |
middleButtonPressed |
Boolean | When true , the middle mouse button was pressed. |
mouseOver |
Boolean | When true , the cursor position was within the bounds of the control containing this object. |
numLockKeyPressed |
Boolean | When true , the NUMLOCK key was pressed. |
optKeyPressed |
Boolean | When true , the OPT key was pressed. (In Mac OS only.) |
rightButtonPressed |
Boolean | When true , the right mouse button was pressed. |
shiftKeyPressed |
Boolean | When true , the SHIFT key was pressed. |