ExtTextOutA-Funktion (wingdi.h)

Artikel
08/27/2023

Die ExtTextOut-Funktion zeichnet Text mit der aktuell ausgewählten Schriftart, Hintergrundfarbe und Textfarbe. Sie können optional Dimensionen angeben, die für Beschneidungen, Deckkraft oder beides verwendet werden sollen.

Syntax

BOOL ExtTextOutA(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCSTR     lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] x

Die x-Koordinate in logischen Koordinaten des Bezugspunkts, der zum Positionieren der Zeichenfolge verwendet wird.

[in] y

Die y-Koordinate in logischen Koordinaten des Bezugspunkts, der zum Positionieren der Zeichenfolge verwendet wird.

[in] options

Gibt an, wie das anwendungsdefinierte Rechteck verwendet wird. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
ETO_CLIPPED	Der Text wird an das Rechteck gekappt.
ETO_GLYPH_INDEX	Das lpString-Array bezieht sich auf ein Von GetCharacterPlacement zurückgegebenes Array und sollte direkt von GDI analysiert werden, da keine weitere sprachspezifische Verarbeitung erforderlich ist. Die Glyphenindizierung gilt nur für TrueType-Schriftarten, aber das Flag kann für Bitmap- und Vektorschriftarten verwendet werden, um anzugeben, dass keine weitere Sprachverarbeitung erforderlich ist und GDI die Zeichenfolge direkt verarbeiten sollte. Beachten Sie, dass alle Glyphenindizes 16-Bit-Werte sind, obwohl davon ausgegangen wird, dass es sich bei der Zeichenfolge um ein Array von 8-Bit-Werten für Rasterschriftarten handelt. Für ExtTextOutW werden die Glyphenindizes in einer Metadatei gespeichert. Um jedoch die richtigen Zeichen anzuzeigen, muss die Metadatei mit derselben Schriftart wiedergegeben werden. Für ExtTextOutA werden die Glyphenindizes nicht gespeichert.
ETO_IGNORELANGUAGE	Ist für das System reserviert. Wenn eine Anwendung dieses Flag festlegt, verliert sie die internationale Skriptunterstützung, und in einigen Fällen wird möglicherweise überhaupt kein Text angezeigt.
ETO_NUMERICSLATIN	Um Zahlen anzuzeigen, verwenden Sie europäische Ziffern.
ETO_NUMERICSLOCAL	Verwenden Sie zum Anzeigen von Zahlen die für das Gebietsschema geeigneten Ziffern.
ETO_OPAQUE	Die aktuelle Hintergrundfarbe sollte verwendet werden, um das Rechteck zu füllen.
ETO_PDY	Wenn dies festgelegt ist, enthält das Array, auf das von lpDx verwiesen wird, Wertepaare. Der erste Wert jedes Paares ist wie üblich der Abstand zwischen den Ursprüngen benachbarter Zeichenzellen, der zweite Wert ist jedoch die Verschiebung entlang der vertikalen Richtung der Schriftart.
ETO_RTLREADING	Sprachausgabe "Naher Osten" von Windows: Wenn dieser Wert angegeben ist und eine hebräische oder arabische Schriftart im Gerätekontext ausgewählt ist, wird die Zeichenfolge in der Lesereihenfolge von rechts nach links ausgegeben. Wenn dieser Wert nicht angegeben wird, wird die Zeichenfolge in der Reihenfolge von links nach rechts ausgegeben. Der gleiche Effekt kann durch Festlegen des TA_RTLREADING-Werts in SetTextAlign erzielt werden. Dieser Wert wird aus Gründen der Abwärtskompatibilität beibehalten.

Die werte ETO_GLYPH_INDEX und ETO_RTLREADING können nicht zusammen verwendet werden. Da ETO_GLYPH_INDEX impliziert, dass die gesamte Sprachverarbeitung abgeschlossen wurde, ignoriert die Funktion das ETO_RTLREADING-Flag, falls ebenfalls angegeben.

[in] lprect

Ein Zeiger auf eine optionale RECT-Struktur , die die Dimensionen eines Rechtecks in logischen Koordinaten angibt, das zum Ausschneiden, Decken oder beides verwendet wird.

[in] lpString

Ein Zeiger auf eine Zeichenfolge, die den zu zeichnenden Text angibt. Die Zeichenfolge muss nicht mit Null beendet werden, da cbCount die Länge der Zeichenfolge angibt.

[in] c

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

Dieser Wert darf 8192 nicht überschreiten.

[in] lpDx

Ein Zeiger auf ein optionales Array von Werten, die den Abstand zwischen den Ursprüngen benachbarter Zeichenzellen angeben. Logische Einheiten lpDx[i] trennen beispielsweise die Ursprünge der Zeichenzelle i und der Zeichenzelle i + 1.

Rückgabewert

Wenn die Zeichenfolge gezeichnet wird, ist der Rückgabewert nonzero. Wenn die ANSI-Version von ExtTextOut jedoch mit ETO_GLYPH_INDEX aufgerufen wird, gibt die Funktion TRUE zurück, obwohl die Funktion nichts tut.

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

Hinweise

Die aktuellen Textausrichtungseinstellungen für den angegebenen Gerätekontext bestimmen, wie der Referenzpunkt zum Positionieren des Texts verwendet wird. Die Textausrichtungseinstellungen werden durch Aufrufen der GetTextAlign-Funktion abgerufen. Die Einstellungen für die Textausrichtung werden durch Aufrufen der SetTextAlign-Funktion geändert. Sie können die folgenden Werte für die Textausrichtung verwenden. Es kann nur ein Flag ausgewählt werden, das sich auf die horizontale und vertikale Ausrichtung auswirkt. Darüber hinaus kann nur eines der beiden Flags ausgewählt werden, die die aktuelle Position ändern.

Begriff	BESCHREIBUNG
TA_BASELINE	Der Referenzpunkt befindet sich in der Basiszeile des Texts.
TA_BOTTOM	Der Bezugspunkt befindet sich am unteren Rand des umgebenden Rechtecks.
TA_TOP	Der Bezugspunkt befindet sich am oberen Rand des umgebenden Rechtecks.
TA_CENTER	Der Bezugspunkt wird horizontal an der Mitte des umgebenden Rechtecks ausgerichtet.
TA_LEFT	Der Bezugspunkt befindet sich am linken Rand des umgebenden Rechtecks.
TA_RIGHT	Der Bezugspunkt befindet sich am rechten Rand des umgebenden Rechtecks.
TA_NOUPDATECP	Die aktuelle Position wird nach jedem Textausgabeaufruf nicht aktualisiert. Der Referenzpunkt wird an die Textausgabefunktion übergeben.
TA_RTLREADING	Sprachausgabe "Naher Osten" von Windows: Der Text ist in der Lesereihenfolge von rechts nach links angeordnet, im Gegensatz zur standardmäßigen Reihenfolge von links nach rechts. Dies gilt nur, wenn die im Gerätekontext ausgewählte Schriftart entweder hebräisch oder arabisch ist.
TA_UPDATECP	Die aktuelle Position wird nach jedem Textausgabeaufruf aktualisiert. Die aktuelle Position wird als Bezugspunkt verwendet.

Wenn der lpDx-ParameterNULL ist, verwendet die ExtTextOut-Funktion den Standardabstand zwischen Zeichen. Die Zeichenzellenherkunft und der Inhalt des Arrays, auf das der lpDx-Parameter verweist, werden in logischen Einheiten angegeben. Ein Zeichenzellenursprung wird als die linke obere Ecke der Zeichenzelle definiert.

Standardmäßig wird die aktuelle Position von dieser Funktion nicht verwendet oder aktualisiert. Eine Anwendung kann jedoch die SetTextAlign-Funktion aufrufen, wobei der fMode-Parameter auf TA_UPDATECP festgelegt ist, damit das System die aktuelle Position jedes Mal verwenden und aktualisieren kann, wenn die Anwendung ExtTextOut für einen angegebenen Gerätekontext aufruft. Wenn dieses Flag festgelegt ist, ignoriert das System die X - und Y-Parameter bei nachfolgenden ExtTextOut-Aufrufen .

Für die ANSI-Version von ExtTextOut verfügt das lpDx-Array über die gleiche Anzahl von INT-Werten wie Bytes in lpString. Bei DBCS-Zeichen können Sie den dx in den lpDx-Einträgen zwischen dem Lead-Byte und dem Trail-Byte verteilen, solange die Summe der beiden Bytes dem gewünschten dx entspricht. Für DBCS-Zeichen mit der Unicode-Version von ExtTextOut erhält jede Unicode-Glyphe einen einzelnen pdx-Eintrag .

Beachten Sie, dass die alpDx-Werte von GetTextExtentExPoint nicht mit den lpDx-Werten für ExtTextOut identisch sind. Um die alpDx-Werte in lpDx zu verwenden, müssen Sie sie zuerst verarbeiten.

ExtTextOut verwendet bei Bedarf Uniscribe , was zu einem Schriftartfallback führt. Das ETO_IGNORELANGUAGE-Flag verhindert dieses Verhalten und sollte nicht übergeben werden.

Darüber hinaus führt ExtTextOut vor dem Übergang in den Kernelmodus internes Batching von Aufrufen aus, um einige der Leistungsprobleme beim Abwägen der Verwendung von PolyTextOut und ExtTextOut zu verringern.

Tipp

ExtTextOut wird dringend gegenüber PolyTextOut für die moderne Entwicklung empfohlen, da es die Anzeige verschiedener Sprachen verarbeiten kann.

Beispiele

Ein Beispiel finden Sie unter Festlegen von Schriftarten für Menu-Item Textzeichenfolgen unter Verwenden von Menüs.

Hinweis

Der wingdi.h-Header definiert ExtTextOut 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 nicht codierungsneutralem Code 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
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 (einschließlich Windows.h)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll