CStatusBar 类

项目
06/16/2023

含有文本输出窗格或“指示符”的控件条。

语法

class CStatusBar : public CControlBar

成员

公共构造函数

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

公共方法

名称	描述
CStatusBar::CommandToIndex	获取给定指示器 ID 的索引。
CStatusBar::Create	创建状态栏，将其附加到 `CStatusBar` 对象，并设置初始字体和栏高度。
CStatusBar::CreateEx	为嵌入式 `CStatusBarCtrl` 对象创建具有其他样式的 `CStatusBar` 对象。
CStatusBar::DrawItem	当所有者绘制的状态栏控件的可视特征发生变化时调用。
CStatusBar::GetItemID	获取给定索引的指示器 ID。
CStatusBar::GetItemRect	获取给定索引的显示矩形。
CStatusBar::GetPaneInfo	获取给定索引的指示器 ID、样式和宽度。
CStatusBar::GetPaneStyle	获取给定索引的指示器样式。
CStatusBar::GetPaneText	获取给定索引的指示器文本。
CStatusBar::GetStatusBarCtrl	允许直接访问基础公共控件。
CStatusBar::SetIndicators	设置指示器 ID。
CStatusBar::SetPaneInfo	设置给定索引的指示器 ID、样式和宽度。
CStatusBar::SetPaneStyle	设置给定索引的指示器样式。
CStatusBar::SetPaneText	设置给定索引的指示器文本。

备注

输出窗格通常用作消息行和状态指示器。示例包括简要说明所选菜单命令的菜单帮助消息行，以及显示 SCROLL LOCK、NUM LOCK 和其他键的状态的指示器。

CStatusBar::GetStatusBarCtrl 是 MFC 4.0 新增的成员函数，允许利用 Windows 通用控件支持实现状态栏栏自定义和其他功能。 CStatusBar 成员函数提供 Windows 公共控件的大部分功能；但是，当你调用 GetStatusBarCtrl 时，可以为状态栏赋予更多 Windows 95/98 状态栏的特征。调用 GetStatusBarCtrl时，它将返回对 CStatusBarCtrl 对象的引用。有关使用 Windows 公共控件设计工具栏的详细信息，请参阅 CStatusBarCtrl。如需详细了解常用控件的一般信息，请参阅 Windows SDK 中的常用控件。

框架将指示器信息存储在数组中，最左边的指示器位于位置 0。创建状态栏时，可以使用框架将其与相应指示器关联的字符串 ID 数组。然后，可以使用字符串 ID 或索引来访问指示器。

默认情况下，第一个指示器具有“弹性”：它占用其他指示器窗格未使用的状态栏长度，使其他窗格右对齐。

若要创建状态栏，请执行以下步骤：

构造 CStatusBar 对象。
调用 Create（或 CreateEx）函数来创建状态栏窗口并将其附加到 CStatusBar 对象。
调用 SetIndicators 以将字符串 ID 与每个指示器相关联。

可通过三种方法更新状态栏窗格中的文本：

调用 CWnd::SetWindowText 以仅更新窗格 0 中的文本。
在状态栏的 ON_UPDATE_COMMAND_UI 处理程序中调用 CCmdUI::SetText。
调用 SetPaneText 以更新所有窗格的文本。

调用 SetPaneStyle 以更新状态栏窗格的样式。

有关使用 CStatusBar 的详细信息，请参阅文章 MFC 中的状态栏实现和技术说明 31：控件条。

继承层次结构

CStatusBar

要求

标头：afxext.h

CStatusBar::CommandToIndex

获取给定 ID 的指示器索引。

int CommandToIndex(UINT nIDFind) const;

参数

nIDFind
要检索其索引的指示器的字符串 ID。

返回值

如果成功，则返回指示器的索引；如果失败，则返回 -1。

备注

第一个指示器的索引为 0。

CStatusBar::Create

创建状态栏（子窗口）并将其与 CStatusBar 对象相关联。

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_BOTTOM,
    UINT nID = AFX_IDW_STATUS_BAR);

参数

pParentWnd
指向 CWnd 对象的指针，该对象的 Windows 窗口是状态栏的父级。

dwStyle
状态栏样式。除了标准 Windows 样式外，还支持以下样式。

CBRS_TOP 控件条位于框架窗口顶部。
CBRS_BOTTOM 控件条位于框架窗口底部。
CBRS_NOALIGN 控件条在父级调整大小时不会重新定位。

nID
工具栏的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

同时设置初始字体并将状态栏的高度设置为默认值。

CStatusBar::CreateEx

调用此函数以创建状态栏（子窗口）并将其与 CStatusBar 对象相关联。

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwCtrlStyle = 0,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_BOTTOM,
    UINT nID = AFX_IDW_STATUS_BAR);

参数

pParentWnd
指向 CWnd 对象的指针，该对象的 Windows 窗口是状态栏的父级。

dwCtrlStyle
用于创建嵌入式 CStatusBarCtrl 对象的其他样式。默认值指定一个没有大小调整手柄或工具提示支持的状态栏。支持的状态栏样式包括：

SBARS_SIZEGRIP 状态栏控件在状态栏的右端提供一个大小调整手柄。大小调整手柄类似于大小调整边框；它是用户可以通过单击和拖动来重设父窗口大小的矩形区域。
SBT_TOOLTIPS 状态栏支持工具提示。

有关这些样式的详细信息，请参阅 CStatusBarCtrl 的设置。

dwStyle
状态栏样式。默认值指定在框架窗口底部创建可见状态栏。应用窗口样式和 CDialogBar::Create 中列出的状态栏控件样式的任意组合。但是，此参数应始终包含 WS_CHILD 和 WS_VISIBLE 样式。

nID
状态栏的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

此函数还设置初始字体并将状态栏的高度设置为默认值。

在创建嵌入式状态栏控件期间需要存在某些样式时，请使用 CreateEx，而不是 Create。例如，将 dwCtrlStyle 设置为 SBT_TOOLTIPS，以在状态栏对象中显示工具提示。

CStatusBar::CStatusBar

构造 CStatusBar 对象，根据需要创建默认状态栏字体，并将字体特征设置为默认值。

CStatusBar();

CStatusBar::DrawItem

当所有者绘制的状态栏的可视特征发生变化时，框架会调用此成员函数。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向 DRAWITEMSTRUCT 结构的指针，该结构包含有关所需绘制类型的信息。

注解

DRAWITEMSTRUCT 结构的 itemAction 成员定义要执行的绘制操作。替代此成员函数以实现所有者绘制 CStatusBar 对象的绘制。在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

CStatusBar::GetItemID

返回 nIndex 指定的指示器的 ID。

UINT GetItemID(int nIndex) const;

参数

nIndex
将检索其 ID 的指示器的索引。

返回值

nIndex 指定的指示器的 ID。

CStatusBar::GetItemRect

将 nIndex 指定的指示器坐标复制到 lpRect 指向的结构中。

void GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

参数

nIndex
将检索其矩形坐标的指示器的索引。

lpRect
指向 RECT 结构或 CRect 对象，该结构或对象将接收 nIndex 指定的指示器的坐标。

注解

坐标相对于状态栏的左上角（以像素为单位）。

CStatusBar::GetPaneInfo

将 nID、nStyle 和 cxWidth 设置为 nIndex 指定的位置处的指示器窗格的 ID、样式和宽度。

void GetPaneInfo(
    int nIndex,
    UINT& nID,
    UINT& nStyle,
    int& cxWidth) const;

参数

nIndex
将检索其信息的窗格的索引。

nID
对设置为窗格 ID 的 UINT 的引用。

nStyle
对设置为窗格样式的 UINT 的引用。

cxWidth
对设置为窗格宽度的整数的引用。

CStatusBar::GetPaneStyle

调用此成员函数以检索状态栏窗格的样式。

UINT GetPaneStyle(int nIndex) const;

参数

nIndex
将检索其样式的窗格的索引。

返回值

nIndex 指定的状态栏窗格的样式。

注解

窗格的样式决定了窗格的显示方式。

有关可用于状态栏的样式列表，请参阅 Create。

CStatusBar::GetPaneText

调用此成员函数以检索状态栏窗格中显示的文本。

CString GetPaneText(int nIndex) const;  void GetPaneText(int nIndex, CString& rString) const;

参数

nIndex
将检索其文本的窗格的索引。

rString
对 CString 对象的引用，该对象包含要检索的文本。

返回值

包含窗格文本的 CString 对象。

备注

此成员函数的第二种形式用字符串文本填充 CString 对象。

CStatusBar::GetStatusBarCtrl

此成员函数允许直接访问基础常用控件。

CStatusBarCtrl& GetStatusBarCtrl() const;

返回值

包含对 CStatusBarCtrl 对象的引用。

备注

使用 GetStatusBarCtrl 可利用 Windows 状态栏公共控件的功能和 CStatusBarCtrl 提供的支持进行状态栏自定义。例如，通过使用公共控件，可以指定在状态栏上包含大小调整手柄的样式，或者可以指定使状态栏出现在父窗口工作区顶部的样式。

如需详细了解公共控件的一般信息，请参阅 Windows SDK 中的公共控件。

CStatusBar::SetIndicators

将每个指示器的 ID 设置为数组 lpIDArray 的相应元素指定的值，加载每个 ID 指定的字符串资源，并将指示器的文本设置为字符串。

BOOL SetIndicators(
    const UINT* lpIDArray,
    int nIDCount);

参数

lpIDArray
指向 ID 数组的指针。

nIDCount
lpIDArray 指向的数组中的元素数。

返回值

如果成功，则不为 0；否则为 0。

CStatusBar::SetPaneInfo

将指定的指示器窗格设置为新的 ID、样式和宽度。

void SetPaneInfo(
    int nIndex,
    UINT nID,
    UINT nStyle,
    int cxWidth);

参数

nIndex
将设置其样式的指示器窗格的索引。

nID
指示器窗格的新 ID。

nStyle
指示器窗格的新样式。

cxWidth
指示器窗格的新宽度。

备注

支持以下指示器样式：

SBPS_NOBORDERS 窗格周围没有 3-D 边框。
SBPS_POPOUT 反转边框，使文本“弹出”。
SBPS_DISABLED 不绘制文本。
SBPS_STRETCH 拉伸窗格以填充未使用的空间。每个状态栏只能有一个窗格具有此样式。
SBPS_NORMAL 无拉伸、边框或弹出。

CStatusBar::SetPaneStyle

调用此成员函数以设置状态栏窗格的样式。

void SetPaneStyle(
    int nIndex,
    UINT nStyle);

参数

nIndex
将设置其样式的窗格的索引。

nStyle
将设置其样式的窗格的样式。

备注

窗格的样式决定了窗格的显示方式。

有关可用于状态栏的样式列表，请参阅 SetPaneInfo。

CStatusBar::SetPaneText

调用此成员函数以将窗格文本设置为 lpszNewText 指向的字符串。

BOOL SetPaneText(
    int nIndex,
    LPCTSTR lpszNewText,
    BOOL bUpdate = TRUE);

参数

nIndex
将设置其文本的窗格的索引。

lpszNewText
指向新窗格文本的指针。

bUpdate
如果为 TRUE，则在设置文本后窗格将失效。

返回值

如果成功，则不为 0；否则为 0。

备注

调用 SetPaneText 后，必须添加 UI 更新处理程序才能在状态栏中显示新文本。

示例

//Sets and displays text for pane index 3 and id ID_INDICATOR_SCRL
m_wndStatusBar.SetPaneText(3, _T("My New Status Bar Text"), TRUE);

//UI handler in the message map updates the status bar text:
ON_UPDATE_COMMAND_UI(ID_INDICATOR_SCRL, &CMainFrame::OnUpdatePane)

void CMainFrame::OnUpdatePane(CCmdUI* pCmdUI)
{
   pCmdUI->Enable();
}

另请参阅

MFC 示例 CTRLBARS
MFC Sample DLGCBR32
CControlBar Class
层次结构图
 CStatusBarCtrl 类
 CControlBar Class

通过

CStatusBar 类

语法

成员

公共构造函数

公共方法

备注

继承层次结构

要求

CStatusBar::CommandToIndex

参数

返回值

备注

CStatusBar::Create

参数

返回值

备注

CStatusBar::CreateEx

参数

返回值

备注

CStatusBar::CStatusBar

CStatusBar::DrawItem

参数

注解

CStatusBar::GetItemID

参数

返回值

CStatusBar::GetItemRect

参数

注解

CStatusBar::GetPaneInfo

参数

CStatusBar::GetPaneStyle

参数

返回值

注解

CStatusBar::GetPaneText

参数

返回值

备注

CStatusBar::GetStatusBarCtrl

返回值

备注

CStatusBar::SetIndicators

参数

返回值

CStatusBar::SetPaneInfo

参数

备注

CStatusBar::SetPaneStyle

参数

备注

CStatusBar::SetPaneText

参数

返回值

备注

示例

另请参阅

反馈

其他资源