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 DrawTextW(
[in] HDC hdc,
[in, out] LPCWSTR 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) 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.
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) |
Consulte também
DrawTextEx
Funções de fonte e texto
fontes e visão geral de texto
GrayString
RECT
tabbedTextOut
textout