Función GetCharacterPlacementA (wingdi.h)

Artículo
11/20/2024

La función GetCharacterPlacement recupera información sobre una cadena de caracteres, como anchos de caracteres, posicionamiento de símbolos 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 visualizació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 dejado 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 GCP_NODIACRITICS valor 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. No es necesario que la cadena finalice cero, ya que nCount especifica la longitud de la cadena.

[in] nCount

Longitud de la cadena a la que apuntalpString.

[in] nMexExtent

Extensión máxima (en unidades lógicas) a la que se procesa la cadena. Los caracteres que, si se procesan, superarían esta extensión se omiten. Los cálculos de las matrices de orden o glifo necesarias solo se aplican a los caracteres incluidos. Este parámetro solo se usa si el valor de 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, extensión y otras matrices solo si la extensión total aún no ha superado el máximo. Una vez 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 varios de los siguientes valores.

Valor	Significado
GCP_CLASSIN	Especifica que la matriz de 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 desee mostrarlas. Use GetFontLanguageInfo para determinar si una fuente admite diacríticos. Si lo hace, 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	Para los lenguajes que necesitan reordenar o diferentes formas de glifo en función de las posiciones de los caracteres dentro 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 Left-To-Right y Right-To-Left, para ayudar a determinar el posicionamiento final de caracteres dentro de las cadenas de salida. Normalmente no se muestran y se quitan de los de lpGlyphs de y matrices de lpDx. Puede usar la marca GCP_DISPLAYZWG para mostrar estos caracteres.
GCP_GLYPHSHAPE	Especifica que se van a mostrar 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 debe usarse con GetCharacterPlacement.
GCP_JUSTIFY	Ajusta las extensiones de la matriz de lpDx para que la longitud de la cadena sea la misma que nMaxExtent. GCP_JUSTIFY solo se pueden 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 de lpDx, Kashida se indica mediante un índice de justificación negativo. 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. Debido a esto, 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 devuelto desde una llamada GetTextMetrics). Tenga en cuenta que, solo porque GetFontLanguageInfo devuelve la marca GCP_KASHIDA no significa que tenga que usarse en la llamada a GetCharacterPlacement, solo que la opción está disponible.
GCP_LIGATE	Use ligaciones dondequiera que 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 ligar a ?. Sin embargo, para que esto 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 ligaduras. 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 del lpGlyphs matriz. 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 normalmente es 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 ciertos idiomas. Invalide el control normal de neutrales y los trate como caracteres seguros que coincidan con el orden de lectura de cadenas. Útil solo con la marca GCP_REORDER.
GCP_NUMERICOVERRIDE	Solo ciertos idiomas. Invalide el control normal de los valores numéricos y los trate como caracteres seguros que coincidan con el orden de lectura de cadenas. Útil solo con la marca GCP_REORDER.
GCP_NUMERICSLATIN	Sólo á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	Sólo á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	Reordene la cadena. Se usa para idiomas que no son SBCS y orden de lectura de izquierda a derecha. Si no se especifica este valor, se supone que la cadena ya está en orden de presentación. Si se establece esta marca para idiomas semitices y se usa la matriz de 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 en los que se usa y se omiten los campos de lpOutStr ing y lpOrder. Use GetFontLanguageInfo para determinar si la fuente actual admite el reordenamiento.
GCP_SYMSWAPOFF	Solo idiomas semitices. Especifica que los caracteres intercambiables no se restablecen. Por ejemplo, en una cadena de derecha a izquierda, no se invierten los valores "(" y ")".
GCP_USEKERNING	Use pares de kerning en la fuente (si existe) al crear las matrices de anchos. Use GetFontLanguageInfo para determinar si la fuente actual admite pares de kerning. Tenga en cuenta que, solo porque GetFontLanguageInfo devuelve la marca GCP_USEKERNING no significa que tenga que usarse en la llamada a GetCharacterPlacement, solo que la opción está disponible. La mayoría de las fuentes TrueType tienen una tabla de kerning, pero no es necesario usarla.

El GCP_NODIACRITICS valor 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 alto de la cadena en unidades lógicas. El ancho es la palabra de orden bajo y el alto es la palabra de orden superior.

Si se produce un error en la función, el valor devuelto es cero.

Observaciones

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 intercharacter y las matrices de índices no siempre es necesario a menos que se requiera justificación o kerning. 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 índice antes de llamar a ExtTextOut. Esto resulta 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 el lpGlyphs matriz de salida se usa en la llamada a ExtTextOut, se debe establecer la marca ETO_GLYPH_INDEX.

getCharacterPlacement comprueba el lpOrder, lpDX, lpCaretPos, lpOutStringy lpGlyphs miembros 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 de lpDX lpCaret Pos 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 se deben usar 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 solo de espacios, la función devuelve un error.

ExtTextOut espera una entrada de lpDX para cada byte de una cadena DBCS, mientras que GetCharacterPlacement asigna una entrada de lpDX para cada glifo. Para corregir este error de coincidencia al usar esta combinación de funciones, use GetGlyphIndices o expanda la matriz de 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 de lpDX de . A continuación, use la matriz de 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 índices de glifo avanzan ancho 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 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

extTextOut

funciones de fuente y texto de

de información general de fuentes y texto de

GCP_RESULTS

GetCharABCWidths

GetCharWidth32

GetFontLanguageInfo

GetStringTypeEx

GetTextExtentPoint32

GetTextMetrics de

Compartir a través de