Función ExtTextOutA (wingdi.h)

Artículo
11/20/2024

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, opaco o ambos.

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 varios de los siguientes valores.

Valor	Significado
ETO_CLIPPED	El texto se recortará en el rectángulo.
ETO_GLYPH_INDEX	La matriz de 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 glifos solo se aplica a las fuentes TrueType, pero la marca se puede usar para las fuentes de mapa de bits y vectores 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 scripts internacionales y, en algunos casos, puede que no muestre ningún texto.
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 de costumbre, 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 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 ETO_RTLREADING si también se especifica.

[in] lprect

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

[in] lpString

Puntero a una cadena que especifica el texto que se va a dibujar. No es necesario que la cadena finalice cero, ya que cbCount especifica la longitud de la cadena.

[in] c

Longitud de la cadena a la que apuntalpString.

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, lpDx[i] las unidades lógicas separan los orígenes de la celda de caracteres i y 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 se produce un error en la función, el valor devuelto es cero.

Observaciones

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 llamando a la función GetTextAlign. La configuración de alineación de texto se modifica llamando a la función SetTextAlign. Puede usar los siguientes valores 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 establece 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 las celdas 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 y Y en llamadas extTextOut posteriores.

Para la versión ANSI de ExtTextOut, la matriz de lpDx tiene el mismo número de valores INT que los bytes de lpString. En el caso de los caracteres DBCS, puede apportion the dx in the lpDx entradas entre el byte principal y el byte final, siempre y cuando la suma de los dos bytes sume hasta el dx deseado. Para los caracteres DBCS con la versión Unicode de ExtTextOut, cada glifo Unicode obtiene una sola entrada pdx.

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

extTextOut usará uniscribe cuando sea necesario, lo que da lugar a la reserva de fuentes. La marca ETO_IGNORELANGUAGE impedirá este comportamiento y no se debe pasar.

Además, extTextOut realizará un 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.

Propina

extTextOut se recomienda encarecidamente a través de polyTextOut para el desarrollo moderno debido a su capacidad de 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wingdi.h (incluya Windows.h)
biblioteca de	Gdi32.lib
DLL de	Gdi32.dll

Consulte también

funciones de fuente y texto de

de información general de fuentes y texto de

GetTextAlign

RECT

SelectObject

SetBkColor

SetTextAlign

SetTextColor

Compartir a través de