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