CStatusBarCtrl 类

提供 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 参数

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

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 类