Função GetMenuStringW (winuser.h)

Artigo
11/20/2024

Copia a cadeia de caracteres de texto do item de menu especificado no buffer especificado.

Observação A função GetMenuString foi substituída. Use a função GetMenuItemInfo para recuperar o texto do item de menu.

Sintaxe

int GetMenuStringW(
  [in]            HMENU  hMenu,
  [in]            UINT   uIDItem,
  [out, optional] LPWSTR lpString,
  [in]            int    cchMax,
  [in]            UINT   flags
);

Parâmetros

[in] hMenu

Tipo: HMENU

Um identificador para o menu.

[in] uIDItem

Tipo: UINT

O item de menu a ser alterado, conforme determinado pelo parâmetro uFlag.

[out, optional] lpString

Tipo: LPTSTR

O buffer que recebe a cadeia de caracteres terminada em nulo. Se a cadeia de caracteres for maior ou maior que lpString, a cadeia de caracteres será truncada e o caractere nulo de terminação será adicionado. Se lpString for NULL, a função retornará o comprimento da cadeia de caracteres de menu.

[in] cchMax

Tipo: int

O comprimento máximo, em caracteres, da cadeia de caracteres a ser copiada. Se a cadeia de caracteres for maior que o máximo especificado no parâmetro nMaxCount, os caracteres extras serão truncados. Se nMaxCount for 0, a função retornará o comprimento da cadeia de caracteres de menu.

[in] flags

Tipo: UINT

Indica como o parâmetro uIDItem é interpretado. Esse parâmetro deve ser um dos seguintes valores.

Valor	Significado
MF_BYCOMMAND 0x00000000L	Indica que uIDItem fornece o identificador do item de menu. Se o sinalizador MF_BYCOMMAND nem MF_BYPOSITION não for especificado, o sinalizador MF_BYCOMMAND será o sinalizador padrão.
MF_BYPOSITION 0x00000400L	Indica que uIDItem fornece a posição relativa baseada em zero do item de menu.

Valor de retorno

Tipo: int

Se a função for bem-sucedida, o valor retornado especifica o número de caracteres copiados para o buffer, não incluindo o caractere nulo de encerramento.

Se a função falhar, o valor retornado será zero.

Se o item especificado não for do tipo MIIM_STRING ou MFT_STRING, o valor retornado será zero.

Observações

O parâmetro nMaxCount deve ser um maior que o número de caracteres na cadeia de caracteres de texto para acomodar o caractere nulo de terminação.

Se nMaxCount for 0, a função retornará o comprimento da cadeia de caracteres de menu.

Aviso de segurança

O parâmetro lpString é um buffer de TCHAR e nMaxCount é o comprimento da cadeia de caracteres de menu em caracteres. Dimensionar esses parâmetros incorretamente pode causar truncamento da cadeia de caracteres, levando a uma possível perda de dados.

Exemplos

Para obter um exemplo, consulte Criando aceleradores editáveis do usuário.

Nota

O cabeçalho winuser.h define GetMenuString 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-3 (introduzido no Windows 10, versão 10.0.14393)

Consulte também

Conceitual

GetMenuItemID

menus

de referência de

Compartilhar via