CMenu::InsertMenu

發行項
02/28/2013

插入新的功能表項目 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	指定參數指定現有的功能表項目的命令 ID。如果 MF_BYCOMMAND 和 MF_BYPOSITION 未設定，這是預設值。
MF_BYPOSITION	指定參數重新命名現有的功能表項目的位置。第一個項目在位置 0。如果 nPosition 是 1，則新的功能表項目附加至功能表的尾端。

nFlags
指定 nPosition 如何解譯並指定有關新功能表項目狀態資訊，在加入至功能表時。如需可以設定旗標的清單，請參閱 AppendMenu 成員函式。若要指定一個以上的值，請使用位元 OR 運算子組合成 MF_BYCOMMAND 或 MF_BYPOSITION 旗標。
nIDNewItem
指定新的功能表項目的命令 ID，或者，如果 nFlags 設為 MF_POPUP，功能表控制代碼 ()HMENU快顯功能表。 nIDNewItem 參數已忽略 (不需要)，如果 nFlags 設為 MF_SEPARATOR。

lpszNewItem
指定新的功能表項目的內容。 nFlags 可用來透過下列方式說明 lpszNewItem :

nFlags	lpszNewItem 的說明
MF_OWNERDRAW	包含應用程式可以使用維護其他資料與功能表項目中應用程式所提供的 32 位元值。這個值為 32 位元應用程式可在 WM_MEASUREITEM 和 WM_DRAWITEM 訊息提供結構的 itemData 成員。為功能表項目一開始顯示或變更時，這些訊息傳送。
MF_STRING	包含長指標 null 結尾的字串。這是預設解譯。
MF_SEPARATOR	lpszNewItem 參數已忽略 (不需要)。

pBmp
要用來做為功能表項目的 CBitmap 點的物件。

傳回值

如果不是零，則函式成功，則為 0。

備註

應用程式可以藉由將值指定功能表項目的狀態。 nFlags。

當在視窗變更的功能表 ( 視窗是否已經顯示)，應用程式應該呼叫 CWnd::DrawMenuBar。

當 nIDNewItem 指定快顯功能表時，它會變成控制項對於其插入的功能表。如果終結該功能表，也會終結插入的功能表。要從 CMenu 物件中斷連接已插入的功能表避免衝突。

如果現用 (MDI) 多重文件介面 (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;
}