# Interface: com.pnfsoftware.jeb.client.api.IGraphicalClientContext

This important interface represents a client context for scripting inside a GUI client. It is a specialized context for clients displaying a graphical user interface. 

 Note: The public context of the official RCP desktop client implements this interface. 

 Note: Additional methods may be provided to offer basic manipulation of UI elements.

## Method: displayFileOpenSelector
- parameter: `caption`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Display a file selector dialog \(Open file\).
parameter: caption: optional caption
return: selected file path or null

## Method: displayFileSaveSelector
- parameter: `caption`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Display a file selector dialog \(Save file\).
parameter: caption: optional caption
return: selected file path or null

## Method: displayFolderSelector
- parameter: `caption`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Display a folder selection dialog.
parameter: caption: optional caption
return: folder path or null

## Method: displayForm
- parameter: `caption`, type: `java.lang.String`
- parameter: `description`, type: `java.lang.String`
- parameter: `entries`, type: `com.pnfsoftware.jeb.client.api.FormEntry<?>[]`
- return type: `java.lang.Object[]`

Description: Display a form dialog prompting the user for inputs.
parameter: caption: title for the dialog
parameter: description: optional form description line
parameter: entries: a list of form entries
return: the array of user inputs, or null if the user canceled the action

## Method: displayGraph
- parameter: `caption`, type: `java.lang.String`
- parameter: `graph`, type: `com.pnfsoftware.jeb.util.graph.Digraph`

Description: Create a graph dialog. The dialog is modeless. This method opens the dialog and returns immediately. 

 Also see [the extended version of this method](#displayGraph(String, Digraph, GraphDialogExtensions)).
parameter: caption: shell title
parameter: graph: directed graph model

## Method: displayGraph
- parameter: `caption`, type: `java.lang.String`
- parameter: `graph`, type: `com.pnfsoftware.jeb.util.graph.Digraph`
- parameter: `ext`, type: `com.pnfsoftware.jeb.client.api.GraphDialogExtensions`

Description: Create a graph dialog. The dialog is modeless. This method opens the dialog and returns immediately.
parameter: caption: shell title
parameter: graph: directed graph model
parameter: ext: optional; used to customize the graph and provide action handlers

## Method: displayList
- parameter: `caption`, type: `java.lang.String`
- parameter: `message`, type: `java.lang.String`
- parameter: `headers`, type: `java.lang.String[]`
- parameter: `rows`, type: `java.lang.Object[][]`
- return type: `int`

Description: Display a table of elements.
parameter: caption: optional caption
parameter: message: optional message
parameter: headers: table headers
parameter: rows: rows; a row must have the same number of elements as the provided headers;            objects are rendered using their [Object#toString()](Object#toString()) method
return: the 0\-based index of the selected row, or \-1 if none

## Method: displayMessageBox
- parameter: `caption`, type: `java.lang.String`
- parameter: `message`, type: `java.lang.String`
- parameter: `iconType`, type: `com.pnfsoftware.jeb.client.api.IconType`
- parameter: `bgType`, type: `com.pnfsoftware.jeb.client.api.ButtonGroupType`
- return type: `int`

Description: Display a message box to the user.
parameter: caption: title for the message box
parameter: message: text to be displayed, can be multi\-line
parameter: iconType: icon to be displayed in the message box \(default: INFORMATION\)
parameter: bgType: button to be provided in the message box \(default: OK\)
return: 0\(cancel\), 1\(ok\), 2\(yes\), 3\(no\)

## Method: displayQuestionBox
- parameter: `caption`, type: `java.lang.String`
- parameter: `message`, type: `java.lang.String`
- parameter: `defaultValue`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Display a message box prompting the user for input.
parameter: caption: title for the message box
parameter: message: information, should be a single line of text
parameter: defaultValue: optional default input value, will be selected if provided
return: the user input text, or null if none

## Method: displaySimpleForm
- parameter: `caption`, type: `java.lang.String`
- parameter: `description`, type: `java.lang.String`
- parameter: `entries`, type: `java.lang.String[]`
- return type: `java.lang.String[]`

Description: Display a simple form dialog prompting the user for inputs.
parameter: caption: title for the dialog
parameter: description: optional form description line
parameter: entries: a 2N\-array of \(header, default value\) entries; example: \("First name", "Your            first name", "Last name", ""\)
return: the array of user inputs, or null if the user canceled the action

## Method: displayText
- parameter: `caption`, type: `java.lang.String`
- parameter: `text`, type: `java.lang.String`
- parameter: `editable`, type: `boolean`
- return type: `java.lang.String`

Description: Display a text box.
parameter: caption: title for the message box
parameter: text: initial text to display
parameter: editable: true if the user may edit the text
return: the text \(updated if it is editable\), or null if the user cancelled

## Method: executeAsync
- parameter: `taskName`, type: `java.lang.String`
- parameter: `runnable`, type: `java.lang.Runnable`

Description: Execute a task asynchronously. The task will not be executed on the UI thread. Users are offered a way to cancel task execution. Therefore, if possible, the runnable should check for user\-requested interruption \(using [Thread#interrupted()](Thread#interrupted())\), and interrupt processing accordingly.
parameter: taskName: optional task name
parameter: runnable: a task
throws: the task was interrupted
throws: an exception happened during execution of the task \-             retrieve it with getTargetException\(\) or getCause\(\)

## Method: executeAsyncWithReturn
- parameter: `taskName`, type: `java.lang.String`
- parameter: `callable`, type: `java.util.concurrent.Callable<T>`
- return type: `T`

Description: Execute a task asynchronously, and retrieve a value returned by the task. Users are offered a way to cancel task execution. Therefore, if possible, the runnable should check for user\-requested interruption \(using [Thread#interrupted()](Thread#interrupted())\), and interrupt processing accordingly. 

 This method must be called on the UI thread.
parameter: taskName: optional task name
parameter: callable: a task
parameter: T: callable result type
return: the object returned by the callable on success, null on failure
throws: the task was interrupted
throws: an exception happened during execution of the task \-             retrieve it with getTargetException\(\) or getCause\(\)

## Method: findFragment
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `label`, type: `java.lang.String`
- parameter: `focus`, type: `boolean`
- return type: `com.pnfsoftware.jeb.client.api.IUnitFragment`

Description: Find and activate a view fragment for the provided unit with the provided name.
parameter: unit: target unit
parameter: label: fragment name, e.g. "disassembly"
parameter: focus: if true, on success, the fragment will also receive focus
return: the fragment or null

## Method: getFocusedAddress
- return type: `java.lang.String`

Description: Get the currently active `unit address` of the focused fragment. Convenience method ~equivalent to `getFocusedFragment().getActiveAddress()`.
return: may be null

## Method: getFocusedFragment
- return type: `com.pnfsoftware.jeb.client.api.IUnitFragment`

Description: Get the currently focused fragment. Convenience method ~equivalent to `getFocusedView().getActiveFragment()`.
return: may be null

## Method: getFocusedItem
- return type: `com.pnfsoftware.jeb.core.output.IItem`

Description: Get the currently active `unit item` of the focused fragment. Convenience method ~equivalent to `getFocusedFragment().getActiveItem()`.
return: may be null

## Method: getFocusedUnit
- return type: `com.pnfsoftware.jeb.core.units.IUnit`

Description: Get the IUnit object represented by the currently focused fragment. Convenience method ~equivalent to `getFocusedView().getUnit()`.
return: may be null

## Method: getFocusedView
- return type: `com.pnfsoftware.jeb.client.api.IUnitView`

Description: Get the currently focused view.
return: the focused view, or null if none

## Method: getViews
- parameter: `targetUnit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- return type: `java.util.List<? extends com.pnfsoftware.jeb.client.api.IUnitView>`

Description: Get the list of views representing the given unit within the UI client.
parameter: targetUnit: the target unit, null to get all views
return: a list of views

## Method: getViews
- return type: `java.util.List<? extends com.pnfsoftware.jeb.client.api.IUnitView>`

Description: Get the list of all views in the current UI client.
return: a list of views

## Method: navigate
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- parameter: `unitAddress`, type: `java.lang.String`
- return type: `boolean`

Description: Convenience method used to find and open a unit fragment, and navigate to an optionally\-provided address within that fragment.
parameter: unit: unit to display
parameter: unitAddress: optional; a unit address \(refer to [IAddressableUnit](IAddressableUnit)\)
return: success indicator

## Method: openView
- parameter: `unit`, type: `com.pnfsoftware.jeb.core.units.IUnit`
- return type: `boolean`

Description: Create or open the view or set of views representing a given unit. On success, one view will also receive focus.
parameter: unit: the unit
return: true if at least one view was open or created. The full set of views associated to         the unit can always be retrieved using [#getViews(IUnit)](#getViews(IUnit))

## Method: registerUnitFragmentPositionChangeListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.client.api.IUnitFragmentPositionChangeListener`

Description: Register a listener for positional changes in unit fragments.
parameter: listener: listener to register

## Method: uiExecute
- parameter: `runnable`, type: `java.lang.Runnable`

Description: Execute a task on the UI thread. The method returns immediately. Exceptions raised during execution of the runnable are neutered. 

 This method may be called from any thread.
parameter: runnable: a task

## Method: uiExecuteBlocking
- parameter: `runnable`, type: `java.lang.Runnable`

Description: Execute a task on the UI thread. The method returns after the task completed. Exceptions raised during execution of the runnable are neutered. To catch exception \(as well as retrieve a return value\), use [#uiExecuteBlocking2(Callable)](#uiExecuteBlocking2(Callable)). 

 This method may be called from any thread.
parameter: runnable: a task

## Method: uiExecuteBlocking2
- parameter: `callable`, type: `java.util.concurrent.Callable<T>`
- return type: `T`

Description: Execute a task on the UI thread. The method returns after the task completed. 

 This method may be called from any thread.
parameter: T: 
parameter: callable: 
return: 
throws: 

## Method: uiExecuteWithDelay
- parameter: `delay`, type: `int`
- parameter: `runnable`, type: `java.lang.Runnable`

Description: Execute a task on the UI thread after the provided delay. 

 This method must be called on the UI thread.
parameter: delay: in milliseconds
parameter: runnable: a task

## Method: unregisterUnitFragmentPositionChangeListener
- parameter: `listener`, type: `com.pnfsoftware.jeb.client.api.IUnitFragmentPositionChangeListener`

Description: Unregister a listener for positional changes in unit fragments.
parameter: listener: listener to unregister