GetCharacterPlacementA-Funktion (wingdi.h)

Artikel
11/20/2024

Die GetCharacterPlacement Funktion ruft Informationen zu einer Zeichenfolge ab, z. B. Zeichenbreiten, Caretpositionierung, Sortierung 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 auf ein oder mehrere Arrays, die durch die Struktur angegeben sind.

Obwohl diese Funktion einst für die Arbeit mit Zeichenfolgen ausreichend war, muss mit einer zunehmenden Anzahl von Sprachen und Skripts gearbeitet werden, die sie veraltet gemacht haben. Es wurde durch die Funktionalität des Uniscribe-Moduls ersetzt. 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 dies nicht gültig ist, ignoriert GetCharacterPlacement den Wert.

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

Syntax

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA 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 null beendet werden, da nCount die Länge der Zeichenfolge angibt.

[in] nCount

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

[in] nMexExtent

Der maximale Umfang (in logischen Einheiten), zu dem die Zeichenfolge verarbeitet wird. Zeichen, die bei der Verarbeitung dieses Umfangs überschreiten würden, werden ignoriert. Berechnungen für alle erforderlichen Sortier- oder Glyphenarrays gelten nur für die enthaltenen Zeichen. Dieser Parameter wird nur verwendet, wenn der GCP_MAXEXTENT Wert im dwFlags Parameter angegeben wird. Wenn die Funktion die Eingabezeichenfolge verarbeitet, wird jedes Zeichen und sein Umfang nur dann zur Ausgabe, zum Umfang und anderen Arrays hinzugefügt, wenn der Gesamtumfang noch nicht das Maximum überschritten hat. Sobald der Grenzwert erreicht ist, wird die Verarbeitung beendet.

[in, out] lpResults

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

[in] dwFlags

Gibt an, wie die Zeichenfolge in die erforderlichen Arrays verarbeitet wird. Dieser Parameter kann einen oder mehrere der folgenden Werte sein.

Wert	Bedeutung
GCP_CLASSIN	Gibt an, dass das lpClass Array voreingestellte Klassifizierungen für Zeichen enthält. Die Klassifizierungen können mit der Ausgabe identisch sein. Wenn die bestimmte Klassifizierung für ein Zeichen nicht bekannt ist, muss die entsprechende Position im Array auf Null festgelegt werden. weitere Informationen zu den Klassifizierungen finden Sie unter GCP_RESULTS. Dies ist nur hilfreich, wenn GetFontLanguageInfo das GCP_REORDER Flag 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 mit nuller Breite behandelt. Eine hebräische Zeichenfolge kann z. B. diakritische Zeichen enthalten, sie können jedoch nicht angezeigt werden. Verwenden Sie GetFontLanguageInfo-, um zu bestimmen, ob eine Schriftart diakritische Zeichen unterstützt. Wenn dies der Fall ist, können Sie das GCP_DIACRITIC Flag im Aufruf von GetCharacterPlacementverwenden oder nicht verwenden, je nach den Anforderungen Ihrer Anwendung.
GCP_DISPLAYZWG	Bei Sprachen, die abhängig von den Positionen der Zeichen in einem Wort neu angeordnet werden müssen oder unterschiedliche Glyphenformen erforderlich sind, werden nicht angezeigte Zeichen häufig auf der Codeseite angezeigt. Beispielsweise gibt es auf der Hebräischen Codeseite Links-To-Right und Rechts-To-Left Markierungen, um die endgültige Positionierung von Zeichen innerhalb der Ausgabezeichenfolgen zu bestimmen. Normalerweise werden diese nicht angezeigt und aus den lpGlyphen und lpDx Arrays entfernt. Sie können das GCP_DISPLAYZWG-Kennzeichen 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 Codeseite definiert sind. Einige Sprachen, z. B. Arabisch, können die Erstellung von Glyphen nur unterstützen, wenn dieser Wert angegeben ist. Wenn GetFontLanguageInfo diesen Wert für eine Zeichenfolge zurückgibt, muss dieser Wert in GetCharacterPlacement-verwendet werden.
GCP_JUSTIFY	Passt die Vergrößerungen im lpDx- Array so an, dass die Zeichenfolgenlänge mit nMaxExtent-identisch ist. GCP_JUSTIFY dürfen nur in Verbindung mit GCP_MAXEXTENT verwendet werden.
GCP_KASHIDA	Verwenden Sie Kashidas sowie oder anstelle von angepassten Vergrößerungen, um die Länge der Zeichenfolge so zu ändern, dass sie dem wert entspricht, der durch nMaxExtentangegeben wird. Im lpDx Array wird eine Kashida durch einen negativen Begründungsindex angegeben. GCP_KASHIDA dürfen nur in Verbindung mit GCP_JUSTIFY verwendet werden und nur, 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 als die Anzahl der Zeichen in der Eingabezeichenfolge ist. Da Kashidas verwendet werden, kann die Anwendung nicht davon ausgehen, dass das Festlegen der Arrays auf die Größe der Eingabezeichenfolge ausreichend ist. (Der maximal mögliche Wert ist ungefähr dxPageWidth/dxAveCharWidth, wobei dxPageWidth die Breite des Dokuments und dxAveCharWidth die durchschnittliche Zeichenbreite ist, wie von einem GetTextMetrics Aufruf zurückgegeben wird). Beachten Sie, dass GetFontLanguageInfo das GCP_KASHIDA Flag nicht bedeutet, dass es im Aufruf von GetCharacterPlacementverwendet werden muss, nur dass die Option verfügbar ist.
GCP_LIGATE	Verwenden Sie Ligationen überall, wo Zeichen ligate. Eine Ligation tritt auf, wenn eine Glyphe für zwei oder mehr Zeichen verwendet wird. Beispielsweise die Buchstaben a und e can ligate zu ?. Damit dies verwendet werden kann, müssen jedoch sowohl die Sprachunterstützung als auch die Schriftart die erforderlichen Glyphen unterstützen (das Beispiel wird nicht standardmäßig 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 der lpGlyphen Array fest. Wenn eine normale Ligation erforderlich ist, legen Sie diesen Wert auf Null fest. Wenn GCP_LIGATE nicht angegeben ist, findet keine Ligation statt. Weitere Informationen finden Sie unter GCP_RESULTS. Wenn der GCP_REORDER Wert in der Regel für den Zeichensatz erforderlich ist, aber nicht angegeben ist, ist die Ausgabe bedeutungslos, es sei denn, die übergebene Zeichenfolge ist bereits in visueller Reihenfolge vorhanden (d. h. das Ergebnis, das in lpGcpResults->lpOutString in einem Aufruf von GetCharacterPlacement wird, ist die Eingabezeichenfolge eines zweiten Aufrufs). Beachten Sie, dass GetFontLanguageInfo das GCP_LIGATE Flag nicht bedeutet, dass es im Aufruf von GetCharacterPlacementverwendet werden muss, nur dass die Option verfügbar ist.
GCP_MAXEXTENT	Berechnen Sie Zeichenfolgenbereiche nur so lange, wie das resultierende Ausmaß 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 der GCP_REORDER-Kennzeichnung hilfreich.
GCP_NUMERICOVERRIDE	Nur bestimmte Sprachen. Überschreiben Sie die normale Behandlung von Zahlen, und behandeln Sie sie als starke Zeichen, die der Lesereihenfolge der Zeichenfolgen entsprechen. Nur mit der GCP_REORDER-Kennzeichnung hilfreich.
GCP_NUMERICSLATIN	Nur Arabisch/Thailändisch. Verwenden Sie standardmäßige lateinische Glyphen für Zahlen und überschreiben Sie den Systemstandard. Um festzustellen, ob diese Option in der Sprache der Schriftart verfügbar ist, verwenden Sie GetStringTypeEx-, um festzustellen, ob die Sprache mehr als ein Zahlenformat unterstützt.
GCP_NUMERICSLOCAL	Nur Arabisch/Thailändisch. Verwenden Sie lokale Glyphen für numerische Zeichen und überschreiben Sie den Systemstandard. Um festzustellen, ob diese Option in der Sprache der Schriftart verfügbar ist, verwenden Sie GetStringTypeEx-, um festzustellen, ob die Sprache mehr als ein Zahlenformat unterstützt.
GCP_REORDER	Ordnen Sie die Zeichenfolge neu an. Wird für Sprachen verwendet, die keine SBCS- und Lesereihenfolge von links nach rechts sind. Wenn dieser Wert nicht angegeben ist, wird davon ausgegangen, dass die Zeichenfolge bereits in der Anzeigereihenfolge liegt. 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 außerhalb der Grenzen der Zeichenfolge anzugeben. GCP_CLASS_PREBOUNDRTL und GCP_CLASS_PREBOUNDLTR können zum Festlegen der Reihenfolge verwendet werden. 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 ist, wird der lpString Parameter für Sprachen, in denen diese verwendet wird, visuell sortiert, und die lpOutString- und lpOrder- Felder werden ignoriert. Verwenden Sie GetFontLanguageInfo-, um zu bestimmen, ob die aktuelle Schriftart die 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. "(" und ")" nicht umgekehrt.
GCP_USEKERNING	Verwenden Sie Kerning-Paare in der Schriftart (falls vorhanden) beim Erstellen der Breite von Arrays. Verwenden Sie GetFontLanguageInfo-, um zu bestimmen, ob die aktuelle Schriftart Kerning-Paare unterstützt. Beachten Sie, dass GetFontLanguageInfo das GCP_USEKERNING Flag nicht bedeutet, dass es im Aufruf von GetCharacterPlacementverwendet werden muss, nur dass die Option verfügbar ist. Die meisten TrueType-Schriftarten verfügen über eine Kerntabelle, 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, ist der Rückgabewert die Breite und Höhe der Zeichenfolge in logischen Einheiten. Die Breite ist das Wort mit niedriger Reihenfolge und die Höhe ist das Wort mit hoher Reihenfolge.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null.

Bemerkungen

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

Die Verwendung GetCharacterPlacement- zum Abrufen von Intercharacter-Abständen und Indexarrays ist nicht immer erforderlich, es sei denn, Begründung oder Kerning ist erforderlich. Bei nicht lateinischen Schriftarten können Anwendungen die Geschwindigkeit verbessern, mit der die ExtTextOut-Funktion Text rendert, indem sie GetCharacterPlacement verwenden, um die Intercharacter-Abstände und Indexarrays abzurufen, bevor ExtTextOutaufgerufen wird. Dies ist besonders hilfreich beim wiederholten Rendern desselben Texts oder beim Verwenden des Intercharacter-Abstands zum Positionieren des Carets. Wenn das lpGlyphs Ausgabearray im Aufruf von ExtTextOut-verwendet wird, muss das ETO_GLYPH_INDEX-Flag festgelegt werden.

GetCharacterPlacement überprüft die lpOrder, lpDX, lpCaretPos, lpOutStringund lpGlyphen Member 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 sicherzustellen, dass gültige Informationen abgerufen werden, ist die Anwendung dafür verantwortlich, das Mitglied vor dem Aufrufen der Funktion auf eine gültige Adresse festzulegen und den Wert des Elements nach dem Aufruf zu überprüfen. Wenn die GCP_JUSTIFY- oder GCP_USEKERNING Werte angegeben werden, müssen die lpDX- und/oder lpCaretPos-Member über gültige Adressen verfügen.

Beachten Sie, dass die in GCP_RESULTS.lpGlyphen zurückgegebenen Glyphen 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 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. Verwenden Sie entweder GetGlyphIndices, oder erweitern Sie das lpDX- Array mit Nullbreiteneinträgen für das entsprechende zweite Byte eines DBCS-Bytepaars, um diesen Konflikt zu beheben.

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 Berechnung mithilfe der vorausgestellten Breite jedes Zeichens durchzuführen, wobei nMaxFit die Anzahl der Zeichen ist, deren Glyphen die Erweiterte Breite kleiner als die Breite des führenden Zeichens ist.

Anmerkung

Der wingdi.h-Header definiert GetCharacterPlacement als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wingdi.h (enthalten Windows.h)
Library	Gdi32.lib
DLL-	Gdi32.dll