ScriptItemizeOpenType-Funktion (usp10.h)

Artikel
03/03/2024

Unterbricht eine Unicode-Zeichenfolge in individuell formbare Elemente und stellt ein Array von Featuretags für jedes formbare Element für die OpenType-Verarbeitung bereit.

Syntax

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
);

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 verarbeitet. 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] pScriptTags

Zeiger auf einen Puffer, in dem die Funktion ein Array von OPENTYPE_TAG Strukturen abruft, die Skripttags darstellen. Der Puffer sollte Bytes lang sein cMaxItems * sizeof(OPENTYPE_TAG) .

Hinweis Wenn alle Zeichen in einem Element neutral sind, ist der Wert dieses Parameters SCRIPT_TAG_UNKNOWN (0x00000000). Dies kann beispielsweise der Fall sein, wenn ein Element vollständig aus Interpunktion besteht.

[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. In allen Fehlerfällen werden keine Elemente vollständig verarbeitet, und kein Teil der Ausgabe enthält definierte Werte. Die Anwendung kann den Rückgabewert mit den Makros SUCCEEDED und FAILED testen.

Die Funktion gibt E_OUTOFMEMORY zurück, wenn die von cMaxItems angegebene Größe zu klein ist. Die Anwendung kann versuchen, die Funktion mit einem größeren Puffer erneut aufzurufen.

Die Funktion gibt E_INVALIDARG zurück, wenn mindestens eine der folgenden Bedingungen auftritt:

pwcInChars ist auf NULL festgelegt.
cInChars ist 0
pItems ist auf NULL festgelegt.
pScriptTags ist auf NULL festgelegt.
cMaxItems< 2

Hinweise

ScriptItemizeOpenType wird der älteren ScriptItemize-Funktion vorgezogen. Ein Vorteil von ScriptItemizeOpenType ist die Verfügbarkeit von Featuretags für jedes formbare Element.

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 in ein einzelnes Element fallen, aus jeder SCRIPT_ITEM Struktur, die von ScriptItemizeOpenType abgerufen wird. Es sollte jedoch nicht mehrere Elemente in einer einzigen Ausführung kombiniert werden. Beim Messen oder Rendern kann die Anwendung ScriptShapeOpenType für jede Ausführung aufrufen und muss die entsprechende SCRIPT_ANALYSIS-Struktur in der SCRIPT_ITEM Struktur übergeben, die von ScriptItemizeOpenType abgerufen wird.

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 ScriptItemizeOpenType. 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 ScriptItemizeOpenType 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 ScriptItemizeOpenType 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-Elementvon SCRIPT_ANALYSIS wird in SCRIPT_ITEM 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	Hemmen Sie die arabische Formbildung, also 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 kontextabhängige Anzeige von Ziffern in arabischem Skripttext. Es gibt an, ob Ziffern mit nativen arabischen Schriftzeichen oder europäischen Ziffern gerendert werden. Am Anfang eines Absatzes sollte dieser Member normalerweise als TRUE für ein arabisches Gebietsschema oder FALSE für ein anderes Gebietsschema initialisiert werden. Die Funktion aktualisiert den Skriptzustand, während sie starken Text verarbeitet.

Der Ausgabeparameter pScriptTags gibt ein Array mit Einträgen an, die parallel zu Elementen enthalten sind. Für jedes Element ruft diese Funktion ein Skripttag ab, das für die Strukturierung in allen nachfolgenden Vorgängen verwendet werden soll.

Ein Skripttag wird in der Regel durch ScriptItemizeOpenType aus Eingabezeichen bestimmt. Wenn die Funktion ein bestimmtes Skripttag abruft, sollte es von der Anwendung ohne Änderung an andere Funktionen übergeben werden. Wenn Zeichen jedoch neutral sind (z. B. Ziffern) und das Skript nicht bestimmt werden kann, sollte die Anwendung ein geeignetes Skripttag auswählen, z. B. basierend auf schriftart und sprache, die dem Text zugeordnet ist.

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 der Bibliotheksliste angeben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	usp10.h
Bibliothek	Usp10.lib
DLL	Usp10.dll
Verteilbare Komponente	Usp10.dll Version 1.600 oder höher unter Windows XP