Função TextOutW (wingdi.h)

Artigo
03/08/2023

A função TextOut grava uma cadeia de caracteres no local especificado, usando a fonte, a cor da tela de fundo e a cor do texto selecionadas no momento.

Sintaxe

BOOL TextOutW(
  [in] HDC     hdc,
  [in] int     x,
  [in] int     y,
  [in] LPCWSTR lpString,
  [in] int     c
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo.

[in] x

A coordenada x, em coordenadas lógicas, do ponto de referência que o sistema usa para alinhar a cadeia de caracteres.

[in] y

A coordenada y, em coordenadas lógicas, do ponto de referência que o sistema usa para alinhar a cadeia de caracteres.

[in] lpString

Um ponteiro para a cadeia de caracteres a ser desenhada. A cadeia de caracteres não precisa ser terminada em zero, pois cchString especifica o comprimento da cadeia de caracteres.

[in] c

O comprimento da cadeia de caracteres apontada por lpString, em caracteres.

Valor retornado

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

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

Comentários

A interpretação do ponto de referência depende do modo de alinhamento de texto atual. Um aplicativo pode recuperar esse modo chamando a função GetTextAlign ; um aplicativo pode alterar esse modo chamando a função SetTextAlign . Você pode usar os valores a seguir para alinhamento de texto. Somente um sinalizador pode ser escolhido daqueles que afetam o alinhamento horizontal e vertical. Além disso, apenas um dos dois sinalizadores que alteram a posição atual pode ser escolhido.

Termo	Descrição
TA_BASELINE	O ponto de referência estará na linha base do texto.
TA_BOTTOM	O ponto de referência estará na borda inferior do retângulo delimitador.
TA_TOP	O ponto de referência estará na borda superior do retângulo delimitador.
TA_CENTER	O ponto de referência será alinhado horizontalmente com o centro do retângulo delimitador.
TA_LEFT	O ponto de referência estará na borda esquerda do retângulo delimitador.
TA_RIGHT	O ponto de referência estará na borda direita do retângulo delimitador.
TA_NOUPDATECP	A posição atual não é atualizada após cada chamada de saída de texto. O ponto de referência é passado para a função de saída de texto.
TA_RTLREADING	Edição de idioma do Oriente Médio do Windows: O texto é disposto na ordem de leitura da direita para a esquerda, em vez da ordem padrão da esquerda para a direita. Isso se aplica somente quando a fonte selecionada no contexto do dispositivo é hebraico ou árabe.
TA_UPDATECP	A posição atual é atualizada após cada chamada de saída de texto. A posição atual é usada como o ponto de referência.

Por padrão, a posição atual não é usada ou atualizada por essa função. No entanto, um aplicativo pode chamar a função SetTextAlign com o parâmetro fMode definido como TA_UPDATECP para permitir que o sistema use e atualize a posição atual sempre que o aplicativo chamar TextOut para um contexto de dispositivo especificado. Quando esse sinalizador é definido, o sistema ignora os parâmetros nXStart e nYStart em chamadas TextOut subsequentes.

Quando a função TextOut é colocada dentro de um colchete de caminho, o sistema gera um caminho para o texto TrueType que inclui cada caractere mais sua caixa de caracteres. A região gerada é a caixa de caracteres menos o texto, em vez do texto em si. Você pode obter a região delimitada pela estrutura de tópicos do texto TrueType definindo o modo de plano de fundo como transparente antes de colocar a função TextOut no colchete de caminho. Veja a seguir o código de exemplo que demonstra esse procedimento.


// Obtain the window's client rectangle 
GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode 
// to transparent, the region is the text itself 
// SetBkMode(hdc, TRANSPARENT); 

// Bracket begin a path 
BeginPath(hdc);

// Send some text out into the world 
TCHAR text[ ] = "Defenestration can be hazardous";
TextOut(hdc,r.left,r.top,text, ARRAYSIZE(text));

// Bracket end a path 
EndPath(hdc);

// Derive a region from that path 
SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath() 
// SelectClipRgn(hdc, PathToRegion(hdc)); 

// Fill the region with grayness 
FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

Exemplos

Para obter um exemplo, consulte Enumerando as fontes instaladas.

Observação

O cabeçalho wingdi.h define TextOut 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	wingdi.h (inclua Windows.h)
Biblioteca	Gdi32.lib
DLL	Gdi32.dll