Compartilhar via


Função ModifyMenuA (winuser.h)

Altera um item de menu existente. Essa função é usada para especificar o conteúdo, a aparência e o comportamento do item de menu.

Nota A função ModifyMenu foi substituída pela função SetMenuItemInfo . No entanto, você ainda poderá usar ModifyMenu se não precisar de nenhum dos recursos estendidos de SetMenuItemInfo.
 

Sintaxe

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

Parâmetros

[in] hMnu

Tipo: HMENU

Um identificador para o menu a ser alterado.

[in] uPosition

Tipo: UINT

O item de menu a ser alterado, 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 item de menu. Esse parâmetro deve incluir um dos seguintes valores necessários.

Valor Significado
MF_BYCOMMAND
0x000000000L
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 item de 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
Places uma marca de marcar ao lado do item. Se o aplicativo fornecer bitmaps de marca marcar (consulte a função SetMenuItemBitmaps), esse sinalizador exibirá um bitmap selecionado ao lado do item de menu.
MF_DISABLED
0x00000002L
Desabilita o item de menu para que ele não possa ser selecionado, mas esse sinalizador não o esmaeça.
MF_ENABLED
0x000000000L
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
Places 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 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 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
0x000000000L
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
0x000000000L
Não coloca uma marca de marcar ao lado do item (o padrão). Se o aplicativo fornecer bitmaps de marca marcar (consulte a função SetMenuItemBitmaps), esse sinalizador exibirá um bitmap claro ao lado do item de menu.

[in] uIDNewItem

Tipo: UINT_PTR

O identificador do item de menu modificado 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 item de menu alterado. A interpretação desse parâmetro depende se o parâmetro uFlags inclui o sinalizador MF_BITMAP, MF_OWNERDRAW ou MF_STRING .

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

Retornar valor

Tipo: BOOL

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

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

Comentários

Se ModifyMenu substituir um item de menu que abre um menu suspenso ou submenu, a função destruirá o antigo menu suspenso ou submenu e liberará a memória usada por ele.

Para que os aceleradores de teclado funcionem com itens de menu desenhados pelo proprietário ou bitmap, o proprietário do menu deve processar a mensagem WM_MENUCHAR . Consulte Menus desenhados pelo proprietário e a mensagem de WM_MENUCHAR para obter mais informações.

O aplicativo deve chamar a função DrawMenuBar sempre que um menu for alterado, independentemente de o menu estar em uma janela exibida. Para alterar os atributos dos itens de menu existentes, é muito mais rápido usar as funções CheckMenuItem e EnableMenuItem .

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

  • MF_BYCOMMAND e MF_BYPOSITION
  • MF_DISABLED, MF_ENABLED e MF_GRAYED
  • MF_BITMAP, MF_STRING, MF_OWNERDRAW e MF_SEPARATOR
  • MF_MENUBARBREAK e MF_MENUBREAK
  • MF_CHECKED e MF_UNCHECKED

Exemplos

Para obter um exemplo, consulte Configurando fontes para Menu-Item cadeias de caracteres de texto.

Observação

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

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winuser.h (inclua Windows.h)
Biblioteca User32.lib
DLL User32.dll
Conjunto de APIs ext-ms-win-ntuser-menu-l1-1-3 (introduzido no Windows 10, versão 10.0.14393)

Confira também

Appendmenu

Checkmenuitem

Conceitual

Drawmenubar

Enablemenuitem

Menus

Referência

SetMenuItemBitmaps

Setmenuiteminfo