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> } ]);
|
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 |
|
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 |
|
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.
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.
checkbox¶
Class Name: Checkbox
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.
To add to a window w:
w.add ("checkbox" [, bounds, text, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The text displayed in the control. |
|
Optional. An object that contains any of the following properties:
|
dropdownlist¶
Class Name: DropDownList
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.
To add to a window w:
w.add( "dropdownlist", bounds [, items, {creation_properties}] );
|
Optional. The control’s position and size. |
|
Optional. Supply this argument or the
|
|
Optional. Supply this argument or the items argument, not both. This form is most useful for elements defined using Resource specifications. An object that contains the following property:
|
edittext¶
Class Name: EditText
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.
To add to a window w:
w.add ("edittext" [, bounds, text, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The text displayed in the control. |
|
Optional. An object that contains any of the following properties:
|
flashplayer¶
Class Name: FlashPlayer
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.
To add to a window w:
w.add ("flashplayer" [, bounds, movieToLoad, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. A path or URL string or File object for the SWF file to load into the player. |
|
Optional. An object that contains any of the following properties:
|
group¶
Class Name: Group
A container for other controls. Containers have additional properties that control the children; see Container properties. Hiding a group hides all its children. Making it visible makes visible those children that are not individually hidden.
To add to a window w:
w.add ("group" [, bounds, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. An object that contains any of the following properties:
|
image¶
Class Name: Image
Displays an icon or image.
To add to a window w:
w.add ("image" [, bounds, icon, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The named resource for the icon or family of icons displayed in the button control, or a pathname or File object for an image file. Images must be in PNG format. |
|
Optional. An object that contains the following properties:
|
item¶
Class Name: Array of ListItem
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
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.
To add to a window w:
w.add ("listbox", bounds [, items, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. An array of strings for the text of each list item.
A ListItem object is created for each item. Supply this argument,
or the items property in |
|
Optional. An object that contains any of the following properties:
|
panel¶
Class Name: Panel
A container for other types of controls, with an optional frame. Containers have additional properties that control the children; see Container properties. Hiding a panel hides all its children. Making it visible makes visible those children that are not individually hidden.
To add to a window w:
w.add ("panel" [, bounds, text, {creation_properties}]);
|
Optional. The element’s position and size. A panel whose width is 0 appears as a vertical line. A panel whose height is 0 appears as a horizontal line. |
|
Optional. The text displayed in the border of the panel. |
|
Optional. An object that contains any of the following properties:
|
progressbar¶
Class Name: Progressbar
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.
To add to a window w:
w.add ("progressbar" [, bounds, value, minvalue, maxvalue, creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The initial position of the progress indicator. Default is 0. |
|
Optional. The minimum value that the |
|
Optional. The maximum value that the |
|
Optional. An object that contains the following property:
|
scrollbar¶
Class Name: Scrollbar
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.
|
Contains the current position of the scrollbar’s indicator
within the scrolling area, within the range of |
|
Determines the scrolling unit for the up or down arrow. Default is 1. |
|
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
|
To add to a window w:
w.add ("scrollbar" [, bounds, value, minvalue, maxvalue, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The initial position of the scroll indicator. Default is 0. |
|
Optional. The minimum value that the |
|
Optional. The maximum value that the |
|
Optional. An object that contains the following property:
|
slider¶
Class Name: Slider
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.
To add to a window w:
w.add ("slider" [, bounds, value, minvalue, maxvalue, {creation_properties}]);
|
Optional. The control’s position and size. |
|
Optional. The initial position of the scroll indicator. Default is 0. |
|
Optional. The minimum value that the |
|
Optional. The maximum value that the |
|
Optional. An object that contains the following property:
|
statictext¶
Class Name: StaticText
A text field that the user cannot change.
To add to a window w:
w.add ("statictext" [, bounds, text, {creation_properties}]);
|
Optional. The element’s position and size. |
|
Optional. The text displayed in the control. |
|
Optional. An object that contains any of the following properties:
|
tab¶
Class Name: Tab
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 properties. Hiding a panel hides all its children. Making it visible makes visible those children that are not individually hidden.
To add a tab to a tabbed panel t in window w:
w.t.add ("tab" [, bounds, text, {creation_properties}]);
|
Not used, pass |
|
Optional. The text displayed in the tab. |
|
Optional. An object that contains any of the following properties:
|
tabbedpanel¶
Class Name: TabbedPanel
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 properties. 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
ref:control-event-onChange notification.
To add to a window w:
w.add ("tabbedpanel" [, bounds, text, {creation_properties}]);
|
Optional. The element’s position and size. This determines the sizes and positions of the tab children. |
|
Ignored. |
|
Optional. An object that contains any of the following properties:
|
treeview¶
Class Name: TreeView
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.
To add to a window w:
w.add ("treeview" [, bounds, items, {creation_properties}])
|
Optional. The control’s position and size. |
|
Optional. An array of strings for 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 |
|
Optional. An object that contains any of the following 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 properties for properties that apply to container elements (controls of type panel, tabbedpanel, tab, and group).
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 ENTER in Windows, or presses the spacebar in Mac OS.
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 in the parent container. For orientation = 'row':
top
center (default)
bottom
fill
For orientation = 'column':
left
center (default)
right
fill
For orientation = 'stack':
top
right
bottom
center (default)
left
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 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.
Setting an element’s size or location changes its bounds property,
and vice-versa.
characters¶
Type: Number
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.
checked¶
Type: Boolean
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.
columns¶
Type: Object
For listbox objects only. A JavaScript object with two read-only properties whose values are set by the creation parameters:
|
An array of column title strings, whose length matches the number of columns specified at creation. |
|
An array of column widths, whose length matches the number of columns specified at creation. |
enabled¶
Type: Boolean
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. A disabled ListItem is not selectable in a listbox, dropdownlist or treeview list.
expanded¶
Type: Boolean
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.
graphics¶
Type: Object
A ScriptUIGraphics object that can be used to customize the control’s appearance, in response to the onDraw event.
helpTip¶
Type: String
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.
icon¶
Type: String or File
Deprecated. Use Image instead.
image¶
Type: Object
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.
indent¶
Type: Number
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.
index¶
Type: Number
For ListItem objects only. The index of this item in the items
collection of its parent list control. Read only.
items¶
Type: Array of Object
For a list object (listbox, dropdownlist or treeview list), a collection
of ListItem objects for the items in the list. Access by 0-based index. To
obtain the number of items in the list, use items.length. Read only.
itemSize¶
Type: Dimension
For a list object (listbox, dropdownlist or treeview list),
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
jumpdelta¶
Type: Number
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.
justify¶
Type: String
The justification of text in static text and edit text 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.
location¶
Type: Point
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]. Setting an
element’s location changes its bounds property, and vice-versa. By
default, location is undefined until the parent container’s layout
manager is invoked.
maximumSize¶
Type: Dimension
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.
minimumSize¶
Type: Dimension
A Dimension object that specifies the minimum height and width for
an element. Default is [0,0].
maxvalue¶
Type: Number
The maximum value that the value property can have.
If
maxvalueis reset less thanvalue,valueis reset tomaxvalue.If
maxvalueis reset less thanminvalue,minvalueis reset tomaxvalue.
minvalue¶
Type: Number
The minimum value that the value property can have.
If
minvalueis reset greater thanvalue,valueis reset tominvalue.If
minvalueis reset greater thanmaxvalue,maxvalueis reset tominvalue.
parent¶
Type: Object
The immediate parent object of this element. Read only.
preferredSize¶
Type: Dimension
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.
properties¶
Type: Object
An object that contains one or more creation properties of the element (properties used only when the element is created).
selected¶
Type: Boolean
For ListItem objects only. When true, the item is part of the selection
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.
selection¶
(For ListBox only)
Type: Array of ListItem
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.
selection¶
(For DropDownList and TreeView only)
Type: ListItem
For a dropdownlist or treeview list object, 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.
shortcutKey¶
Type: String
The key sequence that invokes the onShortcutKey callback for this element (in Windows only).
size¶
Type: Dimension
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.
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]. Setting an element’s
size changes its bounds property, and vice-versa.
stepdelta¶
Type: Number
The amount by which to increment or decrement a Scrollbar element’s position when the user clicks a stepper button.
subitems¶
Type: Array
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.
Each object has two properties, of which one or both can be supplied:
|
A localizable display string for this label. |
|
An Image object for this label. |
text¶
Type: String
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.
textselection¶
Type: String
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.
title¶
Type: String
For a dropdownlist, FlashPlayer, IconButton, Image, or tabbedpanel 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.
titleLayout¶
Object
For a dropdownlist, FlashPlayer, IconButton, Image, or tabbedpanel with a title value, the way the text label is shown in relation to the element. A JavaScript object with these properties:
|
The position of the title relative to the element, an
array of [horizontal_alignment, vertical_alignment]. For possible
alignment values, see alignment. Note that |
|
A 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 |
|
A number; 0 or greater. The number of pixels separating the title from the element. |
|
An array of numbers, |
|
One of |
|
If |
type¶
Type: String
Contains the type name of the element, as specified on creation.
For
Windowobjects, 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.
Read only.
value¶
Type: Boolean
For a Checkbox or RadioButton, true if the control is in the selected or set state, false if it is not.
value¶
Type: Number
For a Scrollbar or Slider, 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.
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 Window object that contains this control. Read only.
windowBounds¶
Type: Bounds
A Bounds object that contains the bounds of this control in the containing window’s coordinates. Compare Bounds, in which coordinates are relative to the immediate parent container. Read only.
function_name¶
Type: Function
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:
Number |
undefined |
String |
Object |
Boolean |
Array |
Null |
Note
The ActionScript class and date objects are not supported as
parameter values.
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);
|
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, an object of 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 control.
Returns undefined.
dispatchEvent()¶
controlObj.dispatchEvent (eventObj)
|
An object of the UIEvent base class. |
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.
Returns false if any of the registered listeners that handled the event called the event object’s preventDefault() method, true otherwise.
hide()¶
controlObj.hide()
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 undefined.
notify()¶
controlObj.notify([event])
|
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. |
Sends a notification message, simulating the specified user interaction event.
Returns undefined.
removeEventListener()¶
controlbj.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 control. All arguments must be identical to those that were used to register the event handler.
Returns undefined.
show()¶
controlObj.show()
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 undefined.
toString()¶
listItemObj.toString()
For ListItem controls only. Retrieves the value of this item’s text property as a string.
Returns a String.
valueOf()¶
listItemObj.valueOf()
For ListItem controls only. Retrieves the index number of this item in the parent list’s items array.
Returns a Number.
List control object functions¶
The following table shows the methods defined for list objects only.
add()¶
listObj.add (type, text[, index])
|
The type of item to add. One of:
|
|
The localizable text label for the item. |
|
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. |
For list objects (listbox, dropdownlist or treeview) only.
Adds an item to the items array at the given index.
Returns the item control object for type = 'item', or null for
type = 'separator'.
find()¶
listObj.find(text)
text
The text of the item to find.
For list objects (listbox, dropdownlist or treeview) only.
Looks in this object’s items array for an item object with the given text
value.
Returns the item object if found; otherwise, returns null.
remove()¶
containerObj.remove(index)
containerObj.remove(text)
containerObj.remove(child)
|
The item or child to remove, specified by 0-based index, |
For containers (panel, group), removes the specified child control from
the container’s children array.
For list objects (listbox, dropdownlist or treeview) only, removes the specified item from this object’s items array. No error results if the item does not exist.
Returns undefined.
removeAll()¶
listObj.removeAll()
For list objects (listbox, dropdownlist or treeview) only.
Removes all items from the object’s items array.
Returns undefined.
revealItem()¶
listObj.revealItem(item)
|
The item or child to reveal, a control object. |
For listbox only. Scrolls the list to make the specified item visible, if necessary.
Returns undefined.
FlashPlayer control functions¶
These functions apply only to controls of type flashplayer.
Note
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
rewindargument to playMovie() is true) nor suspend then resume the execution of the file (whenrewindis false).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]] )
|
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. |
|
Optional. One or more arguments to pass through to the function, of these types:
|
Invokes an ActionScript function defined in the Flash application.
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)
|
The File object for the SWF file. |
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.
Returns undefined.
playMovie()¶
flashPlayerObj.playMovie(rewind)
|
When true, restarts the movie from the beginning; otherwise, starts playing from the point where it was stopped. |
Restarts a movie that has been stopped.
Note
Do not call when a movie is currently playing.
Returns undefined.
stopMovie()¶
flashPlayerObj.stopMovie()
Halts playback of the current movie.
Note
Does not work when called from the player’s hosting environment.
Returns undefined.
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:
For an EditText control, 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 parameterenterKeySignalsOnChange; see the edittext description.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:
For an EditText control, 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.
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¶
(In Windows 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:
altKeyPressed |
Boolean |
When true, the ALT key was pressed. (In Windows 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. |