Trackbar Controls

A trackbar is a window that contains a slider and optional tick marks. When the user moves the slider, using either the mouse or the direction keys, the trackbar sends notification messages to indicate the change.

About Trackbar Controls
Using Trackbar Controls
Trackbar Control Updates in Internet Explorer

About Trackbar Controls

Trackbars are useful when you want the user to select a discrete value or a set of consecutive values in a range. For example, you might use a trackbar to allow the user to set the repeat rate of the keyboard by moving the slider to a given tick mark. The following illustration shows a typical trackbar.

The slider in a trackbar moves in increments that you specify when you create it. The values in this range are referred to as logical units. For example, if you specify that the trackbar should have logical units that range from zero to five, the slider can occupy only six positions: a position at the left side of the trackbar and one position for each increment in the range. Typically, each of these positions is identified by a tick mark.

You create a trackbar by using the CreateWindowEx function, specifying the TRACKBAR_CLASS window class. After you have created a trackbar, you can use trackbar messages to set and retrieve many of its properties. Changes that you can make include setting the minimum and maximum positions for the slider, drawing tick marks, setting a selection range, and repositioning the slider.

Trackbar Messages

The logical units of a trackbar are the set of contiguous values that the trackbar can represent. They are usually defined by specifying the range of possible values with a TBM_SETRANGE message when the trackbar is first created. Applications can dynamically alter the range by using the TBM_SETRANGEMAX and TBM_SETRANGEMIN messages. An application that allows the range to be changed dynamically retrieves the final range settings when the user has finished working with the trackbar. To retrieve these settings, use the TBM_GETRANGEMAX and TBM_GETRANGEMIN messages.

An application can send messages to the trackbar to retrieve information about the window and to change its characteristics. To retrieve the position of the slider (that is, the value the user has chosen), use the TBM_GETPOS message. To set the position of the slider, use the TBM_SETPOS message.

A trackbar automatically displays tick marks at its beginning and end, unless you specify the TBS_NOTICKS style. You can use the TBS_AUTOTICKS style to automatically display additional tick marks at regular intervals along the trackbar. By default, a TBS_AUTOTICKS trackbar displays a tick mark at each increment of the trackbar's range. To specify a different interval for the automatic tick marks, send the TBM_SETTICFREQ message to the trackbar. For example, you could use this message to display only 10 tick marks in a range of 1 through 100.

To set the position of a single tick mark, send the TBM_SETTIC message. A trackbar maintains an array of DWORD values that stores the position of each tick mark. The array does not include the first and last tick marks that the trackbar creates automatically. You can specify an index in this array when you send the TBM_GETTIC message to retrieve the position of the corresponding tick mark. Alternatively, you can send the TBM_GETPTICS message to retrieve a pointer to the array. The number of elements in the array is equal to two less than the tick count returned by the TBM_GETNUMTICS message. This is because the count returned by TBM_GETNUMTICS includes the first and last tick marks that are not included in the array. To retrieve the physical position of a tick mark, in client coordinates of the trackbar's window, send the TBM_GETTICPOS message. The TBM_CLEARTICS message removes all but the first and last of a trackbar's tick marks.

A trackbar's line size determines how far the slider moves in response to keyboard input from the arrow keys, such as the RIGHT ARROW or DOWN ARROW key. To retrieve or set the line size, send the TBM_GETLINESIZE and TBM_SETLINESIZE messages. The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

A trackbar's page size determines how far the slider moves in response to keyboard input, such as the PAGE UP or PAGE DOWN key, or mouse input, such as clicks in the trackbar channel. To retrieve or set the page size, send the TBM_GETPAGESIZE and TBM_SETPAGESIZE messages. The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page. For more information, see Trackbar Notification Messages.

An application can send messages to retrieve the dimensions of a trackbar. The TBM_GETTHUMBRECT message retrieves the bounding rectangle for the slider. The TBM_GETTHUMBLENGTH message retrieves the length of the slider. The TBM_GETCHANNELRECT message retrieves the bounding rectangle for the trackbar's channel, which is the area over which the slider moves. It contains the highlight when a range is selected. If a trackbar has the TBS_FIXEDLENGTH style, you can send the TBM_SETTHUMBLENGTH message to change the length of the slider.

If you create a trackbar with the TBS_ENABLESELRANGE style, you can specify a "selection range," which restricts the user to a specified portion of the total range. The logical units do not change, but only a subset of them are available for use. The trackbar highlights the available range and displays triangular tick marks at the start and end. Typically, an application handles the trackbar's notification messages and sets the trackbar's selection range according to the user's input.

You retrieve or set the selection range by sending messages to the trackbar. Use the TBM_SETSEL message to set the starting and ending positions of a selection. To set just the starting position or just the ending position of a selection, send a TBM_SETSELSTART or TBM_SETSELEND message. To retrieve the starting or ending positions of a selection range, send a TBM_GETSELSTART or TBM_GETSELEND message. To clear a selection range and restore the trackbar to its original range, send the TBM_CLEARSEL message.

Trackbar Notification Messages

A trackbar notifies its parent window of user actions by sending the parent a WM_HSCROLL or WM_VSCROLL message. A trackbar with the TBS_HORZ style sends WM_HSCROLL messages. A trackbar with the TBS_VERT style sends WM_VSCROLL messages. The low-order word of the wParam parameter of WM_HSCROLL or WM_VSCROLL contains the notification code. For the TB_THUMBPOSITION and TB_THUMBTRACK notifications, the high-order word of the wParam parameter specifies the position of the slider. For all other notifications, the high-order word is zero; send the TBM_GETPOS message to determine the slider position. The lParam parameter is the handle to the trackbar.

The system sends the TB_BOTTOM, TB_LINEDOWN, TB_LINEUP, and TB_TOP notification messages only when the user interacts with a trackbar by using the keyboard. The TB_THUMBPOSITION and TB_THUMBTRACK notification messages are only sent when the user is using the mouse. The TB_ENDTRACK, TB_PAGEDOWN, and TB_PAGEUP notification messages are sent in both cases. The following table lists the trackbar notification messages and the events (virtual key codes or mouse events) that cause the notifications to be sent.

Notification message	Reason sent
TB_BOTTOM	VK_END
TB_ENDTRACK	WM_KEYUP (the user released a key that sent a relevant virtual key code)
TB_LINEDOWN	VK_RIGHT or VK_DOWN
TB_LINEUP	VK_LEFT or VK_UP
TB_PAGEDOWN	VK_NEXT (the user clicked the channel below or to the right of the slider)
TB_PAGEUP	VK_PRIOR (the user clicked the channel above or to the left of the slider)
TB_THUMBPOSITION	WM_LBUTTONUP following a TB_THUMBTRACK notification message
TB_THUMBTRACK	Slider movement (the user dragged the slider)
TB_TOP	VK_HOME

Default Trackbar Message Processing

This section describes the window message processing performed by a trackbar.

Message	Processing performed
WM_CAPTURECHANGED	Kills the timer if one was set during WM_LBUTTONDOWN processing and sends the TB_THUMBPOSITION notification message, if necessary. It always sends the TB_ENDTRACK notification message.
WM_CREATE	Performs additional initialization, such as setting the line size, page size, and tick mark frequency to default values.
WM_DESTROY	Frees resources.
WM_ENABLE	Repaints the trackbar window.
WM_ERASEBKGND	Erases the window background, using the current background color for the trackbar.
WM_GETDLGCODE	Returns the DLGC_WANTARROWS value.
WM_KEYDOWN	Processes the direction keys and sends the TB_TOP, TB_BOTTOM, TB_PAGEUP, TB_PAGEDOWN, TB_LINEUP, and TB_LINEDOWN notification messages, as appropriate.
WM_KEYUP	Sends the TB_ENDTRACK notification message if the key was one of the direction keys.
WM_KILLFOCUS	Repaints the trackbar window.
WM_LBUTTONDOWN	Sets the focus and the mouse capture to the trackbar. When necessary, it sets a timer that determines how quickly the slider moves toward the mouse cursor when the user holds down the mouse button in the window.
WM_LBUTTONUP	Releases the mouse capture and kills the timer if one was set during WM_LBUTTONDOWN processing. It sends the TB_THUMBPOSITION notification message, if necessary. It always sends the TB_ENDTRACK notification message.
WM_MOUSEMOVE	Moves the slider and sends the TB_THUMBTRACK notification message when tracking the mouse (see WM_TIMER ).
WM_PAINT	Paints the trackbar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFOCUS	Repaints the trackbar window.
WM_SIZE	Sets the dimensions of the trackbar, removing the slider if there is not enough room to display it.
WM_TIMER	Retrieves the mouse position and updates the position of the slider. (It is received only when the user is dragging the slider.)
WM_WININICHANGE	Initializes slider dimensions.

Creating a Trackbar

The following example shows how to create a trackbar with the TBS_AUTOTICKS and TBS_ENABLESELRANGE styles. When the trackbar is created, both its range and its selection range are initialized. The page size is also set at this time.

// CreateTrackbar - creates and initializes a trackbar. 
// 
// Global variable 
//     g_hinst - instance handle 
HWND WINAPI CreateTrackbar( 
    HWND hwndDlg,  // handle of dialog box (parent window) 
    UINT iMin,     // minimum value in trackbar range 
    UINT iMax,     // maximum value in trackbar range 
    UINT iSelMin,  // minimum value in trackbar selection 
    UINT iSelMax)  // maximum value in trackbar selection 
{ 

    InitCommonControls(); // loads common control's DLL 

    hwndTrack = CreateWindowEx( 
        0,                             // no extended styles 
        TRACKBAR_CLASS,                // class name 
        "Trackbar Control",            // title (caption) 
        WS_CHILD | WS_VISIBLE | 
        TBS_AUTOTICKS | TBS_ENABLESELRANGE,  // style 
        10, 10,                        // position 
        200, 30,                       // size 
        hwndDlg,                       // parent window 
        ID_TRACKBAR,             // control identifier 
        g_hinst,                       // instance 
        NULL                           // no WM_CREATE parameter 
        ); 

    SendMessage(hwndTrack, TBM_SETRANGE, 
        (WPARAM) TRUE,                   // redraw flag 
        (LPARAM) MAKELONG(iMin, iMax));  // min. & max. positions 
    SendMessage(hwndTrack, TBM_SETPAGESIZE, 
        0, (LPARAM) 4);                  // new page size 

    SendMessage(hwndTrack, TBM_SETSEL, 
        (WPARAM) FALSE,                  // redraw flag 
        (LPARAM) MAKELONG(iSelMin, iSelMax); 
    SendMessage(hwndTrack, TBM_SETPOS, 
        (WPARAM) TRUE,                   // redraw flag 
        (LPARAM) iSelMin); 

    SetFocus(hwndTrack); 

    return hwndTrack; 
}

Processing Trackbar Notification Messages

The following example is a function that is called whenever a WM_HSCROLL message is received by the dialog box containing the trackbar. The trackbar has the TBS_ENABLESELRANGE style. The position of the slider is compared against the selection range, and the slider is moved to the starting or ending position of the selection range, when necessary.

A dialog containing a trackbar with the TBS_VERT style could use this function when it receives a WM_VSCROLL message.

// TBNotifications - handles trackbar notifications received 
// in the wParam parameter of WM_HSCROLL. This function simply 
// ensures that the slider remains within the selection range. 

VOID WINAPI TBNotifications( 
    WPARAM wParam,  // wParam of WM_HSCROLL message 
    HWND hwndTrack, // handle of trackbar window 
    UINT iSelMin,   // minimum value of trackbar selection 
    UINT iSelMax)   // maximum value of trackbar selection 
    { 
    DWORD dwPos;    // current position of slider 

    switch (LOWORD(wParam)) { 
        case TB_ENDTRACK: 
            dwPos = SendMessage(hwndTrack, TBM_GETPOS, 0, 0); 
            if (dwPos > iSelMax) 
                SendMessage(hwndTrack, TBM_SETPOS, 
                    (WPARAM) TRUE,       // redraw flag 
                    (LPARAM) iSelMax); 
            else if (dwPos < iSelMin) 
                SendMessage(hwndTrack, TBM_SETPOS, 
                    (WPARAM) TRUE,       // redraw flag 
                    (LPARAM) iSelMin); 
            break; 

        default: 
            break; 

        } 
}

Trackbar Control Updates in Internet Explorer

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

Buddy Windows	Trackbar controls now provide support for up to two buddy windows. Trackbar buddy windows are automatically positioned by the control to appear centered at the ends of the trackbar control. To assign an existing window to a trackbar, use the TBM_SETBUDDY message. To retrieve the handle to a given buddy window, send the TBM_GETBUDDY message.
ToolTips	Trackbar controls now support ToolTips. A trackbar creates a default ToolTip control when created with the TBS_TOOLTIPS style. However, you can assign a new ToolTip control to a trackbar by sending the TBM_SETTOOLTIPS message. To retrieve the handle to an assigned ToolTip control, use the TBM_GETTOOLTIPS message.