CMFCRibbonPanel 類別
實作包含一組功能區項目的面板。 繪製面板時，會在指定的面板大小下，顯示盡可能多的項目。
如需更多詳細資料，請參閱 Visual Studio 安裝位置下之 VC\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]指定要新增之工具列的資源識別碼。
uiColdResID
[in]指定工具列冷影像的資源識別碼。
uiHotResID
[in]指定工具列作用中影像的資源識別碼。
uiDisabledResID
[in]指定工具列已停用影像的資源標識碼。
傳回值
呼叫這個方法，將工具列新增至功能區面板。 工具列將會新增至上一次呼叫 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
擷取指定命令標識碼所識別的功能區專案。
CMFCRibbonBaseElement* FindByID(UINT uiCmdID) const;
參數
uiCmdID
[in]功能區專案的命令標識碼。
傳回值
指定命令識別碼所識別的功能區專案;否則，如果未使用指定的命令標識碼來識別任何功能區專案，則為 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
將具有指定命令識別碼的功能區專案加入至指定的陣列。
void GetElementsByID(
UINT uiCmdID,
CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);
參數
uiCmdID
[in]功能區專案的命令標識碼。
arElements
[in]功能區元素的陣列。
備註
只會測試功能區面板中所包含的功能區元素。
CMFCRibbonPanel：：GetHighlighted
擷取功能區面板上反白顯示的功能區專案。
CMFCRibbonBaseElement* GetHighlighted() const;
傳回值
功能區面板上反白顯示之功能區專案的指標。
備註
CMFCRibbonPanel：：GetIndex
從功能區面板中所包含的功能區項目陣列擷取指定功能區專案的以零起始的索引。
virtual int GetIndex(CMFCRibbonBaseElement* pElem) const;
參數
pElem
[in]功能區專案的指標。
傳回值
如果方法成功，則為指定功能區專案的以零起始的索引;否則為 -1。
備註
CMFCRibbonPanel：：GetItemIDsList
擷取功能區面板中所有功能區元素的命令標識碼。
void GetItemIDsList(CList<UINT, UINT>& lstItems) const;
參數
lstItems
[out]功能區面板中所含功能區元素的命令標識符清單。
備註
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。
備註
若要依命令標識碼取代功能區元素，請呼叫 CMFCRibbonPanel：：ReplaceByID。
CMFCRibbonPanel：：ReplaceByID
根據指定的命令標識碼，將一個專案取代為另一個專案。
BOOL ReplaceByID(
UINT uiCmdID,
CMFCRibbonBaseElement* pElem);
參數
uiCmdID
[in]指定要取代之專案的命令標識碼。
pElem
[in， out]將取代原始專案之專案的有效指標。
傳回值
TRUE 是表示 如果原始功能區專案已成功由新的功能區專案取代;如果功能區專案未取代，或沒有具有指定命令標識符的項目實際存在，則為 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
將快捷功能表指派給具有指定命令標識碼的專案。
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]指定新增功能表之功能區元素的命令標識碼。
hMenu
[in]指定要新增至功能區面板的 Windows 功能表句柄。
bIsDefautCommand
[in]如果單擊功能區專案，則為TRUE，指定應該執行與功能區專案相關聯的命令。 在此情況下，只有在使用者單擊功能區元素旁的箭號時，才會開啟功能表。 FALSE 表示如果按兩下功能區專案，則不應該執行與功能區專案相關聯的命令。 在此情況下，不論使用者按兩下元素的位置為何，都會顯示快捷功能表。
bRightAlign
[in]TRUE 表示指定快捷功能表靠右對齊;否則為 FALSE。
uiMenuResID
[in]指定要新增至功能區面板之功能表的資源識別碼。
傳回值
如果功能表已指派給功能區元素，則為TRUE;否則為 FALSE。
備註
呼叫這個方法，將快捷功能表指派給具有指定命令標識碼的功能區專案。
CMFCRibbonPanel：：SetElementRTC
將所提供運行時間類別資訊所指定的功能區專案加入功能區面板。
CMFCRibbonBaseElement* SetElementRTC(
int nIndex,
CRuntimeClass* pRTC);
參數
nIndex
[in]指定要加入之功能區專案之以零起始的索引。
pRTC
[in， out]新增至功能區面板之功能區專案之運行時間類別資訊的指標。
傳回值
使用指定的運行時間類別資訊所建立的功能區專案。
備註
如果您想要將自訂元素（例如色彩按鈕）新增至功能區面板，您必須指定自定義專案的運行時間類別資訊。 功能區會儲存這項資訊、建立自定義專案，並取代位於指定命令標識碼的現有專案。。 然後，功能區會傳回新建立專案的指標。
CMFCRibbonPanel：：SetElementRTCByID
將提供的運行時間類別資訊所指定的功能區專案加入功能區面板。
CMFCRibbonBaseElement* SetElementRTCByID(
UINT uiCmdID,
CRuntimeClass* pRTC);
參數
uiCmdID
[in]指定要加入的功能區專案命令標識碼。
pRTC
[in， out]與新增至功能區面板之功能區專案相關聯的運行時間類別資訊的指標。
傳回值
使用指定的運行時間類別資訊所建立的功能區專案。
備註
如果您想要將自訂元素（例如色彩按鈕）新增至功能區面板，您必須指定自定義專案的運行時間類別資訊。 功能區會儲存這項資訊、建立自定義專案，並取代指定的命令標識碼所找到的現有專案。 然後，它會傳回新建立專案的指標。
範例
下列範例示範如何使用 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
將焦點設定為指定的 Ribbon 元素。
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
傳回 Gallery 元素的周框。
CRect GetGalleryRect();
傳回值
資源庫元素在此面板中的大小和位置。
備註
CMFCRibbonPanel：：GetFocused
傳回具有焦點的項目。
CMFCRibbonBaseElement* GetFocused() const;
傳回值
焦點專案或 NULL 的指標。
備註
另請參閱
階層架構圖表
類別
CObject 類別
CMFCRibbonCategory 類別
CMFCRibbonBaseElement 類別