public interface

IGraphicalClientContext

implements IClientContext
com.pnfsoftware.jeb.client.api.IGraphicalClientContext

Class Overview

This important interface represents a client context for scripting inside a GUI client. 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 will be provided in to offer basic manipulation of UI elements.

Summary

Public Methods
abstract String displayFileOpenSelector(String caption)
Display a file selector dialog (Open file).
abstract String displayFileSaveSelector(String caption)
Display a file selector dialog (Save file).
abstract String displayFolderSelector(String caption)
Display a folder selection dialog.
abstract Object[] displayForm(String caption, String description, FormEntry...<?> entries)
Display a form dialog prompting the user for inputs.
abstract void displayGraph(String caption, Digraph graph)
Create a graph dialog.
abstract void displayGraph(String caption, Digraph graph, GraphDialogExtensions ext)
Create a graph dialog.
abstract int displayList(String caption, String message, String[] headers, Object[][] rows)
Display a table of elements.
abstract int displayMessageBox(String caption, String message, IconType iconType, ButtonGroupType bgType)
Display a message box to the user.
abstract String displayQuestionBox(String caption, String message, String defaultValue)
Display a message box prompting the user for input.
abstract String[] displaySimpleForm(String caption, String description, String... entries)
Display a simple form dialog prompting the user for inputs.
abstract String displayText(String caption, String text, boolean editable)
Display a text box.
abstract void executeAsync(String taskName, Runnable runnable)
Execute a task asynchronously.
abstract <T> T executeAsyncWithReturn(String taskName, Callable<T> callable)
Execute a task asynchronously, and retrieve a value returned by the task.
abstract IUnitFragment findFragment(IUnit unit, String label, boolean focus)
Find and activate a view fragment for the provided unit with the provided name.
abstract String getFocusedAddress()
Get the currently active unit address of the focused fragment.
abstract IUnitFragment getFocusedFragment()
Get the currently focused fragment.
abstract IItem getFocusedItem()
Get the currently active unit item of the focused fragment..
abstract IUnit getFocusedUnit()
Get the IUnit object represented by the currently focused fragment.
abstract IUnitView getFocusedView()
Get view containing the currently focused view
abstract List<? extends IUnitView> getViews()
Get the list of all views in the current UI client.
abstract List<? extends IUnitView> getViews(IUnit targetUnit)
Get the list of views representing the given unit within the UI client.
abstract boolean navigate(IUnit unit, String unitAddress)
Convenience method used to find and open a unit fragment, and navigate to an optionally-provided address within that fragment.
abstract boolean openView(IUnit unit)
Create or open the view or set of views representing a given unit.
abstract void registerUnitFragmentPositionChangeListener(IUnitFragmentPositionChangeListener listener)
Register a listener for positional changes in unit fragments.
abstract void uiExecute(Runnable runnable)
Execute a task on the UI thread.
abstract void uiExecuteBlocking(Runnable runnable)
Execute a task on the UI thread.
abstract void uiExecuteWithDelay(int delay, Runnable runnable)
Execute a task on the UI thread after the provided delay.
abstract void unregisterUnitFragmentPositionChangeListener(IUnitFragmentPositionChangeListener listener)
Unregister a listener for positional changes in unit fragments.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.client.api.IClientContext

Public Methods

public abstract String displayFileOpenSelector (String caption)

Display a file selector dialog (Open file).

Parameters
caption optional caption
Returns
  • selected file path or null

public abstract String displayFileSaveSelector (String caption)

Display a file selector dialog (Save file).

Parameters
caption optional caption
Returns
  • selected file path or null

public abstract String displayFolderSelector (String caption)

Display a folder selection dialog.

Parameters
caption optional caption
Returns
  • folder path or null

public abstract Object[] displayForm (String caption, String description, FormEntry...<?> entries)

Display a form dialog prompting the user for inputs.

Parameters
caption title for the dialog
description optional form description line
entries a list of form entries
Returns
  • the array of user inputs, or null if the user canceled the action

public abstract void displayGraph (String caption, Digraph graph)

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

Also see the extended version of this method.

Parameters
caption shell title
graph directed graph model

public abstract void displayGraph (String caption, Digraph graph, GraphDialogExtensions ext)

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

Parameters
caption shell title
graph directed graph model
ext optional; used to customize the graph and provide action handlers

public abstract int displayList (String caption, String message, String[] headers, Object[][] rows)

Display a table of elements.

Parameters
caption optional caption
message optional message
headers table headers
rows rows; a row must have the same number of elements as the provided headers; objects are rendered using their #toString() method
Returns
  • the 0-based index of the selected row, or -1 if none

public abstract int displayMessageBox (String caption, String message, IconType iconType, ButtonGroupType bgType)

Display a message box to the user.

Parameters
caption title for the message box
message text to be displayed, can be multi-line
iconType icon to be displayed in the message box (default: INFORMATION)
bgType button to be provided in the message box (default: OK)
Returns
  • 0(cancel), 1(ok), 2(yes), 3(no)

public abstract String displayQuestionBox (String caption, String message, String defaultValue)

Display a message box prompting the user for input.

Parameters
caption title for the message box
message information, should be a single line of text
defaultValue optional default input value, will be selected if provided
Returns
  • the user input text, or null if none

public abstract String[] displaySimpleForm (String caption, String description, String... entries)

Display a simple form dialog prompting the user for inputs.

Parameters
caption title for the dialog
description optional form description line
entries a 2N-array of (header, default value) entries; example: ("First name", "Your first name", "Last name", "")
Returns
  • the array of user inputs, or null if the user canceled the action

public abstract String displayText (String caption, String text, boolean editable)

Display a text box.

Parameters
caption title for the message box
Returns
  • the text (updated if it is editable), or null if the user cancelled

public abstract void executeAsync (String taskName, Runnable runnable)

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 interrupted()), and interrupt processing accordingly.

Parameters
taskName optional task name
runnable a task
Throws
InterruptedException the task was interrupted
InvocationTargetException an exception happened during execution of the task - retrieve it with getTargetException() or getCause()

public abstract T executeAsyncWithReturn (String taskName, Callable<T> callable)

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 interrupted()), and interrupt processing accordingly.

This method must be called on the UI thread.

Parameters
taskName optional task name
callable a task
Returns
  • the object returned by the callable on success, null on failure
Throws
InterruptedException the task was interrupted
InvocationTargetException an exception happened during execution of the task - retrieve it with getTargetException() or getCause()

public abstract IUnitFragment findFragment (IUnit unit, String label, boolean focus)

Find and activate a view fragment for the provided unit with the provided name.

Parameters
unit target unit
label fragment name, e.g. "disassembly"
focus if true, on success, the fragment will also receive focus
Returns
  • the fragment or null

public abstract String getFocusedAddress ()

Get the currently active unit address of the focused fragment. Convenience method ~equivalent to getFocusedFragment().getActiveAddress().

Returns
  • may be null

public abstract IUnitFragment getFocusedFragment ()

Get the currently focused fragment. Convenience method ~equivalent to getFocusedView().getActiveFragment().

Returns
  • may be null

public abstract IItem getFocusedItem ()

Get the currently active unit item of the focused fragment.. Convenience method ~equivalent to getFocusedFragment().getActiveItem().

public abstract IUnit getFocusedUnit ()

Get the IUnit object represented by the currently focused fragment. Convenience method ~equivalent to getFocusedView().getUnit().

Returns
  • may be null

public abstract IUnitView getFocusedView ()

Get view containing the currently focused view

public abstract List<? extends IUnitView> getViews ()

Get the list of all views in the current UI client.

Returns
  • a list of views

public abstract List<? extends IUnitView> getViews (IUnit targetUnit)

Get the list of views representing the given unit within the UI client.

Parameters
targetUnit the target unit, null to get all views
Returns
  • a list of views

public abstract boolean navigate (IUnit unit, String unitAddress)

Convenience method used to find and open a unit fragment, and navigate to an optionally-provided address within that fragment.

Parameters
unit mandatory
unitAddress optional; a unit address (refer to IAddressableUnit)
Returns
  • success indicator

public abstract boolean openView (IUnit unit)

Create or open the view or set of views representing a given unit. On success, one view will also receive focus.

Parameters
unit the unit
Returns
  • 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)

public abstract void registerUnitFragmentPositionChangeListener (IUnitFragmentPositionChangeListener listener)

Register a listener for positional changes in unit fragments.

public abstract void uiExecute (Runnable runnable)

Execute a task on the UI thread. The method returns immediately.

This method may be called from any thread.

Parameters
runnable a task

public abstract void uiExecuteBlocking (Runnable runnable)

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

This method may be called from any thread.

Parameters
runnable a task

public abstract void uiExecuteWithDelay (int delay, Runnable runnable)

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

This method must be called on the UI thread.

Parameters
delay in milliseconds
runnable a task

public abstract void unregisterUnitFragmentPositionChangeListener (IUnitFragmentPositionChangeListener listener)

Unregister a listener for positional changes in unit fragments.