CMenu::InsertMenu

[アーティクル]
08/09/2011

新しいメニュー項目を 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
直前に新しいメニュー項目が挿入される、メニュー項目を指定します。 nPosition の解釈は、次に挙げる nFlags の設定により決まります。

nFlags	nPosition の解釈
MF_BYCOMMAND	パラメーターを既存のメニュー項目のコマンド ID で指定することを示します。 MF_BYCOMMAND と MF_BYPOSITION がどちらも設定されていないときの既定の設定になります。
MF_BYPOSITION	パラメーターを既存のメニュー項目の位置で指定することを示します。最初の項目位置は 0 です。 nPosition が -1 のときは、新しいメニュー項目はメニューの最後に追加されます。

nFlags
新しいメニュー項目がメニューに追加されるときのそのメニュー項目の状態情報と nPosition の解釈のしかたを指定します。設定されるフラグの一覧は、「CMenu::AppendMenu」メンバー関数を参照してください。複数の値を指定するときは、ビットごとの OR 演算子を使って、MF_BYCOMMAND フラグまたは MF_BYPOSITION フラグと組み合わせてください。
nIDNewItem
新しいメニュー項目のコマンド ID を指定します。nFlags に MF_POPUP が設定されているときは、ポップアップメニューのメニューハンドル (HMENU) を指定します。 nFlags が MF_SEPARATOR に設定されているときは、パラメーター nIDNewItem は無視されます (必要ありません)。

lpszNewItem
新しいメニュー項目の内容を指定します。 lpszNewItem の解釈は、nFlags の設定状態により次のように変化します。

nFlags	lpszNewItem の解釈
MF_OWNERDRAW	アプリケーション提供の 32 ビットの値を保持します。この値は、アプリケーションがそのメニュー項目に割り当てる付加的なデータを管理するために使います。この 32 ビットの値は WM_MEASUREITEMメッセージと WM_DRAWITEM メッセージにより提供される構造体の itemData メンバーに格納され、アプリケーションで利用できます。これらのメッセージはメニュー項目が初期表示されたとき、または変更されたときに送られます。
MF_STRING	NULL で終わる文字列への long のポインターを保持します。これは既定です。
MF_SEPARATOR	パラメーター lpszNewItem は無視されます (必要ありません)。

pBmp
メニュー項目として使用される CBitmap オブジェクトへのポインター。

戻り値

正常終了した場合は 0 以外を返します。それ以外の場合は 0 を返します。

解説

nFlags に値を設定することにより、アプリケーションのメニュー項目の状態を指定できます。

ウィンドウにあるメニューが変更されたときは (ウィンドウが表示されているかどうかにかかわらず)、アプリケーションは CWnd::DrawMenuBar 関数を呼び出す必要があります。

nIDNewItem がポップアップメニューを示しているときは、ポップアップメニューは挿入先メニューの一部になります。挿入先メニューが破棄されたときは、挿入されたメニューも破棄されます。挿入されたメニューは、矛盾が起きないように CMenu オブジェクトから切り離します。

アクティブなマルチドキュメントインターフェイス (MDI: multiple document interface) の子ウィンドウが最大表示されていて、アプリケーションが、MF_BYPOSITION を指定してこの関数を使い、MDI のアプリケーションメニューにポップアップメニューを挿入したとき、メニューは希望する位置よりも 1 つ左側に挿入されます。この現象は、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;
}