struttura GCP_RESULTSA (wingdi.h)

La struttura GCP_RESULTS contiene informazioni sui caratteri in una stringa. Questa struttura riceve i risultati della funzione GetCharacterPlacement. Per alcune lingue, il primo elemento nelle matrici può contenere più informazioni dipendenti dalla lingua.

Sintassi

typedef struct tagGCP_RESULTSA {
  DWORD  lStructSize;
  LPSTR  lpOutString;
  UINT   *lpOrder;
  int    *lpDx;
  int    *lpCaretPos;
  LPSTR  lpClass;
  LPWSTR lpGlyphs;
  UINT   nGlyphs;
  int    nMaxFit;
} GCP_RESULTSA, *LPGCP_RESULTSA;

Membri

lStructSize

Dimensione, in byte, della struttura.

lpOutString

Puntatore al buffer che riceve la stringa di output o NULL se la stringa di output non è necessaria. La stringa di output è una versione della stringa originale che si trova nell'ordine che verrà visualizzato in un dispositivo specificato. In genere la stringa di output è identica alla stringa originale, ma può essere diversa se la stringa deve essere riordinata e il flag GCP_REORDER è impostato o se la stringa originale supera l'extent massimo e viene impostato il flag GCP_MAXEXTENT.

lpOrder

Puntatore alla matrice che riceve indici di ordinamento o NULL se gli indici di ordinamento non sono necessari. Tuttavia, il suo significato dipende dagli altri elementi di GCP_RESULTS. Se gli indici del glifo devono essere restituiti, gli indici sono destinati alla matrice lpGlyphs; se glifi non vengono restituiti e viene richiesto lpOrder, gli indici sono per lpOutString. Ad esempio, nel secondo caso il valore di lpOrder[i] è la posizione di lpString[i] nella stringa di output lpOutString.

Viene in genere usato quando GetFontLanguageInfo restituisce il flag GCP_REORDER, che indica che la stringa originale deve essere riordinata. Ad esempio, in ebraico, in cui il testo viene eseguito da destra a sinistra, la matrice lpOrder fornisce le posizioni esatte di ogni elemento nella stringa originale.

lpDx

Puntatore alla matrice che riceve le distanze tra le celle di caratteri adiacenti o è NULL se queste distanze non sono necessarie. Se il rendering del glifo viene eseguito, le distanze sono relative ai glifi non ai caratteri, quindi la matrice risultante può essere usata con la funzione ExtTextOut.

Le distanze in questa matrice sono in ordine di visualizzazione. Per trovare la distanza per il i^carattere nella stringa originale, usare la matrice lpOrder come indicato di seguito:

width = lpDx[lpOrder[i]];

lpCaretPos

Puntatore alla matrice che riceve i valori di posizione del cursore o è NULL se le posizioni del cursore non sono necessarie. Ogni valore specifica la posizione del cursore immediatamente prima del carattere corrispondente. In alcune lingue la posizione del cursore per ogni carattere potrebbe non essere immediatamente a sinistra del carattere. Ad esempio, in ebraico, in cui il testo viene eseguito da destra a sinistra, la posizione del cursore è a destra del carattere. Se l'ordinamento del glifo viene eseguito, lpCaretPos corrisponde alla stringa originale, non alla stringa di output. Ciò significa che alcuni valori adiacenti possono essere uguali.

I valori in questa matrice sono in ordine di input. Per trovare il valore della posizione del cursore per il i^carattere nella stringa originale, usare la matrice come indicato di seguito:

position = lpCaretPos[i];

lpClass

Puntatore alla matrice che contiene e/o riceve classificazioni di caratteri. I valori indicano come disporre i caratteri nella stringa e sono simili (ma non identici) ai valori CT_CTYPE2 restituiti dalla funzione GetStringTypeEx. Ogni elemento della matrice può essere impostato su zero o uno dei valori seguenti.

Valore	Significato
GCPCLASS_ARABIC	Carattere arabo.
GCPCLASS_HEBREW	Carattere ebraico.
GCPCLASS_LATIN	Carattere da un alfabeto latino o da un altro set di caratteri a byte singolo per una lingua da sinistra a destra.
GCPCLASS_LATINNUMBER	Cifra da un alfabeto latino o da un altro set di caratteri a byte singolo per una lingua da sinistra a destra.
GCPCLASS_LOCALNUMBER	Cifra del set di caratteri associato al tipo di carattere corrente.

 

Quando si specificano valori nella matrice lpClass con il flag di GCP_CLASSIN, è inoltre possibile usare quanto segue.

Valore	Significato
GCPCLASS_LATINNUMERICSEPARATOR	Solo input. Carattere utilizzato per separare le cifre latine, ad esempio una virgola o una virgola decimale.
GCPCLASS_LATINNUMERICTERMINATOR	Solo input. Carattere utilizzato per terminare le cifre latine, ad esempio un segno più o meno.
GCPCLASS_NEUTRAL	Solo input. Il carattere non ha una classificazione specifica.
GCPCLASS_NUMERICSEPARATOR	Solo input. Carattere utilizzato per separare le cifre, ad esempio una virgola o una virgola decimale.

 

Per le lingue che usano il flag GCP_REORDER, è possibile usare anche i valori seguenti con il flag GCP_CLASSIN. A differenza dei valori precedenti, che possono essere usati ovunque nella matrice lpClass, tutti i valori seguenti vengono usati solo nella prima posizione della matrice. Tutti combinati con altre classificazioni.

Si noti che GCPCLASS_PREBOUNDLTR e GCPCLASS_PREBOUNDRTL si escludono a vicenda, come GCPCLASSPOSTBOUNDLTR e GCPCLASSPOSTBOUNDRTL.

Valore	Significato
GCPCLASS_PREBOUNDLTR	Impostare lpClass[0] su GCPCLASS_PREBOUNDLTR per associare la stringa all'ordine di lettura da sinistra a destra prima della stringa.
GCPCLASS_PREBOUNDRTL	Impostare lpClass[0] su GCPCLASS_PREBOUNDRTL per associare la stringa all'ordine di lettura da destra a sinistra prima della stringa.
GCPCLASS_POSTBOUNDLTR	Impostare lpClass[0] su GCPCLASS_POSTBOUNDLTR per associare la stringa all'ordine di lettura da sinistra a destra dopo la stringa.
GCPCLASS_POSTBOUNDRTL	Impostare lpClass[0] su GCPCLASS_POSTBOUNDRTL per associare la stringa all'ordine di lettura da destra a sinistra dopo la stringa.

 

Per forzare il layout di un carattere da eseguire in modo specifico, preimpostare la classificazione per l'elemento di matrice corrispondente; la funzione lascia invariate tali classificazioni preimpostate e calcola le classificazioni solo per gli elementi di matrice impostati su zero. Le classificazioni predefinite vengono usate solo se il flag GCP_CLASSIN è impostato e viene fornita la matrice lpClass .

Se GetFontLanguageInfo non restituisce GCP_REORDER per il tipo di carattere corrente, solo il valore GCPCLASS_LATIN è significativo.

lpGlyphs

Puntatore alla matrice che riceve i valori che identificano i glifi usati per il rendering della stringa o è NULL se il rendering del glifo non è necessario. Il numero di glifi nella matrice può essere minore del numero di caratteri nella stringa originale se la stringa contiene glifi legati. Inoltre, se è necessario riordinare, l'ordine dei glifi potrebbe non essere sequenziale.

Questa matrice è utile se vengono eseguite più operazioni su una stringa con qualsiasi forma di legatura, crenatura o cambio di ordine. L'uso dei valori in questa matrice per le operazioni successive consente di risparmiare tempo altrimenti necessario per generare gli indici del glifo ogni volta.

Questa matrice contiene sempre indici glifi e il valore ETO_GLYPH_INDEX deve essere sempre usato quando questa matrice viene usata con la funzione ExtTextOut.

Quando si utilizza GCP_LIGATE, è possibile limitare il numero di caratteri che verranno collegati tra loro. In arabo, ad esempio, le legature a tre caratteri sono comuni. Questa operazione viene eseguita impostando il valore massimo richiesto in lpGcpResults->lpGlyphs[0]. Se non è necessario alcun valore massimo, è necessario impostare questo campo su zero.

Per le lingue come l'arabo, dove GetFontLanguageInfo restituisce il flag GCP_GLYPHSHAPE, i glifi per un carattere saranno diversi a seconda che il carattere si trova all'inizio, al centro o alla fine di una parola. In genere, il primo carattere nella stringa di input sarà anche il primo carattere di una parola e l'ultimo carattere nella stringa di input verrà considerato come l'ultimo carattere in una parola. Tuttavia, se la stringa visualizzata è un subset della stringa completa, ad esempio quando viene visualizzata una sezione di testo scorrevole, questo potrebbe non essere true. In questi casi, è consigliabile forzare la forma del primo o dell'ultimo carattere come non essere forme iniziali o finali. A tale scopo, la prima posizione nella matrice lpGlyphs viene usata eseguendo un'operazione OR del valore di ligation precedente con i valori GCPGLYPH_LINKBEFORE e/o GCPGLYPH_LINKAFTER. Ad esempio, un valore di GCPGLYPH_LINKBEFORE | 2 indica che le legature a due caratteri sono il massimo richiesto e il primo carattere nella stringa deve essere considerato come se fosse al centro di una parola.

nGlyphs

All'input, questo membro deve essere impostato sulle dimensioni delle matrici a cui puntano i membri del puntatore della matrice. Nell'output, questo valore viene impostato sul numero di glifi compilati, nelle matrici di output. Se la sostituzione del glifo non è necessaria (ovvero, ogni carattere di input viene mappato esattamente a un glifo), questo membro è uguale a quello dell'input.

nMaxFit

Numero di caratteri che rientrano negli extent specificati dal parametro nMaxExtent della funzione GetCharacterPlacement. Se il valore GCP_MAXEXTENT o GCP_JUSTIFY è impostato, questo valore può essere minore del numero di caratteri nella stringa originale. Questo membro viene impostato indipendentemente dal fatto che venga specificato il valore GCP_MAXEXTENT o GCP_JUSTIFY. A differenza di nGlyphs, che specifica il numero di glifi di output, nMaxFit fa riferimento al numero di caratteri della stringa di input. Per le lingue SBCS latine, questa sarà la stessa.

Osservazioni

Se il lpGlyphs, lpOutStringo nessuno dei due elementi è necessario dipende dai risultati della chiamata GetFontLanguageInfo.

Nel caso di un tipo di carattere per una lingua come l'inglese, in cui nessuno dei flag GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC o GCP_KASHIDA vengono restituiti, nessuna delle matrici è necessaria per il corretto funzionamento. (anche se non richiesto, possono comunque essere usati. Se viene usata la matrice lpOutString , corrisponderà esattamente alla lpInputString passata a GetCharacterPlacement.) Si noti, tuttavia, che se si usa GCP_MAXEXTENT, lpOutString conterrà la stringa troncata se usata, NON una copia esatta dell'originale.

Nel caso di tipi di carattere per lingue come l'ebraico, che hanno riordinamento ma in genere non hanno forme di glifo aggiuntive, è consigliabile usare lpOutString. In questo modo la stringa verrà visualizzata nell'ordine leggibile dello schermo. Tuttavia, la matrice lpGlyphs non è in genere necessaria. L'ebraico può avere glifi aggiuntivi, se il tipo di carattere è TrueType/Open.

Nel caso di lingue come thai o arabo, in cui GetFontLanguageInfo restituisce il flag di GCP_GLYPHSHAPE, il lpOutString fornirà l'ordine leggibile della stringa passata a GetCharacterPlacement, ma i valori saranno comunque i caratteri non formattati. Per una visualizzazione corretta, è necessario usare la matrice lpGlyphs.

Nota

L'intestazione wingdi.h definisce GCP_RESULTS come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
intestazione	wingdi.h (include Windows.h)

Vedere anche

ExtTextOut

strutture di tipo carattere e testo

panoramica tipi di carattere e testo

GetCharacterPlacement

GetFontLanguageInfo