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    }