DrawText-Funktion (winuser.h)

Artikel
03/04/2024

Die DrawText-Funktion zeichnet formatierten Text im angegebenen Rechteck. Es formatiert den Text gemäß der angegebenen Methode (Erweitern von Registerkarten, Rechtfertigungszeichen, Zeilenbruchzeilen usw.).

Um zusätzliche Formatierungsoptionen anzugeben, verwenden Sie die DrawTextEx-Funktion .

Syntax

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR 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, der den zu zeichnenden Text angibt. Wenn der nCount-Parameter -1 ist, muss die Zeichenfolge null-beendet 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 -1 ist, 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 DT_SINGLELINE-Wert verwendet.
DT_CALCRECT	Bestimmt die Breite und Höhe des Rechtecks. Wenn mehrere Textzeilen vorhanden sind, verwendet DrawText die Breite des Rechtecks, auf das vom lpRect-Parameter verwiesen wird, 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 es das letzte Zeichen in der Zeile eingrenzt. 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 für angezeigten Text das Ende einer Zeichenfolge nicht in das Rechteck passt, wird er abgeschnitten, und Auslassungspunkte werden hinzugefügt. Wenn ein Wort, das sich nicht am Ende der Zeichenfolge befindet, über die Grenzen des Rechtecks hinausgeht, 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 die externe Leitung 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 dem angezeigten Text entspricht. Dieser Wert hat keine Auswirkung, es sei denn, DT_END_ELLIPSIS oder DT_PATH_ELLIPSIS wird angegeben.
DT_NOCLIP	Zeichnet ohne Ausschneiden. DrawText ist etwas schneller, wenn DT_NOCLIP verwendet wird.
DT_NOFULLWIDTHCHARBREAK	Verhindert einen Zeilenumbruch bei 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, DT_WORDBREAK angegeben wird.
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 Anweisung 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 nach dem letzten umgekehrten Schrägstrich so viel wie möglich des Texts bei. Die Zeichenfolge wird nur geändert, wenn das flag DT_MODIFYSTRING angegeben ist. Vergleichen Sie DT_END_ELLIPSIS und DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Zeichnet nur eine Unterstreichung an der Position des Zeichens nach dem Präfixzeichen ampersand (&). Zeichnet keine anderen Zeichen in der Zeichenfolge. Beispiel: Beispiel: Eingabezeichenfolge: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Vergleichen Sie DT_HIDEPREFIX und DT_NOPREFIX.
DT_RIGHT	Richtet Text rechts aus.
DT_RTLREADING	Layout in der Lesereihenfolge 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 Nur Text in einer einzelnen Zeile an. Wagenrückläufe und Zeilenfeeds unterbrechen die Linie nicht.
DT_TABSTOP	Legt Tabstopps fest. Bits 15-8 (hochgeordnetes Byte des Worts mit niedriger Reihenfolge) 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	Zentrativ den Text vertikal. Dieser Wert wird nur mit dem DT_SINGLELINE-Wert 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 unterbricht auch die Linie. 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 wird, ist der Rückgabewert der Offset von lpRect->top bis zum Ende des gezeichneten Texts.

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

Hinweise

Die DrawText-Funktion verwendet die ausgewählte Schriftart, Textfarbe und Hintergrundfarbe des Gerätekontexts, um den Text zu zeichnen. Sofern nicht das DT_NOCLIP-Format verwendet wird, klammert 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, der kursiv ist. Es wird davon ausgegangen, dass alle Formatierungen mehrere Zeilen aufweisen, es sei denn, das DT_SINGLELINE Format wird 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.

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