UI Builder Module

Create UI elements by adding SWT controls via script commands to a dynamic GridLayout. Each element allows to provide layout data, which accepts a fairly simple syntax: <coordinates> <horizontal align> <vertical align>

coordinates
Provides X/Y coordinates for elements in the grid where 1/1 denotes the upper left corner. 2/1 would create the element in the second column of the first row. Coordinates may also provide rowSpan/columnSpan information: 1-3/2-3 would create the element spanning columns 1 to 3 in rows 2 to 3. showGrid() adds visual indications to help layouting.
horizontal alignment
  • < ... align left
  • x ... align center
  • > ... align right
  • o ... fill
  • o! ... grab horizontal space (! may be added to any alignment)
vertical alignment
  • ^ ... align top
  • x ... align middle
  • v ... align bottom
  • o ... fill
  • o! ... grab vertical space (! may be added to any alignment)

Most methods of this module deal with SWT components. To access them the code needs to be run in the UI thread. See ui.executeUI() for more information.

Whenever callback code is registered the executing engine is automatically set to be kept alive after script execution. This is required as callback execution needs a script engine.

Method Overview

Method Description
addControl() Add a generic control.
createButton() Create a push button.
createCheckBox() Create a checkbox.
createComboViewer() Create a combo box.
createComparator() Create a comparator (sorter) to be used for combos, lists or tables.
createComposite() Create a new composite.
createDialog() Create a dialog with scripted content.
createGroup() Create a group composite.
createImage() Create an image instance.
createLabel() Create a label.
createLabelProvider() Create a label provider to be used for combos, lists or tables.
createListViewer() Create a list viewer.
createProgressBar() Create a progress bar.
createRadioButton() Create a radio button.
createScrolledComposite() Create a new composite inside of a scrolled composite.
createSeparator() Create a separator.
createTableViewer() Create a table viewer.
createText() Create a single line text input.
createTextBox() Create a multi line text input.
createTreeViewer() Create a tree viewer.
createView() Create a view with scripted content.
createViewerColumn() Create a column for a table viewer.
getComposite() Get the active composite.
getProviderElement() Get the current element for the label/content provider.
getUiEvent() Get the current event in case we are within a UI callback method.
popComposite() Remove the current composite from the composite stack.
pushComposite() Sets the active composite for further commands.
removeControl() Remove a control.
setColumnCount() Set the minimum column count.
showGrid() Display a grid aiding in layouting.

Methods

addControl

Control addControl(Control control, [String layout]) throws Throwable

Add a generic control.

control
control to add
layout
layout data (see module documentation)Optional: defaults to <null>.

control instance

Throwable
when control cannot be added

createButton

Button createButton(Object labelOrImage, Object callback, [String layout]) throws Throwable

Create a push button.

labelOrImage
button text or image to be used
callback
callback code when button gets pressed. Use {module #getUiEvent()} to access the SelectionEvent.
layout
layout data (see module documentation)Optional: defaults to <null>.

button instance

Throwable
on any SWT error

createCheckBox

Button createCheckBox(String label, [boolean selected], [Object callback], [String layout]) throws Throwable

Create a checkbox.

label
checkbox text
selected
initial state of the checkboxOptional: defaults to <ru>.
callback
callback code when the checkbox gets ticked/unticked. Use {module #getUiEvent()} to access the SelectionEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <null>.

checkbox instance

Throwable
on any SWT error

createComboViewer

ComboViewer createComboViewer(Object[] elements, [boolean editable], [Object callback], [String layout]) throws Throwable

Create a combo box. The first element will automatically be selected.

elements
combo elements to display.
editable
set to true to allow users to enter custom entriesOptional: defaults to <als>.
callback
callback code when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <null>.

combo viewer instance

Throwable
on any SWT error

createComparator

ViewerComparator createComparator(StructuredViewer viewer, [Object categoryCallback], [Object compareCallback]) throws Throwable

Create a comparator (sorter) to be used for combos, lists or tables. The comparator is automatically attached to the provided viewer.

viewer
viewer to create the comparator for
categoryCallback
script callback to return the category type for an element. The element can be retrieved with getProviderElement(). The return type is expected to be an integer. Lower numbers get displayed first.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
compareCallback
script callback to return the comparison result of 2 elements. The elements are stored as array in getProviderElement(). The return type is expected to be an integer. If <0 then the first element gets listed first, >0 lists the 2nd element firstOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.

the viewer comparator

Throwable
when comparator cannot be set

createComposite

Composite createComposite([String layout]) throws Throwable

Create a new composite. To activate the composite (and create elements inside) use pushComposite().

layout
layout data (see module documentation)Optional: defaults to <o! o!>.

composite instance

Throwable
on any SWT error

createDialog

org.eclipse.ease.modules.platform.uibuilder.ScriptableDialog createDialog(Object layoutCode, [String title], [String message]) throws Throwable

Create a dialog with scripted content. To populate the dialog we need to provide a callback method that creates UI elements for the dialog area. After the setup the dialog can be shown by calling dialog.open(). To retrieve input data after the dialog got closed call dialog.getData(uiComponent).

layoutCode
script code to be called when dialog window is created
title
dialog title text displayed in header areaOptional: defaults to <Dialog>.
message
dialog info message displayed in header areaOptional: defaults to <null>.

dialog instance

Throwable
when dialog cannot be created.

createGroup

Group createGroup([String label], [String layout]) throws Throwable

Create a group composite. Further create commands will target this composite. To revert back to the parent use popComposite().

label
group labelOptional: defaults to <null>.
layout
layout data (see module documentation)Optional: defaults to <o o>.

group instance

Throwable
on any SWT error

createImage

Image createImage(String location) throws Throwable

Create an image instance. Images will not directly be displayed. Instead they can be used when creating controls or views. When an image is created, its lifecycle gets bound to the current composite. When the composite gets disposed also all images bound to that composite get disposed.

location
location to create image from

image instance

Throwable
on any SWT error

createLabel

Label createLabel(Object labelOrImage, [String layout]) throws Throwable

Create a label.

labelOrImage
label text or image to be used
layout
layout data (see module documentation)Optional: defaults to <<>.

label instance

Throwable
on any SWT error

createLabelProvider

ColumnLabelProvider createLabelProvider([Object textCallback], [Object imageCallback])

Create a label provider to be used for combos, lists or tables. While the callback is executed you may call getProviderElement() to get the current element.

textCallback
script callback to return the text for the elementOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
imageCallback
script callback to return an Image or ImageDescriptor for the elementOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.

label provider instance

createListViewer

ListViewer createListViewer(Object[] elements, [Object callback], [String layout]) throws Throwable

Create a list viewer.

elements
list elements to display
callback
callback when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <null>.

list viewer instance

Throwable
on any SWT error

createProgressBar

ProgressBar createProgressBar([int value], [int maximum], [String layout]) throws Throwable

Create a progress bar.

value
start value of the progress barOptional: defaults to <0>.
maximum
maximum value of the progress barOptional: defaults to <0>.
layout
layout data (see module documentation)Optional: defaults to <o>.

progress bar instance

Throwable
on any SWT error

createRadioButton

Button createRadioButton(String label, [boolean selected], [Object callback], [String layout]) throws Throwable

Create a radio button.

label
radio text
selected
initial state of the checkboxOptional: defaults to <ru>.
callback
callback code when the radio button gets ticked/unticked. Use {module #getUiEvent()} to access the SelectionEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <null>.

radio button instance

Throwable
on any SWT error

createScrolledComposite

Composite createScrolledComposite([String layout]) throws Throwable

Create a new composite inside of a scrolled composite. Scrollbars will be added dynamically in case the content does not fit into the composite area. To activate the composite (and create elements inside) use pushComposite().

layout
layout data (see module documentation)Optional: defaults to <o! o!>.

composite instance

Throwable
on any SWT error

createSeparator

Label createSeparator([boolean horizontal], [String layout]) throws Throwable

Create a separator.

horizontal
true for horizontal, false for verticalOptional: defaults to <ru>.
layout
layout data (see module documentation)Optional: defaults to <o>.

separator instance

Throwable
on any SWT error

createTableViewer

TableViewer createTableViewer(Object[] elements, [Object callback], [String layout]) throws Throwable

Create a table viewer. To enhance look and feel create columns using createViewerColumn().

elements
table elements to display
callback
callback when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <o! o!>.

table viewer instance

Throwable
on any SWT error

createText

Text createText([String layout]) throws Throwable

Create a single line text input.

layout
layout data (see module documentation)Optional: defaults to <o!>.

text instance

Throwable
on any SWT error

createTextBox

Text createTextBox([String layout]) throws Throwable

Create a multi line text input.

layout
layout data (see module documentation)Optional: defaults to <o!>.

text instance

Throwable
on any SWT error

createTreeViewer

TreeViewer createTreeViewer(Object[] rootElements, Object getChildrenCallback, [Object callback], [String layout]) throws Throwable

Create a tree viewer. To enhance look and feel create columns using createViewerColumn().

rootElements
tree root elements to display
getChildrenCallback
script callback to return element children. During the callback .getProviderElement() can be used to retrieve the current element.
callback
callback when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
layout
layout data (see module documentation)Optional: defaults to <o! o!>.

tree viewer instance

Throwable
on any SWT error

createView

MPart createView([String title], [String iconUri], [String relativeTo], [String position]) throws Throwable

Create a view with scripted content. Automatically sets the active composite for further commands. This view will not be stored when the workbench gets closed.

title
view titleOptional: defaults to <Dynamic View>.
iconUri
URI of view icon to be usedOptional: defaults to <null>.
relativeTo
name/ID of an existing view to put this view relative toOptional: defaults to <null>.
position
one of
  • x,o ... same stack
  • v ... below target view
  • ^ ... above target view
  • < ... left of target view
  • > ... right of target view
Optional: defaults to <x>.

view instance

Throwable
when the view cannot be created

createViewerColumn

ViewerColumn createViewerColumn(ColumnViewer viewer, String title, [BaseLabelProvider labelProvider], [int weight]) throws Throwable

Create a column for a table viewer. The viewer will automatically use a weighted layout for columns, distributing the horizontal space on all columns depending on their weight.

viewer
viewer to create column for
title
column title
labelProvider
label provider for columnOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
weight
column weightOptional: defaults to <1>.

table viewer column

Throwable
on any SWT error

getComposite

Composite getComposite()

Get the active composite.

active composite or null

getProviderElement

Object getProviderElement()

Get the current element for the label/content provider. Only valid while a provider callback is evaluated.

the element for the current provider evaluation or null

getUiEvent

Object getUiEvent()

Get the current event in case we are within a UI callback method.

current UI event or null

popComposite

Composite popComposite()

Remove the current composite from the composite stack. For the topmost composite this method does nothing.

current composite after the removal

pushComposite

void pushComposite(Composite composite)

Sets the active composite for further commands. The composite layout will be set to GridLayout if not already done. When creating multiple composites you may return to a previous one using popComposite().

composite
composite to be used

removeControl

void removeControl(Object controlOrLocation)

Remove a control.

controlOrLocation
either the control instance returned from a create* method or the coordinates the control is created in.

setColumnCount

void setColumnCount(int columns)

Set the minimum column count. If the current column count is already equal or higher then this method does nothing.

columns
minimum amount of columns

showGrid

void showGrid([boolean showGrid])

Display a grid aiding in layouting. When the grid is displayed, empty cells do show a label with their location coordinates.

showGrid
true to display.Optional: defaults to <ru>.