Función DrawText (winuser.h)

Artículo
03/04/2024

La función DrawText dibuja texto con formato en el rectángulo especificado. Da formato al texto según el método especificado (expandiendo fichas, justificando caracteres, líneas de separación, etc.).

Para especificar opciones de formato adicionales, use la función DrawTextEx .

Sintaxis

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

Parámetros

[in] hdc

Identificador del contexto del dispositivo.

[in, out] lpchText

Puntero a la cadena que especifica el texto que se va a dibujar. Si el parámetro nCount es -1, la cadena debe terminar en null.

Si uFormat incluye DT_MODIFYSTRING, la función podría agregar hasta cuatro caracteres adicionales a esta cadena. El búfer que contiene la cadena debe ser lo suficientemente grande como para acomodar estos caracteres adicionales.

[in] cchText

Longitud, en caracteres, de la cadena. Si nCount es -1, se supone que el parámetro lpchText es un puntero a una cadena terminada en null y DrawText calcula automáticamente el recuento de caracteres.

[in, out] lprc

Puntero a una estructura RECT que contiene el rectángulo (en coordenadas lógicas) en el que se va a dar formato al texto.

[in] format

Método para dar formato al texto. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
DT_BOTTOM	Justifica el texto en la parte inferior del rectángulo. Este valor solo se usa con el valor DT_SINGLELINE.
DT_CALCRECT	Determina el ancho y el alto del rectángulo. Si hay varias líneas de texto, DrawText usa el ancho del rectángulo al que apunta el parámetro lpRect y extiende la base del rectángulo para enlazar la última línea de texto. Si la palabra más grande es más ancha que el rectángulo, el ancho se expande. Si el texto es menor que el ancho del rectángulo, se reduce el ancho. Si solo hay una línea de texto, DrawText modifica el lado derecho del rectángulo para que delimite el último carácter de la línea. En cualquier caso, DrawText devuelve el alto del texto con formato, pero no dibuja el texto.
DT_CENTER	Centra el texto horizontalmente en el rectángulo.
DT_EDITCONTROL	Duplica las características que muestran texto de un control de edición de varias líneas. En concreto, el ancho medio de caracteres se calcula de la misma manera que para un control de edición y la función no muestra una última línea parcialmente visible.
DT_END_ELLIPSIS	Para el texto mostrado, si el final de una cadena no cabe en el rectángulo, se trunca y se agregan puntos suspensivos. Si una palabra que no está al final de la cadena va más allá de los límites del rectángulo, se trunca sin puntos suspensivos. La cadena no se modifica a menos que se especifique la marca DT_MODIFYSTRING. Comparar con DT_PATH_ELLIPSIS y DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Expande los caracteres de tabulación. El número de caracteres predeterminado por tabulación es ocho. Los valores de DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS y DT_END_ELLIPSIS no se pueden usar con el valor de DT_EXPANDTABS.
DT_EXTERNALLEADING	Incluye la inicial externa de fuente en el alto de la línea. Normalmente, la punta externa no se incluye en el alto de una línea de texto.
DT_HIDEPREFIX	Omite el carácter de prefijo de y comercial (&) en el texto. La letra siguiente no estará subrayada, pero se siguen procesando otros caracteres de prefijo mnemónico. Ejemplo: cadena de entrada: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d" Comparar con DT_NOPREFIX y DT_PREFIXONLY.
DT_INTERNAL	Utiliza la fuente del sistema para calcular la métrica del texto.
DT_LEFT	Alinea el texto a la izquierda.
DT_MODIFYSTRING	Modifica la cadena especificada para que coincida con el texto mostrado. Este valor no tiene ningún efecto a menos que se especifique DT_END_ELLIPSIS o DT_PATH_ELLIPSIS.
DT_NOCLIP	Dibuja sin recorte. DrawText es algo más rápido cuando se usa DT_NOCLIP.
DT_NOFULLWIDTHCHARBREAK	Impide un salto de línea en un DBCS (cadena de caracteres de doble ancho), por lo que la regla de salto de línea es equivalente a las cadenas SBCS. Por ejemplo, esto se puede usar en ventanas coreanas para obtener más legibilidad de las etiquetas de icono. Este valor no tiene ningún efecto a menos que se especifique DT_WORDBREAK.
DT_NOPREFIX	Desactiva el procesamiento de caracteres de prefijo. Normalmente, DrawText interpreta el carácter de prefijo mnemónico & como una directiva para resaltar el carácter siguiente y los caracteres de prefijo mnemónico && como una directiva para imprimir un solo &. Al especificar DT_NOPREFIX, este procesamiento está desactivado. Por ejemplo, Ejemplo: cadena de entrada: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Comparar con DT_HIDEPREFIX y DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Para el texto mostrado, reemplaza los caracteres en medio de la cadena por puntos suspensivos para que el resultado se ajuste al rectángulo especificado. Si la cadena contiene caracteres de barra diagonal inversa (\\), DT_PATH_ELLIPSIS conserva tanto como sea posible el texto después de la última barra diagonal inversa. La cadena no se modifica a menos que se especifique la marca DT_MODIFYSTRING. Comparar con DT_END_ELLIPSIS y DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Dibuja solo un subrayado en la posición del carácter que sigue al carácter de prefijo (&). No dibuja ningún otro carácter en la cadena. Por ejemplo, Ejemplo: cadena de entrada: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Comparar con DT_HIDEPREFIX y DT_NOPREFIX.
DT_RIGHT	Alinea el texto a la derecha.
DT_RTLREADING	Diseño en orden de lectura de derecha a izquierda para texto bidireccional cuando la fuente seleccionada en hdc es una fuente hebreo o árabe. El orden de lectura predeterminado para todo el texto es de izquierda a derecha.
DT_SINGLELINE	Muestra texto solo en una sola línea. Los retornos de carro y las fuentes de línea no rompen la línea.
DT_TABSTOP	Establece las tabulaciones. Los bits 15-8 (byte de orden superior de la palabra de orden bajo) del parámetro uFormat especifican el número de caracteres para cada pestaña. El número predeterminado de caracteres por pestaña es ocho. Los valores DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP y DT_NOPREFIX no se pueden usar con el valor DT_TABSTOP.
DT_TOP	Justifica el texto en la parte superior del rectángulo.
DT_VCENTER	Centra el texto verticalmente. Este valor solo se usa con el valor DT_SINGLELINE.
DT_WORDBREAK	Rompe palabras. Las líneas se rompen automáticamente entre palabras si una palabra se extendería más allá del borde del rectángulo especificado por el parámetro lpRect . Una secuencia de avance de retorno de carro también rompe la línea. Si no se especifica, la salida está en una línea.
DT_WORD_ELLIPSIS	Trunca cualquier palabra que no cabe en el rectángulo y agrega puntos suspensivos. Comparar con DT_END_ELLIPSIS y DT_PATH_ELLIPSIS.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el alto del texto en unidades lógicas. Si se especifica DT_VCENTER o DT_BOTTOM, el valor devuelto es el desplazamiento de lpRect->top a la parte inferior del texto dibujado.

Si la función no se realiza correctamente, el valor devuelto es cero.

Comentarios

La función DrawText usa la fuente seleccionada del contexto del dispositivo, el color de texto y el color de fondo para dibujar el texto. A menos que se use el formato DT_NOCLIP, DrawText recorta el texto para que no aparezca fuera del rectángulo especificado. Tenga en cuenta que el texto con un voladizo significativo se puede recortar, por ejemplo, una "W" inicial en la cadena de texto o texto que está en cursiva. Se supone que todo el formato tiene varias líneas a menos que se especifique el formato DT_SINGLELINE.

Si la fuente seleccionada es demasiado grande para el rectángulo especificado, la función DrawText no intenta sustituir una fuente más pequeña.

El modo de alineación de texto para el contexto del dispositivo debe incluir las marcas de TA_LEFT, TA_TOP y TA_NOUPDATECP.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-misc-l1-1-0 (introducido en Windows 8)