uilayout

Classes that assist with laying out a user interface.

User interfaces created using these classes can be displayed as dialogs, added as tabs to a game component editor, or realized into generic containers. Containers can be nested to create complex interface layouts.

See the plug-in authoring kit for examples that use this library.

AbstractContainer( [controls...] )

An AbstractContainer is a base class for other classes in this library. An AbstractContainer manages a list of objects and can realize these objects into a grouping of user interface controls.

When a container is realized, the control objects that have been added to it will be converted into user interface widgets and laid out in a panel or other user interface object. A given container can only be realized once; attempting to realize the container again will throw an exception.

Any kind of object may be added to an AbstractContainer. Interface components are added unchanged, and other objects are converted into an interface component when the container is realized. The standard conversions are as follows:

AbstractContainers are converted into a control or group of controls by calling the container's realize function (in fact, this works for any object with a realize function)
icons and images are converted into icon labels
other kinds of objects are first converted to a string by calling their toString function, and then that string is added as a label control

Some kinds of containers can have controls added with "hints" that affect how the control is laid out. Controls are added with hints using the place method. Adding controls using the add method will add it with a default hint (null).

controls an optional list of controls that will be added to the container

AbstractContainer.realized read-only

This read-only property is true if this container was previously realized, which means that realizing it again will throw an exception.

true is this container has been realized

AbstractContainer.title

This property defines a title for the container. If a title is set, the realized UI panel will be placed in a border titled using this text. Some types of container may ignore this setting.

a title string to use for the container

AbstractContainer.editorTabWrapping

This boolean property affects how a container will be added to a component editor when calling addToEditor. If true (the default), then the container will be nested inside of a panel. The panel will be laid out with BorderLayout and the container will be placed in the NORTH position. This produces a more consistent layout by preventing the container from expanding to cover the entire extent of the tab.

AbstractContainer.editorTabScrolling

This boolean property affects how a container will be added to a component editor when calling addToEditor. If true, then the container will be wrapped in a scroll pane that enables vertical scrolling. If the editor is not tall enough to display all of the controls in a tab, a scroll bar will automatically appear to allow the user to scroll to unreachable controls. If false (the default), then the controls will be clipped to the bottom of their tab.

AbstractContainer.prototype.realize() [abstract]

Convert this container into a user interface component that groups together the controls that have been added to it. (Typically the returned object is a swing.JPanel, but this is not required.)

This method is not defined in AbstractContainer and will throw an exception if called. Sublasses must override this method.

AbstractContainer.prototype.add( [control...] )

Adds zero or more control objects to this container. The added objects will all be given a default hint value that allows this container to lay the control out as it sees fit.

control ... controls to be added with the component's default placement rules

returns this container

AbstractContainer.prototype.place( [control, hint...] )

Adds zero or more control objects to this container, using hints to control the layout. Not all AbstractContainers use hints.

control, hint ... pairs of controls to be added and their associated placement hints

returns this container

AbstractContainer.prototype.getControl( index )

Returns the control at position index in the list of controls maintained by this container.

index the index of the control

returns the requested control or throws an error if index is invalid

AbstractContainer.prototype.getHint( index )

Returns the hint for the control at position index in the list of controls maintained by this container.

index the index of the control

returns the requested control hint or throws an error if index is invalid

AbstractContainer.prototype.getControlCount()

Returns the number of controls in this container.

returns the number of added controls

AbstractContainer.prototype.addToEditor( editor, [title], [heartbeatListener], [fieldPopulationListener], [tabIndex] )

Realizes this container as a user interface control and adds it to a component editor as a new tab.

`editor`	the `StrangeEonsEditor` to add this to
`title`	an optional title for the tab that will be added
`heartbeatListener`	an optional function that is called every update heartbeat
`fieldPopulationListener`	an optional function that is called when the controls should be populated with data from the component
`tabIndex`	an optional index at which to insert the stack in the list of tabs

returns the user interface element that contains the converted stack controls

AbstractContainer.findEditorTabPane( editor ) static

Returns the JTabbedPane instance that houses the primary editing controls for editor. Returns null if an appropriate tab pane cannot be found.

editor the StrangeEonsEditor to search for a tab pane

AbstractContainer.prototype.createDialog( [title], [okText], [cancelText], [icon], [modal] ) {

Realizes this container and places the resulting component in a dialog box. The returned dialog box can be displayed by calling its showDialog() method. In addition to the full suite of methods provided by swing.JDialog, the returned dialog box offers the following methods:

int getCloseButton()
Returns the button pressed by the user to close the dialog:

`-1`	dialog still open (possible if modeless), or user closed window
`0`	user pressed Cancel button
`1`	user pressed OK button

JButton getOKButton()
Returns the dialog box's OK button (or null if it doesn't have one).

JButton getCancelButton()
Returns the dialog box's Cancel button (or null if it doesn't have one).

int showDialog()
Displays the dialog. If the dialog is modeless, the method returns immediately. If it is modal, the script stops until the user closes the dialog, and the returned value indicates the button used to close the dialog (see the description of getCloseButton().

Component getContent()
Return the component that was realized by the container when the dialog was created.

`title`	an optional title for the dialog window
`okText`	optional text to use for the OK button; `null` for default text, "" to hide button
`cancelText`	optional text to use for the Cancel button; `null` for default text, "" to hide button
`icon`	an optional icon that will be placed next to the content (`null` for no icon)
`modal`	optional flag; if `true`, the script stops running until the dialog is closed

returns the new dialog box

AbstractContainer.prototype.test()

Tests the layout of an AbstractContainer by realizing it and displaying the result in a simple dialog.

Row( [control...] ) : AbstractContainer

Creates a new Row container, which organizes controls into a horizontal row. Controls in this container will accept a non-negative numeric hint that adjusts the size of the gap between the hinted control and the previous control. The default hints will provide a gap of 0 for the first control and 1 for subsequent controls. Each unit of gap inserts a small indentation.

control a list of zero or more controls to be added to the new Row

Row.setAlignment( alignment )

Set the alignment of the row within the parent container; left-justified if -1, centered if 0, right-justified if 1.

alignment the alignment value to set

Row.getAlignment()

Returns the alignment setting of the row.

Stack( [control...] ) : AbstractContainer

Creates a new Stack object, which organizes controls into a vertical stack. This container does not use hints.

control a list of zero or more controls to be added to the new Stack

FixedGrid( columns, [controls...] ) : AbstractContainer

Creates a new FixedGrid object, which organizes controls into a simple grid. All cells in a grid column have the same width, and all cells in a grid row have the same height. This container recognizes a single hint, the string "wrap". A component with this hint will end the current row of controls and start a new row with the next control added.

`columns`	the number of column grids
`control`	a list of zero or more controls to be added to the new `Stack`

FixedGrid.getColumns()

Returns the number of columns in this grid.

FixedGrid.setColumns()

Sets the number of columns to use when realizing the container.

Grid( [constraints], [colConstraints], [rowConstraints] ) : AbstractContainer

Creates a new Grid object, which organizes controls using a highly flexible grid. The layout is controlled using strings that describe the desired layout options. See this summary of the the hint string syntax for details.

Example:

 var grid = new Grid();
 grid.place(
     "Name", "",
     textField(), "wrap, span, grow",
     "Ability", "",
     textField( "", 15 ), "grow",
     "Modifier", "",
     textField( "", 10 ), "grow"
 );
 grid.createDialog().showDialog();

`layoutConstraints`	optional global constraints on the layout
`columnConstraints`	optional constraints on the grid columns
`rowConstraints`	optional constraints on the grid rows

returns a new Grid containter

TypeGrid( [hgap], [vgap] ) : AbstractContainer

Creates a new TypeGrid object, which organizes controls similarly to a typewritten page. A TypeGrid is easier to use, but less flexible than, a Grid container. The layout is controlled using strings that describe the desired layout options. The following constraint strings are available:

br	Insert a line break before this control
p	Insert a paragraph break before this control
tab	Align control to a tab stop
hfill	Cause control to fill the available horizontal space
vfill	Cause control to fill the available vertical space (may be used once per container)
left	Align subsequent controls to the left edge of the container (this is the default)
right	Align subsequent controls to the right edge of the container
center	Center subsequent controls horizontally
vtop	Align controls to the top of the container (this is the default)
vcenter	Align controls to the vertical center of the container

Example:

 var typeGrid = new TypeGrid();
 typeGrid.place(
     "<html><b><u>Registration", "center",
     "Name", "p left",
     textField( "", 30 ), "tab hfill",
     "Age", "br",
     textField( "", 3 ), "tab",
     "Gender", "br",
     comboBox( ["Male","Female","Other"] ), "tab"
 );
 typeGrid.createDialog( "Demo", "Register", null, null ).showDialog();

`layoutConstraints`	optional global constraints on the layout
`columnConstraints`	optional constraints on the grid columns
`rowConstraints`	optional constraints on the grid rows

returns a new TypeGrid containter

TabPane( [control...] ) : AbstractContainer

Creates a new TabPane object, which organizes controls into a set of tabs with mutually exclusive visibility. Each control added will be shown on a separate tab. For this reason, the added controls are usually other containers. The hint supplied for each added control will be used as the label for the tab. If no hint is given, a series of dummy names ("Tab 1", "Tab 2", etc.), will be used.

control a list of zero or more controls to be added to the new TabPane

TabPane.smallTabs

If set to true, then the tabbed pane will feature smaller tabs.

Splitter( [verticalSplit], [left], [right] ) : AbstractContainer

Creates a new Splitter object, which creates a panel that separates two controls by a splitter bar that can be dragged to change the relative space that they are allotted.

`verticalSplit`	if `true`, the splitter divides the space into two columns; otherwise it divides the space into two rows
`left`	the first component
`right`	the second component

returns a new Splitter container

Contents