Progress Bar Control

Progress Bar Control


A progress bar is a window that an application can use to indicate the progress of a lengthy operation. It consists of a rectangle that is gradually filled with the system highlight color as an operation progresses. The following illustration shows a progress bar positioned along the bottom of a window.

Progress bar positioned along the bottom of a window.

arrowy.gifUsing Progress Bars

arrowy.gifProgress Bar Control Updates in Internet Explorer

arrowy.gifProgress Bar Control Reference

Using Progress Bars

You create a progress bar by using the CreateWindowEx function, specifying the PROGRESS_CLASS window class. This window class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControls function first.

Range and Current Position

A progress bar's range represents the entire duration of the operation, and the current position represents the progress that the application has made toward completing the operation. The window procedure uses the range and the current position to determine the percentage of the progress bar to fill with the highlight color as well as to determine the text, if any, to display within the progress bar. Because the range and current position values are expressed as unsigned integers, the highest possible range or current position value is 65,535.

The minimum value in the range can be from 0 to 65,535. Likewise, the maximum value can be from 0 to 65,535. If you do not set the range values, the system sets the minimum value to 0 and the maximum value to 100. You can adjust the range to convenient integers by using the PBM_SETRANGE message.

A progress bar provides several messages that you can use to set the current position. The PBM_SETPOS message sets the position to a given value. The PBM_DELTAPOS message advances the position by adding a specified value to the current position.

The PBM_SETSTEP message allows you to specify a step increment for a progress bar. Subsequently, whenever you send the PBM_STEPIT message to the progress bar, the current position advances by the specified increment. By default, the step increment is set to 10.

Default Progress Bar Message Processing

This section describes the messages handled by the window procedure for the PROGRESS_CLASS class.
Message Processing performed
WM_CREATE Allocates and initializes an initial structure.
WM_DESTROY Frees all resources associated with the progress bar.
WM_ERASEBKGND Draws the background and borders of the progress bar.
WM_GETFONT Returns the handle to the font that the progress bar is currently using to draw text.
WM_PAINT Draws the progress bar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFONT Saves the handle to the new font and returns the handle to the previous font.

Progress Bar Example

The following example shows how to use a progress bar to indicate the progress of a lengthy file-parsing operation. The example creates a progress bar and positions it along the bottom of the parent window's client area. The height of the progress bar is based on the height of the arrow bitmap used in a scroll bar. The range is based on the size of the file divided by 2048, which is the size of each "chunk" of data read from the file. The example also sets an increment and advances the current position of the progress bar by the increment after parsing each chunk.

	// ParseALargeFile - parses a large file and uses a progress bar to 
	//   indicate the progress of the parsing operation. 
	// Returns TRUE if successful, or FALSE otherwise. 
	// hwndParent - parent window of the progress bar. 
	// lpszFileName - name of the file to parse. 
	// 
	// Global variable 
	//     g_hinst - instance handle 
	extern HINSTANCE g_hinst; 
 
	BOOL ParseALargeFile(HWND hwndParent, LPSTR lpszFileName) 
	{ 
	    RECT rcClient;  // client area of parent window 
    int cyVScroll;  // height of scroll bar arrow 
    HWND hwndPB;    // handle of progress bar 
    HANDLE hFile;   // handle of file 
    DWORD cb;       // size of file and count of bytes read 
    LPCH pch;       // address of data read from file 
    LPCH pchTmp;    // temporary pointer 
 
    // Ensure that the common control DLL is loaded and create a 
    // progress bar along the bottom of the client area of the 
    // parent window. Base the height of the progress bar on 
    // the height of a scroll bar arrow. 
    InitCommonControls(); 
    GetClientRect(hwndParent, &rcClient); 
    cyVScroll = GetSystemMetrics(SM_CYVSCROLL); 
    hwndPB = CreateWindowEx(0, PROGRESS_CLASS, (LPSTR) NULL, 
        WS_CHILD | WS_VISIBLE, rcClient.left, 
        rcClient.bottom - cyVScroll, 
        rcClient.right, cyVScroll, 
        hwndParent, (HMENU) 0, g_hinst, NULL); 
 
    // Open the file for reading, and retrieve the size of the file. 
    hFile = CreateFile(lpszFileName, GENERIC_READ, FILE_SHARE_READ, 
        (LPSECURITY_ATTRIBUTES) NULL, OPEN_EXISTING, 
        FILE_ATTRIBUTE_NORMAL, (HANDLE) NULL); 
 
    if (hFile == (HANDLE) INVALID_HANDLE_VALUE) 
        return FALSE; 
 
    cb = GetFileSize(hFile, (LPDWORD) NULL); 
 
    // Set the range and increment of the progress bar. 
    SendMessage(hwndPB, PBM_SETRANGE, 0, MAKELPARAM(0, cb / 2048)); 
    SendMessage(hwndPB, PBM_SETSTEP, (WPARAM) 1, 0); 
 
    // Parse the file. 
    pch = (LPCH) LocalAlloc(LPTR, sizeof(char) * 2048); 
    pchTmp = pch; 
    do { 
        ReadFile(hFile, pchTmp, sizeof(char) * 2048, &cb, 
            (LPOVERLAPPED) NULL); 
        . 
        . // Include here any code that parses the file. 
        . 
 
        // Advance the current position of the progress bar 
        // by the increment. 
        SendMessage(hwndPB, PBM_STEPIT, 0, 0); 
    } while (cb); 
    CloseHandle((HANDLE) hFile); 
 
    DestroyWindow(hwndPB); 
    return TRUE; 
	} 
 

Progress Bar Control Updates in Internet Explorer

Progress bar controls in Microsoft® Internet Explorer support the following new features.

New Progress Bar Control Styles
Progress bar controls can now display progress information vertically, using the PBS_VERTICAL style. Also, a smooth progress mode is supported using the PBS_SMOOTH style. Using the PBS_SMOOTH style causes the control to display a contiguous progress bar instead of a segmented bar.
Extended Range Values
Progress bar controls now support 32-bit range values. To set range values in excess of 65,535, use the PBM_SETRANGE32 message. To retrieve 32-bit range values, use the PBM_GETRANGE message. The progress bar high limit, low limit, and position parameters are signed integers. To make full use of the 32-bit range, set the range to -0x7FFFFFFF to 0x7FFFFFFF and treat the position as a signed integer.
Programmable Colors
An application can now control the colors used in a progress bar control with the PBM_SETBARCOLOR and PBM_SETBKCOLOR messages.

Progress Bar Control Reference

This section contains information about the following programming elements used with progress bar controls.

Progress Bar Control Styles

Messages
PBM_DELTAPOS
PBM_GETPOS
PBM_GETRANGE
PBM_SETBARCOLOR
PBM_SETBKCOLOR
PBM_SETPOS
PBM_SETRANGE
PBM_SETRANGE32
PBM_SETSTEP
PBM_STEPIT

Structures
PBRANGE

Progress Bar Control Styles

Progress bar controls now support control styles. You can set progress bar styles in the same way as other common controls (CreateWindowEx, GetWindowLong, SetWindowLong). The following are the supported styles:
PBS_SMOOTH Version 4.70. The progress bar displays progress status in a smooth scrolling bar instead of the default segmented bar.
PBS_VERTICAL Version 4.70. The progress bar displays progress status vertically, from bottom to top.

Progress Bar Control Messages

This section includes information about the messages used with progress bar controls.

PBM_DELTAPOS
PBM_DELTAPOS 
    wParam = (WPARAM) nIncrement 
    lParam = 0; 

Advances the current position of a progress bar by a specified increment and redraws the bar to reflect the new position.

nIncrement
Amount to advance the position.
PBM_GETPOS
PBM_GETPOS
    wParam = 0;
    lParam = 0;

Retrieves the current position of the progress bar.

Version 4.70

PBM_GETRANGE
PBM_GETRANGE
    wParam = (WPARAM)(BOOL) fWhichLimit;
    lParam = (LPARAM)(PPBRANGE) ppBRange; 

Retrieves information about the current high and low limits of a given progress bar control.

fWhichLimit
Flag value specifying which limit value is to be used as the message's return value. This parameter can be one of the following values:
TRUE Return the low limit.
FALSE Return the high limit.
ppBRange
Address of a PBRANGE structure that is to be filled with the high and low limits of the progress bar control. If this parameter is set to NULL, the control will return only the limit specified by fWhichLimit.

Version 4.70

PBM_SETBARCOLOR
PBM_SETBARCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBar;

Sets the color of the progress indicator bar in the progress bar control.

clrBar
COLORREF value that specifies the new progress indicator bar color. Specify the CLR_DEFAULT value to cause the progress bar to use its default progress indicator bar color.

Version 4.71

PBM_SETBKCOLOR
PBM_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Sets the background color in the progress bar.

clrBk
COLORREF value that specifies the new background color. Specify the CLR_DEFAULT value to cause the progress bar to use its default background color.

Version 4.71

PBM_SETPOS
PBM_SETPOS 
    wParam = (WPARAM) nNewPos; 
    lParam = 0; 

Sets the current position for a progress bar and redraws the bar to reflect the new position.

nNewPos
Signed integer that becomes the new position.
PBM_SETRANGE
PBM_SETRANGE 
    wParam = 0; 
    lParam = MAKELPARAM(nMinRange, nMaxRange); 

Sets the minimum and maximum values for a progress bar and redraws the bar to reflect the new range.

nMinRange
Minimum range value. By default, the minimum value is zero.
nMaxRange
Maximum range value. By default, the maximum value is 100.
PBM_SETRANGE32
PBM_SETRANGE32
    wParam = (WPARAM)(int) iLowLim;
    lParam = (LPARAM)(int) iHighLim;

Sets the range of a progress bar control to a 32-bit value.

iLowLim
A signed integer that represents the low limit to be set for the progress bar control.
iHighLim
A signed integer that represents the high limit to be set for the progress bar control.

To retrieve the entire high and low 32-bit values, use the PBM_GETRANGE message.

Version 4.70

PBM_SETSTEP
PBM_SETSTEP 
    wParam = (WPARAM) nStepInc; 
    lParam = 0; 

Specifies the step increment for a progress bar. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM_STEPIT message. By default, the step increment is set to 10.

nStepInc
New step increment.
PBM_STEPIT
PBM_STEPIT 
    wParam = 0; 
    lParam = 0; 

Advances the current position for a progress bar by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM_SETSTEP message.

When the position exceeds the maximum range value, this message resets the current position so that the progress indicator starts over again from the beginning.

Progress Bar Control Structures

This section contains information about the structure used with progress bar controls.

PBRANGE
typedef struct {
    int iLow;
    int iHigh;        
} PBRANGE, *PPBRANGE;

Contains information about the high and low limits of a progress bar control. This structure is used with the PBM_GETRANGE message.

iLow
Low limit for the progress bar control. This is a signed integer.
iHigh
High limit for the progress bar control. This is a signed integer.

Version 4.70

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.