Checkbox (SUI)

A dual-state control showing a box that has a checkmark when the value is true, and is empty when the value is false.

Calls the onClick() callback if the control is clicked or if its notify() method is called.

Methods:

addEventListener, dispatchEvent, hide, notify, onActivate, onClick, onDeactivate, onDraw, onShortcutKey, removeEventListener, show

Objects:

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

Property Listing

Property

Type

Access

Description

active

Boolean

read/write

True if this element is active.

An active control is the one with keyboard focus—that is, the one that accepts keystrokes, or in the case of a Button, is selected when the user types Return or Enter in Windows, or the space bar in Mac OS.

alignment

String

read/write

The alignment style for this element. If defined, this value overrides the alignChildren setting for the parent container.

This can be a single string, which indicates the alignment for the orientation specified in the parent container, or an array of two strings, indicating both the horizontal and vertical alignment (in that order). Allowed values depend on the orientation value of the parent container. They are not case sensitive. For orientation=row:top, bottom, fill For orientation=column: left, right, fill For orientation=stack:top, bottom, left, right, fill

bounds

Bounds (SUI)

read/write

The boundaries of the element, in parent-relative coordinates.

Setting an element's size or location changes its bounds property, and vice-versa.

characters

Number

read/write

A number of characters for which to reserve space when calculating the preferred size of the element.

children

Array of Object

readonly

An array of child elements.

enabled

Boolean

read/write

True if this element is enabled.

An enabled element can accept input, according to its type. When false, control elements do not accept input, and all types of elements have a dimmed appearance.

graphics

ScriptUIGraphics (SUI)

readonly

The graphics object that can be used to customize the element's appearance, in response to the onDraw() event.

helpTip

String

read/write

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

indent

Number

read/write

The number of pixels to indent the element during automatic layout.

Applies for column orientation and left alignment, or row orientation and top alignment.

justify

String

read/write

The default text justification style for child text elements.

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

location

Point (SUI)

read/write

The upper left corner of this element relative to its parent.

The location is defined as [bounds.x, bounds.y]. Setting an element's location changes its bounds property, and vice-versa.

maximumSize

Dimension (SUI)

read/write

The maximum height and width to which the element can be resized.

minimumSize

Dimension (SUI)

read/write

The minimum height and width to which the element can be resized.

parent

 

readonly

The parent element.

preferredSize

Dimension (SUI)

read/write

The preferred size, used by layout managers to determine the best size for each element.

If not explicitly set by a script, value is established by the UI 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 UI framework-specific attributes.A script can explicitly set this value before the layout manager is invoked in order to establish an element size other than the default.

properties

Object

read/write

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

A CheckBox object has no creation properties. The third argument to the add() method that creates it is the text to be displayed.

shortcutKey

String

read/write

The key sequence that invokes the onShortcutKey() callback for this element (in Windows only).

size

Dimension (SUI)

read/write

The current dimensions of this element.

Initially undefined, and unless explicitly set by a script, it is defined by a LayoutManager . 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, but this is not recommended. Defined as [bounds.width, bounds.height]. Setting an element's size changes its bounds property, and vice-versa.

text

String

read/write

The text to display, a localizable string.

type

String

readonly

The element type; "checkbox".

value

Boolean

read/write

The selection state of the control.

When true, the control is in the selected or set state and displays the check mark. When false, shows an empty box.

visible

Boolean

read/write

True if this element is shown, false if it is hidden.

When a container is hidden, its children are also hidden, but they retain their own visibility values, and are shown or hidden accordingly when the parent is next shown.

window

Window (SUI)

readonly

The window that this element belongs to.

windowBounds

Bounds (SUI)

readonly

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

Method Listing

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

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

Parameter

Type

Description

eventName

String

The name of the event.

Event names are listed in the JavaScript Tools Guide.

handler

Function

The function that handles the event.

This can be the name of a function defined in the extension, or a locally defined handler function to be executed when the event occurs. A handler function takes one argument, the UIEvent object.

capturePhase

Boolean

When true, the handler is called only in the capturing phase of the event propagation.

Default is false, meaning that the handler is called in the bubbling phase if this object is an ancestor of the target, or in the at-target phase if this object is itself the target.

(default: false)

Event (SUI) dispatchEvent ()

Simulates the occurrence of an event in this target.

A script can create a UIEvent object for a specific event and pass it to this method to start the event propagation for the event.

undefined hide ()

Hides this element.

undefined notify ([eventName:String])

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

Parameter

Type

Description

eventName

String

The name of the control event handler to call.

One of: onClick, onChange, onChanging. By default, simulates the onChange event for an edittext control, an onClick event for controls that support that event.

undefined onActivate ()

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

Called when the user gives the control the keyboard focus by clicking it or tabbing into it.

undefined onClick ()

An event-handler callback function, called when the element has been clicked.

undefined onDeactivate ()

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

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

undefined onDraw ()

An event-handler callback function, called when the window 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.

undefined onShortcutKey ()

An event-handler callback function, called when the element's shortcutKey sequence is typed in the active window.

In Windows only.

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

Unregisters an event handler for a particular type of event occuring in this element.

All arguments must be identical to those that were used to register the event handler.

Parameter

Type

Description

eventName

String

The name of the event.

handler

Function

The function that handles the event.

capturePhase

Boolean

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

(default: false)

undefined show ()

Shows this element.

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.