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

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.

Field Summary

Fields

Change	Modifier and Type	Field	Description
	static int	INITIAL_MODAL_DELAY	The time, for modal tasks, to try and run before blocking and showing a dialog
NEW	protected Task	task

Constructor Summary

Constructors

Change	Constructor	Description
TaskLauncher(Task task)	Constructor for TaskLauncher.
TaskLauncher(Task task, TaskMonitor taskMonitor)	Constructor where an external taskMonitor is used.
TaskLauncher(Task task, java.awt.Component parent)	Constructor for TaskLauncher.
TaskLauncher(Task task, java.awt.Component parent, int delay)	Construct a new TaskLauncher.
TaskLauncher(Task task, java.awt.Component parent, int delay, int dialogWidth)	Construct a new TaskLauncher.

Method Summary

Change	Modifier and Type	Method	Description
NEW	protected TaskDialog	createTaskDialog(java.awt.Component comp)
	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

Field Detail

INITIAL_MODAL_DELAY

public static final int INITIAL_MODAL_DELAY

The time, for modal tasks, to try and run before blocking and showing a dialog

See Also:

Constant Field Values

task NEW

protected Task task

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 delay)

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

delay - number of milliseconds to delay until the task monitor is displayed

TaskLauncher

public TaskLauncher(Task task,
                    java.awt.Component parent,
                    int delay,
                    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

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

TaskLauncher

public TaskLauncher(Task task,
                    TaskMonitor taskMonitor)

Constructor where an external taskMonitor is used. Normally, this class will provide the TaskDialog as the monitor. This constructor is useful when you want to run the task and use a monitor that is embedded in some other component.

See notes on modal usage

Parameters:

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

taskMonitor - the monitor to use while running the task.

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

createTaskDialog NEW

protected TaskDialog createTaskDialog(java.awt.Component comp)