Função InsertMenuA (winuser.h)

Artigo
11/20/2024

Insere um novo item de menu em um menu, movendo outros itens para baixo no menu.

Observação A função InsertMenu foi substituída pela função InsertMenuItem. Você ainda pode usar InsertMenu, no entanto, se não precisar de nenhum dos recursos estendidos de InsertMenuItem.

Sintaxe

BOOL InsertMenuA(
  [in]           HMENU    hMenu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCSTR   lpNewItem
);

Parâmetros

[in] hMenu

Tipo: HMENU

Um identificador para o menu a ser alterado.

[in] uPosition

Tipo: UINT

O item de menu antes do qual o novo item de menu deve ser inserido, conforme determinado pelo parâmetro uFlags.

[in] uFlags

Tipo: UINT

Controla a interpretação do parâmetro uPosition e o conteúdo, a aparência e o comportamento do novo item de menu. Esse parâmetro deve incluir um dos seguintes valores necessários.

Valor	Significado
MF_BYCOMMAND 0x00000000L	Indica que o parâmetro uPosition fornece o identificador do item de menu. O sinalizador MF_BYCOMMAND será o padrão se nem o sinalizador MF_BYCOMMAND nem MF_BYPOSITION for especificado.
MF_BYPOSITION 0x00000400L	Indica que o parâmetro uPosition fornece a posição relativa baseada em zero do novo item de menu. Se uPosition for -1, o novo item de menu será acrescentado ao final do menu.

O parâmetro também deve incluir pelo menos um dos valores a seguir.

Valor	Significado
MF_BITMAP 0x00000004L	Usa um bitmap como o item de menu. O parâmetro lpNewItem contém um identificador para o bitmap.
MF_CHECKED 0x00000008L	Coloca uma marca de seleção ao lado do item de menu. Se o aplicativo fornecer bitmaps de marca de seleção (consulte SetMenuItemBitmaps), esse sinalizador exibirá o bitmap de marca de seleção ao lado do item de menu.
MF_DISABLED 0x00000002L	Desabilita o item de menu para que ele não possa ser selecionado, mas não o cinza.
MF_ENABLED 0x00000000L	Habilita o item de menu para que ele possa ser selecionado e restaurá-lo de seu estado esmaecido.
MF_GRAYED 0x00000001L	Desabilita o item de menu e o cinza para que ele não possa ser selecionado.
MF_MENUBARBREAK 0x00000020L	Funciona da mesma forma que o sinalizador MF_MENUBREAK para uma barra de menus. Para um menu suspenso, submenu ou menu de atalho, a nova coluna é separada da coluna antiga por uma linha vertical.
MF_MENUBREAK 0x00000040L	Coloca o item em uma nova linha (para barras de menus) ou em uma nova coluna (para um menu suspenso, submenu ou menu de atalho) sem separar colunas.
MF_OWNERDRAW 0x00000100L	Especifica que o item é um item desenhado pelo proprietário. Antes que o menu seja exibido pela primeira vez, a janela que possui o menu recebe uma mensagem WM_MEASUREITEM para recuperar a largura e a altura do item de menu. A mensagem WM_DRAWITEM é enviada para o procedimento de janela da janela do proprietário sempre que a aparência do item de menu deve ser atualizada.
MF_POPUP 0x00000010L	Especifica que o item de menu abre um menu suspenso ou submenu. O parâmetro uIDNewItem especifica um identificador para o menu suspenso ou submenu. Esse sinalizador é usado para adicionar um nome de menu a uma barra de menus ou a um item de menu que abre um submenu em um menu suspenso, submenu ou menu de atalho.
MF_SEPARATOR 0x00000800L	Desenha uma linha divisória horizontal. Esse sinalizador é usado apenas em um menu suspenso, submenu ou menu de atalho. A linha não pode ser esmaeçada, desabilitada ou realçada. Os parâmetros lpNewItem e uIDNewItem são ignorados.
MF_STRING 0x00000000L	Especifica que o item de menu é uma cadeia de caracteres de texto; o parâmetro lpNewItem é um ponteiro para a cadeia de caracteres.
MF_UNCHECKED 0x00000000L	Não coloca uma marca de seleção ao lado do item de menu (padrão). Se o aplicativo fornecer bitmaps de marca de seleção (consulte a função SetMenuItemBitmaps), esse sinalizador exibirá o bitmap claro ao lado do item de menu.

[in] uIDNewItem

Tipo: UINT_PTR

O identificador do novo item de menu ou, se o parâmetro uFlags tiver o sinalizador MF_POPUP definido, um identificador para o menu suspenso ou submenu.

[in, optional] lpNewItem

Tipo: LPCTSTR

O conteúdo do novo item de menu. A interpretação de lpNewItem depende se o parâmetro uFlags inclui o sinalizador MF_BITMAP, MF_OWNERDRAWou MF_STRING, da seguinte maneira.

Valor	Significado
MF_BITMAP 0x00000004L	Contém um identificador de bitmap.
MF_OWNERDRAW 0x00000100L	Contém um valor fornecido pelo aplicativo que pode ser usado para manter dados adicionais relacionados ao item de menu. O valor está no itemData membro da estrutura apontado pelo parâmetro lParam da mensagem WM_MEASUREITEM ou WM_DRAWITEM enviada quando o item de menu é criado ou sua aparência é atualizada.
MF_STRING 0x00000000L	Contém um ponteiro para uma cadeia de caracteres terminada em nulo (o padrão).

Valor de retorno

Tipo: BOOL

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Observações

O aplicativo deve chamar a função DrawMenuBar sempre que um menu for alterado, se o menu estiver em uma janela exibida.

Os seguintes grupos de sinalizadores não podem ser usados juntos:

MF_BYCOMMAND e MF_BYPOSITION
MF_DISABLED, MF_ENABLEDe MF_GRAYED
MF_BITMAP, MF_STRING, MF_OWNERDRAWe MF_SEPARATOR
MF_MENUBARBREAK e MF_MENUBREAK
MF_CHECKED e MF_UNCHECKED

Nota

O cabeçalho winuser.h define InsertMenu como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winuser.h (inclua Windows.h)
biblioteca	User32.lib
de DLL	User32.dll
conjunto de API	ext-ms-win-ntuser-menu-l1-1-0 (introduzido no Windows 8)