WriteConsoleOutputAttribute Funktion

Artikel
12/15/2023

Wichtig

In diesem Dokument werden Konsolenplattformfunktionen beschrieben, die nicht mehr Teil unserer Ökosystem-Roadmap sind. Wir empfehlen nicht, diesen Inhalt in neuen Produkten zu verwenden, aber wir werden weiterhin vorhandene Nutzungen für die unbegrenzte Zukunft unterstützen. Unsere bevorzugte moderne Lösung konzentriert sich auf virtuelle Terminalsequenzen für maximale Kompatibilität in plattformübergreifenden Szenarien. Weitere Informationen zu dieser Designentscheidung finden Sie in unserem Dokument klassische Konsole im Vergleich zum virtuellen Terminal.

Kopiert eine Reihe von Zeichenattributen in aufeinander folgende Zellen eines Konsolenbildschirmpuffers, beginnend an einer angegebenen Position.

Syntax

BOOL WINAPI WriteConsoleOutputAttribute(
  _In_        HANDLE  hConsoleOutput,
  _In_  const WORD    *lpAttribute,
  _In_        DWORD   nLength,
  _In_        COORD   dwWriteCoord,
  _Out_       LPDWORD lpNumberOfAttrsWritten
);

Parameter

hConsoleOutput [in]
Ein Handle für den Konsolenbildschirm-Puffer. Das Handle muss das Zugriffsrecht GENERIC_WRITE besitzen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Konsolenpuffer.

lpAttribute [in]
Die Attribute, die beim Schreiben in den Konsolenbildschirmpuffer verwendet werden sollen. Weitere Informationen finden Sie unter Zeichenattribute.

nLength [in]
Die Anzahl der Bildschirmpufferzeichenzellen, in die die Attribute kopiert werden.

dwWriteCoord [in]
Eine COORD-Struktur, die die Zeichenkoordinaten der ersten Zelle im Konsolenbildschirmpuffer angibt, in die die Attribute geschrieben werden.

lpNumberOfAttrsWritten [out]
Ein Zeiger auf eine Variable, die die Anzahl der Attribute empfängt, die tatsächlich in den Konsolenbildschirmpuffer geschrieben wurden.

Rückgabewert

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

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn die Anzahl der Attribute, die geschrieben werden sollen, über das Ende der angegebenen Zeile im Konsolenbildschirmpuffer hinausgeht, werden Attribute in die nächste Zeile geschrieben. Wenn die Anzahl der Attribute, die über das Ende des Konsolenbildschirmpuffers hinaus geschrieben werden sollen, werden die Attribute bis zum Ende des Konsolenbildschirmpuffers geschrieben.

Die Zeichenwerte an den Positionen, in die geschrieben wird, werden nicht geändert.

Tipp

Diese API verfügt über eine virtuelle Terminal-Entsprechung in den Sequenzen Textformatierung und Cursorpositionierung. Bewegen Sie den Cursor an die Einfügeposition, wenden Sie die gewünschte Formatierung an, und schreiben Sie Text aus, um den Text auszufüllen. Es gibt keine Entsprechung zum Anwenden von Farben auf einen Bereich, ohne auch Text auszusetzen. Diese Entscheidung richtet die Windows-Plattform absichtlich an andere Betriebssysteme aus, bei denen die einzelne Clientanwendung erwartet wird, dass sie sich ihren eigenen gezeichneten Zustand für eine weitere Manipulation merken wird.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	ConsoleApi2.h (über WinCon.h, Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll