C++ Syntax

void

MKI_DialogUpdateProgress(

const LPCWSTR f_pszText1,

const LPCWSTR f_pszText2,

__int64 f_nDone,

__int64 f_nTotal );

Initializes the text controls and, if existing, the progress indicator of a non-modal progress indication box.

Parameters

Text1

[const LPCWSTR] Text to be displayed in the middle line of the progress indicator. This text should be used to display a numeric indicator like "Object 25 of 100" or at least "Object 25". If Text1 is nullptr, this parameter is ignored, i.e. the current content of the middle line will remain unchanged. Use MKI_ConvertNumberString to convert integers into a string with thousands separators.

Text2

[const LPCWSTR] Text to be displayed in the lower line of the progress indicator. This text should be used to display a size indicator like "30 KiB". Use MKI_ConvertBytesString to convert a byte size into a string with size-dependent formatting. If Text2 is nullptr, this parameter is ignored, i.e. the current content of the lower line will remain unchanged.

Done

[__int64] Number of calculation steps already executed. This value is used to calculate the percent bar's filling level. If Done is less than zero, this parameter is ignored, the percent bar may change if Total is valid.

Total

[__int64] Number of total calculation steps. This value is used to calculate the percent bar's filling level. If Total is 0, the percent bar will be empty. If Total is less than zero, this parameter is ignored, the percent bar may change if Done is valid.

Comment

The progress indicator management uses timer functions to achieve a "smooth" movement of the percent bar. In average, the content of the progress indicator is updated every 1/10 second. Due to this timer management, feel free to call this procedure each time any value changes, there will be no significant performance loss caused by permanent dialog window updates!

If, however, the preparation for this call takes a considerable amount of time (due to assembling texts and converting numerical values to strings), use MKI_DialogProgressIsPending first to check if that effort is called for at this moment.

At the time the progress indicator's content is updated, the application's message queue is checked for a message indicating that the user either pressed the "Cancel" button of the progress indicator or pressed the ESC key to cancel. Use MKI_DialogIsCancelled to determine whether this has occurred.