# UI Module

Methods providing access to UI components. Allows to show dialogs, execute code in the UI thread, access views and editors.

## Method Overview

Method | Description
--- | ---
clearConsole() | Clear the script console.
closeView() | Close a dedicated view.
convertSelection() | Converts selection to a consumable form.
createColor() | Constructs a new color given the desired red, green and blue values expressed as ints in the range 0 to 255 (where 0 is black and 255 is full brightness).
executeUI() | Run code in UI thread.
exitApplication() | Close the application.
getActiveEditor() | Get the active editor instance.
getActiveView() | Get the active view instance.
getClipboard() | Get text data from the clipboard.
getConsole() | Get the script console for the current engine.
getSelection() | Get the current selection.
getShell() | Get the workbench shell instance.
isHeadless() | Verify if we are running in headless mode.
isUIThread() | Returns `true` when executed in the UI thread.
maximizeView() | Maximize a dedicated view.
minimizeView() | Minimize a dedicated view.
moveView() | Move an existing view to a new position relative to another view.
openDialog() | Show a generic dialog.
openEditor() | Alias for showEditor().
openView() | Alias for showView().
renameScriptShell() | Renames the script shell window to the specified name.
setClipboard() | Write text data to the clipboard.
showConfirmDialog() | Displays a confirmation dialog.
showEditor() | Opens a file in an editor.
showErrorDialog() | Displays an error dialog.
showInfoDialog() | Displays an info dialog.
showInputDialog() | Displays an input dialog.
showMessageDialog() | Alias for showInfoDialog().
showQuestionDialog() | Displays a question dialog.
showSelectionDialog() | Displays a selection dialog.
showView() | Shows a view in this page with the given id and secondary id.
showWarningDialog() | Displays a warning dialog.
shutdown() | Shut down the application.

## Methods

### clearConsole

void clearConsole()

Clear the script console.

### closeView

void closeView(String name, [String secondaryID])

Close a dedicated view.

name
  visible name or id of view to close
secondaryID
  secondary ID of view to closeOptional: defaults to <null>.

### convertSelection

Object convertSelection(ISelection selection)

Converts selection to a consumable form. Table/Tree selections are transformed into Object[], Text selections into the selected String.

selection
  selection to convert

converted elements

### createColor

Color createColor(int red, int green, int blue)

Constructs a new color given the desired red, green and blue values expressed as ints in the range 0 to 255 (where 0 is black and 255 is full brightness).

You must dispose the color when it is no longer required.

red
  the amount of red in the color
green
  the amount of green in the color
blue
  the amount of blue in the color

color instance

### executeUI

Object executeUI(Object code) throws ExecutionException

Run code in UI thread. Needed to interact with SWT elements. Might not be supported by some engines. Might be disabled by the user. Code will be executed synchronously and stall UI updates while executed.

code
  code/object to execute

execution result

ExecutionException
  when execution of UI code fails

### exitApplication

void exitApplication()

Close the application. On unsaved editors user will be asked to save before closing.

### getActiveEditor

IEditorPart getActiveEditor()

Get the active editor instance.

active editor

### getActiveView

IWorkbenchPart getActiveView()

Get the active view instance.

active view

### getClipboard

Object getClipboard()

Get text data from the clipboard.

clipboard text

### getConsole

ScriptConsole getConsole()

Get the script console for the current engine.

script console or `null`

### getSelection

ISelection getSelection([String name])

Get the current selection. If partID is provided, the selection of the given part is returned. Otherwise the selection of the current active part is returned.

name
  name or ID of part to get selection fromOptional: defaults to <null>.

current selection

### getShell

Shell getShell()

Get the workbench shell instance.

shell

### isHeadless

boolean isHeadless()

Verify if we are running in headless mode.

`true` if we are running without UI

### isUIThread

boolean isUIThread()

Returns `true` when executed in the UI thread.

`true` in UI thread

### maximizeView

void maximizeView(String name) throws Throwable

Maximize a dedicated view. If the view is not opened yet, it will be opened by this call. A second call will restore the original size of the view.

name
  visible name or id of view to maximize

Throwable
  when view cannot be opened

### minimizeView

void minimizeView(String name) throws Throwable

Minimize a dedicated view. If the view is not opened yet, it will be opened by this call. A second call will restore view on a floating dock.

name
  name or id of view to minimize

Throwable
  when view cannot be opened

### moveView

void moveView(String sourceView, String relativeTo, [String position])

Move an existing view to a new position relative to another view.

sourceView
  view to move: view ID or view title
relativeTo
  view to move source relative to: view ID or view title
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>.

### openDialog

int openDialog(Window dialog) throws Throwable

Show a generic dialog.

dialog
  dialog to display

result of dialog.open() method

Throwable
  when we cannot open the dialog

### renameScriptShell

void renameScriptShell(String newName)

Renames the script shell window to the specified name.

newName
  new name for the script shell window

### setClipboard

void setClipboard(String data)

Write text data to the clipboard.

data
  data to write to the clipboard

### showConfirmDialog

boolean showConfirmDialog(String message, [String title])

Displays a confirmation dialog. Uses the engine I/O streams in headless mode.

message
  dialog message
title
  dialog titleOptional: defaults to <Confirmation>.

`true` when accepted

### showEditor

IEditorPart showEditor(Object location) throws Throwable

Opens a file in an editor.

Alias: openEditor()

location
  file location to open, either IFile or workspace file location

editor instance or `null`

Throwable
  when we cannot open the editor

### showErrorDialog

void showErrorDialog(String message, [String title])

Displays an error dialog. Uses the engine output stream in headless mode.

message
  dialog message
title
  dialog titleOptional: defaults to <Error>.

### showInfoDialog

void showInfoDialog(String message, [String title])

Displays an info dialog. Uses the engine output stream in headless mode.

Alias: showMessageDialog()

message
  dialog message
title
  dialog titleOptional: defaults to <Info>.

### showInputDialog

String showInputDialog(String message, [String initialValue], [String title])

Displays an input dialog. Uses the engine I/O streams in headless mode.

message
  dialog message
initialValue
  default value used to populate input boxOptional: defaults to <>.
title
  dialog titleOptional: defaults to <Information request>.

user input or `null` in case the user aborted/closed the dialog

### showQuestionDialog

boolean showQuestionDialog(String message, [String title])

Displays a question dialog. Contains yes/no buttons. Uses the engine I/O streams in headless mode.

message
  dialog message
title
  dialog titleOptional: defaults to <Question>.

`true` when 'yes' was pressed, `false` otherwise

### showSelectionDialog

Object showSelectionDialog(Object[] elements, [String message], [String title])

Displays a selection dialog. Selection elements need to provide a useful toString() method. Uses the engine I/O streams in headless mode.

elements
  array of elements to choose from
message
  dialog messageOptional: defaults to <>.
title
  dialog titleOptional: defaults to <Selection request>.

selected element or `null` in case the user aborted/closed the dialog

### showView

IViewPart showView(String name, [String secondaryId], [int mode]) throws Throwable

Shows a view in this page with the given id and secondary id. The Behavior of this method varies based on the supplied mode. If `VIEW_ACTIVATE` is supplied, the view is given focus. If `VIEW_VISIBLE` is supplied, then it is made visible but not given focus. Finally, if `VIEW_CREATE` is supplied the view is created and will only be made visible if it is not created in a folder that already contains visible views.

This allows multiple instances of a particular view to be created. They are disambiguated using the secondary id. If a secondary id is given, the view must allow multiple instances by having specified allowMultiple="true" in its extension.

Alias: openView()

name
  either the id of the view extension to use or the visible name of the view (tab title)
secondaryId
  the secondary id to use, or `null` for no secondary idOptional: defaults to <null>.
mode
  the activation mode. Must be .VIEW_ACTIVATE, .VIEW_VISIBLE or .VIEW_CREATE, Default is .VIEW_ACTIVATEOptional: defaults to <1>.

a view

Throwable
  when the view cannot be opened

### showWarningDialog

void showWarningDialog(String message, [String title])

Displays a warning dialog. Uses the engine output stream in headless mode.

message
  dialog message
title
  dialog titleOptional: defaults to <Warning>.

### shutdown

void shutdown()

Shut down the application.