Group (SUI)

A container for other controls within a window.

A group can specify layout options for its child elements. Hiding a group hides all its children. Making it visible makes visible those children that are not individually hidden.

Go to Property Listing | Method Listing

Methods:

add, addEventListener, dispatchEvent, hide, onDraw, remove, removeEventListener, show

Objects:

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

Property Listing

Property	Type	Access	Description
alignChildren	String	read/write	Tells the layout manager how unlike-sized children of this container should be aligned within a column or row. Order of creation determines which children are at the top of a column or the left of a row; the earlier a child is created, the closer it is to the top or left of its column or row. If defined, alignment for a child element overrides the alignChildren setting for the parent container. See alignment property for values.
alignment	String	read/write	The alignment style for 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.
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.
layout	LayoutManager (SUI)	read/write	The layout manager for this container. The first time a container object is made visible, ScriptUI invokes this layout manager by calling its layout() function. Default is an instance of the LayoutManager class that is automatically created when the container element is created.
location	Point (SUI)	read/write	The upper left corner of 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.
margins	Number	read/write	The number of pixels between the edges of a container and the outermost child elements. You can specify different margins for each edge of the container. The default value is based on the type of container, and is chosen to match the standard Adobe UI guidelines.
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.
orientation	String	read/write	The layout orientation of children in a container. Interpreted by the layout manager for the container. The default LayoutManager Object accepts the (case-insensitive) values row, column, or stack. For window and panel, the default is column, and for group the default is row. The allowed values for the container’s alignChildren and its children’s alignment properties depend on the orientation.
parent		readonly	The 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 control (properties used only when the element is created). A Group object has no creation properties.
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.
spacing	Number	read/write	The number of pixels separating one child element from its adjacent sibling element. Because each container holds only a single row or column of children, only a single spacing value is needed for a container. The default value is based on the type of container, and is chosen to match standard Adobe UI guidelines.
type	String	readonly	The element type; "group".
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

Object add (type:String, [bounds:BoundsSUI], [text:String], [properties:Object])

Adds a child element to this container.

Creates and returns a new control or container object and adds it to the children of this group.

Parameter	Type	Description
type	String	The type of the child element, as specified for the type property. Control types are listed in the JavaScript Tools Guide.
bounds	Bounds (SUI)	A bounds specification that describes the size and position of the new control or container, relative to its parent. If supplied, this value creates a new Bounds object which is assigned to the new object’s bounds property.
text	String	The text or label, a localizable string. Initial text to be displayed in the control as the title, label, or contents, depending on the control type. If supplied, this value is assigned to the new object’s text property.
properties	Object	An object that contains one or more creation properties of the new child (properties used only when the element is created). The creation properties depend on the element type. See properties property of each control type.

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

Registers an event handler for a particular type of event occuring in this 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)

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

An event-handler callback function, called when the group 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 remove (what:VariesSUI)

Removes the specified child control from this group's children array.

No error results if the child does not exist.

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

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

Unregisters an event handler for a particular type of event occuring in this 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)