001/* ProgressMonitor.java --
002   Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.swing;
039
040import java.awt.Component;
041import java.awt.event.ActionEvent;
042import java.awt.event.ActionListener;
043
044import 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 */
065public 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}