Package ghidra.util.task

Class TaskLauncher

java.lang.Object

ghidra.util.task.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

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.
protected void	runInThisBackgroundThread(Task task)	Runs the given task in the current thread, which cannot be the Swing thread

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

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(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 this launcher will delay showing the modal dialog in order to prevent the dialog from being show, 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)

runInThisBackgroundThread

protected void runInThisBackgroundThread(Task task)

Runs the given task in the current thread, which cannot be the Swing thread

Parameters:

task - the task to run

Throws:

java.lang.IllegalStateException - if the given thread is the Swing thread