Interface IGraphicalClientContext

All Superinterfaces:
IClientContext

public interface IGraphicalClientContext extends IClientContext
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.

  • Method Details

    • displayFileOpenSelector

      String displayFileOpenSelector(String caption)
      Display a file selector dialog (Open file).
      Parameters:
      caption - optional caption
      Returns:
      selected file path or null
    • displayFileSaveSelector

      String displayFileSaveSelector(String caption)
      Display a file selector dialog (Save file).
      Parameters:
      caption - optional caption
      Returns:
      selected file path or null
    • displayFolderSelector

      String displayFolderSelector(String caption)
      Display a folder selection dialog.
      Parameters:
      caption - optional caption
      Returns:
      folder path or null
    • displayQuestionBox

      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
    • displaySimpleForm

      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
    • displayForm

      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
    • displayMessageBox

      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)
    • displayText

      String displayText(String caption, String text, boolean editable)
      Display a text box.
      Parameters:
      caption - title for the message box
      text -
      editable -
      Returns:
      the text (updated if it is editable), or null if the user cancelled
    • displayList

      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
    • displayGraph

      default 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
    • displayGraph

      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
    • executeAsync

      void executeAsync(String taskName, Runnable runnable) throws InterruptedException, InvocationTargetException
      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()), 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()
    • executeAsyncWithReturn

      <T> T executeAsyncWithReturn(String taskName, Callable<T> callable) throws InterruptedException, InvocationTargetException
      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()), 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()
    • uiExecute

      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
    • uiExecuteBlocking

      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
    • uiExecuteWithDelay

      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
    • registerUnitFragmentPositionChangeListener

      void registerUnitFragmentPositionChangeListener(IUnitFragmentPositionChangeListener listener)
      Register a listener for positional changes in unit fragments.
      Parameters:
      listener -
    • unregisterUnitFragmentPositionChangeListener

      void unregisterUnitFragmentPositionChangeListener(IUnitFragmentPositionChangeListener listener)
      Unregister a listener for positional changes in unit fragments.
      Parameters:
      listener -
    • getViews

      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
    • getViews

      List<? extends IUnitView> getViews()
      Get the list of all views in the current UI client.
      Returns:
      a list of views
    • getFocusedView

      IUnitView getFocusedView()
      Get view containing the currently focused view
      Returns:
    • getFocusedFragment

      default IUnitFragment getFocusedFragment()
      Get the currently focused fragment. Convenience method ~equivalent to getFocusedView().getActiveFragment().
      Returns:
      may be null
    • getFocusedUnit

      default IUnit getFocusedUnit()
      Get the IUnit object represented by the currently focused fragment. Convenience method ~equivalent to getFocusedView().getUnit().
      Returns:
      may be null
    • getFocusedAddress

      default String getFocusedAddress()
      Get the currently active unit address of the focused fragment. Convenience method ~equivalent to getFocusedFragment().getActiveAddress().
      Returns:
      may be null
    • getFocusedItem

      default IItem getFocusedItem()
      Get the currently active unit item of the focused fragment.. Convenience method ~equivalent to getFocusedFragment().getActiveItem().
      Returns:
    • openView

      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)
    • findFragment

      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