CControlBar Class

项目
10/12/2023

控件条类 CStatusBar、CToolBar、CDialogBar、CReBar 和 COleResizeBar 的基类。

语法

class CControlBar : public CWnd

成员

受保护构造函数

名称	描述
CControlBar::CControlBar	构造 `CControlBar` 对象。

公共方法

名称	描述
CControlBar::CalcDynamicLayout	以 CSize 对象的形式返回动态控件条的大小。
CControlBar::CalcFixedLayout	以 CSize 对象的形式返回控件条的大小。
CControlBar::CalcInsideRect	返回控件条区域的当前维度；包括边框。
CControlBar::DoPaint	呈现控件条的边框和手柄。
CControlBar::DrawBorders	呈现控件条的边框。
CControlBar::DrawGripper	呈现控件条的手柄。
CControlBar::EnableDocking	允许控件条停靠或浮动。
CControlBar::GetBarStyle	检索控件条样式设置。
CControlBar::GetBorders	检索控件条的边框值。
CControlBar::GetCount	返回控件条中的非 HWND 元素数。
CControlBar::GetDockingFrame	返回指向控件条停靠到的框架的指针。
CControlBar::IsFloating	如果所涉及的控件条是浮动控件条，则返回非零值。
CControlBar::OnUpdateCmdUI	调用命令 UI 处理程序。
CControlBar::SetBarStyle	修改控件条样式设置。
CControlBar::SetBorders	设置控件条的边框值。
CControlBar::SetInPlaceOwner	更改控件条的就地所有者。

公共数据成员

“属性”	描述
CControlBar::m_bAutoDelete	如果为非零，则当 Windows 控件条被销毁时，将删除 `CControlBar` 对象。
CControlBar::m_pInPlaceOwner	控件条的就地所有者。

备注

控件条是通常与框架窗口的左侧或右侧对齐的窗口。它可能包含子项，这些子项是基于 HWND 的控件（即生成和响应 Windows 消息的窗口）或非基于 HWND 的项（不是窗口，由应用程序代码或框架代码管理）。列表框和编辑控件是基于 HWND 的控件的示例；状态栏窗格和位图按钮是非 HWND 控件的示例。

控件条窗口通常是父框架窗口的子窗口，通常是框架窗口的客户端视图或 MDI 客户端的同级窗口。 CControlBar 对象使用有关其父窗口的客户端矩形的信息为自己定位。然后，它会通知父窗口在父窗口的工作区中有多少未分配的空间。

有关 CControlBar 的详细信息，请参阅：

继承层次结构

CObject

CCmdTarget

CWnd

CControlBar

要求

标头：afxext.h

CControlBar::CalcDynamicLayout

框架调用此成员函数来计算动态工具栏的维度。

virtual CSize CalcDynamicLayout(
    int nLength,
    DWORD nMode);

参数

nLength
控件条的请求维度（水平或垂直，取决于 dwMode）。

nMode
以下预定义的标志用于确定动态控件条的高度和宽度。使用按位 OR (|) 运算符合并标志。

布局模式标志	含义
LM_STRETCH	指示是否应将控件条拉伸到框架的大小。如果不是停靠条（不可停靠），则设置。当条停靠或浮动（可停靠）时，则不设置。如果设置，LM_STRETCH 将忽略 nLength，并根据 LM_HORZ 状态返回维度。 LM_STRETCH 的工作原理类似于 CalcFixedLayout 中使用的 bStretch 参数；有关拉伸和方向之间的关系的详细信息，请参阅该成员函数。
LM_HORZ	指示条是水平方向还是垂直方向。如果条是水平方向，则设置，如果是垂直方向，则不设置。 LM_HORZ 的工作原理类似于 CalcFixedLayout 中使用的 bHorz 参数；有关拉伸和方向之间的关系的详细信息，请参阅该成员函数。
LM_MRUWIDTH	最近一次使用的动态宽度。忽略 nLength 参数并使用所记忆的最近一次使用的宽度。
LM_HORZDOCK	水平停靠维度。忽略 nLength 参数并返回具有最大宽度的动态大小。
LM_VERTDOCK	垂直停靠维度。忽略 nLength 参数并返回具有最大高度的动态大小。
LM_LENGTHY	如果 nLength 指示高度（Y 方向）而不是宽度，则设置。
LM_COMMIT	将 LM_MRUWIDTH 重置为浮动控件条的当前宽度。

返回值

CSize 对象的控件条大小（以像素为单位）。

备注

替代此成员函数以在派生自 CControlBar 的类中提供你自己的动态布局。派生自 CToolbar 等 CControlBar 的 MFC 类将替代此成员函数并提供自己的实现。

CControlBar::CalcFixedLayout

调用此成员函数以计算控件条的水平大小。

virtual CSize CalcFixedLayout(
    BOOL bStretch,
    BOOL bHorz);

参数

bStretch
指示是否应将条拉伸到框架大小。如果不是停靠条（不可停靠），bStretch 参数为非零，如果条停靠或浮动（可停靠），则为 0。

bHorz
指示条是水平方向还是垂直方向。如果条是水平方向，bHorz 参数为非零，如果是垂直方向，则为 0。

返回值

CSize 对象的控件条大小（以像素为单位）。

备注

控件条（如工具栏）可以水平或垂直拉伸以适应控件条中包含的按钮。

如果 bStretch 为 TRUE，则沿 bHorz 提供的方向拉伸维度。换句话说，如果 bHorz 为 FALSE，则垂直拉伸控件条。如果 bStretch 为 FALSE，则不会发生拉伸。下表显示了 bStretch 和 bHorz 可能的排列组合发生以及生成的控件条样式。

bStretch	bHorz	拉伸	方向	停靠/未停靠
TRUE	TRUE	水平拉伸	水平方向	不停靠
TRUE	FALSE	垂直拉伸	垂直方向	不停靠
FALSE	TRUE	不拉伸	水平方向	停靠
FALSE	FALSE	不拉伸	垂直方向	停靠

CControlBar::CalcInsideRect

框架调用此函数来计算控件条的工作区。

virtual void CalcInsideRect(
    CRect& rect,
    BOOL bHorz) const;

参数

rect
包含控件条的当前维度；包括边框。

bHorz
指示条是水平方向还是垂直方向。如果条是水平方向，bHorz 参数为非零，如果是垂直方向，则为 0。

注解

在绘制控件条之前调用此函数。

替代此函数以自定义控件条的边框和手柄条的呈现。

CControlBar::CControlBar

构造 CControlBar 对象。

CControlBar();

CControlBar::DoPaint

由框架调用以呈现控件条的边框和手柄条。

virtual void DoPaint(CDC* pDC);

参数

pDC
指向用于呈现控件条边框和手柄的设备上下文。

备注

替代此函数以自定义控件条的绘制行为。

另一种自定义方法是替代 DrawBorders 和 DrawGripper 函数，并为边框和手柄添加自定义绘图代码。由于这些方法由默认 DoPaint 方法调用，因此不需要替代 DoPaint。

CControlBar::DrawBorders

由框架调用以呈现控件条的边框。

virtual void DrawBorders(
    CDC* pDC,
    CRect& rect);

参数

pDC
指向用于呈现控件条边框的设备上下文。

rect
包含控件条维度的 CRect 对象。

备注

替代此函数以自定义控件条边框的外观。

CControlBar::DrawGripper

由框架调用以呈现控件条的手柄。

virtual void DrawGripper(
    CDC* pDC,
    const CRect& rect);

参数

pDC
指向用于呈现控件条手柄的设备上下文。

rect
包含控件条手柄维度的 CRect 对象。

备注

替代此函数以自定义控件条手柄的外观。

CControlBar::EnableDocking

调用此函数以使控件条能够停靠。

void EnableDocking(DWORD dwDockStyle);

参数

dwDockStyle
指定控件条是否支持停靠，以及控件条可停靠到其父窗口的哪一侧（如果支持停靠）。可以是以下一项或多项：

CBRS_ALIGN_TOP 允许停靠在工作区的顶部。
CBRS_ALIGN_BOTTOM 允许停靠在工作区的底部。
CBRS_ALIGN_LEFT 允许停靠在工作区的左侧。
CBRS_ALIGN_RIGHT 允许停靠在工作区的右侧。
CBRS_ALIGN_ANY 允许停靠在工作区的任意一侧。
CBRS_FLOAT_MULTI 允许多个控件条在单个微型框窗口中浮动。

如果为 0（表示没有标志），则控件条将不会停靠。

备注

指定的侧必须与目标框架窗口中为停靠启用的侧匹配，否则控件条无法停靠到该框架窗口。

CControlBar::GetBarStyle

调用此函数可确定当前为控件条设置的 CBRS_（控件条样式）设置。

DWORD GetBarStyle();

返回值

控件条的当前 CBRS_（控件条样式）设置。有关可用样式的完整列表，请参阅 CControlBar::SetBarStyle。

注解

不处理 WS_（窗口样式）样式。

CControlBar::GetBorders

返回控件条的当前边框值。

CRect GetBorders() const;

返回值

包含控件条对象每一侧的当前宽度（以像素为单位）的 CRect 对象。例如，CRect 对象的 left 成员的值为左边框的宽度。

CControlBar::GetCount

返回 CControlBar 对象上的非 HWND 项数。

int GetCount() const;

返回值

CControlBar 对象上的非 HWND 项数。此函数为 CDialogBar 对象返回 0。

备注

项的类型取决于派生的对象：CStatusBar 对象为窗格，CToolBar 对象为按钮和分隔符。

CControlBar::GetDockingFrame

调用此成员函数，可获取指向控件条要停靠到的当前框架窗口的指针。

CFrameWnd* GetDockingFrame() const;

返回值

如果成功，则为指向框架窗口的指针；否则为 NULL。

如果控件条未停靠到框架窗口（也就是说，如果控件条是浮动的），则此函数将返回指向其父 CMiniFrameWnd 的指针。

备注

有关可停靠控件条的详细信息，请参阅 CControlBar::EnableDocking 和 CFrameWnd::DockControlBar。

CControlBar::IsFloating

调用此成员函数可确定控件条是浮动还是停靠。

BOOL IsFloating() const;

返回值

如果控件条浮动，则为非零；否则为 0。

备注

若要将控件条的状态从停靠更改为浮动，请调用 CFrameWnd::FloatControlBar。

CControlBar::m_bAutoDelete

如果为非零，则当 Windows 控件条被销毁时，将删除 CControlBar 对象。

BOOL m_bAutoDelete;

备注

m_bAutoDelete 是 BOOL 类型的公共变量。

控件条对象通常嵌入在框架窗口对象中。在这种情况下，m_bAutoDelete 为 0，因为当框架窗口被销毁时，嵌入的控件条对象也将被销毁。

如果在堆上分配 CControlBar 对象，并且不打算调用 delete，请将此变量设置为非零值。

CControlBar::m_pInPlaceOwner

控件条的就地所有者。

CWnd* m_pInPlaceOwner;

CControlBar::OnUpdateCmdUI

此成员函数由框架调用，以更新工具栏或状态栏的状态。

virtual void OnUpdateCmdUI(
    CFrameWnd* pTarget,
    BOOL bDisableIfNoHndler) = 0;

参数

pTarget
指向应用程序的主框架窗口。此指针用于路由更新消息。

bDisableIfNoHndler
指示是否应将没有更新处理程序的控件自动显示为已禁用的标志。

备注

若要更新单个按钮或窗格，请在消息映射中使用 ON_UPDATE_COMMAND_UI 宏相应地设置更新处理程序。有关使用此宏的详细信息，请参阅 ON_UPDATE_COMMAND_UI。

OnUpdateCmdUI 在应用程序闲置时由框架调用。要更新的框架窗口必须是可见框架窗口的子窗口（至少是间接的）。 OnUpdateCmdUI 这是一个高级可替代函数。

CControlBar::SetBarStyle

调用此函数可设置控件条所需的 CBRS_ 样式。

void SetBarStyle(DWORD dwStyle);

参数

dwStyle
控件条的所需样式。可以是以下一项或多项：

CBRS_ALIGN_TOP 允许将控件条停靠到框架窗口的工作区顶部。
CBRS_ALIGN_BOTTOM 允许将控件条停靠到框架窗口的工作区底部。
CBRS_ALIGN_LEFT 允许将控件条停靠到框架窗口的工作区左侧。
CBRS_ALIGN_RIGHT 允许将控件条停靠到框架窗口的工作区右侧。
CBRS_ALIGN_ANY 允许将控件条停靠到框架窗口的工作区任意一侧。
CBRS_BORDER_TOP 使边框在可见时绘制在控件条的上边缘。
CBRS_BORDER_BOTTOM 使边框在可见时绘制在控件条的下边缘。
CBRS_BORDER_LEFT 使边框在可见时绘制在控件条的左边缘。
CBRS_BORDER_RIGHT 使边框在可见时绘制在控件条的右边缘。
CBRS_FLOAT_MULTI 允许多个控件条在单个微型框窗口中浮动。
CBRS_TOOLTIPS 使控件条显示工具提示。
CBRS_FLYBY 使消息文本与工具提示同时更新。
CBRS_GRIPPER 允许为任何 CReBar 派生类绘制手柄，类似于 CControlBar 对象中的带上使用的手柄。

备注

不影响 WS_（窗口样式）设置。

CControlBar::SetBorders

调用此函数可设置控件条边框的大小。

void SetBorders(
    int cxLeft = 0,
    int cyTop = 0,
    int cxRight = 0,
    int cyBottom = 0);

void SetBorders(LPCRECT lpRect);

参数

cxLeft
控件条左边框的宽度（以像素为单位）。

cyTop
控件条上边框的高度（以像素为单位）。

cxRight
控件条右边框的宽度（以像素为单位）。

cyBottom
控件条下边框的高度（以像素为单位）。

lpRect
指向包含控件条对象每个边框的当前宽度的 CRect 对象的指针。

示例

下面的代码示例将控件条的上边框和下边框设置为 5 像素，将左边框和右边框设置为 2 像素：

CControlBar &m_myControlBar = m_Rebar;
m_myControlBar.SetBorders(2, 5, 2, 5);

CControlBar::SetInPlaceOwner

更改控件条的就地所有者。

void SetInPlaceOwner(CWnd* pWnd);

参数

pWnd
一个指向 CWnd 对象的指针。

备注

另请参阅

MFC 示例 CTRLBARS
CWnd 类
 层次结构图
 CToolBar 类
 CDialogBar 类
 CStatusBar 类
 CReBar 类