Función GetCharacterPlacementA (wingdi.h)

Artículo
03/08/2023

La función GetCharacterPlacement recupera información sobre una cadena de caracteres, como anchos de caracteres, posicionamiento de intercalación, ordenación dentro de la cadena y representación del glifo. El tipo de información devuelta depende del parámetro dwFlags y se basa en la fuente seleccionada actualmente en el contexto de presentación especificado. La función copia la información en la estructura de GCP_RESULTS especificada o en una o varias matrices especificadas por la estructura .

Aunque esta función era una vez adecuada para trabajar con cadenas de caracteres, una necesidad de trabajar con un número cada vez mayor de lenguajes y scripts lo ha hecho obsoleto. Se ha reemplazado por la funcionalidad del módulo Uniscribe. Para obtener más información, vea Uniscribe.

Se recomienda que una aplicación use la función GetFontLanguageInfo para determinar si los valores de GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE y GCP_KASHIDA son válidos para la fuente seleccionada actualmente. Si no es válido, GetCharacterPlacement omite el valor.

El valor GCP_NODIACRITICS ya no está definido y no se debe usar.

Sintaxis

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

Parámetros

[in] hdc

Identificador del contexto del dispositivo.

[in] lpString

Puntero a la cadena de caracteres que se va a procesar. La cadena no necesita terminar en cero, ya que nCount especifica la longitud de la cadena.

[in] nCount

Longitud de la cadena a la que apunta lpString.

[in] nMexExtent

Extensión máxima (en unidades lógicas) a la que se procesa la cadena. Los caracteres que, en caso de procesarse, superarían esta extensión se omiten. Los cálculos de la ordenación necesaria o las matrices de glifos solo se aplican a los caracteres incluidos. Este parámetro solo se usa si el valor GCP_MAXEXTENT se especifica en el parámetro dwFlags . A medida que la función procesa la cadena de entrada, cada carácter y su extensión se agregan a la salida, la extensión y otras matrices solo si la extensión total aún no ha superado el máximo. Una vez que se haya alcanzado el límite, el procesamiento se detendrá.

[in, out] lpResults

Puntero a una estructura GCP_RESULTS que recibe los resultados de la función.

[in] dwFlags

Especifica cómo procesar la cadena en las matrices necesarias. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
GCP_CLASSIN	Especifica que la matriz lpClass contiene clasificaciones preestablecidas para caracteres. Las clasificaciones pueden ser las mismas que en la salida. Si no se conoce la clasificación concreta de un carácter, la ubicación correspondiente de la matriz debe establecerse en cero. para obtener más información sobre las clasificaciones, vea GCP_RESULTS. Esto solo es útil si GetFontLanguageInfo devolvió la marca GCP_REORDER.
GCP_DIACRITIC	Determina cómo se controlan los diacríticos de la cadena. Si no se establece este valor, los diacríticos se tratan como caracteres de ancho cero. Por ejemplo, una cadena hebreo puede contener diacríticos, pero es posible que no quiera mostrarlas. Use GetFontLanguageInfo para determinar si una fuente admite diacríticos. Si es así, puede usar o no la marca GCP_DIACRITIC en la llamada a GetCharacterPlacement, en función de las necesidades de la aplicación.
GCP_DISPLAYZWG	En el caso de los idiomas que necesitan reordenar o diferentes formas de glifo en función de las posiciones de los caracteres de una palabra, los caracteres no reproducibles a menudo aparecen en la página de códigos. Por ejemplo, en la página de códigos hebreo, hay marcadores de izquierda a derecha y de derecha a izquierda, para ayudar a determinar el posicionamiento final de los caracteres dentro de las cadenas de salida. Normalmente no se muestran y se quitan de las matrices lpGlyphs y lpDx . Puede usar la marca GCP_DISPLAYZWG para mostrar estos caracteres.
GCP_GLYPHSHAPE	Especifica que se mostrarán algunos o todos los caracteres de la cadena mediante formas distintas de las formas estándar definidas en la fuente seleccionada actualmente para la página de códigos actual. Algunos idiomas, como el árabe, no pueden admitir la creación de glifos a menos que se especifique este valor. Como regla general, si GetFontLanguageInfo devuelve este valor para una cadena, este valor se debe usar con GetCharacterPlacement.
GCP_JUSTIFY	Ajusta las extensiones de la matriz lpDx para que la longitud de la cadena sea la misma que nMaxExtent. GCP_JUSTIFY solo se puede usar junto con GCP_MAXEXTENT.
GCP_KASHIDA	Use Kashidas, o en lugar de, extensiones ajustadas para modificar la longitud de la cadena para que sea igual al valor especificado por nMaxExtent. En la matriz lpDx , un Kashida se indica mediante un índice de justificación negativa. GCP_KASHIDA solo se pueden usar junto con GCP_JUSTIFY y solo si la fuente (y el idioma) admiten Kashidas. Use GetFontLanguageInfo para determinar si la fuente actual admite Kashidas. El uso de Kashidas para justificar la cadena puede dar lugar a que el número de glifos necesarios sea mayor que el número de caracteres de la cadena de entrada. Por este motivo, cuando se usan Kashidas, la aplicación no puede suponer que establecer las matrices para que sean el tamaño de la cadena de entrada será suficiente. (El máximo posible será aproximadamente dxPageWidth/dxAveCharWidth, donde dxPageWidth es el ancho del documento y dxAveCharWidth es el ancho medio de caracteres que se devuelve desde una llamada a GetTextMetrics ). Tenga en cuenta que solo porque GetFontLanguageInfo devuelve la marca GCP_KASHIDA no significa que se tenga que usar en la llamada a GetCharacterPlacement, solo que la opción está disponible.
GCP_LIGATE	Use ligaduras donde los caracteres se ligan. Se produce una ligadura en la que se usa un glifo para dos o más caracteres. Por ejemplo, las letras a y e pueden ligarse a ?. Sin embargo, para que se use, tanto la compatibilidad con el idioma como la fuente deben admitir los glifos necesarios (el ejemplo no se procesará de forma predeterminada en inglés). Use GetFontLanguageInfo para determinar si la fuente actual admite ligadura. Si lo hace y se requiere un máximo específico para el número de caracteres que se ligarán, establezca el número en el primer elemento de la matriz lpGlyphs . Si se requiere ligadura normal, establezca este valor en cero. Si no se especifica GCP_LIGATE, no se realizará ninguna ligadura. Consulte GCP_RESULTS para obtener más información. Si el valor de GCP_REORDER suele ser necesario para el juego de caracteres, pero no se especifica, la salida será a menos que la cadena que se pase ya esté en orden visual (es decir, el resultado que se coloca en lpGcpResults-lpOutString> en una llamada a GetCharacterPlacement es la cadena de entrada de una segunda llamada). Tenga en cuenta que solo porque GetFontLanguageInfo devuelve la marca GCP_LIGATE no significa que tenga que usarse en la llamada a GetCharacterPlacement, solo que la opción está disponible.
GCP_MAXEXTENT	Las extensiones de proceso de la cadena solo siempre que la extensión resultante, en unidades lógicas, no supere los valores especificados por el parámetro nMaxExtent .
GCP_NEUTRALOVERRIDE	Solo determinados idiomas. Invalide el control normal de neutrales y los trate como caracteres seguros que coincidan con el orden de lectura de las cadenas. Solo es útil con la marca GCP_REORDER.
GCP_NUMERICOVERRIDE	Solo determinados idiomas. Invalide el control normal de los valores numéricos y los trate como caracteres seguros que coincidan con el orden de lectura de las cadenas. Solo es útil con la marca GCP_REORDER.
GCP_NUMERICSLATIN	Solo árabe/tailandés. Use glifos latinos estándar para números e invalide el valor predeterminado del sistema. Para determinar si esta opción está disponible en el idioma de la fuente, use GetStringTypeEx para ver si el idioma admite más de un formato numérico.
GCP_NUMERICSLOCAL	Solo árabe/tailandés. Use glifos locales para caracteres numéricos e invalide el valor predeterminado del sistema. Para determinar si esta opción está disponible en el idioma de la fuente, use GetStringTypeEx para ver si el idioma admite más de un formato numérico.
GCP_REORDER	Reordenar la cadena. Se usa para idiomas que no son SBCS y orden de lectura de izquierda a derecha. Si no se especifica este valor, ya se supone que la cadena está en orden de visualización. Si se establece esta marca para los idiomas semiticios y se usa la matriz lpClass , los dos primeros elementos de la matriz se usan para especificar el orden de lectura más allá de los límites de la cadena. GCP_CLASS_PREBOUNDRTL y GCP_CLASS_PREBOUNDLTR se pueden usar para establecer el orden. Si no se requiere ningún orden preestablecido, establezca los valores en cero. Estos valores se pueden combinar con otros valores si se establece la marca GCPCLASSIN. Si no se especifica el valor de GCP_REORDER, se toma el parámetro lpString para que se ordene visualmente para los idiomas donde se usa y se omiten los campos lpOutString y lpOrder . Use GetFontLanguageInfo para determinar si la fuente actual admite la reordenación.
GCP_SYMSWAPOFF	Solo idiomas semiticios. Especifica que los caracteres intercambiables no se restablecen. Por ejemplo, en una cadena de derecha a izquierda, no se invierten "(" y ")".
GCP_USEKERNING	Use pares de inter kerning en la fuente (si existe) al crear las matrices de anchos. Use GetFontLanguageInfo para determinar si la fuente actual admite pares de inter kerning. Tenga en cuenta que solo porque GetFontLanguageInfo devuelve la marca GCP_USEKERNING no significa que se tenga que usar en la llamada a GetCharacterPlacement, solo que la opción está disponible. La mayoría de las fuentes TrueType tienen una tabla de inter kerning, pero no es necesario usarla.

El valor GCP_NODIACRITICS ya no está definido y no se debe usar.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el ancho y el alto de la cadena en unidades lógicas. El ancho es la palabra de orden inferior y el alto es la palabra de orden superior.

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

Comentarios

GetCharacterPlacement garantiza que una aplicación pueda procesar correctamente el texto independientemente de la configuración internacional y el tipo de fuentes disponibles. Las aplicaciones usan esta función antes de usar la función ExtTextOut y en lugar de la función GetTextExtentPoint32 (y ocasionalmente en lugar de las funciones GetCharWidth32 y GetCharABCWidths ).

El uso de GetCharacterPlacement para recuperar el espaciado entre intercharacter y las matrices de índices no siempre es necesario a menos que se requiera justificación o intercalación. En el caso de las fuentes no latinas, las aplicaciones pueden mejorar la velocidad a la que la función ExtTextOut representa el texto mediante GetCharacterPlacement para recuperar el espaciado intercharacter y las matrices de índices antes de llamar a ExtTextOut. Esto es especialmente útil cuando se representa el mismo texto repetidamente o cuando se usa el espaciado intercharacter para colocar el símbolo de intercalación. Si la matriz de salida lpGlyphs se usa en la llamada a ExtTextOut, se debe establecer la marca ETO_GLYPH_INDEX.

GetCharacterPlacement comprueba los miembros lpOrder, lpDX, lpCaretPos, lpOutString y lpGlyphs de la estructura GCP_RESULTS y rellena las matrices correspondientes si estos miembros no están establecidos en NULL. Si GetCharacterPlacement no puede rellenar una matriz, establece el miembro correspondiente en NULL. Para garantizar la recuperación de información válida, la aplicación es responsable de establecer el miembro en una dirección válida antes de llamar a la función y comprobar el valor del miembro después de la llamada. Si se especifican los valores de GCP_JUSTIFY o GCP_USEKERNING, los miembros lpDX o lpCaretPos deben tener direcciones válidas.

Tenga en cuenta que los índices de glifo devueltos en GCP_RESULTS.lpGlyphs son específicos de la fuente actual en el contexto del dispositivo y solo deben usarse para dibujar texto en el contexto del dispositivo mientras esa fuente permanece seleccionada.

Al calcular la justificación, si los caracteres finales de la cadena son espacios, la función reduce la longitud de la cadena y quita los espacios antes de calcular la justificación. Si la matriz consta de solo espacios, la función devuelve un error.

ExtTextOut espera una entrada lpDX para cada byte de una cadena DBCS, mientras que GetCharacterPlacement asigna una entrada lpDX para cada glifo. Para corregir esta falta de coincidencia al usar esta combinación de funciones, use GetGlyphIndices o expanda la matriz lpDX con entradas de ancho cero para el segundo byte correspondiente de un par de bytes DBCS.

Si el ancho lógico es menor que el ancho del carácter inicial de la cadena de entrada, GCP_RESULTS.nMaxFit devuelve un valor incorrecto. En este caso, llame a GetCharacterPlacement para los índices de glifo y la matriz lpDX . A continuación, use la matriz lpDX para realizar el cálculo de la extensión mediante el ancho avanzado de cada carácter, donde nMaxFit es el número de caracteres cuyos glifos indexa el ancho avanzado es menor que el ancho del carácter inicial.

Nota

El encabezado wingdi.h define GetCharacterPlacement 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 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