TextOutW-Funktion (wingdi.h)

Artikel
11/20/2024

Die TextOut--Funktion schreibt eine Zeichenfolge an der angegebenen Position unter Verwendung der aktuell ausgewählten Schriftart, der Hintergrundfarbe und der Textfarbe.

Syntax

BOOL TextOutW(
  [in] HDC     hdc,
  [in] int     x,
  [in] int     y,
  [in] LPCWSTR lpString,
  [in] int     c
);

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] x

Die x-Koordinate in logischen Koordinaten des Referenzpunkts, den das System zum Ausrichten der Zeichenfolge verwendet.

[in] y

Die y-Koordinate in logischen Koordinaten des Referenzpunkts, den das System zum Ausrichten der Zeichenfolge verwendet.

[in] lpString

Ein Zeiger auf die zu zeichnende Zeichenfolge. Die Zeichenfolge muss nicht null beendet werden, da cchString- die Länge der Zeichenfolge angibt.

[in] c

Die Länge der Zeichenfolge, auf die durch lpString-in Zeichen verwiesen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

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

Bemerkungen

Die Interpretation des Referenzpunkts hängt vom aktuellen Textausrichtungsmodus ab. Eine Anwendung kann diesen Modus abrufen, indem sie die GetTextAlign--Funktion aufruft; eine Anwendung kann diesen Modus ändern, indem sie die SetTextAlign--Funktion aufruft. Sie können die folgenden Werte für die Textausrichtung verwenden. Es kann nur ein Kennzeichen ausgewählt werden, das sich auf die horizontale und vertikale Ausrichtung auswirkt. Darüber hinaus können nur eine der beiden Flags, die die aktuelle Position ändern, ausgewählt werden.

Ausdruck	Beschreibung
TA_BASELINE	Der Bezugspunkt befindet sich auf 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 Bezugspunkt wird an die Textausgabefunktion übergeben.
TA_RTLREADING	Sprachenedition des Nahen Ostens von Windows: Der Text wird in der Leserichtung von rechts nach links und nicht in der Standardrichtung von links nach rechts angeordnet. Dies gilt nur, wenn die im Gerätekontext ausgewählte Schriftart hebräisch oder arabisch ist.
TA_UPDATECP	Die aktuelle Position wird nach jedem Textausgabeaufruf aktualisiert. Die aktuelle Position wird als Bezugspunkt verwendet.

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 TextOut- für einen angegebenen Gerätekontext aufruft. Wenn dieses Kennzeichen festgelegt ist, ignoriert das System die nXStart- und nYStart- Parameter für nachfolgende TextOut- Aufrufe.

Wenn die TextOut--Funktion in einer Pfadklammer platziert wird, generiert das System einen Pfad für den TrueType-Text, der jedes Zeichen und sein Zeichenfeld enthält. Der generierte Bereich ist das Zeichenfeld minus dem Text und nicht dem Text selbst. Sie können den durch die Gliederung des TrueType-Texts eingeschlossenen Bereich abrufen, indem Sie den Hintergrundmodus auf transparent festlegen, bevor Sie die TextOut--Funktion in der Pfadklammer platzieren. Nachfolgend sehen Sie Beispielcode, der diese Prozedur veranschaulicht.


// Obtain the window's client rectangle 
GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode 
// to transparent, the region is the text itself 
// SetBkMode(hdc, TRANSPARENT); 

// Bracket begin a path 
BeginPath(hdc);

// Send some text out into the world 
TCHAR text[ ] = "Defenestration can be hazardous";
TextOut(hdc,r.left,r.top,text, ARRAYSIZE(text));

// Bracket end a path 
EndPath(hdc);

// Derive a region from that path 
SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath() 
// SelectClipRgn(hdc, PathToRegion(hdc)); 

// Fill the region with grayness 
FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

Beispiele

Ein Beispiel finden Sie unter Aufzählen der installierten Schriftarten.

Anmerkung

Der wingdi.h-Header definiert TextOut 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
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