Difference between revisions of "ShowProgressBar"

Latest revision as of 19:19, 11 March 2022

ShowProgressBar(title, text, p)

Declaration:

ShowProgressBar(title, text: Text atomic; p: number atomic)

Description

Displays a dialog with a progress bar. It's a great idea to show a progress bar whenever a calculation may take more than a few seconds so that the end user doesn't worry that the application has got stuck, and, where possible, to give her an idea of how much longer it may take. The «p» parameter denotes "percent complete" of the computation in progress as shown by the bar width. It should be in the range 0 ≤ «p» ≤1. If «p» < 1 it shows a Cancel button to let the user Cancel further computation. When «p» = 1, it shows an OK button. The dialog disappears when you click OK or «p» > 1, or the computation completes without updating the progress bar.

You can use the «text» parameter to indicate progress -- e.g. the name of a file being read, or scenario being computed.

Example

Var xOrig := X;

Var result :=

for n[] := @Scenario do (

ShowProgressBar("Progress", "Computing scenario "&Scenario, (n - 1)/size(Scenario));

WhatIf(Y, X, xOrig[@Scenario = n])

);

ShowProgressBar("Progress", "Done", 1);

result

You can use a progress bar to track your progress through a Dynamic computation:

Dynamic(initial_population,

(ShowProgressBar( "Progress", "Computing a dynamic model, Time = " & Time, (@Time - 1)/size(Time));

population[Time - 1] + births[Time - 1] - deaths[Time - 1] + net_immigration[Time - 1]))

You may find it helpful to show percent completion of the computation. You might use a User-Defined Function:

ShowProgressBar("Progress", "Calculation is " & NumberToText(p, "Percent", 0) & " complete", p)

where p is your measure of percent complete.

Analytica Cloud Platform and ADE

The progress bar works in Analytica Cloud Platform.

When evaluated from in the Analytica Decision Engine (ADE), it calls IAdeUICallbacks::ShowProgressBar(...). From within that callback, the parent application can display a progress bar or other feedback to the end-user. To receive the callback, the parent application must have previously registered the callback with ADE using CAEngine::SetCallbackObject( ). If it has not registered a callback, then ShowProgressBar from ADE does nothing.

@@ Line 2: / Line 2: @@
 [[Category:Doc Status C]] <!-- For Lumina use, do not change -->
-[[image:showProgressBarDialog.jpg]]
-= Declaration =
+== ShowProgressBar(title, text, p) ==
+Declaration:
+:[[ShowProgressBar]](title, text: Text atomic; p: number atomic)
-  ShowProgressBar(title,text:Text atomic; p:number atomic)
+== Description ==
+Displays a dialog with a progress bar.  It's a great idea to show a progress bar whenever a calculation may take more than a few seconds so that the end user doesn't worry that the application has got stuck, and, where possible, to give her an idea of how much longer it may take. The «p» parameter denotes "percent complete" of the computation in progress as shown by the bar width. It should be in the range 0 &le; «p» &le;1. If  «p» < 1 it shows a '''Cancel''' button to let the user '''Cancel''' further computation.  When «p» = 1, it shows an '''OK''' button. The dialog disappears when you click '''OK''' or «p» > 1, or the computation completes without updating the progress bar.
-= Description =
+You can use the «text» parameter to indicate progress -- e.g. the name of a file being read, or scenario being computed.
-Displays or updates a programmable dialog containing a progress bar.  The first time it is called with p<1, the dialog appears.  When 0<=p<1, a Cancel button is displayed and the progress meter is updated to the indicated proportion, allowing computation to continue while it is visible.  If the user presses Cancel, the computation is aborted.  When p=1, an OK button is shown and the dialog waits until OK is pressed to return and then disappears.  The dialog is also removed when p>1 or a computation completes.
-= Example =
+== Example ==
+:<code>Var xOrig := X;</code>
- [[Var..Do|var]] xOrig := X;
+:<code>Var result :=</code>
- [[Var..Do|var]] result :=
+::<code>for n[] := @Scenario do (</code>
-   for n[] := @Scenario do (
+:::<code>ShowProgressBar("Progress", "Computing scenario "&Scenario, (n - 1)/size(Scenario));</code>
-       [[ShowProgressBar]]( "Progress", "Computing Across All Scenarios", (n-1)/size(scenario) );
+:::<code>WhatIf(Y, X, xOrig[@Scenario = n])</code>
-       [[WhatIf]]( Y, X, xOrig[@Scenario=n] )
+::<code>);</code>
-   );
+:<code>ShowProgressBar("Progress", "Done", 1);</code>
- [[ShowProgressBar]]( "Progress", "Done", 1 );
+:<code>result</code>
- result
+:[[image:showProgressBarDialog.jpg]]
 You can use a progress bar to track your progress through a [[Dynamic]] computation:
- [[Dynamic]]( initial_population,
+:<code>Dynamic(initial_population,</code>
-   [[ShowProgressBar]]( "Progress", "Computing a dynamic model, Time=" & Time, (@Time-1)/size(Time) );
+::<code>(ShowProgressBar( "Progress", "Computing a dynamic model, Time = " & Time, (@Time - 1)/size(Time));</code>
-   population[Time-1] + births[Time-1] - deaths[Time-1] + net_immigration[Time-1] )
+::<code>population[Time - 1] + births[Time - 1] - deaths[Time - 1] + net_immigration[Time - 1]))</code>
-You may find it nice to include a textual indication of the percent complete.  A nice way to do this is to introduce a [[User-Defined Function]]:
-  [[User-Defined Functions|Function]] FormatPct( x : number ) := "" & x
+You may find it helpful to show percent completion of the computation.  You might use a [[User-Defined Function]]:
- { Set the number format for this function to Percent }
-Then use:
+:<code>ShowProgressBar("Progress", "Calculation is " & NumberToText(p, "Percent", 0) & " complete", p)</code>
- [[ShowProgressBar]]( "Progress", FormatPct(p) & " Complete", p )
-where ''p'' is your measure of percent complete.
+where <code>p</code> is your measure of percent complete.
-= Analytica Web Player and ADE =
+== Analytica Cloud Platform and ADE ==
-The progress bar does nothing in ADE or Analytica Web Player.  It doesn't hurt anything being there, but the progress bar dialog only appears when evaluated in desktop Analytica.
+The progress bar works in  [[Analytica Cloud Platform]].
-= See Also =
+When evaluated from in [[ADE|the Analytica Decision Engine (ADE)]], it calls [[IAdeUICallbacks::ShowProgressBar]](...). From within that callback, the parent application can display a progress bar or other feedback to the end-user. To receive the callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback, then ShowProgressBar from ADE does nothing.
+== See Also ==
 * [[MsgBox]]
 * When using [[ADE]]: [[IAdeUICallbacks::ShowProgressBar]] and [[IAdeUICallbacks::HideProgressBar]] methods
+* [[Creating Interfaces for End Users]]