Progress Bar Overview

[This is preliminary documentation and subject to change.]

During script execution time, you can display a progress bar representing the status (time elapsed relative to time remaining) of the installation. In addition, the approximate time remaining for the install can also be displayed (in minutes and seconds).

Here is an overview on how progress bars work in installer.

• While generating an execution script, MsiEngine keeps track of the total progress ticks anticipated by each action (it does this by intercepting ixoProgressTotal script records, and tallying up the specified tick counts). At the end of script generation, the grand tick total is stored as the last field of the ixoEnd record.
• Once the script starts executing, the ixoHeader execution action seeks to the end of the script, pulls out the progress tick total, and sends a "progress master reset" message via the standard Message function. When the active message handler (either MsiHandler, or the Basic UI message object if no MsiHandler is active) receives this message, it resets its internal progress state, and stores away the progress tick total.
• As each script record is executed, progress messages are sent to the active message handler, each detailing the elapsed number of progress ticks. On each progress message, the MsiHandler (if active) broadcasts a SetProgress ControlEvent to the active dialog (assumed in our discussion to be a modeless dialog, with a ProgressBar control somewhere on it).
• The active dialog receiving the SetProgress event checks the EventMapping table for any controls subscribing to that event. In this case, the ProgressBar on the dialog should be a subscriber, with the "Progress" attribute specified in the Attributes column. If so, the "Progress" attribute of the ProgressBar will be set with the "ticksSoFar" and "totalTicks" values passed along with the SetProgress ControlEvent, and the progress bar advances (all other control types ignore the Progress attribute).
• In addition, on each progress message, the MsiHandler also broadcasts a TimeRemaining ControlEvent. The total time remaining for the install is determined by first determining the dynamic "execution rate", i.e. the total number of ticks elapsed divided by the total time since the "master reset" message. The total ticks remaining divided by the execution rate gives the approximate time remaining.
• When receiving the TimeRemaining ControlEvent, the active dialog again looks in the EventMapping table, this time for any TimeRemaining subscribers. In order to display the time remaining, a Text control should be a subscriber, with the "TimeRemaining" attribute specified in the Attributes column. If so, the "TimeRemaining" attribute of the Text control will be set with the time remaining, in seconds. When this attribute is set on a Text control, that control will automatically look in the UIText table for a parameterized template string named "TimeRemaining". This string should have two parameters, [1] for minutes, and [2] for seconds. A good example for this string would be:
• "Time remaining: {[1] min }[2] sec" (The curly braces specify that if the minutes parameter drops to zero, only the seconds portion will be displayed).
• The Text control then converts the total seconds value to minutes and seconds, inserts these values into the TimeRemaining template string, and displays it. (If the template string is not found in the UIText table, you'll only get "UIText string not found!" message).
• If the Basic UI message handler is active (for example, if "LIMITUI=1" is specified as a property on the command line), the progress bar and "Time Remaining" text field are built in to the basic dialog.