UI Builder Module

Create UI elements by adding SWT controls via script commands to a dynamic org.eclipse.swt.layout.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(boolean) 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(Object) 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

Methods

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.

addControl

org.eclipse.swt.widgets.Control addControl(org.eclipse.swt.widgets.Control control, [java.lang.String layout]) java.lang.Throwable

Add a generic control.

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

control instance

java.lang.Throwable: when control cannot be added

createButton

org.eclipse.swt.widgets.Button createButton(java.lang.Object labelOrImage, java.lang.Object callback, [java.lang.String layout]) java.lang.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 org.eclipse.swt.events.SelectionEvent.
layout: layout data (see module documentation)Optional: defaults to <null>.

button instance

java.lang.Throwable: on any SWT error

createCheckBox

org.eclipse.swt.widgets.Button createCheckBox(java.lang.String label, [boolean selected], [java.lang.Object callback], [java.lang.String layout]) java.lang.Throwable

Create a checkbox.

label: checkbox text
selected: initial state of the checkboxOptional: defaults to <true>.
callback: callback code when the checkbox gets ticked/unticked. Use {module #getUiEvent()} to access the org.eclipse.swt.events.SelectionEvent.Optional: defaults to <null>.
layout: layout data (see module documentation)Optional: defaults to <null>.

checkbox instance

java.lang.Throwable: on any SWT error

createComboViewer

org.eclipse.jface.viewers.ComboViewer createComboViewer( elements, [boolean editable], [java.lang.Object callback], [java.lang.String layout]) java.lang.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 <false>.
callback: callback code when selection changes. Use {module #getUiEvent()} to access the org.eclipse.jface.viewers.SelectionChangedEvent.Optional: defaults to <null>.
layout: layout data (see module documentation)Optional: defaults to <null>.

combo viewer instance

java.lang.Throwable: on any SWT error

createComparator

org.eclipse.jface.viewers.ViewerComparator createComparator(org.eclipse.jface.viewers.StructuredViewer viewer, [java.lang.Object categoryCallback], [java.lang.Object compareCallback]) java.lang.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 <null>.
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 <null>.

the viewer comparator

java.lang.Throwable: when comparator cannot be set

createComposite

org.eclipse.swt.widgets.Composite createComposite([java.lang.String layout]) java.lang.Throwable

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

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

composite instance

java.lang.Throwable: on any SWT error

createDialog

org.eclipse.ease.modules.platform.uibuilder.ScriptableDialog createDialog(java.lang.Object layoutCode, [java.lang.String title], [java.lang.String message]) java.lang.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

java.lang.Throwable: when dialog cannot be created.

createGroup

org.eclipse.swt.widgets.Group createGroup([java.lang.String label], [java.lang.String layout]) java.lang.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

java.lang.Throwable: on any SWT error

createImage

org.eclipse.swt.graphics.Image createImage(java.lang.String location) java.lang.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

java.lang.Throwable: on any SWT error

createLabel

org.eclipse.swt.widgets.Label createLabel(java.lang.Object labelOrImage, [java.lang.String layout]) java.lang.Throwable

Create a label.

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

label instance

java.lang.Throwable: on any SWT error

createLabelProvider

org.eclipse.jface.viewers.ColumnLabelProvider createLabelProvider([java.lang.Object textCallback], [java.lang.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 <null>.
imageCallback: script callback to return an org.eclipse.swt.graphics.Image or org.eclipse.jface.resource.ImageDescriptor for the elementOptional: defaults to <null>.

label provider instance

createListViewer

org.eclipse.jface.viewers.ListViewer createListViewer( elements, [java.lang.Object callback], [java.lang.String layout]) java.lang.Throwable

Create a list viewer.

elements: list elements to display
callback: callback when selection changes. Use {module #getUiEvent()} to access the org.eclipse.jface.viewers.SelectionChangedEvent.Optional: defaults to <null>.
layout: layout data (see module documentation)Optional: defaults to <null>.

list viewer instance

java.lang.Throwable: on any SWT error

createProgressBar

org.eclipse.swt.widgets.ProgressBar createProgressBar([int value], [int maximum], [java.lang.String layout]) java.lang.Throwable

Create a progress bar.

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

progress bar instance

java.lang.Throwable: on any SWT error

createRadioButton

org.eclipse.swt.widgets.Button createRadioButton(java.lang.String label, [boolean selected], [java.lang.Object callback], [java.lang.String layout]) java.lang.Throwable

Create a radio button.

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

radio button instance

java.lang.Throwable: on any SWT error

createScrolledComposite

org.eclipse.swt.widgets.Composite createScrolledComposite([java.lang.String layout]) java.lang.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(Composite).

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

composite instance

java.lang.Throwable: on any SWT error

createSeparator

org.eclipse.swt.widgets.Label createSeparator([boolean horizontal], [java.lang.String layout]) java.lang.Throwable

Create a separator.

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

separator instance

java.lang.Throwable: on any SWT error

createTableViewer

org.eclipse.jface.viewers.TableViewer createTableViewer( elements, [java.lang.Object callback], [java.lang.String layout]) java.lang.Throwable

Create a table viewer. To enhance look and feel create columns using createViewerColumn(ColumnViewer, String, BaseLabelProvider, int).

elements: table elements to display
callback: callback when selection changes. Use {module #getUiEvent()} to access the org.eclipse.jface.viewers.SelectionChangedEvent.Optional: defaults to <null>.
layout: layout data (see module documentation)Optional: defaults to <o! o!>.

table viewer instance

java.lang.Throwable: on any SWT error

createText

org.eclipse.swt.widgets.Text createText([java.lang.String layout]) java.lang.Throwable

Create a single line text input.

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

text instance

java.lang.Throwable: on any SWT error

createTextBox

org.eclipse.swt.widgets.Text createTextBox([java.lang.String layout]) java.lang.Throwable

Create a multi line text input.

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

text instance

java.lang.Throwable: on any SWT error

createTreeViewer

org.eclipse.jface.viewers.TreeViewer createTreeViewer( rootElements, java.lang.Object getChildrenCallback, [java.lang.Object callback], [java.lang.String layout]) java.lang.Throwable

Create a tree viewer. To enhance look and feel create columns using createViewerColumn(ColumnViewer, String, BaseLabelProvider, int).

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 org.eclipse.jface.viewers.SelectionChangedEvent.Optional: defaults to <null>.
layout: layout data (see module documentation)Optional: defaults to <o! o!>.

tree viewer instance

java.lang.Throwable: on any SWT error

createView

org.eclipse.e4.ui.model.application.ui.basic.MPart createView([java.lang.String title], [java.lang.String iconUri], [java.lang.String relativeTo], [java.lang.String position]) java.lang.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

java.lang.Throwable: when the view cannot be created

createViewerColumn

org.eclipse.jface.viewers.ViewerColumn createViewerColumn(org.eclipse.jface.viewers.ColumnViewer viewer, java.lang.String title, [org.eclipse.jface.viewers.BaseLabelProvider labelProvider], [int weight]) java.lang.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 <null>.
weight: column weightOptional: defaults to <1>.

table viewer column

java.lang.Throwable: on any SWT error

getComposite

org.eclipse.swt.widgets.Composite getComposite()

Get the active composite.

active composite or null

getProviderElement

java.lang.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

java.lang.Object getUiEvent()

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

current UI event or null

popComposite

org.eclipse.swt.widgets.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(org.eclipse.swt.widgets.Composite composite)

Sets the active composite for further commands. The composite layout will be set to org.eclipse.swt.layout.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(java.lang.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 <true>.