`CMenu` 類別

發行項
06/16/2023

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 視窗的功能表設定為新的功能表、讓視窗重新繪製以反映功能表變更，並將功能表的擁有權傳遞至視窗。從物件卸離 HMENUCMenu 的呼叫 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_UNCHECKEDMF_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 中所述。請注意，在的 GetMenuItemInfo MFC 實作中，您不會使用功能表的控制碼。

範例

// 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 物件或指標所包裝的 NULLCMenu 。

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`