`CMenu` 類別

發行項
07/05/2024

Windows HMENU的封裝。

語法

class CMenu : public CObject

成員

公用建構函式

名稱	描述
`CMenu::CMenu`	建構 `CMenu` 物件。

公用方法

名稱	描述
`CMenu::AppendMenu`	將新專案附加至此功能表的結尾。
`CMenu::Attach`	將 Windows 功能表句柄附加至 `CMenu` 物件。
`CMenu::CheckMenuItem`	將複選標記放在快顯功能表中的功能表項旁，或移除複選標記。
`CMenu::CheckMenuRadioItem`	將單選按鈕放在功能表項旁邊，並從群組中的所有其他功能表項中移除單選按鈕。
`CMenu::CreateMenu`	建立空的功能表，並將它附加至 `CMenu` 物件。
`CMenu::CreatePopupMenu`	建立空的快捷功能表，並將它附加至 `CMenu` 物件。
`CMenu::DeleteMenu`	從功能表中刪除指定的專案。如果功能表項具有相關聯的快捷功能表，則會終結快捷功能表的句柄，並釋放其所使用的記憶體。
`CMenu::DeleteTempMap`	刪除成員函式所`FromHandle`建立的任何暫存`CMenu`物件。
`CMenu::DestroyMenu`	終結附加至 `CMenu` 對象的功能表，並釋放功能表佔用的任何記憶體。
`CMenu::Detach`	從 `CMenu` 物件中斷連結 Windows 功能表句柄，並傳回句柄。
`CMenu::DrawItem`	當擁有者繪製功能表的視覺層面變更時，由架構呼叫。
`CMenu::EnableMenuItem`	啟用、停用或暗色功能表項。
`CMenu::FromHandle`	傳回指定 Windows 功能表句柄之物件的指標 `CMenu` 。
`CMenu::GetDefaultItem`	決定指定功能表上的預設功能表項。
`CMenu::GetMenuContextHelpId`	擷取與功能表相關聯的說明內容標識碼。
`CMenu::GetMenuInfo`	擷取特定功能表上的資訊。
`CMenu::GetMenuItemCount`	決定快顯或最上層功能表中的項目數。
`CMenu::GetMenuItemID`	取得位於指定位置之功能表項的功能表項識別碼。
`CMenu::GetMenuItemInfo`	擷取功能表項的相關信息。
`CMenu::GetMenuState`	傳回指定功能表項的狀態，或快捷功能表中的項目數。
`CMenu::GetMenuString`	擷取指定功能表項的標籤。
`CMenu::GetSafeHmenu`	傳 `m_hMenu` 回這個 `CMenu` 物件所包裝的。
`CMenu::GetSubMenu`	擷取快捷功能表的指標。
`CMenu::InsertMenu`	在指定的位置插入新的功能表項，並將其他專案向下移動功能表。
`CMenu::InsertMenuItem`	在功能表中的指定位置插入新的功能表項。
`CMenu::LoadMenu`	從可執行檔載入功能表資源，並將它附加至 `CMenu` 物件。
`CMenu::LoadMenuIndirect`	從記憶體中的功能表範本載入功能表，並將它附加至 `CMenu` 物件。
`CMenu::MeasureItem`	由架構呼叫，以在建立擁有者繪製功能表時判斷功能表維度。
`CMenu::ModifyMenu`	變更位於指定位置的現有功能表項。
`CMenu::RemoveMenu`	從指定的功能表中，刪除具有相關聯快捷功能表的功能表項。
`CMenu::SetDefaultItem`	設定指定功能表的預設功能表項。
`CMenu::SetMenuContextHelpId`	設定要與功能表相關聯的說明內容標識碼。
`CMenu::SetMenuInfo`	設定特定功能表上的資訊。
`CMenu::SetMenuItemBitmaps`	將指定的複選標記點陣圖與功能表項產生關聯。
`CMenu::SetMenuItemInfo`	變更功能表項的相關信息。
`CMenu::TrackPopupMenu`	在指定的位置顯示浮動快捷功能表，並追蹤彈出視窗功能表上的項目選取範圍。
`CMenu::TrackPopupMenuEx`	在指定的位置顯示浮動快捷功能表，並追蹤彈出視窗功能表上的項目選取範圍。

公用運算子

名稱	描述
`CMenu::operator HMENU`	擷取功能表物件的句柄。
`CMenu::operator !=`	判斷兩個功能表物件是否不相等。
`CMenu::operator ==`	判斷兩個功能表物件是否相等。

公用資料成員

名稱	描述
`CMenu::m_hMenu`	指定附加至 `CMenu` 物件的 Windows 功能表句柄。

備註

它提供成員函式來建立、追蹤、更新和終結功能表。

在 CMenu 堆疊框架上建立物件做為本機，然後呼叫 CMenu的成員函式，視需要操作新的功能表。接下來，呼叫 CWnd::SetMenu 以將功能表設定為視窗，後面緊接著呼叫 CMenu 對象的 Detach 成員函式。成員函式會將 CWnd::SetMenu 視窗的功能表設定為新的功能表、讓視窗重新繪製以反映功能表變更，並將功能表的擁有權傳遞至視窗。從物件卸離 HMENU CMenu 的呼叫Detach，如此一來，當局部CMenu變數超出範圍時，CMenu物件解構函式不會嘗試終結它不再擁有的功能表。當窗口終結時，功能表本身會自動終結。

您可以使用 LoadMenuIndirect 成員函式從記憶體中的範本建立功能表，但是透過呼叫 LoadMenu 從資源建立的功能表更容易維護，功能表資源本身可由功能表編輯器建立和修改。

繼承階層架構

CObject

CMenu

需求

標頭： afxwin.h

`CMenu::AppendMenu`

將新專案附加至功能表的結尾。

BOOL AppendMenu(
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL AppendMenu(
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

參數

nFlags
指定將新功能表項新增至功能表時的狀態相關信息。它是由一節中列出的一或多個值所組成。

nIDNewItem
指定新功能表項的命令標識碼，如果 nFlags 設定為 MF_POPUP，則為快捷功能表的功能表句柄（HMENU）。如果 nFlags 設定為 MF_SEPARATOR，則會nIDNewItem忽略參數（不需要）。

lpszNewItem
指定新功能表項的內容。 nFlags參數是用來以下列方式解譯lpszNewItem：

`nFlags`	解譯 `lpszNewItem`
`MF_OWNERDRAW`	包含應用程式提供的32位值，應用程式可用來維護與功能表項相關聯的其他數據。此 32 位值可在應用程式處理 `WM_MEASUREITEM` 和 `WM_DRAWITEM` 訊息時使用。此值會儲存在這些 `itemData` 訊息所提供之結構的成員中。
`MF_STRING`	包含 Null 終止字串的指標。這是預設解譯。
`MF_SEPARATOR`	`lpszNewItem`參數會被忽略（不需要）。

pBmp
CBitmap指向將做為功能表項的物件。

傳回值

如果函式成功則為非零，否則為 0。

備註

應用程式可以在中 nFlags設定值，以指定功能表項的狀態。當指定快捷功能表時 nIDNewItem ，它就會成為其附加的功能表的一部分。如果該功能表終結，則附加的功能表也會終結。附加的功能表應該與 CMenu 物件中斷連結，以避免衝突。請注意， MF_STRING 和 MF_OWNERDRAW 對的 AppendMenu位圖版本無效。

下列清單描述中可能設定 nFlags的旗標：

MF_CHECKED 做為的 MF_UNCHECKED 切換，將預設複選標記放在專案旁邊。當應用程式提供複選標記點陣圖時（請參閱 SetMenuItemBitmaps 成員函式），就會顯示「複選標記」位圖。
MF_UNCHECKED 做為切換， MF_CHECKED 用來移除專案旁的複選標記。當應用程式提供複選標記點陣圖時（請參閱 SetMenuItemBitmaps 成員函式），會顯示「複選標記關閉」位圖。
MF_DISABLED 停用功能表項，使其無法選取，但不會使它變暗。
MF_ENABLED 啟用功能表項，以便選取功能表項，並從其暗灰色狀態還原它。
MF_GRAYED 停用功能表項，使其無法選取並將它變暗。
MF_MENUBARBREAK 將專案放在靜態功能表的新行上，或放在快捷功能表的新數據行中。新的快顯功能表欄將會以垂直分隔線分隔舊數據行。
MF_MENUBREAK 將專案放在靜態功能表的新行上，或放在快捷功能表的新數據行中。數據行之間不會放置任何分隔線。
MF_OWNERDRAW 指定專案是擁有者繪製專案。第一次顯示功能表時，擁有功能表的視窗會收到 WM_MEASUREITEM 訊息，它會擷取功能表項的高度和寬度。每當 WM_DRAWITEM 擁有者必須更新功能表項的視覺外觀時，就會傳送訊息。此選項不適用於最上層功能表單項。
MF_POPUP 指定功能表項具有與其相關聯的快捷功能表。 ID 參數會指定要與專案相關聯之快捷功能表的句柄。這可用來將最上層快捷功能表或階層式快捷功能表新增至快顯功能表項。
MF_SEPARATOR 繪製水準分隔線。只能在快捷功能表中使用。此行無法呈現暗灰色、停用或反白顯示。會忽略其他參數。
MF_STRING 指定功能表項是字元字串。

下列每個群組都會列出互斥且不能一起使用的旗標：

MF_DISABLED、MF_ENABLED 和 MF_GRAYED
MF_STRING、 MF_OWNERDRAW、 MF_SEPARATOR和點陣圖版本
MF_MENUBARBREAK 和 MF_MENUBREAK
MF_CHECKED 和 MF_UNCHECKED

每當視窗內的選單變更（無論是否顯示視窗），應用程式都應該呼叫 CWnd::DrawMenuBar。

範例

請參閱 CMenu::CreateMenu 的範例。

`CMenu::Attach`

將現有的 Windows 功能表附加至 CMenu 物件。

BOOL Attach(HMENU hMenu);

參數

hMenu
指定 Windows 功能表的句柄。

傳回值

如果作業成功，則為非零;否則為 0。

備註

如果功能表已經附加至物件， CMenu 則不應該呼叫此函式。功能表句柄會儲存在數據成員中 m_hMenu 。

如果您想要操作的功能表已經與視窗相關聯，您可以使用函 CWnd::GetMenu 式來取得功能表的句柄。

範例

CMenu mnu;
HMENU hmnu = AfxGetMainWnd()->GetMenu()->GetSafeHmenu();
mnu.Attach(hmnu);

// Now you can manipulate the window's menu as a CMenu
// object...

mnu.Detach();

`CMenu::CheckMenuItem`

將複選標記新增至快顯功能表中的功能表項，或移除複選標記。

UINT CheckMenuItem(
    UINT nIDCheckItem,
    UINT nCheck);

參數

nIDCheckItem
指定要核取的功能表項，如所 nCheck決定。

nCheck
指定如何檢查功能表項，以及如何判斷功能表項的位置。參數nCheck可以是或與 MF_BYPOSITION 或 MF_UNCHECKED MF_BYCOMMAND 旗標的組合MF_CHECKED。您可以使用位 OR 運算子來結合這些旗標。它們具有下列意義：

MF_BYCOMMAND 指定參數會提供現有功能表項的命令標識碼。這是預設值。
MF_BYPOSITION 指定參數提供現有功能表項的位置。第一個項目位於位置0。
MF_CHECKED 做為的 MF_UNCHECKED 切換，將預設複選標記放在專案旁邊。
MF_UNCHECKED 做為切換， MF_CHECKED 用來移除專案旁的複選標記。

傳回值

專案的上一個狀態： MF_CHECKED 或 MF_UNCHECKED，如果 0xFFFFFFFF 功能表項不存在，則為。

備註

參數 nIDCheckItem 會指定要修改的專案。

參數 nIDCheckItem 可以識別快捷功能表項以及功能表項。檢查快捷功能表項不需要任何特殊步驟。無法檢查最上層功能表項。快顯功能表項必須依位置檢查，因為它沒有與其相關聯的功能表項標識碼。

範例

請參閱 CMenu::GetMenuState 的範例。

`CMenu::CheckMenuRadioItem`

檢查指定的功能表項，並使它成為單選專案。

BOOL CheckMenuRadioItem(
    UINT nIDFirst,
    UINT nIDLast,
    UINT nIDItem,
    UINT nFlags);

參數

nIDFirst
指定（根據單選按鈕群組中的第一個功能表項的值 nFlags，以標識碼或位移。

nIDLast
指定（根據單選按鈕群組中的最後一個功能表項的值 nFlags，以標識碼或位移。

nIDItem
指定（根據的值 nFlags而定，標識碼或位移）群組中的專案，以單選按鈕檢查。

nFlags
以下列方式指定、 nIDLast和 nIDItem 的nIDFirst解譯：

nFlags	解釋
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

傳回值

如果成功，則為非零;否則為 0

備註

同時，函式會取消核取相關聯群組中的所有其他功能表項，並清除這些專案的單選專案類型旗標。核取的專案是使用單選按鈕（或項目符號）位圖來顯示，而不是複選標記位圖。

範例

請參閱 ON_COMMAND_RANGE 的範例。

`CMenu::CMenu`

建立空的功能表，並將它附加至 CMenu 物件。

CMenu();

備註

在您呼叫的其中一個 create 或 load 成員函 CMenu式之前，不會建立功能表：

CreateMenu
CreatePopupMenu
LoadMenu
LoadMenuIndirect
Attach

`CMenu::CreateMenu`

建立功能表，並將它附加至 CMenu 物件。

BOOL CreateMenu();

傳回值

如果已成功建立功能表，則為非零;否則為 0。

備註

功能表一開始是空的。您可以使用或 InsertMenu 成員函式來新增AppendMenu功能表項。

如果功能表指派給視窗，則會在窗口終結時自動終結。

結束之前，如果功能表未指派給視窗，應用程式必須釋放與功能表相關聯的系統資源。應用程式會藉由呼叫 DestroyMenu 成員函式來釋放功能表。

範例

// The code fragment below shows how to create a new menu for the
// application window using CreateMenu() and CreatePopupMenu().
// Then, the created menu will replace the current menu of the
// application. The old menu will be destroyed with DestroyMenu().
// NOTE: The code fragment below is done in a CFrameWnd-derived class.

// Create a new menu for the application window.
VERIFY(m_NewMenu.CreateMenu());

// Create a "File" popup menu and insert this popup menu to the
// new menu of the application window. The "File" menu has only
// one menu item, i.e. "Exit".
VERIFY(m_FileMenu.CreatePopupMenu());
m_FileMenu.AppendMenu(MF_STRING, ID_APP_EXIT, _T("E&xit"));
m_NewMenu.AppendMenu(MF_POPUP, (UINT_PTR)m_FileMenu.m_hMenu, _T("&File"));

// Remove and destroy old menu
SetMenu(NULL);
CMenu *old_menu = CMenu::FromHandle(m_hMenuDefault);
old_menu->DestroyMenu();

// Add new menu.
SetMenu(&m_NewMenu);

// Assign default menu
m_hMenuDefault = m_NewMenu.m_hMenu;

`CMenu::CreatePopupMenu`

建立快捷功能表，並將它附加至 CMenu 物件。

BOOL CreatePopupMenu();

傳回值

如果已成功建立快顯功能表，則為非零;否則為 0。

備註

功能表一開始是空的。您可以使用或 InsertMenu 成員函式來新增AppendMenu功能表項。應用程式可以將快捷功能表新增至現有的功能表或快捷功能表。成員 TrackPopupMenu 函式可用來將此功能表顯示為浮動快捷功能表，以及追蹤彈出視窗選單上的選取專案。

如果功能表指派給視窗，則會在窗口終結時自動終結。如果功能表新增至現有的功能表，該功能表終結時會自動終結。

結束之前，如果功能表未指派給視窗，應用程式必須釋放與快捷功能表相關聯的系統資源。應用程式會藉由呼叫 DestroyMenu 成員函式來釋放功能表。

範例

請參閱 CMenu::CreateMenu 的範例。

`CMenu::DeleteMenu`

從功能表中刪除專案。

BOOL DeleteMenu(
    UINT nPosition,
    UINT nFlags);

參數

nPosition
指定要刪除的功能表項，如所 nFlags決定。

nFlags
用來以下列方式解譯 nPosition ：

`nFlags`	解譯 `nPosition`
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

傳回值

如果函式成功則為非零，否則為 0。

備註

如果功能表項具有相關聯的快捷功能表， DeleteMenu 則會終結快捷功能表的句柄，並釋放快捷功能表所使用的記憶體。

每當視窗內所在的選單變更（無論是否顯示視窗），應用程式都必須呼叫 CWnd::DrawMenuBar。

範例

請參閱 CWnd::GetMenu 的範例。

`CMenu::DeleteTempMap`

由CWinApp閑置時間處理程式自動呼叫，刪除成員函式所FromHandle建立的任何暫存CMenu物件。

static void PASCAL DeleteTempMap();

備註

DeleteTempMap 先中斷連結附加至暫存 CMenu 物件的 Windows 選單物件，再刪除 CMenu 物件。

範例

// DeleteTempMap() is a static member and does not need
// an instantiated CMenu object.
CMenu::DeleteTempMap();

`CMenu::DestroyMenu`

終結功能表和使用的任何 Windows 資源。

BOOL DestroyMenu();

傳回值

如果功能表被終結，則為非零;否則為 0。

備註

功能表在終結之前， CMenu 會與對象中斷連結。解構函式中CMenu會自動呼叫 Windows DestroyMenu 函式。

範例

請參閱 CMenu::CreateMenu 的範例。

`CMenu::Detach`

從 CMenu 物件中斷連結 Windows 功能表，並傳回句柄。

HMENU Detach();

傳回值

如果成功，類型 HMENU為的句柄，則為 Windows 選單，否則 NULL為。

備註

資料 m_hMenu 成員會設定為 NULL。

範例

CMenu mnu;
HMENU hmnu = AfxGetMainWnd()->GetMenu()->GetSafeHmenu();
mnu.Attach(hmnu);

// Now you can manipulate the window's menu as a CMenu
// object...

mnu.Detach();

`CMenu::DrawItem`

當擁有者繪製功能表的視覺層面變更時，由架構呼叫。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

參數

lpDrawItemStruct
結構的指標 DRAWITEMSTRUCT ，其中包含所需繪圖類型的相關信息。

備註

結構 itemAction 的成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。覆寫這個成員函式，以實作擁有者繪製對象的繪圖 CMenu 。應用程式應該在終止此成員函式之前，還原針對所提供 lpDrawItemStruct 顯示內容選取的所有圖形裝置介面（GDI）物件。

如需結構的描述，DRAWITEMSTRUCT請參閱 CWnd::OnDrawItem 。

範例

下列程式代碼來自 MFC CTRLTEST 範例：

// Override DrawItem() to implement drawing for an owner-draw CMenu object.
// CColorMenu is a CMenu-derived class.
void CColorMenu::DrawItem(LPDRAWITEMSTRUCT lpDIS)
{
   CDC *pDC = CDC::FromHandle(lpDIS->hDC);
   COLORREF cr = (COLORREF)lpDIS->itemData; // RGB in item data

   if (lpDIS->itemAction & ODA_DRAWENTIRE)
   {
      // Paint the color item in the color requested
      CBrush br(cr);
      pDC->FillRect(&lpDIS->rcItem, &br);
   }

   if ((lpDIS->itemState & ODS_SELECTED) &&
       (lpDIS->itemAction & (ODA_SELECT | ODA_DRAWENTIRE)))
   {
      // item has been selected - hilite frame
      COLORREF crHilite = RGB(255 - GetRValue(cr),
                              255 - GetGValue(cr), 255 - GetBValue(cr));
      CBrush br(crHilite);
      pDC->FrameRect(&lpDIS->rcItem, &br);
   }

   if (!(lpDIS->itemState & ODS_SELECTED) &&
       (lpDIS->itemAction & ODA_SELECT))
   {
      // Item has been de-selected -- remove frame
      CBrush br(cr);
      pDC->FrameRect(&lpDIS->rcItem, &br);
   }
}

`CMenu::EnableMenuItem`

啟用、停用或將功能表項變暗。

UINT EnableMenuItem(
    UINT nIDEnableItem,
    UINT nEnable);

參數

nIDEnableItem
指定要啟用的功能表項，如所 nEnable決定。此參數可以指定快捷功能表項以及標準功能表項。

nEnable
指定要採取的動作。它可以是、MF_ENABLED、或 MF_GRAYED與 MF_BYCOMMAND 或 MF_BYPOSITION的組合MF_DISABLED。您可以使用C++位 OR 運算子（|）來結合這些值。這些值具有以下意義：

MF_BYCOMMAND 指定參數會提供現有功能表項的命令標識碼。這是預設值。
MF_BYPOSITION 指定參數提供現有功能表項的位置。第一個項目位於位置0。
MF_DISABLED 停用功能表項，使其無法選取，但不會使它變暗。
MF_ENABLED 啟用功能表項，以便選取功能表項，並從其暗灰色狀態還原它。
MF_GRAYED 停用功能表項，使其無法選取並將它變暗。

傳回值

如果無效，則為先前的狀態（MF_DISABLED、 MF_ENABLED或）或 MF_GRAYED-1。

備註

CreateMenu、InsertMenu、 ModifyMenu和 LoadMenuIndirect 成員函式也可以設定功能表項的狀態（已啟用、停用或變暗）。

MF_BYPOSITION使用值需要應用程式使用正確的 CMenu。 CMenu如果使用功能表欄的，則會影響最上層功能表項（功能表欄中的專案）。若要依位置設定快捷選單或巢狀快捷選單中的項目狀態，應用程式必須指定 CMenu 快捷選單的。

當應用程式指定 MF_BYCOMMAND 旗標時，Windows 會檢查屬於 CMenu的所有快捷功能表項;因此，除非有重複的功能表項存在，否則使用 CMenu 功能表欄的就已足夠。

範例

// The code fragment below shows how to disable (and gray out) the
// File\New menu item.
// NOTE: m_bAutoMenuEnable is set to FALSE in the constructor of
// CMainFrame so no ON_UPDATE_COMMAND_UI or ON_COMMAND handlers are
// needed, and CMenu::EnableMenuItem() will work as expected.

CMenu *mmenu = GetMenu();
CMenu *submenu = mmenu->GetSubMenu(0);
submenu->EnableMenuItem(ID_FILE_NEW, MF_BYCOMMAND | MF_DISABLED | MF_GRAYED);

`CMenu::FromHandle`

傳回物件的指標 CMenu ，指定功能表的 Windows 句柄。

static CMenu* PASCAL FromHandle(HMENU hMenu);

參數

hMenu
功能表的 Windows 句柄。

傳回值

可能為暫時或永久的指標 CMenu 。

備註

CMenu如果物件尚未附加至 Windows 功能表物件，則會建立並附加暫存CMenu物件。

此暫存 CMenu 物件只有在下次應用程式在其事件迴圈中有閑置時間之前才有效，此時會刪除所有暫存物件。

範例

請參閱 CMenu::CreateMenu 的範例。

`CMenu::GetDefaultItem`

決定指定功能表上的預設功能表項。

UINT GetDefaultItem(
    UINT gmdiFlags,
    BOOL fByPos = FALSE);

參數

gmdiFlags
值，指定函式搜尋功能表項的方式。此參數可以是無、一個或下列值的組合：

值	意義
`GMDI_GOINTOPOPUPS`	指定，如果預設專案是開啟子功能表的專案，函式會以遞歸方式搜尋對應的子功能表。如果子功能表沒有預設專案，則傳回值會識別開啟子功能表的專案。根據預設，函式會傳回指定功能表上的第一個預設專案，不論它是否為開啟子功能表的專案。
`GMDI_USEDISABLED`	指定函式是傳回預設專案，即使它已停用也一樣。根據預設，函式會略過已停用或灰色的專案。

fByPos
值，指定是否要擷取功能表項的標識碼或其位置。如果此參數為 FALSE，則會傳回標識符。否則，會傳回位置。

傳回值

如果函式成功，傳回值就是功能表項的標識碼或位置。如果函式失敗，則傳回值為 - 1。

備註

此成員函式會實作 Win32 函式 GetMenuDefaultItem 的行為，如 Windows SDK 中所述。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::GetMenuContextHelpId`

擷取與 CMenu相關聯的內容說明標識碼。

DWORD GetMenuContextHelpId() const;

傳回值

如果內容說明標識碼有一個，則為目前相關聯的 CMenu 說明標識符;否則為零。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::GetMenuInfo`

擷取功能表的資訊。

BOOL GetMenuInfo(LPMENUINFO lpcmi) const;

參數

lpcmi
結構的指標 MENUINFO ，其中包含功能表的資訊。

傳回值

如果函式成功，則傳回值為非零;否則，傳回值為零。

備註

呼叫此函式以擷取功能表的相關信息。

`CMenu::GetMenuItemCount`

決定快顯或最上層功能表中的項目數。

UINT GetMenuItemCount() const;

傳回值

如果函式成功，功能表中的項目數;否則為 -1。

範例

請參閱 CWnd::GetMenu 的範例。

`CMenu::GetMenuItemID`

取得位於所 nPos定義位置之功能表項的功能表項識別碼。

UINT GetMenuItemID(int nPos) const;

參數

nPos
指定要擷取其標識碼之功能表項的位置（以零起始）。

傳回值

如果函式成功，則快捷功能表中指定專案的專案識別碼。如果指定的專案是快捷功能表（相對於快捷功能表內的專案），則傳回值為 -1。如果 nPos 對應至 SEPARATOR 功能表項，則傳回值為 0。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::GetMenuItemInfo`

擷取功能表項的相關信息。

BOOL GetMenuItemInfo(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

參數

uItem
要取得相關信息的功能表項標識碼或位置。此參數的意義取決於的值 ByPos。

lpMenuItemInfo
的指標 MENUITEMINFO，如 Windows SDK 中所述，其中包含功能表的相關信息。

fByPos
值，指定的意義 nIDItem。默認為 FALSE，ByPos表示 uItem 是功能表項識別碼。如果未 ByPos 設定為 FALSE，表示功能表項位置。

傳回值

如果函式成功，則傳回非零的值。如果此函式失敗，則傳回值為零。若要取得擴充錯誤資訊，請使用 Win32 函式 GetLastError，如 Windows SDK 中所述。

備註

此成員函式會實作 Win32 函 GetMenuItemInfo式的行為，如 Windows SDK 中所述。請注意，在的 GetMenuItemInfoMFC 實作中，您不會使用功能表的句柄。

範例

// CMainFrame::OnToggleTestMenuInfo() is a menu command handler for 
// "Toggle Info" menu item (whose resource id is ID_MENU_TOGGLEINFO). It 
// toggles the checked or unchecked state of the "Toggle Info" menu item.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnToggleTestMenuItemInfo()
{
   // Get the popup menu which contains the "Toggle Info" menu item.
   CMenu* mmenu = GetMenu();
   CMenu* submenu = mmenu->GetSubMenu(4);

   // Check the state of the "Toggle Info" menu item. Check the menu item
   // if it is currently unchecked. Otherwise, uncheck the menu item
   // if it is not currently checked.
   MENUITEMINFO info;
   info.cbSize = sizeof (MENUITEMINFO); // must fill up this field
   info.fMask = MIIM_STATE;             // get the state of the menu item
   VERIFY(submenu->GetMenuItemInfo(ID_MENU_TOGGLEINFO, &info));

   if (info.fState & MF_CHECKED)
      submenu->CheckMenuItem(ID_MENU_TOGGLEINFO, MF_UNCHECKED | MF_BYCOMMAND);
   else
      submenu->CheckMenuItem(ID_MENU_TOGGLEINFO, MF_CHECKED | MF_BYCOMMAND);
}

`CMenu::GetMenuState`

傳回指定功能表項的狀態，或快捷功能表中的項目數。

UINT GetMenuState(
    UINT nID,
    UINT nFlags) const;

參數

nID
指定由所 nFlags決定的功能表項識別碼。

nFlags
指定的 nID本質。它可能是下列其中一個值：

MF_BYCOMMAND 指定參數會提供現有功能表項的命令標識碼。這是預設值。
MF_BYPOSITION 指定參數提供現有功能表項的位置。第一個項目位於位置0。

傳回值

如果指定的專案不存在，則為值 0xFFFFFFFF 。如果 nId 識別快捷功能表，高階位元組會包含快捷功能表中的項目數，而低序位元組則包含與快顯功能表相關聯的功能表旗標。否則，傳回值是下列清單中值的遮罩（布爾值 OR）（此遮罩描述識別的功能表項 nId 狀態）：

MF_CHECKED 做為的 MF_UNCHECKED 切換，將預設複選標記放在專案旁邊。當應用程式提供複選標記點陣圖時（請參閱 SetMenuItemBitmaps 成員函式），就會顯示「複選標記」位圖。
MF_DISABLED 停用功能表項，使其無法選取，但不會使它變暗。
MF_ENABLED 啟用功能表項，以便選取功能表項，並從其暗灰色狀態還原它。請注意，這個常數的值是 0;使用這個值時，應用程式不應該針對 0 進行測試，是否有失敗。
MF_GRAYED 停用功能表項，使其無法選取並將它變暗。
MF_MENUBARBREAK 將專案放在靜態功能表的新行上，或放在快捷功能表的新數據行中。新的快顯功能表欄將會以垂直分隔線分隔舊數據行。
MF_MENUBREAK 將專案放在靜態功能表的新行上，或放在快捷功能表的新數據行中。數據行之間不會放置任何分隔線。
MF_SEPARATOR 繪製水準分隔線。只能在快捷功能表中使用。此行無法呈現暗灰色、停用或反白顯示。會忽略其他參數。
MF_UNCHECKED 做為切換， MF_CHECKED 用來移除專案旁的複選標記。當應用程式提供複選標記點陣圖時（請參閱 SetMenuItemBitmaps 成員函式），會顯示「複選標記關閉」位圖。請注意，這個常數的值是 0;使用這個值時，應用程式不應該針對 0 進行測試，是否有失敗。

範例

// CMainFrame::OnToggleTestMenuState() is a menu command handler for
// "Toggle State" menu item (whose resource id is ID_MENU_TOGGLESTATE).
// It toggles the checked or unchecked state of the "Toggle State" menu item.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnToggleTestMenuState()
{
   // Get the popup menu which contains the "Toggle State" menu item.
   CMenu *mmenu = GetMenu();
   CMenu *submenu = mmenu->GetSubMenu(4);

   // Check the state of the "Toggle State" menu item. Check the menu item
   // if it is currently unchecked. Otherwise, uncheck the menu item
   // if it is not currently checked.
   UINT state = submenu->GetMenuState(ID_MENU_TOGGLESTATE, MF_BYCOMMAND);
   ASSERT(state != 0xFFFFFFFF);

   if (state & MF_CHECKED)
      submenu->CheckMenuItem(ID_MENU_TOGGLESTATE, MF_UNCHECKED | MF_BYCOMMAND);
   else
      submenu->CheckMenuItem(ID_MENU_TOGGLESTATE, MF_CHECKED | MF_BYCOMMAND);
}

`CMenu::GetMenuString`

將指定功能表項的標籤複製到指定的緩衝區。

int GetMenuString(
    UINT nIDItem,
    LPTSTR lpString,
    int nMaxCount,
    UINT nFlags) const;

int GetMenuString(
    UINT nIDItem,
    CString& rString,
    UINT nFlags) const;

參數

nIDItem
根據的值 nFlags，指定功能表項的整數標識碼或功能表項的位移。

lpString
指向要接收標籤的緩衝區。

rString
要接收所複製功能表字串之對象的參考 CString 。

nMaxCount
指定要複製之標籤的最大長度（以字元為單位）。如果標籤的長度超過中指定的 nMaxCount最大值，則會截斷額外的字元。

nFlags
指定參數的 nIDItem 解譯。它可能是下列其中一個值：

`nFlags`	解譯 `nIDItem`
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

傳回值

指定複製到緩衝區的實際字元數，不包括 Null 終止符。

備註

參數 nMaxCount 應大於標籤中的字元數，以容納終止字串的 Null 字元。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::GetSafeHmenu`

傳 HMENU 回這個 CMenu 物件或指標所包裝的 NULL CMenu 。

HMENU GetSafeHmenu() const;

範例

請參閱 CMenu::LoadMenu 的範例。

`CMenu::GetSubMenu`

CMenu擷取快捷功能表的物件。

CMenu* GetSubMenu(int nPos) const;

參數

nPos
指定功能表中包含之快捷功能表的位置。位置值從第一個功能表項的 0 開始。快顯功能表的識別碼不能用於此函式。

傳回值

如果快捷選單存在於指定位置，則物件的m_hMenu指標CMenu，其成員包含快捷功能表的句柄，否則NULL為。 CMenu如果物件不存在，則會建立暫存物件。傳回的 CMenu 指標不應該儲存。

範例

請參閱 CMenu::TrackPopupMenu 的範例。

`CMenu::InsertMenu`

在指定的 nPosition 位置插入新的功能表項，並將其他專案向下移動功能表。

BOOL InsertMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL InsertMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

參數

nPosition
指定要插入新功能表項之前的功能表項。 nFlags參數可用來以下列方式解譯nPosition：

`nFlags`	解譯 `nPosition`
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。如果 `nPosition` 為 -1，新功能表項會附加至功能表的結尾。

nFlags
指定如何 nPosition 解譯，並在將新功能表項新增至功能表時指定新功能表項狀態的相關信息。如需可設定的旗標清單，請參閱 AppendMenu 成員函式。若要指定多個值，請使用位 OR 運算子將它們與 MF_BYCOMMAND 或 MF_BYPOSITION 旗標結合。

nIDNewItem
指定新功能表項的命令標識碼，如果 nFlags 設定為 MF_POPUP，則為彈出視窗功能表的功能表句柄（HMENU）。如果 nFlags 設定為 MF_SEPARATOR，則會nIDNewItem忽略參數（不需要）。

lpszNewItem
指定新功能表項的內容。 nFlags 可用來以下列方式解譯 lpszNewItem ：

`nFlags`	解譯 `lpszNewItem`
`MF_OWNERDRAW`	包含應用程式提供的32位值，應用程式可用來維護與功能表項相關聯的其他數據。這個 32 位值可供和訊息所提供`WM_MEASUREITEMWM_DRAWITEM`結構成員中的`itemData`應用程式使用。這些訊息會在功能表項一開始顯示或變更時傳送。
`MF_STRING`	包含以 Null 結尾字串的長指標。這是預設解譯。
`MF_SEPARATOR`	`lpszNewItem`參數會被忽略（不需要）。

pBmp
CBitmap指向將做為功能表項的物件。

傳回值

如果函式成功則為非零，否則為 0。

備註

應用程式可以在中 nFlags設定值，以指定功能表項的狀態。

每當視窗內的選單變更（無論是否顯示視窗），應用程式都應該呼叫 CWnd::DrawMenuBar。

當指定快捷功能表時 nIDNewItem ，它會成為插入該功能表的一部分。如果該功能表終結，插入的功能表也會被終結。插入的功能表應該與 CMenu 物件中斷連結，以避免衝突。

如果作用中的多個文檔介面（MDI）子視窗最大化，而且應用程式會呼叫此函式並指定 MF_BYPOSITION 旗標，將快顯功能表插入 MDI 應用程式的功能表中，則選單會插入離預期更遠的位置。這是因為使用中 MDI 子視窗的 [控制單] 選單會插入 MDI 框架視窗選單列的第一個位置。若要正確定位功能表，應用程式必須將1新增至原本會使用的位置值。應用程式可以使用訊息來判斷目前作用中的 WM_MDIGETACTIVE 子視窗是否最大化。

範例

// CMainFrame::OnChangeFileMenu() is a menu command handler for
// CMainFrame class, which in turn is a CFrameWnd-derived class.
// It modifies the File menu by inserting, removing and renaming
// some menu items. Other operations include associating a context
// help id and setting default menu item to the File menu.
// CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnChangeFileMenu()
{
   // Get the menu from the application window.
   CMenu *mmenu = GetMenu();

   // Look for "File" menu.
   int pos = FindMenuItem(mmenu, _T("&File"));
   if (pos == -1)
      return;

   // Remove "New" menu item from the File menu.
   CMenu *submenu = mmenu->GetSubMenu(pos);
   pos = FindMenuItem(submenu, _T("&New\tCtrl+N"));
   if (pos > -1)
      submenu->RemoveMenu(pos, MF_BYPOSITION);

   // Look for "Open" menu item from the File menu. Insert a new
   // menu item called "Close" right after the "Open" menu item.
   // ID_CLOSEFILE is the command id for the "Close" menu item.
   pos = FindMenuItem(submenu, _T("&Open...\tCtrl+O"));
   if (pos > -1)
      submenu->InsertMenu(pos + 1, MF_BYPOSITION, ID_CLOSEFILE, _T("&Close"));

   // Rename menu item "Exit" to "Exit Application".
   pos = FindMenuItem(submenu, _T("E&xit"));
   if (pos > -1)
   {
      UINT id = submenu->GetMenuItemID(pos);
      submenu->ModifyMenu(id, MF_BYCOMMAND, id, _T("E&xit Application"));
   }

   // Associate a context help ID with File menu, if one is not found.
   // ID_FILE_CONTEXT_HELPID is the context help ID for the File menu
   // that is defined in resource file.
   if (submenu->GetMenuContextHelpId() == 0)
      submenu->SetMenuContextHelpId(ID_FILE_CONTEXT_HELPID);

   // Set "Open" menu item as the default menu item for the File menu,
   // if one is not found. So, when a user double-clicks the File
   // menu, the system sends a command message to the menu's owner
   // window and closes the menu as if the File\Open command item had
   // been chosen.
   if (submenu->GetDefaultItem(GMDI_GOINTOPOPUPS, TRUE) == -1)
   {
      pos = FindMenuItem(submenu, _T("&Open...\tCtrl+O"));
      submenu->SetDefaultItem(pos, TRUE);
   }
}

// FindMenuItem() will find a menu item string from the specified
// popup menu and returns its position (0-based) in the specified
// popup menu. It returns -1 if no such menu item string is found.
int FindMenuItem(CMenu *Menu, LPCTSTR MenuString)
{
   ASSERT(Menu);
   ASSERT(::IsMenu(Menu->GetSafeHmenu()));

   int count = Menu->GetMenuItemCount();
   for (int i = 0; i < count; i++)
   {
      CString str;
      if (Menu->GetMenuString(i, str, MF_BYPOSITION) &&
          str.Compare(MenuString) == 0)
         return i;
   }

   return -1;
}

`CMenu::InsertMenuItem`

在功能表中的指定位置插入新的功能表項。

BOOL InsertMenuItem(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

參數

uItem
請參閱 Windows SDK 中的 InsertMenuItem 描述uItem。

lpMenuItemInfo
請參閱 Windows SDK 中的 InsertMenuItem 描述lpmii。

fByPos
請參閱 Windows SDK 中的 InsertMenuItem 描述fByPosition。

備註

此函式會 InsertMenuItem包裝 Windows SDK 中所述的。

`CMenu::LoadMenu`

從應用程式的可執行檔載入功能表資源，並將它附加至 CMenu 物件。

BOOL LoadMenu(LPCTSTR lpszResourceName);
BOOL LoadMenu(UINT nIDResource);

參數

lpszResourceName
指向包含要載入之功能表資源名稱的 Null 終止字串。

nIDResource
指定要載入之功能表資源的功能表標識碼。

傳回值

如果已成功載入功能表資源，則為非零;否則為 0。

備註

結束之前，如果功能表未指派給視窗，應用程式必須釋放與功能表相關聯的系統資源。應用程式會藉由呼叫 DestroyMenu 成員函式來釋放功能表。

範例

// CMainFrame::OnReplaceMenu() is a menu command handler for CMainFrame
// class, which in turn is a CFrameWnd-derived class. It loads a new
// menu resource and replaces the SDI application window's menu bar with
// this new menu. CMainFrame is a CFrameWnd-derived class.
void CMainFrame::OnReplaceMenu()
{
   // Load the new menu.
   m_ShortMenu.LoadMenu(IDR_SHORT_MENU);
   ASSERT(m_ShortMenu);

   // Remove and destroy the old menu
   SetMenu(NULL);
   ::DestroyMenu(m_hMenuDefault);

   // Add the new menu
   SetMenu(&m_ShortMenu);

   // Assign default menu
   m_hMenuDefault = m_ShortMenu.GetSafeHmenu(); // or m_ShortMenu.m_hMenu;
}

`CMenu::LoadMenuIndirect`

從記憶體中的功能表範本載入資源，並將其附加至 CMenu 物件。

BOOL LoadMenuIndirect(const void* lpMenuTemplate);

參數

lpMenuTemplate
指向功能表範本（這是單 MENUITEMTEMPLATEHEADER 一結構和一或多個 MENUITEMTEMPLATE 結構的集合）。如需這兩個結構的詳細資訊，請參閱 Windows SDK。

傳回值

如果已成功載入功能表資源，則為非零;否則為 0。

備註

功能表範本是標頭，後面接著一或多個 MENUITEMTEMPLATE 結構的集合，每個結構可能包含一或多個功能表項和快捷功能表。

版本號碼應該是 0。

旗 mtOption 標應該包含 MF_END 快顯清單中的最後一個專案，以及主清單中的最後一個專案。如需其他旗標， AppendMenu 請參閱成員函式。 mtId在中mtOption指定時MF_POPUP，必須省略 MENUITEMTEMPLATE 結構中的成員。

配置給 MENUITEMTEMPLATE 結構的空間必須夠大，才能 mtString 包含功能表項的名稱做為 Null 終止字串。

結束之前，如果功能表未指派給視窗，應用程式必須釋放與功能表相關聯的系統資源。應用程式會藉由呼叫 DestroyMenu 成員函式來釋放功能表。

範例

// CMainFrame::OnLoadMenuIndirect() is a menu command handler for
// CMainFrame class, which in turn is a CFrameWnd-derived class. It
// shows how to use LoadMenuIndirect() to load a resource from a
// menu template in memory.
void CMainFrame::OnLoadMenuIndirect()
{
   // For simplicity, allocate 500 bytes from stack. May use
   // GlobalAlloc() to allocate memory bytes from heap.
   BYTE milist[500];
   memset(milist, 0, 500);
   int bytes_left = sizeof(milist);

   // Fill up the MENUITEMTEMPLATEHEADER structure.
   MENUITEMTEMPLATEHEADER *mheader = (MENUITEMTEMPLATEHEADER*)milist;
   mheader->versionNumber = 0;
   mheader->offset = 0;

   int bytes_used = sizeof(MENUITEMTEMPLATEHEADER);
   bytes_left -= bytes_used;

   // Add the following menu items to menu bar:
   // File     Edit
   //   Exit     Copy
   //            Paste
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&File", 0,
                             TRUE, FALSE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"E&xit",
                             ID_APP_EXIT, FALSE, TRUE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Edit", 0,
                             TRUE, TRUE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Copy",
                             ID_EDIT_COPY, FALSE, FALSE);
   bytes_left -= bytes_used;
   bytes_used += AddMenuItem(milist + bytes_used, bytes_left, L"&Paste",
                             ID_EDIT_PASTE, FALSE, TRUE);
   bytes_left -= bytes_used;

   // Load resource from a menu template in memory.
   ASSERT(m_IndiMenu.LoadMenuIndirect(milist));

   // Remove and destroy old menu
   SetMenu(NULL);
   ::DestroyMenu(m_hMenuDefault);

   // Add new menu.
   SetMenu(&m_IndiMenu);

   // Assign default menu
   m_hMenuDefault = m_IndiMenu.m_hMenu;
}

// This is a helper function for adding a menu item (either a popup
// or command item) to the specified menu template.
//
//    MenuTemplate  - pointer to a menu template
//    TemplateBytes - space remaining in MenuTemplate
//    MenuString    - string for the menu item to be added
//    MenuID        - id for the command item. Its value is ignored if
//                    IsPopup is TRUE.
//    IsPopup       - TRUE for popup menu (or submenu); FALSE for command
//                    item
//    LastItem      - TRUE if MenuString is the last item for the popup;
//                    FALSE otherwise.
UINT AddMenuItem(LPVOID MenuTemplate, int TemplateBytes, WCHAR *MenuString,
                 WORD MenuID, BOOL IsPopup, BOOL LastItem)
{
   MENUITEMTEMPLATE *mitem = (MENUITEMTEMPLATE*)MenuTemplate;

   UINT bytes_used = 0;
   if (IsPopup) // for popup menu
   {
      if (LastItem)
         mitem->mtOption = MF_POPUP | MF_END;
      else
         mitem->mtOption = MF_POPUP;
      bytes_used += sizeof(mitem->mtOption);

      mitem = (MENUITEMTEMPLATE*)((BYTE*)MenuTemplate + bytes_used);
      // a popup doesn't have mtID!!!

      TemplateBytes -= bytes_used;
      wcscpy_s((WCHAR*)mitem, TemplateBytes / sizeof(WCHAR), MenuString);
      bytes_used += (UINT)(sizeof(WCHAR) * (wcslen(MenuString) + 1)); // include '\0'
   }
   else // for command item
   {
      mitem->mtOption = LastItem ? MF_END : 0;
      mitem->mtID = MenuID;
      TemplateBytes -= bytes_used;
      wcscpy_s(mitem->mtString, TemplateBytes / sizeof(WCHAR), MenuString);
      bytes_used += (UINT)(sizeof(mitem->mtOption) + sizeof(mitem->mtID) +
                           sizeof(WCHAR) * (wcslen(MenuString) + 1)); // include '\0'
   }

   return bytes_used;
}

`CMenu::m_hMenu`

指定 HMENU 附加至 CMenu 物件的 Windows 功能表句柄。

HMENU m_hMenu;

範例

請參閱 CMenu::LoadMenu 的範例。

`CMenu::MeasureItem`

建立具有擁有者繪製樣式的功能表時，由架構呼叫。

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

參數

lpMeasureItemStruct
結構的指標 MEASUREITEMSTRUCT 。

備註

根據預設，此成員函式不會執行任何動作。覆寫此成員函式並 MEASUREITEMSTRUCT 填入結構，以通知 Windows 功能表的維度。

如需結構的描述，MEASUREITEMSTRUCT請參閱 CWnd::OnMeasureItem 。

範例

下列程式代碼來自 MFC CTRLTEST 範例：

// Override MeasureItem() to return the size of the menu item.
// CColorMenu is a CMenu-derived class.

#define COLOR_BOX_WIDTH 20
#define COLOR_BOX_HEIGHT 20

void CColorMenu::MeasureItem(LPMEASUREITEMSTRUCT lpMIS)
{
   // all items are of fixed size
   lpMIS->itemWidth = COLOR_BOX_WIDTH;
   lpMIS->itemHeight = COLOR_BOX_HEIGHT;
}

`CMenu::ModifyMenu`

變更位於所 nPosition指定位置的現有功能表項。

BOOL ModifyMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem = 0,
    LPCTSTR lpszNewItem = NULL);

BOOL ModifyMenu(
    UINT nPosition,
    UINT nFlags,
    UINT_PTR nIDNewItem,
    const CBitmap* pBmp);

參數

nPosition
指定要變更的功能表項。 nFlags參數可用來以下列方式解譯nPosition：

`nFlags`	解譯 `nPosition`
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

nFlags
指定解譯方式 nPosition ，並提供功能表項變更的相關信息。如需可設定的旗標清單，請參閱 AppendMenu 成員函式。

nIDNewItem
指定已修改功能表項的命令標識碼，如果 nFlags 設定為 MF_POPUP，則為快捷功能表的功能表句柄（HMENU）。如果 nFlags 設定為 MF_SEPARATOR，則會nIDNewItem忽略參數（不需要）。

lpszNewItem
指定新功能表項的內容。 nFlags參數可用來以下列方式解譯lpszNewItem：

`nFlags`	解譯 `lpszNewItem`
`MF_OWNERDRAW`	包含應用程式提供的32位值，應用程式可用來維護與功能表項相關聯的其他數據。當應用程式處理 `MF_MEASUREITEM` 和 `MF_DRAWITEM`時，可以使用這個32位值。
`MF_STRING`	包含 Null 終止字串或 `CString`的長指標。
`MF_SEPARATOR`	`lpszNewItem`參數會被忽略（不需要）。

pBmp
CBitmap指向將做為功能表項的物件。

傳回值

如果函式成功則為非零，否則為 0。

備註

應用程式會在中 nFlags設定值，以指定功能表項的新狀態。如果此函式會取代與功能表項相關聯的快捷功能表，它會終結舊的快捷功能表，並釋放快捷功能表所使用的記憶體。

每當視窗內的選單變更（無論是否顯示視窗），應用程式都應該呼叫 CWnd::DrawMenuBar。若要變更現有功能表項的屬性，使用 CheckMenuItem 和 EnableMenuItem 成員函式會更快。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::operator HMENU`

使用此運算符來擷取物件的句柄 CMenu 。

operator HMENU() const;

傳回值

如果成功，則為物件的句柄 CMenu ， NULL否則為。

備註

您可以使用句柄直接呼叫 Windows API。

`CMenu::operator !=`

判斷兩個功能表在邏輯上是否不相等。

BOOL operator!=(const CMenu& menu) const;

參數

menu
要 CMenu 比較的物件。

備註

測試左側的功能表物件是否不等於右側的功能表物件。

`CMenu::operator ==`

判斷兩個功能表在邏輯上是否相等。

BOOL operator==(const CMenu& menu) const;

參數

menu
要 CMenu 比較的物件。

備註

測試左側的功能表物件是否等於右邊的功能表物件（值而言 HMENU ）。

`CMenu::RemoveMenu`

從功能表刪除具有相關聯快捷功能表的功能表項。

BOOL RemoveMenu(
    UINT nPosition,
    UINT nFlags);

參數

nPosition
指定要移除的功能表項。 nFlags參數可用來以下列方式解譯nPosition：

`nFlags`	解譯 `nPosition`
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

nFlags
指定解譯方式 nPosition 。

傳回值

如果函式成功則為非零，否則為 0。

備註

它不會終結快捷功能表的句柄，因此可以重複使用功能表。呼叫此函式之前，應用程式可能會呼叫 GetSubMenu 成員函式來擷取快顯 CMenu 物件以供重複使用。

每當視窗內所在的選單變更（無論是否顯示視窗），應用程式都必須呼叫 CWnd::DrawMenuBar。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::SetDefaultItem`

設定指定功能表的預設功能表項。

BOOL SetDefaultItem(
    UINT uItem,
    BOOL fByPos = FALSE);

參數

uItem
新預設功能表項的識別碼或位置，或 - 1 代表沒有預設專案。此參數的意義取決於的值 fByPos。

fByPos
值，指定的意義 uItem。如果此參數為 FALSE， uItem 則為功能表項標識碼。否則，它是功能表項位置。

傳回值

如果函式成功，則傳回非零的值。如果此函式失敗，則傳回值為零。若要取得擴充錯誤資訊，請使用 Win32 函式 GetLastError，如 Windows SDK 中所述。

備註

此成員函式會實作 Win32 函式 SetMenuDefaultItem 的行為，如 Windows SDK 中所述。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::SetMenuContextHelpId`

將內容說明標識碼與 CMenu產生關聯。

BOOL SetMenuContextHelpId(DWORD dwContextHelpId);

參數

dwContextHelpId
要與 CMenu產生關聯的內容說明標識碼。

傳回值

如果成功，則為非零;否則為 0

備註

選單中的所有項目都會共用此識別碼，無法將說明內容識別碼附加至個別選單項。

範例

請參閱 CMenu::InsertMenu 的範例。

`CMenu::SetMenuInfo`

設定功能表的資訊。

BOOL SetMenuInfo(LPCMENUINFO lpcmi);

參數

lpcmi
結構的指標 MENUINFO ，其中包含功能表的資訊。

傳回值

如果函式成功，則傳回值為非零;否則，傳回值為零。

備註

呼叫此函式來設定功能表的特定資訊。

`CMenu::SetMenuItemBitmaps`

將指定的點陣圖與功能表項產生關聯。

BOOL SetMenuItemBitmaps(
    UINT nPosition,
    UINT nFlags,
    const CBitmap* pBmpUnchecked,
    const CBitmap* pBmpChecked);

參數

nPosition
指定要變更的功能表項。 nFlags參數可用來以下列方式解譯nPosition：

`nFlags`	nPosition 的解譯
`MF_BYCOMMAND`	指定參數會提供現有功能表項的命令標識碼。如果兩者 `MF_BYCOMMAND` 都未設定， `MF_BYPOSITION` 則為預設值。
`MF_BYPOSITION`	指定參數提供現有功能表項的位置。第一個項目位於位置0。

nFlags
指定解譯方式 nPosition 。

pBmpUnchecked
指定要用於未核取之功能表項的點陣圖。

pBmpChecked
指定要用於核取之功能表項的點陣圖。

傳回值

如果函式成功則為非零，否則為 0。

備註

無論功能表項是否已核取或取消核取，Windows 會在功能表項旁邊顯示適當的點陣圖。

pBmpUnchecked如果或 pBmpChecked 為 NULL，則 Windows 不會在對應屬性的功能表項旁邊顯示任何專案。如果這兩個參數都是 NULL，則 Windows 會在檢查專案時使用預設複選標記，並在取消核取專案時移除複選標記。

當功能表終結時，不會終結這些位圖;應用程式必須終結它們。

Windows GetMenuCheckMarkDimensions 函式會擷取用於功能表項的預設複選標記維度。應用程式會使用這些值來判斷此函式所提供位圖的適當大小。取得大小、建立您的點陣圖，然後加以設定。

範例

// The code fragment below is from CMainFrame::OnCreate and shows
// how to associate bitmaps with the "Bitmap" menu item.
// Whether the "Bitmap" menu item is checked or unchecked, Windows
// displays the appropriate bitmap next to the menu item. Both
// IDB_CHECKBITMAP and IDB_UNCHECKBITMAP bitmaps are loaded
// in OnCreate() and destroyed in the destructor of CMainFrame class.
// CMainFrame is a CFrameWnd-derived class.

// Load bitmaps from resource. Both m_CheckBitmap and m_UnCheckBitmap
// are member variables of CMainFrame class of type CBitmap.
ASSERT(m_CheckBitmap.LoadBitmap(IDB_CHECKBITMAP));
ASSERT(m_UnCheckBitmap.LoadBitmap(IDB_UNCHECKBITMAP));

// Associate bitmaps with the "Bitmap" menu item.
CMenu *mmenu = GetMenu();
CMenu *submenu = mmenu->GetSubMenu(4);
ASSERT(submenu->SetMenuItemBitmaps(ID_MENU_BITMAP, MF_BYCOMMAND,
                                   &m_CheckBitmap, &m_UnCheckBitmap));

// This code fragment is taken from CMainFrame::~CMainFrame

// Destroy the bitmap objects if they are loaded successfully
// in OnCreate().
if (m_CheckBitmap.m_hObject)
   m_CheckBitmap.DeleteObject();

if (m_UnCheckBitmap.m_hObject)
   m_UnCheckBitmap.DeleteObject();

`CMenu::SetMenuItemInfo`

變更功能表項的相關信息。

BOOL SetMenuItemInfo(
    UINT uItem,
    LPMENUITEMINFO lpMenuItemInfo,
    BOOL fByPos = FALSE);

參數

uItem
請參閱 Windows SDK 中的 SetMenuItemInfo 描述uItem。

lpMenuItemInfo
請參閱 Windows SDK 中的 SetMenuItemInfo 描述lpmii。

fByPos
請參閱 Windows SDK 中的 SetMenuItemInfo 描述fByPosition。

備註

此函式會 SetMenuItemInfo包裝 Windows SDK 中所述的。

`CMenu::TrackPopupMenu`

在指定的位置顯示浮動快捷功能表，並追蹤彈出視窗功能表上的項目選取範圍。

BOOL TrackPopupMenu(
    UINT nFlags,
    int x,
    int y,
    CWnd* pWnd,
    LPCRECT lpRect = 0);

參數

nFlags
指定螢幕位置和滑鼠位置旗標。如您需要可用旗標的清單，請參閱 TrackPopupMenu 。

x
指定快捷選單螢幕座標中的水準位置。視參數的值 nFlags 而定，功能表可以靠左對齊、靠右對齊或置中相對於這個位置。

y
指定畫面上功能表頂端的垂直位置。

pWnd
識別擁有快捷功能表的視窗。即使已指定旗標，TPM_NONOTIFY這個參數也不能NULL是。此視窗會從功能表接收所有 WM_COMMAND 訊息。在 Windows 3.1 版和更新版本中，視窗在傳回之前TrackPopupMenu不會接收WM_COMMAND訊息。在 Windows 3.0 中，視窗會在 WM_COMMAND 傳回之前 TrackPopupMenu 接收訊息。

lpRect
忽略。

傳回值

這個方法會傳回在 Windows SDK 中呼叫 TrackPopupMenu 的結果。

備註

浮動彈出視窗功能表可以在畫面上的任何位置出現。

範例

// The code fragment shows how to get the File menu from the
// application window and displays it as a floating popup menu
// when the right mouse button is clicked in view.
// CMdiView is a CView-derived class.
void CMdiView::OnRButtonDown(UINT nFlags, CPoint point)
{
   CView::OnRButtonDown(nFlags, point);

   CMenu *menu_bar = AfxGetMainWnd()->GetMenu();
   CMenu *file_menu = menu_bar->GetSubMenu(0);
   ASSERT(file_menu);

   ClientToScreen(&point);
   file_menu->TrackPopupMenu(TPM_LEFTALIGN | TPM_RIGHTBUTTON, point.x,
                             point.y, this);
}

`CMenu::TrackPopupMenuEx`

在指定的位置顯示浮動快捷功能表，並追蹤彈出視窗功能表上的項目選取範圍。

BOOL TrackPopupMenuEx(
    UINT fuFlags,
    int x,
    int y,
    CWnd* pWnd,
    LPTPMPARAMS lptpm);

參數

fuFlags
指定擴充功能表的各種函式。如需所有值及其意義的清單，請參閱 TrackPopupMenuEx。

x
指定快捷選單螢幕座標中的水準位置。

y
指定畫面上功能表頂端的垂直位置。

pWnd
擁有快捷功能表的視窗指標，以及從建立的功能表接收訊息。這個視窗可以是目前應用程式的任何視窗，但不能是 NULL。如果您在參數中fuFlags指定 TPM_NONOTIFY ，函式不會將任何訊息傳送至 pWnd。函式必須針對所 pWnd 指向的視窗傳回，才能接收 WM_COMMAND 訊息。

lptpm
TPMPARAMS結構指標，指定功能表不應重疊的畫面區域。這個參數可以是 NULL。

傳回值

如果您在參數中fuFlags指定 TPM_RETURNCMD ，傳回值就是使用者所選取專案的功能表項識別碼。如果使用者取消功能表而不進行選取，或發生錯誤，則傳回值為0。

如果您未在參數中fuFlags指定 TPM_RETURNCMD ，如果函式成功，則傳回值為非零值，如果函式失敗則為 0。若要取得延伸錯誤資訊，請呼叫 GetLastError。

備註

浮動彈出視窗功能表可以在畫面上的任何位置出現。如需建立快捷選單時處理錯誤的詳細資訊，請參閱 TrackPopupMenuEx。

另請參閱

MFC 範例 CTRLTEST
MFC 範例 DYNAMENU
CObject 類
 階層架構圖表

共用方式為

CMenu 類別

語法

成員

公用建構函式

公用方法

公用運算子

公用資料成員

備註

繼承階層架構

需求

CMenu::AppendMenu

參數

傳回值

備註

範例

CMenu::Attach

參數

傳回值

備註

範例

CMenu::CheckMenuItem

參數

傳回值

備註

範例

CMenu::CheckMenuRadioItem

參數

傳回值

備註

範例

CMenu::CMenu

備註

CMenu::CreateMenu

傳回值

備註

範例

CMenu::CreatePopupMenu

傳回值

備註

範例

CMenu::DeleteMenu

參數

傳回值

備註

範例

CMenu::DeleteTempMap

備註

範例

CMenu::DestroyMenu

傳回值

備註

範例

CMenu::Detach

傳回值

備註

範例

CMenu::DrawItem

參數

備註

範例

CMenu::EnableMenuItem

參數

傳回值

備註

範例

CMenu::FromHandle

參數

傳回值

備註

範例

CMenu::GetDefaultItem

參數

傳回值

備註

範例

CMenu::GetMenuContextHelpId

傳回值

範例

CMenu::GetMenuInfo

`CMenu` 類別

`CMenu::AppendMenu`

`CMenu::Attach`

`CMenu::CheckMenuItem`

`CMenu::CheckMenuRadioItem`

`CMenu::CMenu`

`CMenu::CreateMenu`

`CMenu::CreatePopupMenu`

`CMenu::DeleteMenu`

`CMenu::DeleteTempMap`

`CMenu::DestroyMenu`

`CMenu::Detach`

`CMenu::DrawItem`

`CMenu::EnableMenuItem`

`CMenu::FromHandle`

`CMenu::GetDefaultItem`

`CMenu::GetMenuContextHelpId`

`CMenu::GetMenuInfo`

`CMenu::GetMenuItemCount`

`CMenu::GetMenuItemID`

`CMenu::GetMenuItemInfo`

`CMenu::GetMenuState`

`CMenu::GetMenuString`

`CMenu::GetSafeHmenu`

`CMenu::GetSubMenu`

`CMenu::InsertMenu`

`CMenu::InsertMenuItem`

`CMenu::LoadMenu`

`CMenu::LoadMenuIndirect`

`CMenu::m_hMenu`

`CMenu::MeasureItem`

`CMenu::ModifyMenu`

`CMenu::operator HMENU`

`CMenu::operator !=`

`CMenu::operator ==`

`CMenu::RemoveMenu`