001 // License: GPL. For details, see LICENSE file.
002 package org.openstreetmap.josm.gui.progress;
003
004 import java.awt.Component;
005
006 /**
007 * Typical use case is:
008 * <pre>
009 * monitor.beginTask()
010 * try {
011 * .. do some work
012 * monitor.worked()
013 * monitor.subTask()/monitor.intermediateTask()
014 * .. do some work
015 * monitor.worked()
016 * } finally {
017 * monitor.finishTask();
018 * }
019 * </pre>
020 *
021 * {@link #subTask(String)} and {@link #indeterminateSubTask(String)} has nothing to do with logical
022 * structure of the work, they just show task title to the user.
023 *
024 * If task consists of multiple tasks then {@link #createSubTaskMonitor(int, boolean)} may be used. It
025 * will create new ProgressMonitor, then can be passed to the subtask. Subtask doesn't know whether
026 * it runs standalone or as a part of other task. Progressbar will be updated so that total progress is
027 * shown, not just progress of the subtask
028 *
029 * All ProgressMonitor implementations should be thread safe.
030 *
031 */
032 public interface ProgressMonitor {
033
034 public interface CancelListener {
035 void operationCanceled();
036 }
037
038 public final int DEFAULT_TICKS = 10000;
039
040 /**
041 * Can be used with {@link #worked(int)} and {@link #createSubTaskMonitor(int, boolean)} to
042 * express that the task should use all remaining ticks
043 */
044 public final int ALL_TICKS = -1;
045
046 void beginTask(String title);
047
048 /**
049 * Starts this progress monitor. Must be called exactly once
050 * @param title
051 * @param ticks
052 */
053 void beginTask(String title, int ticks);
054
055 /**
056 * Finish this progress monitor, close the dialog or inform the parent progress monitor
057 * that it can continue with other tasks. Must be called at least once (if called multiply times
058 * then further calls are ignored)
059 */
060
061 void finishTask();
062 /**
063 * Can be used if method receive ProgressMonitor but it's not interested progress monitoring.
064 * Basically replaces {@link #beginTask(String)} and {@link #finishTask()}
065 *
066 * This method can be also used in finally section if method expects that some exception
067 * might prevent it from passing progressMonitor away. If {@link #beginTask(String)} was
068 * already called then this method does nothing.
069 */
070 void invalidate();
071
072 /**
073 *
074 * @param ticks Number of total work units
075 */
076 void setTicksCount(int ticks);
077 /**
078 *
079 * @param ticks Number of work units already done
080 */
081 void setTicks(int ticks);
082
083 int getTicks();
084 int getTicksCount();
085
086 /**
087 * Increase number of already done work units by ticks
088 * @param ticks
089 */
090 void worked(int ticks);
091
092 /**
093 * Subtask that will show progress running back and forth
094 * @param title Can be null, in that case task title is not changed
095 */
096 void indeterminateSubTask(String title);
097 /**
098 * Normal subtask
099 * @param title Can be null, in that case task title is not changed
100 */
101 void subTask(String title);
102 /**
103 * Shows additional text
104 */
105 void setCustomText(String text);
106 /**
107 * Show extra text after normal task title. Hack for ProgressInputStream to show number of kB
108 * already downloaded
109 * @param text
110 */
111 void setExtraText(String text);
112
113 /**
114 * Creates subtasks monitor.
115 * @param ticks Number of work units that should be done when subtask finishes
116 * @param internal If true then subtask can't modify task title/custom text
117 * @return
118 */
119 ProgressMonitor createSubTaskMonitor(int ticks, boolean internal);
120
121 boolean isCanceled();
122 void cancel();
123 void addCancelListener(CancelListener listener);
124 void removeCancelListener(CancelListener listener);
125
126 /**
127 * Appends a message to the log managed by the progress monitor.
128 *
129 * @param message the log message. Ignored if null or white space only.
130 */
131 void appendLogMessage(String message);
132
133 /**
134 * Should be used only by PleaseWaitRunnable. If taskId <> null then "In background" button will be shown
135 * @param taskId
136 */
137 void setProgressTaskId(ProgressTaskId taskId);
138
139 /**
140 * Should be used only by PleaseWaitRunnable
141 * @param taskId
142 */
143 ProgressTaskId getProgressTaskId();
144
145 /**
146 *
147 * @return component suitable as parent for dialogs that wants to be shown in front of progress dialog
148 */
149 Component getWindowParent();
150 }