CMFCRibbonPanel 类
实现包含一组功能区元素的面板。 在绘制面板时，系统将根据面板的大小显示尽可能多的元素。
有关详细信息，请参阅所安装的 Visual Studio 的 C\atlmfc\src\mfc 文件夹中的源代码。
语法
class CMFCRibbonPanel : public CObject
成员
受保护构造函数
| 名称 | 描述 |
|---|---|
| CMFCRibbonPanel::CMFCRibbonPanel | 构造并初始化一个 CMFCRibbonPanel 对象。 |
公共方法
备注
功能区面板是你在功能区类别中创建的相关任务的逻辑分组。 随着功能区大小发生变化，面板布局会自动调整以显示尽可能多的元素。
可以通过调用 CMFCRibbonCategory::GetPanel 方法来获取包含在功能区类别中的功能区面板。
示例
以下示例演示如何使用 CMFCRibbonPanel 类中的各种方法配置 CMFCRibbonPanel 对象。 该示例演示如何设置显示功能区面板的键盘快捷方式、按列垂直对齐面板中的元素以及启用列对齐。 此代码片段是 MS Office 2007 演示示例的一部分。
// CMFCRibbonCategory* pCategory
// CMFCToolBarImages m_PanelImages
CMFCRibbonPanel *pPanelClipboard = pCategory->AddPanel(_T("Clipboard"), m_PanelImages.ExtractIcon(1));
pPanelClipboard->SetKeys(_T("zc"));
pPanelClipboard->SetCenterColumnVert();
pPanelClipboard->SetJustifyColumns();
继承层次结构
要求
标头：afxRibbonPanel.h
CMFCRibbonPanel::Add
将指定的功能区元素追加到功能区面板中包含的功能区元素数组。
virtual void Add(CMFCRibbonBaseElement* pElem);
参数
pElem
[in, out] 指向功能区元素的指针。
注解
CMFCRibbonPanel::AddSeparator
将分隔符添加到功能区面板。
virtual void AddSeparator();
注解
调用此方法，将分隔符添加到功能区面板。 此分隔符将添加到先前调用 CMFCRibbonPanel::Add 所添加的功能区元素旁边。 若要在给定位置插入分隔符，请调用 CMFCribbonPanel::InsertSeparator。
CMFCRibbonPanel::AddToolBar
将工具栏添加到功能区面板。
CMFCRibbonButtonsGroup* AddToolBar(
UINT uiToolbarResID,
UINT uiColdResID = 0,
UINT uiHotResID = 0,
UINT uiDisabledResID = 0);
参数
uiToolbarResID
[in] 指定要添加的工具栏的资源 ID。
uiColdResID
[in] 指定工具栏冷图像的资源 ID。
uiHotResID
[in] 指定工具栏热图像的资源 ID。
uiDisabledResID
[in] 指定工具栏已禁用图像的资源 ID。
返回值
调用此方法将工具栏添加到功能区面板。 此工具栏将添加到先前调用 CMFCRibbonPanel::Add 所添加的功能区元素旁边。
注解
有关工具栏、热图像、冷图像和已禁用图像的详细信息，请参阅 CMFCToolBar 类。
CMFCRibbonPanel::CMFCRibbonPanel
构造并初始化 CMFCRibbonPanel 对象。
CMFCRibbonPanel(
LPCTSTR lpszName = NULL,
HICON hIcon = NULL);
CMFCRibbonPanel(CMFCRibbonGallery* pPaletteButton);
参数
lpszName
[in] 功能区面板的名称。
hIcon
[in] 功能区面板的默认按钮图标的句柄。
pPaletteButton
[in] 指向功能区面板的功能区库的指针。
CMFCRibbonPanel::FindByData
检索与指定数据关联的功能区元素。
CMFCRibbonBaseElement* FindByData(DWORD_PTR dwData) const;
参数
dwData
[in] 与功能区元素关联的数据。
返回值
如果此方法成功，则为指向功能区元素的指针；否则为 NULL。
注解
CMFCRibbonPanel::FindByID
检索由指定命令 ID 标识的功能区元素。
CMFCRibbonBaseElement* FindByID(UINT uiCmdID) const;
参数
uiCmdID
[in] 功能区元素的命令 ID。
返回值
由指定命令 ID 标识的功能区元素；否则，如果未使用指定命令 ID 标识功能区元素，则为 NULL。
CMFCRibbonPanel::GetCaptionHeight
检索功能区面板标题的高度。
int GetCaptionHeight() const;
返回值
功能区面板标题的高度（以像素为单位）。
备注
CMFCRibbonPanel::GetCount
检索功能区面板中包含的功能区元素数。
int GetCount() const;
返回值
功能区面板中包含的功能区元素数。
CMFCRibbonPanel::GetData
返回与面板关联的用户定义数据。
DWORD_PTR GetData() const;
返回值
与面板关联的用户定义数据。
CMFCRibbonPanel::GetDefaultButton
检索功能区面板的默认按钮。
CMFCRibbonButton& GetDefaultButton();
返回值
功能区面板的默认按钮。
备注
当功能区面板没有足够空间来显示其功能区元素时，将显示默认按钮。
CMFCRibbonPanel::GetDroppedDown
检索在功能区元素的弹出菜单已下拉的情况下，指向该功能区元素的指针。
CMFCRibbonBaseElement* GetDroppedDown() const;
返回值
指向其弹出菜单已下拉的功能区元素的指针；否则，如果没有功能区元素的弹出菜单被下拉，则为 NULL。
备注
仅测试功能区面板中包含的功能区元素。
CMFCRibbonPanel::GetElement
返回位于指定索引处的功能区元素。
CMFCRibbonBaseElement* GetElement(int nIndex) const;
参数
nIndex
[in] 指定要检索的元素的从零开始的索引。
返回值
指向位于功能区面板中 nIndex 位置的基本功能区元素的有效指针，如果在指定索引处没有元素，则为 NULL。
CMFCRibbonPanel::GetElements
检索功能区面板中包含的所有功能区元素。
void GetElements(CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);
参数
arElements
[out] 一个数组，用于填充功能区面板中包含的所有功能区元素。
注解
CMFCRibbonPanel::GetElementsByID
将具有指定命令 ID 的功能区元素添加到指定的数组。
void GetElementsByID(
UINT uiCmdID,
CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);
参数
uiCmdID
[in] 功能区元素的命令 ID。
arElements
[in] 功能区元素数组。
备注
仅测试功能区面板中包含的功能区元素。
CMFCRibbonPanel::GetHighlighted
检索功能区面板上突出显示的功能区元素。
CMFCRibbonBaseElement* GetHighlighted() const;
返回值
指向功能区面板上突出显示的功能区元素的指针。
备注
CMFCRibbonPanel::GetIndex
从功能区面板中包含的功能区元素数组中检索指定功能区元素的从零开始的索引。
virtual int GetIndex(CMFCRibbonBaseElement* pElem) const;
参数
pElem
[in] 指向功能区元素的指针。
返回值
如果此方法成功，则为指定功能区元素的从零开始的索引；否则为 -1。
备注
CMFCRibbonPanel::GetItemIDsList
检索功能区面板中所有功能区元素的命令 ID。
void GetItemIDsList(CList<UINT, UINT>& lstItems) const;
参数
lstItems
[out] 功能区面板中包含的功能区元素的命令 ID 列表。
注解
CMFCRibbonPanel::GetName
检索功能区面板的名称。
LPCTSTR GetName() const;
返回值
功能区面板的名称。
备注
CMFCRibbonPanel::GetParentButton
CMFCRibbonBaseElement* GetParentButton() const;
返回值
注解
CMFCRibbonPanel::GetParentCategory
返回功能区面板的父类别。
CMFCRibbonCategory* GetParentCategory() const;
返回值
指向包含此功能区面板的功能区类别的指针。
CMFCRibbonPanel::GetParentMenuBar
CMFCRibbonPanelMenuBar* GetParentMenuBar() const;
返回值
注解
CMFCRibbonPanel::GetPreferedMenuLocation
检索功能区面板弹出菜单的首选显示矩形。
virtual BOOL GetPreferedMenuLocation(CRect& rect);
参数
rect
[out] 未使用此参数。
返回值
始终返回 FALSE。
备注
此方法始终返回 FALSE。 重写此方法以检索功能区面板弹出菜单的首选显示矩形。
CMFCRibbonPanel::GetPressed
检索在用户当前按下功能区面板的情况下，指向该功能区面板上的功能区元素的指针。
CMFCRibbonBaseElement* GetPressed() const;
返回值
如果用户当前按下功能区元素，则为指向功能区元素的指针；否则为 NULL。
注解
CMFCRibbonPanel::GetRect
检索功能区面板的显示矩形。
const CRect& GetRect() const;
返回值
功能区面板的显示矩形。
备注
CMFCRibbonPanel::HasElement
指示功能区面板是否包含指定的功能区元素。
BOOL HasElement(const CMFCRibbonBaseElement* pElem) const;
参数
pElem
[in] 指向功能区元素的指针。
返回值
如果功能区面板包含指定的功能区元素，则为 TRUE；否则为 FALSE。
注解
CMFCRibbonPanel::Highlight
为所选功能区面板和点指定的功能区元素设置突出显示颜色。
virtual void Highlight(
BOOL bHighlight,
CPoint point);
参数
bHighlight
[in] 如果为 TRUE，则突出显示功能区面板；如果为 FALSE，则取消突出显示功能区面板。
point
[in] 指针的 x 和 y 坐标，相对于窗口左上角。
备注
CMFCRibbonPanel::HitTest
检索在指定的点位于功能区元素中的情况下，指向该功能区元素的指针。
virtual CMFCRibbonBaseElement* HitTest(
CPoint point,
BOOL bCheckPanelCaption = FALSE);
参数
point
[in] 指针的 x 和 y 坐标，相对于窗口左上角。
bCheckPanelCaption
[in] 如果为 TRUE，则测试功能区面板标题；否则为 FALSE。
返回值
如果指定的点位于功能区元素中，则为指向该功能区元素的指针；否则为 NULL。
注解
仅测试功能区面板中包含的功能区元素。
CMFCRibbonPanel::HitTestEx
检索在指定的点位于功能区元素中的情况下，该功能区元素的从零开始的索引。
virtual int HitTestEx(CPoint point) const;
参数
point
[in] 指针的 x 和 y 坐标，相对于窗口左上角。
返回值
如果指定的点位于功能区元素中，则为该功能区元素的从零开始的索引；否则为 -1。
注解
仅测试功能区面板中包含的功能区元素。
CMFCRibbonPanel::Insert
在功能区面板中包含的功能区元素数组中的指定位置插入指定的功能区元素。
virtual BOOL Insert(
CMFCRibbonBaseElement* pElem,
int nIndex);
参数
pElem
[in, out] 指向功能区元素的指针。
nIndex
[in] 从零开始的值，介于 -1 到数组中包含的功能区元素数之间。
返回值
如果成功插入功能区元素，则为 TRUE；否则为 FALSE。
备注
如果 nIndex 的值为 -1，或者 nIndex 等于数组中功能区元素的数目，则会将指定的功能区元素添加到数组的末尾。 如果 nIndex 的值超出范围，则该方法将失败。
CMFCRibbonPanel::InsertSeparator
在给定位置插入分隔符。
virtual BOOL InsertSeparator(int nIndex);
参数
nIndex
[in] 指定插入分隔符的从零开始的索引。
返回值
如果已成功插入分隔符，则为 TRUE；否则为 FALSE。
备注
调用此方法以在 nIndex 指定的位置插入分隔符。 若要在最近添加的功能区元素旁插入分隔符，请调用 CMFCRibbonPanel::AddSeparator。
CMFCRibbonPanel::IsCenterColumnVert
指示功能区元素的垂直位置是否在其显示矩形内居中。
BOOL IsCenterColumnVert() const;
返回值
如果功能区元素的垂直位置在其显示矩形内居中，则为 TRUE；否则为 FALSE。
CMFCRibbonPanel::IsCollapsed
指示功能区面板的显示大小是否在水平方向上最小化。
BOOL IsCollapsed() const;
返回值
如果功能区面板的显示大小在水平方向最小化，则为 TRUE；否则为 FALSE。
备注
当功能区面板折叠时，仅显示其默认按钮、其名称和下拉箭头。
CMFCRibbonPanel::IsHighlighted
指示是否突出显示功能区面板的显示。
BOOL IsHighlighted() const;
返回值
如果突出显示功能区面板的显示，则为 TRUE；否则为 FALSE。
注解
当指针悬停在功能区面板上时，该面板的显示会突出显示。
CMFCRibbonPanel::IsJustifyColumns
指示功能区面板中同一列中的功能区元素的显示尺寸是否设置为相同宽度。
BOOL IsJustifyColumns() const;
返回值
如果功能区面板中同一列中的功能区元素的显示尺寸设置为相同的宽度，则为 TRUE；否则为 FALSE。
CMFCRibbonPanel::IsMainPanel
指示功能区面板是否为主功能区面板。
virtual BOOL IsMainPanel() const;
返回值
始终返回 FALSE。
备注
此方法始终返回 FALSE。 重写此方法以指示功能区面板是否为主功能区面板。
当用户选择应用程序按钮时，将显示主功能区面板。
CMFCRibbonPanel::IsMenuMode
BOOL IsMenuMode() const;
返回值
备注
CMFCRibbonPanel::OnKey
virtual BOOL OnKey(UINT nChar);
参数
[in] nChar
返回值
备注
CMFCRibbonPanel::RecalcWidths
重新计算功能区面板的每个显示布局配置的宽度。
virtual void RecalcWidths(
CDC* pDC,
int nHeight);
参数
pDC
[in] 指向功能区面板的设备上下文的指针。
nHeight
[in] 功能区面板的高度。
备注
功能区面板会随着可用宽度的变化而更改其布局配置。
CMFCRibbonPanel::Remove
移除并选择性地删除位于指定索引处的元素。
BOOL Remove(
int nIndex,
BOOL bDelete = TRUE);
参数
nIndex
[in] 指定从功能区面板中移除的元素的从零开始的索引。
bDelete
[in] 如果为 TRUE，则删除要移除的元素；否则为 FALSE。
返回值
如果元素已被移除和删除，则为 TRUE（如果 bDelete 为 TRUE）；如果元素未被移除，或者 nIndex 处没有功能区元素，则为 FALSE。
备注
调用此方法以从功能区面板中移除元素。
CMFCRibbonPanel::RemoveAll
从功能区面板中删除所有功能区元素。
void RemoveAll();
备注
所有的功能区元素从功能区面板中删除并销毁。
CMFCRibbonPanel::Replace
根据元素的索引值将一个元素替换为另一个元素。
BOOL Replace(
int nIndex,
CMFCRibbonBaseElement* pElem);
参数
nIndex
[in] 指定要替换的元素的从零开始的索引。
pElem
[in, out] 指向用于替换原始元素的元素的有效指针。
返回值
如果原始功能区元素已成功替换为新功能区元素，则为 TRUE；如果未替换功能区元素，或者指定索引处没有元素，则为 FALSE。
备注
若要通过命令 ID 替换功能区元素，请调用 CMFCRibbonPanel::ReplaceByID。
CMFCRibbonPanel::ReplaceByID
根据指定的命令 ID 将一个元素替换为另一个元素。
BOOL ReplaceByID(
UINT uiCmdID,
CMFCRibbonBaseElement* pElem);
参数
uiCmdID
[in] 指定要替换的元素的命令 ID。
pElem
[in, out] 指向将替换原始元素的元素的有效指针。
返回值
如果原始功能区元素已成功替换为新功能区元素，则为 TRUE；如果未替换功能区元素或实际不存在具有指定命令 ID 的元素，则为 FALSE。
备注
若要根据位置替换功能区元素，请调用 CMFCRibbonPanel::Replace。
CMFCRibbonPanel::SetCenterColumnVert
启用或禁用功能区元素的垂直位置在其显示矩形内居中。
void SetCenterColumnVert(BOOL bSet = TRUE);
参数
bSet
[in] 如果为 TRUE，则将功能区元素的垂直位置在其显示矩形内居中；如果为 FALSE，则禁用此功能。
备注
CMFCRibbonPanel::SetData
将用户定义的数据与功能区面板相关联。
void SetData(DWORD_PTR dwData);
参数
dwData
[in] 指定要设置的用户定义数据。
备注
调用此方法将用户定义的数据与功能区面板相关联。
CMFCRibbonPanel::SetElementMenu
将弹出菜单分配给具有给定命令 ID 的元素。
BOOL SetElementMenu(
UINT uiCmdID,
HMENU hMenu,
BOOL bIsDefautCommand = FALSE,
BOOL bRightAlign = FALSE);
BOOL SetElementMenu(
UINT uiCmdID,
UINT uiMenuResID,
BOOL bIsDefautCommand = FALSE,
BOOL bRightAlign = FALSE);
参数
uiCmdID
[in] 指定在其中添加菜单的功能区元素的命令 ID。
hMenu
[in] 指定要添加到功能区面板的 Windows 菜单的句柄。
bIsDefautCommand
[in] 如果为 TRUE，则指定在单击功能区元素的情况下应执行与该元素相关联的命令。 在这种情况下，只有当用户单击功能区元素旁边的箭头时，才会打开菜单。 如果为 FALSE，则指定在单击功能区元素的情况下不应执行与该元素相关联的命令。 在这种情况下，无论用户单击元素的哪个位置，都会显示弹出菜单。
bRightAlign
[in] 如果为 TRUE，则指定弹出菜单向右对齐；否则为 FALSE。
uiMenuResID
[in] 指定要添加到功能区面板的菜单的资源 ID。
返回值
如果菜单已分配给功能区元素，则为 TRUE；否则为 FALSE。
备注
调用此方法，将弹出菜单分配给具有给定命令 ID 的功能区元素。
CMFCRibbonPanel::SetElementRTC
将由所提供的运行时类信息指定的功能区元素添加到功能区面板。
CMFCRibbonBaseElement* SetElementRTC(
int nIndex,
CRuntimeClass* pRTC);
参数
nIndex
[in] 指定要添加的功能区元素的从零开始的索引。
pRTC
[in, out] 指向添加到功能区面板的功能区元素的运行时类信息的指针。
返回值
使用指定的运行时类信息创建的功能区元素。
备注
如果要将自定义元素（例如，颜色按钮）添加到功能区面板，则必须指定自定义元素的运行时类信息。 功能区存储此信息、创建自定义元素并替换由指定命令 ID 定位（标识）的现有元素。 然后，功能区返回指向新创建的元素的指针。
CMFCRibbonPanel::SetElementRTCByID
将由所提供的运行时类信息指定的功能区元素添加到功能区面板。
CMFCRibbonBaseElement* SetElementRTCByID(
UINT uiCmdID,
CRuntimeClass* pRTC);
参数
uiCmdID
[in] 指定要添加的功能区元素的命令 ID。
pRTC
[in, out] 指向与添加到功能区面板的功能区元素相关联的运行时类信息的指针。
返回值
使用指定的运行时类信息创建的功能区元素。
备注
如果要将自定义元素（例如，颜色按钮）添加到功能区面板，则必须指定自定义元素的运行时类信息。 功能区存储此信息、创建自定义元素并替换由指定命令 ID 定位的现有元素。 然后，它将返回指向新创建的元素的指针。
示例
下面的示例显示如何使用 SetElementRTCByID 方法：
// Load and add toolbar with standard buttons. This toolbar
// should display a custom color button with id ID_CHAR_COLOR:
pPanel->AddToolBar(IDR_MAINFRAME,
IDB_MAINFRAME256);
CMFCRibbonColorButton* pColorButton =
(CMFCRibbonColorButton*)pPanel->SetElementRTCByID(
ID_CHAR_COLOR,
RUNTIME_CLASS (CMFCRibbonColorButton));
// SetElementRTCByID sets runtime class and returns a pointer
// to the newly created custom button,
which can be set up immediately:
pColorButton->EnableAutomaticButton(_T("Automatic"),
RGB (0,
0,
0));
CMFCRibbonPanel::SetJustifyColumns
启用或禁用同一列中功能区元素的宽度调整。
void SetJustifyColumns(BOOL bSet = TRUE);
参数
bSet
[in] 如果为 TRUE，则将同一列中的功能区元素的宽度调整为该列中最大功能区元素的宽度；如果为 FALSE，则禁用此宽度调整。
备注
在功能区面板中启用此功能后，同一列中功能区元素的宽度将调整为同一列中最大功能区元素的宽度。
CMFCRibbonPanel::SetKeys
设置功能区面板的默认按钮的快捷键提示。
void SetKeys(LPCTSTR lpszKeys);
参数
lpszKeys
[in] 功能区面板的默认按钮的快捷键提示。
备注
当功能区面板没有足够空间来显示其功能区元素时，将显示默认按钮。
CMFCRibbonPanel::ShowPopup
为功能区面板创建并显示弹出菜单。
CMFCRibbonPanelMenu* ShowPopup(CMFCRibbonDefaultPanelButton* pButton = NULL);
参数
pButton
[in] 指向功能区面板的默认按钮的指针。
返回值
如果此方法成功，则为指向功能区面板弹出菜单的指针；否则为 NULL。
备注
仅当功能区面板的显示折叠时，功能区面板的弹出菜单才可用。
CMFCRibbonPanel::SetFocused
将焦点设置为指定的功能区元素。
void SetFocused(CMFCRibbonBaseElement* pNewFocus);
参数
pNewFocus
指向接收焦点的功能区元素的指针。
注解
CMFCRibbonPanel::MakeGalleryItemVisible
滚动库以使指定的功能区元素可见。
void MakeGalleryItemVisible(CMFCRibbonBaseElement* pItem);
参数
pItem
指向要显示的功能区元素的指针。
备注
CMFCRibbonPanel::IsWindows7Look
指示父功能区是否具有 Windows 7 的外观（小型矩形应用程序按钮）。
BOOL IsWindows7Look() const;
返回值
如果父功能区具有 Windows 7 的外观，则为 TRUE；否则为 FALSE。
备注
CMFCRibbonPanel::GetVisibleElements
检索可见元素数组。
void GetVisibleElements(
CArray<CMFCRibbonBaseElement*,
CMFCRibbonBaseElement*>& arElements);
参数
arElements
函数返回时，此参数包含可见元素数组。
备注
CMFCRibbonPanel::GetGalleryRect
返回库元素的边框。
CRect GetGalleryRect();
返回值
此面板中库元素的大小和位置。
注解
CMFCRibbonPanel::GetFocused
返回焦点元素。
CMFCRibbonBaseElement* GetFocused() const;
返回值
指向焦点元素的指针或 NULL。
注解
另请参阅
层次结构图
类
CObject 类
CMFCRibbonCategory 类
CMFCRibbonBaseElement 类