Summary

Synopsis

This article demonstrates how to control the Progress Bar at runtime from a Custom Code Action.

Discussion

It is possible to increment the Progress Bar being displayed programmatically from a Custom Code Action. This article will demonstrate how to accomplish this as well as point out some differences in behavior if the action is sequenced in the Install sequence or one of the Pre or Post Install sequences.

A sample custom action is included with the InstallAnywhere IDE which demonstrates how to manipulate the Progress Bar. That sample can be found at:

<IA_HOME>\CustomCode\Samples\SampleProgress

The SampleProgress.htm found at this location has a brief description of the action. The actual source for the action found at:

<IA_HOME>\CustomCode\Samples\SampleProgress\com\zerog\ia\plugins\progress\SampleProgress.java

contains additional comments which describe the behavior. The sample included in this article has been modified slightly from the example. The source is included in the Additional Information section below for reference as well as in the attached Jar file. The attached Jar file includes the compiled class file. The class was compiled at a 1.5 level and therefore will only run with JVMs of version 1.5 and above.

Pre or Post Install Sequences

In order to use the action in either of the Pre or Post Install sequences, add two IA Actions to the project in the sequence where the action should be executed. First add a Set InstallAnywhere Variable Single Action. Next, add an Execute Custom Code Action at some point after the Set InstallAnywhere Variable Single action in the sequence. The Set InstallAnywhere Variable Action is used to set an IA Variable which controls how many seconds the Custom Action will take to execute. Use this Action to set the IA Variable:

$PROGRESS_SECONDS$

to the number of seconds the action should take to execute. The screenshot below shows the variable being set to 5 seconds.

When the action is scheduled to execute in the Install sequence, the behavior is slightly different than if it executes in the Pre or Post Install sequence. Rather than the action controlling the Progress Bar from 0% to 100%, the action is given a section of the Progress Bar, or ?slice?, which represents its portion of the entire Install sequence. How large or small of a ?slice? the action is given depends on the number returned by the action?s getEstimatedTimeToInstall() method. This method should return the approximate amount of time, in tenths of seconds, which the action will take to execute. The larger this number is compared to the total time the Install sequence is estimated to require the larger the ?slice? this action will be assigned.

The action included with this article returns 10 times the resolved value of the $PROGRESS_SECONDS$ IA Variable to represent this amount of time in tenths of a second. As in the Pre or Post Install Sequence above, the $PROGRESS_SECONDS$ IA Variable must be set to the number of seconds this action should take to execute in order for the action to execute properly.

To add this action to the Install Sequence, an Execute Custom Code Action should be added to the sequence and configured as explained in the Pre or Post Install Sequence example above. If the IA Variable $PROGRESS_SECONDS$ has not been set previously, be sure to add a Set InstallAnywhere Variable Single Action before the Execute Custom Code Action and set the $PROGRESS_SECONDS$ variable to the number of seconds.

General Explanation of the Code

The install method of the attached action first resolves the value of the $PROGRESS_SECONDS$ IA Variable and instantiates a new Integer object with the value. It then calls the showProgress() method passing the InstallerProxy object passed to the install() method as well as the int value of the Integer representing the number of seconds the action should take to execute.

The actual manipulation of the Progress Bar takes place in the showProgress() method. The method first determine the amount of time the action should sleep during each iteration of the for loop. The for loop executes 100 times, incrementing the Progress Bar 1% each time, therefore, the action should sleep 1/100th of the total amount of time the action is estimated to require each time through the loop. Since the number passed to the sleep method is in thousandths of a second, this is determined by the following:

seconds * 1000 / 100

which simplifies to:

seconds * 10

The code sets a variable of type long named increment to this value.

Next, the action uses the various setProgress*() methods to set the title, description, and then initializes the percentage complete to 0%. Finally, the for loop executes 100 times. In each iteration of the for loop the following occurs:

1.) The percentage complete of the Progress Bar is set to the value of the variable being incremented by the loop (from 0 to 100).

2.) The Progress Bar Status Text is updated to indicate the percentage complete.

3.) The code then sleeps for the time defined by the increment variable.

After 100 iterations of this loop, the action is complete and exits.

Additional Information

import com.zerog.ia.api.pub.CustomCodeAction;

import com.zerog.ia.api.pub.InstallException;

import com.zerog.ia.api.pub.InstallerProxy;

import com.zerog.ia.api.pub.ProgressAccess;

import com.zerog.ia.api.pub.UninstallerProxy;

public class ProgressTest extends CustomCodeAction {

@Override

public void install(InstallerProxy ip) throws InstallException {

// TODO Auto-generated method stub

Integer seconds = new Integer(ip.substitute("$PROGRESS_SECONDS$"));

showProgress(ip, seconds.intValue());

}

@Override

public void uninstall(UninstallerProxy up) throws InstallException {

// TODO Auto-generated method stub

}

@Override

public String getInstallStatusMessage() {

// TODO Auto-generated method stub

return "Progress Sample";

}

@Override

public String getUninstallStatusMessage() {

// TODO Auto-generated method stub

return getInstallStatusMessage();

}

public long getEstimatedTimeToInstall(InstallerProxy ip) {

Long time = new Long(ip.substitute("$PROGRESS_SECONDS$"));

return time.longValue()*10;

}

private void showProgress(ProgressAccess progressAccess, int seconds) {

//Set increment to number of milliseconds divided by 100

long increment = seconds*10;

progressAccess.setProgressTitle("Show Progress");

progressAccess.setProgressDescription("This action is testing progress interaction for "+seconds+" seconds");

progressAccess.setProgressPercentage(0);

for (int i = 1; i <= 100; i++) {

progressAccess.setProgressPercentage((float) i);

progressAccess.setProgressStatusText("My progress is " + i);

try {

Thread.sleep(increment);

} catch (InterruptedException e) {

// Noop

}

}

}

}