windows_programming_notes.nbk: Home | Index | Next Page: PtInRect | Previous Page: Progress Bar Control Styles
From http://msdn2.microsoft.com/en-us/library/bb760816(VS.85).aspx
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 animated as an operation progresses.
The following illustration shows a progress bar that does not use visual
styles.
The following illustration shows a progress bar using visual styles. The
appearance of the control will vary depending on the operating system and
the selected theme.
More information is contained under the following headings.
You can create a progress bar by using the CreateWindowEx function, specifying the PROGRESS_CLASS window class. This window class is registered when the common controls DLL is loaded. For more information, see About Common Controls.
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. 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.
Note: You use the Theme API to apply visual styles to applications. If you are using a progress bar control with the Theme API on Microsoft Windows XP the control must be at least 10 pixels high.
This section describes the messages handled by the window procedure for the [PROGRESS_CLASS] class.
By creating the progress bar control with the [PBS_MARQUEE] style, you can animate it in a way that shows activity but does not indicate what proportion of the task is complete. The highlighted part of the progress bar moves repeatedly along the length of the bar. You can start and stop the animation, and control its speed, by sending the [PBM_SETMARQUEE] message. Marquee progress bars do not have a range or position.
The following illustration shows a progress bar in marquee mode. The
highlighted part moves across the bar.
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, LPTSTR 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,
(LPTSTR) 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);
// TODO: Write an error handler to check that all the
// requested data was read.
// 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;
}
windows_programming_notes.nbk: Home | Index | Next Page: PtInRect | Previous Page: Progress Bar Control Styles
Notebook exported on Monday, 7 July 2008, 18:56:50 PM Eastern Daylight Time