DrawTextW-Funktion (winuser.h)

Artikel
06/08/2023

Die DrawText-Funktion zeichnet formatierten Text im angegebenen Rechteck. Der Text wird gemäß der angegebenen Methode formatiert (Erweitern von Registerkarten, Rechtfertigen von Zeichen, Zeilenbruchlinien usw.).

Verwenden Sie die DrawTextEx-Funktion , um zusätzliche Formatierungsoptionen anzugeben.

Syntax

int DrawTextW(
  [in]      HDC     hdc,
  [in, out] LPCWSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in, out] lpchText

Ein Zeiger auf die Zeichenfolge, die den zu zeichnenden Text angibt. Wenn der nCount-Parameter -1 ist, muss die Zeichenfolge NULL-endend sein.

Wenn uFormat DT_MODIFYSTRING enthält, kann die Funktion dieser Zeichenfolge bis zu vier zusätzliche Zeichen hinzufügen. Der Puffer, der die Zeichenfolge enthält, sollte groß genug sein, um diese zusätzlichen Zeichen aufzunehmen.

[in] cchText

Die Länge der Zeichenfolge in Zeichen. Wenn nCount den Wert -1 aufweist, wird angenommen, dass der lpchText-Parameter ein Zeiger auf eine Zeichenfolge mit NULL-Beendigung ist, und DrawText berechnet die Zeichenanzahl automatisch.

[in, out] lprc

Ein Zeiger auf eine RECT-Struktur , die das Rechteck (in logischen Koordinaten) enthält, in dem der Text formatiert werden soll.

[in] format

Die Methode zum Formatieren des Texts. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
DT_BOTTOM	Rechtfertigt den Text am unteren Rand des Rechtecks. Dieser Wert wird nur mit dem wert DT_SINGLELINE verwendet.
DT_CALCRECT	Bestimmt die Breite und Höhe des Rechtecks. Wenn mehrere Textzeilen vorhanden sind, verwendet DrawText die Breite des Rechtecks, auf das der lpRect-Parameter verweist, und erweitert die Basis des Rechtecks, um die letzte Textzeile zu binden. Wenn das größte Wort breiter als das Rechteck ist, wird die Breite erweitert. Wenn der Text kleiner als die Breite des Rechtecks ist, wird die Breite reduziert. Wenn nur eine Textzeile vorhanden ist, ändert DrawText die rechte Seite des Rechtecks, sodass das letzte Zeichen in der Zeile gebunden wird. In beiden Fällen gibt DrawText die Höhe des formatierten Texts zurück, zeichnet den Text jedoch nicht.
DT_CENTER	Zentriert Text horizontal im Rechteck.
DT_EDITCONTROL	Dupliziert die Textanzeigeeigenschaften eines mehrlineigen Bearbeitungssteuerelements. Insbesondere wird die durchschnittliche Zeichenbreite auf die gleiche Weise wie für ein Bearbeitungssteuerelement berechnet, und die Funktion zeigt keine teilweise sichtbare letzte Zeile an.
DT_END_ELLIPSIS	Wenn das Ende einer Zeichenfolge bei angezeigtem Text nicht in das Rechteck passt, wird er abgeschnitten, und Auslassungspunkte werden hinzugefügt. Wenn ein Wort, das sich nicht am Ende der Zeichenfolge befindet, die Grenzen des Rechtecks überschreitet, wird es ohne Auslassungspunkte abgeschnitten. Die Zeichenfolge wird nur geändert, wenn das flag DT_MODIFYSTRING angegeben ist. Vergleichen Sie mit DT_PATH_ELLIPSIS und DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Erweitert Tabstoppzeichen. Die Standardanzahl von Zeichen pro Tabstopp beträgt acht. Die Werte DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS und DT_END_ELLIPSIS können nicht mit dem DT_EXPANDTABS-Wert verwendet werden.
DT_EXTERNALLEADING	Schließt die externe Schriftartgröße in die Zeilenhöhe ein. Normalerweise ist externes Führendes nicht in der Höhe einer Textzeile enthalten.
DT_HIDEPREFIX	Ignoriert das Präfixzeichen ampersand (&) im Text. Der folgende Buchstabe wird nicht unterstrichen, aber andere mnemonische Präfixzeichen werden weiterhin verarbeitet. Beispiel: Eingabezeichenfolge: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d" Vergleichen Sie mit DT_NOPREFIX und DT_PREFIXONLY.
DT_INTERNAL	Berechnet mit der Systemschriftart die Textmetrik.
DT_LEFT	Richtet Text links aus.
DT_MODIFYSTRING	Ändert die angegebene Zeichenfolge so, dass sie mit dem angezeigten Text übereinstimmt. Dieser Wert hat keine Auswirkung, es sei denn, DT_END_ELLIPSIS oder DT_PATH_ELLIPSIS wird angegeben.
DT_NOCLIP	Zeichnet ohne Beschneidung. DrawText ist etwas schneller, wenn DT_NOCLIP verwendet wird.
DT_NOFULLWIDTHCHARBREAK	Verhindert einen Zeilenumbruch an einem DBCS (double-wide character string), sodass die Zeilenumbruchregel SBCS-Zeichenfolgen entspricht. Dies kann beispielsweise in koreanischen Fenstern verwendet werden, um die Lesbarkeit von Symbolbezeichnungen zu verbessern. Dieser Wert hat keine Auswirkung, es sei denn, es wird DT_WORDBREAK angegeben.
DT_NOPREFIX	Deaktiviert die Verarbeitung von Präfixzeichen. Normalerweise interpretiert DrawText das mnemonische Präfixzeichen & als Direktive, um das folgende Zeichen zu unterstreichen, und die mnemonischen Präfixzeichen && als Direktive zum Drucken eines einzelnen &. Durch Angabe DT_NOPREFIX wird diese Verarbeitung deaktiviert. Beispiel: Beispiel: Eingabezeichenfolge: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Vergleichen Sie mit DT_HIDEPREFIX und DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Für angezeigten Text ersetzt Zeichen in der Mitte der Zeichenfolge durch Auslassungspunkte, sodass das Ergebnis in das angegebene Rechteck passt. Wenn die Zeichenfolge umgekehrte Schrägstriche (\\) enthält, behält DT_PATH_ELLIPSIS den Text nach dem letzten umgekehrten Schrägstrich so weit wie möglich bei. Die Zeichenfolge wird nur geändert, wenn das flag DT_MODIFYSTRING angegeben ist. Vergleichen Sie mit DT_END_ELLIPSIS und DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Zeichnet nur eine Unterstreichung an der Position des Zeichens nach dem Präfixzeichen amper und (&). Zeichnet keine anderen Zeichen in der Zeichenfolge. Beispiel: Beispiel: Eingabezeichenfolge: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Vergleichen Sie mit DT_HIDEPREFIX und DT_NOPREFIX.
DT_RIGHT	Richtet Text rechts aus.
DT_RTLREADING	Layout in Leserichtung von rechts nach links für bidirektionalen Text, wenn die im hdc ausgewählte Schriftart eine hebräische oder arabische Schriftart ist. Die Standardlesereihenfolge für den gesamten Text ist von links nach rechts.
DT_SINGLELINE	Zeigt Text nur in einer einzelnen Zeile an. Wagenrückläufe und Zeilenfeeds unterbrechen die Linie nicht.
DT_TABSTOP	Legt Tabstopps fest. Die Bits 15-8 (Byte mit hoher Ordnung des Worts mit niedriger Ordnung) des uFormat-Parameters geben die Anzahl der Zeichen für jede Registerkarte an. Die Standardanzahl von Zeichen pro Registerkarte beträgt acht. Die Werte DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP und DT_NOPREFIX können nicht mit dem DT_TABSTOP-Wert verwendet werden.
DT_TOP	Rechtfertigt den Text am oberen Rand des Rechtecks.
DT_VCENTER	Zentriert Text vertikal. Dieser Wert wird nur mit dem wert DT_SINGLELINE verwendet.
DT_WORDBREAK	Unterbricht Wörter. Zeilen werden automatisch zwischen Wörtern unterbrochen, wenn sich ein Wort über den Rand des durch den lpRect-Parameter angegebenen Rechtecks erstreckt. Eine Wagenrücklaufvorschubsequenz durchbricht die Zeile ebenfalls. Wenn dies nicht angegeben ist, erfolgt die Ausgabe in einer Zeile.
DT_WORD_ELLIPSIS	Schneidet jedes Wort ab, das nicht in das Rechteck passt, und fügt Auslassungspunkte hinzu. Vergleichen Sie mit DT_END_ELLIPSIS und DT_PATH_ELLIPSIS.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Höhe des Texts in logischen Einheiten. Wenn DT_VCENTER oder DT_BOTTOM angegeben ist, ist der Rückgabewert der Offset von lpRect->top bis zum unteren Rand des gezeichneten Texts.

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

Hinweise

Die DrawText-Funktion verwendet die ausgewählte Schriftart, die Textfarbe und die Hintergrundfarbe des Gerätekontexts, um den Text zu zeichnen. Sofern nicht das DT_NOCLIP-Format verwendet wird, schneidet DrawText den Text so ab, dass er nicht außerhalb des angegebenen Rechtecks angezeigt wird. Beachten Sie, dass Text mit erheblichem Überhang abgeschnitten werden kann, z. B. ein anfängliches "W" in der Textzeichenfolge oder Text in Kursivschrift. Es wird davon ausgegangen, dass alle Formatierungen mehrere Zeilen aufweisen, es sei denn, das DT_SINGLELINE Format ist angegeben.

Wenn die ausgewählte Schriftart für das angegebene Rechteck zu groß ist, versucht die DrawText-Funktion nicht, eine kleinere Schriftart zu ersetzen.

Der Textausrichtungsmodus für den Gerätekontext muss die Flags TA_LEFT, TA_TOP und TA_NOUPDATECP enthalten.

Hinweis

Der winuser.h-Header definiert DrawText 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

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	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-misc-l1-1-0 (eingeführt in Windows 8)