GetCharacterPlacementW-Funktion (wingdi.h)

Artikel
08/27/2023

Die GetCharacterPlacement-Funktion ruft Informationen zu einer Zeichenfolge ab, z. B. Zeichenbreiten, Caretpositionierung, Reihenfolge innerhalb der Zeichenfolge und Glyphenrendering. Der Typ der zurückgegebenen Informationen hängt vom dwFlags-Parameter ab und basiert auf der aktuell ausgewählten Schriftart im angegebenen Anzeigekontext. Die Funktion kopiert die Informationen in die angegebene GCP_RESULTS-Struktur oder in ein oder mehrere Arrays, die von der -Struktur angegeben werden.

Obwohl diese Funktion einst für die Arbeit mit Zeichenfolgen ausreichend war, hat die Notwendigkeit, mit einer wachsenden Anzahl von Sprachen und Skripts zu arbeiten, sie veraltet gemacht. Es wurde durch die Funktionalität des Uniscribe-Moduls abgelöst. Weitere Informationen finden Sie unter Uniscribe.

Es wird empfohlen, dass eine Anwendung die GetFontLanguageInfo-Funktion verwendet, um zu bestimmen, ob die Werte GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE und GCP_KASHIDA für die aktuell ausgewählte Schriftart gültig sind. Wenn nicht gültig, ignoriert GetCharacterPlacement den Wert.

Der GCP_NODIACRITICS Wert ist nicht mehr definiert und sollte nicht verwendet werden.

Syntax

DWORD GetCharacterPlacementW(
  [in]      HDC            hdc,
  [in]      LPCWSTR        lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSW lpResults,
  [in]      DWORD          dwFlags
);

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] lpString

Ein Zeiger auf die zu verarbeitende Zeichenfolge. Die Zeichenfolge muss nicht mit Null beendet werden, da nCount die Länge der Zeichenfolge angibt.

[in] nCount

Die Länge der Zeichenfolge , auf die lpString verweist.

[in] nMexExtent

Der maximale Umfang (in logischen Einheiten), bis zu dem die Zeichenfolge verarbeitet wird. Zeichen, die diesen Wertbereich bei Verarbeitung überschreiten würden, werden ignoriert. Berechnungen für alle erforderlichen Reihenfolge- oder Glyphenarrays gelten nur für die enthaltenen Zeichen. Dieser Parameter wird nur verwendet, wenn der GCP_MAXEXTENT-Wert im dwFlags-Parameter angegeben ist. Da die Funktion die Eingabezeichenfolge verarbeitet, wird jedes Zeichen und sein Wertebereich nur dann der Ausgabe, dem Wertebereich und anderen Arrays hinzugefügt, wenn der gesamte Wertebereich das Maximum noch nicht überschritten hat. Bei Erreichen des Limits wird die Verarbeitung beendet.

[in, out] lpResults

Ein Zeiger auf eine GCP_RESULTS-Struktur , die die Ergebnisse der Funktion empfängt.

[in] dwFlags

Gibt das Verarbeiten der Zeichenfolge in die erforderlichen Arrays an. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
GCP_CLASSIN	Gibt an, dass das lpClass-Array voreingestellte Klassifizierungen für Zeichen enthält. Die Klassifizierungen können mit den Klassifizierungen bei der Ausgabe identisch sein. Wenn die bestimmte Klassifizierung für ein Zeichen nicht bekannt ist, muss die entsprechende Position im Array auf 0 (null) festgelegt werden. Weitere Informationen zu den Klassifizierungen finden Sie unter GCP_RESULTS. Dies ist nur nützlich, wenn GetFontLanguageInfo das flag GCP_REORDER zurückgegeben hat.
GCP_DIACRITIC	Bestimmt, wie diakritische Zeichen in der Zeichenfolge behandelt werden. Wenn dieser Wert nicht festgelegt ist, werden diakritische Zeichen als Zeichen der Breite null behandelt. Beispielsweise kann eine hebräische Zeichenfolge diakritische Zeichen enthalten, aber Sie möchten sie möglicherweise nicht anzeigen. Verwenden Sie GetFontLanguageInfo , um zu bestimmen, ob eine Schriftart diakritische Zeichen unterstützt. Wenn dies der Fall ist, können Sie je nach Den Anforderungen Ihrer Anwendung das Flag GCP_DIACRITIC im Aufruf von GetCharacterPlacement verwenden oder nicht.
GCP_DISPLAYZWG	Bei Sprachen, die je nach Position der Zeichen in einem Wort eine Neuanordnung oder unterschiedliche Glyphenformen erfordern, werden häufig nicht angezeigte Zeichen auf der Codepage angezeigt. Auf der hebräischen Codepage gibt es z. B. Die Markierungen von links nach rechts und rechts nach links, um die endgültige Positionierung von Zeichen in den Ausgabezeichenfolgen zu bestimmen. Normalerweise werden diese nicht angezeigt und aus den lpGlyphen - und lpDx-Arrays entfernt. Sie können das flag GCP_DISPLAYZWG verwenden, um diese Zeichen anzuzeigen.
GCP_GLYPHSHAPE	Gibt an, dass einige oder alle Zeichen in der Zeichenfolge mit anderen Formen als den Standardformen angezeigt werden sollen, die in der aktuell ausgewählten Schriftart für die aktuelle Codepage definiert sind. Einige Sprachen, z. B. Arabisch, können die Erstellung von Glyphen nicht unterstützen, es sei denn, dieser Wert wird angegeben. Im Allgemeinen gilt: Wenn GetFontLanguageInfo diesen Wert für eine Zeichenfolge zurückgibt, muss dieser Wert mit GetCharacterPlacement verwendet werden.
GCP_JUSTIFY	Passt die Blöcke im lpDx-Array so an, dass die Länge der Zeichenfolge identisch mit nMaxExtent ist. GCP_JUSTIFY dürfen nur in Verbindung mit GCP_MAXEXTENT verwendet werden.
GCP_KASHIDA	Verwenden Sie Kashidas sowie oder anstelle von angepassten Blöcken, um die Länge der Zeichenfolge so zu ändern, dass sie dem von nMaxExtent angegebenen Wert entspricht. Im lpDx-Array wird eine Kashida durch einen negativen Begründungsindex angegeben. GCP_KASHIDA dürfen nur in Verbindung mit GCP_JUSTIFY und nur verwendet werden, wenn die Schriftart (und Sprache) Kashidas unterstützen. Verwenden Sie GetFontLanguageInfo , um zu bestimmen, ob die aktuelle Schriftart Kashidas unterstützt. Die Verwendung von Kashidas zum Rechtfertigen der Zeichenfolge kann dazu führen, dass die Anzahl der erforderlichen Glyphen größer ist als die Anzahl der Zeichen in der Eingabezeichenfolge. Daher kann die Anwendung bei Verwendung von Kashidas nicht davon ausgehen, dass das Festlegen der Arrays auf die Größe der Eingabezeichenfolge ausreichend ist. (Der maximal mögliche Wert beträgt ungefähr dxPageWidth/dxAveCharWidth, wobei dxPageWidth die Breite des Dokuments und dxAveCharWidth die durchschnittliche Zeichenbreite ist, die von einem GetTextMetrics-Aufruf zurückgegeben wird. Beachten Sie, dass nur weil GetFontLanguageInfo das flag GCP_KASHIDA zurückgibt, nicht bedeutet, dass es im Aufruf von GetCharacterPlacement verwendet werden muss, nur dass die Option verfügbar ist.
GCP_LIGATE	Verwenden Sie Ligations überall dort, wo Zeichen ligaieren. Eine Ligation tritt auf, wenn eine Glyphe für zwei oder mehr Zeichen verwendet wird. Beispielsweise können die Buchstaben a und e zu ? ligaieren. Damit dies verwendet werden kann, müssen jedoch sowohl die Sprachunterstützung als auch die Schriftart die erforderlichen Glyphen unterstützen (das Beispiel wird standardmäßig nicht in Englisch verarbeitet). Verwenden Sie GetFontLanguageInfo , um zu bestimmen, ob die aktuelle Schriftart Ligation unterstützt. Wenn dies der Fall ist und ein bestimmtes Maximum für die Anzahl der Zeichen erforderlich ist, die ligate, legen Sie die Zahl im ersten Element des lpGlyphs-Arrays fest. Wenn eine normale Ligation erforderlich ist, legen Sie diesen Wert auf 0 (null) fest. Wenn GCP_LIGATE nicht angegeben ist, findet keine Ligation statt. Weitere Informationen finden Sie unter GCP_RESULTS. Wenn der GCP_REORDER Wert normalerweise für den Zeichensatz erforderlich, aber nicht angegeben wird, ist die Ausgabe bedeutungslos, es sei denn, die übergebene Zeichenfolge befindet sich bereits in visueller Reihenfolge (d. h. das Ergebnis, das in einem Aufruf von GetCharacterPlacement in lpGcpResults-lpOutString> eingefügt wird, ist die Eingabezeichenfolge eines zweiten Aufrufs). Beachten Sie, dass nur weil GetFontLanguageInfo das GCP_LIGATE Flag zurückgibt, nicht bedeutet, dass es im Aufruf von GetCharacterPlacement verwendet werden muss, nur dass die Option verfügbar ist.
GCP_MAXEXTENT	Computeausdehnungen der Zeichenfolge nur, solange der resultierende Bereich in logischen Einheiten die vom nMaxExtent-Parameter angegebenen Werte nicht überschreitet.
GCP_NEUTRALOVERRIDE	Nur bestimmte Sprachen. Überschreiben Sie die normale Behandlung von Neutralen, und behandeln Sie sie als starke Zeichen, die der Lesereihenfolge der Zeichenfolgen entsprechen. Nur mit dem flag GCP_REORDER nützlich.
GCP_NUMERICOVERRIDE	Nur bestimmte Sprachen. Überschreiben Sie die normale Behandlung von Numerischen, und behandeln Sie sie als starke Zeichen, die der Lesereihenfolge der Zeichenfolgen entsprechen. Nur mit dem flag GCP_REORDER nützlich.
GCP_NUMERICSLATIN	Nur Arabisch/Thailändisch. Verwenden Sie standardlateinische Glyphen für Zahlen, und setzen Sie den Systemstandard außer Kraft. Um festzustellen, ob diese Option in der Sprache der Schriftart verfügbar ist, verwenden Sie GetStringTypeEx , um festzustellen, ob die Sprache mehrere Zahlenformate unterstützt.
GCP_NUMERICSLOCAL	Nur Arabisch/Thailändisch. Verwenden Sie lokale Glyphen für numerische Zeichen, und setzen Sie den Systemstandard außer Kraft. Um festzustellen, ob diese Option in der Sprache der Schriftart verfügbar ist, verwenden Sie GetStringTypeEx , um festzustellen, ob die Sprache mehrere Zahlenformate unterstützt.
GCP_REORDER	Ordnen Sie die Zeichenfolge neu an. Verwenden Sie für Sprachen, die nicht SBCS und leserichtung von links nach rechts sind. Wenn dieser Wert nicht angegeben wird, wird davon ausgegangen, dass sich die Zeichenfolge bereits in der Anzeigereihenfolge befindet. Wenn dieses Flag für semitische Sprachen festgelegt ist und das lpClass-Array verwendet wird, werden die ersten beiden Elemente des Arrays verwendet, um die Lesereihenfolge über die Grenzen der Zeichenfolge hinaus anzugeben. GCP_CLASS_PREBOUNDRTL und GCP_CLASS_PREBOUNDLTR können verwendet werden, um die Reihenfolge festzulegen. Wenn keine voreingestellte Reihenfolge erforderlich ist, legen Sie die Werte auf Null fest. Diese Werte können mit anderen Werten kombiniert werden, wenn das GCPCLASSIN-Flag festgelegt ist. Wenn der GCP_REORDER Wert nicht angegeben wird, wird der lpString-Parameter für Sprachen, in denen dies verwendet wird, visuell sortiert, und die Felder lpOutString und lpOrder werden ignoriert. Verwenden Sie GetFontLanguageInfo , um zu bestimmen, ob die aktuelle Schriftart eine Neuanordnung unterstützt.
GCP_SYMSWAPOFF	Nur semitische Sprachen. Gibt an, dass austauschbare Zeichen nicht zurückgesetzt werden. In einer Zeichenfolge von rechts nach links werden z. B. die "(' und ')" nicht umgekehrt.
GCP_USEKERNING	Verwenden Sie Kerningpaare in der Schriftart (sofern vorhanden), wenn Sie die Arrays für die Breite erstellen. Verwenden Sie GetFontLanguageInfo , um zu bestimmen, ob die aktuelle Schriftart Kerningpaare unterstützt. Beachten Sie, dass nur weil GetFontLanguageInfo das flag GCP_USEKERNING zurückgibt, nicht bedeutet, dass es im Aufruf von GetCharacterPlacement verwendet werden muss, nur dass die Option verfügbar ist. Die meisten TrueType-Schriftarten verfügen über eine Kerningtabelle, aber Sie müssen sie nicht verwenden.

Der GCP_NODIACRITICS Wert ist nicht mehr definiert und sollte nicht verwendet werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, handelt es sich bei dem Rückgabewert um die Breite und Höhe der Zeichenfolge in logischen Einheiten. Die Breite ist das Wort mit niedriger Ordnung, und die Höhe ist das Wort mit hoher Ordnung.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.

Hinweise

GetCharacterPlacement stellt sicher, dass eine Anwendung Text unabhängig von der internationalen Einstellung und dem typ der verfügbaren Schriftarten ordnungsgemäß verarbeiten kann. Anwendungen verwenden diese Funktion vor der Verwendung der ExtTextOut-Funktion und anstelle der GetTextExtentPoint32-Funktion (und gelegentlich anstelle der Funktionen GetCharWidth32 und GetCharABCWidths ).

Die Verwendung von GetCharacterPlacement zum Abrufen von Interzeichenabstand und Indexarrays ist nicht immer erforderlich, es sei denn, es ist eine Begründung oder kerning erforderlich. Bei nicht lateinischen Schriftarten können Anwendungen die Geschwindigkeit verbessern, mit der die ExtTextOut-Funktion Text rendert, indem Sie GetCharacterPlacement verwenden, um den Interzeichenabstand und die Indexarrays vor dem Aufruf von ExtTextOut abzurufen. Dies ist besonders nützlich, wenn derselbe Text wiederholt gerendert wird oder wenn sie den Zeichenabstand zum Positionieren des Carets verwenden. Wenn das lpGlyphs-Ausgabearray beim Aufruf von ExtTextOut verwendet wird, muss das flag ETO_GLYPH_INDEX festgelegt werden.

GetCharacterPlacement überprüft die Elemente lpOrder, lpDX, lpCaretPos, lpOutString und lpGlyphen der GCP_RESULTS-Struktur und füllt die entsprechenden Arrays aus, wenn diese Member nicht auf NULL festgelegt sind. Wenn GetCharacterPlacement kein Array ausfüllen kann, wird das entsprechende Element auf NULL festgelegt. Um den Abruf gültiger Informationen sicherzustellen, ist die Anwendung dafür verantwortlich, den Member vor dem Aufruf der Funktion auf eine gültige Adresse festzulegen und den Wert des Members nach dem Aufruf zu überprüfen. Wenn die GCP_JUSTIFY- oder GCP_USEKERNING-Werte angegeben sind, müssen die lpDX - und/oder lpCaretPos-Member über gültige Adressen verfügen.

Beachten Sie, dass die in GCP_RESULTS.lpGlyphen zurückgegebenen Glyphenindizes für die aktuelle Schriftart im Gerätekontext spezifisch sind und nur zum Zeichnen von Text im Gerätekontext verwendet werden sollten, während diese Schriftart ausgewählt bleibt.

Wenn beim Berechnen der Begründung die nachfolgenden Zeichen in der Zeichenfolge Leerzeichen sind, reduziert die Funktion die Länge der Zeichenfolge und entfernt die Leerzeichen vor dem Berechnen der Begründung. Wenn das Array nur aus Leerzeichen besteht, gibt die Funktion einen Fehler zurück.

ExtTextOut erwartet einen lpDX-Eintrag für jedes Byte einer DBCS-Zeichenfolge, während GetCharacterPlacement für jede Glyphe einen lpDX-Eintrag zuweist. Um diesen Konflikt bei Verwendung dieser Funktionskombination zu beheben, verwenden Sie entweder GetGlyphIndices , oder erweitern Sie das lpDX-Array mit Nullbreiteneinträgen für das entsprechende zweite Byte eines DBCS-Bytepaars.

Wenn die logische Breite kleiner als die Breite des führenden Zeichens in der Eingabezeichenfolge ist, gibt GCP_RESULTS.nMaxFit einen ungültigen Wert zurück. Rufen Sie in diesem Fall GetCharacterPlacement für Glyphenindizes und das lpDX-Array auf. Verwenden Sie dann das lpDX-Array , um die Ausdehnungsberechnung mit der erweiterten Breite jedes Zeichens durchzuführen, wobei nMaxFit die Anzahl von Zeichen ist, deren Glyphenvorschubbreite kleiner als die Breite des führenden Zeichens ist.

Hinweis

Der wingdi.h-Header definiert GetCharacterPlacement als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wingdi.h (windows.h einschließen)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll