ScriptShape-Funktion (usp10.h)
Generiert Glyphen und visuelle Attribute für eine Unicode-Ausführung.
Syntax
HRESULT ScriptShape(
[in] HDC hdc,
[in, out] SCRIPT_CACHE *psc,
[in] const WCHAR *pwcChars,
[in] int cChars,
[in] int cMaxGlyphs,
[in, out] SCRIPT_ANALYSIS *psa,
[out] WORD *pwOutGlyphs,
[out] WORD *pwLogClust,
[out] SCRIPT_VISATTR *psva,
[out] int *pcGlyphs
);
Parameter
[in] hdc
Optional. Handle für den Gerätekontext. Weitere Informationen finden Sie unter Zwischenspeichern.
[in, out] psc
Zeiger auf eine SCRIPT_CACHE Struktur, die den Skriptcache identifiziert.
[in] pwcChars
Zeiger auf ein Array von Unicode-Zeichen, das die Ausführung definiert.
[in] cChars
Anzahl der Zeichen in der Unicode-Ausführung.
[in] cMaxGlyphs
Maximale Anzahl der zu generierenden Glyphen und länge von pwOutGlyphen. Ein vernünftiger Wert ist (1.5 * cChars + 16), aber dieser Wert kann unter bestimmten Umständen nicht ausreichen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in, out] psa
Zeiger auf die SCRIPT_ANALYSIS-Struktur für die Ausführung, die die Ergebnisse eines früheren Aufrufs von ScriptItemize enthält.
[out] pwOutGlyphs
Zeiger auf einen Puffer, in dem diese Funktion ein Array von Glyphen mit größe abruft, wie durch cMaxGlyphen angegeben.
[out] pwLogClust
Zeiger auf einen Puffer, in dem diese Funktion ein Array logischer Clusterinformationen abruft. Jedes Arrayelement entspricht einem Zeichen im Array von Unicode-Zeichen; daher weist dieses Array die Anzahl von Elementen auf, die durch cChars angegeben werden. Der Wert jedes Elements ist der Offset von der ersten Glyphe in der Ausführung bis zur ersten Glyphe im Cluster, die das entsprechende Zeichen enthält. Beachten Sie, dass, wenn der fRTL-Member in der SCRIPT_ANALYSIS-Struktur auf TRUE festgelegt ist, die Elemente abnehmen, wenn das Array gelesen wird.
[out] psva
Zeiger auf einen Puffer, in dem diese Funktion ein Array von SCRIPT_VISATTR Strukturen abruft, die visuelle Attributinformationen enthalten. Da jede Glyphe nur über ein visuelles Attribut verfügt, verfügt dieses Array über die Anzahl von Elementen, die durch cMaxGlyphen angegeben werden.
[out] pcGlyphs
Zeiger auf die Position, an der diese Funktion die Anzahl der in pwOutGlyphen angegebenen Glyphen abruft.
Rückgabewert
Gibt bei Erfolg 0 zurück. Die Funktion gibt einen HRESULT-Wert ungleich null zurück, wenn sie nicht erfolgreich ist. In allen Fehlerfällen ist der Inhalt aller Ausgabeparameter nicht definiert.
Fehlerrückmeldungen umfassen:
- E_OUTOFMEMORY. Die durch cMaxGlyphen angegebene Länge des Ausgabepuffers reicht nicht aus.
- E_PENDING. Der vom psc-Parameter angegebene Skriptcache enthält nicht genügend Informationen, um die Zeichenfolge zu formen, und der Gerätekontext wurde als NULL übergeben, sodass die Funktion den Strukturierungsprozess nicht abschließen kann. Die Anwendung sollte einen richtigen Gerätekontext für die Ausführung einrichten und diese Funktion erneut mit dem entsprechenden Wert in hdc und allen anderen Parametern aufrufen.
- USP_E_SCRIPT_NOT_IN_FONT. Die Schriftart, die dem Gerätekontext entspricht, unterstützt nicht das Skript, das für die ausführung erforderlich ist, die von pwcChars angegeben wird. Die Anwendung sollte eine andere Schriftart auswählen und dabei entweder ScriptGetCMap oder eine andere Funktion verwenden, um die Schriftart auszuwählen.
Hinweise
Eine Erläuterung des Kontexts, in dem diese Funktion normalerweise aufgerufen wird, finden Sie unter Anzeigen von Text mit Uniscribe .
Wenn diese Funktion E_OUTOFMEMORY zurückgibt, ruft die Anwendung ScriptShape möglicherweise wiederholt mit nacheinander größeren Ausgabepuffern auf, bis ein ausreichend großer Puffer bereitgestellt wird. Die Anzahl der von einem Codepunkt generierten Glyphen variiert je nach Skript und Schriftart. Für ein einfaches Skript kann ein Unicode-Codepunkt eine einzelne Glyphe generieren. Eine komplexe Skriptschriftart kann jedoch Zeichen aus Komponenten konstruieren und somit mehrfach so viele Glyphen wie Zeichen generieren. Außerdem gibt es Sonderfälle, z. B. ungültige Zeichendarstellungen, in denen zusätzliche Glyphen hinzugefügt werden, um die ungültige Sequenz darzustellen. Daher ist eine vernünftige Schätzung für die Größe des Puffers, der durch pwOutGlyphen angegeben wird, das 1,5-fache der Länge des Zeichenpuffers, plus zusätzliche 16 Glyphen für seltene Fälle, z. B. ungültige Sequenzdarstellung.
Diese Funktion kann den fNoGlyphIndex-Member der SCRIPT_ANALYSIS-Struktur festlegen, wenn die Schriftart oder das Betriebssystem Glyphenindizes nicht unterstützen kann.
Die Anwendung kann ScriptShape aufrufen, um zu bestimmen, ob eine Schriftart die Zeichen in einer bestimmten Zeichenfolge unterstützt. Wenn die Funktion S_OK zurückgibt, sollte die Anwendung die Ausgabe auf fehlende Glyphen überprüfen. Wenn fLogicalOrder in der SCRIPT_ANALYSIS-Struktur auf TRUE festgelegt ist, generiert die Funktion immer Glyphen in derselben Reihenfolge wie die ursprünglichen Unicode-Zeichen. Wenn fLogicalOrder auf FALSE festgelegt ist, generiert die Funktion Elemente von rechts nach links in umgekehrter Reihenfolge, sodass ScriptTextOut sie vor dem Aufruf von ExtTextOut nicht umkehren muss.
Wenn das eScript-Element von SCRIPT_ANALYSIS auf SCRIPT_UNDEFINED festgelegt ist, wird die Strukturierung deaktiviert. In diesem Fall zeigt ScriptShape die Glyphe an, die sich in der CMAP-Tabelle der Schriftart befindet. Wenn keine Glyphe in der Tabelle enthalten ist, gibt die Funktion an, dass Glyphen fehlen.
ScriptShape sequenziert Cluster innerhalb der Ausführung einheitlich und sequenziert Glyphen einheitlich innerhalb eines Clusters. Es verwendet den Wert des fRTL-Elements von SCRIPT_ANALYSIS aus ScriptItemize, um die Sequenzierung als von links nach rechts oder von rechts nach links zu identifizieren.
Beispiele
Das folgende Beispiel zeigt, wie ScriptShape ein logisches Clusterarray (pwLogClust) aus einem Zeichenarray (pwcChars) und einem Glyphenarray (pwOutGlyphen) generiert. Die Ausführung umfasst vier Cluster.
- Erster Cluster: Ein Zeichen, dargestellt durch eine Glyphe
- Zweiter Cluster: ein Zeichen, dargestellt durch drei Glyphen
- Dritter Cluster: drei Zeichen, dargestellt durch eine Glyphe
- Vierter Cluster: zwei Zeichen, dargestellt durch drei Glyphen
- | c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |
- | c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |
- | 0 | 1 | 4 4 4 | 5 5 |
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 |