Função TextOutW (wingdi.h)

Artigo
11/20/2024

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 por zero, pois cchString especifica o comprimento da cadeia de caracteres.

[in] c

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

Valor de retorno

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

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

Observações

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.

Prazo	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 linguagem do Oriente Médio do Windows: O texto é disposto na ordem de leitura da direita para a esquerda, em oposição à ordem padrão da esquerda para a direita. Isso se aplica somente quando a fonte selecionada no contexto do dispositivo é hebraica 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 de nXStart e nYStart em chamadas textout de 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 entre a 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.

Nota

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 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	wingdi.h (inclua Windows.h)
biblioteca	Gdi32.lib
de DLL	Gdi32.dll

Consulte também

Funções de fonte e texto

fontes e visão geral de texto

GetTextAlign

SelectObject

SetBkColor

SetTextAlign

SetTextColor

tabbedTextOut

Compartilhar via