Compartilhar via


Função DrawTextExW (winuser.h)

A função DrawTextEx desenha texto formatado no retângulo especificado.

Sintaxe

int DrawTextExW(
  [in]      HDC              hdc,
  [in, out] LPWSTR           lpchText,
  [in]      int              cchText,
  [in, out] LPRECT           lprc,
  [in]      UINT             format,
  [in]      LPDRAWTEXTPARAMS lpdtp
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo no qual desenhar.

[in, out] lpchText

Um ponteiro para a cadeia de caracteres que contém o texto a ser desenhado. Se o parâmetro cchText for -1, a cadeia de caracteres deverá ser terminada em nulo.

Se dwDTFormat incluir DT_MODIFYSTRING, a função poderá adicionar até quatro caracteres adicionais a essa cadeia de caracteres. O buffer que contém a cadeia de caracteres deve ser grande o suficiente para acomodar esses caracteres extras.

[in] cchText

O comprimento da cadeia de caracteres apontada por lpchText. Se cchText for -1, o parâmetro lpchText será considerado um ponteiro para uma cadeia de caracteres terminada em nulo e DrawTextEx calculará a contagem de caracteres automaticamente.

[in, out] lprc

Um ponteiro para uma estrutura RECT que contém o retângulo, em coordenadas lógicas, em que o texto deve ser formatado.

[in] format

As opções de formatação. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
DT_BOTTOM
Justifica o texto na parte inferior do retângulo. Esse valor é usado apenas com o valor DT_SINGLELINE.
DT_CALCRECT
Determina a largura e a altura do retângulo. Se houver várias linhas de texto, DrawTextEx usará a largura do retângulo apontado pelo parâmetro lprc e estenderá a base do retângulo para associar a última linha de texto. Se houver apenas uma linha de texto, DrawTextEx modificará o lado direito do retângulo para que ele limite o último caractere na linha. Em ambos os casos, DrawTextEx retorna a altura do texto formatado, mas não desenha o texto.
DT_CENTER
Centraliza o texto horizontalmente no retângulo.
DT_EDITCONTROL
Duplica as características de exibição de texto de um controle de edição de várias linhas. Especificamente, a largura média do caractere é calculada da mesma maneira que para um controle de edição e a função não exibe uma última linha parcialmente visível.
DT_END_ELLIPSIS
Para texto exibido, substitui o final de uma cadeia de caracteres por reticências para que o resultado se ajuste ao retângulo especificado. Qualquer palavra (não no final da cadeia de caracteres) que ultrapasse os limites do retângulo é truncada sem reticências. A cadeia de caracteres não é modificada, a menos que o sinalizador DT_MODIFYSTRING seja especificado.

Compare com DT_PATH_ELLIPSIS e DT_WORD_ELLIPSIS.

DT_EXPANDTABS
Amplia os caracteres da guia. O número padrão de caracteres por guia é oito.
DT_EXTERNALLEADING
Inclui os principais de fonte externa na altura da linha. Normalmente, a esquerda externa não está incluída na altura de uma linha de texto.
DT_HIDEPREFIX
Ignora o caractere de prefixo e comercial (&) no texto. A letra a seguir não será sublinhada, mas outros caracteres de prefixo mnemônico ainda serão processados.

Exemplo:

cadeia de caracteres de entrada: "A&bc&&d"

normal: "Abc&d"

DT_HIDEPREFIX: "Abc&d"

Compare com DT_NOPREFIX e DT_PREFIXONLY.

DT_INTERNAL
Usa a fonte do sistema para calcular métricas de texto.
DT_LEFT
Alinha o texto à esquerda.
DT_MODIFYSTRING
Modifica a cadeia de caracteres especificada para corresponder ao texto exibido. Esse valor não tem efeito, a menos que DT_END_ELLIPSIS ou DT_PATH_ELLIPSIS seja especificado.
DT_NOCLIP
Desenha sem recorte. DrawTextEx é um pouco mais rápido quando DT_NOCLIP é usado.
DT_NOFULLWIDTHCHARBREAK
Impede uma quebra de linha em um DBCS (cadeia de caracteres de largura dupla), de modo que a regra de quebra de linha seja equivalente a cadeias de caracteres SBCS. Por exemplo, isso pode ser usado em janelas coreanas, para obter mais legibilidade de rótulos de ícone. Esse valor não tem efeito, a menos que DT_WORDBREAK seja especificado.
DT_NOPREFIX
Desativa o processamento de caracteres de prefixo. Normalmente, DrawTextEx interpreta o caractere de prefixo mnemônico de e comercial (&) como uma diretiva para sublinhar o caractere a seguir e os caracteres de prefixo mnemônico de e comercial duplo (&&) como uma diretiva para imprimir um único e comercial. Ao especificar DT_NOPREFIX, esse processamento é desativado. Comparar com DT_HIDEPREFIX e DT_PREFIXONLY
DT_PATH_ELLIPSIS
Para texto exibido, substitui caracteres no meio da cadeia de caracteres por reticências para que o resultado se ajuste ao retângulo especificado. Se a cadeia de caracteres contiver caracteres de barra invertida (\\), DT_PATH_ELLIPSIS preservará o máximo possível do texto após a última barra invertida. A cadeia de caracteres não é modificada, a menos que o sinalizador DT_MODIFYSTRING seja especificado.

Compare com DT_END_ELLIPSIS e DT_WORD_ELLIPSIS.

DT_PREFIXONLY
Desenha apenas um sublinhado na posição do caractere após o caractere de prefixo e comercial (&). Não desenha nenhum caractere na cadeia de caracteres.

Exemplo:

cadeia de caracteres de entrada: "A&bc&&d"

normal: "Abc&d"

PREFIXONLY: " _ "

Compare com DT_NOPREFIX e DT_HIDEPREFIX.

DT_RIGHT
Alinha o texto à direita.
DT_RTLREADING
Layout na ordem de leitura da direita para a esquerda para texto bidirecional quando a fonte selecionada no hdc é uma fonte hebraica ou árabe. A ordem de leitura padrão para todo o texto é da esquerda para a direita.
DT_SINGLELINE
Exibe texto somente em uma única linha. Retornos de carro e alimentações de linha não quebram a linha.
DT_TABSTOP
Define paradas de tabulação. A estrutura DRAWTEXTPARAMS apontada pelo parâmetro lpDTParams especifica o número de larguras médias de caracteres por parada de tabulação.
DT_TOP
Justifica o texto para a parte superior do retângulo.
DT_VCENTER
Centraliza o texto verticalmente. Esse valor é usado apenas com o valor DT_SINGLELINE.
DT_WORDBREAK
Quebra palavras. As linhas serão quebradas automaticamente entre palavras se uma palavra se estender para além da borda do retângulo especificada pelo parâmetro lprc . Uma sequência de alimentação de linha de retorno de carro também quebra a linha.
DT_WORD_ELLIPSIS
Trunca qualquer palavra que não se encaixe no retângulo e adicione reticências.

Compare com DT_END_ELLIPSIS e DT_PATH_ELLIPSIS.

[in] lpdtp

Um ponteiro para uma estrutura DRAWTEXTPARAMS que especifica opções de formatação adicionais. Este parâmetro pode ser NULL.

Retornar valor

Se a função for bem-sucedida, o valor retornado será a altura do texto em unidades lógicas. Se DT_VCENTER ou DT_BOTTOM for especificado, o valor retornado será o deslocamento de lprc->top para a parte inferior do texto desenhado.

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

Comentários

A função DrawTextEx dá suporte apenas a fontes cujo escape e orientação são zero.

O modo de alinhamento de texto para o contexto do dispositivo deve incluir os sinalizadores TA_LEFT, TA_TOP e TA_NOUPDATECP.

Observação

O cabeçalho winuser.h define DrawTextEx 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 winuser.h (inclua Windows.h)
Biblioteca User32.lib
DLL User32.dll
Conjunto de APIs ext-ms-win-ntuser-misc-l1-2-0 (introduzido em Windows 8.1)

Confira também

DRAWTEXTPARAMS

Drawtext

Funções de fonte e texto

Visão geral de fontes e texto