com.sun.jbi.bc.common.window.progress

com.sun.jbi.bc.common.window.progress (henceforth Progress) is a library package that simplifies the creation of a visual task progress display. The library utilizes the NetBeans Progress API and Dialogs API to render a consistent and cleanly manipulable progress display for use by GUI applications in the NetBeans platform.

Progress consists of these principal components:

• ProgressDialogFactory - A factory for vending ProgressDescriptor objects.
• ProgressDescriptor - An object that represents a progress to be tracked. A ProgressDescriptor provides the presentation of the tracking, as well as the means to update the tracked progress.
• ProgressController - A management object thru which the task's progress is marked or canceled.

Applications can use Progress in the following manner.

1. The application obtains a ProgressDescriptor from the ProgressDialogFactory.
2. The application obtains the visual progress tracking component (a java.awt.Component object) from the ProgressDescriptor, and makes it visible via the AWT Event Dispatch thread.
3. The application starts the work to be tracked on another thread. In this thread, a ProgressController is obtained from the ProgressDescriptor, and this object is messaged with updates to the work's progress.
4. If the application wants to support cancelable task, it may also poll the ProgressController at application-specific checkpoints to determine if the user has signaled, thru the visual component, the cancelation of the task. (The application may also programatically cancel the task thru the ProgressController object.)
5. When a task is canceled, either by a user or the application itself, the visual component is dismissed automatically. It is also dismissed when the ProgressController is informed of the completion of the task.
6. At the conclusion of the tracking, the application may query the ProgressController object to determine if it the task completed or was canceled, so it may follow-up accordingly.

Example

Code

package trackertest;

import com.sun.jbi.bc.common.window.progress.ProgressController;
import com.sun.jbi.bc.common.window.progress.ProgressDescriptor;
import com.sun.jbi.bc.common.window.progress.ProgressDialogFactory;
import java.awt.Component;
import java.awt.Window;
import javax.swing.SwingUtilities;

public class Main {
    
    /** Creates a new instance of Main */
    public Main() {
    }
    public static void main(String[] args) {
        
        // Create a ProgressDescriptor
        ProgressDescriptor progress =
            ProgressDialogFactory.createProgressDialog("Sample Process", true);
        
        // This is the control object for updating progress, canceling it, etc.
        final ProgressController tracker = progress.getController();
        
        // This is the visual component that displays the tracking.
        final Component view = progress.getGUIComponent();
        
        // Create thread to do the work being tracked.
        // Since this is a standalone program, I could have skipped creating
        // a separate thread for the task.
        //
        // But as this library is for GUI applications, where all this code
        // would likely be executing in the Event Dispatch thread, I'm pretending
        // that 'main' is executing in the dispatch thread as well.
        Thread process = new Thread(new Runnable() {
            public void run() {
                // Start tracking progress consisting of 4 workunits.
                tracker.start(4);
                
                // Announce task phase, then do it, then check if I should cancel
                tracker.progress("Sub task 1...", 1);
                doSubtask1();
                if (tracker.isCanceled()) {
                    return;
                }
                
                tracker.progress("Sub task 2...", 2);
                doSubtask2();
                if (tracker.isCanceled()) {
                    return;
                }
                
                // Lockout user from being able to cancel the progress
                // from this point on.
                tracker.lockout();
                tracker.progress("Sub task 3...", 3);
                doSubtask3();
                
                tracker.progress("Sub task 4...", 4);
                doSubtask4();
                
                // Task complete!
                tracker.finish();
            }
        });
        
        // In a GUI application, where this code is already running in the event
        // dispatch thread, there would be no need to push the setVisible call
        // like this (and, in fact, it would be wrong to do so).
        SwingUtilities.invokeLater(new Runnable() {
            public void run() {
                view.setVisible(true);
            }
        });
        
        // Start the progressive task
        try {
            process.start();
            process.join();
        } catch (InterruptedException ex) {
            ;
        }

        if (tracker.isCanceled()) {
            // Handle cancelation
        } else {
            // Handle completion
        }
        
        // (Only for the purpose of this example)
        if (view instanceof Window) {
            ((Window) view).dispose();
        }
    }
    private static void doSubtask1() {
        delay(1500);
    }
    private static void doSubtask2() {
        delay(2000);
    }
    private static void doSubtask3() {
        delay(2500);
    }
    private static void doSubtask4() {
        delay(4000);
    }
    private static void delay(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException ex) {
            ;
        }
    }
}

Output

Below: Sub task 2 (screenshot of phase 1 omitted) is underway. Note the cancelation button is still active. If a non-cancelable progress tracking was requested from the ProgressDialogFactory, the button would be grayed out from the start.

http://alaska.stc.com:10000/alaska/attach/BCGUIProgressLibrary/progressdialog2.jpg

Below: Sub task 3 is underway, and now the cancelation button is disabled, as a result of the programmatic call to ProgressController.lockout.

http://alaska.stc.com:10000/alaska/attach/BCGUIProgressLibrary/progressdialog3.jpg

Below: Sub task 4 is underway. Once the cancelation button is disabled via lockout call, it cannot be enabled again for the duration of the progress tracking.

http://alaska.stc.com:10000/alaska/attach/BCGUIProgressLibrary/progressdialog4.jpg

Below: ProgressController.finish has been called. The tracking display will briefly display its indication before automatically dismissing the dialog.

http://alaska.stc.com:10000/alaska/attach/BCGUIProgressLibrary/progressdialog5.jpg

Issues

• Pressing the ESC key causes the dialog to hide itself, which is not desirable. It might be possible to prevent this by using WindowListeners.

This page (revision-1) was last changed on 09-Nov-06 09:42 AM, -0800 by Adapters.

More info...