COMSOL 6.4 - Progress Methods

Progress Methods

Progress methods are used to create and update progress information in the Status bar, in a progress form object, and in a dialog.


Name	Syntax	Description
setProgressInterval	setProgressInterval(String message, int intervalStart, int intervalEnd)	Sets a progress interval to use for the top-level progress and display message at that level. The top level will go from intervalStart to intervalEnd as the second level goes from 0 to 100. As the second level increases, the top level is increased by (intervalEnd - intervalStart) * (second level progress (0-100) / 100). The value for intervalStart must be between 0 and intervalEnd, and the value for intervalEnd must be between intervalStart and 100. Calling this method implicitly resets any manual progress previously set by calls to setProgress().
setProgress	setProgress(int value, String message)	Sets a value for the user-controlled progress level. By default, this is the top level, but if a progress interval is active (setProgressInterval has been called and resetProgress has not been called after that), then it is the second level.
setProgress	setProgress(int value)	Same as setProgress(message, value), but uses the latest message or an empty string (if no message has been set).
resetProgress	resetProgress()	Removes all progress levels and resets progress to 0 and the message to an empty string.
showIndeterminateProgress	showIndeterminateProgress(String message)	Shows a progress dialog with an indeterminate progress bar, given message and a cancel button.
showIndeterminateProgress	showIndeterminateProgress(String message, boolean cancelButton)	Shows a progress dialog with an indeterminate progress bar, given message and an optional cancel button.
showProgress	showProgress()	Shows a progress dialog with a cancel button. No model progress is included.
showProgress	showProgress(boolean modelProgress)	Shows a progress dialog with a cancel button and an optional model progress.
showProgress	showProgress(boolean modelProgress, boolean addSecondLevel)	Shows a progress dialog with a cancel button, optional model progress, and one or two levels of progress information. Two levels can only be used if modelProgress is true.
showProgress	showProgress(boolean modelProgress, boolean addSecondLevel, boolean cancelButton)	Shows a progress dialog with optional model progress, one or two levels, and possibly a cancel button. Two levels can only be used if modelProgress is true.
closeProgress	closeProgress()	Closes the currently shown progress dialog.
startProgress	startProgress(String name) startProgress(FormObject progressBar)	Resets the value of the given progress bar form object name to 0. The progress bar to control can be specified with an absolute path, such as form1/progressbar1, or a name relative to the context from which the method was called. Nothing is done if no progress bar corresponding to the given name is found.
setProgressBar	setProgressBar(String name, int workDone, String message) setProgressBar(FormObject progressBar, int workDone, String message)	Sets the value of the given progress bar form object name in the range 0-100 and the associated progress message. Values out of range are converted to 0 or 100. The progress bar to control can be specified with an absolute path, such as form1/progressbar1, or a name relative to the context from which the method was called. Nothing is done if no progress bar corresponding to the given name is found, or if the progress bar is used for showing model progress.
setProgressBar	setProgressBar(String name, int workDone) setProgressBar(FormObject progressBar, int workDone)	Same as above, but does not update the progress message.

Example Code

showProgress(true, true, true);

/* Opens a progress dialog with cancel button showing two levels of progress. The values shown in progress dialog will be updated to match the two levels of progress. */

setProgressInterval("Preparing application", 0, 20);

/* Sets the current progress scale to go from 0 to 20. This means that the top-level progress will go from 0 to 20 when second-level progress goes from 0 to 100. */

setProgress(0, "Init step 1");

/* Sets the second-level progress to 0 and the second-level progress message to "Init step 1". */

// do some work

setProgress(40);

/* Sets the second-level progress to 40, this causes the top-level progress to be updated to 8 (40% of 20). */

// do some work

setProgress(80, "Init step 2");

/* Sets the second-level progress to 80 and the progress message to "Init step 2". The top-level message is still "Preparing application" and top-level progress is now 16. */

// do some work

setProgressInterval("Meshing", 20, 40);

/* Sets the top-level interval to 20 - 40 and the progress message to "Meshing" at this point the value shown at the top-level will be 20. The second-level progress is cleared when the top-level interval is changed. */

<call-meshing algorithm here>

/* The progress messages and values from the meshing algorithm are shown at the second-level progress. The top-level progress message will be "Meshing", but the top-level progress advances from 20 to 40 while second-level progress advances from 0 to 100. */

setProgressInterval("Solving", 40, 100);

/* The top-level progress message is changed to "Solving" and its value to 40.

<call-solver>

closeProgress();

Application Progress Information

Progress information can be displayed in three different ways: in the Status bar, in a progress form object, and in a dialog. Application progress information is controlled by the setProgress methods, which take as their input an integer between 0 and 100 and an optional message. The integer represents how far the displayed progress bar has progressed. If no message is supplied, the last message provided is used. For example:

setProgress(10, "Computing data");

setProgress(25);

This will keep Computing data as the progress message.

Use the setProgress method by itself if you want to display custom progress in the task and status bar. Once you have done this, that progress bar will no longer be updated by progress information from the COMSOL model, but will be completely dependent on further calls to setProgress for changes in its value. Precede it with a call to showProgress to also display the built-in progress dialog, see below.

Note that progress information from the COMSOL model will not be shown in between calls to setProgress. Progress is reset between method calls. If you want to combine custom steps of progress in methods with built-in model progress, then use setProgressInterval instead.

With setProgressInterval, you can control the top two levels of progress information. The second level can be displayed in a progress dialog and a progress bar form object, see the code segment below. The second progress level, controlled by your own custom progress calculation, is connected to the first level such that one interval at the top level corresponds to the entire second level. Thus if the interval is 0–50, when the second level progress reaches 40, for example, the first level will be set to 20 (=(40/100)*50).

Important uses of the method setProgressInterval are listed below:

•

Combining calls to the COMSOL model so that you get continuous progress going from 0–100.

•

Computing several studies as well as evaluating several plots. Call setProgressInterval before each call to the built-in methods with an interval that approximates how much time each model computation takes. For example:

setProgressInterval("Computing solution", 0, 80);

model.study("std1").run();

setProgressInterval("Plotting", 80, 100);

useGraphics(model.result("pg3"), "energy_response_plot/graphics1");

•

Combining one or more calls to built-in COMSOL methods with custom methods that in themselves take significant time. In this case, use setProgressInterval as in the previous example, followed by your own custom code with appropriate calls to setProgress. These calls should run from 0 to 100 as they are controlling the second progress level. For example:

setProgressInterval("Computing solution", 0, 60);

model.study("std1").run();

setProgressInterval("Working", 60, 80);

setProgress(0, "Specific message about what I'm doing");

// ...

// Code that does something

// ...

setProgress(60);

If you, in a running application, wish to no longer use progress intervals, call resetProgress to return to the original state. This will also reset progress to 0.

The Progress Dialog

A progress dialog can be used to display application progress as described in the previous section. The progress dialog has the following options:

•

Whether to show model progress or not. When off, no progress from the model part of the application is forwarded to the progress dialog.

•

Whether to show one or two progress levels in the progress dialog.

•

Whether to include a cancel button. Cancel also works for user-defined methods, as it halts execution when the next line in the method is reached.

Use the showProgress methods to enable or disable these options. To close the progress dialog, use the closeProgress method.

You can show a progress dialog with an indeterminate progress bar that keeps spinning until you close the progress dialog. Only one progress dialog can be shown at a time. Use the showIndeterminateProgress methods to display this progress dialog.

The Progress Bar Form Object

The form object can either show overall application progress information or customized partial progress information. If you have selected the checkbox in the window of the node, then the overall application progress information becomes available.

When is selected, the progress bar will show the same information as the progress dialog. That is, one or two levels of progress information and a cancel button, depending on the settings in the form object.

When is cleared, you control the progress bar through the setProgressBar methods. These take the path name of the progress bar form object, for example, main/progressbar1.