This monitor can be configured to allow cancelling via {@link #setCancelEnabled(boolean)}. - * If this cancelling is enabled, the the monitor may be cancelled programmatically. + * Implementation of {@link TaskMonitor} with most features stubbed out. + *
+ * This class supports cancelling and cancel listener notification. Cancelling must be enabled
+ * via {@link #setCancelEnabled(boolean)}.
*/
public class TaskMonitorAdapter implements TaskMonitor {
@@ -145,7 +144,7 @@ public class TaskMonitorAdapter implements TaskMonitor {
cancelled = false;
}
- // TODO this seems like a mistake, to notify of 'cancelled' when clearning
+ // TODO this seems like a mistake, to notify of 'cancelled' when clearing
notifyChangeListeners();
}
diff --git a/Ghidra/Framework/Utility/src/main/java/ghidra/util/task/TaskMonitor.java b/Ghidra/Framework/Utility/src/main/java/ghidra/util/task/TaskMonitor.java
index 4093447c90..7c2074baeb 100644
--- a/Ghidra/Framework/Utility/src/main/java/ghidra/util/task/TaskMonitor.java
+++ b/Ghidra/Framework/Utility/src/main/java/ghidra/util/task/TaskMonitor.java
@@ -18,22 +18,24 @@ package ghidra.util.task;
import ghidra.util.exception.CancelledException;
/**
- * TaskMonitor provides an interface by means of which a
- * potentially long running task can show its progress and also check if the user
- * has cancelled the operation.
+ * TaskMonitor provides an interface that allows potentially long running tasks to show
+ * progress and check for user has cancellation.
*
- * Operations that support a task monitor should periodically
- * check to see if the operation has been cancelled and abort. If possible, the
- * operation should also provide periodic progress information. If it can estimate a
- * percentage done, then it should use the setProgress(int) method,
- * otherwise it should just call the setMessage(String) method.
+ * Tasks that support a task monitor should periodically check to see if the operation has been
+ * cancelled and abort. If possible, the task should also provide periodic progress information. If
+ * your task can estimate the amount of work done, then it should use the {@link #setProgress(long)}
+ * method, otherwise it should call {@link #setMessage(String)} method to provide status updates.
*/
public interface TaskMonitor {
+ /**
+ * A 'do nothing' task monitor that can be passed to APIs when the client has not progress to
+ * report.
+ */
public static final TaskMonitor DUMMY = new StubTaskMonitor();
/**
- * Returns the given task monitor if it is not {@code null}. Otherwise, a {@link #DUMMY}
+ * Returns the given task monitor if it is not {@code null}. Otherwise, a {@link #DUMMY}
* monitor is returned.
* @param tm the monitor to check for {@code null}
* @return a non-null task monitor
@@ -47,21 +49,21 @@ public interface TaskMonitor {
/**
* Returns true if the user has cancelled the operation
- *
+ *
* @return true if the user has cancelled the operation
*/
public boolean isCancelled();
/**
* True (the default) signals to paint the progress information inside of the progress bar
- *
+ *
* @param showProgressValue true to paint the progress value; false to not
*/
public void setShowProgressValue(boolean showProgressValue);
/**
* Sets the message displayed on the task monitor
- *
+ *
* @param message the message to display
*/
public void setMessage(String message);
@@ -81,7 +83,7 @@ public interface TaskMonitor {
/**
* Initialized this TaskMonitor to the given max values. The current value of this monitor
* will be set to zero.
- *
+ *
* @param max maximum value for progress
*/
public void initialize(long max);
@@ -95,14 +97,14 @@ public interface TaskMonitor {
*/
public void setMaximum(long max);
- /**
+ /**
* Returns the current maximum value for progress
* @return the maximum progress value
*/
public long getMaximum();
/**
- * An indeterminate task monitor may choose to show an animation instead of updating progress
+ * An indeterminate task monitor may choose to show an animation instead of updating progress
* @param indeterminate true if indeterminate
*/
public void setIndeterminate(boolean indeterminate);
@@ -114,11 +116,22 @@ public interface TaskMonitor {
public boolean isIndeterminate();
/**
- * Check to see if this monitor has been canceled
+ * (Use {@link #checkCancelled()} instead)
+ *
+ * Check to see if this monitor has been cancelled.
* @throws CancelledException if monitor has been cancelled
*/
public void checkCanceled() throws CancelledException;
+ /**
+ * Check to see if this monitor has been cancelled
+ * @throws CancelledException if monitor has been cancelled
+ */
+ public default void checkCancelled() throws CancelledException {
+ // note: call checkCanceled() until it is removed; this produces the least number of changes
+ checkCanceled();
+ }
+
/**
* A convenience method to increment the current progress by the given value
* @param incrementAmount The amount by which to increment the progress
@@ -126,10 +139,8 @@ public interface TaskMonitor {
public void incrementProgress(long incrementAmount);
/**
- * Returns the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value
- * set
- * @return the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value
- * set
+ * Returns the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value set
+ * @return the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value set
*/
public long getProgress();
@@ -163,9 +174,17 @@ public interface TaskMonitor {
public boolean isCancelEnabled();
/**
+ * (Use {@link #clearCancelled()} instead)
+ *
* Clear the cancellation so that this TaskMonitor may be reused - * */ public void clearCanceled(); + /** + * Clear the cancellation so that this TaskMonitor may be reused + */ + public default void clearCancelled() { + // note: call clearCanceled() until it is removed; this produces the least number of changes + clearCanceled(); + } }