CReBarCtrl

CReBarCtrl 类封装了 rebar 控件的机能， rebar 控件是一个子窗口容器。 rebar 控

件所属的应用程序将 rebar 控件包含的子窗口分配给 rebar 带。子窗口是另外一种通用的控件。

rebar 控件包含一个或多个带。每一个带可以包含一个控制条，一个位图，一个文本标签和一个子窗口的组合。但一个带只能包含每一种项的一个。

rebar 控件可以在指定的位图之上显示子窗口。所有的 rebar 控件带都可以调整大小，除了那些使用 RBBS_FIXEDSIZE 风格的以外。当你调整一个 rebar 控件带的位置和大小的时候， rebar 控件控制对应于该带的子窗口的位置和大小。单击和拖动一个带的控制条，就可以调整控件中的带的大小或改变它们的顺序。

下面的例子说明了一个具有三个带的 rebar 控件：

带 0 包含了一个平坦的、透明（ transparent）的工具条

控件。
带 1 包含了透明的标准按钮和下拉按钮。
带 2 包含了一个组合框和四个标准按钮。

CReBarCtrl - 图1

Rebar 控件

Rebar 控件支持：

图像列表。
消息处理。
定制绘画功能。
除标准的窗口风格之外，附加的各种控件风格。要获

取这些风格的列表，参见 “ Platform SDK ” 中的 “ Rebar 控件风格 ” 。

#include <afxcmn.h>

CReBarCtrl 类成员

Constructors

CreBarCtrl 构造一个 CReBarCtrl 对象

Initialization

Create 创建 rebar 控件，并将它与 CReBarCtrl 对象连接

Attributes

GetBandCount 获取在 rebar 控件中的当前带数

GetBandInfo 获取 rebar 控件中的指定带的信息

GetBarHeight 获取 rebar 控件的高度

GetBarInfo 获取有关 rebar 控件的信息以及它使用的图像列表

GetBkColor 获取 rebar 控件的缺省背景颜色GetDropTarget 获取一个 rebar 控件的 ID ropTarget 接口指针GetRect 获取一个 rebar 控件中的给定带的边界矩形

GetRowCount 获取一个 rebar 控件中的带行的数目

GetRowHeight 获取一个 rebar 控件中的指定行的高度

续表

GetTextColor 获取一个 rebar 控件的缺省文本颜色

GetToolTips 获取与 rebar 控件相关的任何工具提示控件的句柄

IDToIndex 将一个带的标识符（ ID ）转换成一个 rebar 控件中的带索引

SetBandInfo 设置一个 rebar 控件中的已存在的带的特征

SetBarInfo 设置一个 rebar 控件的特征

SetBkColor 设置一个 rebar 控件的缺省背景颜色

SetOwner 设置一个 rebar 控件的属主窗口

SetTextColor 设置一个 rebar 控件的缺省文本颜色

SetToolTips 使一个工具提示控件与 rebar 控件相关联

GetImageList 获取与 rebar 控件相关的图像列表

SetImageList 设置一个 rebar 控件的图像列表

GetBandBorders 获取一个带的边界

GetPalette 获取 rebar 控件的当前调色板

SetPalette 设置 rebar 控件的当前调色板

Operations

BeginDrag 设置 rebar 控件进入拖－放模式

DeleteBand 从一个 rebar 控件中删除一个带

DragMove 在调用 BeginDrag 后，更新在 rebar 控件中的拖动位置

EndDrag 终止 rebar 控件的拖放操作

HitTest 如果一个 rebar 带在屏幕上的给定点存在的话，则确定 rebar 带的哪一部分是在这个点上

InsertBand 向一个 rebar 控件中插入一个新带

M aximizeBand 将 rebar 控件中的一个带调整到它的理想或最大尺

寸

M inim izeBand 将 rebar 控件中的一个带调整到它的理想或最小尺

寸

ShowBand 显示或隐藏一个 rebar 控件中的给定带

SizeToRect 使一个 rebar 控件符合一个指定的矩形

MoveBand 将一个带从一个索引移动到另一个索引

成员函数

CReBarCtrl::BeginDrag

void BeginDrag( UINT uBand , DWORD dwPos = (DWORD)-1);

参数

uBand

从零开始的带索引值，这些带将被拖放操作影响。

dwPos

一个 D W O R D 值，包含了开始的鼠标坐标。水平坐标包含在 LOWORD 中，垂直坐标包含在 HIWORD 中。如果你传递的是（ DWORD ） -1 ，则rebar 控件将通过调用 ::GetMessage 或 ::PeekMessage 来使用鼠标最后一次的位置。

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

请参阅 ::GetMessage， ::Peek M essage

CReBarCtrl::Create

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

nID );

返回值

如果成功地创建了对象，则返回非零值；否则返回 0 。

dwStyle

指定应用于控件的 rebar 控件风格的组合。参见“ Platfor SD K”中的“ rebar

控件风格 ” ，可以获得所支持的风格的列表。

rect

个指向 CRect 对象或 RECT 结构的引用，它们是 rebar 控件
的位置和尺

寸。

pParentWnd

个指向 CWnd 对象的指针。它不能是 NULL 。

nID

指定 rebar 控件的控制 ID 。

分两步来创建一个 rebar 控件：

调用 CReBarCtrl 来构造一个 CReBarCtrl 对象。
调用 Create 成员函数来创建 W indows rebar 控件，并将它与

CReBarCtrl 对象连接。

当你调用 Create 时，通用的控件被初始化。

CReBarCtrl::CReBarCtrl

CReBarCtrl();

说明

此成员函数用来创建一个 CReBarCtrl 对象。

请参阅 CReBarCtrl::Create

CReBarCtrl::DeleteBand

BOOL DeleteBand( UINT uBand );

返回值

如果成功地删除了带，则返回非零值；否则返回 0 。

参数

uBand

要被删除的带的从零开始的索引值。

说明

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

CReBarCtrl::DragMove

void DragMove( DWORD dwPos = ( DWORD)-1 );

参数

dwPos

一个 DWORD 值，该值包含了新的鼠标位置。水平坐标包含在 LOWORD 中，垂直坐标包含在 HIWORD 中。如果你传递的是（ DWORD ）－ 1 ，则 rebar 控件将通过调用 ::Get M essage 或 ::Peek M essage 来使用鼠标最后一次的位置。

说明

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

请参阅 CReBarCtrl::BeginDrag ，

CReBarCtrl::EndDrag， ::GetMessage ， ::PeekMessage

CReBarCtrl::EndD ra g

void EndDrag();

说明

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

请参阅 CReBarCtrl::BeginDrag ， CReBarCtrl::DragMove

CReBarCtrl::GetBandBorders

void GetBandBorders( UINT uBand , LPRECT prc ) const;

参数

uBand

将要被获取边界的带的从 0 开始的索引。

prc

一个指向 RECT 结构的指针，该结构将用来接收带的边界。如果该 rebar 控件具有 RBS_BANDBORDERS 风格，则此结构的每一个成员都将接收相似的数目，从相应的带的一面来说，这构成了边界。如果该 rebar 控件不具有 RBS_BANDBORDERS 风格，则此结构只有左边的成员接收有效的信息。要获取有关 rebar 控件风格的描述，请参见 “ Platform SDK”中的 “ rebar 控件风格 ” 。

说明

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

CReBarCtrl::GetBandCount UINT GetBandCount() const; 返回值

被分配给控件的带的数目。

说明

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

请参阅 CReBarCtrl::GetBandInfo ， CReBarCtrl::SetBandInfo ，

CReBarCtrl::DeleteBand ，

CReBarCtrl::InsertBand ， CReBarCtrl::ShowBand

CReBarCtrl::GetBandInfo

BOOL GetBandInfo( UINT uBand , REBARBANDINFO* prbbi ) const;

返回值

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

参数

uBand

带的从零开始的索引，将从这些带获取信息。

prbbi

一个指向 REBARBANDINFO 结构的指针，该结构用来接收带的信息。你必须在发送此消息之前将此结构的成员 cbSize 设置为sizeof(REBARBANDINFO )，并将 f M ask 成员设置为你要获取的项。

说明

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

请参阅 CReBarCtrl::SetBandInfo ， CReBarCtrl::GetBandCount ，

CReBarCtrl:: DeleteBand ，

CReBarCtrl:: InsertBand ， CReBarCtrl:: ShowBand

CReBarCtrl:: GetBarHeight

UINT GetBarHeight() const;

以像素表示的代表控件高度的值。

说明

此成员函数用来获取 rebar 控件的高度。

请参阅 CReBarCtrl::GetBarInfo ， CReBarCtrl::SetBarInfo

CReBarCtrl::GetBarInfo

BOOL GetBarInfo( REBARINFO* prbi ) const;

返回值

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

prbi

一个指向 REBARINFO 结构的指针，该结构将用来获取此 rebar 控件的信息。你必须在发送这个消息之前设置此结构的 cbSize 成员为sizeof(REBARINFO )。

说明

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

请参阅 CReBarCtrl:SetBarInfo

CReBarCtrl::GetBkColor

COLORREF GetBkColor() const;

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

说明

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

请参阅 CReBarCtrl::SetBkColor

CReBarCtrl::GetDropTarget

IDropTarget* GetDropTarget() const;

返回值

返回一个指向 IDropTarget 接口的指针。

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

CReBarCtrl::GetImageList CImageList* GetImageList(); 返回值

返回一个指向 CImageList 对象的指针。如果没有控件的图像列表则返回 NULL 。

说明

此成员函数用来获取与一个 rebar 控件相关的 CImageList 对象。此成员函数使用 REBARINFO 结构中的 size 和 mask 信息，就像在 “ Platform SDK ” 中描述

的一样。

请参阅 CReBarCtrl::SetImageList

CReBarCtrl::GetPalette CPalette* GetPalette() const; 返回值

返回一个指向 CPalette 对象的指针，该对象指定 rebar 控件的当前调色板。

说明

此成员函数用来获取 rebar 控件的当前调色板。

值得注意的是，此成员函数使用一个 CPalette 对象作为它的返回值，而不是一个 HPALETTE 。

请参阅 CReBarCtrl::SetPalette

CReBarCtrl::GetRect

BOOL GetRect( UINT uBand , LPRECT prc ) const;

返回值

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

参数

uBand

在 rebar 控件中的带的从 0 开始的索引。

prc

一个指向 RECT 结构的指针，该结构将用来接收 rebar 带的边界。

说明

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

请参阅 CReBarCtrl::SizeToRect

CReBarCtrl::GetRowCount UINT GetRowCount() const; 返回值

返回一个 UINT 值，它代表控件中的带行的数目。

说明

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

SDK ” 中所描述的一样。

请参阅 CReBarCtrl::GetRowHeight

CReBarCtrl::GetRowHeight

UINT GetRowHeight( UINT uRow ) const;

返回值

一个 UINT 值，该值代表行的以像素为单位的高度。

参数

uRow

带的从 0 开始的索引，此索引所代表的带的高度将被获取。

说明

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

请参阅 CReBarCtrl::GetRowCount

CReBarCtrl::GetTextColor COLORREF GetTextColor() const; 返回值

返回一个 COLORREF 值，该值代表当前缺省的文本颜色。

说明

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

请参阅 CReBarCtrl::SetTextColor ， CReBarCtrl::GetBkColor ，

CReBarCtrl::SetBkColor CReBarCtrl::GetToolTips CToolTipCtrl* GetToolTips() const; 返回值

返回一个指向 CToolTipCtrl 对象的指针。

说明

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

而不是一个 H W N D 。

请参阅 CReBarCtrl::SetToolTips

CReBarCtrl::HitTest

int HitTe st( RBHITTE S TINFO* prbht ) ;

返回值

返回在给定点的带的从 0 开始的索引，如果在该指定点上没有 rebar 带，则返回 -1 。

参数

prbht

的 pt 成员布线在客户区坐标被初始化为指向要被测试的项。

说明

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

CReBarCtrl::IDToIndex

int IDToIndex( UINT uBandID ) const;

返回值

如果成功则返回从 0 开始的带索引；否则返回 -1 。如果有复制的带索引存在，则返回第一个。

uBandID

应用程序定义的指定带的标识符，当带被插入时，由 REBARBANDINFO

中的 wID 成员传递。

说明

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

请参阅 CReBarCtrl::InserBand

CReBarCtrl::Insert Band

BOOL Inser tBand( UINT uIndex , REBARBANDINFO* prbbi ) ;

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

参数

uIndex

从零开始的位置索引，带将在这个位置插入。如果你设置这个参数为 -1 ，则控件会将新带插入在最后。

prbbi

一个指向 REBARBANDINFO 结构的指针，此结构定义了要被插入的带。在调用此成员函数之前，你必须将此结构的 cbSize 成员设置为sizeof( REBARBANDINFO ) 。

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

CReBarCtrl::MaximizeBand

void MaximizeBand( UINT uBand );

参数

uBand

返回要被最大化的带的从零开始的索引值。

说明

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

请参阅 CReBarCtrl::MinimizeBand

CReBarCtrl::MinimizeBand

void MinimizeBand( UINT uBand );

参数

uBand

返回要被最大化的带的从 0 开始的索引值。

说明

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

CReBarCtrl::MoveBand

BOOL MoveBand( UINT uFrom , UINT uTo );

返回值

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

参数

uFrom

要被移动的带的从 0 开始的索引。

uTo

新的带位置的从 0 开始的索引。此参数的值必须不大于总带数减 1 的值。要得到总带数，可以调用 GetBandCoun t。

说明

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

CReBarCtrl::SetBandInfo

BOOL SetBandInfo( UINT uBand , REBARBANDINFO* prbbi );

返回值

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

参数

uBand

要接收新设置的带的从 0 开始的索引。

prbbi

指向一个 REBARBANDINFO 结构的指针，此结构定义了要被插入的带。在发送此消息之前，你必须将此结构的 cbSize 成员设置为sizeof( REBARBANDINFO ) 。

说明

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

请参阅 CReBarCtrl::GetBandInfo

CReBarCtrl::SetBarInfo

BOOL SetBarInfo( REBANRINFO* prb i);

返回值

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

参数

prbi

个指向 REBARINFO 结构的指针，该结构包含了要设置的
信息。在发送此消息之前，你必须将此结构的 cbSize 成员设置为sizeof( REBARINFO ) 。

说明

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

请参阅 CReBarCtrl::GetBarInfo

CReBarCtrl::SetBkColor

COLORREF SetBkColor( COLORREF clr );

返回值

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

参数

clr

一个 COLORREF 值，它代表新的缺省背景颜色。

说明

此成员函数用来实现 Win32 消息 RB_SETB K COLOR 的行为，就像在“ Platform

关于何时设置背景颜色和如何设置缺省值的信息。

请参阅 CReBarCtrl::GetBkColor

CReBarCtrl::SetImageList

BOOL SetImageList(CImageList* pImageList );

返回值

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

参数

pImageList

一个指向 CImageList 对象的指针，该对象包含了要分配给 rebar 控件的图

说明

此成员函数用来给 rebar 控件分配图像列表。

请参阅 CReBarCtrl::GetImageList

CReBarCtrl::SetOwner

CWnd* SetOwner( CWnd* pWnd );

返回值

返回一个指向 CWnd 对象的指针，该对象是此 rebar 控件的当前属主。

参数

pWnd

一个指向 CWnd 对象的指针，该对象要被设置为此 rebar 控件的属主。

说明

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

值得注意的是，不管是对 rebar 控件的当前属主还是被选中的属主，都使用指向 CWnd 对象的指针，而不是窗口句柄。

注意此成员函数并不改变在创建对象时所设置的父；它只是向你指定的窗口发送通知消息。

CReBarCtrl::SetPalette

CPalette* SetPalette( HPALETTE hPal );

返回值

返回一个指向 CPalette 对象的指针，该对象指定了 rebar 控件先前调色板。

参数

hPal

一个 HPALETTE ，它指定了 rebar 控件将要使用的新的调色板。

说明

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

值得注意的是，此成员函数用一个 CPalette 对象作为它的返回值，而不是一个

HPALETTE 。

请参阅 CReBarCtrl::GetPalette

CReBarCtrl::SetTextColor

COLORREF SetTextColor( COLORREF clr );

返回值

返回 COLORREF 值，该值代表了与 CReBarCtrl 对象相关的先前文本颜色。

参数

clr

是一个 COLORREF 值，它代表 CReBarCtrl 对象中的新的文本颜色。

此成员函数用来实现 W in32 消息 RB_SETTEXTCOLOR 的行为，就像在“ Platform SDK ” 中所描述的一样。此函数用来支持一个 rebar 控件中的文本颜色的灵活性。

请参阅 CReBarCtrl::GetTextColor

CReBarCtrl::SetToolTips

void SetToolTips( CToolTipCtrl* pToolTip );

参数

pToolTip

一个指向 CToolTipCtrl 对象的指针。

此成员函数用来使一个工具提示控件和一个 rebar 控件相联系。当你使用完后，你必须销毁此 CRoolTipCtrl 对象。

请参阅 CReBarCtrl::GetToolTips

CReBarCtrl::ShowBand

BOOL ShowBand( UINT uBand , BOOL fShow = TRUE ) ;

返回值

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

参数

uBand

此 rebar 控件中的一个带的从零开始的索引值。

fShow

表明是显示还是隐藏这个带。如果这个值是 TRUE ，则显示此带。否则，隐藏这个带。

说明

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

请参阅 CReBarCtrl::SetBandInfo ， CReBarCtrl::GetBandCoun t，

CReBarCtrl::DeleteBand ， CReBarCtrl::InsertBand ，

CReBarCtrl::GetBandInfo

CReBarCtrl::SizeToRect

BOOL SizeToRect( CRect& rect );

返回值

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

参数

rect

一个指向 CRect 对象的引用，该对象指定了一个 rebar 对象必须适合的矩

形。

说明

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

值得注意的是，此成员函数使用一个 CRect 对象作为参数，而不是一个 RECT

结构。

请参阅 CReBarCtrl::GetRect

CReBarCtrl

CReBarCtrl

CReBarCtrl 类 成 员

成 员 函 数

CReBarCtrl 类成员

成员函数