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 = 100; 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 }