001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.progress;
043:
044: import java.util.logging.Level;
045: import java.util.logging.Logger;
046: import javax.swing.JComponent;
047: import javax.swing.JLabel;
048: import org.netbeans.progress.spi.InternalHandle;
049:
050: /**
051: * Instances provided by the ProgressHandleFactory allow the users of the API to
052: * notify the progress bar UI about changes in the state of the running task.
053: * Progress component will be visualized only after one of the start() methods.
054: * @author Milos Kleint (mkleint@netbeans.org)
055: */
056: public final class ProgressHandle {
057:
058: private static final Logger LOG = Logger
059: .getLogger(ProgressHandle.class.getName());
060:
061: private InternalHandle internal;
062:
063: /** Creates a new instance of ProgressHandle */
064: ProgressHandle(InternalHandle internal) {
065: LOG.fine(internal.getDisplayName());
066: this .internal = internal;
067: }
068:
069: /**
070: * start the progress indication for indeterminate task.
071: * it will be visualized by a progress bar in indeterminate mode.
072: *
073: */
074: public void start() {
075: start(0, -1);
076: }
077:
078: /**
079: * start the progress indication for a task with known number of steps.
080: * @param workunits total number of workunits that will be processed
081: */
082: public void start(int workunits) {
083: start(workunits, -1);
084: }
085:
086: /**
087: * start the progress indication for a task with known number of steps and known
088: * time estimate for completing the task.
089: * @param workunits total number of workunits that will be processed
090: * @param estimate estimated time to process the task in seconds
091: */
092:
093: public void start(int workunits, long estimate) {
094: internal.start("", workunits, estimate);
095: }
096:
097: /**
098: * Currently determinate task (with percentage or time estimate) can be
099: * switched to indeterminate mode.
100: */
101: public void switchToIndeterminate() {
102: internal.toIndeterminate();
103: }
104:
105: /**
106: * Currently running task can switch to silent suspend mode where the progress bar
107: * stops moving, hides completely or partially. Useful to make progress in status bar less intrusive
108: * for very long running tasks, eg. running an ant script that executes user application, debugs user application etc.
109: * Any incoming progress wakes up the progress bar to previous state.
110: * @param message a message to display in the silent mode
111: * @since org.netbeans.api.progress/1 1.9
112: */
113: public void suspend(String message) {
114: LOG.log(Level.FINE, "{0}: {1}", new Object[] {
115: internal.getDisplayName(), message });
116: internal.toSilent(message);
117: }
118:
119: /**
120: * Currently indeterminate task can be switched to show percentage completed.
121: * A common usecase is to calculate the amount of work in the beginning showing
122: * in indeterminate mode and later switch to the progress with known steps
123: * @param workunits a definite number of complete units of work out of the total
124: */
125: public void switchToDeterminate(int workunits) {
126: internal.toDeterminate(workunits, -1);
127: }
128:
129: /**
130: * Currently indeterminate task can be switched to show the time estimate til completion.
131: * A common usecase is to calculate the amount of work in the beginning
132: * in indeterminate mode and later switch to the progress with the calculated estimate.
133: * @param workunits a definite number of complete units of work out of the total
134: * @param estimate estimated time to process the task, in seconds
135: */
136: public void switchToDeterminate(int workunits, long estimate) {
137: internal.toDeterminate(workunits, estimate);
138: }
139:
140: /**
141: * finish the task, remove the task's component from the progress bar UI.
142: */
143: public void finish() {
144: internal.finish();
145: }
146:
147: /**
148: * Notify the user about completed workunits.
149: * @param workunit a cumulative number of workunits completed so far
150: */
151: public void progress(int workunit) {
152: progress(null, workunit);
153: }
154:
155: /**
156: * Notify the user about progress by showing message with details.
157: * @param message details about the status of the task
158: */
159: public void progress(String message) {
160: progress(message, InternalHandle.NO_INCREASE);
161: }
162:
163: /**
164: * Notify the user about completed workunits and show additional detailed message.
165: * @param message details about the status of the task
166: * @param workunit a cumulative number of workunits completed so far
167: */
168: public void progress(String message, int workunit) {
169: LOG.log(Level.FINE, "{0}: {1}", new Object[] {
170: internal.getDisplayName(), message });
171: internal.progress(message, workunit);
172: }
173:
174: /**
175: * Set a custom initial delay for the progress task to appear in the status bar.
176: * This delay marks the time between starting of the progress handle
177: * and its appearance in the status bar. If it finishes earlier, it's not shown at all.
178: * There is a default < 1s value for this. If you want it to appear earlier or later,
179: * call this method with the value you prefer <strong>before {@linkplain #start() starting}</strong> the handle.
180: * (Has no effect if called after the handle is started.)
181: * <p> Progress bars that are placed in custom dialogs do always appear right away without a delay.
182: * @param millis number of miliseconds to wait before the progress appears in status bar.
183: * @since org.netbeans.api.progress/1 1.2
184: */
185: public void setInitialDelay(int millis) {
186: internal.setInitialDelay(millis);
187: }
188:
189: /**
190: * change the display name of the progress task. Use with care, please make sure the changed name is not completely different,
191: * or otherwise it might appear to the user as a different task.
192: * @param newDisplayName a new name to set for the task
193: * @since org.netbeans.api.progress 1.5
194: */
195: public void setDisplayName(String newDisplayName) {
196: LOG.fine(newDisplayName);
197: internal.requestDisplayNameChange(newDisplayName);
198: }
199:
200: /**
201: * have the component in custom location, don't include in the status bar.
202: */
203: JComponent extractComponent() {
204: return internal.extractComponent();
205: }
206:
207: /**
208: * for unit testing only..
209: * @deprecated for unit testing only.
210: */
211: @Deprecated
212: InternalHandle getInternalHandle() {
213: return internal;
214: }
215:
216: JLabel extractDetailLabel() {
217: return internal.extractDetailLabel();
218: }
219:
220: JLabel extractMainLabel() {
221: return internal.extractMainLabel();
222: }
223:
224: }
|