Função ExtTextOutA (wingdi.h)

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 ser um ou mais 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 do GetCharacterPlacement e deve ser analisada diretamente pelo 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 raster. Para ExtTextOutW, os índices de glifo são salvos em um metafile. No entanto, para exibir os caracteres corretos, o metafilo 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, 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 linguagem do Oriente Médio do Windows: Se esse valor for especificado e uma fonte hebraica ou árabe estiver 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á saída na ordem da esquerda para a direita. O mesmo efeito pode ser obtido definindo o valor de 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 de 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 apontado 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 célula de caractere i + 1.

Valor de retorno

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

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

Observações

As configurações atuais de alinhamento de texto para o contexto do 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.

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.

 

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 apontado 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 reordenar o dx no lpDx entradas entre o byte do lead e o byte de trilha, desde que a soma dos dois bytes se adicione ao dx desejado. Para caracteres DBCS com a versão Unicode doExtTextOut , cada glifo Unicode obtém uma única entrada de pdx.

Observe que os valores alpDx de GetTextExtentExPoint não são os mesmos que os valores de lpDx paraextTextOut . Para usar os valores alpDx em 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 avaliar o uso de PolyTextOut versus ExtTextOut.

Ponta

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

Exemplos

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

Nota

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

RECT

SelectObject

SetBkColor

SetTextAlign

SetTextColor