BookNBPlatformCookbookCH0210

Contents

NetBeans Platform Cookbook Chapter 02 10

Using Progress Bar

The Progress Bar is known from NetBeans IDE. It is embedded in the status line at the bottom of the main window. Here you can show state of long running tasks. If more tasks are running the user can expand their list. Progress Bar support is provided by Progress API module.

Preparation

The progress bar works in two modes indeterminate and determinate. If you use start() method without parameters you inform the handler to show a progress bar with continuously moving band indicating that it is not known how duration the task will take. But he shows that the task is working.

If you use start(stepscount) or start(stepscount, duration) the handle shows growing progress rectangle and writes ratio of done work in per cent or remaining time.

The user can be showed some messages by progress(message) or progress(message, doneunits) method. This message is visible when the user clicks on the progress bar to expand it.

The ProgressHandle object is informed about done work by progress(done) method. When the finish() method is called progress bar gets hidden.

How to

To make the user informed about task progress first ask the ProgressHandleFactory to create a ProgressHandle instance using createHandle(name) static factory method. Then call its start() method for indeterminate mode. When the task finishes call the finish() method. The progress bar disappears. You can show some messages while the task is executing by progress(message) method - these messages are visible if the user clicks the progress bar to expand it.

Runnable tsk = new Runnable()
   {
      public void run() {
          final ProgressHandle progr =
         ProgressHandleFactory.createHandle("Simple task");
          
          progr.start();
          
          prepareWork(); 
          progr.progress( "List prepared" );
          doLoading();
          progr.progress( "Objects loaded" );
          doBuild();
          progr.progress( "Objects structure built" ); 
          
          progr.finish();
      }

 };
 RequestProcessor.getDefault().post(tsk);

If number of steps or duration is known use start() method with parameters:

public void run() {
     final ProgressHandle progr =
             ProgressHandleFactory.createHandle(
                                "Known steps", this);

     long sleepTime = 1000L * stepDuration;
     int duration = steps * stepDuration;

     if (this.stepDuration == 0) {
         progr.start(steps);
         sleepTime = 2000L;
     } else {
         progr.start(steps, duration);  // steps, seconds
     }

     for (int i = 1; i <= steps && !canceled; i++) {
         processFile(i, sleepTime);
         progr.progress("File " + i + " processed", i);
         System.out.println(" step " + i);
     }

     progr.finish();

 }

If the task implements the Cancellable interface and you pass it into ProgressHandleFactory.createHandle() method the progress bar will show stop task button. The cancel method returns true if the job was successfully canceled, false if job can't be canceled for some reason (see documentation).

image:nbpcook_02_16_progress.png

image:nbpcook_02_17_progress2.png

image:nbpcook_02_18_progress3.png

Figure 2.16 Progress Bar and its modes.


Notes/Tips

Switch mode

If you find out how work units/time the task takes to finish you can switch mode of the ProgressHandle by methods:

switchToDeterminate(int workunits)
switchToDeterminate(int workunits,long estimate)

On the contrary if you consider the estimate work/time is unknown switch the mode to indeterminate one:

switchToIndeterminate()

Hide or suspend

The progress bar can be hidden or suspended if the work is very very long or if it sleeps and it is no need to show it – some other bars can be shown. Every progress wakes it again. Read ProgressHandle.suspend(String message) method documentation.

Fast tasks

If the task can be faster than e. g. one second then showing its progress bar could be useless. The method setInitialDelay(int millis) called before task is started shows the progress bar after delay time. If the task finishes earlier the progress bar is not shown at all.


Text and sources were created under NB 6.8, 7.0, 7.1.x, 7.2.

Navigation

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo