ScriptStringAnalyse-Funktion (usp10.h)

Artikel
01/10/2024

Analysiert eine Nur-Text-Zeichenfolge.

Syntax

HRESULT ScriptStringAnalyse(
  [in]           HDC                    hdc,
  [in]           const void             *pString,
  [in]           int                    cString,
  [in]           int                    cGlyphs,
  [in]           int                    iCharset,
  [in]           DWORD                  dwFlags,
  [in]           int                    iReqWidth,
  [in, optional] SCRIPT_CONTROL         *psControl,
  [in, optional] SCRIPT_STATE           *psState,
  [in, optional] const int              *piDx,
  [in, optional] SCRIPT_TABDEF          *pTabdef,
  [in]           const BYTE             *pbInClass,
  [out]          SCRIPT_STRING_ANALYSIS *pssa
);

Parameter

[in] hdc

Handle für den Gerätekontext. Wenn dwFlags auf SSA_GLYPHS festgelegt ist, ist das Gerätekontexthandle erforderlich. Wenn dwFlags auf SSA_BREAK festgelegt ist, ist das Gerätekontexthandle optional. Wenn das Gerätekontexthandle bereitgestellt wird, überprüft die Funktion die aktuelle Schriftart im Gerätekontext. Wenn es sich bei der aktuellen Schriftart um eine symbolische Schriftart handelt, behandelt die Funktion die Zeichenfolge als einzelne neutrale SCRIPT_UNDEFINED Element.

[in] pString

Zeiger auf die zu analysierende Zeichenfolge. Die Zeichenfolge muss mindestens ein Zeichen aufweisen. Dies kann eine Unicode-Zeichenfolge sein oder den Zeichensatz einer Windows ANSI-Codepage verwenden, wie durch den iCharset-Parameter angegeben.

[in] cString

Länge der zu analysierenden Zeichenfolge. Die Länge wird in Zeichen für eine ANSI-Zeichenfolge oder in Breitzeichen für eine Unicode-Zeichenfolge gemessen. Die Länge muss mindestens 1 sein.

[in] cGlyphs

Größe des Glyphenpuffers in WORD-Werten. Diese Größe ist erforderlich. Die empfohlene Größe ist (1.5 * cString + 16).

[in] iCharset

Zeichensatzdeskriptor. Wenn die Eingabezeichenfolge eine ANSI-Zeichenfolge ist, wird dieser Deskriptor auf den Zeichensatzbezeichner festgelegt. Wenn die Zeichenfolge eine Unicode-Zeichenfolge ist, wird dieser Deskriptor auf -1 festgelegt.

Die folgenden Zeichensatzbezeichner sind definiert:

[in] dwFlags

Flags, die die erforderliche Analyse angeben. Dieser Parameter kann einen der in der folgenden Tabelle aufgeführten Werte aufweisen.

Wert	Bedeutung
SSA_BREAK	Ruft Unterbrechungsflags ab, d. h. Zeichen- und Wortstopps.
SSA_CLIP	Schneiden Sie die Zeichenfolge bei iReqWidth ab.
SSA_DZWG	Stellen Sie Darstellungssymbole für Steuerzeichen bereit.
SSA_FALLBACK	Verwenden Sie Fallbackschriftarten.
SSA_FIT	Rechtfertigen Sie die Zeichenfolge mit iReqWidth.
SSA_GCP	Rufen Sie fehlende Glyphen und pwLogClust mit GetCharacterPlacement-Konventionen ab .
SSA_GLYPHS	Generieren von Glyphen, Positionen und Attributen.
SSA_HIDEHOTKEY	Entfernen Sie die erste "&" aus der angezeigten Zeichenfolge.
SSA_HOTKEY	Ersetzen Sie "&" durch unterstrichen am nachfolgenden Codepunkt.
SSA_HOTKEYONLY	Nur Unterstreichung anzeigen. Das resultierende Bitmuster kann mithilfe einer XOR-Maske angezeigt werden, um die Sichtbarkeit der Hotkey-Unterstreichung umzuschalten, ohne den Text zu stören.
SSA_LINK	Wenden Sie die Verknüpfung und Zuordnung ostasiatischer Schriftarten auf nicht komplexen Text an.
SSA_METAFILE	Schreiben Sie Elemente mit ExtTextOutW-Aufrufen , nicht mit Glyphen.
SSA_PASSWORD	Doppelte Eingabezeichenfolge, die cString-Zeiten mit einem einzelnen Zeichen enthält.
SSA_RTL	Verwenden Sie die Basiseinbettungsebene 1.
SSA_TAB	Erweitern Sie Registerkarten.

[in] iReqWidth

Erforderliche Breite für die Anpassung oder Beschneidung.

[in, optional] psControl

Zeiger auf eine SCRIPT_CONTROL-Struktur . Die Anwendung kann diesen Parameter auf NULL festlegen, um anzugeben, dass alle SCRIPT_CONTROL Member auf 0 festgelegt sind.

[in, optional] psState

Zeiger auf eine SCRIPT_STATE-Struktur . Die Anwendung kann diesen Parameter auf NULL festlegen, um anzugeben, dass alle SCRIPT_STATE Member auf 0 festgelegt sind. Das uBidiLevel-Element von SCRIPT_STATE wird ignoriert. Der verwendete Wert wird vom SSA_RTL-Flag in Kombination mit dem Layout des Gerätekontexts abgeleitet.

[in, optional] piDx

Zeiger auf das angeforderte logische DX-Array.

[in, optional] pTabdef

Zeiger auf eine SCRIPT_TABDEF-Struktur . Dieser Wert ist nur erforderlich, wenn dwFlags auf SSA_TAB festgelegt ist.

[in] pbInClass

Zeiger auf einen BYTE-Wert, der GetCharacterPlacement-Zeichenklassifizierungen angibt.

[out] pssa

Zeiger auf einen Puffer, in dem diese Funktion eine SCRIPT_STRING_ANALYSIS-Struktur abruft. Diese Struktur wird bei erfolgreicher Rückgabe der Funktion dynamisch zugeordnet.

Rückgabewert

Gibt bei erfolgreicher Ausführung S_OK zurück. Die Funktion gibt einen HRESULT-Wert ungleich null zurück, wenn sie nicht erfolgreich ist.

Fehlerrückmeldungen umfassen:

E_INVALIDARG. Ein ungültiger Parameter wurde gefunden.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK wurde nicht angegeben, oder es fehlt eine Standard-Fallbackschriftart.

Die Funktion kann auch einen Systemfehler zurückgeben, der in einen HRESULT-Typ konvertiert wurde. Ein Beispiel ist ein Fehler, der aufgrund fehlenden Arbeitsspeichers oder eines GDI-Aufrufs mithilfe des Gerätekontexts zurückgegeben wird.

Hinweise

Die Verwendung dieser Funktion ist der erste Schritt bei der Behandlung von Nur-Text-Zeichenfolgen. Eine solche Zeichenfolge hat nur eine Schriftart, eine Formatvorlage, eine Größe, eine Farbe usw. ScriptStringAnalyse ordnet temporäre Puffer für Elementanalysen, Glyphen, Verschiebungsbreiten usw. zu. Anschließend wird automatisch ScriptItemize, ScriptShape, ScriptPlace und ScriptBreak ausgeführt. Die Ergebnisse sind über alle anderen ScriptString* -Funktionen verfügbar.

Bei erfolgreicher Rückgabe dieser Funktion gibt pssa eine dynamisch zugeordnete Struktur an, die die Anwendung nacheinander an die anderen ScriptString* -Funktionen übergeben kann. Die Anwendung muss die Struktur letztendlich durch Aufrufen von ScriptStringFree freigeben.

Obwohl die Funktionalität von ScriptStringAnalyse durch direkte Aufrufe anderer Funktionen implementiert werden kann, reduziert die Verwendung der Funktion selbst drastisch die Menge an Code, die in der Anwendung für die Nur-Text-Verarbeitung erforderlich 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 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