Class TaskLauncher


  • public class TaskLauncher
    extends java.lang.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 Summary

      Constructors 
      Constructor Description
      TaskLauncher​(Task task)
      Constructor for TaskLauncher
      TaskLauncher​(Task task, java.awt.Component parent)
      Constructor for TaskLauncher
      TaskLauncher​(Task task, java.awt.Component parent, int delayMs)
      Construct a new TaskLauncher
      TaskLauncher​(Task task, java.awt.Component parent, int delayMs, int dialogWidth)
      Construct a new TaskLauncher
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected ghidra.util.task.TaskRunner createTaskRunner​(Task task, java.awt.Component parent, int delayMs, int dialogWidth)  
      static <T extends Task>
      T
      launch​(T task)
      Directly launches a Task via a new TaskLauncher instance, with a progress dialog.
      static void launchModal​(java.lang.String title, MonitoredRunnable runnable)
      A convenience method to directly run a MonitoredRunnable in a separate thread as a Task, displaying a modal progress dialog.
      static void launchModal​(java.lang.String title, java.lang.Runnable runnable)
      A convenience method to directly run a Runnable in a separate thread as a Task, displaying a non-modal progress dialog.
      static void launchNonModal​(java.lang.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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • 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,
                            java.awt.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,
                            java.awt.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,
                            java.awt.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 Detail

      • launchNonModal

        public static void launchNonModal​(java.lang.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​(java.lang.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​(java.lang.String title,
                                       java.lang.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,
                                                               java.awt.Component parent,
                                                               int delayMs,
                                                               int dialogWidth)