SetConsoleMode-Funktion

Artikel
07/12/2023

Legt den Eingabemodus des Eingabepuffers einer Konsole oder den Ausgabemodus des Bildschirmpuffers einer Konsole fest.

Syntax

BOOL WINAPI SetConsoleMode(
  _In_ HANDLE hConsoleHandle,
  _In_ DWORD  dwMode
);

Parameter

hConsoleHandle [in]
Ein Handle zum Konsoleneingabepuffer oder zu einem Konsolenbildschirmpuffer. Das Handle muss über das Zugriffsrecht GENERIC_READ verfügen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Konsolenpuffer.

dwMode [in]
Der Eingabe- oder Ausgabemodus, der festgelegt werden soll.

Wenn der Parameter hConsoleHandle- ein Eingabehandle ist, kann der Modus einen oder mehrere der folgenden Werte aufweisen. Wenn eine Konsole erstellt wird, werden alle Eingabemodi außer ENABLE_WINDOW_INPUT und ENABLE_VIRTUAL_TERMINAL_INPUT standardmäßig aktiviert.

Wert	Bedeutung
ENABLE_ECHO_INPUT 0x0004	Von der Funktion ReadFile oder ReadConsole gelesene Zeichen werden während der Eingabe in die Konsole in den aktiven Bildschirmpuffer geschrieben. Dieser Modus kann nur verwendet werden, wenn auch der Modus ENABLE_LINE_INPUT aktiviert ist.
ENABLE_INSERT_MODE 0x0020	Ist diese Option aktiviert, wird der in ein Konsolenfenster eingegebene Text an der aktuellen Cursorposition eingefügt, und der Text hinter dieser Position wird nicht überschrieben. Ist die Option deaktiviert, wird der nachfolgende Text überschrieben.
ENABLE_LINE_INPUT 0x0002	Die Funktion ReadFile oder ReadConsole gibt nur dann Werte zurück, wenn ein Wagenrücklaufzeichen gelesen wird. Ist dieser Modus deaktiviert, geben die Funktionen Werte zurück, wenn ein oder mehrere Zeichen verfügbar sind.
ENABLE_MOUSE_INPUT 0x0010	Wenn sich der Mauszeiger innerhalb der Grenzen des Konsolenfensters befindet und das Fenster den Tastaturfokus hält, werden durch Mausbewegungen und das Drücken von Maustasten erzeugte Mausereignisse in den Eingabepuffer gestellt. Diese Ereignisse werden von ReadFile oder ReadConsole ignoriert, auch wenn dieser Modus aktiviert ist. Die Funktion ReadConsoleInput kann verwendet werden, um MOUSE_EVENT-Eingabedatensätze aus dem Eingabepuffer zu lesen.
ENABLE_PROCESSED_INPUT 0x0001	STRG+C wird vom System verarbeitet und nicht in den Eingabepuffer platziert. Wenn der Eingabepuffer von ReadFile oder ReadConsole gelesen wird, werden andere Steuerungstasten vom System verarbeitet und nicht in den ReadFile oder ReadConsole-Puffer zurückgegeben. Wenn der Modus ENABLE_LINE_INPUT ebenfalls aktiviert ist, werden Rücktasten-, Wagenrücklauf- und Zeilenvorschubzeichen vom System verarbeitet.
ENABLE_QUICK_EDIT_MODE 0x0040	Dieses Flag ermöglicht es dem Benutzer, Text mit der Maus auszuwählen und zu bearbeiten. Zum Aktivieren dieses Modus verwenden Sie `ENABLE_QUICK_EDIT_MODE \| ENABLE_EXTENDED_FLAGS`. Um diesen Modus zu deaktivieren, verwenden Sie ENABLE_EXTENDED_FLAGS ohne dieses Flag.
ENABLE_WINDOW_INPUT 0x0008	Benutzerinteraktionen, die die Größe des Konsolenbildschirmpuffers ändern, werden im Eingabepuffer der Konsole gemeldet. Informationen über diese Ereignisse können von Anwendungen, die die Funktion ReadConsoleInput verwenden, aus dem Eingabepuffer gelesen werden, jedoch nicht von Anwendungen, die ReadFile oder ReadConsole verwenden.
ENABLE_VIRTUAL_TERMINAL_INPUT 0x0200	Wenn Sie dieses Flag setzen, wird die Engine für die virtuelle Terminalverarbeitung angewiesen, die vom Konsolenfenster empfangenen Benutzereingaben in virtuelle Konsolenterminalsequenzen umzuwandeln, die von einer unterstützenden Anwendung über die Funktionen ReadFile oder ReadConsole abgerufen werden können. Typischerweise ist die Verwendung dieses Flags in Verbindung mit ENABLE_VIRTUAL_TERMINAL_PROCESSING auf dem Ausgabehandle vorgesehen, um eine Verbindung zu einer Anwendung herzustellen, die ausschließlich über virtuelle Terminalsequenzen kommuniziert.

Wenn der Parameter hConsoleHandle- ein Bildschirmpufferhandle ist, kann der Modus einen oder mehrere der folgenden Werte aufweisen. Wenn ein Bildschirmpuffer erstellt wird, sind beide Ausgabemodi standardmäßig aktiviert.

Wert	Bedeutung
ENABLE_PROCESSED_OUTPUT 0x0001	Zeichen, die von der Funktion WriteFile oder WriteConsole geschrieben bzw. von der Funktion ReadFile oder ReadConsole ausgegeben werden, werden auf ASCII-Steuerungssequenzen durchsucht, und die entsprechende Aktion wird ausgeführt. Rücktasten-, Tabulator-, Glocken-, Wagenrücklauf- und Zeilenvorschubzeichen werden verarbeitet. Dieses Flag sollte aktiviert sein, wenn Steuerelementsequenzen gelesen werden oder ENABLE_VIRTUAL_TERMINAL_PROCESSING festgelegt ist.
ENABLE_WRAP_AT_EOL_OUTPUT 0x0002	Beim Schreiben mit WriteFile oder WriteConsole oder beim Ausgeben des Echos mit ReadFile oder ReadConsole bewegt sich der Cursor an den Anfang der nächsten Zeile, sobald er das Ende der aktuellen Zeile erreicht. Dies bewirkt, dass die im Konsolenfenster angezeigten Zeilen automatisch nach oben gescrollt werden, wenn sich der Cursor über die letzte Zeile im Fenster hinaus bewegt. Dies bewirkt zudem, dass der Inhalt des Konsolenbildschirmpuffers nach oben scrollt (../und dabei die oberste Zeile des Konsolenbildschirmpuffers verwirft), wenn sich der Cursor über die letzte Zeile im Konsolenbildschirmpuffer hinaus bewegt. Wenn dieser Modus deaktiviert ist, wird das letzte Zeichen in der Zeile mit allen nachfolgenden Zeichen überschrieben.
ENABLE_VIRTUAL_TERMINAL_PROCESSING 0x0004	Beim Schreiben mit WriteFile oder WriteConsole werden die Zeichen nach VT100 und ähnlichen Steuerzeichenfolgen durchsucht, die die Cursorbewegung, den Farb-/Schriftartmodus und andere Vorgänge steuern, die auch über die vorhandenen Konsolen-APIs ausgeführt werden können. Weitere Informationen finden Sie unter Virtuelle Konsolenterminalsequenzen. Stellen Sie sicher, dass ENABLE_PROCESSED_OUTPUT festgelegt ist, wenn dieses Flag verwendet wird.
DISABLE_NEWLINE_AUTO_RETURN 0x0008	Wenn Sie mit WriteFile oder WriteConsole schreiben, wird ein zusätzlicher Status zum Umbruch am Zeilenende hinzugefügt, wodurch sich Cursorbewegungen und Bildlaufvorgänge im Puffer verzögern können. Wenn ENABLE_WRAP_AT_EOL_OUTPUT gesetzt ist und Text das Zeilenende erreicht, springt der Cursor normalerweise sofort in die nächste Zeile, und der Inhalt des Puffers wird um eine Zeile nach oben gescrollt. Im Gegensatz zu diesem Flagsatz bewegt sich der Cursor nicht zur nächsten Zeile fort, und es wird kein Scrollvorgang ausgeführt. Das geschriebene Zeichen wird an der Endposition in der Zeile angezeigt, und der Cursor bleibt über diesem Zeichen stehen, als ob ENABLE_WRAP_AT_EOL_OUTPUT deaktiviert wäre, aber das nächste druckbare Zeichen wird angezeigt, als ob ENABLE_WRAP_AT_EOL_OUTPUT aktiviert wäre. Es erfolgt kein Überschreiben. Insbesondere wird der Cursor schnell nach unten in die nächste Zeile bewegt, ggf. wird ein Bildlauf durchgeführt, das Zeichen wird angezeigt, und der Cursor bewegt sich um eine Position weiter. Typischerweise ist die Verwendung dieses Flags in Verbindung mit der Einstellung ENABLE_VIRTUAL_TERMINAL_PROCESSING vorgesehen, um einen Terminalemulator besser zu emulieren, bei dem das Schreiben des endgültigen Zeichens auf dem Bildschirm (../in der rechten unteren Ecke) ohne Auslösen eines sofortigen Bildlaufs das gewünschte Verhalten ist.
ENABLE_LVB_GRID_WORLDWIDE 0x0010	Die APIs zum Schreiben von Zeichenattributen, beispielsweise WriteConsoleOutput und WriteConsoleOutputAttribute, erlauben die Verwendung von Flags aus Zeichenattributen, um die Farbe des Vorder- und Hintergrunds von Text anzupassen. Zusätzlich wurde ein Bereich von DBCS-Flags mit dem Präfix COMMON_LVB angegeben. Historisch gesehen funktionierten diese Flags nur in DBCS-Codepages für Chinesisch, Japanisch und Koreanisch. Mit Ausnahme der Flags für das führende Byte und das nachgestellte Byte können die übrigen Flags, die „Line Drawing“ und „Reverse Video“ (../Vordergrund- und Hintergrundfarben vertauschen) beschreiben, für andere Sprachen nützlich sein, um Teile der Ausgabe hervorzuheben. Durch das Setzen dieses Konsolenmodusflags können die Attribute in jeder Codepage in jeder Sprache verwendet werden. Es ist standardmäßig deaktiviert, um die Kompatibilität mit bekannten Anwendungen zu gewährleisten, die in der Vergangenheit davon profitierten, dass die Konsole diese Flags auf Nicht-CJK-Computern ignorierte, um Bits in diesen Feldern für ihre eigenen Zwecke oder versehentlich zu speichern. Beachten Sie, dass die Verwendung des ENABLE_VIRTUAL_TERMINAL_PROCESSING-Modus dazu führen kann, dass LVB-Raster- und Videoumkehr-Flags gesetzt werden, während dieses Flag noch deaktiviert ist, wenn die angefügte Anwendung Unterstreichung oder Videoumkehrung über virtuelle Konsolenterminalsequenzen anfordert.

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

Eine Konsole besteht aus einem Eingabepuffer und einem oder mehreren Bildschirmpuffern. Der Modus eines Konsolenpuffers bestimmt, wie sich die Konsole bei Eingabe- oder Ausgabevorgängen (E/A) verhält. Ein Satz von Flag-Konstanten wird mit Eingabehandles und ein weiterer Satz mit Bildschirmpufferhandles (Ausgabehandles) verwendet. Das Festlegen der Ausgabemodi eines Bildschirmpuffers wirkt sich nicht auf die Ausgabemodi anderer Bildschirmpuffer aus.

Die Modi ENABLE_LINE_INPUT und ENABLE_ECHO_INPUT betreffen nur Prozesse, die zum Lesen aus dem Eingabepuffer der Konsole ReadFile oder ReadConsole verwenden. In ähnlicher Weise wirkt sich der Modus ENABLE_PROCESSED_INPUT primär auf Benutzer von ReadFile und ReadConsole aus, mit der Ausnahme, dass er auch bestimmt, ob CTRL+C-Eingaben im Eingabepuffer gemeldet (um von der Funktion ReadConsoleInput gelesen zu werden) oder an eine von der Anwendung definierte Funktion übergeben werden.

Die Modi ENABLE_WINDOW_INPUT und ENABLE_MOUSE_INPUT bestimmen, ob Benutzerinteraktionen mit Fenstergrößenänderung und Mausaktionen im Eingabepuffer gemeldet oder verworfen werden. Diese Ereignisse können von ReadConsoleInput gelesen werden, aber sie werden von ReadFile und ReadConsole immer gefiltert.

Die Modi ENABLE_PROCESSED_OUTPUT und ENABLE_WRAP_AT_EOL_OUTPUT betreffen nur Prozesse, die ReadFile oder ReadConsole und WriteFile oder WriteConsole verwenden.

Um den aktuellen Modus eines Konsoleneingabepuffers oder Bildschirmpuffers zu bestimmen, verwenden Sie die Funktion GetConsoleMode.

Beispiele

Ein Beispiel finden Sie unter Lesen von Eingabepufferereignissen.

Anforderungen


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