ProgressHandle


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.api.progress;
21  
22  import javax.swing.JComponent  ;
23  import javax.swing.JLabel  ;
24  import org.netbeans.progress.spi.InternalHandle;
25  
26  /**
27   * Instances provided by the ProgressHandleFactory allow the users of the API to
28   * notify the progress bar UI about changes in the state of the running task.
29   * Progress component will be visualized only after one of the start() methods.
30   * @author Milos Kleint (mkleint@netbeans.org)
31   */
32  public final class ProgressHandle {
33      private InternalHandle internal;
34      /** Creates a new instance of ProgressHandle */
35      ProgressHandle(InternalHandle internal) {
36          this.internal = internal;
37      }
38  
39      
40      /**
41       * start the progress indication for indeterminate task. 
42       * it will be visualized by a progress bar in indeterminate mode.
43       * 
44       */
45      public void start() {
46          start(0, -1);
47      }
48      
49      /**
50       * start the progress indication for a task with known number of steps.
51       * @param workunits total number of workunits that will be processed
52       */
53      public void start(int workunits) {
54         start(workunits, -1); 
55      }
56      
57      
58      /**
59       * start the progress indication for a task with known number of steps and known
60       * time estimate for completing the task.
61       * @param workunits total number of workunits that will be processed
62       * @param estimate estimated time to process the task in seconds
63       */
64      
65      public void start(int workunits, long estimate) {
66         internal.start("", workunits, estimate);
67      }
68  
69  
70      /**
71       * Currently determinate task (with percentage or time estimate) can be 
72       * switched to indeterminate mode.
73       */
74      public void switchToIndeterminate() {
75          internal.toIndeterminate();
76      }
77      
78      /**
79       * Currently running task can switch to silent suspend mode where the progress bar 
80       * stops moving, hides completely or partially. Useful to make progress in status bar less intrusive 
81       * for very long running tasks, eg. running an ant script that executes user application, debugs user application etc.
82       * Any incoming progress wakes up the progress bar to previous state.
83       * @param message a message to display in the silent mode
84       * @since org.netbeans.api.progress/1 1.9
85       */
86      public void suspend(String   message) {
87          internal.toSilent(message);
88      }
89      
90      /**
91       * Currently indeterminate task can be switched to show percentage completed.
92       * A common usecase is to calculate the amount of work in the beginning showing 
93       * in indeterminate mode and later switch to the progress with known steps
94       * @param workunits a definite number of complete units of work out of the total
95       */
96      public void switchToDeterminate(int workunits) {
97          internal.toDeterminate(workunits, -1);
98      }
99      
100     /**
101      * Currently indeterminate task can be switched to show the time estimate til completion.
102      * A common usecase is to calculate the amount of work in the beginning 
103      * in indeterminate mode and later switch to the progress with the calculated estimate.
104      * @param workunits a definite number of complete units of work out of the total
105      * @param estimate estimated time to process the task, in seconds
106      */
107     public void switchToDeterminate(int workunits, long estimate) {
108         internal.toDeterminate(workunits, estimate);
109     }
110     
111     /**
112      * finish the task, remove the task's component from the progress bar UI.
113      */
114     public void finish() {
115         internal.finish();
116     }
117     
118     
119     /**
120      * Notify the user about completed workunits.
121      * @param workunit a cumulative number of workunits completed so far
122      */
123     public void progress(int workunit) {
124         progress(null, workunit);
125     }
126     
127     /**
128      * Notify the user about progress by showing message with details.
129      * @param message details about the status of the task
130      */
131     public void progress(String   message) {
132         progress(message, InternalHandle.NO_INCREASE);
133     }
134     
135     /**
136      * Notify the user about completed workunits and show additional detailed message.
137      * @param message details about the status of the task
138      * @param workunit a cumulative number of workunits completed so far
139      */
140     public void progress(String   message, int workunit) {
141         internal.progress(message, workunit);
142     }
143     
144 
145     /**
146      * Set a custom initial delay for the progress task to appear in the status bar.
147      * This delay marks the time between starting of the progress handle
148      * and its appearance in the status bar. If it finishes earlier, it's not shown at all.
149      * There is a default &lt; 1s value for this. If you want it to appear earlier or later,
150      * call this method with the value you prefer <strong>before {@linkplain #start() starting}</strong> the handle.
151      * (Has no effect if called after the handle is started.)
152      * <p> Progress bars that are placed in custom dialogs do always appear right away without a delay.
153      * @param millis number of miliseconds to wait before the progress appears in status bar.
154      * @since org.netbeans.api.progress/1 1.2
155      */
156     public void setInitialDelay(int millis) {
157        internal.setInitialDelay(millis); 
158     }
159     
160     /**
161      * change the display name of the progress task. Use with care, please make sure the changed name is not completely different,
162      * or otherwise it might appear to the user as a different task.
163      * @param newDisplayName a new name to set for the task
164      * @since org.netbeans.api.progress 1.5
165      */
166     public void setDisplayName(String   newDisplayName) {
167         internal.requestDisplayNameChange(newDisplayName);
168     }
169     
170     /**
171      * have the component in custom location, don't include in the status bar.
172      */
173     JComponent   extractComponent() {
174         return internal.extractComponent();
175     }
176 
177     /**
178      * for unit testing only..
179      * @deprecated for unit testing only.
180      */
181     @Deprecated  
182     InternalHandle getInternalHandle() {
183         return internal;
184     }
185 
186     JLabel   extractDetailLabel() {
187         return internal.extractDetailLabel();
188     }
189 
190     JLabel   extractMainLabel() {
191         return internal.extractMainLabel();
192     }
193     
194 
195 }
196
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags