C S tatusBarCtrl

个 “ 状态条控件 ” 是一个水平的窗口，通常显示在一
个父窗口的底部，在其

中应用程序可以显示不同类型的状态信息。可以将此状态条控件分割为多个部分，用来显示多种类型的信息。

CStatusBarCtrl 类提供了 W indows 通用状态条控件的性能。这个控件（也就是CStatusBarCtrl 类）只对运行在 Windows 95 和 W indows NT3.51 或更新版本下的程序来说是可用的。

有关使用 CStatusBarCtrl 的更多信息，参见 “ V isual C++ 程序员指南 ” 中的 “控件主题 ” 和 “ 使用 CStatusBarCtrl ” 。

#include <afxcmn.h>

请参阅 CtoolBarCtrl

C StatusBarCtrl 类成员

Construction

CstatusBarCtrl 构造一个 CStatusBarCtrl 对象

Create 创建一个状态条控件并将它与一个 CstatusBarCtrl

对象连接

Attributes

SetText 设置一个状态条控件的给定部分中的文本

GetText 从一个状态条控件的给定部分中获取文本

GetTextLength 从一个状态条控件的给定部分获取文本的用字符

数目表示的长度

SetParts 设置一个状态条控件中的部分数目，以及每一个部分的右边缘的坐标

GetParts 获取一个状态条控件中的部分数目

GetBorders 获取一个状态条控件的水平或垂直边界的对齐宽

度

SetMinHeight 设置一个状态条控件的绘制区域的最小高度

SetSimple 指定一个状态条控件是显示简单的文本，还是显

示由前一次调用 SetParts 设置的所有控件部分

续表

GetRect 获取一个状态条控件中的一个部分的边界矩形

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

GetTipText 获取状态条中的一个窗格的工具提示文本

SetTipText 设置状态条中的一个窗格的工具提示文本

SetBkColor 设置一个状态条控件中的背景颜色

SetIcon 设置状态条控件中的窗格的图标

Overridable s D rawItem 当一个属主绘制的状态条控件的外观改变时调用

此函数

成员函数

CStatusBarCtrl::Create

BOOL Create( DWORD dwStyle , const RECT& rect , CWnd* pParentWnd , UINT

nID );

返回值

如果成功则返回非零值；否则返回零。

参数

dwStyle

指定状态条控件的风格。状态条控件风格的任意组合都适用于这个控件。这个参数必须包括 WS_CHILD 风格。它也必须包括 WS_VISIBLE 风格。参见说明部分可以获得更多信息。

rect

指定状态条控件的大小和位置。它可以是一个 CRect 对象或一个 RECT 结

构。

pParentWnd

指定状态条控件的父窗口，通常是一个 CDialog。它不能是 NULL 。

nID

指定状态条控件的 ID 。

说明

构造一个 CStatusBarCtrl 对象可以分两步。首先调用构造函数，然后调用 Create

来创建状态条控件并将它与 CStatusBarCtrl 对象连接。

dwStyle 参数可以是下列值的任意组合：

CCS_BOTTOM 使控件将它自己定位在父窗口的客户区的底

端，并将宽度设置为与父窗口的宽度一样。状态条控件将此作为它的缺省风格。
CCS_NODIVIDER 禁止在控件的顶部绘制两个像素的高亮区

。
CCS_NOHILITE 禁止在控件的顶部绘制一个像素的高亮区

。
CCS_NOMOVEY 使控件响应 WM_SIZE 消息，调整自己的大小

并水平移

动自己，但不是垂直移动。如果使用了 CCS_NORESIZE 风格，则此风格不能使用。

CCS_NOPARENTALIGE 禁止控件自动移动到父窗口的顶部或

底部。不管控件的父窗口的尺寸怎么改变，控件都保持它在父窗口中的位置。如果也使用了 CCS_TOP 和 CCS_BOTTOM 风格，则高度被调整为缺省值，但位置和宽度仍然保持不变。
CCS_NORESIZE 当控件设置它自己的初始尺寸和新尺寸时

，禁止控件使用缺省的宽度和高度。而是用在创建或调整大小的请求中指定的宽度和高度。
CCS_TOP 使控件将自己定位在其父窗口的顶部，并将自

己的宽度设置为与父窗口的宽度一样。

个状态窗口的缺省位置是沿着父窗口的底部，但是你
也可以指定 CCS_TOP

风格来使它显示在父窗口的客户区的顶部。还可以指定 SBARS_SIZEGRIP 风格来使它包括一个位于状态窗口右端的调整大小的把手。并不建议组合CCS_TOP 和 SBARS_SIZEGRIP 风格，因为这样获得的调整大小把手是没有用的，尽管系统将它绘制在了状态窗口中。

请参阅 CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl( );

说明

此成员函数用来构造一个 CStatusBarCtrl 控件。

请参阅 CStatusBarCtrl::Create

CStatusBarCtrl::DrawItem

virtual void DrawItem( LPDRA W ITEMSTRUCT lpDrawItemStruct );

参数

lpDrawItemStruct

一个指向 DRAWITEMSTRUCT 结构的长指针。该结构包含了有关所要求的绘制的类型的信息。

说明

当一个属主绘制的状态条控件的外观发生改变时框架调用此成员函数。

D R A W ITEMS- TRUCT 结构的 itemAction 成员定义了要执行的绘制动作。

缺省的，这个成员函数不做任何事情。重载这个成员函数来实现对一个属主绘制的 CStatusBarCtrl 对象的绘制。

在此成员函数终止之前，应用程序应该恢复在 lpDrawItemStruct 中提供的显示环境所选择的所有图形设备接口（ GD I）。

请参阅 CWnd::OnDrawItem

CStatusBarCtrl::GetBorders

BOOL GetBorders( int* pBorders ) const;

BOOL GetBorders( int& nHorz , int& nVer t, int& nSpacing ) const;

返回值

如果成功则返回非零值；否则返回零。

参数

pBorders

一个有三个元素的整数数组的地址。第一个元素用来接收水平边界的宽

度，第二个元素用来接收垂直边界的宽度，第三个元素用来接收矩形之间的边界的宽度。

nHorz

是对一个用来接收水平边界宽度的整数的引用。

nVert

是对一个用来接收垂直边界宽度的整数的引用。

nSpacing

是对一个用来接收矩形之间的边界宽度的整数的引用。

说明

此成员函数用来获取状态条控件的水平和垂直边界，以及矩形之间的空间的当前宽度。这些边界决定了控件的外部边缘和控件内部包含文本的矩形之间的间隔。

请参阅 CStatusBarCtrl::GetParts, CStatusBarCtrl::SetParts

CStatusBarCtrl::GetParts

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

返回值

如果成功则返回控件中的部分数；否则返回零。

参数

nParts

要获取其坐标的部分数。如果这个参数大于控件中的部分数，则只返回现有部分的坐标。

pParts

一个整数数组的地址，该数组的元素个数与 nParts 指定的部分数一样。

数组中的每一个元素都用来接收相应部分的右边缘的客户区坐标。如果一个元素被设置为 -1 ，则表示该部分的右边缘扩展到了状态条的右边缘。

说明

此成员函数用来获取一个状态条控件中的部分数。这个成员函数也用来获取给定数目的部分的右边缘的坐标。

请参阅 CStatusBarCtrl::GetBorders, CStatusBarCtrl::SetParts

CStatusBarCtrl::GetRect

BOOL GetRect( int nPane , LPRECT lpRect ) const;

返回值

如果成功则返回非零值；否则返回零。

nPane

要获取其边界矩形的部分的从零开始的索引。

lpRect

一个 RECT 结构的地址，该结构接收边界矩形。

说明

此成员函数用来获取状态条控件中的一个部分的边界矩形。

请参阅 CStatusBarCtrl::GetParts

CStatusBarCtrl::GetText

int GetText( LPCTSTR lpszTex t, int nPane , int* pType ) const;

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

参数

lpszText

用来接收文本的缓冲的地址。这个参数是一个用空字符结尾的字符串。

nPane

要获取其文本的部分的从零开始的索引。

pType

指向一个用来接收信息类型的整数的指针。这个类型可以是下列值中的一个：

0 绘制的文本的一个边界看起来低于状态条平面。
SBT_NOBORDERS 绘制的文本没有边界。
SBT_POPOUT 绘制的文本的边界显示比状态条的平面高。
SBT_OWNERDRAW 如果文本具有 SBT_OWNERDRAW 绘制风格，则

pType 接收这个消息并返回与文本关联的 32 位值，而不是长度和操作类型。

说明

此成员函数用来从一个状态条控件的给定部分获取文本。

请参阅 CStatusBarCtrl::SetText, CStatusBarCtrl::GetTextLength

CStatusBarCtrl::GetTextLength

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

返回值

返回文本的用字符数表示的长度。

参数

nPane

要获取其文本的部分的从零开始的索引。

pType

指向一个用来接收信息类型的整数的指针。这个类型是下列值中的一个：

0 绘制的文本的一个边界看起来低于状态条平面。
SBT_NOBORDERS 绘制的文本没有边界。
SBT_OWNERDRAW 文本是父窗口绘制的。
SBT_POPOUT 绘制的文本的边界显示比状态条的平面高。

说明

此成员函数用来从一个状态条控件中的给定部分获取文本的用字符数表示的长

度。

请参阅 CStatusBarCtrl::GetText, CStatusBarCtrl::SetText

CStatusBarCtrl::GetTipText

CString GetTipText( int nPane ) const;

返回值

返回一个 CString 对象，该对象包含了要被使用在工具提示中的文本。

参数

nPane

要获取工具提示文本的状态条窗格的从零开始的索引。

说明

此成员函数用来实现 W in32 消息 SB_GETTIPTEXT 的行为，就像在 “ Platform SDK ” 中描述的一样。

请参阅 CStatusBarCtrl::SetTipText

CStatusBarCtrl::IsSimple BOOL IsSimple( ) const; 返回值

如果状态窗口控件是在简单模式下则返回非零值；否则返回零。

说明

此成员函数用来实现 Win32 消息 SB_ISSIMPLE 行为，就像在 “ Platform SDK ”

中描述的一样。

请参阅 CStatusBarCtrl::SetSimple

CStatusBarCtrl::SetBkColor

COLORREF SetBkColor( COLORREF cr );

返回值

返回一个代表先前的缺省背景颜色的 COLORREF 值。

参数

是指定新的背景颜色的 COLORREF 值。如果指定的是 CLR_DEFAULT

值，则会导致状态条使用它的缺省背景颜色。

说明

此成员函数用来实现 Win32 消息 SB_SETBKCOLOR 的行为，就像在“ Platform SDK ” 中描述的一样。

CStatusBarCtrl::SetIcon

BOOL SetIcon( int nPane , HICON hIcon );

返回值

如果成功则返回非零值；否则返回零。

参数

nPane

将用来接收图标的窗格的从零开始的索引。如果此参数是 -1 ，则状态条

hIcon

是要被设置的图标的句柄。如果这个值是 NULL ，则图标被从此部分中移

走。

说明

此成员函数用来实现 Win32 消息 SB_SETICON 的行为，就像在“ Platform SDK ” 中描述的一样。

CStatusBarCtrl::SetMinHeight void SetMinHeight( int nMin ); 参数

nMin

说明

此成员函数用来设置一个状态条控件的绘画区的最小高度。这个最小高度是

nMin 和两倍的状态条控件的以像素表示的垂直边界的宽度的和。

请参阅 CStatusBarCtrl::GetRect, CStatusBarCtrl::GetBorders

CStatusBarCtrl::SetParts

BOOL SetParts( int nParts , int* pWidths );

返回值

如果成功则返回非零值；否则返回零。

参数

nParts

要设置的部分的数目。部分数不能大于 255 。

pWidths

一个整数数组的地址，该数组的元素个数与 nParts 指定的数目一样。数组中的每一个元素以客户区坐标指定了相应部分的右边缘位置。如果某一个元素是 -1 ，则相应部分的右边缘位置扩展到了该控件的右边缘。

说明

此成员函数用来设置一个状态条控件中的部分数，以及每一部分的右边缘的坐标。

请参阅 CStatusBarCtrl::GetBorders, CStatusBarCtrl::GetParts

CStatusBarCtrl::SetSimple

BOOL SetSimple( BOOL bSimple = TRUE );

返回值

如果发生了错误则返回零。

参数

bSimple

显示类型标志。如果这个参数是 TRUE ，则控件显示简单的文本；如果是 FALSE ，则它显示多个部分。

说明

此成员函数用来指定一个状态条控件是显示简单文本，还是显示前面调用

SetParts 设置的所有控件部分。

如果状态条控件是从非简单模式改变到简单模式，或者是从简单到非简单，控件都会被重画。

请参阅 CStatusBarCtrl::SetParts

CStatusBarCtrl::SetText

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

返回值

如果成功则返回非零值；否则返回零。

参数

lpszText

一个以空字符结尾的字符串的地址，该字符串指定了要设置的文本。如果 nType 是 SBT_OWNERDRAW ，则 lpszText 表示 32 位的数据。

nPane nType

绘制操作的类型。这个类型可以是下列值中的一个：

0 绘制的文本的一个边界看起来低于状态条平面。
SBT_NOBORDERS 绘制的文本没有边界。
SBT_OWNERDRAW 文本是父窗口绘制的。
SBT_POPOUT 绘制的文本的边界显示比状态条的平面高。

说明

此成员函数用来在一个状态条控件的给定部分中设置文本。当控件下一次接收到 WM_PAINT 消息时，这是表示控件的该部分被改变的消息，导致该部分显

请参阅 CStatusBarCtrl::GetText, CStatusBarCtrl::GetTextLength

CStatusBarCtrl::SetTipText

void SetTipText( int nPane , LPCTSTR pszTipText );

参数

nPane

要接收工具提示文本的状态条窗格的从零开始的索引。

pszTipText

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

说明

此成员函数用来实现 W in32 消息 SB_SETTIPTEXT 的行为，就像在 “ Platform

请参阅 CStatusBarCtrl::GetTipText

C S tatusBarCtrl

C S tatusBarCtrl

C StatusBarCtrl 类 成 员

成 员 函 数

C StatusBarCtrl 类成员

成员函数