001    /* ProgressMonitor.java --
002       Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.swing;
039    
040    import java.awt.Component;
041    import java.awt.event.ActionEvent;
042    import java.awt.event.ActionListener;
043    
044    import javax.accessibility.AccessibleContext;
045    
046    /**
047     * <p>Using this class you can easily monitor tasks where you cannot
048     * estimate the duration exactly.</p>
049     *
050     * <p>A ProgressMonitor instance waits until the first time setProgress
051     * is called. When <code>millisToDecideToPopup</code> time elapsed the
052     * instance estimates the duration until the whole operation is completed.
053     * If this duration exceeds <code>millisToPopup</code> a non-modal dialog
054     * with a message and a progress bar is shown.</p>
055     *
056     * <p>The value of <code>millisToDecideToPopup</code> defaults to
057     * <code>500</code> and <code>millisToPopup</code> to
058     * <code>2000</code>.</p>
059     *
060     * @author Andrew Selkirk
061     * @author Robert Schuster (robertschuster@fsfe.org)
062     * @since 1.2
063     * @status updated to 1.2
064     */
065    public class ProgressMonitor
066    {
067    
068      /**
069       * The accessible content for this component
070       */
071      protected AccessibleContext accessibleContext;
072    
073      /**
074       * parentComponent
075       */
076      Component component;
077    
078      /**
079       * note
080       */
081      String note;
082    
083      /**
084       * message
085       */
086      Object message;
087    
088      /**
089       * millisToDecideToPopup
090       */
091      int millisToDecideToPopup = 500;
092    
093      /**
094       * millisToPopup
095       */
096      int millisToPopup = 2000;
097    
098      int min, max, progress;
099    
100      JProgressBar progressBar;
101    
102      JLabel noteLabel;
103    
104      JDialog progressDialog;
105    
106      Timer timer;
107    
108      boolean canceled;
109    
110      /**
111       * Creates a new <code>ProgressMonitor</code> instance.  This is used to
112       * monitor a task and pops up a dialog if the task is taking a long time to
113       * run.
114       *
115       * @param component The parent component of the progress dialog or
116       *                  <code>null</code>.
117       * @param message A constant message object which works in the way it does
118       *                in {@link JOptionPane}.
119       * @param note A string message which can be changed while the operation goes
120       *             on.
121       * @param minimum The minimum value for the operation (start value).
122       * @param maximum The maximum value for the operation (end value).
123       */
124      public ProgressMonitor(Component component, Object message,
125                             String note, int minimum, int maximum)
126      {
127    
128        // Set data.
129        this.component = component;
130        this.message = message;
131        this.note = note;
132    
133        min = minimum;
134        max = maximum;
135      }
136    
137      /**
138       * <p>Hides the dialog and stops any measurements.</p>
139       *
140       * <p>Has no effect when <code>setProgress</code> is not at least
141       * called once.</p>
142       */
143      public void close()
144      {
145        if (progressDialog != null)
146          {
147            progressDialog.setVisible(false);
148          }
149    
150        if (timer != null)
151          {
152            timer.stop();
153            timer = null;
154          }
155      }
156    
157      /**
158       * <p>Updates the progress value.</p>
159       *
160       * <p>When called for the first time this initializes a timer
161       * which decides after <code>millisToDecideToPopup</code> time
162       * whether to show a progress dialog or not.</p>
163       *
164       * <p>If the progress value equals or exceeds the maximum
165       * value the progress dialog is closed automatically.</p>
166       *
167       * @param progress New progress value.
168       */
169      public void setProgress(int progress)
170      {
171        this.progress = progress;
172    
173        // Initializes and starts a timer with a task
174        // which measures the duration and displays
175        // a progress dialog if neccessary.
176        if (timer == null && progressDialog == null)
177          {
178            timer = new Timer(25, null);
179            timer.addActionListener(new TimerListener());
180            timer.start();
181          }
182    
183        // Cancels timer and hides progress dialog if the
184        // maximum value is reached.
185        if (progressBar != null && this.progress >= progressBar.getMaximum())
186          {
187            // The reason for using progressBar.getMaximum() instead of max is that
188            // we want to prevent that changes to the value have any effect after the
189            // progress dialog is visible (This is how the JDK behaves.).
190            close();
191          }
192    
193      }
194    
195      /**
196       * Returns the minimum or start value of the operation.
197       *
198       * @return Minimum or start value of the operation.
199       */
200      public int getMinimum()
201      {
202        return min;
203      }
204    
205      /**
206       * <p>Use this method to set the minimum or start value of
207       * your operation.</p>
208       *
209       * <p>For typical application like copy operation this will be
210       * zero.</p>
211       *
212       * <p>Keep in mind that changing this value after the progress
213       * dialog is made visible has no effect upon the progress bar.</p>
214       *
215       * @param minimum The new minimum value.
216       */
217      public void setMinimum(int minimum)
218      {
219        min = minimum;
220      }
221    
222      /**
223       * Return the maximum or end value of your operation.
224       *
225       * @return Maximum or end value.
226       */
227      public int getMaximum()
228      {
229        return max;
230      }
231    
232      /**
233       * <p>Sets the maximum or end value of the operation to the
234       * given integer.</p>
235       *
236       * @param maximum
237       */
238      public void setMaximum(int maximum)
239      {
240        max = maximum;
241      }
242    
243      /**
244       * Returns whether the user canceled the operation.
245       *
246       * @return Whether the operation was canceled.
247       */
248      public boolean isCanceled()
249      {
250        // The value is predefined to false
251        // and changes only when the user clicks
252        // the cancel button in the progress dialog.
253        return canceled;
254      }
255    
256      /**
257       * Returns the amount of milliseconds to wait
258       * until the ProgressMonitor should decide whether
259       * a progress dialog is to be shown or not.
260       *
261       * @return The duration in milliseconds.
262       */
263      public int getMillisToDecideToPopup()
264      {
265        return millisToDecideToPopup;
266      }
267    
268      /**
269       * Sets the amount of milliseconds to wait until the
270       * ProgressMonitor should decide whether a progress dialog
271       * is to be shown or not.
272       *
273       * <p>This method has no effect when the progress dialog
274       * is already visible.</p>
275       *
276       * @param time The duration in milliseconds.
277       */
278      public void setMillisToDecideToPopup(int time)
279      {
280        millisToDecideToPopup = time;
281      }
282    
283      /**
284       * Returns the number of milliseconds to wait before displaying the progress
285       * dialog.  The default value is 2000.
286       *
287       * @return The number of milliseconds.
288       *
289       * @see #setMillisToPopup(int)
290       */
291      public int getMillisToPopup()
292      {
293        return millisToPopup;
294      }
295    
296      /**
297       * Sets the number of milliseconds to wait before displaying the progress
298       * dialog.
299       *
300       * @param time  the number of milliseconds.
301       *
302       * @see #getMillisToPopup()
303       */
304      public void setMillisToPopup(int time)
305      {
306        millisToPopup = time;
307      }
308    
309      /**
310       * Returns a message which is shown in the progress dialog.
311       *
312       * @return The changeable message visible in the progress dialog.
313       */
314      public String getNote()
315      {
316        return note;
317      }
318    
319      /**
320       * <p>Set the message shown in the progess dialog.</p>
321       *
322       * <p>Changing the note while the progress dialog is visible
323       * is possible.</p>
324       *
325       * @param note A message shown in the progress dialog.
326       */
327      public void setNote(String note)
328      {
329        if (noteLabel != null)
330          {
331            noteLabel.setText(note);
332          }
333        else
334          {
335            this.note = note;
336          }
337      }
338    
339      /**
340       * Internal method that creates the progress dialog.
341       */
342      void createDialog()
343      {
344        // If there is no note we suppress the generation of the
345        // label.
346        Object[] tmp = (note == null) ?
347          new Object[]
348            {
349              message,
350              progressBar = new JProgressBar(min, max)
351            }
352          :
353          new Object[]
354            {
355              message,
356              noteLabel = new JLabel(note),
357              progressBar = new JProgressBar(min, max)
358            };
359    
360        JOptionPane pane = new JOptionPane(tmp, JOptionPane.INFORMATION_MESSAGE);
361    
362        // FIXME: Internationalize the button
363        JButton cancelButton = new JButton("Cancel");
364        cancelButton.addActionListener(new ActionListener()
365        {
366          public void actionPerformed(ActionEvent ae)
367          {
368            canceled = true;
369          }
370        });
371    
372        pane.setOptions(new Object[] { cancelButton });
373    
374        // FIXME: Internationalize the title
375        progressDialog = pane.createDialog(component, "Progress ...");
376        progressDialog.setModal(false);
377        progressDialog.setResizable(true);
378    
379        progressDialog.pack();
380        progressDialog.setVisible(true);
381    
382      }
383    
384      /** An ActionListener implementation which does the measurements
385       * and estimations of the ProgressMonitor.
386       */
387      class TimerListener implements ActionListener
388      {
389        long timestamp;
390    
391        int lastProgress;
392    
393        boolean first = true;
394    
395        TimerListener()
396        {
397           timestamp = System.currentTimeMillis();
398        }
399    
400        public void actionPerformed(ActionEvent ae)
401        {
402           long now = System.currentTimeMillis();
403    
404           if (first)
405           {
406             if ((now - timestamp) > millisToDecideToPopup)
407             {
408               first = false;
409    
410    
411               long expected = (progress - min == 0) ?
412                 (now - timestamp) * (max - min) :
413                 (now - timestamp) * (max - min) / (progress - min);
414    
415               if (expected > millisToPopup)
416               {
417                 createDialog();
418               }
419             }
420             else
421             {
422               // We have not waited long enough to make a decision,
423               // so return and try again when the timer is invoked.
424               return;
425             }
426           }
427           else if (progressDialog != null)
428           {
429             // The progress dialog is being displayed. We now calculate
430             // whether setting the progress bar to the current progress
431             // value would result in a visual difference.
432             int delta = progress - progressBar.getValue();
433    
434             if ((delta * progressBar.getWidth() / (max - min)) > 0)
435             {
436               // At least one pixel would change.
437               progressBar.setValue(progress);
438             }
439           }
440           else
441           {
442             // No dialog necessary
443             timer.stop();
444             timer = null;
445           }
446    
447          timestamp = now;
448        }
449      }
450    
451      /**
452       * Gets the accessible context.
453       *
454       * @return the accessible context.
455       */
456      public AccessibleContext getAccessibleContext()
457      {
458        return accessibleContext;
459      }
460    }