Função DrawText (winuser.h)

Artigo
06/08/2023

A função DrawText desenha texto formatado no retângulo especificado. Ele formata o texto de acordo com o método especificado (expandindo guias, justificando caracteres, linhas quebrando e assim por diante).

Para especificar opções de formatação adicionais, use a função DrawTextEx .

Sintaxe

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo.

[in, out] lpchText

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

Se uFormat 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, em caracteres, da cadeia de caracteres. Se nCount for -1, o parâmetro lpchText será considerado um ponteiro para uma cadeia de caracteres terminada em nulo e DrawText 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) no qual o texto deve ser formatado.

[in] format

O método de formatação do texto. 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, DrawText usará a largura do retângulo apontado pelo parâmetro lpRect e estenderá a base do retângulo para associar a última linha de texto. Se a palavra maior for maior que o retângulo, a largura será expandida. Se o texto for menor que a largura do retângulo, a largura será reduzida. Se houver apenas uma linha de texto, DrawText modificará o lado direito do retângulo para que ele limite o último caractere na linha. Em ambos os casos, DrawText 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 o texto exibido, se o final de uma cadeia de caracteres não se ajustar ao retângulo, ele será truncado e as reticências serão adicionadas. Se uma palavra que não estiver no final da cadeia de caracteres ultrapassar os limites do retângulo, ela será 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. Os valores DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS e DT_END_ELLIPSIS não podem ser usados com o valor DT_EXPANDTABS.
DT_EXTERNALLEADING	Inclui os principais de fonte externa na altura da linha. Normalmente, a liderança externa não é incluída na altura de uma linha de texto.
DT_HIDEPREFIX	Ignora o caractere de prefixo de 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. DrawText é 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, DrawText interpreta o caractere mnemonic-prefix & como uma diretiva para sublinhar o caractere a seguir e os caracteres de prefixo mnemônico && como uma diretiva para imprimir um único &. Ao especificar DT_NOPREFIX, esse processamento está desativado. Por exemplo, Exemplo: cadeia de caracteres de entrada: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Compare 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 encaixe no 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 ampersand (&). Não desenha nenhum outro caractere na cadeia de caracteres. Por exemplo, Exemplo: cadeia de caracteres de entrada: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Compare com DT_HIDEPREFIX e DT_NOPREFIX.
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. O carro retorna e os feeds de linha não quebram a linha.
DT_TABSTOP	Define paradas de tabulação. Os bits 15-8 (byte de ordem alta da palavra de ordem baixa) do parâmetro uFormat especificam o número de caracteres para cada guia. O número padrão de caracteres por guia é oito. Os valores DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP e DT_NOPREFIX não podem ser usados com o valor DT_TABSTOP.
DT_TOP	Justifica o texto na 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 além da borda do retângulo especificada pelo parâmetro lpRect . Uma sequência de alimentação de linha de retorno de carro também quebra a linha. Se isso não for especificado, a saída estará em uma 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.

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 lpRect->top para a parte inferior do texto desenhado.

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

Comentários

A função DrawText usa a fonte, a cor do texto e a cor da tela de fundo selecionadas do contexto do dispositivo para desenhar o texto. A menos que o formato DT_NOCLIP seja usado, DrawText recorta o texto para que ele não apareça fora do retângulo especificado. Observe que o texto com saliência significativa pode ser recortado, por exemplo, um "W" inicial na cadeia de texto ou texto que está em itálico. Supõe-se que toda a formatação tenha várias linhas, a menos que o formato DT_SINGLELINE seja especificado.

Se a fonte selecionada for muito grande para o retângulo especificado, a função DrawText não tentará substituir uma fonte menor.

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

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-1-0 (introduzido em Windows 8)