Función ExtTextOutA (wingdi.h)

Artículo
03/08/2023

La función ExtTextOut dibuja texto con la fuente, el color de fondo y el color de texto seleccionados actualmente. Opcionalmente, puede proporcionar dimensiones que se usarán para recortar, opacar o ambas.

Sintaxis

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Parámetros

[in] hdc

Identificador del contexto del dispositivo.

[in] x

Coordenada x, en coordenadas lógicas, del punto de referencia utilizado para colocar la cadena.

[in] y

Coordenada y, en coordenadas lógicas, del punto de referencia utilizado para colocar la cadena.

[in] options

Especifica cómo usar el rectángulo definido por la aplicación. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
ETO_CLIPPED	El texto se recortará en el rectángulo.
ETO_GLYPH_INDEX	La matriz lpString hace referencia a una matriz devuelta desde GetCharacterPlacement y GDI debe analizarse directamente, ya que no se requiere ningún procesamiento adicional específico del lenguaje. La indexación de glifo solo se aplica a las fuentes TrueType, pero la marca se puede usar para el mapa de bits y las fuentes vectoriales para indicar que no es necesario ningún procesamiento de lenguaje adicional y GDI debe procesar la cadena directamente. Tenga en cuenta que todos los índices de glifo son valores de 16 bits, aunque se supone que la cadena es una matriz de valores de 8 bits para las fuentes ráster. Para ExtTextOutW, los índices de glifo se guardan en un metarchivo. Sin embargo, para mostrar los caracteres correctos, el metarchivo debe reproducirse con la misma fuente. Para ExtTextOutA, los índices de glifo no se guardan.
ETO_IGNORELANGUAGE	Reservado para uso del sistema. Si una aplicación establece esta marca, pierde la compatibilidad con scripting internacional y, en algunos casos, puede que no muestre texto en absoluto.
ETO_NUMERICSLATIN	Para mostrar números, use dígitos europeos.
ETO_NUMERICSLOCAL	Para mostrar números, use dígitos adecuados para la configuración regional.
ETO_OPAQUE	El color de fondo actual debe usarse para rellenar el rectángulo.
ETO_PDY	Cuando se establece, la matriz a la que apunta lpDx contiene pares de valores. El primer valor de cada par es, como es habitual, la distancia entre los orígenes de las celdas de caracteres adyacentes, pero el segundo valor es el desplazamiento a lo largo de la dirección vertical de la fuente.
ETO_RTLREADING	Edición de idioma de Oriente Medio de Windows: Si se especifica este valor y se selecciona una fuente hebreo o árabe en el contexto del dispositivo, la cadena se genera mediante el orden de lectura de derecha a izquierda. Si no se especifica este valor, la cadena se genera en orden de izquierda a derecha. El mismo efecto se puede lograr estableciendo el valor de TA_RTLREADING en SetTextAlign. Este valor se conserva para la compatibilidad con versiones anteriores.

Los valores de ETO_GLYPH_INDEX y ETO_RTLREADING no se pueden usar juntos. Dado que ETO_GLYPH_INDEX implica que se ha completado todo el procesamiento del lenguaje, la función omite la marca de ETO_RTLREADING si también se especifica.

[in] lprect

Puntero a una estructura RECT opcional que especifica las dimensiones, en coordenadas lógicas, de un rectángulo que se usa para recortar, opaco o ambos.

[in] lpString

Puntero a una cadena que especifica el texto que se va a dibujar. La cadena no necesita terminar en cero, ya que cbCount especifica la longitud de la cadena.

[in] c

Longitud de la cadena a la que apunta lpString.

Este valor no puede superar 8192.

[in] lpDx

Puntero a una matriz opcional de valores que indican la distancia entre los orígenes de las celdas de caracteres adyacentes. Por ejemplo, las unidades lógicas lpDx[i] separan los orígenes de la celda de caracteres i y la celda de caracteres i + 1.

Valor devuelto

Si se dibuja la cadena, el valor devuelto es distinto de cero. Sin embargo, si se llama a la versión ANSI de ExtTextOut con ETO_GLYPH_INDEX, la función devuelve TRUE aunque la función no haga nada.

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

Comentarios

La configuración actual de alineación de texto para el contexto de dispositivo especificado determina cómo se usa el punto de referencia para colocar el texto. La configuración de alineación de texto se recupera mediante una llamada a la función GetTextAlign . La configuración de alineación de texto se modifica mediante una llamada a la función SetTextAlign . Puede usar los valores siguientes para la alineación de texto. Solo se puede elegir una marca de las que afectan a la alineación horizontal y vertical. Además, solo se puede elegir una de las dos marcas que modifican la posición actual.

Término	Descripción
TA_BASELINE	El punto de referencia estará en la línea base del texto.
TA_BOTTOM	El punto de referencia estará en el borde inferior del rectángulo delimitador.
TA_TOP	El punto de referencia estará en el borde superior del rectángulo delimitador.
TA_CENTER	El punto de referencia se alineará horizontalmente con el centro del rectángulo delimitador.
TA_LEFT	El punto de referencia estará en el borde izquierdo del rectángulo delimitador.
TA_RIGHT	El punto de referencia estará en el borde derecho del rectángulo delimitador.
TA_NOUPDATECP	La posición actual no se actualiza después de cada llamada de salida de texto. El punto de referencia se pasa a la función de salida de texto.
TA_RTLREADING	Edición de idioma de Oriente Medio de Windows: El texto se coloca en orden de lectura de derecha a izquierda, en lugar del orden predeterminado de izquierda a derecha. Esto solo se aplica cuando la fuente seleccionada en el contexto del dispositivo es hebreo o árabe.
TA_UPDATECP	La posición actual se actualiza después de cada llamada de salida de texto. La posición actual se usa como punto de referencia.

Si el parámetro lpDx es NULL, la función ExtTextOut usa el espaciado predeterminado entre caracteres. Los orígenes de celda de caracteres y el contenido de la matriz a la que apunta el parámetro lpDx se especifican en unidades lógicas. Un origen de celda de caracteres se define como la esquina superior izquierda de la celda de caracteres.

De forma predeterminada, esta función no usa ni actualiza la posición actual. Sin embargo, una aplicación puede llamar a la función SetTextAlign con el parámetro fMode establecido en TA_UPDATECP para permitir que el sistema use y actualice la posición actual cada vez que la aplicación llama a ExtTextOut para un contexto de dispositivo especificado. Cuando se establece esta marca, el sistema omite los parámetros X e Y en las llamadas posteriores a ExtTextOut .

Para la versión ANSI de ExtTextOut, la matriz lpDx tiene el mismo número de valores INT que hay bytes en lpString. Para los caracteres DBCS, puede apportion the dx in the lpDx entries between the lead byte and the trail byte, as as the sum of the two bytes adds up to the desired dx. Para los caracteres DBCS con la versión Unicode de ExtTextOut, cada glifo Unicode obtiene una única entrada pdx .

Tenga en cuenta que los valores alpDx de GetTextExtentExPoint no son los mismos que los valores lpDx para ExtTextOut. Para usar los valores de alpDx en lpDx, primero debe procesarlos.

ExtTextOut usará Uniscribe cuando sea necesario, lo que dará lugar a una reserva de fuentes. La marca ETO_IGNORELANGUAGE impedirá este comportamiento y no se debe pasar.

Además, ExtTextOut realizará el procesamiento por lotes interno de llamadas antes de realizar la transición al modo kernel, lo que mitiga algunos de los problemas de rendimiento al ponderar el uso de PolyTextOut frente a ExtTextOut.

Sugerencia

ExtTextOut se recomienda encarecidamente sobre PolyTextOut para el desarrollo moderno debido a su capacidad para controlar la visualización de diferentes lenguajes.

Ejemplos

Para obtener un ejemplo, vea "Establecer fuentes para Menu-Item cadenas de texto" en Usar menús.

Nota

El encabezado wingdi.h define ExtTextOut como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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	wingdi.h (incluye Windows.h)
Library	Gdi32.lib
Archivo DLL	Gdi32.dll