Função GetMenuStringA (winuser.h)

  • Artigo

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

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

Sintaxe

int GetMenuStringA(
  [in]            HMENU hMenu,
  [in]            UINT  uIDItem,
  [out, optional] LPSTR 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 tão longa 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 usar um dos valores a seguir.

Valor Significado
MF_BYCOMMAND
0x00000000L
 Indica que uIDItem fornece o identificador do item de menu. Se nem o sinalizador MF_BYCOMMAND nem MF_BYPOSITION 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.

Retornar valor

Tipo: int

Se a função tiver êxito, o valor retornado especificará o número de caracteres copiados para o buffer, sem incluir 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.

Comentários

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 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 pelo usuário.

Observação

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 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

Conceitual

GetMenuItemID

Menus

Referência