Funzione GetCharacterPlacementW (wingdi.h)

Articolo
03/08/2023

La funzione GetCharacterPlacement recupera informazioni su una stringa di caratteri, ad esempio larghezze di caratteri, posizionamento del cursore, ordinamento all'interno della stringa e rendering del glifo. Il tipo di informazioni restituite dipende dal parametro dwFlags ed è basato sul tipo di carattere attualmente selezionato nel contesto di visualizzazione specificato. La funzione copia le informazioni nella struttura GCP_RESULTS specificata o in una o più matrici specificate dalla struttura.

Anche se questa funzione era una volta adeguata per lavorare con le stringhe di caratteri, è necessario lavorare con un numero crescente di linguaggi e script ha reso obsoleto. È stata sostituita dalla funzionalità del modulo Uniscribe. Per altre informazioni, vedere Uniscribe.

È consigliabile che un'applicazione usi la funzione di GetFontLanguageInfo per determinare se i valori di GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE e GCP_KASHIDA sono validi per il tipo di carattere attualmente selezionato. Se non è valido, GetCharacterPlacement ignora il valore.

Il valore GCP_NODIACRITICS non è più definito e non deve essere usato.

Sintassi

DWORD GetCharacterPlacementW(
  [in]      HDC            hdc,
  [in]      LPCWSTR        lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSW lpResults,
  [in]      DWORD          dwFlags
);

Parametri

[in] hdc

Handle per il contesto del dispositivo.

[in] lpString

Puntatore alla stringa di caratteri da elaborare. La stringa non deve essere terminata con zero, perché nCount specifica la lunghezza della stringa.

[in] nCount

Lunghezza della stringa a cui punta lpString.

[in] nMexExtent

Extent massimo (in unità logiche) in cui viene elaborata la stringa. I caratteri che, se elaborati, superano questo extent vengono ignorati. I calcoli per qualsiasi ordinamento o matrice di glifi necessari si applicano solo ai caratteri inclusi. Questo parametro viene usato solo se il valore GCP_MAXEXTENT viene specificato nel parametro dwFlags . Poiché la funzione elabora la stringa di input, ogni carattere e il relativo extent vengono aggiunti all'output, all'extent e ad altre matrici solo se l'extent totale non ha ancora superato il valore massimo. Una volta raggiunto il limite, l'elaborazione verrà arrestata.

[in, out] lpResults

Puntatore a una struttura GCP_RESULTS che riceve i risultati della funzione.

[in] dwFlags

Specifica come elaborare la stringa nelle matrici necessarie. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
GCP_CLASSIN	Specifica che la matrice lpClass contiene classificazioni predefinite per i caratteri. Le classificazioni possono essere le stesse dell'output. Se la classificazione specifica per un carattere non è nota, la posizione corrispondente nella matrice deve essere impostata su zero. per altre informazioni sulle classificazioni, vedere GCP_RESULTS. Ciò è utile solo se GetFontLanguageInfo restituito il flag di GCP_REORDER.
GCP_DIACRITIC	Determina la modalità di gestione dei segni diacritici nella stringa. Se questo valore non è impostato, i segni diacritici vengono considerati come caratteri di larghezza zero. Ad esempio, una stringa ebraica può contenere segni diacritici, ma potrebbe non essere necessario visualizzarli. Utilizzare GetFontLanguageInfo per determinare se un tipo di carattere supporta segni diacritici. In caso affermativo, è possibile usare o meno il flag GCP_DIACRITIC nella chiamata a GetCharacterPlacement, a seconda delle esigenze dell'applicazione.
GCP_DISPLAYZWG	Per le lingue che necessitano di riordinare o diverse forme glifi a seconda delle posizioni dei caratteri all'interno di una parola, i caratteri non visualizzabili vengono spesso visualizzati nella tabella codici. Nella tabella codici ebraico, ad esempio, sono presenti indicatori diTo-Right sinistra e di destraTo-Left, per determinare il posizionamento finale dei caratteri all'interno delle stringhe di output. In genere non vengono visualizzati e vengono rimossi dalle matrici lpGlyphs e lpDx. È possibile usare il flag GCP_DISPLAYZWG per visualizzare questi caratteri.
GCP_GLYPHSHAPE	Specifica che alcuni o tutti i caratteri nella stringa devono essere visualizzati utilizzando forme diverse dalle forme standard definite nel tipo di carattere attualmente selezionato per la tabella codici corrente. Alcune lingue, ad esempio l'arabo, non possono supportare la creazione del glifo a meno che non sia specificato questo valore. Come regola generale, se GetFontLanguageInfo restituisce questo valore per una stringa, questo valore deve essere usato con GetCharacterPlacement.
GCP_JUSTIFY	Regola gli extent nella matrice lpDx in modo che la lunghezza della stringa corrisponda a nMaxExtent. GCP_JUSTIFY possono essere utilizzati solo in combinazione con GCP_MAXEXTENT.
GCP_KASHIDA	Usare anche Kashidas o, invece di, extent regolati per modificare la lunghezza della stringa in modo che sia uguale al valore specificato da nMaxExtent. Nella matrice lpDx, un Kashida è indicato da un indice di giustificazione negativo. GCP_KASHIDA possono essere utilizzati solo in combinazione con GCP_JUSTIFY e solo se il tipo di carattere (e la lingua) supportano Kashidas. Utilizzare GetFontLanguageInfo per determinare se il tipo di carattere corrente supporta Kashidas. L'uso di Kashidas per giustificare la stringa può comportare il numero di glifi necessari maggiore del numero di caratteri nella stringa di input. Per questo motivo, quando vengono usati Kashida, l'applicazione non può presupporre che l'impostazione delle matrici come dimensione della stringa di input sia sufficiente. Il valore massimo possibile sarà circa dxPageWidth/dxAveCharWidth, dove dxPageWidth è la larghezza del documento e dxAveCharWidth è la larghezza media dei caratteri restituita da una chiamata GetTextMetrics). Si noti che solo perché GetFontLanguageInfo restituisce il flag GCP_KASHIDA non significa che deve essere usato nella chiamata a GetCharacterPlacement, solo che l'opzione è disponibile.
GCP_LIGATE	Usare legazioni ovunque i caratteri ligate. Si verifica una legatura in cui viene usato un glifo per due o più caratteri. Ad esempio, le lettere a e e possono ligate a ?. Per utilizzarlo, tuttavia, sia il supporto della lingua che il tipo di carattere devono supportare i glifi necessari (l'esempio non verrà elaborato per impostazione predefinita in inglese). Utilizzare GetFontLanguageInfo per determinare se il tipo di carattere corrente supporta la ligation. In caso affermativo e per il numero di caratteri da ligate è necessario un valore massimo specifico, impostare il numero nel primo elemento della matrice lpGlyphs. Se è necessaria la ligazione normale, impostare questo valore su zero. Se non viene specificata GCP_LIGATE, non verrà eseguita alcuna ligation. Per altre informazioni, vedere GCP_RESULTS. Se il valore GCP_REORDER è in genere necessario per il set di caratteri ma non viene specificato, l'output sarà significativo a meno che la stringa passata non sia già nell'ordinamento visivo, ovvero il risultato che viene inserito in lpGcpResults->lpOutString in una chiamata a GetCharacterPlacement è la stringa di input di una seconda chiamata. Si noti che solo perché GetFontLanguageInfo restituisce il flag GCP_LIGATE non significa che deve essere usato nella chiamata a GetCharacterPlacement, solo che l'opzione è disponibile.
GCP_MAXEXTENT	Gli extent di calcolo della stringa solo a condizione che l'extent risultante, in unità logiche, non superi i valori specificati dal parametro nMaxExtent.
GCP_NEUTRALOVERRIDE	Solo determinate lingue. Eseguire l'override della normale gestione dei neutrali e considerarli come caratteri sicuri che corrispondono all'ordine di lettura delle stringhe. Utile solo con il flag GCP_REORDER.
GCP_NUMERICOVERRIDE	Solo determinate lingue. Eseguire l'override della gestione normale dei numeri e considerarli come caratteri sicuri che corrispondono all'ordine di lettura delle stringhe. Utile solo con il flag GCP_REORDER.
GCP_NUMERICSLATIN	Solo arabo/thai. Usare glifi latini standard per i numeri ed eseguire l'override del valore predefinito del sistema. Per determinare se questa opzione è disponibile nella lingua del tipo di carattere, utilizzare GetStringTypeEx per verificare se la lingua supporta più di un formato numerico.
GCP_NUMERICSLOCAL	Solo arabo/thai. Usare glifi locali per i caratteri numerici ed eseguire l'override dell'impostazione predefinita del sistema. Per determinare se questa opzione è disponibile nella lingua del tipo di carattere, utilizzare GetStringTypeEx per verificare se la lingua supporta più di un formato numerico.
GCP_REORDER	Riordinare la stringa. Usare per le lingue che non sono SBCS e l'ordine di lettura da sinistra a destra. Se questo valore non viene specificato, si presuppone che la stringa sia già nell'ordine di visualizzazione. Se questo flag è impostato per linguaggi semitici e viene utilizzata la matrice lpClass, i primi due elementi della matrice vengono usati per specificare l'ordine di lettura oltre i limiti della stringa. GCP_CLASS_PREBOUNDRTL e GCP_CLASS_PREBOUNDLTR possono essere usati per impostare l'ordine. Se non è necessario alcun ordine predefinito, impostare i valori su zero. Questi valori possono essere combinati con altri valori se è impostato il flag GCPCLASSIN. Se il valore GCP_REORDER non viene specificato, il parametro lpString viene considerato come oggetto visivo per le lingue in cui viene usato e i campi lpOutString e lpOrder vengono ignorati. Utilizzare getFontLanguageInfo per determinare se il tipo di carattere corrente supporta il riordinamento.
GCP_SYMSWAPOFF	Solo lingue semitiche. Specifica che i caratteri scambiabili non vengono reimpostati. Ad esempio, in una stringa da destra a sinistra, '(' e ')' non vengono invertiti.
GCP_USEKERNING	Usare coppie di crenatura nel tipo di carattere (se presente) durante la creazione delle matrici di larghezze. Utilizzare GetFontLanguageInfo per determinare se il tipo di carattere corrente supporta le coppie di crenatura. Si noti che solo perché GetFontLanguageInfo restituisce il flag GCP_USEKERNING non significa che deve essere usato nella chiamata a GetCharacterPlacement, solo che l'opzione è disponibile. La maggior parte dei tipi di carattere TrueType ha una tabella di crenatura, ma non è necessario usarla.

Il valore GCP_NODIACRITICS non è più definito e non deve essere usato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la larghezza e l'altezza della stringa in unità logiche. La larghezza è la parola in ordine basso e l'altezza è la parola di ordine elevato.

Se la funzione ha esito negativo, il valore restituito è zero.

Osservazioni

GetCharacterPlacement assicura che un'applicazione possa elaborare correttamente il testo indipendentemente dall'impostazione internazionale e dal tipo di tipi di carattere disponibili. Le applicazioni usano questa funzione prima di usare la funzione ExtTextOut e al posto della funzione GetTextExtentPoint32 (e occasionalmente al posto della GetCharWidth32 e funzioni getCharABCWidths).

L'uso di GetCharacterPlacement per recuperare la spaziatura intercaracter e le matrici di indici non è sempre necessario a meno che non sia necessaria una giustificazione o una crenatura. Per i tipi di carattere non latini, le applicazioni possono migliorare la velocità con cui la funzione ExtTextOut esegue il rendering del testo usando GetCharacterPlacement per recuperare la spaziatura intercaracter e le matrici di indici prima di chiamare ExtTextOut. Ciò è particolarmente utile quando si esegue ripetutamente il rendering dello stesso testo o quando si usa la spaziatura intercaracter per posizionare il cursore. Se la matrice di output lpGlyphs viene usata nella chiamata a ExtTextOut, è necessario impostare il flag ETO_GLYPH_INDEX.

GetCharacterPlacement controlla l'lpOrder, lpDX, lpCaretPos, le lpGlyphs membri della struttura GCP_RESULTS e riempie le matrici corrispondenti se questi membri non sono impostati su NULL. Se GetCharacterPlacement non è in grado di riempire una matrice, imposta il membro corrispondente su NULL. Per garantire il recupero di informazioni valide, l'applicazione è responsabile dell'impostazione del membro su un indirizzo valido prima di chiamare la funzione e di controllare il valore del membro dopo la chiamata. Se vengono specificati i valori di GCP_JUSTIFY o GCP_USEKERNING, i membri lpDX e/o lpCaretPos membri devono avere indirizzi validi.

Si noti che gli indici del glifo restituiti in GCP_RESULTS.lpGlyphs sono specifici del tipo di carattere corrente nel contesto del dispositivo e devono essere usati solo per disegnare testo nel contesto di dispositivo mentre il tipo di carattere rimane selezionato.

Quando si calcola una giustificazione, se i caratteri finali nella stringa sono spazi, la funzione riduce la lunghezza della stringa e rimuove gli spazi prima di calcolare la giustificazione. Se la matrice è costituita solo da spazi, la funzione restituisce un errore.

ExtTextOut prevede una voce lpDX per ogni byte di una stringa DBCS, mentre GetCharacterPlacement assegna una voce lpDX per ogni glifo. Per correggere questa mancata corrispondenza quando si usa questa combinazione di funzioni, usare GetGlyphIndices o espandere la matrice lpDX con voci di larghezza zero per il secondo byte corrispondente di una coppia di byte DBCS.

Se la larghezza logica è minore della larghezza del carattere iniziale nella stringa di input, GCP_RESULTS.nMaxFit restituisce un valore non valido. In questo caso, chiamare GetCharacterPlacement per gli indici glifi e la matrice lpDX . Usare quindi la matrice lpDX per eseguire il calcolo dell'extent usando la larghezza avanzata di ogni carattere, dove nMaxFit è il numero di caratteri i cui indici glifi avanzano di larghezza è inferiore alla larghezza del carattere iniziale.

Nota

L'intestazione wingdi.h definisce GetCharacterPlacement 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]
piattaforma di destinazione	Finestre
intestazione	wingdi.h (include Windows.h)
libreria	Gdi32.lib
dll	Gdi32.dll