Flat Scroll Bars

Flat Scroll Bars


Microsoft® Internet Explorer Version 4.0 introduces a new visual technology called flat scroll bars. Functionally, flat scroll bars behave just like normal scroll bars. The only difference is they are not displayed three-dimensionally.

The following illustration shows a window that contains flat scroll bars.

Window that contains flat scroll bars.

Note Flat scroll bar APIs are implemented in version 4.71 and later of Comctl32.dll.

arrowy.gifUsing Flat Scroll Bars

arrowy.gifFlat Scroll Bars Reference

Using Flat Scroll Bars

This section describes how to implement flat scroll bars in your application.

Before You Begin

To use the flat scroll bar APIs, you must include Commctrl.h in your source files and link with Comctl32.lib.

Adding Flat Scroll Bars to a Window

To add flat scroll bars to a window, call InitializeFlatSB, passing the handle to the window. Instead of using the standard scroll bar APIs to manipulate your scroll bars, you must use the FlatSB_xxxx versions. There are flat scroll bar APIs for setting and retrieving the scroll information, range, and position. If flat scroll bars haven't been initialized for your window, the flat scroll bar APIs will defer to the corresponding standard APIs, if any exist. This allows you to turn flat scroll bars on and off without having to write conditional code.

Enhancing Flat Scroll Bars

FlatSB_SetScrollProp allows you to modify the flat scroll bars to customize the look of your window. You can set the width of a vertical scroll bar and the height of a horizontal scroll bar. You can also set the width (horizontal scroll bar) and the height (vertical scroll bar) of the scroll bar's direction arrows.

FlatSB_SetScrollProp also allows you to customize how the flat scroll bars are displayed. By changing the WSB_PROP_VSTYLE and WSB_PROP_HSTYLE properties, you can set the type of scroll bar that you wish to use. Three styles are available:

FSB_ENCARTA_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE A normal, nonflat scroll bar is displayed. No special visual effects will be applied.

Removing Flat Scroll Bars

If you wish to remove flat scroll bars from your window, call the UninitializeFlatSB API, passing the handle to the window. This API only removes flat scroll bars from your window at run time. You do not need to call this API when your window is destroyed.

Flat Scroll Bars Reference

This section contains information on the following new APIs for controlling flat scroll bars:

InitializeFlatSB
FlatSB_EnableScrollBar
FlatSB_GetScrollInfo
FlatSB_GetScrollPos
FlatSB_GetScrollProp
FlatSB_GetScrollRange
FlatSB_SetScrollInfo
FlatSB_SetScrollPos
FlatSB_SetScrollProp
FlatSB_SetScrollRange
FlatSB_ShowScrollBar
UninitializeFlatSB

InitializeFlatSB

BOOL InitializeFlatSB(
    HWND hwnd
);

Initializes flat scroll bars for a particular window.

hwnd
Handle to the window that will receive flat scroll bars.

This API must be called before any other flat scroll bar APIs are called. The window will receive flat scroll bars by default. The scroll bar style can be changed with the FlatSB_SetScrollProp API.

Version 4.71

FlatSB_EnableScrollBar

BOOL FlatSB_EnableScrollBar(
    HWND hwnd, 
    int wSBflags, 
    UINT wArrows
);

Enables or disables one or both flat scroll bar direction buttons. If flat scroll bars are not initialized for the window, this function calls the standard EnableScrollBar API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
wSBflags
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_BOTH Enables or disables the direction buttons on the horizontal and vertical scroll bars.
SB_HORZ Enables or disables the direction buttons on the horizontal scroll bar.
SB_VERT Enables or disables the direction buttons on the vertical scroll bar.
wArrows
Parameter that specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. It can be one of the following values:
ESB_DISABLE_BOTH Disables both direction buttons on the specified scroll bar.
ESB_DISABLE_DOWN Disables the down direction button on the vertical scroll bar.
ESB_DISABLE_LEFT Disables the left direction button on the horizontal scroll bar.
ESB_DISABLE_LTUP Disables the left direction button on the horizontal scroll bar or the up direction button on the vertical scroll bar.
ESB_DISABLE_RIGHT Disables the right direction button on the horizontal scroll bar.
ESB_DISABLE_RTDN Disables the right direction button on the horizontal scroll bar or the down direction button on the vertical scroll bar.
ESB_DISABLE_UP Disables the up direction button on the vertical scroll bar.
ESB_ENABLE_BOTH Enables both direction buttons on the specified scroll bar.

Version 4.71

FlatSB_GetScrollInfo

BOOL FlatSB_GetScrollInfo(
    HWND hwnd, 
    int fnBar, 
    LPSCROLLINFO lpsi
);

Retrieves the information for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollInfo API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
fnBar
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Retrieves the information for the horizontal scroll bar.
SB_VERT Retrieves the information for the vertical scroll bar.
lpsi
Address of a SCROLLINFO structure that will receive the information for the specified scroll bar. The cbSize and fMask members of the structure must be filled out prior to calling FlatSB_GetScrollInfo. The fMask member specifies which properties should be retrieved and can be any combination of the following values:
SIF_PAGE Retrieves the page information for the flat scroll bar. This will be placed in the nPage member of the SCROLLINFO structure.
SIF_POS Retrieves the position information for the flat scroll bar. This will be placed in the nPos member of the SCROLLINFO structure.
SIF_RANGE Retrieves the range information for the flat scroll bar. This will be placed in the nMin and nMax members of the SCROLLINFO structure.
SIF_ALL A combination of SIF_PAGE, SIF_POS, and SIF_RANGE.

Version 4.71

FlatSB_GetScrollPos

int FlatSB_GetScrollPos(
    HWND hwnd, 
    int code
);

Retrieves the thumb position in a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollPos API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Retrieves the thumb position of the horizontal scroll bar.
SB_VERT Retrieves the thumb position of the vertical scroll bar.

Version 4.71

FlatSB_GetScrollProp

BOOL FlatSB_GetScrollProp(
    HWND hwnd, 
    UINT index, 
    LPINT pValue
);

Retrieves the properties for a flat scroll bar. This function can also be used to determine if InitializeFlatSB has been called for this window.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
index
Parameter that determines what pValue represents and which property is being retrieved. It can be one of the following values:
WSB_PROP_CXHSCROLL pValue is an address of an INT value that receives the width, in pixels, of the direction buttons in a horizontal scroll bar.
WSB_PROP_CXHTHUMB pValue is an address of an INT value that receives the width, in pixels, of the thumb in a horizontal scroll bar.
WSB_PROP_CXVSCROLL pValue is an address of an INT value that receives the width, in pixels, of a vertical scroll bar.
WSB_PROP_CYHSCROLL pValue is an address of an INT value that receives the height, in pixels, of a horizontal scroll bar.
WSB_PROP_CYVSCROLL pValue is an address of an INT value that receives the height, in pixels, of the direction buttons in a vertical scroll bar.
WSB_PROP_CYVTHUMB pValue is an address of an INT value that receives the height, in pixels, of the thumb in a vertical scroll bar.
WSB_PROP_HBKGCOLOR pValue is an address of a COLORREF value that receives the background color in a horizontal scroll bar.
WSB_PROP_HSTYLE pValue is an address of an INT value that receives one of the following visual effects for the horizontal scroll bar.
FSB_ENCARTA_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in 3-D.
FSB_FLAT_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in inverted colors.
FSB_REGULAR_MODE A normal, nonflat scroll bar is displayed. No special visual effects are applied.
WSB_PROP_PALETTE pValue is an address of an HPALETTE value that receives the palette that a scroll bar uses when drawing.
WSB_PROP_VBKGCOLOR pValue is an address of a COLORREF value that receives the background color in a vertical scroll bar.
WSB_PROP_VSTYLE pValue is an address of an INT value that receives one of the following visual effects for the vertical scroll bar.
FSB_ENCARTA_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in 3-D.
FSB_FLAT_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in inverted colors.
FSB_REGULAR_MODE A normal, nonflat scroll bar is displayed. No special visual effects are applied.
WSB_PROP_WINSTYLE pValue is an address of an INT value that receives the WS_HSCROLL and WS_VSCROLL style bits contained by the current window.
pValue
Address that receives the requested data. This parameter depends on the flag passed in index.

Version 4.71

FlatSB_GetScrollRange

BOOL FlatSB_GetScrollRange(
    HWND hwnd, 
    int code, 
    LPINT lpMinPos, 
    LPINT lpMaxPos
);

Retrieves the scroll range for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollRange API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Retrieves the scroll range of the horizontal scroll bar.
SB_VERT Retrieves the scroll range of the vertical scroll bar.
lpMinPos
Address of an INT value that receives the minimum scroll range value.
lpMaxPos
Address of an INT value that receives the maximum scroll range value.

Version 4.71

FlatSB_SetScrollInfo

int FlatSB_SetScrollInfo(
    HWND hwnd, 
    int fnBar, 
    LPSCROLLINFO lpsi,
    BOOL fRedraw
);

Sets the information for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollInfo API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
fnBar
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Sets the information for the horizontal scroll bar.
SB_VERT Sets the information for the vertical scroll bar.
lpsi
Address of a SCROLLINFO structure that contains the new information for the specified scroll bar. The cbSize and fMask members of the structure must be filled in prior to calling FlatSB_SetScrollInfo. The fMask member specifies which members of the structure contain valid information and can be any combination of the following values:
SIF_DISABLENOSCROLL Disables the scroll bar if the new information would cause the scroll bar to be removed.
SIF_PAGE Sets the page information for the flat scroll bar. The nPage member of the SCROLLINFO structure must contain the new page value.
SIF_POS Sets the position information for the flat scroll bar. The nPos member of the SCROLLINFO structure must contain the new position value.
SIF_RANGE Sets the range information for the flat scroll bar. The nMin and nMax members of the SCROLLINFO structure must contain the new range values.
SIF_ALL A combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Version 4.71

FlatSB_SetScrollPos

int FlatSB_SetScrollPos(
    HWND hwnd, 
    int code,
    int nPos,
    BOOL fRedraw
);

Sets the current position of the thumb in a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollPos API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Sets the thumb position of the horizontal scroll bar.
SB_VERT Sets the thumb position of the vertical scroll bar.
nPos
Parameter that specifies the new thumb position.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Version 4.71

FlatSB_SetScrollProp

BOOL FlatSB_SetScrollProp(
    HWND hwnd, 
    UINT index, 
    int newValue, 
    BOOL fRedraw
);

Sets the properties for a flat scroll bar.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
index
Parameter that determines what newValue represents and which property is being set. This parameter can be one of the following values:
WSB_PROP_CXHSCROLL newValue is an INT value that represents the width, in pixels, of the direction buttons in a horizontal scroll bar.
WSB_PROP_CXHTHUMB newValue is an INT value that represents the width, in pixels, of the thumb in a horizontal scroll bar.
WSB_PROP_CXVSCROLL newValue is an INT value that represents the width, in pixels, of the vertical scroll bar.
WSB_PROP_CYHSCROLL newValue is an INT value that represents the height, in pixels, of the horizontal scroll bar.
WSB_PROP_CYVSCROLL newValue is an INT value that represents the height, in pixels, of the direction buttons in a vertical scroll bar.
WSB_PROP_CYVTHUMB newValue is an INT value that represents the height, in pixels, of the thumb in a vertical scroll bar.
WSB_PROP_HBKGCOLOR newValue is a COLORREF value that represents the background color in a horizontal scroll bar.
WSB_PROP_HSTYLE newValue is one of the following values that changes the visual effects for the horizontal scroll bar.
FSB_ENCARTA_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE A normal, nonflat scroll bar is displayed. No special visual effects will be applied.
WSB_PROP_PALETTE newValue is an HPALETTE value that represents the new palette that the scroll bar should use when drawing.
WSB_PROP_VBKGCOLOR newValue is a COLORREF value that represents the background color in a vertical scroll bar.
WSB_PROP_VSTYLE newValue is one of the following values that changes the visual effects for the vertical scroll bar:
FSB_ENCARTA_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE A normal, nonflat scroll bar is displayed. No special visual effects will be applied.
newValue
New value to set. This parameter depends on the flag passed in index.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Version 4.71

FlatSB_SetScrollRange

int FlatSB_SetScrollRange(
    HWND hwnd,
    int code,
    int nMinPos,
    int nMaxPos,
    BOOL fRedraw
);

Sets the scroll range of a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollRange API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ Sets the scroll range of the horizontal scroll bar.
SB_VERT Sets the scroll range of the vertical scroll bar.
nMinPos
Parameter that specifies the new minimum scroll range value.
nMaxPos
Parameter that specifies the new maximum scroll range value.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Version 4.71

FlatSB_ShowScrollBar

BOOL FlatSB_ShowScrollBar(
    HWND hwnd, 
    int code, 
    BOOL fShow
);

Shows or hides a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard ShowScrollBar API.

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_BOTH Shows or hides the horizontal and vertical scroll bars.
SB_HORZ Shows or hides the horizontal scroll bar.
SB_VERT Shows or hides the vertical scroll bar.
fShow
Parameter that specifies whether the scroll bar should be shown or hidden. If this parameter is nonzero, the scroll bar will be shown; if it is zero, the scroll bar will be hidden.

Version 4.71

UninitializeFlatSB

HRESULT UninitializeFlatSB(
    HWND hwnd
);

Uninitializes flat scroll bars for a particular window. The specified window will revert to having standard scroll bars.

hwnd
Handle to the window with the flat scroll bars that will be uninitialized.

Version 4.71

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