CStatusBarCtrl 类

项目
06/16/2023

提供 Windows 公共状态栏控件的功能。

语法

class CStatusBarCtrl : public CWnd

成员

公共构造函数

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

公共方法

名称	描述
CStatusBarCtrl::Create	创建状态栏控件并将其附加到 `CStatusBarCtrl` 对象。
CStatusBarCtrl::CreateEx	创建具有指定 Windows 扩展样式的状态栏控件，并将其附加到 `CStatusBarCtrl` 对象。
CStatusBarCtrl::DrawItem	当所有者绘制的状态栏控件的可视特征发生变化时调用。
CStatusBarCtrl::GetBorders	检索状态栏控件的水平和垂直边框的当前宽度。
CStatusBarCtrl::GetIcon	检索当前状态栏控件中部件（也称为窗格）的图标。
CStatusBarCtrl::GetParts	检索状态栏控件中部件的计数。
CStatusBarCtrl::GetRect	检索状态栏控件中部件的边框。
CStatusBarCtrl::GetText	从状态栏控件的给定部分中检索文本。
CStatusBarCtrl::GetTextLength	从状态栏控件的给定部分中检索文本的长度（以字符为单位）。
CStatusBarCtrl::GetTipText	检索状态栏中窗格的工具提示文本。
CStatusBarCtrl::IsSimple	检查状态窗口控件以确定它是否处于简单模式。
CStatusBarCtrl::SetBkColor	设置状态栏中的背景色。
CStatusBarCtrl::SetIcon	设置状态栏中窗格的图标。
CStatusBarCtrl::SetMinHeight	设置状态栏控件绘图区域的最小高度。
CStatusBarCtrl::SetParts	设置状态栏控件中的部件数以及每个部件右边缘的坐标。
CStatusBarCtrl::SetSimple	指定状态栏控件是显示简单文本，还是显示由上一次调用 `SetParts` 设置的所有控件部件。
CStatusBarCtrl::SetText	设置状态栏控件给定部分中的文本。
CStatusBarCtrl::SetTipText	设置状态栏中窗格的工具提示文本。

备注

“状态栏控件”是一个水平窗口，通常显示在父窗口底部，应用程序可在此显示各种状态信息。状态栏控件可以分为几个部分，以显示多种类型的信息。

此控件（以及 CStatusBarCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

有关使用 CStatusBarCtrl 的详细信息，请参阅控件和使用 CStatusBarCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CStatusBarCtrl

要求

标头： afxcmn.h

CStatusBarCtrl::Create

创建状态栏控件并将其附加到 CStatusBarCtrl 对象。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwStyle
指定状态栏控件的样式。应用 Windows SDK 中公共控件样式中列出的状态栏控件样式的任意组合。此参数必须包含 WS_CHILD 样式。它还应包含 WS_VISIBLE 样式。

rect
指定状态栏控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定状态栏控件的父窗口，通常为 CDialog。不得为 NULL。

nID
指定状态栏控件的 ID。

返回值

如果成功，则不为零，否则为零。

备注

分两步构建 CStatusBarCtrl。首先，调用构造函数，然后调用 Create，这将创建状态栏控件并将其附加到 CStatusBarCtrl 对象。

状态窗口的默认位置位于父窗口的底部，但可指定 CCS_TOP 样式让其显示在父窗口工作区的顶部。还可以指定 SBARS_SIZEGRIP 样式以在状态窗口的右侧包含一个大小调整手柄。不建议将 CCS_TOP 和 SBARS_SIZEGRIP 样式组合在一起，因为生成的大小调整手柄将不工作，即使系统在状态窗口中绘制它也是如此。

若要创建具有扩展窗口样式的状态栏，请调用 CStatusBarCtrl::CreateEx 而不是 Create。

示例

VERIFY(m_wndSBC.Create(WS_CHILD | WS_VISIBLE | CCS_BOTTOM | SBARS_SIZEGRIP,
                       CRect(0, 0, 0, 0), this, IDC_STATUSBARCTRL));

CStatusBarCtrl::CreateEx

创建一个控件（子窗口）并将其与 CStatusBarCtrl 对象相关联。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

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

注解

使用 CreateEx 而不是 Create 来应用由 Windows 扩展样式前言 WS_EX_ 指定的扩展 Windows 样式。

CStatusBarCtrl::CStatusBarCtrl

构造 CStatusBarCtrl 对象。

CStatusBarCtrl();

CStatusBarCtrl::DrawItem

当所有者描述的状态栏控件的可视特征发生变化时由框架调用。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向 DRAWITEMSTRUCT 结构的长指针，其中包含有关所需绘图类型的信息。

注解

DRAWITEMSTRUCT 结构的 itemAction 成员定义要执行的绘制操作。

默认情况下，此成员函数不执行任何操作。替代此成员函数以实现所有者绘制 CStatusBarCtrl 对象的绘制。

在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

CStatusBarCtrl::GetBorders

检索状态栏控件的水平和垂直边框以及矩形之间空间的当前宽度。

BOOL GetBorders(int* pBorders) const;

BOOL GetBorders(
    int& nHorz,
    int& nVert,
    int& nSpacing) const;

参数

pBorders
具有三个元素的整数数组的地址。第一个元素接收水平边框的宽度，第二个元素接收垂直边框的宽度，第三个元素接收矩形之间边框的宽度。

nHorz
对接收水平边框宽度的整数的引用。

nVert
对接收垂直边框宽度的整数的引用。

nSpacing
对接收矩形之间边框宽度的整数的引用。

返回值

如果成功，则不为零，否则为零。

备注

这些边框确定控件的外边缘与控件中包含文本的矩形之间的间距。

示例

RECT rectPane1;
VERIFY(m_wndSBC.GetRect(1, &rectPane1));

int borderArray[3];
VERIFY(m_wndSBC.GetBorders(borderArray));

int nHorz, nVert, nSpacing;
VERIFY(m_wndSBC.GetBorders(nHorz, nVert, nSpacing));

CStatusBarCtrl::GetIcon

检索当前状态栏控件中部件（也称为窗格）的图标。

HICON GetIcon(int iPart) const;

参数

iPart
[in] 包含要检索的图标的部件的从零开始的索引。如果此参数为 -1，则假定状态栏为简单模式状态栏。

返回值

如果方法成功，则图标的句柄；否则为 NULL。

注解

此方法发送 SB_GETICON 消息，如 Windows SDK 中所述。

状态栏控件由一行文本输出窗格（也称为部件）组成。有关状态栏的详细信息，请参阅 MFC 中的状态栏实现和设置 CStatusBarCtrl 对象的模式。

示例

第一个代码示例定义一个变量 m_statusBar，用于访问当前状态栏控件。此变量将在下一个示例中使用。

public:
CStatusBarCtrl m_statusBar;

下一个代码示例将图标复制到当前状态栏控件的两个窗格中。在代码示例的前面部分中，我们创建了一个具有三个窗格的状态栏控件，然后向第一个窗格添加了一个图标。本示例从第一个窗格中检索图标，然后将其添加到第二个和第三个窗格中。

// Get the icon from pane 1 and set it in panes 2 and 3.
HICON hIcon = m_statusBar.GetIcon(0);
m_statusBar.SetIcon(1, hIcon);
m_statusBar.SetIcon(2, hIcon);

CStatusBarCtrl::GetParts

检索状态栏控件中部件的计数。

int GetParts(
    int nParts,
    int* pParts) const;

参数

nParts
要检索坐标的部件数。如果此参数大于控件中的部件数，则该消息仅检索现有部件的坐标。

pParts
整数数组的地址，其元素数与 nParts 指定的部分数相同。数组中的每个元素接收相应部分右边缘的客户端坐标。如果元素设置为 - 1，则该部件的右边缘的位置将扩展到状态栏的右边缘。

返回值

控件中的部件数（如果成功），否则为零。

备注

此成员函数还检索给定数量零件的右边缘的坐标。

示例

int pParts[2];

int nParts = m_wndSBC.GetParts(2, pParts);

CStatusBarCtrl::GetRect

检索状态栏控件中部件的边框。

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

参数

nPane
要检索其边框的部件的从零开始的索引。

lpRect
接收边框的 RECT 结构的地址。

返回值

如果成功，则不为零，否则为零。

示例

CRect rectPane1;

VERIFY(m_wndSBC.GetRect(1, &rectPane1));

CStatusBarCtrl::GetText

从状态栏控件的给定部分中检索文本。

CString GetText(
    int nPane,
    int* pType = NULL) const;

int GetText(
    LPCTSTR lpszText,
    int nPane,
    int* pType = NULL) const;

参数

lpszText
接收文本的缓冲区的地址。此参数是一个以 null 结尾的字符串。

nPane
要从中检索文本的部分的从零开始的索引。

pType
指向接收类型信息的整数的指针。类型可以是以下值之一：

0 文本的绘制边框应低于状态栏的平面。
SBT_NOBORDERS 文本绘制时没有边框。
SBT_POPOUT 文本的绘制带有边框，以显示在状态栏平面上方的位置。
SBT_OWNERDRAW 如果文本具有 SBT_OWNERDRAW 绘图类型，pType 将收到此消息，并返回与文本关联的 32 位值，而不是长度和操作类型。

返回值

包含当前文本的文本或 CString 的长度（以字符为单位）。

示例

int nType;
TCHAR *pszPaneOneText;

pszPaneOneText = new TCHAR[m_wndSBC.GetTextLength(1, &nType) + 1];
int nTextLength = m_wndSBC.GetText(pszPaneOneText, 1, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

delete pszPaneOneText;

CStatusBarCtrl::GetTextLength

从状态栏控件的给定部分中检索文本的长度（以字符为单位）。

int GetTextLength(
    int nPane,
    int* pType = NULL) const;

参数

nPane
要从中检索文本的部分的从零开始的索引。

pType
指向接收类型信息的整数的指针。类型可以是以下值之一：

0 文本的绘制边框应低于状态栏的平面。
SBT_NOBORDERS 文本绘制时没有边框。
SBT_OWNERDRAW 父窗口绘制文本。
SBT_POPOUT 文本的绘制带有边框，以显示在状态栏平面上方的位置。

返回值

以字符数表示的文本长度。

示例

int nType;
int nLength = m_wndSBC.GetTextLength(0, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

CStatusBarCtrl::GetTipText

检索状态栏中窗格的工具提示文本。

CString GetTipText(int nPane) const;

参数

nPane
用于接收工具提示文本的状态栏窗格的从零开始的索引。

返回值

一个 CString 对象，其中包含要在工具提示中使用的文本。

备注

此成员函数实现 Win32 消息 SB_GETTIPTEXT 的行为，如 Windows SDK 中所述。

示例

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl::IsSimple

检查状态窗口控件以确定它是否处于简单模式。

BOOL IsSimple() const;

返回值

如果状态窗口控件处于简单模式，则为非零值；否则为零。

注解

此成员函数实现 Win32 消息 SB_ISSIMPLE 的行为，如 Windows SDK 中所述。

CStatusBarCtrl::SetBkColor

设置状态栏中的背景色。

COLORREF SetBkColor(COLORREF cr);

参数

cr
一个指定新背景色的 COLORREF 值。指定 CLR_DEFAULT 值以使状态栏使用其默认背景色。

返回值

表示上一个默认背景色的 COLORREF 值。

备注

此成员函数实现 Win32 消息 SB_SETBKCOLOR 的行为，如 Windows SDK 中所述。

示例

m_wndSBC.SetBkColor(RGB(0, 0, 250));

HICON hIcon = AfxGetApp()->LoadIcon(IDI_PANE_0_ICON);
VERIFY(hIcon);
VERIFY(m_wndSBC.SetIcon(0, hIcon));

CStatusBarCtrl::SetIcon

设置状态栏中窗格的图标。

BOOL SetIcon(
    int nPane,
    HICON hIcon);

参数

nPane
将接收图标的窗格的从零开始的索引。如果此参数为 -1，则假定状态栏为简单状态栏。

hIcon
要设置的图标的句柄。如果此值为 NULL，则从部件中删除图标。

返回值

如果成功，则不为零，否则为零。

备注

此成员函数实现 Win32 消息 SB_SETICON 的行为，如 Windows SDK 中所述。

示例

请参阅 CStatusBarCtrl::SetBkColor 的示例。

CStatusBarCtrl::SetMinHeight

设置状态栏控件绘图区域的最小高度。

void SetMinHeight(int nMin);

参数

nMin
控件的最小高度（以像素为单位）。

备注

最小高度是 nMin 和状态栏控件垂直边框宽度的两倍（以像素为单位）。

示例

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl::SetParts

设置状态栏控件中的部件数以及每个部件右边缘的坐标。

BOOL SetParts(
    int nParts,
    int* pWidths);

参数

nParts
要设置的部件数。部件数不能大于 255。

pWidths
整数数组的地址，其元素数与 nParts 指定的部分数相同。数组中的每个元素都指定相应部件右边缘的位置（在客户端坐标中）。如果元素为 - 1，则该部件的右边缘的位置将扩展到控件的右边缘。

返回值

如果成功，则不为零，否则为零。

示例

const int c_nParts = 4;
CRect rect;

m_wndSBC.GetClientRect(&rect);
int aWidths[c_nParts] = {rect.right - 300, rect.right - 200, rect.right - 100,
                         -1};

VERIFY(m_wndSBC.SetParts(c_nParts, aWidths));

CStatusBarCtrl::SetSimple

指定状态栏控件是显示简单文本，还是显示由上一次调用 SetParts 设置的所有控件部件。

BOOL SetSimple(BOOL bSimple = TRUE);

参数

bSimple
[in] 显示类型标志。如果此参数为 TRUE，则该控件将显示简单文本；如果为 FALSE，则显示多个部件。

返回值

始终返回 0。

注解

如果应用程序将状态栏控件从非简单更改为简单，反之亦然，系统将立即重绘该控件。

CStatusBarCtrl::SetText

设置状态栏控件给定部分中的文本。

BOOL SetText(
    LPCTSTR lpszText,
    int nPane,
    int nType);

参数

lpszText
用于指定要设置的文本且以 Null 结尾的字符串的地址。如果 nType 是 SBT_OWNERDRAW，则 lpszText 表示 32 位数据。

nPane
要设置部件的从零开始的索引。如果此值为 255，则假定状态栏控件是仅具有一个部件的简单控件。

nType
绘制操作的类型。有关可能值的列表，请参阅 SB_SETTEXT 消息。

返回值

如果成功，则不为零，否则为零。

备注

该消息会使已更改的控件部分失效，从而导致该控件在下一个控件收到 WM_PAINT 消息时显示新文本。

示例

VERIFY(m_wndSBC.SetText(_T("Text For Pane 1"), 1, 0));

CStatusBarCtrl::SetTipText

设置状态栏中窗格的工具提示文本。

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

参数

nPane
用于接收工具提示文本的状态栏窗格的从零开始的索引。

pszTipText
指向包含工具提示文本的字符串的指针。

备注

此成员函数实现 Win32 消息 SB_SETTIPTEXT 的行为，如 Windows SDK 中所述。

示例

m_wndSBC.SetTipText(0, _T("This is Pane 0"));

另请参阅

CWnd 类
 层次结构图
 CToolBarCtrl 类

通过

CStatusBarCtrl 类

语法

成员

公共构造函数

公共方法

备注

继承层次结构

要求

CStatusBarCtrl::Create

参数

返回值

备注

示例

CStatusBarCtrl::CreateEx

参数

返回值

注解

CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl::DrawItem

参数

注解

CStatusBarCtrl::GetBorders

参数

返回值

备注

示例

CStatusBarCtrl::GetIcon

参数

返回值

注解

示例

CStatusBarCtrl::GetParts

参数

返回值

备注

示例

CStatusBarCtrl::GetRect

参数

返回值

示例

CStatusBarCtrl::GetText

参数

返回值

示例

CStatusBarCtrl::GetTextLength

参数

返回值

示例

CStatusBarCtrl::GetTipText

参数

返回值

备注

示例

CStatusBarCtrl::IsSimple

返回值

注解

CStatusBarCtrl::SetBkColor

参数

返回值

备注

示例

CStatusBarCtrl::SetIcon

参数

返回值

备注

示例

CStatusBarCtrl::SetMinHeight

参数

备注

示例

CStatusBarCtrl::SetParts

参数

返回值

示例

CStatusBarCtrl::SetSimple

参数

返回值

注解

CStatusBarCtrl::SetText