Funzione ScriptItemizeOpenType (usp10.h)

Articolo
03/03/2024

Suddivide una stringa Unicode in elementi singolarmente formabili e fornisce una matrice di tag di funzionalità per ogni elemento formabile per l'elaborazione OpenType.

Sintassi

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

Parametri

[in] pwcInChars

Puntatore a una stringa Unicode da creare.

[in] cInChars

Numero di caratteri in pwcInChars da itemizzare.

[in] cMaxItems

Numero massimo di strutture SCRIPT_ITEM che definiscono gli elementi da elaborare.

[in, optional] psControl

Puntatore a una struttura SCRIPT_CONTROL che indica il tipo di itemization da eseguire.

In alternativa, l'applicazione può impostare questo parametro su NULL se non sono necessarie proprietà SCRIPT_CONTROL . Per altre informazioni, vedere la sezione Osservazioni.

[in, optional] psState

Puntatore a una struttura SCRIPT_STATE che indica lo stato dell'algoritmo bidirezionale iniziale.

In alternativa, l'applicazione può impostare questo parametro su NULL se lo stato dello script non è necessario. Per altre informazioni, vedere la sezione Osservazioni.

[out] pItems

Puntatore a un buffer in cui la funzione recupera SCRIPT_ITEM strutture che rappresentano gli elementi elaborati. Il buffer deve essere (cMaxItems + 1) * sizeof(SCRIPT_ITEM) byte in lunghezza. Non è valido chiamare questa funzione con un buffer che gestisce meno di due strutture SCRIPT_ITEM . La funzione aggiunge sempre un elemento terminale alla matrice di analisi dell'elemento in modo che la lunghezza dell'elemento con indice "i" in base zero sia sempre disponibile come segue:

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

Puntatore a un buffer in cui la funzione recupera una matrice di strutture OPENTYPE_TAG che rappresentano i tag di script. Il buffer deve essere cMaxItems * sizeof(OPENTYPE_TAG) byte in lunghezza.

Nota Quando tutti i caratteri in un elemento sono neutrali, il valore di questo parametro è SCRIPT_TAG_UNKNOWN (0x00000000). Ciò può verificarsi, ad esempio, se un elemento è costituito interamente dalla punteggiatura.

[out] pcItems

Puntatore al numero di strutture SCRIPT_ITEM elaborate.

Valore restituito

Restituisce 0 in caso di esito positivo. La funzione restituisce un valore HRESULT diverso da zero se non riesce. In tutti i casi di errore, nessun elemento viene completamente elaborato e nessuna parte dell'output contiene valori definiti. L'applicazione può testare il valore restituito con le macro SUCCESSED e FAILED .

La funzione restituisce E_OUTOFMEMORY se le dimensioni indicate da cMaxItems sono troppo piccole. L'applicazione può provare a chiamare nuovamente la funzione con un buffer più grande.

La funzione restituisce E_INVALIDARG se si verificano una o più delle condizioni seguenti:

pwcInChars è impostato su NULL
cInChars è 0
pItems è impostato su NULL
pScriptTags è impostato su NULL
cMaxItems< 2

Commenti

ScriptItemizeOpenType è preferibile rispetto alla funzione ScriptItemize precedente. Un vantaggio di ScriptItemizeOpenType è la disponibilità di tag di funzionalità per ogni elemento formabile.

Per una discussione sul contesto in cui viene normalmente chiamata questa funzione, vedere Visualizzazione del testo con Uniscrivimento .

La funzione delimita gli elementi in base a una modifica del motore di forma o a una modifica della direzione.

L'applicazione può creare più intervalli o esecuzioni che rientrano interamente all'interno di un singolo elemento, da ogni SCRIPT_ITEM struttura recuperata da ScriptItemizeOpenType. Tuttavia, non deve combinare più elementi in una singola esecuzione. Durante la misurazione o il rendering, l'applicazione può chiamare ScriptShapeOpenType per ogni esecuzione e deve passare la struttura di SCRIPT_ANALYSIS corrispondente nella struttura SCRIPT_ITEM recuperata da ScriptItemizeOpenType.

Se il testo gestito da un'applicazione può includere qualsiasi contenuto da destra a sinistra, l'applicazione usa i parametri psControl e psState nella chiamata di ScriptItemizeOpenType. Tuttavia, l'applicazione non deve eseguire questa operazione e può gestire il testo bidirezionale stesso invece di basarsi su Uniscribe per farlo. I parametri psControl e psState sono utili in alcuni scenari strettamente da sinistra a destra, ad esempio quando il membro fLinkStringBefore di SCRIPT_CONTROL non è specifico degli script da destra a sinistra. L'applicazione imposta psControl e psState su NULL per avere ScriptItemizeOpenType interrompere la stringa Unicode puramente in base al codice carattere.

L'applicazione può impostare tutti i parametri su valori non NULL in modo che la funzione esegua un'analisi bidirezionale Unicode completa. Per consentire un'analisi bidirezionale Unicode corretta, la struttura SCRIPT_STATE deve essere inizializzata in base all'ordine di lettura all'inizio del paragrafo e ScriptItemizeOpenType deve essere passata all'intero paragrafo. In particolare, il membro uBidiLevel deve essere inizializzato su 0 per sinistra a destra e 1 per destra a sinistra.

Il membro fRTL di SCRIPT_ANALYSIS viene fatto riferimento in SCRIPT_ITEM. Il membro fNumerico di SCRIPT_PROPERTIES viene recuperato da ScriptGetProperties. Questi membri forniscono insieme la stessa classificazione del membro lpClass di GCP_RESULTS, a cui fa riferimento lpResults in GetCharacterPlacement.

Le cifre europee U+0030 a U+0039 possono essere rese come cifre nazionali, come illustrato nella tabella seguente.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Forme cifre visualizzate per Unicode U+0030 a U+0039
FALSE	Qualsiasi	Cifre europee
TRUE	FALSE	Come specificato in uDefaultLanguage membro di SCRIPT_CONTROL.
TRUE	TRUE	Come testo sicuro precedente, impostazione predefinita per il membro uDefaultLanguage di SCRIPT_CONTROL.

In modalità cifra di contesto si verifica una delle azioni seguenti:

Se lo script specificato da uDefaultLanguage si trova nella stessa direzione dell'output, tutte le cifre rilevate prima del rendering delle prime lettere vengono visualizzate nella lingua indicata da uDefaultLanguage.
Se lo script specificato da uDefaultLanguage si trova nella direzione opposta dell'output, tutte le cifre rilevate prima del rendering delle prime lettere vengono eseguite in cifre europee.

Ad esempio, se uDefaultLanguage indica LANG_ARABIC, le cifre iniziali si trovano in Arabic-Indic in un incorporamento da destra a sinistra. Tuttavia, sono in cifre europee in un incorporamento da sinistra a destra.

Per altre informazioni, vedere Forme cifre.

I caratteri e le definizioni di controllo Unicode e i relativi effetti sui membri SCRIPT_STATE vengono forniti nella tabella seguente. Per altre informazioni sui caratteri di controllo Unicode, vedere The Unicode Standard (Lo standard Unicode).

Caratteri di controllo Unicode	Significato	Effetto sull'SCRIPT_STATE
PALLE	Eseguire l'override delle cifre europee (NODS) con forme di cifre nazionali.	Impostare fDigitSubstitute.
ANNUISCE	Usare forme di cifra nominale, altrimenti note come cifre europee. Vedere NADS.	Cancella fDigitSubstitute.
CULO	Attivare lo scambio di coppie simmetriche, ad esempio parentesi. Per questi caratteri, sinistra e destra vengono interpretati come apertura e chiusura. Questo è il valore predefinito. Vedere ISS.	Cancella fInhibitSymSwap.
ISS	Inibire lo scambio di coppie simmetriche. Vedere ASS.	Impostare fInhibitSymSwap.
AAFS	Attivare la forma araba per le forme di presentazione araba. Vedere IAFS.	Impostare fCharShape.
IAFS	Inibire la forma araba, ovvero le legature e le connessioni cursive, per le forme di presentazione araba. I caratteri arabi nominale non sono interessati. Questo è il valore predefinito. Vedere AAFS.	Cancella fCharShape.

Il membro fArabicNumContext di SCRIPT_STATE supporta la visualizzazione sensibile al contesto dei numeri nel testo dello script arabo. Indica se viene eseguito il rendering delle cifre usando forme di cifre arabe native o cifre europee. All'inizio di un paragrafo, questo membro deve in genere essere inizializzato su TRUE per le impostazioni locali arabe o FALSE per qualsiasi altra impostazione locale. La funzione aggiorna lo stato dello script durante l'elaborazione del testo sicuro.

Il parametro di output pScriptTags indica una matrice con voci parallele agli elementi. Per ogni elemento, questa funzione recupera un tag di script che deve essere usato per il data shaping in tutte le operazioni successive.

Un tag di script viene in genere determinato da ScriptItemizeOpenType dai caratteri di input. Se la funzione recupera un tag di script specifico, l'applicazione deve passarla ad altre funzioni senza modifiche. Tuttavia, quando i caratteri sono neutrali (ad esempio, cifre) e lo script non può essere determinato, l'applicazione deve scegliere un tag di script appropriato, ad esempio in base al tipo di carattere e alla lingua associati al testo.

Importante A partire da Windows 8: per mantenere la possibilità di eseguire in Windows 7, un modulo che usa Uniscribe deve specificare Usp10.lib prima di gdi32.lib nell'elenco di librerie.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	usp10.h
Libreria	Usp10.lib
DLL	Usp10.dll
Componente ridistribuibile	Usp10.dll versione 1.600 o successiva in Windows XP