
Rebar controls act as containers for child windows. An application assigns child windows, which are often other controls, to a rebar control band. Rebar controls contain one or more bands, and each band can have any combination of a gripper bar, a bitmap, a text label, and a child window. However, bands cannot contain more than one child window.
A rebar control displays the child window over a specified background bitmap. As you dynamically reposition a rebar control band, the rebar control manages the size and position of the child window assigned to that band.
The following illustration shows a rebar control that has two bands. One contains a combo box, and the other contains a transparent toolbar control.
Note The rebar control is implemented in version 4.70 and later of Comctl32.dll.
An application defines a rebar band's traits by using the RB_INSERTBAND and RB_SETBANDINFO messages. These messages accept the address of a REBARBANDINFO structure as the lParam parameter. The REBARBANDINFO structure members define the traits of a given band. To set a band's traits, set the cbSize member to indicate the size of the structure, in bytes. Then set the fMask member to indicate which structure members your application is filling.
To assign a child window to a band, include the RBBIM_CHILD flag in the fMask member of the REBARBANDINFO structure, and then set the hwndChild member to the child window's handle. Applications can set the minimum allowable width and height of a child window in the cxMinChild and cyMinChild members.
When a rebar control is destroyed, it destroys any child windows assigned to the bands within it. To prevent the control from destroying child windows assigned to its bands, remove the bands by sending the RB_DELETEBAND message, and then reset the parent to another window with the SetParent function before destroying the rebar control.
All rebar control bands can be resized, except those that use the RBBS_FIXEDSIZE style. To resize or change the order of bands within the control, click and drag a band's gripper bar. The rebar control automatically resizes and repositions child windows assigned to its bands. Additionally, you can toggle the size of a band by clicking on the band text, if there is any.
If an application is using an image list with a rebar control, it must send the RB_SETBARINFO message before adding bands to the control. This message accepts the address of a REBARINFO structure as the lParam parameter. Before sending the message, prepare the REBARINFO structure by setting the cbSize member to the size of the structure, in bytes. Then, if the rebar control is going to display images on the bands, set the fMask member to the RBIM_IMAGELIST flag and assign an image list handle to the himl member. If the rebar will not use band images, set fMask to zero.
A rebar control forwards all WM_NOTIFY window messages to its parent window. Additionally, a rebar control forwards any messages sent to it from windows assigned to its bands, like WM_CHARTOITEM, WM_COMMAND, and others.
Rebar controls support custom draw functionality. For more information, see About Custom Draw.
This section gives sample code that demonstrates how to implement a rebar control.
An application creates a rebar control by calling the CreateWindowEx function, specifying REBARCLASSNAME as the window class. The application must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_COOL_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.
The following sample creates a rebar control with two bandsone that contains a combo box and another that contains a toolbar. The sample includes the RBS_VARHEIGHT style to allow the control to use variable band height. After creating the rebar control, CreateRebar creates the child windows with calls to two application-defined functions, CreateComboBox and CreateToolbar. Before adding each band, CreateRebar initializes the cbSize member of the REBARBANDINFO structure, as required by the RB_INSERTBAND message. Then it sets the value of the structure's fMask member to reflect which members contain valid data. CreateRebar sets the cyMinChild member for each band to allow for the height of the control within it. The cxMinChild member is zero to allow the user to completely hide the control within a given band.
HWND WINAPI CreateRebar(HWND hwndOwner)
{
REBARINFO rbi;
REBARBANDINFO rbBand;
RECT rc;
HWND hwndCB, hwndTB, hwndRB;
DWORD dwBtnSize;
INITCOMMONCONTROLSEX icex;
icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
icex.dwICC = ICC_COOL_CLASSES|ICC_BAR_CLASSES;
InitCommonControlsEx(&icex);
hwndRB = CreateWindowEx(WS_EX_TOOLWINDOW,
REBARCLASSNAME,
NULL,
WS_CHILD|WS_VISIBLE|WS_CLIPSIBLINGS|
WS_CLIPCHILDREN|RBS_VARHEIGHT|CCS_NODIVIDER,
0,0,0,0,
hwndOwner,
NULL,
g_hinst,
NULL);
if(!hwndRB)
return NULL;
// Initialize and send the REBARINFO structure.
rbi.cbSize = sizeof(REBARINFO); // Required when using this struct.
rbi.fMask = 0;
rbi.himl = (HIMAGELIST)NULL;
if(!SendMessage(hwndRB, RB_SETBARINFO, 0, (LPARAM)&rbi))
return NULL;
// Initialize structure members that both bands will share.
rbBand.cbSize = sizeof(REBARBANDINFO); // Required
rbBand.fMask = RBBIM_COLORS | RBBIM_TEXT | RBBIM_BACKGROUND |
RBBIM_STYLE | RBBIM_CHILD | RBBIM_CHILDSIZE |
RBBIM_SIZE;
rbBand.fStyle = RBBS_CHILDEDGE | RBBS_FIXEDBMP;
rbBand.hbmBack= LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_BACKGRND));
// Create the combo box control to be added.
hwndCB = CreateComboBox(hwndRB);
// Set values unique to the band with the combo box.
GetWindowRect(hwndCB, &rc);
rbBand.lpText = "Combo Box";
rbBand.hwndChild = hwndCB;
rbBand.cxMinChild = 0;
rbBand.cyMinChild = rc.bottom - rc.top;
rbBand.cx = 200;
// Add the band that has the combo box.
SendMessage(hwndRB, RB_INSERTBAND, (WPARAM)-1, (LPARAM)&rbBand);
// Create the toolbar control to be added.
hwndTB = CreateToolbar(hwndOwner, dwStyle);
// Get the height of the toolbar.
dwBtnSize = SendMessage(hwndTB, TB_GETBUTTONSIZE, 0,0);
// Set values unique to the band with the toolbar.
rbBand.lpText = "Tool Bar";
rbBand.hwndChild = hwndTB;
rbBand.cxMinChild = 0;
rbBand.cyMinChild = HIWORD(dwBtnSize);
rbBand.cx = 250;
// Add the band that has the toolbar.
SendMessage(hwndRB, RB_INSERTBAND, (WPARAM)-1, (LPARAM)&rbBand);
return (hwndRB);
}
This section contains information about the following new or updated API elements used with rebar controls.
| Structures |
| NMRBAUTOSIZE |
| NMREBAR |
| NMREBARCHILDSIZE |
| RBHITTESTINFO |
| REBARBANDINFO |
| REBARINFO |
Rebar controls support a variety of control styles in addition to standard window styles.
| RBS_AUTOSIZE | Version 4.71. The rebar control will automatically change the layout of the bands when the size or position of the control changes. An RBN_AUTOSIZE notification will be sent when this occurs. |
| RBS_BANDBORDERS | Version 4.70. The rebar control displays narrow lines to separate adjacent bands. |
| RBS_DBLCLKTOGGLE | Version 4.71. The rebar band will toggle its maximized or minimized state when the user double-clicks on the band. Without this style, the maximized or minimized state is toggled when the user single-clicks on the band. |
| RBS_FIXEDORDER | Version 4.70. The rebar control always displays bands in the same order. You can move bands to different rows, but the band order is static. |
| RBS_REGISTERDROP | Version 4.71. The rebar control generates RBN_GETOBJECT notification messages when an object is dragged over a band in the control. To receive the RBN_GETOBJECT notifications, initialize OLE with a call to OleInitialize or CoInitialize. |
| RBS_TOOLTIPS | Version 4.70. Not yet supported. |
| RBS_VARHEIGHT | Version 4.70. The rebar control displays bands at the minimum required height, when possible. Without this style, the rebar control displays all bands at the same height, using the height of the tallest visible band to determine the height of other bands. |
| RBS_VERTICALGRIPPER | Version 4.71. The size grip will be displayed vertically instead of horizontally in a vertical rebar control. This style is ignored for rebar controls that do not have the CCS_VERT style. |
This section contains information about the messages used with rebar controls.
RB_BEGINDRAG
wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(DWORD)dwPos;
Puts the rebar control in drag-and-drop mode. This message does not cause a RBN_BEGINDRAG notification to be sent.
The RB_BEGINDRAG, RB_DRAGMOVE, and RB_ENDDRAG messages allow you to implement an IDropTarget interface for a rebar control. You send the RB_BEGINDRAG message in response to IDropTarget::DragEnter, send the RB_DRAGMOVE message in response to IDropTarget::DragOver, and the RB_ENDDRAG message in response to IDropTarget::Drop and IDropTarget::DragLeave.
Version 4.71
RB_DELETEBAND
wParam = (WPARAM)(UINT) uBand;
lParam = 0;
Deletes a band from a rebar control.
Version 4.70
RB_DRAGMOVE
wParam = 0;
lParam = (LPARAM)(DWORD)dwPos;
Updates the drag position in the rebar control after a previous RB_BEGINDRAG message.
Version 4.71
See also RB_ENDDRAG
RB_ENDDRAG
wParam = 0;
lParam = 0;
Terminates the rebar control's drag-and-drop operation. This message does not cause an RBN_ENDDRAG notification to be sent.
Version 4.71
See also RB_BEGINDRAG, RB_DRAGMOVE
RB_GETBANDBORDERS
wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPRECT) lprc;
Retrieves the borders of a band. The result of this message can be used to calculate the usable area in a band.
Version 4.71
RB_GETBANDCOUNT
wParam = 0;
lParam = 0;
Retrieves the count of bands currently in the rebar control.
Version 4.70
RB_GETBANDINFO
wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;
Retrieves information about a specified band in a rebar control.
Version 4.70
See also RB_SETBANDINFO
RB_GETBARHEIGHT
wParam = 0;
lParam = 0;
Retrieves the height of the rebar control.
Version 4.71
RB_GETBARINFO
wParam = 0;
lParam = (LPARAM)(LPREBARINFO) lprbi;
Retrieves information about the rebar control and the image list it uses.
Version 4.70
RB_GETBKCOLOR
wParam = 0;
lParam = 0;
Retrieves a rebar control's default background color.
Version 4.71
See also RB_SETBKCOLOR
RB_GETDROPTARGET
wParam = 0;
lParam = (IDropTarget**)ppDropTarget;
Retrieves a rebar control's IDropTarget interface pointer.
Version 4.71
RB_GETCOLORSCHEME
wParam = 0;
lParam = (LPARAM)(LPCOLORSCHEME) lpcs;
Retrieves the color scheme information from the rebar control.
Version 4.71
See also RB_SETCOLORSCHEME
RB_GETPALETTE
wParam = 0;
lParam = 0;
Retrieves the rebar control's current palette.
Version 4.71
See also RB_SETPALETTE
RB_GETRECT
wParam = (WPARAM)(INT) iBand;
lParam = (LPARAM)(LPRECT) lprc;
Retrieves the bounding rectangle for a given band in a rebar control.
Version 4.71
RB_GETROWCOUNT
wParam = 0;
lParam = 0;
Retrieves the number of rows of bands in a rebar control.
Version 4.70
RB_GETROWHEIGHT
wParam = (WPARAM)(UINT) uRow;
lParam = 0;
Retrieves the height of a specified row in a rebar control.
To retrieve the number of rows in a rebar control, use the RB_GETROWCOUNT message.
Version 4.70
RB_GETTEXTCOLOR
wParam = 0;
lParam = 0;
Retrieves a rebar control's default text color.
Version 4.71
See also RB_SETTEXTCOLOR
RB_GETTOOLTIPS
wParam = 0;
lParam = 0;
Retrieves the handle to any tooltip control associated with the rebar control.
Version 4.71
RB_GETUNICODEFORMAT
wParam = 0;
lParam = 0;
Retrieves the UNICODE character format flag for the control.
See also RB_SETUNICODEFORMAT
RB_HITTEST
wParam = 0;
lParam = (LPARAM)(LPRBHITTESTINFO) lprbht;
Determines which portion of a rebar band is at a given point on the screen, if a rebar band exists at that point.
Version 4.71
RB_IDTOINDEX
wParam = (WPARAM)(UINT) uBandID;
lParam = 0;
Converts a band identifier to a band index in a rebar control.
Version 4.71
RB_INSERTBAND
wParam = (WPARAM)(UINT) uIndex;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;
Inserts a new band in a rebar control.
Version 4.70
RB_MAXIMIZEBAND
wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(BOOL) fIdeal;
Resizes a band in a rebar control to either its ideal or largest size.
Version 4.71
RB_MINIMIZEBAND
wParam = (WPARAM)(UINT) uBand;
lParam = 0;
Resizes a band in a rebar control to its smallest size.
Version 4.71
RB_MOVEBAND
wParam = (WPARAM)(UINT) iFrom;
lParam = (LPARAM)(UINT) iTo;
Moves a band from one index to another.
This message will most likely change the index of other bands in the rebar control. If a band is moved from index 6 to index 0, all of the bands in between will have their index incremented by one.
iTo must never be greater than the number of bands minus one. The number of bands can be obtained with the RB_GETBANDCOUNT message.
Version 4.71
RB_SETBANDINFO
wParam = (WPARAM)(UINT) uBand;
lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;
Sets characteristics of an existing band in a rebar control.
Version 4.70
RB_SETBARINFO
wParam = 0;
lParam = (LPARAM)(LPREBARINFO) lprbi;
Sets the characteristics of a rebar control.
Version 4.70
RB_SETBKCOLOR
wParam = 0;
lParam = (LPARAM)(COLORREF)clrBk;
Sets a rebar control's default background color.
The rebar control's default background color is used to draw the background in a rebar control and all bands that are added after this message has been sent. The default background color for a particular band can be overridden when a band is added or modified by setting the RBBIM_COLORS flag in fMask and setting clrBack in the REBARBANDINFO structure.
Version 4.71
See also RB_GETBKCOLOR
RB_SETCOLORSCHEME
wParam = 0;
lParam = (LPARAM)(LPCOLORSCHEME) lpcs;
Sets the color scheme information for the rebar control.
The rebar control uses the color scheme information when drawing the 3-D elements in the control and bands.
Version 4.71
See also RB_GETCOLORSCHEME
RB_SETPALETTE
wParam = 0;
lParam = (LPARAM)(HPALETTE) hpal;
Sets the rebar control's current palette.
It is the responsibility of the application sending this message to delete the HPALETTE passed in this message (see DeleteObject). The rebar control will not delete an HPALETTE set with this message.
Version 4.71
See also RB_GETPALETTE
RB_SETPARENT
wParam = (WPARAM)(HWND) hwndParent;
lParam = 0;
Sets a rebar control's parent window.
The rebar control sends notification messages to the window you specify with this message. This message does not actually change the parent of the rebar control.
Version 4.70
RB_SETTEXTCOLOR
wParam = 0;
lParam = (LPARAM)(COLORREF)clrText;
Sets a rebar control's default text color.
The rebar control's default text color is used to draw the text in a rebar control and all bands that are added after this message has been sent. The default text color for a particular band can be overridden when a band is added or modified by setting the RBBIM_COLORS flag in fMask and setting clrFore in the REBARBANDINFO structure.
Version 4.71
See also RB_GETTEXTCOLOR
RB_SETTOOLTIPS
wParam = (WPARAM)(HWND) hwndToolTip;
lParam = 0;
Associates a tooltip control with the rebar control.
Version 4.71
RB_SETUNICODEFORMAT
wParam = (WPARAM)(BOOL)fUnicode;
lParam = 0;
Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.
See also RB_GETUNICODEFORMAT
RB_SHOWBAND
wParam = (WPARAM)(INT) iBand;
lParam = (LPARAM)(BOOL) fShow;
Shows or hides a given band in a rebar control.
Version 4.71
RB_SIZETORECT
wParam = 0;
lParam = (LPARAM)(LPRECT) prc;
Attempts to find the best layout of the bands for the given rectangle.
The rebar bands will be arranged and wrapped as necessary to fit the rectangle. Bands that have the RBBS_VARIABLEHEIGHT style will be resized as evenly as possible to fit the rectangle. The height of a horizontal rebar or the width of a vertical rebar may change, depending on the new layout.
Version 4.71
This section contains information about the rebar control notification messages.
NM_CUSTOMDRAW
lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;
Sent by the rebar control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.
When dwDrawStage equals CDDS_PREPAINT:
|
When dwDrawStage equals CDDS_ITEMPREPAINT:
|
Version 4.70
See also Using Custom Draw
NM_NCHITTEST
lpnmmouse = (LPNMMOUSE) lParam;
Sent by a rebar control when the control receives a WM_NCHITTEST message. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_RELEASEDCAPTURE
lpnmh = (LPNMHDR) lParam;
Notifies a rebar control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71.
RBN_AUTOSIZE
lpnmas = (LPNMRBAUTOSIZE) lParam;
Sent by a rebar control created with the RBS_AUTOSIZE style when the rebar automatically resizes itself. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_BEGINDRAG
lpnmrb = (LPNMREBAR)lParam;
Sent by a rebar control when the user begins dragging a band. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_CHILDSIZE
lprbcs = (LPNMREBARCHILDSIZE)lParam;
Sent by a rebar control when a band's child window is resized. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_DELETEDBAND
lpnmrb = (LPNMREBAR)lParam;
Sent by a rebar control after a band has been deleted. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_DELETINGBAND
lpnmrb = (LPNMREBAR)lParam;
Sent by a rebar control when a band is about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_ENDDRAG
lpnmrb = (LPNMREBAR)lParam;
Sent by a rebar control when the user stops dragging a band. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
RBN_GETOBJECT
lpnmon = (LPNMOBJECTNOTIFY) lParam;
Sent by a rebar control created with the RBS_REGISTERDROP style when an object is dragged over a band in the control. This notification message is sent in the form of a WM_NOTIFY message.
To receive the RBN_GETOBJECT notification, initialize OLE with a call to OleInitialize or CoInitialize.
Version 4.71
RBN_HEIGHTCHANGE
lpnmhdr = (LPNMHDR) lParam;
Sent by a rebar control when its height has changed. This notification message is sent in the form of a WM_NOTIFY message.
Rebar controls that use the CCS_VERT style send this notification message when their width changes.
Version 4.70
RBN_LAYOUTCHANGED
lpnmhdr = (LPNMHDR) lParam;
Sent by a rebar control when the user changes the layout of the control's bands. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
This section contains information about the structures used with rebar controls.
typedef struct tagNMRBAUTOSIZE {
NMHDR hdr;
BOOL fChanged;
RECT rcTarget;
RECT rcActual;
} NMRBAUTOSIZE, *LPNMRBAUTOSIZE;
Contains information used in handling the RBN_AUTOSIZE notification messages.
Version 4.71
typedef struct tagNMREBAR {
NMHDR hdr;
DWORD dwMask;
UINT uBand;
UINT fStyle;
UINT wID;
LPARAM lParam;
} NMREBAR, *LPNMREBAR;
Contains information used in handling various rebar notification messages.
| RBNM_ID | The wID member contains valid information. |
| RBNM_LPARAM | The lParam member contains valid information. |
| RBNM_STYLE | The fStyle member contains valid information. |
Version 4.71
typedef struct tagNMREBARCHILDSIZE{
NMHDR hdr;
UINT uBand;
UINT wID;
RECT rcChild;
RECT rcBand;
} NMREBARCHILDSIZE, *LPNMREBARCHILDSIZE;
Contains information used in handling the RBN_CHILDSIZE notification message.
Version 4.71
typedef struct _RB_HITTESTINFO {
POINT pt;
UINT flags;
int iBand;
} RBHITTESTINFO, FAR *LPRBHITTESTINFO;
Contains information specific to a hit test operation. This structure is used with the RB_HITTEST message.
| RBHT_CAPTION | The point was in the rebar band's caption. |
| RBHT_CLIENT | The point was in the rebar band's client area. |
| RBHT_GRABBER | The point was in the rebar band's gripper. |
| RBHT_NOWHERE | The point was not in a rebar band. |
Version 4.71
typedef struct tagREBARBANDINFO{
UINT cbSize;
UINT fMask;
UINT fStyle;
COLORREF clrFore;
COLORREF clrBack;
LPTSTR lpText;
UINT cch;
int iImage;
HWND hwndChild;
UINT cxMinChild;
UINT cyMinChild;
UINT cx;
HBITMAP hbmBack;
UINT wID;
#if (_WIN32_IE >= 0x0400)
UINT cyChild;
UINT cyMaxChild;
UINT cyIntegral;
UINT cxIdeal;
LPARAM lParam;
UINT cxHeader;
#endif
} REBARBANDINFO, FAR *LPREBARBANDINFO;
Contains information that defines a band in a rebar control.
| RBBIM_BACKGROUND | The hbmBack member is valid or must be filled. |
| RBBIM_CHILD | The hwndChild member is valid or must be filled. |
| RBBIM_CHILDSIZE | The cxMinChild and cyMinChild members are valid or must be filled. |
| RBBIM_COLORS | The clrFore and clrBack members are valid or must be filled. |
| RBBIM_HEADERSIZE | Version 4.71. The cxHeader member is valid or must be filled. |
| RBBIM_IDEALSIZE | Version 4.71. The cxIdeal member is valid or must be filled. |
| RBBIM_ID | The wID member is valid or must be filled. |
| RBBIM_IMAGE | The iImage member is valid or must be filled. |
| RBBIM_LPARAM | Version 4.71. The lParam member is valid or must be filled. |
| RBBIM_SIZE | The cx member is valid or must be filled. |
| RBBIM_STYLE | The fStyle member is valid or must be filled. |
| RBBIM_TEXT | The lpText member is valid or must be filled. |
| RBBS_BREAK | The band is on a new line. |
| RBBS_CHILDEDGE | The band has an edge at the top and bottom of the child window. |
| RBBS_FIXEDBMP | The background bitmap does not move when the band is resized. |
| RBBS_FIXEDSIZE | The band can't be sized. With this style, the sizing grip is not displayed on the band. |
| RBBS_GRIPPERALWAYS | Version 4.71. The band will always have sizing grip, even if it is the only band in the rebar. |
| RBBS_HIDDEN | The band will not be visible. |
| RBBS_NOGRIPPER | Version 4.71. The band will never have sizing grip, even if there is more than one band in the rebar. |
| RBBS_NOVERT | The band won't be displayed when the rebar control uses the CCS_VERT style. |
| RBBS_VARIABLEHEIGHT | Version 4.71. The band can be resized by the rebar control. cyIntegral and cyMaxChild affect how the rebar will resize the band. |
The cxMinChild, cyMinChild, and cx members provide information on dimensions relative to the orientation of the control. That is, for a horizontal rebar control, cxMinChild and cx are horizontal measurements and cyMinChild is a vertical measurement. However, if the control uses the CCS_VERT style, cxMinChild and cx are vertical measurements and cyMinChild is a horizontal measurement.
Version 4.70
typedef struct tagREBARINFO{
UINT cbSize;
UINT fMask;
HIMAGELIST himl;
} REBARINFO, FAR *LPREBARINFO;
Contains information that describes rebar control characteristics.
| RBIM_IMAGELIST | The himl member is valid or must be filled. |
Version 4.70
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.