ScriptItemize-Funktion (usp10.h)

Artikel
03/03/2024

Unterbricht eine Unicode-Zeichenfolge in individuell formbare Elemente.

Syntax

HRESULT ScriptItemize(
  [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]          int                  *pcItems
);

Parameter

[in] pwcInChars

Zeiger auf eine Unicode-Zeichenfolge, die elementiert werden soll.

[in] cInChars

Anzahl der zeichen in pwcInChars , die zugeordnet werden sollen.

[in] cMaxItems

Maximale Anzahl von SCRIPT_ITEM Strukturen, die zu verarbeitende Elemente definieren.

[in, optional] psControl

Zeiger auf eine SCRIPT_CONTROL Struktur, die den Typ der auszuführenden Elementisierung angibt.

Alternativ kann die Anwendung diesen Parameter auf NULL festlegen, wenn keine SCRIPT_CONTROL Eigenschaften erforderlich sind. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in, optional] psState

Zeiger auf eine SCRIPT_STATE-Struktur , die den anfänglichen bidirektionalen Algorithmuszustand angibt.

Alternativ kann die Anwendung diesen Parameter auf NULL festlegen, wenn der Skriptstatus nicht benötigt wird. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[out] pItems

Zeiger auf einen Puffer, in dem die Funktion SCRIPT_ITEM Strukturen abruft, die die verarbeiteten Elemente darstellen. Der Puffer sollte Bytes lang sein (cMaxItems + 1) * sizeof(SCRIPT_ITEM) . Es ist ungültig, diese Funktion mit einem Puffer aufzurufen, der weniger als zwei SCRIPT_ITEM Strukturen enthält. Die Funktion fügt dem Elementanalysearray immer ein Terminalelement hinzu, sodass die Länge des Elements mit nullbasiertem Index "i" immer als verfügbar ist:

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

[out] pcItems

Zeiger auf die Anzahl der verarbeiteten SCRIPT_ITEM Strukturen.

Rückgabewert

Gibt bei Erfolg 0 zurück. Die Funktion gibt einen nichtzero-HRESULT-Wert zurück, wenn er nicht erfolgreich ist.

Die Funktion gibt E_INVALIDARG zurück, wenn pwcInChars auf NULL, cInChars auf 0, pItems auf NULL oder cMaxItems< 2 festgelegt ist.

Die Funktion gibt E_OUTOFMEMORY zurück, wenn der Wert von cMaxItems nicht ausreicht. Wie in allen Fehlerfällen werden keine Elemente vollständig verarbeitet und kein Teil des Ausgabearrays enthält definierte Werte. Wenn die Funktion E_OUTOFMEMORY zurückgibt, kann die Anwendung sie mit einem größeren pItems-Puffer erneut aufrufen.

Hinweise

Eine Diskussion über den Kontext, in dem diese Funktion normalerweise aufgerufen wird, finden Sie unter Anzeigen von Text mit Uniscribe .

Die Funktion schränkt Elemente entweder durch eine Änderung der Formgebungs-Engine oder eine Richtungsänderung ab.

Die Anwendung kann mehrere Bereiche erstellen oder ausführen, die vollständig innerhalb eines einzelnen Elements liegen, und zwar von jeder SCRIPT_ITEM Struktur, die von ScriptItemize abgerufen wird. Es sollte jedoch nicht mehrere Elemente in einer einzigen Ausführung kombiniert werden. Später kann die Anwendung beim Messen oder Rendern ScriptShape für jede Ausführung aufrufen und muss die von ScriptItemize abgerufene SCRIPT_ANALYSIS Struktur in der SCRIPT_ITEM-Struktur übergeben.

Wenn der von einer Anwendung behandelte Text beliebige Inhalte von rechts nach links enthalten kann, verwendet die Anwendung die Parameter psControl und psState beim Aufrufen von ScriptItemize. Die Anwendung muss dies jedoch nicht tun und kann bidirektionalen Text selbst verarbeiten, anstatt sich hierfür auf Uniscribe zu verlassen. Die Parameter psControl und psState sind in einigen szenarien von links nach rechts nützlich, z. B. wenn das fLinkStringBefore-Element von SCRIPT_CONTROL nicht spezifisch für Rechts-nach-links-Skripts ist. Die Anwendung legt psControl und psState auf NULL fest, damit ScriptItemize die Unicode-Zeichenfolge rein nach Zeichencode unterbricht.

Die Anwendung kann alle Parameter auf Werte ohne NULL festlegen, damit die Funktion eine vollständige bidirektionale Unicode-Analyse durchführt. Um eine korrekte bidirektionale Unicode-Analyse zu ermöglichen, sollte die SCRIPT_STATE-Struktur entsprechend der Lesereihenfolge beim Absatzstart initialisiert werden, und ScriptItemize sollte der gesamte Absatz übergeben werden. Insbesondere sollte das uBidiLevel-Element auf 0 für von links nach rechts und 1 für von rechts nach links initialisiert werden.

Auf das fRTL-Element von SCRIPT_ANALYSIS wird in SCRIPT_ITEM enabled="1" verwiesen. Das fNumeric-Element von SCRIPT_PROPERTIES wird von ScriptGetProperties abgerufen. Diese Member bieten zusammen dieselbe Klassifizierung wie das lpClass-Member von GCP_RESULTS, auf das von lpResults in GetCharacterPlacement verwiesen wird.

Die europäischen Ziffern U+0030 bis U+0039 können als nationale Ziffern gerendert werden, wie in der folgenden Tabelle dargestellt.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Für Unicode U+0030 bis U+0039 angezeigte Ziffernformen
FALSE	Any	Europäische Ziffern
TRUE	FALSE	Wie im uDefaultLanguage-Member von SCRIPT_CONTROL angegeben.
TRUE	TRUE	Wie zuvor stark text, wird standardmäßig uDefaultLanguage-Member von SCRIPT_CONTROL verwendet.

Im Kontextstellenmodus wird eine der folgenden Aktionen ausgeführt:

Wenn sich das von uDefaultLanguage angegebene Skript in der gleichen Richtung wie die Ausgabe befindet, werden alle Ziffern, die vor den ersten Buchstaben gefunden wurden, in der sprache gerendert, die von uDefaultLanguage angegeben wird.
Wenn sich das von uDefaultLanguage angegebene Skript in die entgegengesetzte Richtung zur Ausgabe befindet, werden alle Ziffern, die vor den ersten Buchstaben gefunden wurden, in europäischen Ziffern gerendert.

Wenn uDefaultLanguage beispielsweise LANG_ARABIC angibt, befinden sich die Anfangsziffern in einer Einbettung von rechts nach links in Arabic-Indic. Sie befinden sich jedoch in europäischen Ziffern in einer Einbettung von links nach rechts.

Weitere Informationen finden Sie unter Digit Shapes.

Die Unicode-Steuerelementzeichen und -Definitionen sowie ihre Auswirkungen auf SCRIPT_STATE Member sind in der folgenden Tabelle aufgeführt. Weitere Informationen zu Unicode-Steuerelementzeichen finden Sie im Unicode-Standard.

Unicode-Steuerelementzeichen	Bedeutung	Auswirkungen auf SCRIPT_STATE
NADS	Überschreiben Sie europäische Ziffern (NODS) mit nationalen Ziffernformen.	Legen Sie fDigitSubstitute fest.
NICKT	Verwenden Sie nominale Ziffernformen, die auch als europäische Ziffern bezeichnet werden. Siehe NADS.	Löschen Sie fDigitSubstitute.
ARSCH	Aktivieren Sie den Austausch von symmetrischen Paaren, z. B. Klammern. Für diese Zeichen werden links und rechts als öffnend und schließend interpretiert. Dies ist die Standardoption. Siehe ISS.	Löschen Sie fInhibitSymSwap.
ISS	Hemmt den Austausch von symmetrischen Paaren. Siehe ASS.	Legen Sie fInhibitSymSwap fest.
AAFS	Aktivieren Sie die arabische Formularformung für arabische Präsentationsformulare. Siehe IAFS.	Legen Sie fCharShape fest.
IAFS	Hemmt arabische Formformung, d. h. Ligaturen und cursive Verbindungen, für arabische Präsentationsformen. Nominale arabische Zeichen sind nicht betroffen. Dies ist die Standardoption. Siehe AAFS.	Löschen Sie fCharShape.

Das fArabicNumContext-Element von SCRIPT_STATE unterstützt die kontextsensitive Anzeige von Zahlen im arabischen Skripttext. Es gibt an, ob Ziffern mit nativen arabischen Zeichenzeichen oder europäischen Ziffern gerendert werden. Am Anfang eines Absatzes sollte dieses Element normalerweise als TRUE für ein arabisches Gebietsschema oder false für ein anderes Gebietsschema initialisiert werden. Die Funktion aktualisiert den Skriptstatus, während sie Starktext verarbeitet.

Wichtig Ab Windows 8: Um die Ausführung unter Windows 7 zu gewährleisten, muss ein Modul, das Uniscribe verwendet, Usp10.lib vor gdi32.lib in seiner Bibliotheksliste angeben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	usp10.h
Bibliothek	Usp10.lib
DLL	Usp10.dll
Verteilbare Komponente	Internet Explorer 5 oder höher unter Windows Me/98/95