Package ghidra.util.task

Class TaskLauncher

java.lang.Object
ghidra.util.task.TaskLauncher
public class TaskLauncher extends Object
Class to initiate a Task in a new Thread, and to show a progress dialog that indicates activity if the task takes too long. The progress dialog will show an animation in the event that the task of this class cannot show progress.

For complete control of how this class functions, use TaskLauncher(Task, Component, int, int). Alternatively, for simpler uses, see one of the many static convenience methods.

Modal Usage

Most clients of this class should not be concerned with where the dialog used by this class will appear. By default, it will be shown over the active window, which is the desired behavior for most uses. If you should need a dialog to appear over a non-active window, then either specify that window, or a child component of that window, by calling a constructor that takes in a Component. Further, if you task is modal, then the progress dialog should always be shown over the active window so that users understand that their UI is blocked. In this case, there is no need to specify a component over which to show the dialog.

An alternative to using this class is to use the TaskBuilder, which offers a more Fluent API approach for your tasking needs.

  • Constructor Details

    • TaskLauncher

      public TaskLauncher(Task task)
      Constructor for TaskLauncher

      This constructor assumes that if a progress dialog is needed, then it should appear over the active window. If you should need a dialog to appear over a non-active window, then either specify that window or a component within that window by calling a constructor that takes in a Component.

      Parameters:
      task - task to run in another thread (other than the Swing Thread)

    • TaskLauncher

      public TaskLauncher(Task task, Component parent)
      Constructor for TaskLauncher

      See notes on modal usage

      Parameters:
      task - task to run in another thread (other than the Swing Thread)
      parent - component whose window to use to parent the dialog.

    • TaskLauncher

      public TaskLauncher(Task task, Component parent, int delayMs)
      Construct a new TaskLauncher

      See notes on modal usage

      Parameters:
      task - task to run in another thread (other than the Swing Thread)
      parent - component whose window to use to parent the dialog; null centers the task dialog over the current window
      delayMs - number of milliseconds to delay until the task monitor is displayed

    • TaskLauncher

      public TaskLauncher(Task task, Component parent, int delayMs, int dialogWidth)
      Construct a new TaskLauncher

      See notes on modal usage

      Parameters:
      task - task to run in another thread (other than the Swing Thread)
      parent - component whose window to use to parent the dialog; null centers the task dialog over the current window
      delayMs - number of milliseconds to delay until the task monitor is displayed
      dialogWidth - The preferred width of the dialog (this allows clients to make a wider dialog, which better shows long messages).

  • Method Details

    • launch

      public static <T extends Task> T launch(T task)
      Directly launches a Task via a new TaskLauncher instance, with a progress dialog.

      See also TaskLauncher(Task, Component)

      Parameters:
      task - Task to run in another thread
      Returns:
      the original Task (for chaining)

    • launchNonModal

      public static void launchNonModal(String title, MonitoredRunnable runnable)
      A convenience method to directly run a MonitoredRunnable in a separate thread as a Task, displaying a non-modal progress dialog. 
      
 TaskLauncher.launchNonModal("My task",
   null, // parent
   monitor -> { while (!monitor.isCanceled()) { longRunningWork(); } }
 );

      Note: the task created by this call will be both cancellable and have progress. If you task cannot be cancelled or does not have progress, then do not use this convenience method, but rather call one of the constructors of this class.

      See notes on non-modal usage

      Parameters:
      title - name of the task thread that will be executing this task.
      runnable - MonitoredRunnable that takes a TaskMonitor.

    • launchModal

      public static void launchModal(String title, MonitoredRunnable runnable)
      A convenience method to directly run a MonitoredRunnable in a separate thread as a Task, displaying a modal progress dialog. 
      
 TaskLauncher.launchModal("My task",
    null, // parent
    monitor -> { while (!monitor.isCanceled()) { longRunningWork(); } }
 );

      Note: the task created by this call will be both cancellable and have progress. If you task cannot be cancelled or does not have progress, then do not use this convenience method, but rather call one of the constructors of this class or launchModal(String, MonitoredRunnable).

      Parameters:
      title - name of the task thread that will be executing this task.
      runnable - MonitoredRunnable that takes a TaskMonitor.

    • launchModal

      public static void launchModal(String title, Runnable runnable)
      A convenience method to directly run a Runnable in a separate thread as a Task, displaying a non-modal progress dialog.

      This modal will be launched immediately, without delay. Typically the launcher will delay showing the modal dialog in order to prevent the dialog from being shown, just to have it immediately go away. If you desire this default behavior, then do not use this convenience method. 

      
 TaskLauncher.launchModal("My task",
   monitor -> { foo(); }
 );

      Note: the task created by this call will not be cancellable nor have progress. If you need either of these behaviors, the do not use this convenience method, but rather call one of the constructors of this class.

      Parameters:
      title - name of the task thread that will be executing this task.
      runnable - Runnable to be called in a background thread

    • createTaskRunner

      protected ghidra.util.task.TaskRunner createTaskRunner(Task task, Component parent, int delayMs, int dialogWidth)