Função ExtTextOutA (wingdi.h)

Artigo
03/08/2023

A função ExtTextOut desenha texto usando a fonte, a cor da tela de fundo e a cor do texto selecionadas no momento. Opcionalmente, você pode fornecer dimensões a serem usadas para recorte, opaquing ou ambos.

Sintaxe

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

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 usado para posicionar a cadeia de caracteres.

[in] y

A coordenada y, em coordenadas lógicas, do ponto de referência usado para posicionar a cadeia de caracteres.

[in] options

Especifica como usar o retângulo definido pelo aplicativo. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
ETO_CLIPPED	O texto será recortado no retângulo.
ETO_GLYPH_INDEX	A matriz lpString refere-se a uma matriz retornada de GetCharacterPlacement e deve ser analisada diretamente pela GDI, pois nenhum processamento específico de linguagem adicional é necessário. A indexação de glifo só se aplica a fontes TrueType, mas o sinalizador pode ser usado para fontes de bitmap e vetor para indicar que nenhum processamento de idioma adicional é necessário e a GDI deve processar a cadeia de caracteres diretamente. Observe que todos os índices de glifo são valores de 16 bits, embora a cadeia de caracteres seja considerada uma matriz de valores de 8 bits para fontes de varredura. Para ExtTextOutW, os índices de glifo são salvos em um metarquivo. No entanto, para exibir os caracteres corretos, o metarquivo deve ser reproduzido usando a mesma fonte. Para ExtTextOutA, os índices de glifo não são salvos.
ETO_IGNORELANGUAGE	Reservado para uso do sistema. Se um aplicativo definir esse sinalizador, ele perderá o suporte a scripts internacionais e, em alguns casos, poderá não exibir nenhum texto.
ETO_NUMERICSLATIN	Para exibir números, use dígitos europeus.
ETO_NUMERICSLOCAL	Para exibir números, use dígitos apropriados para a localidade.
ETO_OPAQUE	A cor da tela de fundo atual deve ser usada para preencher o retângulo.
ETO_PDY	Quando isso é definido, a matriz apontada por lpDx contém pares de valores. O primeiro valor de cada par é, como de costume, a distância entre as origens das células de caractere adjacentes, mas o segundo valor é o deslocamento ao longo da direção vertical da fonte.
ETO_RTLREADING	Edição de idioma do Oriente Médio do Windows: Se esse valor for especificado e uma fonte hebraica ou árabe for selecionada no contexto do dispositivo, a cadeia de caracteres será gerada usando a ordem de leitura da direita para a esquerda. Se esse valor não for especificado, a cadeia de caracteres será gerada na ordem da esquerda para a direita. O mesmo efeito pode ser obtido definindo o valor TA_RTLREADING em SetTextAlign. Esse valor é preservado para compatibilidade com versões anteriores.

Os valores ETO_GLYPH_INDEX e ETO_RTLREADING não podem ser usados juntos. Como ETO_GLYPH_INDEX implica que todo o processamento de idioma foi concluído, a função ignora o sinalizador ETO_RTLREADING, se também especificado.

[in] lprect

Um ponteiro para uma estrutura RECT opcional que especifica as dimensões, em coordenadas lógicas, de um retângulo usado para recorte, opaquing ou ambos.

[in] lpString

Um ponteiro para uma cadeia de caracteres que especifica o texto a ser desenhado. A cadeia de caracteres não precisa ser terminada em zero, pois cbCount especifica o comprimento da cadeia de caracteres.

[in] c

O comprimento da cadeia de caracteres apontada por lpString.

Esse valor não pode exceder 8192.

[in] lpDx

Um ponteiro para uma matriz opcional de valores que indicam a distância entre as origens das células de caractere adjacentes. Por exemplo, as unidades lógicas lpDx[i] separam as origens da célula de caractere i e da célula de caracteres i + 1.

Retornar valor

Se a cadeia de caracteres for desenhada, o valor retornado será diferente de zero. No entanto, se a versão ANSI de ExtTextOut for chamada com ETO_GLYPH_INDEX, a função retornará TRUE mesmo que a função não faça nada.

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

Comentários

As configurações atuais de alinhamento de texto para o contexto de dispositivo especificado determinam como o ponto de referência é usado para posicionar o texto. As configurações de alinhamento de texto são recuperadas chamando a função GetTextAlign . As configurações de alinhamento de texto são alteradas 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.

Se o parâmetro lpDx for NULL, a função ExtTextOut usará o espaçamento padrão entre caracteres. As origens de célula de caractere e o conteúdo da matriz apontada pelo parâmetro lpDx são especificados em unidades lógicas. Uma origem de célula de caractere é definida como o canto superior esquerdo da célula de caracteres.

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 ExtTextOut para um contexto de dispositivo especificado. Quando esse sinalizador é definido, o sistema ignora os parâmetros X e Y em chamadas ExtTextOut subsequentes.

Para a versão ANSI do ExtTextOut, a matriz lpDx tem o mesmo número de valores INT que há bytes em lpString. Para caracteres DBCS, você pode acrescentar o dx nas entradas lpDx entre o byte inicial e o byte de trilha, desde que a soma dos dois bytes se soma ao dx desejado. Para caracteres DBCS com a versão Unicode de ExtTextOut, cada glifo Unicode obtém uma única entrada pdx .

Observe que os valores alpDx de GetTextExtentExPoint não são os mesmos que os valores lpDx para ExtTextOut. Para usar os valores alpDx no lpDx, primeiro você deve processá-los.

ExtTextOut usará Uniscribe quando necessário, resultando em fallback de fonte. O sinalizador ETO_IGNORELANGUAGE inibirá esse comportamento e não deverá ser passado.

Além disso, ExtTextOut executará o envio em lote interno de chamadas antes da transição para o modo kernel, mitigando algumas das preocupações de desempenho ao pesar o uso de PolyTextOut versus ExtTextOut.

Dica

ExtTextOut é altamente recomendável sobre PolyTextOut para desenvolvimento moderno devido à sua capacidade de lidar com a exibição de diferentes idiomas.

Exemplos

Para obter um exemplo, confira "Configurando fontes para Menu-Item cadeias de caracteres de texto" em Usando menus.

Observação

O cabeçalho wingdi.h define ExtTextOut 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