CControlBar Class
The base class for the control-bar classes CStatusBar, CToolBar, CDialogBar, CReBar, and COleResizeBar.
Syntax
class CControlBar : public CWnd
Members
Protected Constructors
| Name | Description |
|---|---|
| CControlBar::CControlBar | Constructs a CControlBar object. |
Public Methods
| Name | Description |
|---|---|
| CControlBar::CalcDynamicLayout | Returns the size of a dynamic control bar as a CSize object. |
| CControlBar::CalcFixedLayout | Returns the size of the control bar as a CSize object. |
| CControlBar::CalcInsideRect | Returns the current dimensions of the control bar area; including the borders. |
| CControlBar::DoPaint | Renders the borders and gripper of the control bar. |
| CControlBar::DrawBorders | Renders the borders of the control bar. |
| CControlBar::DrawGripper | Renders the gripper of the control bar. |
| CControlBar::EnableDocking | Allows a control bar to be docked or floating. |
| CControlBar::GetBarStyle | Retrieves the control bar style settings. |
| CControlBar::GetBorders | Retrieves the border values of the control bar. |
| CControlBar::GetCount | Returns the number of non- HWND elements in the control bar. |
| CControlBar::GetDockingFrame | Returns a pointer to the frame to which a control bar is docked. |
| CControlBar::IsFloating | Returns a nonzero value if the control bar in question is a floating control bar. |
| CControlBar::OnUpdateCmdUI | Calls the Command UI handlers. |
| CControlBar::SetBarStyle | Modifies the control bar style settings. |
| CControlBar::SetBorders | Sets the border values of the control bar. |
| CControlBar::SetInPlaceOwner | Changes the in-place owner of a control bar. |
Public Data Members
| Name | Description |
|---|---|
| CControlBar::m_bAutoDelete | If nonzero, the CControlBar object is deleted when the Windows control bar is destroyed. |
| CControlBar::m_pInPlaceOwner | The in-place owner of the control bar. |
Remarks
A control bar is a window that is usually aligned to the left or right of a frame window. It may contain child items that are either HWND-based controls, which are windows that generate and respond to Windows messages, or non- HWND-based items, which are not windows and are managed by application code or framework code. List boxes and edit controls are examples of HWND-based controls; status-bar panes and bitmap buttons are examples of non- HWND-based controls.
Control-bar windows are usually child windows of a parent frame window and are usually siblings to the client view or MDI client of the frame window. A CControlBar object uses information about the parent window's client rectangle to position itself. It then informs the parent window as to how much space remains unallocated in the parent window's client area.
For more information on CControlBar, see:
Inheritance Hierarchy
CControlBar
Requirements
Header: afxext.h
CControlBar::CalcDynamicLayout
The framework calls this member function to calculate the dimensions of a dynamic toolbar.
virtual CSize CalcDynamicLayout(
int nLength,
DWORD nMode);
Parameters
nLength
The requested dimension of the control bar, either horizontal or vertical, depending on dwMode.
nMode
The following predefined flags are used to determine the height and width of the dynamic control bar. Use the bitwise-OR (|) operator to combine the flags.
| Layout mode flags | What it means |
|---|---|
| LM_STRETCH | Indicates whether the control bar should be stretched to the size of the frame. Set if the bar is not a docking bar (not available for docking). Not set when the bar is docked or floating (available for docking). If set, LM_STRETCH ignores nLength and returns dimensions based on the LM_HORZ state. LM_STRETCH works similarly to the bStretch parameter used in CalcFixedLayout; see that member function for more information about the relationship between stretching and orientation. |
| LM_HORZ | Indicates that the bar is horizontally or vertically oriented. Set if the bar is horizontally oriented, and if it is vertically oriented, it is not set. LM_HORZ works similarly to the bHorz parameter used in CalcFixedLayout; see that member function for more information about the relationship between stretching and orientation. |
| LM_MRUWIDTH | Most Recently Used Dynamic Width. Ignores nLength parameter and uses the remembered most recently used width. |
| LM_HORZDOCK | Horizontal Docked Dimensions. Ignores nLength parameter and returns the dynamic size with the largest width. |
| LM_VERTDOCK | Vertical Docked Dimensions. Ignores nLength parameter and returns the dynamic size with the largest height. |
| LM_LENGTHY | Set if nLength indicates height (Y-direction) instead of width. |
| LM_COMMIT | Resets LM_MRUWIDTH to current width of floating control bar. |
Return Value
The control bar size, in pixels, of a CSize object.
Remarks
Override this member function to provide your own dynamic layout in classes you derive from CControlBar. MFC classes derived from CControlBar, such as CToolbar, override this member function and provide their own implementation.
CControlBar::CalcFixedLayout
Call this member function to calculate the horizontal size of a control bar.
virtual CSize CalcFixedLayout(
BOOL bStretch,
BOOL bHorz);
Parameters
bStretch
Indicates whether the bar should be stretched to the size of the frame. The bStretch parameter is nonzero when the bar is not a docking bar (not available for docking) and is 0 when it is docked or floating (available for docking).
bHorz
Indicates that the bar is horizontally or vertically oriented. The bHorz parameter is nonzero if the bar is horizontally oriented and is 0 if it is vertically oriented.
Return Value
The control bar size, in pixels, of a CSize object.
Remarks
Control bars such as toolbars can stretch horizontally or vertically to accommodate the buttons contained in the control bar.
If bStretch is TRUE, stretch the dimension along the orientation provided by bHorz. In other words, if bHorz is FALSE, the control bar is stretched vertically. If bStretch is FALSE, no stretch occurs. The following table shows the possible permutations, and resulting control-bar styles, of bStretch and bHorz.
| bStretch | bHorz | Stretching | Orientation | Docking/Not docking |
|---|---|---|---|---|
| TRUE | TRUE | Horizontal stretching | Horizontally oriented | Not docking |
| TRUE | FALSE | Vertical stretching | Vertically oriented | Not docking |
| FALSE | TRUE | No stretching available | Horizontally oriented | Docking |
| FALSE | FALSE | No stretching available | Vertically oriented | Docking |
CControlBar::CalcInsideRect
The framework calls this function to calculate the client area of the control bar.
virtual void CalcInsideRect(
CRect& rect,
BOOL bHorz) const;
Parameters
rect
Contains the current dimensions of the control bar; including the borders.
bHorz
Indicates that the bar is horizontally or vertically oriented. The bHorz parameter is nonzero if the bar is horizontally oriented and is 0 if it is vertically oriented.
Remarks
This function is called before the control bar is painted.
Override this function to customize the rendering of the borders and gripper bar of the control bar.
CControlBar::CControlBar
Constructs a CControlBar object.
CControlBar();
CControlBar::DoPaint
Called by the framework to render the borders and gripper bar of the control bar.
virtual void DoPaint(CDC* pDC);
Parameters
pDC
Points to the device context to be used for rendering the borders and gripper of the control bar.
Remarks
Override this function to customize the drawing behavior of the control bar.
Another customization method is to override the DrawBorders and DrawGripper functions and add custom drawing code for the borders and gripper. Because these methods are called by the default DoPaint method, an override of DoPaint is not needed.
CControlBar::DrawBorders
Called by the framework to render the borders of the control bar.
virtual void DrawBorders(
CDC* pDC,
CRect& rect);
Parameters
pDC
Points to the device context to be used for rendering the borders of the control bar.
rect
A CRect object containing the dimensions of the control bar.
Remarks
Override this function to customize the appearance of the control bar borders.
CControlBar::DrawGripper
Called by the framework to render the gripper of the control bar.
virtual void DrawGripper(
CDC* pDC,
const CRect& rect);
Parameters
pDC
Points to the device context to be used for rendering the control bar gripper.
rect
A CRect object containing the dimensions of the control bar gripper.
Remarks
Override this function to customize the appearance of the control bar gripper.
CControlBar::EnableDocking
Call this function to enable a control bar to be docked.
void EnableDocking(DWORD dwDockStyle);
Parameters
dwDockStyle
Specifies whether the control bar supports docking and the sides of its parent window to which the control bar can be docked, if supported. Can be one or more of the following:
CBRS_ALIGN_TOP Allows docking at the top of the client area.
CBRS_ALIGN_BOTTOM Allows docking at the bottom of the client area.
CBRS_ALIGN_LEFT Allows docking on the left side of the client area.
CBRS_ALIGN_RIGHT Allows docking on the right side of the client area.
CBRS_ALIGN_ANY Allows docking on any side of the client area.
CBRS_FLOAT_MULTI Allows multiple control bars to be floated in a single mini-frame window.
If 0 (that is, indicating no flags), the control bar will not dock.
Remarks
The sides specified must match one of the sides enabled for docking in the destination frame window, or the control bar cannot be docked to that frame window.
CControlBar::GetBarStyle
Call this function to determine which CBRS_ (control bar styles) settings are currently set for the control bar.
DWORD GetBarStyle();
Return Value
The current CBRS_ (control bar styles) settings for the control bar. See CControlBar::SetBarStyle for the complete list of available styles.
Remarks
Does not handle WS_ (window style) styles.
CControlBar::GetBorders
Returns the current border values for the control bar.
CRect GetBorders() const;
Return Value
A CRect object that contains the current width (in pixels) of each side of the control bar object. For example, the value of the left member, of CRect object, is the width of the left hand border.
CControlBar::GetCount
Returns the number of non- HWND items on the CControlBar object.
int GetCount() const;
Return Value
The number of non- HWND items on the CControlBar object. This function returns 0 for a CDialogBar object.
Remarks
The type of the item depends on the derived object: panes for CStatusBar objects, and buttons and separators for CToolBar objects.
CControlBar::GetDockingFrame
Call this member function to obtain a pointer to the current frame window to which your control bar is docked.
CFrameWnd* GetDockingFrame() const;
Return Value
A pointer to a frame window if successful; otherwise NULL.
If the control bar is not docked to a frame window (that is, if the control bar is floating), this function will return a pointer to its parent CMiniFrameWnd.
Remarks
For more information about dockable control bars, see CControlBar::EnableDocking and CFrameWnd::DockControlBar.
CControlBar::IsFloating
Call this member function to determine whether the control bar is floating or docked.
BOOL IsFloating() const;
Return Value
Nonzero if the control bar is floating; otherwise 0.
Remarks
To change the state of a control bar from docked to floating, call CFrameWnd::FloatControlBar.
CControlBar::m_bAutoDelete
If nonzero, the CControlBar object is deleted when the Windows control bar is destroyed.
BOOL m_bAutoDelete;
Remarks
m_bAutoDelete is a public variable of type BOOL.
A control-bar object is usually embedded in a frame-window object. In this case, m_bAutoDelete is 0 because the embedded control-bar object is destroyed when the frame window is destroyed.
Set this variable to a nonzero value if you allocate a CControlBar object on the heap and you do not plan to call delete.
CControlBar::m_pInPlaceOwner
The in-place owner of the control bar.
CWnd* m_pInPlaceOwner;
CControlBar::OnUpdateCmdUI
This member function is called by the framework to update the status of the toolbar or status bar.
virtual void OnUpdateCmdUI(
CFrameWnd* pTarget,
BOOL bDisableIfNoHndler) = 0;
Parameters
pTarget
Points to the main frame window of the application. This pointer is used for routing update messages.
bDisableIfNoHndler
Flag that indicates whether a control that has no update handler should be automatically displayed as disabled.
Remarks
To update an individual button or pane, use the ON_UPDATE_COMMAND_UI macro in your message map to set an update handler appropriately. See ON_UPDATE_COMMAND_UI for more information about using this macro.
OnUpdateCmdUI is called by the framework when the application is idle. The frame window to be updated must be a child window, at least indirectly, of a visible frame window. OnUpdateCmdUI is an advanced overridable.
CControlBar::SetBarStyle
Call this function to set the desired CBRS_ styles for the control bar.
void SetBarStyle(DWORD dwStyle);
Parameters
dwStyle
The desired styles for the control bar. Can be one or more of the following:
CBRS_ALIGN_TOP Allows the control bar to be docked to the top of the client area of a frame window.
CBRS_ALIGN_BOTTOM Allows the control bar to be docked to the bottom of the client area of a frame window.
CBRS_ALIGN_LEFT Allows the control bar to be docked to the left side of the client area of a frame window.
CBRS_ALIGN_RIGHT Allows the control bar to be docked to the right side of the client area of a frame window.
CBRS_ALIGN_ANY Allows the control bar to be docked to any side of the client area of a frame window.
CBRS_BORDER_TOP Causes a border to be drawn on the top edge of the control bar when it would be visible.
CBRS_BORDER_BOTTOM Causes a border to be drawn on the bottom edge of the control bar when it would be visible.
CBRS_BORDER_LEFT Causes a border to be drawn on the left edge of the control bar when it would be visible.
CBRS_BORDER_RIGHT Causes a border to be drawn on the right edge of the control bar when it would be visible.
CBRS_FLOAT_MULTI Allows multiple control bars to be floated in a single mini-frame window.
CBRS_TOOLTIPS Causes tool tips to be displayed for the control bar.
CBRS_FLYBY Causes message text to be updated at the same time as tool tips.
CBRS_GRIPPER Causes a gripper, similar to that used on bands in a
CReBarobject, to be drawn for anyCControlBar-derived class.
Remarks
Does not affect the WS_ (window style) settings.
CControlBar::SetBorders
Call this function to set the size of the control bar's borders.
void SetBorders(
int cxLeft = 0,
int cyTop = 0,
int cxRight = 0,
int cyBottom = 0);
void SetBorders(LPCRECT lpRect);
Parameters
cxLeft
The width (in pixels) of the control bar's left border.
cyTop
The height (in pixels) of the control bar's top border.
cxRight
The width (in pixels) of the control bar's right border.
cyBottom
The height (in pixels) of the control bar's bottom border.
lpRect
A pointer to a CRect object that contains the current width (in pixels)of each border of the control bar object.
Example
The following code example sets the top and bottom borders of the control bar to 5 pixels, and the left and right borders to 2 pixels:
CControlBar &m_myControlBar = m_Rebar;
m_myControlBar.SetBorders(2, 5, 2, 5);
CControlBar::SetInPlaceOwner
Changes the in-place owner of a control bar.
void SetInPlaceOwner(CWnd* pWnd);
Parameters
pWnd
A pointer to a CWnd object.
Remarks
See also
MFC Sample CTRLBARS
CWnd Class
Hierarchy Chart
CToolBar Class
CDialogBar Class
CStatusBar Class
CReBar Class
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for