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 dal linguaggio.

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;

Members

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 nell'ordine in cui verrà visualizzata 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 gli 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 glifi devono essere restituiti, gli indici sono per la matrice lpGlyphs ; se glifi non vengono restituiti e viene richiesto lpOrder , gli indici sono per lpOutString. Nel secondo caso, ad esempio, il valore di lpOrder[i] è la posizione di lpString[i] nella stringa di output lpOutString.

Questa operazione viene in genere usata 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 carattere}i 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 di posizione del cursore per ^{il carattere}i 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.

Inoltre, è possibile usare quanto segue quando si specificano valori nella matrice lpClass con il flag GCP_CLASSIN.

Per le lingue che usano il flag GCP_REORDER, è anche possibile usare 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.

Per forzare il layout di un carattere da eseguire in modo specifico, preimpostare la classificazione per l'elemento matrice corrispondente; la funzione lascia invariate tali classificazioni preimpostate e calcola le classificazioni solo per gli elementi di matrice che sono stati impostati su zero. Le classificazioni predefinite vengono usate solo se viene impostato il flag GCP_CLASSIN 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 di 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 necessario in lpGcpResults-lpGlyphs>[0]. Se non è richiesto alcun valore massimo, 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 sia all'inizio, al centro o alla fine di una parola. In genere, il primo carattere nella stringa di input sarà anche il primo carattere in 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 significa 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

In 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 esegue il mapping a un glifo esattamente, questo membro è uguale a quello di 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, questo sarà lo stesso.

Commenti

Indipendentemente dal fatto che lpGlyphs, lpOutString o nessuno dei due elementi sia necessario dipende dai risultati della chiamata GetFontLanguageInfo .

Nel caso di un tipo di carattere per una lingua, ad esempio 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 a lpInputString passato 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 dei tipi di carattere per le lingue come l'ebraico, che do 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 GCP_GLYPHSHAPE, lpOutString darà 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 .

Requisiti

Vedi anche

Exttextout

Strutture di tipo carattere e testo

Cenni preliminari su tipi di carattere e testo

GetCharacterPlacement

GetFontLanguageInfo