A função DrawText desenha texto formatado no retângulo especificado. Ele formata o texto de acordo com o método especificado (guias de expansão, justificando caracteres, linhas de quebra e assim por diante).
Para especificar opções de formatação adicionais, use a função DrawTextEx.
Sintaxe
int DrawTextA(
[in] HDC hdc,
[in, out] LPCSTR 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 cchText 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 cchText 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) em que o texto deve ser formatado.
[in] format
O método de formatação do texto. Esse parâmetro pode ser um ou mais 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
Expande caracteres de 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 a fonte externa à esquerda na altura da linha. Normalmente, a liderança externa não está incluída na altura de uma linha de texto.
DT_HIDEPREFIX
Ignora o caractere de prefixo ampersand (&) 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 as 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 de prefixo mnemônico & 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 o texto exibido, substitui os 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 seguindo 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 alta ordem 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 divididas 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 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 ajuste ao retângulo e adiciona reticências.
Compare com DT_END_ELLIPSIS e DT_PATH_ELLIPSIS.
Valor de retorno
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.
Observações
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 corta 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.
Nota
O cabeçalho winuser.h define DrawText 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
winuser.h (inclua Windows.h)
biblioteca
User32.lib
de DLL
User32.dll
conjunto de API
ext-ms-win-ntuser-misc-l1-1-0 (introduzido no Windows 8)