Função GetWindowTextA (winuser.h)

Artigo
08/27/2023

Copia o texto da barra de título da janela especificada (se tiver uma) em um buffer. Se a janela especificada for um controle, o texto do controle será copiado. No entanto, GetWindowText não pode recuperar o texto de um controle em outro aplicativo.

Sintaxe

int GetWindowTextA(
  [in]  HWND  hWnd,
  [out] LPSTR lpString,
  [in]  int   nMaxCount
);

Parâmetros

[in] hWnd

Digite: HWND

Um identificador para a janela ou controle que contém o texto.

[out] lpString

Tipo: LPTSTR

O buffer que receberá o texto. Se a cadeia de caracteres for tão longa ou maior que o buffer, a cadeia de caracteres será truncada e terminada com um caractere nulo.

[in] nMaxCount

Tipo: int

O número máximo de caracteres a serem copiados para o buffer, incluindo o caractere nulo. Se o texto exceder esse limite, ele será truncado.

Retornar valor

Tipo: int

Se a função for bem-sucedida, o valor retornado será o comprimento, em caracteres, da cadeia de caracteres copiada, sem incluir o caractere nulo de terminação. Se a janela não tiver nenhuma barra de título ou texto, se a barra de título estiver vazia ou se a janela ou o identificador de controle for inválido, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Essa função não pode recuperar o texto de um controle de edição em outro aplicativo.

Comentários

Se a janela de destino pertencer ao processo atual, GetWindowText fará com que uma mensagem de WM_GETTEXT seja enviada para a janela ou controle especificado. Se a janela de destino pertencer a outro processo e tiver um legenda, GetWindowText recuperará a janela legenda texto. Se a janela não tiver um legenda, o valor retornado será uma cadeia de caracteres nula. Este comportamento ocorre por design. Ele permite que os aplicativos chamem GetWindowText sem responder se o processo que possui a janela de destino não estiver respondendo. No entanto, se a janela de destino não estiver respondendo e pertencer ao aplicativo de chamada, GetWindowText fará com que o aplicativo de chamada não responda.

Para recuperar o texto de um controle em outro processo, envie uma mensagem WM_GETTEXT diretamente em vez de chamar GetWindowText.

Exemplos

O código de exemplo a seguir demonstra uma chamada para GetWindowTextA.

hwndCombo = GetDlgItem(hwndDlg, IDD_COMBO); 
cTxtLen = GetWindowTextLength(hwndCombo); 

// Allocate memory for the string and copy 
// the string into the memory. 

pszMem = (PSTR) VirtualAlloc((LPVOID) NULL, 
    (DWORD) (cTxtLen + 1), MEM_COMMIT, 
    PAGE_READWRITE); 
GetWindowText(hwndCombo, pszMem, 
    cTxtLen + 1);

Para ver este exemplo no contexto, consulte Enviando uma mensagem.

Observação

O cabeçalho winuser.h define GetWindowText 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-window-l1-1-4 (introduzido no Windows 10, versão 10.0.14393)