# 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 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.
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])

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])

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])

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 SelectionEvent.Optional: defaults to <null>.
layout
  layout data (see module documentation)Optional: defaults to <null>.

checkbox instance

Throwable
  on any SWT error

### createComboViewer

ComboViewer createComboViewer(Object elements, [Object callback], [String layout])

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

elements
  combo elements to display.
callback
  callback code when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <null>.
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])

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

Throwable
  when comparator cannot be set

### createComposite

Composite createComposite([String layout])

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

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])

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])

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)

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])

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 <null>.
imageCallback
  script callback to return an Image or ImageDescriptor for the elementOptional: defaults to <null>.

label provider instance

### createListViewer

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

Create a list viewer.

elements
  list elements to display
callback
  callback when selection changes. Use {module #getUiEvent()} to access the SelectionChangedEvent.Optional: defaults to <null>.
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])

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

Throwable
  on any SWT error

### createRadioButton

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

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 SelectionEvent.Optional: defaults to <null>.
layout
  layout data (see module documentation)Optional: defaults to <null>.

radio button instance

Throwable
  on any SWT error

### createSeparator

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

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

Throwable
  on any SWT error

### createTableViewer

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

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 <null>.
layout
  layout data (see module documentation)Optional: defaults to <"o! o!">.

table viewer instance

Throwable
  on any SWT error

### createText

Text createText([String layout])

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])

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])

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 <null>.
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])

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 title
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])

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

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 <true>.