001// License: GPL. For details, see LICENSE file. 002package org.openstreetmap.josm.gui.progress; 003 004import 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 */ 032public interface ProgressMonitor { 033 034 public interface CancelListener { 035 void operationCanceled(); 036 } 037 038 /** Ticks count used, when no other value is supplied */ 039 int DEFAULT_TICKS = 10000; 040 041 /** 042 * Can be used with {@link #worked(int)} and {@link #createSubTaskMonitor(int, boolean)} to 043 * express that the task should use all remaining ticks 044 */ 045 int ALL_TICKS = -1; 046 047 /** 048 * Starts this progress monitor. Must be called exactly once 049 * Ticks count is set to default value 050 * @param title title text of the task 051 */ 052 void beginTask(String title); 053 054 /** 055 * Starts this progress monitor. Must be called exactly once 056 * @param title title text of the task 057 * @param ticks number of work units (see {@link #setTicksCount(int ticks)}) 058 */ 059 void beginTask(String title, int ticks); 060 061 /** 062 * Finish this progress monitor, close the dialog or inform the parent progress monitor 063 * that it can continue with other tasks. Must be called at least once (if called multiply times 064 * then further calls are ignored) 065 */ 066 void finishTask(); 067 068 /** 069 * Can be used if method receive ProgressMonitor but it's not interested progress monitoring. 070 * Basically replaces {@link #beginTask(String)} and {@link #finishTask()} 071 * 072 * This method can be also used in finally section if method expects that some exception 073 * might prevent it from passing progressMonitor away. If {@link #beginTask(String)} was 074 * already called then this method does nothing. 075 */ 076 void invalidate(); 077 078 /** 079 * Set the total number of work units 080 * @param ticks Number of total work units 081 */ 082 void setTicksCount(int ticks); 083 084 /** 085 * Get the total number of work units 086 * @return Number of total work units 087 */ 088 int getTicksCount(); 089 090 /** 091 * Set the current number of work units 092 * @param ticks Number of work units already done 093 */ 094 void setTicks(int ticks); 095 096 /** 097 * Get the current number of work units 098 * @return Number of work units already done 099 */ 100 int getTicks(); 101 102 /** 103 * Increase number of already done work units by ticks 104 * @param ticks number of ticks to add 105 */ 106 void worked(int ticks); 107 108 /** 109 * Subtask that will show progress running back and forth 110 * @param title Can be {@code null}, in that case task title is not changed 111 */ 112 void indeterminateSubTask(String title); 113 114 /** 115 * Normal subtask 116 * @param title Can be {@code null}, in that case task title is not changed 117 */ 118 void subTask(String title); 119 120 /** 121 * Shows additional text 122 * @param text custom text 123 */ 124 void setCustomText(String text); 125 126 /** 127 * Show extra text after normal task title. Hack for ProgressInputStream to show number of kB already downloaded 128 * @param text extra text 129 */ 130 void setExtraText(String text); 131 132 /** 133 * Creates subtasks monitor. 134 * @param ticks Number of work units that should be done when subtask finishes 135 * @param internal If true then subtask can't modify task title/custom text 136 * @return subtasks monitor 137 */ 138 ProgressMonitor createSubTaskMonitor(int ticks, boolean internal); 139 140 /** 141 * Returns the state of user aborts 142 * @return {@code true} if user aborted operation 143 */ 144 boolean isCanceled(); 145 146 /** 147 * Abort current operation, usually called when user somehow requested an abort 148 */ 149 void cancel(); 150 151 /** 152 * Add listener for user abort action 153 * @param listener the listener for cancel operation 154 */ 155 void addCancelListener(CancelListener listener); 156 157 /** 158 * Remove listener for user abort action 159 * @param listener the listener for cancel operation 160 */ 161 void removeCancelListener(CancelListener listener); 162 163 /** 164 * Appends a message to the log managed by the progress monitor. 165 * 166 * @param message the log message. Ignored if null or white space only. 167 */ 168 void appendLogMessage(String message); 169 170 /** 171 * Set the task ID of the progress dialog 172 * Should be used only by PleaseWaitRunnable. If taskId {@code <> null} then "In background" button will be shown 173 * @param taskId the task ID 174 */ 175 void setProgressTaskId(ProgressTaskId taskId); 176 177 /** 178 * Returns the task ID of the progress dialog 179 * Should be used only by PleaseWaitRunnable 180 * @return the task ID 181 */ 182 ProgressTaskId getProgressTaskId(); 183 184 /** 185 * Return the parent windows of progress dialog 186 * @return component suitable as parent for dialogs that wants to be shown in front of progress dialog 187 */ 188 Component getWindowParent(); 189}