SetConsoleMode
The SetConsoleMode
function sets the input mode of a console s input buffer or the output mode of
a console screen buffer.
BOOL SetConsoleMode(
|
HANDLE hConsoleHandle, |
// handle of
console input or screen buffer |
|
DWORD dwMode |
// input or output
mode to set |
|
); |
|
Parameters
hConsoleHandle
Identifies a
console input buffer or a screen buffer. The handle must have GENERIC_WRITE
access.
dwMode
Specifies the
input or output mode to set. If the hConsoleHandle parameter is an input
handle, the mode can be a combination of the following values. When a console
is created, all input modes except ENABLE_WINDOW_INPUT are enabled by default.
|
Value |
Meaning |
|
ENABLE_LINE_INPUT |
The ReadFile or ReadConsole function returns only
when a carriage return character is read. If this mode is disabled, the
functions return when one or more characters are available. |
|
ENABLE_ECHO_INPUT |
Characters
read by the ReadFile or ReadConsole function are written to the
active screen buffer as they are read. This mode can be used only if the
ENABLE_LINE_INPUT mode is also enabled. |
|
ENABLE_PROCESSED_INPUT |
CTRL+C is processed by the system and is not placed in the
input buffer. If the input buffer is being read by ReadFile or ReadConsole, other control keys are
processed by the system and are not returned in the ReadFile or ReadConsole
buffer. If the ENABLE_LINE_INPUT mode is also enabled, backspace, carriage
return, and linefeed characters are handled by the system. |
|
ENABLE_WINDOW_INPUT |
User
interactions that change the size of the console screen buffer are reported
in the console s input buffer. Information about these events can be read
from the input buffer by applications using the ReadConsoleInput function, but not by
those using ReadFile or ReadConsole. |
|
ENABLE_MOUSE_INPUT |
If the
mouse pointer is within the borders of the console window and the window has
the keyboard focus, mouse events generated by mouse movement and button
presses are placed in the input buffer. These events are discarded by ReadFile or ReadConsole, even when this mode is
enabled. |
If the hConsoleHandle
parameter is a screen buffer handle, the mode can be a combination of the
following values. When a screen buffer is created, both output modes are
enabled by default.
|
Value |
Meaning |
|
ENABLE_PROCESSED_OUTPUT |
Characters
written by the WriteFile
or WriteConsole
function or echoed by the ReadFile or ReadConsole function are
examined for ASCII control sequences and the correct action is performed.
Backspace, tab, bell, carriage return, and linefeed characters are processed. |
|
ENABLE_WRAP_AT_EOL_OUTPUT |
When
writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the
beginning of the next row when it reaches the end of the current row. This
causes the rows displayed in the console window to scroll up automatically
when the cursor advances beyond the last row in the window. It also causes
the contents of the screen buffer to scroll up (discarding the top row of the
screen buffer) when the cursor advances beyond the last row in the screen
buffer. If this mode is disabled, the last character in the row is
overwritten with any subsequent characters. |
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
A console
consists of an input buffer and one or more screen buffers. The mode of a
console buffer determines how the console behaves during input and output (I/O)
operations. One set of flag constants is used with input handles, and another
set is used with screen buffer (output) handles. Setting the output modes of
one screen buffer does not affect the output modes of other screen buffers.
The ENABLE_LINE_INPUT
and ENABLE_ECHO_INPUT modes only affect processes that use ReadFile or ReadConsole to read from the console s
input buffer. Similarly, the ENABLE_PROCESSED_INPUT mode primarily affects ReadFile
and ReadConsole users, except that it also determines whether CTRL+C input is
reported in the input buffer (to be read by the ReadConsoleInput function) or is passed to a
HandlerRoutine
function defined by the application.
The
ENABLE_WINDOW_INPUT and ENABLE_MOUSE_INPUT modes determine whether user
interactions involving window resizing and mouse actions are reported in the
input buffer or discarded. These events can be read by ReadConsoleInput,
but they are always filtered by ReadFile and ReadConsole.
The
ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT modes only affect
processes using ReadFile or ReadConsole and WriteFile or WriteConsole.
To determine
the current mode of a console input buffer or a screen buffer, use the GetConsoleMode
function.
See Also