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);
參數
矩形
[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 可取消選取功能區面板。
點
[in]指標的 x 和 y 座標，相對於視窗左上角。
備註
CMFCRibbonPanel：：HitTest
如果指定的點位於功能區中，則擷取功能區專案。
virtual CMFCRibbonBaseElement* HitTest(
CPoint point,
BOOL bCheckPanelCaption = FALSE);
參數
點
[in]指標的 x 和 y 座標，相對於視窗左上角。
bCheckPanelCaption
[in]TRUE 可測試功能區面板標題，否則為 FALSE。
傳回值
如果指定的點位於功能區元素，則為指標;否則為 Null。
備註
只會測試功能區面板中所包含的功能區元素。
CMFCRibbonPanel：：HitTestEx
擷取功能區元素的以零起始的索引，該元素的指定點位於其中。
virtual int HitTestEx(CPoint point) const;
參數
點
[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 類別
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應