Index: /trunk/src/org/openstreetmap/josm/gui/progress/AbstractProgressMonitor.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/AbstractProgressMonitor.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/AbstractProgressMonitor.java (revision 12369) @@ -7,4 +7,7 @@ import java.util.Queue; +/** + * This class contains the progress logic required to implement a {@link ProgressMonitor}. + */ public abstract class AbstractProgressMonitor implements ProgressMonitor { @@ -58,4 +61,8 @@ protected abstract void doSetCustomText(String title); + /** + * Create a new {@link AbstractProgressMonitor} + * @param cancelHandler The handler that gets notified when the process is canceled. + */ protected AbstractProgressMonitor(CancelHandler cancelHandler) { this.cancelHandler = cancelHandler; Index: /trunk/src/org/openstreetmap/josm/gui/progress/CancelHandler.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/CancelHandler.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/CancelHandler.java (revision 12369) @@ -7,4 +7,7 @@ import org.openstreetmap.josm.gui.progress.ProgressMonitor.CancelListener; +/** + * A handler that notifies all listeners that a given operation was canceled. + */ public class CancelHandler { @@ -12,4 +15,7 @@ private final List listeners = new ArrayList<>(); + /** + * Cancels the operation. This call is ignored if the operation was already canceled. + */ public synchronized void cancel() { if (!isCanceled) { @@ -21,12 +27,24 @@ } + /** + * Checks if the operation was canceled + * @return true if {@link #cancel()} was called. + */ public synchronized boolean isCanceled() { return isCanceled; } + /** + * Adds a new cancel listener + * @param listener The listener to add + */ public synchronized void addCancelListener(CancelListener listener) { listeners.add(listener); } + /** + * Removes a cancel listener + * @param listener The listener to remove + */ public synchronized void removeCancelListener(CancelListener listener) { listeners.remove(listener); Index: /trunk/src/org/openstreetmap/josm/gui/progress/ChildProgress.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ChildProgress.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ChildProgress.java (revision 12369) @@ -4,4 +4,7 @@ import java.awt.Component; +/** + * The progress of a sub task + */ public class ChildProgress extends AbstractProgressMonitor { @@ -9,4 +12,10 @@ private final boolean internal; + /** + * Creates a new {@link ChildProgress} + * @param parent The parent task that creates this progress + * @param cancelHandler The cancel handler to notify when this task is canceled + * @param internal this is an internal task that will not modify the text that is displayed to the user + */ public ChildProgress(AbstractProgressMonitor parent, CancelHandler cancelHandler, boolean internal) { super(cancelHandler); @@ -15,8 +24,16 @@ } + /** + * Gets the parent task + * @return The parent task + */ public final AbstractProgressMonitor getParent() { return parent; } + /** + * See if this is an internal task + * @return True if this task should not modify the text that is displayed to the user + */ public final boolean isInternal() { return internal; Index: /trunk/src/org/openstreetmap/josm/gui/progress/PleaseWaitProgressMonitor.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/PleaseWaitProgressMonitor.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/PleaseWaitProgressMonitor.java (revision 12369) @@ -29,4 +29,8 @@ */ public interface ProgressMonitorDialog { + /** + * Sets the visibility of this dialog + * @param visible The visibility, true to show it, false to hide it + */ void setVisible(boolean visible); @@ -37,11 +41,28 @@ void updateProgress(int progress); + /** + * Sets the description of what is done + * @param text The description of the task + */ void setCustomText(String text); + /** + * Sets the current action that is done + * @param text The current action + */ void setCurrentAction(String text); + /** + * Display that the current progress cannot be determined + * @param newValue wether the progress cannot be determined + */ void setIndeterminate(boolean newValue); - // TODO Not implemented properly in background monitor, log message will get lost if progress runs in background + /** + * Append a message to the progress log + *

+ * TODO Not implemented properly in background monitor, log message will get lost if progress runs in background + * @param message The message + */ void appendLogMessage(String message); } @@ -174,8 +195,16 @@ }; + /** + * See if this task is canceleable + * @return true if it can be canceled + */ public final boolean isCancelable() { return cancelable; } + /** + * Sets this task to be cancelable + * @param cancelable Whether it can be canceled + */ public final void setCancelable(boolean cancelable) { this.cancelable = cancelable; @@ -274,4 +303,7 @@ } + /** + * Update the dialog values + */ public void reset() { if (dialog != null) { @@ -294,4 +326,7 @@ } + /** + * Close the progress dialog window. + */ public void close() { doInEDT(() -> { @@ -312,4 +347,7 @@ } + /** + * Show the progress dialog in foreground + */ public void showForegroundDialog() { isInBackground = false; Index: /trunk/src/org/openstreetmap/josm/gui/progress/ProgressException.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ProgressException.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ProgressException.java (revision 12369) @@ -2,6 +2,15 @@ package org.openstreetmap.josm.gui.progress; +/** + * An exception that is thrown by the progress monitor if something went wrong + */ public class ProgressException extends RuntimeException { + /** + * Create a new {@link ProgressException} + * @param message The message + * @param args The arguments for the message string + * @see String#format + */ public ProgressException(String message, Object... args) { super(String.format(message, args)); Index: /trunk/src/org/openstreetmap/josm/gui/progress/ProgressMonitor.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ProgressMonitor.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ProgressMonitor.java (revision 12369) @@ -34,6 +34,12 @@ public interface ProgressMonitor { + /** + * A listener that listens to cancel events on the progress monitor + */ @FunctionalInterface interface CancelListener { + /** + * Called when the operation was canceled + */ void operationCanceled(); } Index: /trunk/src/org/openstreetmap/josm/gui/progress/ProgressRenderer.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ProgressRenderer.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ProgressRenderer.java (revision 12369) @@ -5,15 +5,35 @@ * Swing components can implement this interface and use a {@link SwingRenderingProgressMonitor} * to render progress information. - * */ public interface ProgressRenderer { + /** + * Sets the title to display + * @param taskTitle The title text + */ void setTaskTitle(String taskTitle); + /** + * Sets the custom text below the title + * @param message The message + */ void setCustomText(String message); + /** + * Display the value as indeterminate value (unknown progress) + * @param indeterminate true if the progress is unknown + */ void setIndeterminate(boolean indeterminate); + /** + * Sets the maximum possible progress + * @param maximum The minimum value + */ void setMaximum(int maximum); + /** + * Sets the current progress + * @param value The progress, in range 0...maximum + * @see #setMaximum(int) + */ void setValue(int value); } Index: /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskId.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskId.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskId.java (revision 12369) @@ -4,12 +4,24 @@ import java.util.Objects; +/** + * The ID of a progress task. It is required to run tasks in background + */ public class ProgressTaskId { private final String id; + /** + * Create a new {@link ProgressTaskId} + * @param component The JOSM component name that creates this id + * @param task The task name + */ public ProgressTaskId(String component, String task) { this.id = component + '.' + task; } + /** + * Gets the id + * @return The task id + */ public String getId() { return id; Index: /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskIds.java =================================================================== --- /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskIds.java (revision 12368) +++ /trunk/src/org/openstreetmap/josm/gui/progress/ProgressTaskIds.java (revision 12369) @@ -2,7 +2,17 @@ package org.openstreetmap.josm.gui.progress; +/** + * The default {@link ProgressTaskId}s used in JOSM + */ public interface ProgressTaskIds { + /** + * Download GPS data + */ ProgressTaskId DOWNLOAD_GPS = new ProgressTaskId("core", "downloadGps"); + + /** + * Download WMS data along a gps line + */ ProgressTaskId PRECACHE_WMS = new ProgressTaskId("core", "precacheWms");