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 usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
O texto será recortado no retângulo. |
|
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. |
|
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. |
|
Para exibir números, use dígitos europeus. |
|
Para exibir números, use dígitos apropriados para a localidade. |
|
A cor da tela de fundo atual deve ser usada para preencher o retângulo. |
|
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. |
|
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.
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 |