From 9c5152d1a9b601bd3cb8f7babc1ed193aad8e407 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 23 Sep 2020 12:20:03 -0700 Subject: [PATCH 01/53] Mark important docs as high pri for localization. --- docs/allocconsole.md | 1 + docs/console-handles.md | 1 + docs/console-screen-buffers.md | 1 + docs/console-virtual-terminal-sequences.md | 1 + docs/creating-a-pseudoconsole-session.md | 1 + docs/creation-of-a-console.md | 1 + docs/ctrl-c-and-ctrl-break-signals.md | 1 + docs/getstdhandle.md | 1 + docs/legacymode.md | 1 + docs/setconsolectrlhandler.md | 1 + docs/setconsolemode.md | 1 + docs/writeconsole.md | 1 + 12 files changed, 12 insertions(+) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 9e1931b..2ad3452 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -4,6 +4,7 @@ description: See reference information about the AllocConsole function, which al author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/AllocConsole diff --git a/docs/console-handles.md b/docs/console-handles.md index 9d02037..19c90ce 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -4,6 +4,7 @@ description: A console process uses handles to access the input and screen buffe author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_handles' diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index 9c2ffd5..5f580f2 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -4,6 +4,7 @@ description: A screen buffer is a two-dimensional array of character and color d author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_screen\_buffers' diff --git a/docs/console-virtual-terminal-sequences.md b/docs/console-virtual-terminal-sequences.md index 7ef1037..60158e8 100644 --- a/docs/console-virtual-terminal-sequences.md +++ b/docs/console-virtual-terminal-sequences.md @@ -4,6 +4,7 @@ description: Virtual terminal sequences are control character sequences that can author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MSHAttr: - 'PreferredSiteName:MSDN' diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index 3fcf98b..d37c172 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -4,6 +4,7 @@ description: A pseudoconsole session will allow an application to host the activ author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole, windows pty, pseudo console --- diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index 26e099b..c951660 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -4,6 +4,7 @@ description: The system creates a new console when it starts a console process, author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_creation\_of\_a\_console' diff --git a/docs/ctrl-c-and-ctrl-break-signals.md b/docs/ctrl-c-and-ctrl-break-signals.md index b4d0691..aea246d 100644 --- a/docs/ctrl-c-and-ctrl-break-signals.md +++ b/docs/ctrl-c-and-ctrl-break-signals.md @@ -4,6 +4,7 @@ description: The CTRL+C and CTRL+BREAK key combinations receive special handling author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_ctrl\_c\_and\_ctrl\_break\_signals' diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index 0628a97..047cedc 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -4,6 +4,7 @@ description: Retrieves a handle to the specified standard device (standard input author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - processenv/GetStdHandle diff --git a/docs/legacymode.md b/docs/legacymode.md index b31453d..13ce915 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -4,6 +4,7 @@ description: Legacy console mode is a compatibility tool to assist with running author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, compatibility diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 8a67ba4..92146b2 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -4,6 +4,7 @@ description: Adds or removes an application-defined HandlerRoutine function from author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/SetConsoleCtrlHandler diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index 3cbc27c..254d7e9 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -4,6 +4,7 @@ description: Sets the input mode of a console's input buffer or the output mode author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/SetConsoleMode diff --git a/docs/writeconsole.md b/docs/writeconsole.md index a20a396..192eb42 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -4,6 +4,7 @@ description: Writes a character string to a console screen buffer beginning at t author: miniksa ms.author: miniksa ms.topic: article +ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/WriteConsole From bb483861a90437bc89b3fb8c82bececa47d937bd Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 23 Sep 2020 12:30:36 -0700 Subject: [PATCH 02/53] recategorize some of the pages so they're easier to group and understand going forward. --- docs/about-character-mode-applications.md | 2 +- docs/attaching-to-a-console.md | 2 +- docs/character-mode-applications.md | 2 +- docs/clearing-the-screen.md | 2 +- docs/closing-a-console.md | 2 +- docs/console-aliases.md | 2 +- docs/console-application-issues.md | 2 +- docs/console-buffer-security-and-access-rights.md | 2 +- docs/console-code-pages.md | 2 +- docs/console-control-handlers.md | 2 +- docs/console-functions.md | 2 +- docs/console-handles.md | 2 +- docs/console-input-buffer.md | 2 +- docs/console-modes.md | 2 +- docs/console-process-groups.md | 2 +- docs/console-reference.md | 2 +- docs/console-screen-buffers.md | 2 +- docs/console-selection.md | 2 +- docs/console-structures.md | 2 +- docs/console-virtual-terminal-sequences.md | 2 +- docs/consoles.md | 2 +- docs/creating-a-pseudoconsole-session.md | 2 +- docs/creation-of-a-console.md | 2 +- docs/ctrl-c-and-ctrl-break-signals.md | 2 +- docs/ctrl-close-signal.md | 2 +- docs/high-level-console-i-o.md | 2 +- docs/high-level-console-input-and-output-functions.md | 2 +- docs/high-level-console-modes.md | 2 +- docs/index.md | 2 +- docs/input-and-output-methods.md | 2 +- docs/legacymode.md | 2 +- docs/low-level-console-i-o.md | 2 +- docs/low-level-console-input-functions.md | 2 +- docs/low-level-console-modes.md | 2 +- docs/low-level-console-output-functions.md | 2 +- docs/pseudoconsoles.md | 4 ++-- ...reading-and-writing-blocks-of-characters-and-attributes.md | 2 +- docs/reading-input-buffer-events.md | 2 +- docs/registering-a-control-handler-function.md | 2 +- docs/scrolling-a-screen-buffer-s-contents.md | 2 +- docs/scrolling-a-screen-buffer-s-window.md | 2 +- docs/scrolling-the-screen-buffer.md | 2 +- docs/using-the-console.md | 2 +- docs/using-the-high-level-input-and-output-functions.md | 2 +- docs/window-and-screen-buffer-size.md | 2 +- 45 files changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/about-character-mode-applications.md b/docs/about-character-mode-applications.md index 0dff216..28a7aa8 100644 --- a/docs/about-character-mode-applications.md +++ b/docs/about-character-mode-applications.md @@ -3,7 +3,7 @@ title: About Consoles description: Consoles provide high-level support for simple character mode applications that interact with the user by using functions that read from standard input and write to standard output or standard error. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_about\_character\_mode\_applications' diff --git a/docs/attaching-to-a-console.md b/docs/attaching-to-a-console.md index 917b012..78ab8fe 100644 --- a/docs/attaching-to-a-console.md +++ b/docs/attaching-to-a-console.md @@ -3,7 +3,7 @@ title: Attaching to a Console description: A process can use the AttachConsole function to attach to a console. A process can be attached to one console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_attaching\_to\_a\_console' diff --git a/docs/character-mode-applications.md b/docs/character-mode-applications.md index e2adf27..62f4e10 100644 --- a/docs/character-mode-applications.md +++ b/docs/character-mode-applications.md @@ -3,7 +3,7 @@ title: Consoles description: Consoles manage input and output (I/O) for character-mode applications (applications that do not provide their own graphical user interface). author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_character\_mode\_applications' diff --git a/docs/clearing-the-screen.md b/docs/clearing-the-screen.md index 7a6dfeb..af525ce 100644 --- a/docs/clearing-the-screen.md +++ b/docs/clearing-the-screen.md @@ -3,7 +3,7 @@ title: Clearing the Screen description: How to clear the screen of the Windows Console using the system function or programmatically using public API functions. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_clearing\_the\_screen' diff --git a/docs/closing-a-console.md b/docs/closing-a-console.md index cefe185..5749e06 100644 --- a/docs/closing-a-console.md +++ b/docs/closing-a-console.md @@ -3,7 +3,7 @@ title: Closing a Console description: A process can use the FreeConsole function to detach itself from its console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_closing\_a\_console' diff --git a/docs/console-aliases.md b/docs/console-aliases.md index e7ab3c8..02585d1 100644 --- a/docs/console-aliases.md +++ b/docs/console-aliases.md @@ -3,7 +3,7 @@ title: Console Aliases description: Describes console aliases and how they are used to map source strings to target strings. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - 'base.console\_aliases' diff --git a/docs/console-application-issues.md b/docs/console-application-issues.md index 9ec9687..c40ef93 100644 --- a/docs/console-application-issues.md +++ b/docs/console-application-issues.md @@ -3,7 +3,7 @@ title: Console Application Issues description: Review console application issues, such as functions that take or return OEM character set strings vs. functions that take or return ANSI character set strings. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_application\_issues' diff --git a/docs/console-buffer-security-and-access-rights.md b/docs/console-buffer-security-and-access-rights.md index b105628..b99a2cb 100644 --- a/docs/console-buffer-security-and-access-rights.md +++ b/docs/console-buffer-security-and-access-rights.md @@ -3,7 +3,7 @@ title: Console Buffer Security and Access Rights description: The Windows security model enables you to control access to console input buffers and console screen buffers. For more information about security, see Access-Control Model. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_buffer\_security\_and\_access\_rights' diff --git a/docs/console-code-pages.md b/docs/console-code-pages.md index 64ad799..e9c82e5 100644 --- a/docs/console-code-pages.md +++ b/docs/console-code-pages.md @@ -3,7 +3,7 @@ title: Console Code Pages description: A code page is a mapping of 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_code\_pages' diff --git a/docs/console-control-handlers.md b/docs/console-control-handlers.md index 857d3e5..127e4f9 100644 --- a/docs/console-control-handlers.md +++ b/docs/console-control-handlers.md @@ -3,7 +3,7 @@ title: Console Control Handlers description: Each console process has its own list of control handler functions that are called by the system when the process receives a CTRL+C, CTRL+BREAK, or CTRL+CLOSE signal. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_control\_handlers' diff --git a/docs/console-functions.md b/docs/console-functions.md index c80b413..fc76085 100644 --- a/docs/console-functions.md +++ b/docs/console-functions.md @@ -3,7 +3,7 @@ title: Console Functions description: Describes a complete list of all functions that are used to access a console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: hub-page keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_functions' diff --git a/docs/console-handles.md b/docs/console-handles.md index 19c90ce..bf5091a 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -3,7 +3,7 @@ title: Console Handles description: A console process uses handles to access the input and screen buffers of its console, including the GetStdHandle, CreateFile, or CreateConsoleScreenBuffer functions. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: diff --git a/docs/console-input-buffer.md b/docs/console-input-buffer.md index 0d36c56..f6168a0 100644 --- a/docs/console-input-buffer.md +++ b/docs/console-input-buffer.md @@ -3,7 +3,7 @@ title: Console Input Buffer description: Each console has an input buffer that contains a queue of input event records. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_input\_buffer' diff --git a/docs/console-modes.md b/docs/console-modes.md index 253f344..c01769c 100644 --- a/docs/console-modes.md +++ b/docs/console-modes.md @@ -3,7 +3,7 @@ title: Console Modes description: Associated with each console input buffer is a set of input modes that affects input operations. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_modes' diff --git a/docs/console-process-groups.md b/docs/console-process-groups.md index 358b8be..abd7076 100644 --- a/docs/console-process-groups.md +++ b/docs/console-process-groups.md @@ -3,7 +3,7 @@ title: Console Process Groups description: When a process uses the CreateProcess function to create a new console process, it can specify the CREATE\_NEW\_PROCESS\_GROUP flag to make the new process the root process of a console process group. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_process\_groups' diff --git a/docs/console-reference.md b/docs/console-reference.md index ae2decb..babd7ba 100644 --- a/docs/console-reference.md +++ b/docs/console-reference.md @@ -3,7 +3,7 @@ title: Console Reference description: Describes the three sections of the Console API, console functions, structures, and WinEvents. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: hub-page keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_reference' diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index 5f580f2..3bb4746 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -3,7 +3,7 @@ title: Console Screen Buffers description: A screen buffer is a two-dimensional array of character and color data for output in a console window. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: diff --git a/docs/console-selection.md b/docs/console-selection.md index 24af5fa..0988218 100644 --- a/docs/console-selection.md +++ b/docs/console-selection.md @@ -3,7 +3,7 @@ title: Console Selection description: An accessibility application needs information about the user's selection in the console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_selection' diff --git a/docs/console-structures.md b/docs/console-structures.md index 3f40d84..a688104 100644 --- a/docs/console-structures.md +++ b/docs/console-structures.md @@ -3,7 +3,7 @@ title: Console Structures description: Describes a complete list of the structurest that are used to access a console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: hub-page keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_structures' diff --git a/docs/console-virtual-terminal-sequences.md b/docs/console-virtual-terminal-sequences.md index 60158e8..eaf3a15 100644 --- a/docs/console-virtual-terminal-sequences.md +++ b/docs/console-virtual-terminal-sequences.md @@ -3,7 +3,7 @@ title: Console Virtual Terminal Sequences description: Virtual terminal sequences are control character sequences that can control cursor movement, color/font mode, and other operations when written to the output stream. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MSHAttr: diff --git a/docs/consoles.md b/docs/consoles.md index 79a95bb..77aa349 100644 --- a/docs/consoles.md +++ b/docs/consoles.md @@ -3,7 +3,7 @@ title: Consoles – Windows Desktop description: A console is an application that provides I/O to command-line applications. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_consoles' diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index d37c172..472ecbd 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -3,7 +3,7 @@ title: Creating a Pseudoconsole session description: A pseudoconsole session will allow an application to host the activities of a character-mode application author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole, windows pty, pseudo console diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index c951660..189c757 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -3,7 +3,7 @@ title: Creation of a Console description: The system creates a new console when it starts a console process, a character-mode process whose entry point is the main function. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: diff --git a/docs/ctrl-c-and-ctrl-break-signals.md b/docs/ctrl-c-and-ctrl-break-signals.md index aea246d..7f2ff00 100644 --- a/docs/ctrl-c-and-ctrl-break-signals.md +++ b/docs/ctrl-c-and-ctrl-break-signals.md @@ -3,7 +3,7 @@ title: CTRL+C and CTRL+BREAK Signals description: The CTRL+C and CTRL+BREAK key combinations receive special handling by console processes. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: diff --git a/docs/ctrl-close-signal.md b/docs/ctrl-close-signal.md index 79c824d..173dd3b 100644 --- a/docs/ctrl-close-signal.md +++ b/docs/ctrl-close-signal.md @@ -3,7 +3,7 @@ title: CTRL+CLOSE Signal description: The system generates a CTRL+CLOSE signal when the user closes a console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_ctrl\_close\_signal' diff --git a/docs/high-level-console-i-o.md b/docs/high-level-console-i-o.md index 60dc61c..de5b21b 100644 --- a/docs/high-level-console-i-o.md +++ b/docs/high-level-console-i-o.md @@ -3,7 +3,7 @@ title: High-Level Console I/O description: The high-level I/O functions provide a simple way to read a stream of characters from console input or to write a stream of characters to console output. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_high\_level\_console\_i\_o' diff --git a/docs/high-level-console-input-and-output-functions.md b/docs/high-level-console-input-and-output-functions.md index ca95a86..c0bfaa7 100644 --- a/docs/high-level-console-input-and-output-functions.md +++ b/docs/high-level-console-input-and-output-functions.md @@ -3,7 +3,7 @@ title: High-Level Console Input and Output Functions description: The ReadFile and WriteFile functions, or the ReadConsole and WriteConsole functions, enable an application to read console input and write console output as a stream of characters. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_high\_level\_console\_input\_and\_output\_functions' diff --git a/docs/high-level-console-modes.md b/docs/high-level-console-modes.md index 2bf9e80..ec48db0 100644 --- a/docs/high-level-console-modes.md +++ b/docs/high-level-console-modes.md @@ -3,7 +3,7 @@ title: High-Level Console Modes description: The behavior of the high-level console functions is affected by the console input and output modes. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_high\_level\_console\_modes' diff --git a/docs/index.md b/docs/index.md index 268ec54..8ca5d93 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@ title: Console documentation description: Read the home page for Windows Console documentation, which describes how you can programmatically control and interact with the Windows Console. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: landing-page keywords: console, character mode applications, command line applications, terminal applications, console api --- diff --git a/docs/input-and-output-methods.md b/docs/input-and-output-methods.md index be9615f..d96992e 100644 --- a/docs/input-and-output-methods.md +++ b/docs/input-and-output-methods.md @@ -3,7 +3,7 @@ title: Input and Output Methods description: There are two different approaches to console I/O, the choice of which depends on how much flexibility and control an application needs. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_input\_and\_output\_methods' diff --git a/docs/legacymode.md b/docs/legacymode.md index 13ce915..4f92a1b 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -3,7 +3,7 @@ title: Legacy Console Mode – Windows Desktop description: Legacy console mode is a compatibility tool to assist with running command-line applications that may not work with the Windows 10 console host author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, compatibility diff --git a/docs/low-level-console-i-o.md b/docs/low-level-console-i-o.md index 3378d65..95a0a9f 100644 --- a/docs/low-level-console-i-o.md +++ b/docs/low-level-console-i-o.md @@ -3,7 +3,7 @@ title: Low-Level Console I/O description: The low-level console I/O functions expand an application's control over console I/O by enabling direct access to a console's input and screen buffers. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_low\_level\_console\_i\_o' diff --git a/docs/low-level-console-input-functions.md b/docs/low-level-console-input-functions.md index 5964f83..a182c56 100644 --- a/docs/low-level-console-input-functions.md +++ b/docs/low-level-console-input-functions.md @@ -3,7 +3,7 @@ title: Low-Level Console Input Functions description: A low-level console input functions buffer contains input records that can include information about keyboard, mouse, buffer-resizing, focus, and menu events. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_low\_level\_console\_input\_functions' diff --git a/docs/low-level-console-modes.md b/docs/low-level-console-modes.md index 85962b9..86c2e5c 100644 --- a/docs/low-level-console-modes.md +++ b/docs/low-level-console-modes.md @@ -3,7 +3,7 @@ title: Low-Level Console Modes description: The types of input events reported in a console's input buffer depend on the console's mouse and window input modes. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_low\_level\_console\_modes' diff --git a/docs/low-level-console-output-functions.md b/docs/low-level-console-output-functions.md index 8926d1e..341a2c9 100644 --- a/docs/low-level-console-output-functions.md +++ b/docs/low-level-console-output-functions.md @@ -3,7 +3,7 @@ title: Low-Level Console Output Functions description: The low-level console output functions provide direct access to the character cells of a screen buffer. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_low\_level\_console\_output\_functions' diff --git a/docs/pseudoconsoles.md b/docs/pseudoconsoles.md index a51e04c..7e458c2 100644 --- a/docs/pseudoconsoles.md +++ b/docs/pseudoconsoles.md @@ -3,7 +3,7 @@ title: Pseudoconsoles – Windows Desktop description: A pseudoconsole is a concept used to provide the hosting or servicing aspect of a character-mode application. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole @@ -21,7 +21,7 @@ This functionality is designed for third-party "terminal window" applications to Note that the underlying console session will still be created on behalf of the application requesting the pseudoconsole. All the rules of [console sessions](consoles.md) still apply including the ability for multiple client character-mode applications to connect to the session. -To provide maximum compatibility with the existing world of pseudoterminal functionality, the information provided over the pseudoconsole channel will always be encoded in UTF-8. This does not affect the codepage or encoding of the client applications that are attached. Translation will happen inside the pseudoconsole system as necessary. +To provide maximum compatibility with the existing world of pseudoterminal functionality, the information provided over the pseudoconsole channel will always be encoded in UTF-8. This does not affect the codepage or encoding of the client applications that are attached. Translation will happen inside the pseudoconsole system as necessary. An example for getting started can be found at [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md). diff --git a/docs/reading-and-writing-blocks-of-characters-and-attributes.md b/docs/reading-and-writing-blocks-of-characters-and-attributes.md index d3d51e7..a526c02 100644 --- a/docs/reading-and-writing-blocks-of-characters-and-attributes.md +++ b/docs/reading-and-writing-blocks-of-characters-and-attributes.md @@ -3,7 +3,7 @@ title: Reading and Writing Blocks of Characters and Attributes description: The ReadConsoleOutput function copies a rectangular block of character and color attribute data from a console screen buffer into a destination buffer. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_reading\_and\_writing\_blocks\_of\_characters\_and\_attributes' diff --git a/docs/reading-input-buffer-events.md b/docs/reading-input-buffer-events.md index 7b40fa5..23abc0b 100644 --- a/docs/reading-input-buffer-events.md +++ b/docs/reading-input-buffer-events.md @@ -3,7 +3,7 @@ title: Reading Input Buffer Events description: The ReadConsoleInput function can be used to directly access a console's input buffer. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_reading\_input\_buffer\_events' diff --git a/docs/registering-a-control-handler-function.md b/docs/registering-a-control-handler-function.md index 2d599f7..d84be49 100644 --- a/docs/registering-a-control-handler-function.md +++ b/docs/registering-a-control-handler-function.md @@ -3,7 +3,7 @@ title: Registering a Control Handler Function description: This is an example of the SetConsoleCtrlHandler function that is used to install a control handler. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_registering\_a\_control\_handler\_function' diff --git a/docs/scrolling-a-screen-buffer-s-contents.md b/docs/scrolling-a-screen-buffer-s-contents.md index feb0dfb..e398e52 100644 --- a/docs/scrolling-a-screen-buffer-s-contents.md +++ b/docs/scrolling-a-screen-buffer-s-contents.md @@ -3,7 +3,7 @@ title: Scrolling a Screen Buffer's Contents description: The ScrollConsoleScreenBuffer function moves a block of character cells from one part of a screen buffer to another part of the same screen buffer. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_scrolling\_a\_screen\_buffer\_s\_contents' diff --git a/docs/scrolling-a-screen-buffer-s-window.md b/docs/scrolling-a-screen-buffer-s-window.md index 2d4dfa0..b9277bc 100644 --- a/docs/scrolling-a-screen-buffer-s-window.md +++ b/docs/scrolling-a-screen-buffer-s-window.md @@ -3,7 +3,7 @@ title: Scrolling a Screen Buffer's Window description: The SetConsoleWindowInfo function can be used to scroll the contents of a screen buffer in the console window. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_scrolling\_a\_screen\_buffer\_s\_window' diff --git a/docs/scrolling-the-screen-buffer.md b/docs/scrolling-the-screen-buffer.md index 5842485..3be7dd2 100644 --- a/docs/scrolling-the-screen-buffer.md +++ b/docs/scrolling-the-screen-buffer.md @@ -3,7 +3,7 @@ title: Scrolling the Screen Buffer description: Describes how the console window displays a portion of the active screen buffer. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_scrolling\_the\_screen\_buffer' diff --git a/docs/using-the-console.md b/docs/using-the-console.md index c61c390..8439ca9 100644 --- a/docs/using-the-console.md +++ b/docs/using-the-console.md @@ -3,7 +3,7 @@ title: Using the Console description: The following examples demonstrate how to use various console functions. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: hub-page keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_using\_the\_console' diff --git a/docs/using-the-high-level-input-and-output-functions.md b/docs/using-the-high-level-input-and-output-functions.md index 0e8b927..87f85e8 100644 --- a/docs/using-the-high-level-input-and-output-functions.md +++ b/docs/using-the-high-level-input-and-output-functions.md @@ -3,7 +3,7 @@ title: Using the High-Level Input and Output Functions description: The following example uses the high-level console I/O functions for console I/O. For more information about the high-level console I/O functions, see High-Level Console I/O. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: sample keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_using\_the\_high\_level\_input\_and\_output\_functions' diff --git a/docs/window-and-screen-buffer-size.md b/docs/window-and-screen-buffer-size.md index 1f63e27..fc0b504 100644 --- a/docs/window-and-screen-buffer-size.md +++ b/docs/window-and-screen-buffer-size.md @@ -3,7 +3,7 @@ title: Window and Screen Buffer Size description: The size of a screen buffer is expressed in terms of a coordinate grid based on character cells. author: miniksa ms.author: miniksa -ms.topic: article +ms.topic: conceptual keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_window\_and\_screen\_buffer\_size' From 5998e67da04662d6f399b6f4e5b08b691ccb7ffa Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 23 Sep 2020 12:32:57 -0700 Subject: [PATCH 03/53] Fix title and main heading for the warning from open publishing about duplicate with consoles.md --- docs/character-mode-applications.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/character-mode-applications.md b/docs/character-mode-applications.md index 62f4e10..0956fcd 100644 --- a/docs/character-mode-applications.md +++ b/docs/character-mode-applications.md @@ -1,5 +1,5 @@ --- -title: Consoles +title: Character Mode Applications description: Consoles manage input and output (I/O) for character-mode applications (applications that do not provide their own graphical user interface). author: miniksa ms.author: miniksa @@ -15,8 +15,7 @@ MSHAttr: ms.assetid: ea3ea214-892c-4953-bc22-7905efbc173f --- -# Consoles - +# Character Mode Applications Consoles manage input and output (I/O) for character-mode applications (applications that do not provide their own graphical user interface). From 7a92954204b3551aeac884067f83579bfa119e2a Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 23 Sep 2020 16:20:43 -0700 Subject: [PATCH 04/53] Do some editing. --- docs/allocconsole.md | 7 ------ docs/console-handles.md | 13 ++++++----- docs/console-screen-buffers.md | 8 +++---- docs/creating-a-pseudoconsole-session.md | 2 +- docs/creation-of-a-console.md | 28 ++++++++---------------- docs/ctrl-c-and-ctrl-break-signals.md | 12 +++------- docs/getstdhandle.md | 6 ++--- docs/handlerroutine.md | 4 ++-- docs/setconsolectrlhandler.md | 18 +++++++-------- docs/setconsolemode.md | 20 ++++++++--------- docs/writeconsole.md | 6 +++-- 11 files changed, 52 insertions(+), 72 deletions(-) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 2ad3452..72bca60 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -120,10 +120,3 @@ Requirements [**GetStdHandle**](getstdhandle.md) -  - -  - - - - diff --git a/docs/console-handles.md b/docs/console-handles.md index bf5091a..d026da7 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -21,17 +21,18 @@ ms.assetid: dc723046-b3e9-418a-b386-79be411e5ac8 A console process uses handles to access the input and screen buffers of its console. A process can use the [**GetStdHandle**](getstdhandle.md), [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858), or [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function to open one of these handles. -The [**GetStdHandle**](getstdhandle.md) function provides a mechanism for retrieving the standard input (STDIN), standard output (STDOUT), and standard error (STDERR) handles associated with a process. During console creation, the system creates these handles. Initially, STDIN is a handle to the console's input buffer, and STDOUT and STDERR are handles of the console's active screen buffer. However, the [**SetStdHandle**](setstdhandle.md) function can redirect the standard handles by changing the handle associated with STDIN, STDOUT, or STDERR. Because the parent's standard handles are inherited by any child process, subsequent calls to **GetStdHandle** return the redirected handle. A handle returned by **GetStdHandle** may, therefore, refer to something other than console I/O. For example, before creating a child process, a parent process can use **SetStdHandle** to set a pipe handle to be the STDIN handle that is inherited by the child process. When the child process calls **GetStdHandle**, it gets the pipe handle. This means that the parent process can control the standard handles of the child process. The handles returned by **GetStdHandle** have GENERIC\_READ | GENERIC\_WRITE access unless **SetStdHandle** has been used to set the standard handle to have lesser access. +The [**GetStdHandle**](getstdhandle.md) function provides a mechanism for retrieving the standard input (`STDIN`), standard output (`STDOUT`), and standard error (`STDERR`) handles associated with a process. During console creation, the system creates these handles. Initially, `STDIN` is a handle to the console's input buffer, and `STDOUT` and `STDERR` are handles of the console's active screen buffer. However, the [**SetStdHandle**](setstdhandle.md) function can redirect the standard handles by changing the handle associated with `STDIN`, `STDOUT`, or `STDERR`. Because the parent's standard handles are inherited by any child process, subsequent calls to **GetStdHandle** return the redirected handle. A handle returned by **GetStdHandle** may, therefore, refer to something other than console I/O. For example, before creating a child process, a parent process can use **SetStdHandle** to set a pipe handle to be the `STDIN` handle that is inherited by the child process. When the child process calls **GetStdHandle**, it gets the pipe handle. This means that the parent process can control the standard handles of the child process. The handles returned by **GetStdHandle** have `GENERIC_READ | GENERIC_WRITE` access unless **SetStdHandle** has been used to set the standard handle to have lesser access. -The value of the handles returned by [**GetStdHandle**](getstdhandle.md) are not 0, 1, and 2, so the standard predefined stream constants in Stdio.h (STDIN, STDOUT, and STDERR) cannot be used in functions that require a console handle. +The value of the handles returned by [**GetStdHandle**](getstdhandle.md) are not 0, 1, and 2, so the standard predefined stream constants in Stdio.h (`STDIN`, `STDOUT`, and `STDERR`) cannot be used in functions that require a console handle. -The [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function enables a process to get a handle to its console's input buffer and active screen buffer, even if STDIN and STDOUT have been redirected. To open a handle to a console's input buffer, specify the CONIN$ value in a call to **CreateFile**. Specify the CONOUT$ value in a call to **CreateFile** to open a handle to a console's active screen buffer. **CreateFile** enables you to specify the read/write access of the handle that it returns. +The [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function enables a process to get a handle to its console's input buffer and active screen buffer, even if `STDIN` and `STDOUT` have been redirected. To open a handle to a console's input buffer, specify the `CONIN$` value in a call to **CreateFile**. Specify the `CONOUT$` value in a call to **CreateFile** to open a handle to a console's active screen buffer. **CreateFile** enables you to specify the read/write access of the handle that it returns. -The [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function creates a new screen buffer and returns a handle. This handle can be used in any function that accepts a handle to console output. The new screen buffer is not active until its handle is specified in a call to the [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) function. Note that changing the active screen buffer does not affect the handle returned by [**GetStdHandle**](getstdhandle.md). Similarly, using [**SetStdHandle**](setstdhandle.md) to change the STDOUT handle does not affect the active screen buffer. +The [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function creates a new screen buffer and returns a handle. This handle can be used in any function that accepts a handle to console output. The new screen buffer is not active (displayed) until its handle is specified in a call to the [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) function. Note that changing the active screen buffer does not affect the handle returned by [**GetStdHandle**](getstdhandle.md). Similarly, using [**SetStdHandle**](setstdhandle.md) to change the `STDOUT` handle does not affect the active screen buffer. -Console handles returned by [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) and [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) can be used in any of the console functions that require a handle to a console's input buffer or of a console screen buffer. Handles returned by [**GetStdHandle**](getstdhandle.md) can be used by the console functions if they have not been redirected to refer to something other than console I/O. If a standard handle has been redirected to refer to a file or a pipe, however, the handle can only be used by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions. +Console handles returned by [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) and [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) can be used in any of the console functions that require a handle to a console's input buffer or of a console screen buffer. Handles returned by [**GetStdHandle**](getstdhandle.md) can be used by the console functions if they have not been redirected to refer to something other than console I/O. If a standard handle has been redirected to refer to a file or a pipe, however, the handle can only be used by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions. [**GetFileType**](https://docs.microsoft.com/windows/win32/api/fileapi/nf-fileapi-getfiletype) can assist in determining what device type the handle refers to. A console handle presents as `FILE_TYPE_CHAR`. -A process can use the [**DuplicateHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724251) function to create a duplicate console handle that has different access or inheritability from the original handle. Note, however, that a process can create a duplicate console handle only for its own use. This differs from other handle types (such as file, pipe, or mutex objects), for which **DuplicateHandle** can create a duplicate that is valid for a different process. +A process can use the [**DuplicateHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724251) function to create a duplicate console handle that has different access or inheritability from the original handle. Note, however, that a process can create a duplicate console handle only for its own use. This differs from other handle types (such as file, pipe, or mutex objects), for which **DuplicateHandle** can create a duplicate that is valid for a different process. +Access to a console must be shared during [creation](creation-of-a-console.md) of the other process or may be requested by the other process through the [**AttachConsole**](attachconsole.md) mechanism. To close a console handle, a process can use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index 3bb4746..6577904 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -33,23 +33,23 @@ A number of properties associated with a screen buffer can be set independently - Cursor position, appearance, and visibility. - Output modes (**ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT**). For more information about console output modes, see [High-Level Console Modes](high-level-console-modes.md). -When a screen buffer is created, it contains blanks. Its cursor is visible and positioned at the buffer's origin (0,0), and the window is positioned with its upper left corner at the buffer's origin. The size of the console screen buffer, the window size, the text attributes, and the appearance of the cursor are determined by the user or by the system defaults. To retrieve the current values of the various properties associated with the console screen buffer, use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md), [**GetConsoleCursorInfo**](getconsolecursorinfo.md), and [**GetConsoleMode**](getconsolemode.md) functions. +When a screen buffer is created, it contains space characters in every position. Its cursor is visible and positioned at the buffer's origin (0,0), and the window is positioned with its upper left corner at the buffer's origin. The size of the console screen buffer, the window size, the text attributes, and the appearance of the cursor are determined by the user or by the system defaults. To retrieve the current values of the various properties associated with the console screen buffer, use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md), [**GetConsoleCursorInfo**](getconsolecursorinfo.md), and [**GetConsoleMode**](getconsolemode.md) functions. -Applications that change any of the console screen buffer properties should either create their own screen buffer or save the state of the inherited screen buffer during startup and restore it at exit. +Applications that change any of the console screen buffer properties should either create their own screen buffer or save the state of the inherited screen buffer during startup and restore it at exit. This cooperative behavior is required to ensure that other applications sharing the same console session are not impacted by the changes. ## Cursor Appearance and Position A screen buffer's cursor can be visible or hidden. When it is visible, its appearance can vary, ranging from completely filling a character cell to appearing as a horizontal line at the bottom of the cell. To retrieve information about the appearance and visibility of the cursor, use the [**GetConsoleCursorInfo**](getconsolecursorinfo.md) function. This function reports whether the cursor is visible and describes the appearance of the cursor as the percentage of a character cell that it fills. To set the appearance and visibility of the cursor, use the [**SetConsoleCursorInfo**](setconsolecursorinfo.md) function. -Characters written by the high-level console I/O functions are written at the current cursor location, advancing the cursor to the next location. To determine the current cursor position in the coordinate system of a screen buffer, use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md). You can use [**SetConsoleCursorPosition**](setconsolecursorposition.md) to set the cursor position and, thereby, control the placement of text that is written or echoed by the high-level I/O functions. If you move the cursor, text at the new cursor location is overwritten. +Characters written by the [high-level console I/O functions](high-level-console-i-o.md) are written at the current cursor location, advancing the cursor to the next location. To determine the current cursor position in the coordinate system of a screen buffer, use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md). You can use [**SetConsoleCursorPosition**](setconsolecursorposition.md) to set the cursor position and, thereby, control the placement of text that is written or echoed by the high-level I/O functions. If you move the cursor, text at the new cursor location is overwritten. The position, appearance, and visibility of the cursor are set independently for each screen buffer. ## Character Attributes -Character attributes can be divided into two classes: color and DBCS. The following attributes are defined in the Wincon.h header file. +Character attributes can be divided into two classes: color and DBCS. The following attributes are defined in the `wincon.h` header file. | Attribute | Meaning | diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index 472ecbd..bbaedd2 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -17,7 +17,7 @@ Hosting a pseudoconsole session is a bit different than a traditional console se You can find additional background information about this system on the [initial announcement blog post](https://blogs.msdn.microsoft.com/commandline/2018/08/02/windows-command-line-introducing-the-windows-pseudo-console-conpty/). -Complete examples of using the Pseudoconsole are available on our GitHub repository [Microsoft/console](https://github.com/Microsoft/console) in the samples directory. +Complete examples of using the Pseudoconsole are available on our GitHub repository [Microsoft/terminal](https://github.com/Microsoft/terminal) in the samples directory. ## Preparing the communication channels diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index 189c757..b5993f2 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -18,8 +18,7 @@ ms.assetid: 84ec2559-cade-447e-8594-5b824d3d3e81 # Creation of a Console - -The system creates a new console when it starts a *console process*, a character-mode process whose entry point is the **main** function. For example, the system creates a new console when it starts the command processor. When the command processor starts a new console process, the user can specify whether the system creates a new console for the new process or whether it inherits the command processor's console. +The system creates a new console when it starts a *console process*, a character-mode process whose entry point is the **main** function. For example, the system creates a new console when it starts the command processor `cmd.exe`. When the command processor starts a new console process, the user can specify whether the system creates a new console for the new process or whether it inherits the command processor's console. A process can create a console by using one of the following methods: @@ -45,24 +44,15 @@ The system uses default values if the [**STARTUPINFO**](https://msdn.microsoft.c A process cannot change the location of its console window on the screen, but the following console functions are available to set or retrieve the other properties specified in the [**STARTUPINFO**](https://msdn.microsoft.com/library/windows/desktop/ms686331) structure. -| Function | Description | -|------------------------------------------------------------------|----------------------------------------------------------------------| +| Function | Description | +|---|---| | [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) | Retrieves the window size, screen buffer size, and color attributes. | -| [**SetConsoleWindowInfo**](setconsolewindowinfo.md) | Changes the size of the console window. | -| [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) | Changes the size of the console screen buffer. | -| [**SetConsoleTextAttribute**](setconsoletextattribute.md) | Sets the color attributes. | -| [**SetConsoleTitle**](setconsoletitle.md) | Sets the console window title. | -| [**GetConsoleTitle**](getconsoletitle.md) | Retrieves the console window title. | - - - +| [**SetConsoleWindowInfo**](setconsolewindowinfo.md) | Changes the size of the console window. | +| [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) | Changes the size of the console screen buffer. | +| [**SetConsoleTextAttribute**](setconsoletextattribute.md) | Sets the color attributes. | +| [**SetConsoleTitle**](setconsoletitle.md) | Sets the console window title. | +| [**GetConsoleTitle**](getconsoletitle.md) | Retrieves the console window title. | A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from an inherited console or from a console created by [**AllocConsole**](allocconsole.md). - - - - - - - +A process can use the [**AttachConsole**](attachconsole.md) function to attach itself to another existing console session after using [**FreeConsole**](freeconsole.md) to detach from its own session (or if there is otherwise no attached session). \ No newline at end of file diff --git a/docs/ctrl-c-and-ctrl-break-signals.md b/docs/ctrl-c-and-ctrl-break-signals.md index 7f2ff00..a0f76eb 100644 --- a/docs/ctrl-c-and-ctrl-break-signals.md +++ b/docs/ctrl-c-and-ctrl-break-signals.md @@ -19,17 +19,11 @@ ms.assetid: 5357ed99-920b-47a0-a922-d5faed7bf23e # CTRL+C and CTRL+BREAK Signals -The CTRL+C and CTRL+BREAK key combinations receive special handling by console processes. By default, when a console window has the keyboard focus, CTRL+C or CTRL+BREAK is treated as a signal (SIGINT or SIGBREAK) and not as keyboard input. By default, these signals are passed to all console processes that are attached to the console. (Detached processes are not affected.) The system creates a new thread in each client process to handle the event. The thread raises an exception if the process is being debugged. The debugger can handle the exception or continue with the exception unhandled. +The CTRL+C and CTRL+BREAK key combinations receive special handling by console processes. By default, when a console window has the keyboard focus, CTRL+C or CTRL+BREAK is treated as a signal (SIGINT or SIGBREAK) and not as keyboard input. By default, these signals are passed to all console processes that are attached to the console. (Detached processes are not affected. See [**Creation of a Console**](creation-of-a-console.md).) The system creates a new thread in each client process to handle the event. The thread raises an exception if the process is being debugged. The debugger can handle the exception or continue with the exception unhandled. -CTRL+BREAK is always treated as a signal, but an application can change the default CTRL+C behavior in two ways that prevent the handler functions from being called: +CTRL+BREAK is always treated as a signal, but an application can change the default CTRL+C behavior in two ways that prevent the handler functions from being called: - The [**SetConsoleMode**](setconsolemode.md) function can disable the **ENABLE\_PROCESSED\_INPUT** input mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal. - When [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) is called with **NULL** and **TRUE** values for its parameters, the calling process ignores CTRL+C signals. Normal CTRL+C processing is restored by calling **SetConsoleCtrlHandler** with **NULL** and **FALSE** values. This attribute of ignoring or not ignoring CTRL+C signals is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes. -  - -  - - - - +For more information on how these signals are processed, including timeouts, please see the [**Handler Routine**](handlerroutine.md) callback documentation. diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index 047cedc..383deda 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -87,8 +87,6 @@ The standard device. This parameter can be one of the following values. -  - Return value ------------ @@ -103,7 +101,7 @@ Remarks Handles returned by **GetStdHandle** can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle to the console's input buffer, and the standard output and standard error handles are handles of the console's active screen buffer. These handles can be used by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, the [**ReadConsoleInput**](readconsoleinput.md), [**WriteConsole**](writeconsole.md), or [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) functions). -The standard handles of a process may be redirected by a call to [**SetStdHandle**](setstdhandle.md), in which case **GetStdHandle** returns the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function to get a handle to a console's input buffer. Similarly, you can specify the CONOUT$ value to get a handle to a console's active screen buffer. +The standard handles of a process may be redirected by a call to [**SetStdHandle**](setstdhandle.md), in which case **GetStdHandle** returns the redirected handle. If the standard handles have been redirected, you can specify the `CONIN$` value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function to get a handle to a console's input buffer. Similarly, you can specify the `CONOUT$` value to get a handle to a console's active screen buffer. ### Attach/detach behavior @@ -113,6 +111,8 @@ If the existing value of the standard handle is **NULL**, or the existing value When a parent uses both **CREATE\_NEW\_CONSOLE** and **STARTF\_USESTDHANDLES** to create a console process, standard handles will not be replaced unless the existing value of the standard handle is NULL or a console pseudohandle. +**NOTE:** Console processes *must* start with the standard handles filled or they will be filled automatically with appropriate handles to a new console. Graphical user interface (GUI) applications can be started without the standard handles and they will not be automatically filled. + Examples -------- diff --git a/docs/handlerroutine.md b/docs/handlerroutine.md index a40223f..4273aba 100644 --- a/docs/handlerroutine.md +++ b/docs/handlerroutine.md @@ -66,13 +66,13 @@ The type of control signal received by the handler. This parameter can be one of CTRL_C_EVENT 0 -

A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function.

+

A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function.

CTRL_BREAK_EVENT 1 -

A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent.

+

A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent.

diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 92146b2..432b111 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -38,7 +38,7 @@ api_type: Adds or removes an application-defined [**HandlerRoutine**](handlerroutine.md) function from the list of handler functions for the calling process. -If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals. +If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals. Syntax ------ @@ -59,7 +59,7 @@ A pointer to the application-defined [**HandlerRoutine**](handlerroutine.md) fun *Add* \[in\] If this parameter is **TRUE**, the handler is added; if it is **FALSE**, the handler is removed. -If the *HandlerRoutine* parameter is **NULL**, a **TRUE** value causes the calling process to ignore CTRL+C input, and a **FALSE** value restores normal processing of CTRL+C input. This attribute of ignoring or processing CTRL+C is inherited by child processes. +If the *HandlerRoutine* parameter is **NULL**, a **TRUE** value causes the calling process to ignore CTRL+C input, and a **FALSE** value restores normal processing of CTRL+C input. This attribute of ignoring or processing CTRL+C is inherited by child processes. Return value ------------ @@ -73,17 +73,17 @@ Remarks This function provides a similar notification for console application and services that [**WM\_QUERYENDSESSION**](https://msdn.microsoft.com/library/windows/desktop/aa376890) provides for graphical applications with a message pump. You could also use this function from a graphical application, but there is no guarantee it would arrive before the notification from **WM\_QUERYENDSESSION**. -Each console process has its own list of application-defined [**HandlerRoutine**](handlerroutine.md) functions that handle CTRL+C and CTRL+BREAK signals. The handler functions also handle signals generated by the system when the user closes the console, logs off, or shuts down the system. Initially, the handler list for each process contains only a default handler function that calls the [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) function. A console process adds or removes additional handler functions by calling the **SetConsoleCtrlHandler** function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called. +Each console process has its own list of application-defined [**HandlerRoutine**](handlerroutine.md) functions that handle CTRL+C and CTRL+BREAK signals. The handler functions also handle signals generated by the system when the user closes the console, logs off, or shuts down the system. Initially, the handler list for each process contains only a default handler function that calls the [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) function. A console process adds or removes additional handler functions by calling the **SetConsoleCtrlHandler** function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns `TRUE`. If none of the handlers returns `TRUE`, the default handler is called. -For console processes, the CTRL+C and CTRL+BREAK key combinations are typically treated as signals (**CTRL\_C\_EVENT** and **CTRL\_BREAK\_EVENT**). When a console window with the keyboard focus receives CTRL+C or CTRL+BREAK, the signal is typically passed to all processes sharing that console. +For console processes, the CTRL+C and CTRL+BREAK key combinations are typically treated as signals (**CTRL\_C\_EVENT** and **CTRL\_BREAK\_EVENT**). When a console window with the keyboard focus receives CTRL+C or CTRL+BREAK, the signal is typically passed to all processes sharing that console. -CTRL+BREAK is always treated as a signal, but typical CTRL+C behavior can be changed in three ways that prevent the handler functions from being called: +CTRL+BREAK is always treated as a signal, but typical CTRL+C behavior can be changed in three ways that prevent the handler functions from being called: -- The [**SetConsoleMode**](setconsolemode.md) function can disable the **ENABLE\_PROCESSED\_INPUT** mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal. -- Calling **SetConsoleCtrlHandler** with the **NULL** and **TRUE** arguments causes the calling process to ignore CTRL+C signals. This attribute is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes. -- If a console process is being debugged and CTRL+C signals have not been disabled, the system generates a **DBG\_CONTROL\_C** exception. This exception is raised only for the benefit of the debugger, and an application should never use an exception handler to deal with it. If the debugger handles the exception, an application will not notice the CTRL+C, with one exception: alertable waits will terminate. If the debugger passes the exception on unhandled, CTRL+C is passed to the console process and treated as a signal, as previously discussed. +- The [**SetConsoleMode**](setconsolemode.md) function can disable the **ENABLE\_PROCESSED\_INPUT** mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal. +- Calling **SetConsoleCtrlHandler** with the **NULL** and **TRUE** arguments causes the calling process to ignore CTRL+C signals. This attribute is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes. +- If a console process is being debugged and CTRL+C signals have not been disabled, the system generates a **DBG\_CONTROL\_C** exception. This exception is raised only for the benefit of the debugger, and an application should never use an exception handler to deal with it. If the debugger handles the exception, an application will not notice the CTRL+C, with one exception: alertable waits will terminate. If the debugger passes the exception on unhandled, CTRL+C is passed to the console process and treated as a signal, as previously discussed. -A console process can use the [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) function to send a CTRL+C or CTRL+BREAK signal to a console process group. +A console process can use the [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) function to send a CTRL+C or CTRL+BREAK signal to a console process group. The system generates **CTRL\_CLOSE\_EVENT**, **CTRL\_LOGOFF\_EVENT**, and **CTRL\_SHUTDOWN\_EVENT** signals when the user closes the console, logs off, or shuts down the system so that the process has an opportunity to clean up before termination. Console functions, or any C run-time functions that call console functions, may not work reliably during processing of any of the three signals mentioned previously. The reason is that some or all of the internal console cleanup routines may have been called before executing the process signal handler. diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index 254d7e9..9a3de57 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -92,13 +92,13 @@ The input or output mode to be set. If the *hConsoleHandle* parameter is an inpu ENABLE_LINE_INPUT 0x0002 -

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.

+

The ReadFile or ReadConsole function returns only when a carriage return character ('\r' or 0x0D) is read. If this mode is disabled, the functions return when one or more characters are available.

ENABLE_MOUSE_INPUT 0x0010 -

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 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. Use ReadConsoleInput to receive these events.

@@ -123,8 +123,8 @@ The input or output mode to be set. If the *hConsoleHandle* parameter is an inpu ENABLE_VIRTUAL_TERMINAL_INPUT 0x0200 -

Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into Console Virtual Terminal Sequences that can be retrieved by a supporting application through ReadFile or ReadConsole functions.

-

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences.

+

Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into Console Virtual Terminal Sequences that can be retrieved by a supporting application through ReadFile or ReadConsole functions.

+

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences.

@@ -163,7 +163,7 @@ If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one ENABLE_PROCESSED_OUTPUT 0x0001 -

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 line feed characters are processed.

+

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 ('\b' or 0x08), tab ('\t' or 0x09), bell ('\a' or 0x07), carriage return ('\r' or 0x0D), and line feed ('\n' or 0x0A) characters are processed.

@@ -175,15 +175,15 @@ If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one ENABLE_VIRTUAL_TERMINAL_PROCESSING 0x0004 -

When writing with WriteFile or WriteConsole, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see Console Virtual Terminal Sequences.

+

When writing with WriteFile or WriteConsole, characters are parsed for "ANSI escape", "virtual terminal", and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the Console APIs. For more information, see Console Virtual Terminal Sequences.

DISABLE_NEWLINE_AUTO_RETURN 0x0008

When writing with WriteFile or WriteConsole, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

-

Normally when ENABLE_WRAP_AT_EOL_OUTPUT is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if ENABLE_WRAP_AT_EOL_OUTPUT was off, but the next printable character will be printed as if ENABLE_WRAP_AT_EOL_OUTPUT is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

-

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior.

+

Normally when ENABLE_WRAP_AT_EOL_OUTPUT is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if ENABLE_WRAP_AT_EOL_OUTPUT was off, but the next printable character will be printed as if ENABLE_WRAP_AT_EOL_OUTPUT is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

+

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior.

@@ -193,7 +193,7 @@ If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (swap foreground and background colors) can be useful for other languages to emphasize portions of output.

Setting this console mode flag will allow these attributes to be used in every code page on every language.

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

-

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via Console Virtual Terminal Sequences.

+

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via Console Virtual Terminal Sequences.

@@ -218,7 +218,7 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a [**HandlerRoutine**](handlerroutine.md) function defined by the application. +The **ENABLE\_LINE\_INPUT** and **ENABLE\_ECHO\_INPUT** modes only affect processes that use [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a [**HandlerRoutine**](handlerroutine.md) 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**](readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md). diff --git a/docs/writeconsole.md b/docs/writeconsole.md index 192eb42..6fe7d8a 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -66,7 +66,7 @@ Parameters A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). *lpBuffer* \[in\] -A pointer to a buffer that contains characters to be written to the console screen buffer. +A pointer to a buffer that contains characters to be written to the console screen buffer. This is expected to be an array of either `char` for `WriteConsoleA` or `wchar_t` for `WriteConsoleW`. *nNumberOfCharsToWrite* \[in\] The number of characters to be written. If the total size of the specified number of characters exceeds the available heap, the function fails with **ERROR\_NOT\_ENOUGH\_MEMORY**. @@ -97,7 +97,9 @@ The **WriteConsole** function uses either Unicode characters or ANSI characters **WriteConsole** fails if it is used with a standard handle that is redirected to a file. If an application processes multilingual output that can be redirected, determine whether the output handle is a console handle (one method is to call the [**GetConsoleMode**](getconsolemode.md) function and check whether it succeeds). If the handle is a console handle, call **WriteConsole**. If the handle is not a console handle, the output is redirected and you should call [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) to perform the I/O. Be sure to prefix a Unicode plain text file with a byte order mark. For more information, see [Using Byte Order Marks](https://msdn.microsoft.com/library/windows/desktop/dd374101). -Although an application can use **WriteConsole** in ANSI mode to write ANSI characters, consoles do not support ANSI escape sequences. However, some functions provide equivalent functionality. For more information, see [**SetCursorPos**](https://msdn.microsoft.com/library/windows/desktop/ms648394(v=vs.85).aspx), [**SetConsoleTextAttribute**](setconsoletextattribute.md), and [**GetConsoleCursorInfo**](getconsolecursorinfo.md). +Although an application can use **WriteConsole** in ANSI mode to write ANSI characters, consoles do not support "ANSI escape" or "virtual terminal" sequences unless enabled. See [**Console Virtual Terminal Sequences**](console-virtual-terminal-sequences.md) for more information and for operating system version applicability. + +When virtual terminal escape sequences are not enabled, console functions can provide equivalent functionality. For more information, see [**SetCursorPos**](https://msdn.microsoft.com/library/windows/desktop/ms648394(v=vs.85).aspx), [**SetConsoleTextAttribute**](setconsoletextattribute.md), and [**GetConsoleCursorInfo**](getconsolecursorinfo.md). Requirements ------------ From bed232cbb4419d42b8c611efadeb904e13dfd1e4 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 23 Sep 2020 16:23:04 -0700 Subject: [PATCH 05/53] Revert "Mark important docs as high pri for localization." This reverts commit 9c5152d1a9b601bd3cb8f7babc1ed193aad8e407. --- docs/allocconsole.md | 1 - docs/console-handles.md | 1 - docs/console-screen-buffers.md | 1 - docs/console-virtual-terminal-sequences.md | 1 - docs/creating-a-pseudoconsole-session.md | 1 - docs/creation-of-a-console.md | 1 - docs/ctrl-c-and-ctrl-break-signals.md | 1 - docs/getstdhandle.md | 1 - docs/legacymode.md | 1 - docs/setconsolectrlhandler.md | 1 - docs/setconsolemode.md | 1 - docs/writeconsole.md | 1 - 12 files changed, 12 deletions(-) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 72bca60..543b7ec 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -4,7 +4,6 @@ description: See reference information about the AllocConsole function, which al author: miniksa ms.author: miniksa ms.topic: article -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/AllocConsole diff --git a/docs/console-handles.md b/docs/console-handles.md index d026da7..f398e78 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -4,7 +4,6 @@ description: A console process uses handles to access the input and screen buffe author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_handles' diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index 6577904..da14336 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -4,7 +4,6 @@ description: A screen buffer is a two-dimensional array of character and color d author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_console\_screen\_buffers' diff --git a/docs/console-virtual-terminal-sequences.md b/docs/console-virtual-terminal-sequences.md index eaf3a15..0cfab4d 100644 --- a/docs/console-virtual-terminal-sequences.md +++ b/docs/console-virtual-terminal-sequences.md @@ -4,7 +4,6 @@ description: Virtual terminal sequences are control character sequences that can author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MSHAttr: - 'PreferredSiteName:MSDN' diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index bbaedd2..ff368b2 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -4,7 +4,6 @@ description: A pseudoconsole session will allow an application to host the activ author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole, windows pty, pseudo console --- diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index b5993f2..185e6b7 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -4,7 +4,6 @@ description: The system creates a new console when it starts a console process, author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_creation\_of\_a\_console' diff --git a/docs/ctrl-c-and-ctrl-break-signals.md b/docs/ctrl-c-and-ctrl-break-signals.md index a0f76eb..2d3387c 100644 --- a/docs/ctrl-c-and-ctrl-break-signals.md +++ b/docs/ctrl-c-and-ctrl-break-signals.md @@ -4,7 +4,6 @@ description: The CTRL+C and CTRL+BREAK key combinations receive special handling author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api MS-HAID: - '\_win32\_ctrl\_c\_and\_ctrl\_break\_signals' diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index 383deda..2842d50 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -4,7 +4,6 @@ description: Retrieves a handle to the specified standard device (standard input author: miniksa ms.author: miniksa ms.topic: article -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - processenv/GetStdHandle diff --git a/docs/legacymode.md b/docs/legacymode.md index 4f92a1b..893bdc8 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -4,7 +4,6 @@ description: Legacy console mode is a compatibility tool to assist with running author: miniksa ms.author: miniksa ms.topic: conceptual -ms.localizationpriority: high ms.prod: console keywords: console, character mode applications, command line applications, terminal applications, console api, compatibility diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 432b111..4989e24 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -4,7 +4,6 @@ description: Adds or removes an application-defined HandlerRoutine function from author: miniksa ms.author: miniksa ms.topic: article -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/SetConsoleCtrlHandler diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index 9a3de57..93e7517 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -4,7 +4,6 @@ description: Sets the input mode of a console's input buffer or the output mode author: miniksa ms.author: miniksa ms.topic: article -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/SetConsoleMode diff --git a/docs/writeconsole.md b/docs/writeconsole.md index 6fe7d8a..f2ed443 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -4,7 +4,6 @@ description: Writes a character string to a console screen buffer beginning at t author: miniksa ms.author: miniksa ms.topic: article -ms.localizationpriority: high keywords: console, character mode applications, command line applications, terminal applications, console api f1_keywords: - consoleapi/WriteConsole From c9fd60e5b64e2cca27e77ec25ba5f8219bf14e35 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 14:09:40 -0700 Subject: [PATCH 06/53] Create not recommended template, create documents explaining it, try embedding it in one. --- docs/classic-vs-vt.md | 1 + docs/ecosystem-roadmap.md | 1 + docs/not-recommended-banner.md | 2 ++ docs/readconsoleoutput.md | 1 + 4 files changed, 5 insertions(+) create mode 100644 docs/classic-vs-vt.md create mode 100644 docs/ecosystem-roadmap.md create mode 100644 docs/not-recommended-banner.md diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md new file mode 100644 index 0000000..2fd9f95 --- /dev/null +++ b/docs/classic-vs-vt.md @@ -0,0 +1 @@ +TBD \ No newline at end of file diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md new file mode 100644 index 0000000..2fd9f95 --- /dev/null +++ b/docs/ecosystem-roadmap.md @@ -0,0 +1 @@ +TBD \ No newline at end of file diff --git a/docs/not-recommended-banner.md b/docs/not-recommended-banner.md new file mode 100644 index 0000000..fb76346 --- /dev/null +++ b/docs/not-recommended-banner.md @@ -0,0 +1,2 @@ +> [!IMPORTANT] +> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap.md)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt.md)** document. \ No newline at end of file diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index 68a9d85..923c60b 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -41,6 +41,7 @@ api_type: # ReadConsoleOutput function +[!INCLUDE [not-recommended-banner](not-recommended-banner.md)] Reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer. From 28a411e15287a734c39ec03379af3ce0e6c7caf6 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 15:01:37 -0700 Subject: [PATCH 07/53] shuffle around, add metadata blocks and first header. --- docs/classic-vs-vt.md | 13 ++++++++++++- docs/ecosystem-roadmap.md | 13 ++++++++++++- docs/{ => includes}/not-recommended-banner.md | 0 docs/readconsoleoutput.md | 2 +- 4 files changed, 25 insertions(+), 3 deletions(-) rename docs/{ => includes}/not-recommended-banner.md (100%) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 2fd9f95..e1fc8a6 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -1 +1,12 @@ -TBD \ No newline at end of file +--- +title: Classic Console APIs versus Virtual Terminal Sequences +description: Describes the contrast between the classic Win32 console API surface and the concept of virtual terminal sequences, sometimes also known as escape sequences, to write command-line applications. +author: miniksa +ms.author: miniksa +ms.topic: conceptual +keywords: console, terminal, virtual terminal, escape sequences, vt, vt100, console api +ms.prod: console + +--- + +# Classic Console APIs versus Virtual Terminal Sequences diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 2fd9f95..6157700 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -1 +1,12 @@ -TBD \ No newline at end of file +--- +title: Windows Console and Terminal Ecosystem Roadmap +description: Provides a high-level view of the interactions between and plans for the Windows Console Host, Console APIs, Console Subsystem, and Terminal product. +author: miniksa +ms.author: miniksa +ms.topic: conceptual +keywords: console, terminal, virtual terminal, console host, command-line, subsystem, roadmap, ecosystem +ms.prod: console + +--- + +# Windows Console and Terminal Ecosystem Roadmap diff --git a/docs/not-recommended-banner.md b/docs/includes/not-recommended-banner.md similarity index 100% rename from docs/not-recommended-banner.md rename to docs/includes/not-recommended-banner.md diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index 923c60b..acd1784 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -41,7 +41,7 @@ api_type: # ReadConsoleOutput function -[!INCLUDE [not-recommended-banner](not-recommended-banner.md)] +[!INCLUDE [not-recommended-banner](.\includes\not-recommended-banner.md)] Reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer. From aadc9dabd0ae00c4840358282132b53ad2c95248 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 15:03:04 -0700 Subject: [PATCH 08/53] tiny update to ownership --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f30dfde..14a6a03 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ While some metadata is stored per file (e.g. above), common metadata required by "fileMetadata": { "ms.prod": { "/console/**.yml": "windows"}, "ms.technology": { "/console/**.yml": "desktop"}, - "manager": {"/console/**.yml": "richturn"} + "manager": {"/console/**.yml": "miniksa"} } } } From 98f1f1400f730105167de1e7a78b03a16b7cafb8 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 15:03:49 -0700 Subject: [PATCH 09/53] did I use the wrong slashes for the path. --- docs/readconsoleoutput.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index acd1784..0f85d40 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -41,7 +41,7 @@ api_type: # ReadConsoleOutput function -[!INCLUDE [not-recommended-banner](.\includes\not-recommended-banner.md)] +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer. From 5336993edc8e5706a870706331c7798ae3b96c47 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 16:18:34 -0700 Subject: [PATCH 10/53] Bannerize a ton of APIs that we want to see be disfavored versus virtual terminal sequences. --- docs/about-character-mode-applications.md | 8 - docs/addconsolealias.md | 11 +- docs/allocconsole.md | 1 - docs/attachconsole.md | 8 - docs/attaching-to-a-console.md | 8 - docs/char-info-str.md | 9 +- docs/character-mode-applications.md | 8 - docs/clearing-the-screen.md | 86 +++++++++-- docs/closing-a-console.md | 8 - docs/console-aliases.md | 9 +- ...nsole-buffer-security-and-access-rights.md | 12 +- docs/console-code-pages.md | 10 +- docs/console-control-handlers.md | 8 - docs/console-cursor-info-str.md | 9 +- docs/console-font-info-str.md | 9 +- docs/console-font-infoex.md | 10 +- docs/console-functions.md | 138 +++++++++--------- docs/console-history-info.md | 1 + docs/console-input-buffer.md | 8 - docs/console-modes.md | 9 -- docs/console-process-groups.md | 9 -- docs/console-readconsole-control.md | 12 -- docs/console-screen-buffer-info-str.md | 1 - docs/console-screen-buffer-infoex.md | 8 - docs/console-screen-buffers.md | 8 - docs/console-selection-info-str.md | 9 +- docs/console-selection.md | 9 +- docs/console-structures.md | 7 - docs/console-winevents.md | 5 + docs/createconsolescreenbuffer.md | 10 +- docs/creation-of-a-console.md | 2 +- docs/ctrl-close-signal.md | 8 - docs/fillconsoleoutputattribute.md | 10 +- docs/fillconsoleoutputcharacter.md | 9 +- docs/flushconsoleinputbuffer.md | 9 -- docs/focus-event-record-str.md | 8 - docs/freeconsole.md | 8 - docs/generateconsolectrlevent.md | 8 - docs/getconsolealias.md | 9 +- docs/getconsolealiases.md | 9 +- docs/getconsolealiaseslength.md | 9 +- docs/getconsolealiasexes.md | 9 +- docs/getconsolealiasexeslength.md | 9 +- docs/getconsolecp.md | 8 - docs/getconsolecursorinfo.md | 9 +- docs/getconsoledisplaymode.md | 9 +- docs/getconsolefontsize.md | 9 +- docs/getconsolehistoryinfo.md | 9 +- docs/getconsolemode.md | 8 - docs/getconsoleoriginaltitle.md | 9 +- docs/getconsoleoutputcp.md | 10 -- docs/getconsoleprocesslist.md | 9 -- docs/getconsolescreenbufferinfo.md | 9 +- docs/getconsolescreenbufferinfoex.md | 9 +- docs/getconsoleselectioninfo.md | 9 +- docs/getconsoletitle.md | 9 +- docs/getconsolewindow.md | 9 +- docs/getcurrentconsolefont.md | 10 +- docs/getcurrentconsolefontex.md | 9 +- docs/getlargestconsolewindowsize.md | 9 +- docs/getnumberofconsoleinputevents.md | 9 +- docs/getnumberofconsolemousebuttons.md | 9 +- docs/getstdhandle.md | 9 -- docs/handlerroutine.md | 9 -- docs/high-level-console-i-o.md | 8 - ...evel-console-input-and-output-functions.md | 8 - docs/high-level-console-modes.md | 10 -- docs/includes/no-vt-equiv-banner.md | 2 + docs/includes/no-vt-equiv-shell-banner.md | 2 + docs/input-and-output-methods.md | 8 - docs/input-record-str.md | 8 - docs/key-event-record-str.md | 8 - docs/legacymode.md | 2 +- docs/low-level-console-i-o.md | 9 +- docs/low-level-console-input-functions.md | 1 + docs/low-level-console-modes.md | 9 +- docs/low-level-console-output-functions.md | 29 ++-- docs/menu-event-record-str.md | 9 +- docs/mouse-event-record-str.md | 9 +- docs/peekconsoleinput.md | 9 +- docs/readconsole.md | 9 -- docs/readconsoleinput.md | 8 - docs/readconsoleoutput.md | 2 + docs/readconsoleoutputattribute.md | 9 +- docs/readconsoleoutputcharacter.md | 9 +- ...ing-blocks-of-characters-and-attributes.md | 9 +- docs/reading-input-buffer-events.md | 8 - .../registering-a-control-handler-function.md | 8 - docs/resizepseudoconsole.md | 1 - docs/scrollconsolescreenbuffer.md | 9 +- docs/scrolling-a-screen-buffer-s-contents.md | 9 +- docs/scrolling-a-screen-buffer-s-window.md | 9 +- docs/scrolling-the-screen-buffer.md | 9 +- docs/setconsoleactivescreenbuffer.md | 9 +- docs/setconsolecp.md | 8 - docs/setconsolectrlhandler.md | 9 -- docs/setconsolecursorinfo.md | 9 +- docs/setconsolecursorposition.md | 9 +- docs/setconsoledisplaymode.md | 9 +- docs/setconsolehistoryinfo.md | 9 +- docs/setconsolemode.md | 9 -- docs/setconsoleoutputcp.md | 9 -- docs/setconsolescreenbufferinfoex.md | 9 +- docs/setconsolescreenbuffersize.md | 9 +- docs/setconsoletextattribute.md | 9 +- docs/setconsoletitle.md | 9 +- docs/setconsolewindowinfo.md | 9 +- docs/setcurrentconsolefontex.md | 9 +- docs/setstdhandle.md | 9 -- docs/small-rect-str.md | 9 -- docs/using-the-console.md | 9 -- ...e-high-level-input-and-output-functions.md | 9 +- docs/window-and-screen-buffer-size.md | 8 - docs/window-buffer-size-record-str.md | 9 -- docs/writeconsole.md | 9 -- docs/writeconsoleinput.md | 9 +- docs/writeconsoleoutput.md | 9 -- 117 files changed, 233 insertions(+), 955 deletions(-) create mode 100644 docs/includes/no-vt-equiv-banner.md create mode 100644 docs/includes/no-vt-equiv-shell-banner.md diff --git a/docs/about-character-mode-applications.md b/docs/about-character-mode-applications.md index 28a7aa8..461198d 100644 --- a/docs/about-character-mode-applications.md +++ b/docs/about-character-mode-applications.md @@ -34,11 +34,3 @@ In Windows, the console is built-in and provides a rich API through which charac - [Console Aliases](console-aliases.md) - [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md) - [Console Application Issues](console-application-issues.md) - -  - -  - - - - diff --git a/docs/addconsolealias.md b/docs/addconsolealias.md index eebb5d7..306e99a 100644 --- a/docs/addconsolealias.md +++ b/docs/addconsolealias.md @@ -36,6 +36,7 @@ api_type: # AddConsoleAlias function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Defines a console alias for the specified executable. @@ -74,6 +75,8 @@ Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + Examples -------- @@ -135,11 +138,3 @@ Requirements [**GetConsoleAliases**](getconsolealiases.md) [**GetConsoleAliasExes**](getconsolealiasexes.md) - -  - -  - - - - diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 543b7ec..0e4d2ea 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -118,4 +118,3 @@ Requirements [**FreeConsole**](freeconsole.md) [**GetStdHandle**](getstdhandle.md) - diff --git a/docs/attachconsole.md b/docs/attachconsole.md index 1512b3e..47de7f7 100644 --- a/docs/attachconsole.md +++ b/docs/attachconsole.md @@ -143,11 +143,3 @@ Requirements [**FreeConsole**](freeconsole.md) [**GetConsoleProcessList**](getconsoleprocesslist.md) - -  - -  - - - - diff --git a/docs/attaching-to-a-console.md b/docs/attaching-to-a-console.md index 78ab8fe..26eff3b 100644 --- a/docs/attaching-to-a-console.md +++ b/docs/attaching-to-a-console.md @@ -21,11 +21,3 @@ ms.assetid: 348e572f-2448-4384-9822-fab01d4ba255 A process can use the [**AttachConsole**](attachconsole.md) function to attach to a console. A process can be attached to one console. A console can have many processes attached to it. To retrieve a list of the processes attached to a console, call the [**GetConsoleProcessList**](getconsoleprocesslist.md) function. - -  - -  - - - - diff --git a/docs/char-info-str.md b/docs/char-info-str.md index b16b181..f210513 100644 --- a/docs/char-info-str.md +++ b/docs/char-info-str.md @@ -32,6 +32,7 @@ api_type: # CHAR\_INFO structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Specifies a Unicode or ANSI character and its attributes. This structure is used by console functions to read from and write to a console screen buffer. @@ -233,11 +234,3 @@ Requirements [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) [**WriteConsoleOutput**](writeconsoleoutput.md) - -  - -  - - - - diff --git a/docs/character-mode-applications.md b/docs/character-mode-applications.md index 0956fcd..dd0268d 100644 --- a/docs/character-mode-applications.md +++ b/docs/character-mode-applications.md @@ -26,11 +26,3 @@ This overview describes support for character-mode applications. - [About Consoles](about-character-mode-applications.md) - [Using the Console](using-the-console.md) - [Console Reference](console-reference.md) - -  - -  - - - - diff --git a/docs/clearing-the-screen.md b/docs/clearing-the-screen.md index af525ce..41c3112 100644 --- a/docs/clearing-the-screen.md +++ b/docs/clearing-the-screen.md @@ -18,27 +18,89 @@ ms.assetid: 2097cc53-13b9-4f29-9d2c-feea56a27cb8 # Clearing the Screen -There are two ways to clear the screen in a console application. +There are four ways to clear the screen in a console application. ## Example 1 +> [!TIP] +> This is the recommended method using **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for all new development. For more information, see the discussion of **[classic console APIs versus virtual terminal sequences](classic-vs-vt.md)**. -The first method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter to clear the screen. +The first method is to set your application up for virtual terminal output sequences and then call the "clear screen" command. ```C -#include + +#include int main( void ) { - system("cls"); + HANDLE hStdout; + + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + + // Fetch existing console mode so we correctly add a flag and not turn off others + DWORD mode = 0; + if (!GetConsoleMode(hStdOut, &mode)) + { + return ::GetLastError(); + } + + // Hold original mode to restore on exit to be cooperative with other command-line apps. + const DWORD originalMode = mode; + mode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING; + + // Try to set the mode. + if (!SetConsoleMode(hStdOut, mode)) + { + return ::GetLastError(); + } + + // Write the sequence for clearing the display. + DWORD written = 0; + PCWSTR sequence = L"\x1b[2J"; + if (!WriteConsoleW(hStdOut, sequence, ARRAYSIZE(sequence), &written, NULL)) + { + // If we fail, try to restore the mode on the way out. + SetConsoleMode(hStdOut, originalMode); + return ::GetLastError(); + } + + // Restore the mode on the way out to be nice to other command-line applications. + SetConsoleMode(hStdOut, originalMode); + return 0; } + ``` +A variation on this command is to use the "clear buffer" command to remove all history scrolling up and down, not just what is visible within the window. + +```C +... + +PCWSTR sequence = L"\x1b[3J"; + +... +``` + +You can find additional variations on this command in the virtual terminal sequences documentation on **[Erase In Display](console-virtual-terminal-sequences.md#text-modification)**. + ## Example 2 +The second method is to write a function to scroll the contents of the screen or buffer and set a fill for the revealed space. -The second method is to write a function to programmatically clear the screen using the [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) and [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) functions. The following sample code demonstrates this technique. +This matches the behavior of (CMD OR POWERSHELL, WHICH WAS IT) + +```C +``` + +## Example 3 + + +The third method is to write a function to programmatically clear the screen using the [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) and [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) functions. + +This matches the behavior of (CMD OR POWERSHELL, WHICH WAS IT) + +The following sample code demonstrates this technique. ```C #include @@ -105,10 +167,16 @@ int main( void ) } ``` -  - -  - +## Example 4 +The fourth method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter to clear the screen. +```C +#include +int main( void ) +{ + system("cls"); + return 0; +} +``` diff --git a/docs/closing-a-console.md b/docs/closing-a-console.md index 5749e06..9df5c92 100644 --- a/docs/closing-a-console.md +++ b/docs/closing-a-console.md @@ -21,11 +21,3 @@ ms.assetid: 254b7cfc-4dee-452f-a409-4fc90d20d4c1 A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its console. If other processes share the console, the console is not destroyed, but the process that called **FreeConsole** cannot refer to it. After calling **FreeConsole**, the process can use [**AllocConsole**](allocconsole.md) to create a new console or [**AttachConsole**](attachconsole.md) to attach to another console. A console is closed when the last process attached to it terminates or calls [**FreeConsole**](freeconsole.md). - -  - -  - - - - diff --git a/docs/console-aliases.md b/docs/console-aliases.md index 02585d1..36b11a7 100644 --- a/docs/console-aliases.md +++ b/docs/console-aliases.md @@ -16,6 +16,7 @@ ms.assetid: 8169708b-83da-47ef-94be-eca3ca7d0a5b # Console Aliases +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Console aliases are used to map source strings to target strings. For example, you can define a console alias that maps "test" to "cd \\a\_very\_long\_path\\test". When you type "test" at the command line, the console subsystem expands the alias and executes the specified cd command. @@ -36,11 +37,3 @@ To add parameters to a console alias macro using Doskey.exe, use the batch param All instances of an executable file running in the same console window share any defined console aliases. Multiple instances of the same executable file running in different console windows do not share console aliases. Different executable files running in the same console window do not share console aliases. To retrieve the target string for a specified source string and executable file, use the [**GetConsoleAlias**](getconsolealias.md) function. To retrieve all aliases for a specified executable file, use the [**GetConsoleAliases**](getconsolealiases.md) function. To retrieve the names of all aliases for which console aliases have been defined, use the [**GetConsoleAliasExes**](getconsolealiasexes.md) function. - -  - -  - - - - diff --git a/docs/console-buffer-security-and-access-rights.md b/docs/console-buffer-security-and-access-rights.md index b99a2cb..e9ef39b 100644 --- a/docs/console-buffer-security-and-access-rights.md +++ b/docs/console-buffer-security-and-access-rights.md @@ -17,7 +17,6 @@ ms.assetid: f9a50063-8fc8-4cd1-8f24-9ae3946d3119 # Console Buffer Security and Access Rights - The Windows security model enables you to control access to console input buffers and console screen buffers. For more information about security, see [Access-Control Model](https://msdn.microsoft.com/library/windows/desktop/aa374876). You can specify a [security descriptor](https://msdn.microsoft.com/library/windows/desktop/aa379563) for the console input and console screen buffers when you call the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) or [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function. If you specify **NULL**, the object gets a default security descriptor. The ACLs in the default security descriptor for a console buffer come from the primary or impersonation token of the creator. @@ -32,12 +31,5 @@ The valid access rights include the **GENERIC\_READ** and **GENERIC\_WRITE** [ge | **GENERIC\_READ** (0x80000000L) | Requests read access to the console screen buffer, enabling the process to read data from the buffer. | | **GENERIC\_WRITE** (0x40000000L) | Requests write access to the console screen buffer, enabling the process to write data to the buffer. | - - - - - - - - - +> [!NOTE] +> TODO: Write a note here about UWP readback blocking and link to the RS4 feature for "console UWPs" \ No newline at end of file diff --git a/docs/console-code-pages.md b/docs/console-code-pages.md index e9c82e5..6346b5f 100644 --- a/docs/console-code-pages.md +++ b/docs/console-code-pages.md @@ -17,7 +17,6 @@ ms.assetid: 98d56bb1-83d2-40aa-adac-fc2e8beab337 # Console Code Pages - A *code page* is a mapping of 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. Associated with each console are two code pages: one for input and one for output. A console uses its input code page to translate keyboard input into the corresponding character value. It uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. An application can use the [**SetConsoleCP**](setconsolecp.md) and [**GetConsoleCP**](getconsolecp.md) functions to set and retrieve a console's input code pages and the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**GetConsoleOutputCP**](getconsoleoutputcp.md) functions to set and retrieve its output code pages. @@ -28,10 +27,5 @@ The identifiers of the code pages available on the local computer are stored in For information about using the registry functions to determine the available code pages, see [**Registry**](https://msdn.microsoft.com/library/windows/desktop/ms724871). -  - -  - - - - +> [!TIP] +> It is recommended for all new and updated command-line applications to avoid code pages and use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. UTF-16 format text can be sent to the *W* family of console APIs. UTF-8 format text can be sent to the *A* family of console APIs after ensuring the code page is first set to **[65001 (CP_UTF8)](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)** with the [**SetConsoleCP**](setconsolecp.md) and [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. diff --git a/docs/console-control-handlers.md b/docs/console-control-handlers.md index 127e4f9..194b4b7 100644 --- a/docs/console-control-handlers.md +++ b/docs/console-control-handlers.md @@ -23,11 +23,3 @@ Each console process has its own list of control handler functions that are call The function's *dwCtrlType* parameter identifies which control signal was received, and the return value indicates whether the signal was handled. For an example of a control handler function, see [Registering a Control Handler Function](registering-a-control-handler-function.md). - -  - -  - - - - diff --git a/docs/console-cursor-info-str.md b/docs/console-cursor-info-str.md index e3c1ad9..6a9dc43 100644 --- a/docs/console-cursor-info-str.md +++ b/docs/console-cursor-info-str.md @@ -33,6 +33,7 @@ api_type: # CONSOLE\_CURSOR\_INFO structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Contains information about the console cursor. @@ -89,11 +90,3 @@ Requirements [**GetConsoleCursorInfo**](getconsolecursorinfo.md) [**SetConsoleCursorInfo**](setconsolecursorinfo.md) - -  - -  - - - - diff --git a/docs/console-font-info-str.md b/docs/console-font-info-str.md index b58b928..408277a 100644 --- a/docs/console-font-info-str.md +++ b/docs/console-font-info-str.md @@ -32,6 +32,7 @@ api_type: # CONSOLE\_FONT\_INFO structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Contains information for a console font. @@ -89,11 +90,3 @@ Requirements [**COORD**](coord-str.md) [**GetCurrentConsoleFont**](getcurrentconsolefont.md) - -  - -  - - - - diff --git a/docs/console-font-infoex.md b/docs/console-font-infoex.md index 4a9d537..b8196ef 100644 --- a/docs/console-font-infoex.md +++ b/docs/console-font-infoex.md @@ -32,6 +32,7 @@ api_type: # CONSOLE\_FONT\_INFOEX structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Contains extended information for a console font. @@ -101,13 +102,4 @@ Requirements ## See also - [**GetCurrentConsoleFontEx**](getcurrentconsolefontex.md) - -  - -  - - - - diff --git a/docs/console-functions.md b/docs/console-functions.md index fc76085..368d67a 100644 --- a/docs/console-functions.md +++ b/docs/console-functions.md @@ -20,73 +20,71 @@ ms.assetid: 2a0e5dcc-be48-42ab-a05a-96f68d012a67 The following functions are used to access a console. - -| Function | Description | -|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| -| [**AddConsoleAlias**](addconsolealias.md) | Defines a console alias for the specified executable. | -| [**AllocConsole**](allocconsole.md) | Allocates a new console for the calling process. | -| [**AttachConsole**](attachconsole.md) | Attaches the calling process to the console of the specified process. | -| [**ClosePseudoConsole**](closepseudoconsole.md) | Closes a pseudoconsole from the given handle. | -| [**CreatePseudoConsole**](createpseudoconsole.md) | Allocates a new pseudoconsole for the calling process. | -| [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) | Creates a console screen buffer. | -| [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Sets the text and background color attributes for a specified number of character cells. | -| [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a character to the console screen buffer a specified number of times. | -| [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) | Flushes the console input buffer. | -| [**FreeConsole**](freeconsole.md) | Detaches the calling process from its console. | -| [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) | Sends a specified signal to a console process group that shares the console associated with the calling process. | -| [**GetConsoleAlias**](getconsolealias.md) | Retrieves the specified alias for the specified executable. | -| [**GetConsoleAliases**](getconsolealiases.md) | Retrieves all defined console aliases for the specified executable. | -| [**GetConsoleAliasesLength**](getconsolealiaseslength.md) | Returns the size, in bytes, of the buffer needed to store all of the console aliases for the specified executable. | -| [**GetConsoleAliasExes**](getconsolealiasexes.md) | Retrieves the names of all executables with console aliases defined. | -| [**GetConsoleAliasExesLength**](getconsolealiasexeslength.md) | Returns the size, in bytes, of the buffer needed to store the names of all executables that have console aliases defined. | -| [**GetConsoleCP**](getconsolecp.md) | Retrieves the input code page used by the console associated with the calling process. | -| [**GetConsoleCursorInfo**](getconsolecursorinfo.md) | Retrieves information about the size and visibility of the cursor for the specified console screen buffer. | -| [**GetConsoleDisplayMode**](getconsoledisplaymode.md) | Retrieves the display mode of the current console. | -| [**GetConsoleFontSize**](getconsolefontsize.md) | Retrieves the size of the font used by the specified console screen buffer. | -| [**GetConsoleHistoryInfo**](getconsolehistoryinfo.md) | Retrieves the history settings for the calling process's console. | -| [**GetConsoleMode**](getconsolemode.md) | Retrieves the current input mode of a console's input buffer or the current output mode of a console screen buffer. | -| [**GetConsoleOriginalTitle**](getconsoleoriginaltitle.md) | Retrieves the original title for the current console window. | -| [**GetConsoleOutputCP**](getconsoleoutputcp.md) | Retrieves the output code page used by the console associated with the calling process. | -| [**GetConsoleProcessList**](getconsoleprocesslist.md) | Retrieves a list of the processes attached to the current console. | -| [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) | Retrieves information about the specified console screen buffer. | -| [**GetConsoleScreenBufferInfoEx**](getconsolescreenbufferinfoex.md) | Retrieves extended information about the specified console screen buffer. | -| [**GetConsoleSelectionInfo**](getconsoleselectioninfo.md) | Retrieves information about the current console selection. | -| [**GetConsoleTitle**](getconsoletitle.md) | Retrieves the title for the current console window. | -| [**GetConsoleWindow**](getconsolewindow.md) | Retrieves the window handle used by the console associated with the calling process. | -| [**GetCurrentConsoleFont**](getcurrentconsolefont.md) | Retrieves information about the current console font. | -| [**GetCurrentConsoleFontEx**](getcurrentconsolefontex.md) | Retrieves extended information about the current console font. | -| [**GetLargestConsoleWindowSize**](getlargestconsolewindowsize.md) | Retrieves the size of the largest possible console window. | -| [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) | Retrieves the number of unread input records in the console's input buffer. | -| [**GetNumberOfConsoleMouseButtons**](getnumberofconsolemousebuttons.md) | Retrieves the number of buttons on the mouse used by the current console. | -| [**GetStdHandle**](getstdhandle.md) | Retrieves a handle for the standard input, standard output, or standard error device. | -| [**HandlerRoutine**](handlerroutine.md) | An application-defined function used with the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function. | -| [**PeekConsoleInput**](peekconsoleinput.md) | Reads data from the specified console input buffer without removing it from the buffer. | -| [**ReadConsole**](readconsole.md) | Reads character input from the console input buffer and removes it from the buffer. | -| [**ReadConsoleInput**](readconsoleinput.md) | Reads data from a console input buffer and removes it from the buffer. | -| [**ReadConsoleOutput**](readconsoleoutput.md) | Reads character and color attribute data from a rectangular block of character cells in a console screen buffer. | -| [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a specified number of foreground and background color attributes from consecutive cells of a console screen buffer. | -| [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a number of characters from consecutive cells of a console screen buffer. | -| [**ResizePseudoConsole**](resizepseudoconsole.md) | Resizes the internal buffers for a pseudoconsole to the given size. | -| [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) | Moves a block of data in a screen buffer. | -| [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) | Sets the specified screen buffer to be the currently displayed console screen buffer. | -| [**SetConsoleCP**](setconsolecp.md) | Sets the input code page used by the console associated with the calling process. | -| [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) | Adds or removes an application-defined [**HandlerRoutine**](handlerroutine.md) from the list of handler functions for the calling process. | -| [**SetConsoleCursorInfo**](setconsolecursorinfo.md) | Sets the size and visibility of the cursor for the specified console screen buffer. | -| [**SetConsoleCursorPosition**](setconsolecursorposition.md) | Sets the cursor position in the specified console screen buffer. | -| [**SetConsoleDisplayMode**](setconsoledisplaymode.md) | Sets the display mode of the specified console screen buffer. | -| [**SetConsoleHistoryInfo**](setconsolehistoryinfo.md) | Sets the history settings for the calling process's console. | -| [**SetConsoleMode**](setconsolemode.md) | Sets the input mode of a console's input buffer or the output mode of a console screen buffer. | -| [**SetConsoleOutputCP**](setconsoleoutputcp.md) | Sets the output code page used by the console associated with the calling process. | -| [**SetConsoleScreenBufferInfoEx**](setconsolescreenbufferinfoex.md) | Sets extended information about the specified console screen buffer. | -| [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) | Changes the size of the specified console screen buffer. | -| [**SetConsoleTextAttribute**](setconsoletextattribute.md) | Sets the foreground (text) and background color attributes of characters written to the console screen buffer. | -| [**SetConsoleTitle**](setconsoletitle.md) | Sets the title for the current console window. | -| [**SetConsoleWindowInfo**](setconsolewindowinfo.md) | Sets the current size and position of a console screen buffer's window. | -| [**SetCurrentConsoleFontEx**](setcurrentconsolefontex.md) | Sets extended information about the current console font. | -| [**SetStdHandle**](setstdhandle.md) | Sets the handle for the standard input, standard output, or standard error device. | -| [**WriteConsole**](writeconsole.md) | Writes a character string to a console screen buffer beginning at the current cursor location. | -| [**WriteConsoleInput**](writeconsoleinput.md) | Writes data directly to the console input buffer. | -| [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. | -| [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) | Copies a number of foreground and background color attributes to consecutive cells of a console screen buffer. | -| [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Copies a number of characters to consecutive cells of a console screen buffer. | - +| Function | Description | +|---|---| +| [**AddConsoleAlias**](addconsolealias.md) | Defines a console alias for the specified executable. | +| [**AllocConsole**](allocconsole.md) | Allocates a new console for the calling process. | +| [**AttachConsole**](attachconsole.md) | Attaches the calling process to the console of the specified process. | +| [**ClosePseudoConsole**](closepseudoconsole.md) | Closes a pseudoconsole from the given handle. | +| [**CreatePseudoConsole**](createpseudoconsole.md) | Allocates a new pseudoconsole for the calling process. | +| [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) | Creates a console screen buffer. | +| [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Sets the text and background color attributes for a specified number of character cells. | +| [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a character to the console screen buffer a specified number of times. | +| [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) | Flushes the console input buffer. | +| [**FreeConsole**](freeconsole.md) | Detaches the calling process from its console. | +| [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) | Sends a specified signal to a console process group that shares the console associated with the calling process. | +| [**GetConsoleAlias**](getconsolealias.md) | Retrieves the specified alias for the specified executable. | +| [**GetConsoleAliases**](getconsolealiases.md) | Retrieves all defined console aliases for the specified executable. | +| [**GetConsoleAliasesLength**](getconsolealiaseslength.md) | Returns the size, in bytes, of the buffer needed to store all of the console aliases for the specified executable. | +| [**GetConsoleAliasExes**](getconsolealiasexes.md) | Retrieves the names of all executables with console aliases defined. | +| [**GetConsoleAliasExesLength**](getconsolealiasexeslength.md) | Returns the size, in bytes, of the buffer needed to store the names of all executables that have console aliases defined. | +| [**GetConsoleCP**](getconsolecp.md) | Retrieves the input code page used by the console associated with the calling process. | +| [**GetConsoleCursorInfo**](getconsolecursorinfo.md) | Retrieves information about the size and visibility of the cursor for the specified console screen buffer. | +| [**GetConsoleDisplayMode**](getconsoledisplaymode.md) | Retrieves the display mode of the current console. | +| [**GetConsoleFontSize**](getconsolefontsize.md) | Retrieves the size of the font used by the specified console screen buffer. | +| [**GetConsoleHistoryInfo**](getconsolehistoryinfo.md) | Retrieves the history settings for the calling process's console. | +| [**GetConsoleMode**](getconsolemode.md) | Retrieves the current input mode of a console's input buffer or the current output mode of a console screen buffer. | +| [**GetConsoleOriginalTitle**](getconsoleoriginaltitle.md) | Retrieves the original title for the current console window. | +| [**GetConsoleOutputCP**](getconsoleoutputcp.md) | Retrieves the output code page used by the console associated with the calling process. | +| [**GetConsoleProcessList**](getconsoleprocesslist.md) | Retrieves a list of the processes attached to the current console. | +| [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) | Retrieves information about the specified console screen buffer. | +| [**GetConsoleScreenBufferInfoEx**](getconsolescreenbufferinfoex.md) | Retrieves extended information about the specified console screen buffer. | +| [**GetConsoleSelectionInfo**](getconsoleselectioninfo.md) | Retrieves information about the current console selection. | +| [**GetConsoleTitle**](getconsoletitle.md) | Retrieves the title for the current console window. | +| [**GetConsoleWindow**](getconsolewindow.md) | Retrieves the window handle used by the console associated with the calling process. | +| [**GetCurrentConsoleFont**](getcurrentconsolefont.md) | Retrieves information about the current console font. | +| [**GetCurrentConsoleFontEx**](getcurrentconsolefontex.md) | Retrieves extended information about the current console font. | +| [**GetLargestConsoleWindowSize**](getlargestconsolewindowsize.md) | Retrieves the size of the largest possible console window. | +| [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) | Retrieves the number of unread input records in the console's input buffer. | +| [**GetNumberOfConsoleMouseButtons**](getnumberofconsolemousebuttons.md) | Retrieves the number of buttons on the mouse used by the current console. | +| [**GetStdHandle**](getstdhandle.md) | Retrieves a handle for the standard input, standard output, or standard error device. | +| [**HandlerRoutine**](handlerroutine.md) | An application-defined function used with the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function. | +| [**PeekConsoleInput**](peekconsoleinput.md) | Reads data from the specified console input buffer without removing it from the buffer. | +| [**ReadConsole**](readconsole.md) | Reads character input from the console input buffer and removes it from the buffer. | +| [**ReadConsoleInput**](readconsoleinput.md) | Reads data from a console input buffer and removes it from the buffer. | +| [**ReadConsoleOutput**](readconsoleoutput.md) | Reads character and color attribute data from a rectangular block of character cells in a console screen buffer. | +| [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a specified number of foreground and background color attributes from consecutive cells of a console screen buffer. | +| [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a number of characters from consecutive cells of a console screen buffer. | +| [**ResizePseudoConsole**](resizepseudoconsole.md) | Resizes the internal buffers for a pseudoconsole to the given size. | +| [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) | Moves a block of data in a screen buffer. | +| [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) | Sets the specified screen buffer to be the currently displayed console screen buffer. | +| [**SetConsoleCP**](setconsolecp.md) | Sets the input code page used by the console associated with the calling process. | +| [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) | Adds or removes an application-defined [**HandlerRoutine**](handlerroutine.md) from the list of handler functions for the calling process. | +| [**SetConsoleCursorInfo**](setconsolecursorinfo.md) | Sets the size and visibility of the cursor for the specified console screen buffer. | +| [**SetConsoleCursorPosition**](setconsolecursorposition.md) | Sets the cursor position in the specified console screen buffer. | +| [**SetConsoleDisplayMode**](setconsoledisplaymode.md) | Sets the display mode of the specified console screen buffer. | +| [**SetConsoleHistoryInfo**](setconsolehistoryinfo.md) | Sets the history settings for the calling process's console. | +| [**SetConsoleMode**](setconsolemode.md) | Sets the input mode of a console's input buffer or the output mode of a console screen buffer. | +| [**SetConsoleOutputCP**](setconsoleoutputcp.md) | Sets the output code page used by the console associated with the calling process. | +| [**SetConsoleScreenBufferInfoEx**](setconsolescreenbufferinfoex.md) | Sets extended information about the specified console screen buffer. | +| [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) | Changes the size of the specified console screen buffer. | +| [**SetConsoleTextAttribute**](setconsoletextattribute.md) | Sets the foreground (text) and background color attributes of characters written to the console screen buffer. | +| [**SetConsoleTitle**](setconsoletitle.md) | Sets the title for the current console window. | +| [**SetConsoleWindowInfo**](setconsolewindowinfo.md) | Sets the current size and position of a console screen buffer's window. | +| [**SetCurrentConsoleFontEx**](setcurrentconsolefontex.md) | Sets extended information about the current console font. | +| [**SetStdHandle**](setstdhandle.md) | Sets the handle for the standard input, standard output, or standard error device. | +| [**WriteConsole**](writeconsole.md) | Writes a character string to a console screen buffer beginning at the current cursor location. | +| [**WriteConsoleInput**](writeconsoleinput.md) | Writes data directly to the console input buffer. | +| [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. | +| [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) | Copies a number of foreground and background color attributes to consecutive cells of a console screen buffer. | +| [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Copies a number of characters to consecutive cells of a console screen buffer. | diff --git a/docs/console-history-info.md b/docs/console-history-info.md index 834ca22..e97f038 100644 --- a/docs/console-history-info.md +++ b/docs/console-history-info.md @@ -32,6 +32,7 @@ api_type: # CONSOLE\_HISTORY\_INFO structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Contains information about the console history. diff --git a/docs/console-input-buffer.md b/docs/console-input-buffer.md index f6168a0..eda90d9 100644 --- a/docs/console-input-buffer.md +++ b/docs/console-input-buffer.md @@ -72,11 +72,3 @@ If the input event is a buffer-resizing event, the **Event** member of [**INPUT\ If the user reduces the size of the console screen buffer, any data in the discarded portion of the buffer is lost. Changes to the console screen buffer size as a result of application calls to the [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) function are not generated as buffer-resizing events. - -  - -  - - - - diff --git a/docs/console-modes.md b/docs/console-modes.md index c01769c..efedd70 100644 --- a/docs/console-modes.md +++ b/docs/console-modes.md @@ -17,17 +17,8 @@ ms.assetid: f0dcc123-3b12-44c4-8f94-920203f5198e # Console Modes - Associated with each console input buffer is a set of input modes that affects input operations. Similarly, each console screen buffer has a set of output modes that affects output operations. The input modes can be divided into two groups: those that affect the high-level input functions and those that affect the low-level input functions. The output modes only affect applications that use the high-level output functions. The [**GetConsoleMode**](getconsolemode.md) function reports the current input mode of a console's input buffer or the current output mode of a screen buffer. The [**SetConsoleMode**](setconsolemode.md) function sets the current mode of either a console input buffer or a screen buffer. If a console has multiple screen buffers, the output modes of each can be different. An application can change I/O modes at any time. For more information about the console modes that affect high-level and low-level I/O operations, see [High-Level Console Modes](high-level-console-modes.md) and [Low-Level Console Modes](low-level-console-modes.md). The [**GetConsoleDisplayMode**](getconsoledisplaymode.md) function reports whether the current console is in full-screen mode and whether it communicates directly with the hardware. - -  - -  - - - - diff --git a/docs/console-process-groups.md b/docs/console-process-groups.md index abd7076..bc1d00f 100644 --- a/docs/console-process-groups.md +++ b/docs/console-process-groups.md @@ -17,15 +17,6 @@ ms.assetid: 6cfe5b4b-d677-4747-bbf2-c7243db2346e # Console Process Groups - When a process uses the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) function to create a new console process, it can specify the **CREATE\_NEW\_PROCESS\_GROUP** flag to make the new process the root process of a console process group. The process group includes all processes that are descendants of the root process. A process can use the [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) function to send a CTRL+C or CTRL+BREAK signal to all processes in a console process group. The signal is only received by those processes in the group that are attached to the same console as the process that called **GenerateConsoleCtrlEvent**. - -  - -  - - - - diff --git a/docs/console-readconsole-control.md b/docs/console-readconsole-control.md index fcb1a5f..ebf5e4a 100644 --- a/docs/console-readconsole-control.md +++ b/docs/console-readconsole-control.md @@ -32,7 +32,6 @@ api_type: # CONSOLE\_READCONSOLE\_CONTROL structure - Contains information for a console read operation. Syntax @@ -145,8 +144,6 @@ The state of the control keys. This member can be one or more of the following v -  - Requirements ------------ @@ -173,13 +170,4 @@ Requirements ## See also - [**ReadConsole**](readconsole.md) - -  - -  - - - - diff --git a/docs/console-screen-buffer-info-str.md b/docs/console-screen-buffer-info-str.md index c6485c6..f58d6ab 100644 --- a/docs/console-screen-buffer-info-str.md +++ b/docs/console-screen-buffer-info-str.md @@ -33,7 +33,6 @@ api_type: # CONSOLE\_SCREEN\_BUFFER\_INFO structure - Contains information about a console screen buffer. Syntax diff --git a/docs/console-screen-buffer-infoex.md b/docs/console-screen-buffer-infoex.md index 5ccb5bc..dd14579 100644 --- a/docs/console-screen-buffer-infoex.md +++ b/docs/console-screen-buffer-infoex.md @@ -116,11 +116,3 @@ Requirements [**SetConsoleScreenBufferInfoEx**](setconsolescreenbufferinfoex.md) [**SMALL\_RECT**](small-rect-str.md) - -  - -  - - - - diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index da14336..12e6a7d 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -90,11 +90,3 @@ An application can use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferin The [**GetCurrentConsoleFont**](getcurrentconsolefont.md) function retrieves information about the current console font. The information stored in the [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) structure includes the width and height of each character in the font. The [**GetConsoleFontSize**](getconsolefontsize.md) function retrieves the size of the font used by the specified console screen buffer. - - - - - - - - diff --git a/docs/console-selection-info-str.md b/docs/console-selection-info-str.md index 923e471..21278d4 100644 --- a/docs/console-selection-info-str.md +++ b/docs/console-selection-info-str.md @@ -33,6 +33,7 @@ api_type: # CONSOLE\_SELECTION\_INFO structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Contains information for a console selection. @@ -144,11 +145,3 @@ Requirements [**GetConsoleSelectionInfo**](getconsoleselectioninfo.md) [**SMALL\_RECT**](small-rect-str.md) - -  - -  - - - - diff --git a/docs/console-selection.md b/docs/console-selection.md index 0988218..8b6a04d 100644 --- a/docs/console-selection.md +++ b/docs/console-selection.md @@ -17,13 +17,6 @@ ms.assetid: 2f631e1b-d502-45b7-9c15-34c01e913738 # Console Selection +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] An accessibility application needs information about the user's selection in the console. To retrieve the current console selection, call the [**GetConsoleSelectionInfo**](getconsoleselectioninfo.md) function. The [**CONSOLE\_SELECTION\_INFO**](console-selection-info-str.md) structure contains information about the selection, such as the anchor, coordinates, and status. - -  - -  - - - - diff --git a/docs/console-structures.md b/docs/console-structures.md index a688104..a16bc91 100644 --- a/docs/console-structures.md +++ b/docs/console-structures.md @@ -37,10 +37,3 @@ The following structures are used to access a console. [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) [**SMALL\_RECT**](small-rect-str.md) [**WINDOW\_BUFFER\_SIZE\_RECORD**](window-buffer-size-record-str.md) -  - -  - - - - diff --git a/docs/console-winevents.md b/docs/console-winevents.md index b07b226..ba8f137 100644 --- a/docs/console-winevents.md +++ b/docs/console-winevents.md @@ -46,6 +46,11 @@ api_type: # Console WinEvents +> [!IMPORTANT] +> WinEvents are part of the legacy **[Microsoft Active Accessibility](https://docs.microsoft.com/windows/win32/winauto/microsoft-active-accessibility)** framework. Development using these events is strongly discouraged in favor of the **[Microsoft UI Automation](https://docs.microsoft.com/windows/win32/winauto/entry-uiauto-win32)** framework which provides a more robust and comprehensive suite of interfaces for accessibility and automation applications to interact with the console. + +> [!WARNING] +> Registering for these events is a global activity and will significantly impact performance of all command-line applications running on a system at the same time, including services and background utilities. The following event constants are used in the *event* parameter of the [*WinEventProc*](https://msdn.microsoft.com/library/windows/desktop/dd373885(v=vs.85).aspx) callback function. For more information, see [WinEvents](https://msdn.microsoft.com/library/windows/desktop/dd373889). diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index 02ff3c0..afac040 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -33,6 +33,7 @@ api_type: # CreateConsoleScreenBuffer function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Creates a console screen buffer. @@ -166,7 +167,6 @@ Requirements ## See also - [Console Functions](console-functions.md) [Console Screen Buffers](console-screen-buffers.md) @@ -182,11 +182,3 @@ Requirements [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) - -  - -  - - - - diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index 185e6b7..ba87a77 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -54,4 +54,4 @@ A process cannot change the location of its console window on the screen, but th A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from an inherited console or from a console created by [**AllocConsole**](allocconsole.md). -A process can use the [**AttachConsole**](attachconsole.md) function to attach itself to another existing console session after using [**FreeConsole**](freeconsole.md) to detach from its own session (or if there is otherwise no attached session). \ No newline at end of file +A process can use the [**AttachConsole**](attachconsole.md) function to attach itself to another existing console session after using [**FreeConsole**](freeconsole.md) to detach from its own session (or if there is otherwise no attached session). diff --git a/docs/ctrl-close-signal.md b/docs/ctrl-close-signal.md index 173dd3b..82e6f5d 100644 --- a/docs/ctrl-close-signal.md +++ b/docs/ctrl-close-signal.md @@ -23,11 +23,3 @@ The system generates a CTRL+CLOSE signal when the user closes a console. All pro - Call [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) to terminate the process. - Return **FALSE**. If none of the registered handler functions returns **TRUE**, the default handler terminates the process. - Return **TRUE**. In this case, no other handler functions are called and the process terminates. - -  - -  - - - - diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index fe2f1b9..7768c75 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -33,6 +33,7 @@ api_type: # FillConsoleOutputAttribute function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the character attributes for a specified number of character cells, beginning at the specified coordinates in a screen buffer. @@ -121,7 +122,6 @@ Requirements ## See also - [Console Functions](console-functions.md) [**COORD**](coord-str.md) @@ -133,11 +133,3 @@ Requirements [**SetConsoleTextAttribute**](setconsoletextattribute.md) [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) - -  - -  - - - - diff --git a/docs/fillconsoleoutputcharacter.md b/docs/fillconsoleoutputcharacter.md index 489eecb..b61429f 100644 --- a/docs/fillconsoleoutputcharacter.md +++ b/docs/fillconsoleoutputcharacter.md @@ -41,6 +41,7 @@ api_type: # FillConsoleOutputCharacter function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates. @@ -151,11 +152,3 @@ Requirements [**SetConsoleOutputCP**](setconsoleoutputcp.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - diff --git a/docs/flushconsoleinputbuffer.md b/docs/flushconsoleinputbuffer.md index 92e7a69..8471ca7 100644 --- a/docs/flushconsoleinputbuffer.md +++ b/docs/flushconsoleinputbuffer.md @@ -32,7 +32,6 @@ api_type: # FlushConsoleInputBuffer function - Flushes the console input buffer. All input records currently in the input buffer are discarded. Syntax @@ -109,11 +108,3 @@ Requirements [**ReadConsoleInput**](readconsoleinput.md) [**WriteConsoleInput**](writeconsoleinput.md) - -  - -  - - - - diff --git a/docs/focus-event-record-str.md b/docs/focus-event-record-str.md index 4d0eb75..33a24f0 100644 --- a/docs/focus-event-record-str.md +++ b/docs/focus-event-record-str.md @@ -79,11 +79,3 @@ Requirements [**INPUT\_RECORD**](input-record-str.md) - -  - -  - - - - diff --git a/docs/freeconsole.md b/docs/freeconsole.md index 021569c..2a549b9 100644 --- a/docs/freeconsole.md +++ b/docs/freeconsole.md @@ -110,11 +110,3 @@ Requirements [Console Functions](console-functions.md) [Consoles](consoles.md) - -  - -  - - - - diff --git a/docs/generateconsolectrlevent.md b/docs/generateconsolectrlevent.md index a5cbc65..b5a0d11 100644 --- a/docs/generateconsolectrlevent.md +++ b/docs/generateconsolectrlevent.md @@ -150,11 +150,3 @@ Requirements [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) - -  - -  - - - - diff --git a/docs/getconsolealias.md b/docs/getconsolealias.md index d6b3b9a..3cba579 100644 --- a/docs/getconsolealias.md +++ b/docs/getconsolealias.md @@ -37,6 +37,7 @@ api_type: # GetConsoleAlias function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the text for the specified console alias and executable. @@ -135,11 +136,3 @@ Requirements [**GetConsoleAliases**](getconsolealiases.md) [**GetConsoleAliasExes**](getconsolealiasexes.md) - -  - -  - - - - diff --git a/docs/getconsolealiases.md b/docs/getconsolealiases.md index 0c9aec1..8be5dfc 100644 --- a/docs/getconsolealiases.md +++ b/docs/getconsolealiases.md @@ -37,6 +37,7 @@ api_type: # GetConsoleAliases function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves all defined console aliases for the specified executable. @@ -137,11 +138,3 @@ Requirements [**GetConsoleAliasesLength**](getconsolealiaseslength.md) [**GetConsoleAliasExes**](getconsolealiasexes.md) - -  - -  - - - - diff --git a/docs/getconsolealiaseslength.md b/docs/getconsolealiaseslength.md index 37717b2..857477d 100644 --- a/docs/getconsolealiaseslength.md +++ b/docs/getconsolealiaseslength.md @@ -37,6 +37,7 @@ api_type: # GetConsoleAliasesLength function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the required size for the buffer used by the [**GetConsoleAliases**](getconsolealiases.md) function. @@ -123,11 +124,3 @@ Requirements [**GetConsoleAliases**](getconsolealiases.md) [**GetConsoleAliasExes**](getconsolealiasexes.md) - -  - -  - - - - diff --git a/docs/getconsolealiasexes.md b/docs/getconsolealiasexes.md index 9d092d5..fe56eee 100644 --- a/docs/getconsolealiasexes.md +++ b/docs/getconsolealiasexes.md @@ -37,6 +37,7 @@ api_type: # GetConsoleAliasExes function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the names of all executable files with console aliases defined. @@ -131,11 +132,3 @@ Requirements [**GetConsoleAliasExesLength**](getconsolealiasexeslength.md) [**GetConsoleAliases**](getconsolealiases.md) - -  - -  - - - - diff --git a/docs/getconsolealiasexeslength.md b/docs/getconsolealiasexeslength.md index c3df9ed..45d1b89 100644 --- a/docs/getconsolealiasexeslength.md +++ b/docs/getconsolealiasexeslength.md @@ -37,6 +37,7 @@ api_type: # GetConsoleAliasExesLength function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the required size for the buffer used by the [**GetConsoleAliasExes**](getconsolealiasexes.md) function. @@ -120,11 +121,3 @@ Requirements [**GetConsoleAliases**](getconsolealiases.md) [**GetConsoleAliasExes**](getconsolealiasexes.md) - -  - -  - - - - diff --git a/docs/getconsolecp.md b/docs/getconsolecp.md index a8a7835..69ea158 100644 --- a/docs/getconsolecp.md +++ b/docs/getconsolecp.md @@ -113,11 +113,3 @@ Requirements [**SetConsoleCP**](setconsolecp.md) [**SetConsoleOutputCP**](setconsoleoutputcp.md) - -  - -  - - - - diff --git a/docs/getconsolecursorinfo.md b/docs/getconsolecursorinfo.md index 516cb08..60b40fe 100644 --- a/docs/getconsolecursorinfo.md +++ b/docs/getconsolecursorinfo.md @@ -33,6 +33,7 @@ api_type: # GetConsoleCursorInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves information about the size and visibility of the cursor for the specified console screen buffer. @@ -110,11 +111,3 @@ Requirements [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) [**SetConsoleCursorInfo**](setconsolecursorinfo.md) - -  - -  - - - - diff --git a/docs/getconsoledisplaymode.md b/docs/getconsoledisplaymode.md index 469a215..c1c6d9a 100644 --- a/docs/getconsoledisplaymode.md +++ b/docs/getconsoledisplaymode.md @@ -30,6 +30,7 @@ api_type: # GetConsoleDisplayMode function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the display mode of the current console. @@ -135,11 +136,3 @@ Requirements [Console Modes](console-modes.md) [**SetConsoleDisplayMode**](setconsoledisplaymode.md) - -  - -  - - - - diff --git a/docs/getconsolefontsize.md b/docs/getconsolefontsize.md index 77e278a..67dfbf8 100644 --- a/docs/getconsolefontsize.md +++ b/docs/getconsolefontsize.md @@ -30,6 +30,7 @@ api_type: # GetConsoleFontSize function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the size of the font used by the specified console screen buffer. @@ -109,11 +110,3 @@ Requirements [**COORD**](coord-str.md) [**GetCurrentConsoleFont**](getcurrentconsolefont.md) - -  - -  - - - - diff --git a/docs/getconsolehistoryinfo.md b/docs/getconsolehistoryinfo.md index 45206fa..6a72357 100644 --- a/docs/getconsolehistoryinfo.md +++ b/docs/getconsolehistoryinfo.md @@ -29,6 +29,7 @@ api_type: # GetConsoleHistoryInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the history settings for the calling process's console. @@ -105,11 +106,3 @@ Requirements [**CONSOLE\_HISTORY\_INFO**](console-history-info.md) [**SetConsoleHistoryInfo**](setconsolehistoryinfo.md) - -  - -  - - - - diff --git a/docs/getconsolemode.md b/docs/getconsolemode.md index c436d76..920613e 100644 --- a/docs/getconsolemode.md +++ b/docs/getconsolemode.md @@ -279,11 +279,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/getconsoleoriginaltitle.md b/docs/getconsoleoriginaltitle.md index 8e82ec8..eb4d3cd 100644 --- a/docs/getconsoleoriginaltitle.md +++ b/docs/getconsoleoriginaltitle.md @@ -37,6 +37,7 @@ api_type: # GetConsoleOriginalTitle function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the original title for the current console window. @@ -127,11 +128,3 @@ Requirements [**GetConsoleTitle**](getconsoletitle.md) [**SetConsoleTitle**](setconsoletitle.md) - -  - -  - - - - diff --git a/docs/getconsoleoutputcp.md b/docs/getconsoleoutputcp.md index e84aae6..cdec567 100644 --- a/docs/getconsoleoutputcp.md +++ b/docs/getconsoleoutputcp.md @@ -34,7 +34,6 @@ api_type: # GetConsoleOutputCP function - Retrieves the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. Syntax @@ -103,7 +102,6 @@ Requirements ## See also - [Console Code Pages](console-code-pages.md) [Console Functions](console-functions.md) @@ -113,11 +111,3 @@ Requirements [**SetConsoleCP**](setconsolecp.md) [**SetConsoleOutputCP**](setconsoleoutputcp.md) - -  - -  - - - - diff --git a/docs/getconsoleprocesslist.md b/docs/getconsoleprocesslist.md index 9d11719..fee01b3 100644 --- a/docs/getconsoleprocesslist.md +++ b/docs/getconsoleprocesslist.md @@ -30,7 +30,6 @@ api_type: # GetConsoleProcessList function - Retrieves a list of the processes attached to the current console. Syntax @@ -112,11 +111,3 @@ Requirements [**AttachConsole**](attachconsole.md) [Console Functions](console-functions.md) - -  - -  - - - - diff --git a/docs/getconsolescreenbufferinfo.md b/docs/getconsolescreenbufferinfo.md index b8f8186..cd2f60b 100644 --- a/docs/getconsolescreenbufferinfo.md +++ b/docs/getconsolescreenbufferinfo.md @@ -23,6 +23,7 @@ api_type: # GetConsoleScreenBufferInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves information about the specified console screen buffer. @@ -118,11 +119,3 @@ Requirements [**SetConsoleWindowInfo**](setconsolewindowinfo.md) [Window and Screen Buffer Size](window-and-screen-buffer-size.md) - -  - -  - - - - diff --git a/docs/getconsolescreenbufferinfoex.md b/docs/getconsolescreenbufferinfoex.md index c92dfad..7e1c5e4 100644 --- a/docs/getconsolescreenbufferinfoex.md +++ b/docs/getconsolescreenbufferinfoex.md @@ -32,6 +32,7 @@ api_type: # GetConsoleScreenBufferInfoEx function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves extended information about the specified console screen buffer. @@ -114,11 +115,3 @@ Requirements [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) [**SetConsoleScreenBufferInfoEx**](setconsolescreenbufferinfoex.md) - -  - -  - - - - diff --git a/docs/getconsoleselectioninfo.md b/docs/getconsoleselectioninfo.md index c3d268f..d0dfacb 100644 --- a/docs/getconsoleselectioninfo.md +++ b/docs/getconsoleselectioninfo.md @@ -30,6 +30,7 @@ api_type: # GetConsoleSelectionInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves information about the current console selection. @@ -106,11 +107,3 @@ Requirements [Console Selection](console-selection.md) [**CONSOLE\_SELECTION\_INFO**](console-selection-info-str.md) - -  - -  - - - - diff --git a/docs/getconsoletitle.md b/docs/getconsoletitle.md index 88e113a..90c6e45 100644 --- a/docs/getconsoletitle.md +++ b/docs/getconsoletitle.md @@ -43,6 +43,7 @@ api_type: # GetConsoleTitle function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the title for the current console window. @@ -140,11 +141,3 @@ Requirements [**SetConsoleOutputCP**](setconsoleoutputcp.md) [**SetConsoleTitle**](setconsoletitle.md) - -  - -  - - - - diff --git a/docs/getconsolewindow.md b/docs/getconsolewindow.md index 4d0fe4a..9fb55b7 100644 --- a/docs/getconsolewindow.md +++ b/docs/getconsolewindow.md @@ -38,6 +38,7 @@ api_type: # GetConsoleWindow function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the window handle used by the console associated with the calling process. @@ -105,11 +106,3 @@ Requirements [Console Functions](console-functions.md) - -  - -  - - - - diff --git a/docs/getcurrentconsolefont.md b/docs/getcurrentconsolefont.md index 37320e4..9101110 100644 --- a/docs/getcurrentconsolefont.md +++ b/docs/getcurrentconsolefont.md @@ -30,6 +30,7 @@ api_type: # GetCurrentConsoleFont function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves information about the current console font. @@ -108,7 +109,6 @@ Requirements ## See also - [Console Functions](console-functions.md) [Console Screen Buffers](console-screen-buffers.md) @@ -116,11 +116,3 @@ Requirements [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) [**GetConsoleFontSize**](getconsolefontsize.md) - -  - -  - - - - diff --git a/docs/getcurrentconsolefontex.md b/docs/getcurrentconsolefontex.md index 8dd77a7..9c911f6 100644 --- a/docs/getcurrentconsolefontex.md +++ b/docs/getcurrentconsolefontex.md @@ -29,6 +29,7 @@ api_type: # GetCurrentConsoleFontEx function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves extended information about the current console font. @@ -106,11 +107,3 @@ Requirements [Console Functions](console-functions.md) [**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) - -  - -  - - - - diff --git a/docs/getlargestconsolewindowsize.md b/docs/getlargestconsolewindowsize.md index 8d047cd..db52d9c 100644 --- a/docs/getlargestconsolewindowsize.md +++ b/docs/getlargestconsolewindowsize.md @@ -33,6 +33,7 @@ api_type: # GetLargestConsoleWindowSize function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the size of the largest possible console window, based on the current font and the size of the display. @@ -113,11 +114,3 @@ Requirements [**SetConsoleWindowInfo**](setconsolewindowinfo.md) [Window and Screen Buffer Size](window-and-screen-buffer-size.md) - -  - -  - - - - diff --git a/docs/getnumberofconsoleinputevents.md b/docs/getnumberofconsoleinputevents.md index 44f2e33..5a1fd99 100644 --- a/docs/getnumberofconsoleinputevents.md +++ b/docs/getnumberofconsoleinputevents.md @@ -34,6 +34,7 @@ api_type: # GetNumberOfConsoleInputEvents function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the number of unread input records in the console's input buffer. @@ -126,11 +127,3 @@ Requirements [**ReadConsoleInput**](readconsoleinput.md) [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) - -  - -  - - - - diff --git a/docs/getnumberofconsolemousebuttons.md b/docs/getnumberofconsolemousebuttons.md index a7393e1..e93e0d1 100644 --- a/docs/getnumberofconsolemousebuttons.md +++ b/docs/getnumberofconsolemousebuttons.md @@ -30,6 +30,7 @@ api_type: # GetNumberOfConsoleMouseButtons function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Retrieves the number of buttons on the mouse used by the current console. @@ -110,11 +111,3 @@ Requirements [**INPUT\_RECORD**](input-record-str.md) [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) - -  - -  - - - - diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index 2842d50..e6af22b 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -35,7 +35,6 @@ api_type: # GetStdHandle function - Retrieves a handle to the specified standard device (standard input, standard output, or standard error). Syntax @@ -175,11 +174,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/handlerroutine.md b/docs/handlerroutine.md index 4273aba..cc176bb 100644 --- a/docs/handlerroutine.md +++ b/docs/handlerroutine.md @@ -30,7 +30,6 @@ api_type: # HandlerRoutine callback function - An application-defined function used with the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function. A console process uses this function to handle control signals received by the process. When the signal is received, the system creates a new thread in the process to execute the function. The **PHANDLER\_ROUTINE** type defines a pointer to this callback function. **HandlerRoutine** is a placeholder for the application-defined function name. @@ -183,11 +182,3 @@ Requirements [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) [**SetProcessShutdownParameters**](https://msdn.microsoft.com/library/windows/desktop/ms686227) - -  - -  - - - - diff --git a/docs/high-level-console-i-o.md b/docs/high-level-console-i-o.md index de5b21b..61e86ec 100644 --- a/docs/high-level-console-i-o.md +++ b/docs/high-level-console-i-o.md @@ -34,11 +34,3 @@ For more information, see the following topics: - [Console Modes](console-modes.md) - [High-Level Console Modes](high-level-console-modes.md) - [High-Level Console Input and Output Functions](high-level-console-input-and-output-functions.md) - -  - -  - - - - diff --git a/docs/high-level-console-input-and-output-functions.md b/docs/high-level-console-input-and-output-functions.md index c0bfaa7..6b4b181 100644 --- a/docs/high-level-console-input-and-output-functions.md +++ b/docs/high-level-console-input-and-output-functions.md @@ -31,11 +31,3 @@ A process can use [**WriteFile**](https://msdn.microsoft.com/library/windows/des Characters written by [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md), or echoed by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md), are inserted in a screen buffer at the current cursor position. As each character is written, the cursor position advances to the next character cell; however, the behavior at the end of a row depends on the console screen buffer's wrap at EOL output mode. An application can use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the current cursor position and the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function to set the cursor position. For an example that uses the high-level console I/O functions, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). - -  - -  - - - - diff --git a/docs/high-level-console-modes.md b/docs/high-level-console-modes.md index ec48db0..7432eb5 100644 --- a/docs/high-level-console-modes.md +++ b/docs/high-level-console-modes.md @@ -74,13 +74,3 @@ An application can use the [**GetConsoleMode**](getconsolemode.md) function to d - -  - -  - -  - - - - diff --git a/docs/includes/no-vt-equiv-banner.md b/docs/includes/no-vt-equiv-banner.md new file mode 100644 index 0000000..e397bb9 --- /dev/null +++ b/docs/includes/no-vt-equiv-banner.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/includes/no-vt-equiv-shell-banner.md b/docs/includes/no-vt-equiv-shell-banner.md new file mode 100644 index 0000000..685dc73 --- /dev/null +++ b/docs/includes/no-vt-equiv-shell-banner.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/input-and-output-methods.md b/docs/input-and-output-methods.md index d96992e..d599a09 100644 --- a/docs/input-and-output-methods.md +++ b/docs/input-and-output-methods.md @@ -36,11 +36,3 @@ The following topics describe the console modes and the high-level and low-level - [Low-Level Console Modes](low-level-console-modes.md) - [Low-Level Console Input Functions](low-level-console-input-functions.md) - [Low-Level Console Output Functions](low-level-console-output-functions.md) - -  - -  - - - - diff --git a/docs/input-record-str.md b/docs/input-record-str.md index 399e650..bcc4dac 100644 --- a/docs/input-record-str.md +++ b/docs/input-record-str.md @@ -161,11 +161,3 @@ Requirements [**ReadConsoleInput**](readconsoleinput.md) [**WriteConsoleInput**](writeconsoleinput.md) - -  - -  - - - - diff --git a/docs/key-event-record-str.md b/docs/key-event-record-str.md index 678c3af..4109dc5 100644 --- a/docs/key-event-record-str.md +++ b/docs/key-event-record-str.md @@ -211,11 +211,3 @@ Requirements [**WriteConsoleInput**](writeconsoleinput.md) [**INPUT\_RECORD**](input-record-str.md) - -  - -  - - - - diff --git a/docs/legacymode.md b/docs/legacymode.md index 893bdc8..9904843 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -39,4 +39,4 @@ The legacy Console Host embedded the suggestion portion of the IME inside the ho The major known difference between legacy and current is the implementation of UTF-8. The legacy host has extremely rudimentary and often incorrect support of UTF-8 with [code page 65001](https://docs.microsoft.com/windows/win32/intl/code-pages). The current console host contains incremental improvements release-over-release of Windows 10 to improve this support. Applications that are attempting to rely on predicting "known incorrect" interpretations of UTF-8 from the legacy console will find themselves receiving different answers as support is improved. -Other differences experienced with APIs should be reported to [Microsoft/Terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. \ No newline at end of file +Other differences experienced with APIs should be reported to [Microsoft/Terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. diff --git a/docs/low-level-console-i-o.md b/docs/low-level-console-i-o.md index 95a0a9f..dfbd698 100644 --- a/docs/low-level-console-i-o.md +++ b/docs/low-level-console-i-o.md @@ -17,6 +17,7 @@ ms.assetid: c874aff4-6129-4dbc-8949-24d46382d81c # Low-Level Console I/O +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The low-level console I/O functions expand an application's control over console I/O by enabling direct access to a console's input and screen buffers. These functions enable an application to perform the following tasks: @@ -37,11 +38,3 @@ For more information, see the following topics: - [Low-Level Console Modes](low-level-console-modes.md) - [Low-Level Console Input Functions](low-level-console-input-functions.md) - [Low-Level Console Output Functions](low-level-console-output-functions.md) - -  - -  - - - - diff --git a/docs/low-level-console-input-functions.md b/docs/low-level-console-input-functions.md index a182c56..ffeb16e 100644 --- a/docs/low-level-console-input-functions.md +++ b/docs/low-level-console-input-functions.md @@ -17,6 +17,7 @@ ms.assetid: 41488614-ca7c-4207-b706-f7776423c7ba # Low-Level Console Input Functions +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] A low-level console input functions buffer contains input records that can include information about keyboard, mouse, buffer-resizing, focus, and menu events. The low-level functions provide direct access to the input buffer, unlike the high-level functions that filter and process the input buffer's data, discarding all but keyboard input. diff --git a/docs/low-level-console-modes.md b/docs/low-level-console-modes.md index 86c2e5c..53824d0 100644 --- a/docs/low-level-console-modes.md +++ b/docs/low-level-console-modes.md @@ -17,6 +17,7 @@ ms.assetid: 41bfdc51-27cb-4d5e-898c-507ffc8789b9 # Low-Level Console Modes +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The types of input events reported in a console's input buffer depend on the console's mouse and window input modes. The console's processed input mode determines how the system handles the CTRL+C key combination. To set or retrieve the state of a console's input modes, an application can specify a console input buffer handle in a call to the [**SetConsoleMode**](setconsolemode.md) or [**GetConsoleMode**](getconsolemode.md) function. The following modes are used with console input handles. @@ -30,11 +31,3 @@ The types of input events reported in a console's input buffer depend on the con The output modes of a screen buffer do not affect the behavior of the low-level output functions. - - - - - - - - diff --git a/docs/low-level-console-output-functions.md b/docs/low-level-console-output-functions.md index 341a2c9..da320f8 100644 --- a/docs/low-level-console-output-functions.md +++ b/docs/low-level-console-output-functions.md @@ -17,20 +17,21 @@ ms.assetid: 94185428-e8c7-4926-93ec-867b8c97b4ca # Low-Level Console Output Functions +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The low-level console output functions provide direct access to the character cells of a screen buffer. One set of functions reads from or writes to consecutive cells beginning at any location in the console screen buffer. Another set of functions reads from or writes to rectangular blocks of cells. The following functions read from or write to a specified number of consecutive character cells in a screen buffer, beginning with a specified cell. -| Function | Description | +| Function | Description | |--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| -| [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a string of Unicode or ANSI characters from a screen buffer. | -| [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Writes a string of Unicode or ANSI characters to a screen buffer. | -| [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a string of text and background color attributes from a screen buffer. | -| [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) | Writes a string of text and background color attributes to a screen buffer. | -| [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a single Unicode or ANSI character to a specified number of consecutive cells in a screen buffer. | -| [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Writes a text and background color attribute combination to a specified number of consecutive cells in a screen buffer. | +| [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a string of Unicode or ANSI characters from a screen buffer. | +| [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Writes a string of Unicode or ANSI characters to a screen buffer. | +| [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a string of text and background color attributes from a screen buffer. | +| [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) | Writes a string of text and background color attributes to a screen buffer. | +| [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a single Unicode or ANSI character to a specified number of consecutive cells in a screen buffer. | +| [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Writes a text and background color attribute combination to a specified number of consecutive cells in a screen buffer. | For all of these functions, when the last cell of a row is encountered, reading or writing wraps around to the first cell of the next row. When the end of the last row of the console screen buffer is encountered, the write functions discard all unwritten characters or attributes, and the read functions report the number of characters or attributes actually written. @@ -38,10 +39,10 @@ For all of these functions, when the last cell of a row is encountered, reading The following functions read from or write to rectangular blocks of character cells at a specified location in a screen buffer. -| Function | Description | +| Function | Description | |--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| -| [**ReadConsoleOutput**](readconsoleoutput.md) | Copies character and color data from a specified block of screen buffer cells into a given block in a destination buffer. | -| [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color data to a specified block of screen buffer cells from a given block in a source buffer. | +| [**ReadConsoleOutput**](readconsoleoutput.md) | Copies character and color data from a specified block of screen buffer cells into a given block in a destination buffer. | +| [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color data to a specified block of screen buffer cells from a given block in a source buffer. | @@ -52,11 +53,3 @@ These functions automatically clip the specified screen buffer rectangle to fit The illustration shows a [**ReadConsoleOutput**](readconsoleoutput.md) operation where clipping occurs when the block is read from the console screen buffer, and again when the block is copied into the destination buffer. The function reports the actual screen buffer rectangle that it copied from. ![screen buffer window with destination buffer](images/cscon-03.png) - - - - - - - - diff --git a/docs/menu-event-record-str.md b/docs/menu-event-record-str.md index f190e76..b59cf9f 100644 --- a/docs/menu-event-record-str.md +++ b/docs/menu-event-record-str.md @@ -33,6 +33,7 @@ api_type: # MENU\_EVENT\_RECORD structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Describes a menu event in a console [**INPUT\_RECORD**](input-record-str.md) structure. These events are used internally and should be ignored. @@ -79,11 +80,3 @@ Requirements [**INPUT\_RECORD**](input-record-str.md) - -  - -  - - - - diff --git a/docs/mouse-event-record-str.md b/docs/mouse-event-record-str.md index 9616364..2fc5b71 100644 --- a/docs/mouse-event-record-str.md +++ b/docs/mouse-event-record-str.md @@ -33,6 +33,7 @@ api_type: # MOUSE\_EVENT\_RECORD structure +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Describes a mouse input event in a console [**INPUT\_RECORD**](input-record-str.md) structure. @@ -298,11 +299,3 @@ Requirements [**ReadConsoleInput**](readconsoleinput.md) [**WriteConsoleInput**](writeconsoleinput.md) - -  - -  - - - - diff --git a/docs/peekconsoleinput.md b/docs/peekconsoleinput.md index 07416af..6a3e654 100644 --- a/docs/peekconsoleinput.md +++ b/docs/peekconsoleinput.md @@ -43,6 +43,7 @@ api_type: # PeekConsoleInput function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Reads data from the specified console input buffer without removing it from the buffer. @@ -145,11 +146,3 @@ Requirements [**WriteConsoleInput**](writeconsoleinput.md) [**INPUT\_RECORD**](input-record-str.md) - -  - -  - - - - diff --git a/docs/readconsole.md b/docs/readconsole.md index f4a7bb3..8b7490a 100644 --- a/docs/readconsole.md +++ b/docs/readconsole.md @@ -42,7 +42,6 @@ api_type: # ReadConsole function - Reads character input from the console input buffer and removes it from the buffer. Syntax @@ -166,11 +165,3 @@ Requirements [**SetConsoleOutputCP**](setconsoleoutputcp.md) [**WriteConsole**](writeconsole.md) - -  - -  - - - - diff --git a/docs/readconsoleinput.md b/docs/readconsoleinput.md index 2ea4414..eb9c1d5 100644 --- a/docs/readconsoleinput.md +++ b/docs/readconsoleinput.md @@ -163,11 +163,3 @@ Requirements [**SetConsoleOutputCP**](setconsoleoutputcp.md) [**WriteConsoleInput**](writeconsoleinput.md) - -  - -  - - - - diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index 0f85d40..8cf2b71 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -98,6 +98,8 @@ The **ReadConsoleOutput** function has no effect on the console screen buffer's This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [no-vt-equiv-banner](./includes/no-vt-equiv-banner.md)] + Examples -------- diff --git a/docs/readconsoleoutputattribute.md b/docs/readconsoleoutputattribute.md index bce0afd..b6e9123 100644 --- a/docs/readconsoleoutputattribute.md +++ b/docs/readconsoleoutputattribute.md @@ -33,6 +33,7 @@ api_type: # ReadConsoleOutputAttribute function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Copies a specified number of character attributes from consecutive cells of a console screen buffer, beginning at a specified location. @@ -137,11 +138,3 @@ Requirements [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - diff --git a/docs/readconsoleoutputcharacter.md b/docs/readconsoleoutputcharacter.md index 4d77e02..09b47a3 100644 --- a/docs/readconsoleoutputcharacter.md +++ b/docs/readconsoleoutputcharacter.md @@ -41,6 +41,7 @@ api_type: # ReadConsoleOutputCharacter function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Copies a number of characters from consecutive cells of a console screen buffer, beginning at a specified location. @@ -155,11 +156,3 @@ Requirements [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - diff --git a/docs/reading-and-writing-blocks-of-characters-and-attributes.md b/docs/reading-and-writing-blocks-of-characters-and-attributes.md index a526c02..4a9af0f 100644 --- a/docs/reading-and-writing-blocks-of-characters-and-attributes.md +++ b/docs/reading-and-writing-blocks-of-characters-and-attributes.md @@ -17,6 +17,7 @@ ms.assetid: eaa57723-f003-4e90-8156-be8c3b42b912 # Reading and Writing Blocks of Characters and Attributes +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The [**ReadConsoleOutput**](readconsoleoutput.md) function copies a rectangular block of character and color attribute data from a console screen buffer into a destination buffer. The function treats the destination buffer as a two-dimensional array of [**CHAR\_INFO**](char-info-str.md) structures. Similarly, the [**WriteConsoleOutput**](writeconsoleoutput.md) function copies a rectangular block of character and color attribute data from a source buffer to a console screen buffer. For more information about reading from or writing to rectangular blocks of screen buffer cells, see [Input and Output Methods](input-and-output-methods.md). @@ -128,11 +129,3 @@ int main(void) return 0; } ``` - -  - -  - - - - diff --git a/docs/reading-input-buffer-events.md b/docs/reading-input-buffer-events.md index 23abc0b..fd7fc0d 100644 --- a/docs/reading-input-buffer-events.md +++ b/docs/reading-input-buffer-events.md @@ -173,11 +173,3 @@ VOID ResizeEventProc(WINDOW_BUFFER_SIZE_RECORD wbsr) printf("Console screen buffer is %d columns by %d rows.\n", wbsr.dwSize.X, wbsr.dwSize.Y); } ``` - -  - -  - - - - diff --git a/docs/registering-a-control-handler-function.md b/docs/registering-a-control-handler-function.md index d84be49..807a7ff 100644 --- a/docs/registering-a-control-handler-function.md +++ b/docs/registering-a-control-handler-function.md @@ -91,11 +91,3 @@ int main(void) return 0; } ``` - -  - -  - - - - diff --git a/docs/resizepseudoconsole.md b/docs/resizepseudoconsole.md index 4d98a13..cd04d2b 100644 --- a/docs/resizepseudoconsole.md +++ b/docs/resizepseudoconsole.md @@ -23,7 +23,6 @@ api_type: # ResizePseudoConsole function - Resizes the internal buffers for a pseudoconsole to the given size. Syntax diff --git a/docs/scrollconsolescreenbuffer.md b/docs/scrollconsolescreenbuffer.md index 77f9d00..d232c1e 100644 --- a/docs/scrollconsolescreenbuffer.md +++ b/docs/scrollconsolescreenbuffer.md @@ -37,6 +37,7 @@ api_type: # ScrollConsoleScreenBuffer function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Moves a block of data in a screen buffer. The effects of the move can be limited by specifying a clipping rectangle, so the contents of the console screen buffer outside the clipping rectangle are unchanged. @@ -156,11 +157,3 @@ Requirements [**SetConsoleWindowInfo**](setconsolewindowinfo.md) [**SMALL\_RECT**](small-rect-str.md) - -  - -  - - - - diff --git a/docs/scrolling-a-screen-buffer-s-contents.md b/docs/scrolling-a-screen-buffer-s-contents.md index e398e52..2c86e39 100644 --- a/docs/scrolling-a-screen-buffer-s-contents.md +++ b/docs/scrolling-a-screen-buffer-s-contents.md @@ -17,6 +17,7 @@ ms.assetid: 288c6a0f-fbaa-4eee-895e-a25884b7b70a # Scrolling a Screen Buffer's Contents +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) function moves a block of character cells from one part of a screen buffer to another part of the same screen buffer. The function specifies the upper left and lower right cells of the source rectangle to be moved and the destination coordinates of the new location for the upper left cell. The character and color data in the source cells is moved to the new location, and any cells left empty by the move are filled in with a specified character and color. If a clipping rectangle is specified, the cells outside of it are left unchanged. @@ -103,11 +104,3 @@ return 0; [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md) [Scrolling the Screen Buffer](scrolling-the-screen-buffer.md) - -  - -  - - - - diff --git a/docs/scrolling-a-screen-buffer-s-window.md b/docs/scrolling-a-screen-buffer-s-window.md index b9277bc..de86b50 100644 --- a/docs/scrolling-a-screen-buffer-s-window.md +++ b/docs/scrolling-a-screen-buffer-s-window.md @@ -17,6 +17,7 @@ ms.assetid: bc300349-9bfa-4417-92ad-57a05a658ce5 # Scrolling a Screen Buffer's Window +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The [**SetConsoleWindowInfo**](setconsolewindowinfo.md) function can be used to scroll the contents of a screen buffer in the console window. This function can also change the window size. The function can either specify the new upper left and lower right corners of the console screen buffer's window as absolute screen buffer coordinates or specify the changes from the current window coordinates. The function fails if the specified window coordinates are outside the boundaries of the console screen buffer. @@ -137,11 +138,3 @@ int main( void ) [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md) [Scrolling the Screen Buffer](scrolling-the-screen-buffer.md) - -  - -  - - - - diff --git a/docs/scrolling-the-screen-buffer.md b/docs/scrolling-the-screen-buffer.md index 3be7dd2..c08382a 100644 --- a/docs/scrolling-the-screen-buffer.md +++ b/docs/scrolling-the-screen-buffer.md @@ -17,6 +17,7 @@ ms.assetid: c8404e78-9807-4bed-bc12-25377fa96151 # Scrolling the Screen Buffer +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The console window displays a portion of the active screen buffer. Each screen buffer maintains its own current window rectangle that specifies the coordinates of the upper left and lower right character cells to be displayed in the console window. To determine the current window rectangle of a screen buffer, use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md). When a screen buffer is created, the upper left corner of its window is at the upper left corner of the console screen buffer at (0,0). @@ -42,11 +43,3 @@ The illustration shows a [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuff ![screen buffer window](images/cscon-02.png) The effects of [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) can be limited by specifying an optional clipping rectangle so that the contents of the console screen buffer outside the clipping rectangle are unchanged. The effect of clipping is to create a subwindow (the clipping rectangle) whose contents are scrolled without affecting the rest of the console screen buffer. For an example that uses **ScrollConsoleScreenBuffer**, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). - -  - -  - - - - diff --git a/docs/setconsoleactivescreenbuffer.md b/docs/setconsoleactivescreenbuffer.md index fff4932..9306d92 100644 --- a/docs/setconsoleactivescreenbuffer.md +++ b/docs/setconsoleactivescreenbuffer.md @@ -33,6 +33,7 @@ api_type: # SetConsoleActiveScreenBuffer function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the specified screen buffer to be the currently displayed console screen buffer. @@ -114,11 +115,3 @@ Requirements [Console Screen Buffers](console-screen-buffers.md) [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) - -  - -  - - - - diff --git a/docs/setconsolecp.md b/docs/setconsolecp.md index 5021927..ed89fbe 100644 --- a/docs/setconsolecp.md +++ b/docs/setconsolecp.md @@ -123,11 +123,3 @@ Requirements [**GetConsoleOutputCP**](getconsoleoutputcp.md) [**SetConsoleOutputCP**](setconsoleoutputcp.md) - -  - -  - - - - diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 4989e24..7bf37c4 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -34,7 +34,6 @@ api_type: # SetConsoleCtrlHandler function - Adds or removes an application-defined [**HandlerRoutine**](handlerroutine.md) function from the list of handler functions for the calling process. If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals. @@ -151,11 +150,3 @@ Requirements [**HandlerRoutine**](handlerroutine.md) [**SetConsoleMode**](setconsolemode.md) - -  - -  - - - - diff --git a/docs/setconsolecursorinfo.md b/docs/setconsolecursorinfo.md index 4245f8f..dff821b 100644 --- a/docs/setconsolecursorinfo.md +++ b/docs/setconsolecursorinfo.md @@ -33,6 +33,7 @@ api_type: # SetConsoleCursorInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the size and visibility of the cursor for the specified console screen buffer. @@ -117,11 +118,3 @@ Requirements [**GetConsoleCursorInfo**](getconsolecursorinfo.md) [**SetConsoleCursorPosition**](setconsolecursorposition.md) - -  - -  - - - - diff --git a/docs/setconsolecursorposition.md b/docs/setconsolecursorposition.md index 821740d..9dc80f8 100644 --- a/docs/setconsolecursorposition.md +++ b/docs/setconsolecursorposition.md @@ -33,6 +33,7 @@ api_type: # SetConsoleCursorPosition function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the cursor position in the specified console screen buffer. @@ -132,11 +133,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/setconsoledisplaymode.md b/docs/setconsoledisplaymode.md index f655fc1..be4564f 100644 --- a/docs/setconsoledisplaymode.md +++ b/docs/setconsoledisplaymode.md @@ -29,6 +29,7 @@ api_type: # SetConsoleDisplayMode function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the display mode of the specified console screen buffer. @@ -137,11 +138,3 @@ Requirements [Console Modes](console-modes.md) [**GetConsoleDisplayMode**](getconsoledisplaymode.md) - -  - -  - - - - diff --git a/docs/setconsolehistoryinfo.md b/docs/setconsolehistoryinfo.md index 5425737..7c89f40 100644 --- a/docs/setconsolehistoryinfo.md +++ b/docs/setconsolehistoryinfo.md @@ -29,6 +29,7 @@ api_type: # SetConsoleHistoryInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the history settings for the calling process's console. @@ -105,11 +106,3 @@ Requirements [**CONSOLE\_HISTORY\_INFO**](console-history-info.md) [**GetConsoleHistoryInfo**](getconsolehistoryinfo.md) - -  - -  - - - - diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index 93e7517..f944f33 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -34,7 +34,6 @@ api_type: # SetConsoleMode function - Sets the input mode of a console's input buffer or the output mode of a console screen buffer. Syntax @@ -288,11 +287,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/setconsoleoutputcp.md b/docs/setconsoleoutputcp.md index ffc0863..a54c69c 100644 --- a/docs/setconsoleoutputcp.md +++ b/docs/setconsoleoutputcp.md @@ -33,7 +33,6 @@ api_type: # SetConsoleOutputCP function - Sets the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. Syntax @@ -124,11 +123,3 @@ Requirements [**GetConsoleOutputCP**](getconsoleoutputcp.md) [**SetConsoleCP**](setconsolecp.md) - -  - -  - - - - diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index 477ab25..fb25c80 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -32,6 +32,7 @@ api_type: # SetConsoleScreenBufferInfoEx function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets extended information about the specified console screen buffer. @@ -107,11 +108,3 @@ Requirements [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) [**GetConsoleScreenBufferInfoEx**](getconsolescreenbufferinfoex.md) - -  - -  - - - - diff --git a/docs/setconsolescreenbuffersize.md b/docs/setconsolescreenbuffersize.md index 1a69d79..d273c41 100644 --- a/docs/setconsolescreenbuffersize.md +++ b/docs/setconsolescreenbuffersize.md @@ -33,6 +33,7 @@ api_type: # SetConsoleScreenBufferSize function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Changes the size of the specified console screen buffer. @@ -112,11 +113,3 @@ Requirements [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) [**SetConsoleWindowInfo**](setconsolewindowinfo.md) - -  - -  - - - - diff --git a/docs/setconsoletextattribute.md b/docs/setconsoletextattribute.md index 75279da..55d4964 100644 --- a/docs/setconsoletextattribute.md +++ b/docs/setconsoletextattribute.md @@ -33,6 +33,7 @@ api_type: # SetConsoleTextAttribute function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the attributes of characters written to the console screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md) function, or echoed by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) function. This function affects text written after the function call. @@ -126,11 +127,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/setconsoletitle.md b/docs/setconsoletitle.md index 866b2b4..16d0546 100644 --- a/docs/setconsoletitle.md +++ b/docs/setconsoletitle.md @@ -49,6 +49,7 @@ api_type: # SetConsoleTitle function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the title for the current console window. @@ -176,11 +177,3 @@ Requirements [**SetConsoleCP**](setconsolecp.md) [**SetConsoleOutputCP**](setconsoleoutputcp.md) - -  - -  - - - - diff --git a/docs/setconsolewindowinfo.md b/docs/setconsolewindowinfo.md index 550f0fb..8b4a6c0 100644 --- a/docs/setconsolewindowinfo.md +++ b/docs/setconsolewindowinfo.md @@ -33,6 +33,7 @@ api_type: # SetConsoleWindowInfo function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets the current size and position of a console screen buffer's window. @@ -134,11 +135,3 @@ Requirements [Scrolling the Screen Buffer](scrolling-the-screen-buffer.md) [**SMALL\_RECT**](small-rect-str.md) - -  - -  - - - - diff --git a/docs/setcurrentconsolefontex.md b/docs/setcurrentconsolefontex.md index 0e5ed2e..d442842 100644 --- a/docs/setcurrentconsolefontex.md +++ b/docs/setcurrentconsolefontex.md @@ -29,6 +29,7 @@ api_type: # SetCurrentConsoleFontEx function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Sets extended information about the current console font. @@ -111,11 +112,3 @@ Requirements [Console Functions](console-functions.md) [**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) - -  - -  - - - - diff --git a/docs/setstdhandle.md b/docs/setstdhandle.md index dccabf0..5f37c92 100644 --- a/docs/setstdhandle.md +++ b/docs/setstdhandle.md @@ -35,7 +35,6 @@ api_type: # SetStdHandle function - Sets the handle for the specified standard device (standard input, standard output, or standard error). Syntax @@ -157,11 +156,3 @@ Requirements [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) [**GetStdHandle**](getstdhandle.md) - -  - -  - - - - diff --git a/docs/small-rect-str.md b/docs/small-rect-str.md index f7f8d09..efeb443 100644 --- a/docs/small-rect-str.md +++ b/docs/small-rect-str.md @@ -30,7 +30,6 @@ api_type: # SMALL\_RECT structure - Defines the coordinates of the upper left and lower right corners of a rectangle. Syntax @@ -100,11 +99,3 @@ Requirements [**RECT**](https://msdn.microsoft.com/library/windows/desktop/dd162897) [**RECTL**](https://msdn.microsoft.com/library/windows/desktop/dd162907) - -  - -  - - - - diff --git a/docs/using-the-console.md b/docs/using-the-console.md index 8439ca9..c680c97 100644 --- a/docs/using-the-console.md +++ b/docs/using-the-console.md @@ -17,7 +17,6 @@ ms.assetid: 31bbf2b1-2519-4589-8059-7757cfda105a # Using the Console - The following examples demonstrate how to use the console functions: - [Using the high-level input and output functions](using-the-high-level-input-and-output-functions.md) @@ -27,11 +26,3 @@ The following examples demonstrate how to use the console functions: - [Scrolling a screen buffer's window](scrolling-a-screen-buffer-s-window.md) - [Scrolling a screen buffer's contents](scrolling-a-screen-buffer-s-contents.md) - [Registering a control handler function](registering-a-control-handler-function.md) - -  - -  - - - - diff --git a/docs/using-the-high-level-input-and-output-functions.md b/docs/using-the-high-level-input-and-output-functions.md index 87f85e8..1ca4272 100644 --- a/docs/using-the-high-level-input-and-output-functions.md +++ b/docs/using-the-high-level-input-and-output-functions.md @@ -17,6 +17,7 @@ ms.assetid: 0226cd94-86d0-452b-80e6-e0fed8af0a62 # Using the High-Level Input and Output Functions +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] The following example uses the high-level console I/O functions for console I/O. For more information about the high-level console I/O functions, see [High-Level Console I/O](high-level-console-i-o.md). @@ -236,11 +237,3 @@ void ScrollScreenBuffer(HANDLE h, INT x) &chiFill); // fill character and color } ``` - -  - -  - - - - diff --git a/docs/window-and-screen-buffer-size.md b/docs/window-and-screen-buffer-size.md index fc0b504..014dd54 100644 --- a/docs/window-and-screen-buffer-size.md +++ b/docs/window-and-screen-buffer-size.md @@ -35,11 +35,3 @@ To change a screen buffer's size, use the [**SetConsoleScreenBufferSize**](setco To change the size or location of a screen buffer's window, use the [**SetConsoleWindowInfo**](setconsolewindowinfo.md) function. This function fails if the specified window-corner coordinates exceed the limits of the console screen buffer or the screen. Changing the window size of the active screen buffer changes the size of the console window displayed on the screen. A process can change its console's input mode to enable window input so that the process is able to receive input when the user changes the console screen buffer size. If an application enables window input, it can use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) to retrieve window and screen buffer size at startup. This information can then be used to determine the way data is displayed in the window. If the user changes the console screen buffer size, the application can respond by changing the way data is displayed. For example, an application can adjust the way text wraps at the end of the line if the number of characters per row changes. If an application does not enable window input, it must either use the inherited window and screen buffer sizes, or set them to the desired size during startup and restore the inherited sizes at exit. For additional information about window input mode, see [Low-Level Console Modes](low-level-console-modes.md). - -  - -  - - - - diff --git a/docs/window-buffer-size-record-str.md b/docs/window-buffer-size-record-str.md index b22e97a..4175c5c 100644 --- a/docs/window-buffer-size-record-str.md +++ b/docs/window-buffer-size-record-str.md @@ -33,7 +33,6 @@ api_type: # WINDOW\_BUFFER\_SIZE\_RECORD structure - Describes a change in the size of the console screen buffer. Syntax @@ -93,11 +92,3 @@ Requirements [**INPUT\_RECORD**](input-record-str.md) [**ReadConsoleInput**](readconsoleinput.md) - -  - -  - - - - diff --git a/docs/writeconsole.md b/docs/writeconsole.md index f2ed443..00f2efe 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -42,7 +42,6 @@ api_type: # WriteConsole function - Writes a character string to a console screen buffer beginning at the current cursor location. Syntax @@ -172,11 +171,3 @@ Requirements [**SetCursorPos**](https://msdn.microsoft.com/library/windows/desktop/ms648394(v=vs.85).aspx) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/writeconsoleinput.md b/docs/writeconsoleinput.md index 709c7c2..d2c4ba0 100644 --- a/docs/writeconsoleinput.md +++ b/docs/writeconsoleinput.md @@ -41,6 +41,7 @@ api_type: # WriteConsoleInput function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] Writes data directly to the console input buffer. @@ -149,11 +150,3 @@ Requirements [**SetConsoleOutputCP**](setconsoleoutputcp.md) [**VkKeyScan**](https://msdn.microsoft.com/library/windows/desktop/ms646329) - -  - -  - - - - diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index 92219b4..6db7022 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -41,7 +41,6 @@ api_type: # WriteConsoleOutput function - Writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer. Syntax @@ -174,11 +173,3 @@ Requirements [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - From 245b7f0fa73c592cab8b44eb2718c32e43c5f92c Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 16:24:24 -0700 Subject: [PATCH 11/53] drop md from links as they didn't resolve on docs build. --- docs/includes/no-vt-equiv-banner.md | 2 +- docs/includes/no-vt-equiv-shell-banner.md | 2 +- docs/includes/not-recommended-banner.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/includes/no-vt-equiv-banner.md b/docs/includes/no-vt-equiv-banner.md index e397bb9..e23659d 100644 --- a/docs/includes/no-vt-equiv-banner.md +++ b/docs/includes/no-vt-equiv-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/includes/no-vt-equiv-shell-banner.md b/docs/includes/no-vt-equiv-shell-banner.md index 685dc73..bc69216 100644 --- a/docs/includes/no-vt-equiv-shell-banner.md +++ b/docs/includes/no-vt-equiv-shell-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/includes/not-recommended-banner.md b/docs/includes/not-recommended-banner.md index fb76346..7c74372 100644 --- a/docs/includes/not-recommended-banner.md +++ b/docs/includes/not-recommended-banner.md @@ -1,2 +1,2 @@ > [!IMPORTANT] -> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap.md)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt.md)** document. \ No newline at end of file +> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt)** document. \ No newline at end of file From f22055d6d9499ba729e2a709f2148968af89391b Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Fri, 25 Sep 2020 16:25:13 -0700 Subject: [PATCH 12/53] Fix capitalization issue in TOC. --- docs/TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TOC.md b/docs/TOC.md index 221ed18..754b13a 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -56,7 +56,7 @@ ### [GenerateConsoleCtrlEvent](generateconsolectrlevent.md) ### [GetConsoleAlias](getconsolealias.md) ### [GetConsoleAliases](getconsolealiases.md) -### [GetConsoleAliaseslength](getconsolealiaseslength.md) +### [GetConsoleAliasesLength](getconsolealiaseslength.md) ### [GetConsoleAliasExes](getconsolealiasexes.md) ### [GetConsoleAliasExesLength](getconsolealiasexeslength.md) ### [GetConsoleCP](getconsolecp.md) From 8f2315236cd7e681a01065ce9c622883ca799812 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 30 Sep 2020 14:03:25 -0700 Subject: [PATCH 13/53] bit more cleanup --- .openpublishing.publish.config.json | 2 +- docs/clearing-the-screen.md | 2 +- docs/console-code-pages.md | 2 +- docs/console-handles.md | 8 -------- docs/console-history-info.md | 8 -------- docs/console-reference.md | 9 --------- docs/low-level-console-input-functions.md | 12 ++---------- 7 files changed, 5 insertions(+), 38 deletions(-) diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index b5589f9..65e5d27 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -22,7 +22,7 @@ } ], "notification_subscribers": [ - "richturn@microsoft.com", + "cinnamon@microsoft.com", "duhowett@microsoft.com", "miniksa@microsoft.com" ], diff --git a/docs/clearing-the-screen.md b/docs/clearing-the-screen.md index 41c3112..f3ccbfa 100644 --- a/docs/clearing-the-screen.md +++ b/docs/clearing-the-screen.md @@ -169,7 +169,7 @@ int main( void ) ## Example 4 -The fourth method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter to clear the screen. +The fourth method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter `cmd.exe` to clear the screen. ```C #include diff --git a/docs/console-code-pages.md b/docs/console-code-pages.md index 6346b5f..381e11a 100644 --- a/docs/console-code-pages.md +++ b/docs/console-code-pages.md @@ -28,4 +28,4 @@ The identifiers of the code pages available on the local computer are stored in For information about using the registry functions to determine the available code pages, see [**Registry**](https://msdn.microsoft.com/library/windows/desktop/ms724871). > [!TIP] -> It is recommended for all new and updated command-line applications to avoid code pages and use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. UTF-16 format text can be sent to the *W* family of console APIs. UTF-8 format text can be sent to the *A* family of console APIs after ensuring the code page is first set to **[65001 (CP_UTF8)](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)** with the [**SetConsoleCP**](setconsolecp.md) and [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. +> It is recommended for all new and updated command-line applications to avoid code pages and use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. UTF-16 formatted text can be sent to the *W* family of console APIs. UTF-8 formatted text can be sent to the *A* family of console APIs after ensuring the code page is first set to **[65001 (CP_UTF8)](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)** with the [**SetConsoleCP**](setconsolecp.md) and [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. diff --git a/docs/console-handles.md b/docs/console-handles.md index f398e78..35cde3f 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -34,11 +34,3 @@ A process can use the [**DuplicateHandle**](https://msdn.microsoft.com/library/w Access to a console must be shared during [creation](creation-of-a-console.md) of the other process or may be requested by the other process through the [**AttachConsole**](attachconsole.md) mechanism. To close a console handle, a process can use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. - -  - -  - - - - diff --git a/docs/console-history-info.md b/docs/console-history-info.md index e97f038..ad41df8 100644 --- a/docs/console-history-info.md +++ b/docs/console-history-info.md @@ -116,11 +116,3 @@ Requirements [**GetConsoleHistoryInfo**](getconsolehistoryinfo.md) [**SetConsoleHistoryInfo**](setconsolehistoryinfo.md) - -  - -  - - - - diff --git a/docs/console-reference.md b/docs/console-reference.md index babd7ba..a616967 100644 --- a/docs/console-reference.md +++ b/docs/console-reference.md @@ -17,17 +17,8 @@ ms.assetid: be1aa828-04dc-4d9d-ae88-92842dcafa85 # Console Reference - The following sections describe the Console API: - [Console Functions](console-functions.md) - [Console Structures](console-structures.md) - [Console WinEvents](console-winevents.md) - -  - -  - - - - diff --git a/docs/low-level-console-input-functions.md b/docs/low-level-console-input-functions.md index ffeb16e..fb7795d 100644 --- a/docs/low-level-console-input-functions.md +++ b/docs/low-level-console-input-functions.md @@ -34,8 +34,8 @@ The [**ReadConsoleInput**](readconsoleinput.md), [**PeekConsoleInput**](peekcons Following are descriptions of the low-level console input functions. -| Function | Description | -|------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Function | Description | +|---|---| | [**ReadConsoleInput**](readconsoleinput.md) | Reads and removes input records from an input buffer. The function does not return until at least one record is available to be read. Then all available records are transferred to the buffer of the calling process until either no more records are available or the specified number of records has been read. Unread records remain in the input buffer for the next read operation. The function reports the total number of records that have been read. For an example that uses [**ReadConsoleInput**](readconsoleinput.md), see [Reading Input Buffer Events](reading-input-buffer-events.md). | | [**PeekConsoleInput**](peekconsoleinput.md) | Reads without removing the pending input records in an input buffer. All available records up to the specified number are copied into the buffer of the calling process. If no records are available, the function returns immediately. The function reports the total number of records that have been read. | | [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) | Determines the number of unread input records in an input buffer. | @@ -46,11 +46,3 @@ Following are descriptions of the low-level console input functions. A thread of an application's process can perform a wait operation to wait for input to be available in an input buffer. To initiate a wait operation, specify a handle to the input buffer in a call to any of the [wait functions](https://msdn.microsoft.com/library/windows/desktop/ms687069). These functions can return when the state of one or more objects is signaled. The state of a console input handle becomes signaled when there are unread records in its input buffer. The state is reset to nonsignaled when the input buffer becomes empty. If there is no input available, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the conditions of the wait operation to be satisfied. - - - - - - - - From 6cef3bf0b65f105bfc96dec9c754fe7db30b101e Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 30 Sep 2020 14:16:37 -0700 Subject: [PATCH 14/53] condense ugly table --- docs/low-level-console-output-functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/low-level-console-output-functions.md b/docs/low-level-console-output-functions.md index da320f8..ba37e90 100644 --- a/docs/low-level-console-output-functions.md +++ b/docs/low-level-console-output-functions.md @@ -25,7 +25,7 @@ The following functions read from or write to a specified number of consecutive | Function | Description | -|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +|---|---| | [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a string of Unicode or ANSI characters from a screen buffer. | | [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Writes a string of Unicode or ANSI characters to a screen buffer. | | [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a string of text and background color attributes from a screen buffer. | @@ -40,7 +40,7 @@ The following functions read from or write to rectangular blocks of character ce | Function | Description | -|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| +|---|---| | [**ReadConsoleOutput**](readconsoleoutput.md) | Copies character and color data from a specified block of screen buffer cells into a given block in a destination buffer. | | [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color data to a specified block of screen buffer cells from a given block in a source buffer. | From 670c8375da8a89adfad9adc8ca5c4a440d17fc55 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Mon, 5 Oct 2020 16:38:04 -0700 Subject: [PATCH 15/53] Wide scope of updating, templatizing, cleaning up tables, etc. --- docs/about-character-mode-applications.md | 6 +- docs/addconsolealias.md | 71 ++--- docs/allocconsole.md | 62 +---- docs/attachconsole.md | 102 ++----- docs/attaching-to-a-console.md | 5 +- docs/char-info-str.md | 195 +++----------- docs/clearing-the-screen.md | 147 ++++++---- docs/closepseudoconsole.md | 65 ++--- docs/closing-a-console.md | 1 - docs/console-aliases.md | 6 +- docs/console-application-issues.md | 4 +- ...nsole-buffer-security-and-access-rights.md | 35 ++- docs/console-code-pages.md | 5 +- docs/console-control-handlers.md | 3 +- docs/console-cursor-info-str.md | 46 +--- docs/console-font-info-str.md | 42 +-- docs/console-font-infoex.md | 45 +--- docs/console-functions.md | 3 +- docs/console-handles.md | 3 +- docs/console-history-info.md | 68 ++--- docs/console-input-buffer.md | 15 +- docs/console-modes.md | 2 + docs/console-readconsole-control.md | 131 ++------- docs/console-screen-buffer-info-str.md | 54 +--- docs/console-screen-buffer-infoex.md | 46 +--- docs/console-screen-buffers.md | 59 ++-- docs/console-selection-info-str.md | 100 ++----- docs/console-structures.md | 35 ++- docs/console-virtual-terminal-sequences.md | 31 +-- docs/console-winevents.md | 106 ++------ docs/consoles.md | 5 +- docs/coord-str.md | 53 +--- docs/createconsolescreenbuffer.md | 100 ++----- docs/createpseudoconsole.md | 98 ++----- docs/creating-a-pseudoconsole-session.md | 41 ++- docs/creation-of-a-console.md | 3 +- docs/ctrl-c-and-ctrl-break-signals.md | 1 - docs/fillconsoleoutputattribute.md | 64 ++--- docs/fillconsoleoutputcharacter.md | 72 ++--- docs/flushconsoleinputbuffer.md | 58 +--- docs/focus-event-record-str.md | 40 +-- docs/freeconsole.md | 62 +---- docs/generateconsolectrlevent.md | 94 ++----- docs/getconsolealias.md | 68 ++--- docs/getconsolealiases.md | 68 ++--- docs/getconsolealiaseslength.md | 68 ++--- docs/getconsolealiasexes.md | 68 ++--- docs/getconsolealiasexeslength.md | 68 ++--- docs/getconsolecp.md | 62 +---- docs/getconsolecursorinfo.md | 58 +--- docs/getconsoledisplaymode.md | 98 ++----- docs/getconsolefontsize.md | 58 +--- docs/getconsolehistoryinfo.md | 61 +---- docs/getconsolemode.md | 213 ++------------- docs/getconsoleoriginaltitle.md | 68 ++--- docs/getconsoleoutputcp.md | 62 ++--- docs/getconsoleprocesslist.md | 61 +---- docs/getconsolescreenbufferinfo.md | 64 ++--- docs/getconsolescreenbufferinfoex.md | 61 +---- docs/getconsoleselectioninfo.md | 61 +---- docs/getconsoletitle.md | 73 ++--- docs/getconsolewindow.md | 61 ++--- docs/getcurrentconsolefont.md | 62 ++--- docs/getcurrentconsolefontex.md | 58 +--- docs/getlargestconsolewindowsize.md | 61 +---- docs/getnumberofconsoleinputevents.md | 61 +---- docs/getnumberofconsolemousebuttons.md | 61 +---- docs/getstdhandle.md | 110 ++------ docs/handlerroutine.md | 110 ++------ docs/high-level-console-i-o.md | 6 +- ...evel-console-input-and-output-functions.md | 7 +- docs/high-level-console-modes.md | 49 +--- docs/includes/console-mode-flags.md | 22 ++ docs/includes/console-mode-remarks.md | 7 + .../includes/setting-codepage-mode-remarks.md | 1 + docs/input-and-output-methods.md | 12 +- docs/input-record-str.md | 104 ++----- docs/key-event-record-str.md | 145 ++-------- docs/legacymode.md | 5 +- docs/low-level-console-input-functions.md | 22 +- docs/low-level-console-modes.md | 7 +- docs/low-level-console-output-functions.md | 9 +- docs/menu-event-record-str.md | 39 +-- docs/mouse-event-record-str.md | 251 +++-------------- docs/peekconsoleinput.md | 72 ++--- docs/pseudoconsoles.md | 2 +- docs/readconsole.md | 70 ++--- docs/readconsoleinput.md | 74 ++--- docs/readconsoleoutput.md | 81 ++---- docs/readconsoleoutputattribute.md | 63 ++--- docs/readconsoleoutputcharacter.md | 72 ++--- ...ing-blocks-of-characters-and-attributes.md | 170 ++++++------ docs/reading-input-buffer-events.md | 149 +++++----- .../registering-a-control-handler-function.md | 11 +- docs/resizepseudoconsole.md | 64 ++--- docs/scrollconsolescreenbuffer.md | 73 ++--- docs/scrolling-a-screen-buffer-s-contents.md | 93 ++++--- docs/scrolling-a-screen-buffer-s-window.md | 83 +++--- docs/setconsoleactivescreenbuffer.md | 64 ++--- docs/setconsolecp.md | 64 ++--- docs/setconsolectrlhandler.md | 65 ++--- docs/setconsolecursorinfo.md | 61 +---- docs/setconsolecursorposition.md | 64 ++--- docs/setconsoledisplaymode.md | 90 ++----- docs/setconsolehistoryinfo.md | 61 +---- docs/setconsolemode.md | 221 ++------------- docs/setconsoleoutputcp.md | 63 ++--- docs/setconsolescreenbufferinfoex.md | 58 +--- docs/setconsolescreenbuffersize.md | 58 +--- docs/setconsoletextattribute.md | 66 ++--- docs/setconsoletitle.md | 73 ++--- docs/setconsolewindowinfo.md | 64 ++--- docs/setcurrentconsolefontex.md | 61 +---- docs/setstdhandle.md | 103 ++----- docs/small-rect-str.md | 47 +--- ...e-high-level-input-and-output-functions.md | 254 +++++++++--------- docs/window-and-screen-buffer-size.md | 4 +- docs/window-buffer-size-record-str.md | 47 +--- docs/writeconsole.md | 72 ++--- docs/writeconsoleinput.md | 72 ++--- docs/writeconsoleoutput.md | 73 ++--- docs/writeconsoleoutputattribute.md | 72 ++--- docs/writeconsoleoutputcharacter.md | 81 ++---- 123 files changed, 2043 insertions(+), 5786 deletions(-) create mode 100644 docs/includes/console-mode-flags.md create mode 100644 docs/includes/console-mode-remarks.md create mode 100644 docs/includes/setting-codepage-mode-remarks.md diff --git a/docs/about-character-mode-applications.md b/docs/about-character-mode-applications.md index 461198d..70c475d 100644 --- a/docs/about-character-mode-applications.md +++ b/docs/about-character-mode-applications.md @@ -19,13 +19,13 @@ ms.assetid: 39204f0e-b0b8-4f92-af8e-e146ac06c454 Character mode (or "command-line") applications: -1. [Optionally] Read data from standard input (stdin) +1. \[Optionally\] Read data from standard input (stdin) 2. Do "work" -3. [Optionally] Write data to standard output (stdout) or standard error (stderr) +3. \[Optionally\] Write data to standard output (stdout) or standard error (stderr) Character mode applications communicate with the end-user through a "console" (or "terminal") application. A console converts user input from keyboard, mouse, touch-screen, pen, etc., and sends it to a character mode application's stdin. A console may also display a character mode application's text output on the user's screen. -In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user. +In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user. However, in the recent era, the console team is encouraging all character mode applications to be developed with [virtual terminal sequences](console-virtual-terminal-sequences.md) over the classic API calls for maximum compatibility between Windows and other operating system platforms. More details on this transition and the trade offs involved can be found in our discussion of [classic APIs versus virtual terminal sequences](classic-vs-vt.md). - [Consoles](consoles.md) - [Input and Output Methods](input-and-output-methods.md) diff --git a/docs/addconsolealias.md b/docs/addconsolealias.md index 306e99a..d8a551c 100644 --- a/docs/addconsolealias.md +++ b/docs/addconsolealias.md @@ -40,8 +40,7 @@ api_type: Defines a console alias for the specified executable. -Syntax ------- +## Syntax ```C BOOL WINAPI AddConsoleAlias( @@ -51,8 +50,7 @@ BOOL WINAPI AddConsoleAlias( ); ``` -Parameters ----------- +## Parameters *Source* \[in\] The console alias to be mapped to the text specified by *Target*. @@ -63,71 +61,34 @@ The text to be substituted for *Source*. If this parameter is **NULL**, then the *ExeName* \[in\] The name of the executable file for which the console alias is to be defined. -Return value ------------- +## Return value If the function succeeds, the return value is **TRUE**. If the function fails, the return value is **FALSE**. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). [!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] -Examples --------- +## Examples For an example, see [Console Aliases](console-aliases.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

AddConsoleAliasW (Unicode) and AddConsoleAliasA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **AddConsoleAliasW** (Unicode) and **AddConsoleAliasA** (ANSI) | + +## See also [Console Aliases](console-aliases.md) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 0e4d2ea..ba41d6a 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -33,30 +33,25 @@ api_type: # AllocConsole function - Allocates a new console for the calling process. -Syntax ------- +## Syntax ```C BOOL WINAPI AllocConsole(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A process can be associated with only one console, so the **AllocConsole** function fails if the calling process already has a console. A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its current console, then it can call **AllocConsole** to create a new console or [**AttachConsole**](attachconsole.md) to attach to another console. @@ -66,46 +61,17 @@ If the calling process creates a child process, the child inherits the new conso This function is primarily used by a graphical user interface (GUI) application to create a console window. GUI applications are initialized without a console. Console applications are initialized with a console, unless they are created as detached processes (by calling the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) function with the **DETACHED\_PROCESS** flag). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/attachconsole.md b/docs/attachconsole.md index 47de7f7..198f884 100644 --- a/docs/attachconsole.md +++ b/docs/attachconsole.md @@ -32,11 +32,9 @@ api_type: # AttachConsole function +Attaches the calling process to the console of the specified process as a client application. -Attaches the calling process to the console of the specified process. - -Syntax ------- +## Syntax ```C BOOL WINAPI AttachConsole( @@ -44,95 +42,41 @@ BOOL WINAPI AttachConsole( ); ``` -Parameters ----------- +## Parameters *dwProcessId* \[in\] The identifier of the process whose console is to be used. This parameter can be one of the following values. - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
pid

Use the console of the specified process.

-ATTACH_PARENT_PROCESS -(DWORD)-1

Use the console of the parent of the current process.

- -  - -Return value ------------- +| Value | Meaning | +|-|-| +| *pid* | Use the console of the specified process. | +| **ATTACH\_PARENT\_PROCESS** `(DWORD)-1` | Use the console of the parent of the current process. | + +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks -A process can be attached to at most one console. If the calling process is already attached to a console, the error code returned is **ERROR\_ACCESS\_DENIED** (5). If the specified process does not have a console, the error code returned is **ERROR\_INVALID\_HANDLE** (6). If the specified process does not exist, the error code returned is **ERROR\_INVALID\_PARAMETER** (87). +A process can be attached to at most one console. If the calling process is already attached to a console, the error code returned is **ERROR\_ACCESS\_DENIED** (`5`). If the specified process does not have a console, the error code returned is **ERROR\_INVALID\_HANDLE** (`6`). If the specified process does not exist, the error code returned is **ERROR\_INVALID\_PARAMETER** (`87`). A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its console. If other processes share the console, the console is not destroyed, but the process that called **FreeConsole** cannot refer to it. A console is closed when the last process attached to it terminates or calls **FreeConsole**. After a process calls **FreeConsole**, it can call the [**AllocConsole**](allocconsole.md) function to create a new console or **AttachConsole** to attach to another console. -To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +To compile an application that uses this function, define **\_WIN32\_WINNT** as `0x0501` or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). + +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/attaching-to-a-console.md b/docs/attaching-to-a-console.md index 26eff3b..562137b 100644 --- a/docs/attaching-to-a-console.md +++ b/docs/attaching-to-a-console.md @@ -17,7 +17,8 @@ ms.assetid: 348e572f-2448-4384-9822-fab01d4ba255 # Attaching to a Console - -A process can use the [**AttachConsole**](attachconsole.md) function to attach to a console. A process can be attached to one console. +A process can use the [**AttachConsole**](attachconsole.md) function to attach to a console as a client. A process can be attached to one console. A console can have many processes attached to it. To retrieve a list of the processes attached to a console, call the [**GetConsoleProcessList**](getconsoleprocesslist.md) function. + +To attach as a server, see information about [**Pseudoconsoles**](pseudoconsoles.md). diff --git a/docs/char-info-str.md b/docs/char-info-str.md index f210513..5045673 100644 --- a/docs/char-info-str.md +++ b/docs/char-info-str.md @@ -25,7 +25,7 @@ topic_type: api_name: - CHAR_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -36,8 +36,7 @@ api_type: Specifies a Unicode or ANSI character and its attributes. This structure is used by console functions to read from and write to a console screen buffer. -Syntax ------- +## Syntax ```C typedef struct _CHAR_INFO { @@ -49,8 +48,7 @@ typedef struct _CHAR_INFO { } CHAR_INFO, *PCHAR_INFO; ``` -Members -------- +## Members **Char** A union of the following members. @@ -64,170 +62,37 @@ ANSI character of a screen buffer character cell. **Attributes** The character attributes. This member can be zero or any combination of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-FOREGROUND_BLUE -0x0001

Text color contains blue.

-FOREGROUND_GREEN -0x0002

Text color contains green.

-FOREGROUND_RED -0x0004

Text color contains red.

-FOREGROUND_INTENSITY -0x0008

Text color is intensified.

-BACKGROUND_BLUE -0x0010

Background color contains blue.

-BACKGROUND_GREEN -0x0020

Background color contains green.

-BACKGROUND_RED -0x0040

Background color contains red.

-BACKGROUND_INTENSITY -0x0080

Background color is intensified.

-COMMON_LVB_LEADING_BYTE -0x0100

Leading byte.

-COMMON_LVB_TRAILING_BYTE -0x0200

Trailing byte.

-COMMON_LVB_GRID_HORIZONTAL -0x0400

Top horizontal

-COMMON_LVB_GRID_LVERTICAL -0x0800

Left vertical.

-COMMON_LVB_GRID_RVERTICAL -0x1000

Right vertical.

-COMMON_LVB_REVERSE_VIDEO -0x4000

Reverse foreground and background attribute.

-COMMON_LVB_UNDERSCORE -0x8000

Underscore.

- -  - -Examples --------- +| Value | Meaning | +|-|-| +| **FOREGROUND_BLUE** `0x0001` | Text color contains blue. | +| **FOREGROUND_GREEN** `0x0002` | Text color contains green. | +| **FOREGROUND_RED** `0x0004` | Text color contains red. | +| **FOREGROUND_INTENSITY** `0x0008` | Text color is intensified. | +| **BACKGROUND_BLUE** `0x0010` | Background color contains blue. | +| **BACKGROUND_GREEN** `0x0020` | Background color contains green. | +| **BACKGROUND_RED** `0x0040` | Background color contains red. | +| **BACKGROUND_INTENSITY** `0x0080` | Background color is intensified. | +| **COMMON_LVB_LEADING_BYTE** `0x0100` | Leading byte. | +| **COMMON_LVB_TRAILING_BYTE** `0x0200` | Trailing byte. | +| **COMMON_LVB_GRID_HORIZONTAL** `0x0400` | Top horizontal. | +| **COMMON_LVB_GRID_LVERTICAL** `0x0800` | Left vertical. | +| **COMMON_LVB_GRID_RVERTICAL** `0x1000` | Right vertical. | +| **COMMON_LVB_REVERSE_VIDEO** `0x4000` | Reverse foreground and background attribute. | +| **COMMON_LVB_UNDERSCORE** `0x8000` | Underscore. | + +## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wincon.h (include Windows.h)
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinCon.h (include Windows.h) | + +## See also [**ReadConsoleOutput**](readconsoleoutput.md) diff --git a/docs/clearing-the-screen.md b/docs/clearing-the-screen.md index f3ccbfa..4fcf203 100644 --- a/docs/clearing-the-screen.md +++ b/docs/clearing-the-screen.md @@ -17,10 +17,9 @@ ms.assetid: 2097cc53-13b9-4f29-9d2c-feea56a27cb8 # Clearing the Screen - There are four ways to clear the screen in a console application. -## Example 1 +## Example 1 > [!TIP] > This is the recommended method using **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for all new development. For more information, see the discussion of **[classic console APIs versus virtual terminal sequences](classic-vs-vt.md)**. @@ -28,7 +27,6 @@ There are four ways to clear the screen in a console application. The first method is to set your application up for virtual terminal output sequences and then call the "clear screen" command. ```C - #include int main( void ) @@ -63,13 +61,12 @@ int main( void ) SetConsoleMode(hStdOut, originalMode); return ::GetLastError(); } - + // Restore the mode on the way out to be nice to other command-line applications. SetConsoleMode(hStdOut, originalMode); return 0; } - ``` A variation on this command is to use the "clear buffer" command to remove all history scrolling up and down, not just what is visible within the window. @@ -84,97 +81,139 @@ PCWSTR sequence = L"\x1b[3J"; You can find additional variations on this command in the virtual terminal sequences documentation on **[Erase In Display](console-virtual-terminal-sequences.md#text-modification)**. -## Example 2 +## Example 2 The second method is to write a function to scroll the contents of the screen or buffer and set a fill for the revealed space. -This matches the behavior of (CMD OR POWERSHELL, WHICH WAS IT) +This matches the behavior of the command prompt `cmd.exe`. ```C -``` +#include -## Example 3 +void cls(HANDLE hConsole) +{ + CONSOLE_SCREEN_BUFFER_INFO csbi; + SMALL_RECT scrollRect; + COORD scrollTarget; + CHAR_INFO fill; + // Get the number of character cells in the current buffer. + if (!GetConsoleScreenBufferInfo(hConsole, &csbi)) + { + return; + } -The third method is to write a function to programmatically clear the screen using the [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) and [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) functions. + // Scroll the rectangle of the entire buffer. + scrollRect.Left = 0; + scrollRect.Top = 0; + scrollRect.Right = csbi.dwSize.X; + scrollRect.Bottom = csbi.dwSize.Y; -This matches the behavior of (CMD OR POWERSHELL, WHICH WAS IT) + // Scroll it upwards off the top of the buffer with a magnitude of the entire height. + scrollTarget.X = 0; + scrollTarget.Y = (SHORT)(0 - csbi.dwSize.Y); -The following sample code demonstrates this technique. + // Fill with empty spaces with the buffer's default text attribute. + fill.Char.UnicodeChar = TEXT(' '); + fill.Attributes = csbi.wAttributes; -```C -#include + // Do the scroll + ScrollConsoleScreenBuffer(hConsole, &scrollRect, NULL, scrollTarget, &fill); + + // Move the cursor to the top left corner too. + csbi.dwCursorPosition.X = 0; + csbi.dwCursorPosition.Y = 0; -void cls( HANDLE hConsole ) + SetConsoleCursorPosition(hConsole, csbi.dwCursorPosition); +} + +int main(void) { - COORD coordScreen = { 0, 0 }; // home for the cursor - DWORD cCharsWritten; - CONSOLE_SCREEN_BUFFER_INFO csbi; - DWORD dwConSize; + HANDLE hStdout; + + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + + cls(hStdout); + + return 0; +} -// Get the number of character cells in the current buffer. +``` - if( !GetConsoleScreenBufferInfo( hConsole, &csbi )) - { - return; - } +## Example 3 - dwConSize = csbi.dwSize.X * csbi.dwSize.Y; +The third method is to write a function to programmatically clear the screen using the [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) and [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) functions. - // Fill the entire screen with blanks. +The following sample code demonstrates this technique. - if( !FillConsoleOutputCharacter( hConsole, // Handle to console screen buffer - (TCHAR) ' ', // Character to write to the buffer - dwConSize, // Number of cells to write - coordScreen, // Coordinates of first cell - &cCharsWritten ))// Receive number of characters written - { - return; - } +```C +#include - // Get the current text attribute. +void cls(HANDLE hConsole) +{ + COORD coordScreen = { 0, 0 }; // home for the cursor + DWORD cCharsWritten; + CONSOLE_SCREEN_BUFFER_INFO csbi; + DWORD dwConSize; - if( !GetConsoleScreenBufferInfo( hConsole, &csbi )) - { - return; - } + // Get the number of character cells in the current buffer. + if (!GetConsoleScreenBufferInfo(hConsole, &csbi)) + { + return; + } - // Set the buffer's attributes accordingly. + dwConSize = csbi.dwSize.X * csbi.dwSize.Y; - if( !FillConsoleOutputAttribute( hConsole, // Handle to console screen buffer - csbi.wAttributes, // Character attributes to use - dwConSize, // Number of cells to set attribute - coordScreen, // Coordinates of first cell - &cCharsWritten )) // Receive number of characters written - { - return; - } + // Fill the entire screen with blanks. + if (!FillConsoleOutputCharacter(hConsole, // Handle to console screen buffer + (TCHAR)' ', // Character to write to the buffer + dwConSize, // Number of cells to write + coordScreen, // Coordinates of first cell + &cCharsWritten)) // Receive number of characters written + { + return; + } - // Put the cursor at its home coordinates. + // Get the current text attribute. + if (!GetConsoleScreenBufferInfo(hConsole, &csbi)) + { + return; + } + + // Set the buffer's attributes accordingly. + if (!FillConsoleOutputAttribute(hConsole, // Handle to console screen buffer + csbi.wAttributes, // Character attributes to use + dwConSize, // Number of cells to set attribute + coordScreen, // Coordinates of first cell + &cCharsWritten)) // Receive number of characters written + { + return; + } - SetConsoleCursorPosition( hConsole, coordScreen ); + // Put the cursor at its home coordinates. + SetConsoleCursorPosition(hConsole, coordScreen); } -int main( void ) +int main(void) { HANDLE hStdout; hStdout = GetStdHandle(STD_OUTPUT_HANDLE); cls(hStdout); - + return 0; } ``` -## Example 4 +## Example 4 The fourth method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter `cmd.exe` to clear the screen. ```C #include -int main( void ) +int main(void) { system("cls"); return 0; diff --git a/docs/closepseudoconsole.md b/docs/closepseudoconsole.md index e391cd1..db9cdb4 100644 --- a/docs/closepseudoconsole.md +++ b/docs/closepseudoconsole.md @@ -20,75 +20,42 @@ api_type: # ClosePseudoConsole function - Closes a pseudoconsole from the given handle. -Syntax ------- +## Syntax ```C void WINAPI ClosePseudoConsole( - _In_ HPCON hPC + _In_ HPCON hPC ); ``` -Parameters ----------- +## Parameters *hPC* \[in\] A handle to an active psuedoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). -Return value ------------- +## Return value *none* -Remarks -------- +## Remarks Upon closing a pseudoconsole, client applications attached to the session will be terminated as well. A final painted frame may arrive on `hOutput` from the pseudoconsole when this API is called. It is expected that the caller will drain this information from the communication channel buffer and either present it or discard it. Failure to drain the buffer may cause the Close call to wait indefinitely until it is drained or the communication channels are broken another way. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 10 1809 [desktop apps only]

Minimum supported server

Windows Server 2019 [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | +| Minimum supported server | Windows Server 2019 \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Pseudoconsoles](pseudoconsoles.md) diff --git a/docs/closing-a-console.md b/docs/closing-a-console.md index 9df5c92..8eeace4 100644 --- a/docs/closing-a-console.md +++ b/docs/closing-a-console.md @@ -17,7 +17,6 @@ ms.assetid: 254b7cfc-4dee-452f-a409-4fc90d20d4c1 # Closing a Console - A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its console. If other processes share the console, the console is not destroyed, but the process that called **FreeConsole** cannot refer to it. After calling **FreeConsole**, the process can use [**AllocConsole**](allocconsole.md) to create a new console or [**AttachConsole**](attachconsole.md) to attach to another console. A console is closed when the last process attached to it terminates or calls [**FreeConsole**](freeconsole.md). diff --git a/docs/console-aliases.md b/docs/console-aliases.md index 36b11a7..77326bd 100644 --- a/docs/console-aliases.md +++ b/docs/console-aliases.md @@ -20,19 +20,19 @@ ms.assetid: 8169708b-83da-47ef-94be-eca3ca7d0a5b Console aliases are used to map source strings to target strings. For example, you can define a console alias that maps "test" to "cd \\a\_very\_long\_path\\test". When you type "test" at the command line, the console subsystem expands the alias and executes the specified cd command. -To define a console alias, use Doskey.exe to create a macro, or use the [**AddConsoleAlias**](addconsolealias.md) function. The following example uses Doskey.exe: +To define a console alias, use `Doskey.exe` to create a macro, or use the [**AddConsoleAlias**](addconsolealias.md) function. The following example uses `Doskey.exe`: **doskey test=cd \\**a\_very\_long\_path**\\test** The following call to [**AddConsoleAlias**](addconsolealias.md) creates the same console alias: -``` syntax +``` C AddConsoleAlias( TEXT("test"), TEXT("cd \\\\test"), TEXT("cmd.exe")); ``` -To add parameters to a console alias macro using Doskey.exe, use the batch parameters $1 through $9. For more information on the special codes that can be used in Doskey macro definitions, see the command-line help for Doskey.exe or [Doskey](https://go.microsoft.com/fwlink/p/?linkid=196265) on TechNet. +To add parameters to a console alias macro using `Doskey.exe`, use the batch parameters `$1` through `$9`. For more information on the special codes that can be used in Doskey macro definitions, see the command-line help for `Doskey.exe` or [Doskey](https://go.microsoft.com/fwlink/p/?linkid=196265) on TechNet. All instances of an executable file running in the same console window share any defined console aliases. Multiple instances of the same executable file running in different console windows do not share console aliases. Different executable files running in the same console window do not share console aliases. diff --git a/docs/console-application-issues.md b/docs/console-application-issues.md index c40ef93..84aa1f9 100644 --- a/docs/console-application-issues.md +++ b/docs/console-application-issues.md @@ -19,7 +19,9 @@ ms.assetid: a561fbdd-b50d-4687-92d7-735377a7991d The 8-bit console functions use the OEM code page. All other functions use the ANSI code page by default. This means that strings returned by the console functions may not be processed correctly by the other functions and vice versa. For example, if **FindFirstFileA** returns a string that contains certain extended ANSI characters, **WriteConsoleA** will not display the string properly. -The best long-term solution for a console application is to use Unicode. Barring that solution, a console application should use the [SetFileApisToOEM](https://msdn.microsoft.com/library/windows/desktop/aa365534) function. That function changes relevant file functions so that they produce OEM character set strings rather than ANSI character set strings. +The best long-term solution for a console application is to use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. The console will accept UTF-16 encoding on the W variant of the APIs or UTF-8 encoding on the A variant of the APIs after using **[SetConsoleCP](setconsolecp.md)** and **[SetConsoleOutputCP](setconsoleoutputcp.md)** to `65001` (`CP_UTF8` constant) for the UTF-8 code page. + +Barring that solution, a console application should use the [SetFileApisToOEM](https://msdn.microsoft.com/library/windows/desktop/aa365534) function. That function changes relevant file functions so that they produce OEM character set strings rather than ANSI character set strings. The following are file functions: diff --git a/docs/console-buffer-security-and-access-rights.md b/docs/console-buffer-security-and-access-rights.md index e9ef39b..8be29d3 100644 --- a/docs/console-buffer-security-and-access-rights.md +++ b/docs/console-buffer-security-and-access-rights.md @@ -19,17 +19,44 @@ ms.assetid: f9a50063-8fc8-4cd1-8f24-9ae3946d3119 The Windows security model enables you to control access to console input buffers and console screen buffers. For more information about security, see [Access-Control Model](https://msdn.microsoft.com/library/windows/desktop/aa374876). +## Console Object Security Descriptors + You can specify a [security descriptor](https://msdn.microsoft.com/library/windows/desktop/aa379563) for the console input and console screen buffers when you call the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) or [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function. If you specify **NULL**, the object gets a default security descriptor. The ACLs in the default security descriptor for a console buffer come from the primary or impersonation token of the creator. The handles returned by [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858), [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md), and [**GetStdHandle**](getstdhandle.md) have the **GENERIC\_READ** and **GENERIC\_WRITE** access rights. The valid access rights include the **GENERIC\_READ** and **GENERIC\_WRITE** [generic access rights](https://msdn.microsoft.com/library/windows/desktop/aa446632). - -| Value | Meaning | -|----------------------------------|-------------------------------------------------------------------------------------------------------| +| Value | Meaning | +|-|-| | **GENERIC\_READ** (0x80000000L) | Requests read access to the console screen buffer, enabling the process to read data from the buffer. | | **GENERIC\_WRITE** (0x40000000L) | Requests write access to the console screen buffer, enabling the process to write data to the buffer. | > [!NOTE] -> TODO: Write a note here about UWP readback blocking and link to the RS4 feature for "console UWPs" \ No newline at end of file +> **[Universal Windows Platform console apps](https://docs.microsoft.com/windows/uwp/launch-resume/console-uwp)** and those with a lower **[integrity level](https://docs.microsoft.com/windows/win32/secauthz/mandatory-integrity-control)** than the attached console will be prohibited from both reading the output buffer and writing to the input buffer even if the security descriptors above would normally permit it. Please see the **[Wrong Way Verbs](#wrong-way-verbs)** discussion below for more details. + +## Wrong-Way Verbs + +Some operations to the console objects will be denied even if the object has a security descriptor that is stated to specifically permit reading or writing. This specifically concerns command-line applications running in a reduced-privilege context that are sharing a console session that was created by a command-line application in a more permissive context. + +The term "wrong-way verbs" is intended to apply to the operation that is the converse of the normal flow for one of the console objects. Specifically, the normal flow for the output buffer is writing and the normal flow for the input buffer is reading. The "wrong-way" would therefore be the reading of the output buffer or the writing of the input buffer. These are functions that are described in the **[Low-Level Console I/O Functions](low-level-console-i-o.md)** documentation. + +The two scenarios where this can be found are: + +1. **[Universal Windows Platform console apps](https://docs.microsoft.com/windows/uwp/launch-resume/console-uwp)**. As these are cousins of other Universal Windows Platform applications, they hold a promise that they are isolated from other applications and provide user guarantees around the effects of their operation. +1. Any console application intentionally launched with a lower **[integrity level](https://docs.microsoft.com/windows/win32/secauthz/mandatory-integrity-control)** than the existing session which can be accomplished with **[labeling or token manipulation during CreateProcess](https://docs.microsoft.com/en-us/previous-versions/dotnet/articles/bb625960(v=msdn.10))**. + +If either of these scenarios is detected, the console will apply the "wrong-way verbs" flag to the command-line application connection and reject calls to the following APIs to reduce the surface of communication between the levels: + +:::row::: + :::column::: + [ReadConsoleOutput](readconsoleoutput.md) + [ReadConsoleOutputCharacter](readconsoleoutputcharacter.md) + [ReadConsoleOutputAttribute](readconsoleoutputattribute.md) + :::column-end::: + :::column::: + [WriteConsoleInput](writeconsoleinput.md) + :::column-end::: +:::row-end::: + +Rejected calls will receive an **access denied** error code, the same as if the read or write permission were denied by the security descriptors on the object. diff --git a/docs/console-code-pages.md b/docs/console-code-pages.md index 381e11a..6f6c172 100644 --- a/docs/console-code-pages.md +++ b/docs/console-code-pages.md @@ -21,9 +21,8 @@ A *code page* is a mapping of 256 character codes to individual characters. Diff Associated with each console are two code pages: one for input and one for output. A console uses its input code page to translate keyboard input into the corresponding character value. It uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. An application can use the [**SetConsoleCP**](setconsolecp.md) and [**GetConsoleCP**](getconsolecp.md) functions to set and retrieve a console's input code pages and the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**GetConsoleOutputCP**](getconsoleoutputcp.md) functions to set and retrieve its output code pages. -The identifiers of the code pages available on the local computer are stored in the registry under the following key. - -**HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Nls\\CodePage** +The identifiers of the code pages available on the local computer are stored in the registry under the following key: +`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage` For information about using the registry functions to determine the available code pages, see [**Registry**](https://msdn.microsoft.com/library/windows/desktop/ms724871). diff --git a/docs/console-control-handlers.md b/docs/console-control-handlers.md index 194b4b7..0b84375 100644 --- a/docs/console-control-handlers.md +++ b/docs/console-control-handlers.md @@ -17,9 +17,10 @@ ms.assetid: 6480e8ee-d228-4c07-99df-de1e0c3ca250 # Console Control Handlers - Each console process has its own list of control handler functions that are called by the system when the process receives a [CTRL+C](ctrl-c-and-ctrl-break-signals.md), [CTRL+BREAK](ctrl-c-and-ctrl-break-signals.md), or [CTRL+CLOSE](ctrl-close-signal.md) signal. Initially, the list of control handlers for each process contains only a default handler function that calls the [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) function. A console process can add or remove additional [**HandlerRoutine**](handlerroutine.md) functions by calling the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function. This function does not affect the lists of control handlers for other processes. When a console process receives any of the control signals, it calls the handler functions on a last-registered, first-called basis until one of the handlers returns **TRUE**. If none of the handlers returns **TRUE**, the default handler is called. The function's *dwCtrlType* parameter identifies which control signal was received, and the return value indicates whether the signal was handled. +A new thread is started inside the command-line client process to run the handler routines. More information on the timeout values and action of this thread can be found in the [**HandlerRoutine**](handlerroutine#remarks) function documentation. + For an example of a control handler function, see [Registering a Control Handler Function](registering-a-control-handler-function.md). diff --git a/docs/console-cursor-info-str.md b/docs/console-cursor-info-str.md index 6a9dc43..fba2bcb 100644 --- a/docs/console-cursor-info-str.md +++ b/docs/console-cursor-info-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - CONSOLE_CURSOR_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -37,8 +37,7 @@ api_type: Contains information about the console cursor. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_CURSOR_INFO { @@ -47,45 +46,26 @@ typedef struct _CONSOLE_CURSOR_INFO { } CONSOLE_CURSOR_INFO, *PCONSOLE_CURSOR_INFO; ``` -Members -------- +## Members **dwSize** The percentage of the character cell that is filled by the cursor. This value is between 1 and 100. The cursor appearance varies, ranging from completely filling the cell to showing up as a horizontal line at the bottom of the cell. -**Note**  While the **dwSize** value is normally between 1 and 100, under some circumstances a value outside of that range might be returned. For example, if **CursorSize** is set to 0 in the registry, the **dwSize** value returned would be 0. +> [!NOTE] +>While the **dwSize** value is normally between 1 and 100, under some circumstances a value outside of that range might be returned. For example, if **CursorSize** is set to 0 in the registry, the **dwSize** value returned would be 0. -  - -**bVisible** + **bVisible** The visibility of the cursor. If the cursor is visible, this member is **TRUE**. -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wincon.h (include Windows.h)
+## Requirements -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinCon.h (include Windows.h) | +## See also [**GetConsoleCursorInfo**](getconsolecursorinfo.md) diff --git a/docs/console-font-info-str.md b/docs/console-font-info-str.md index 408277a..8b7b378 100644 --- a/docs/console-font-info-str.md +++ b/docs/console-font-info-str.md @@ -25,7 +25,7 @@ topic_type: api_name: - CONSOLE_FONT_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -36,8 +36,7 @@ api_type: Contains information for a console font. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_FONT_INFO { @@ -46,8 +45,7 @@ typedef struct _CONSOLE_FONT_INFO { } CONSOLE_FONT_INFO, *PCONSOLE_FONT_INFO; ``` -Members -------- +## Members **nFont** The index of the font in the system's console font table. @@ -55,37 +53,19 @@ The index of the font in the system's console font table. **dwFontSize** A [**COORD**](coord-str.md) structure that contains the width and height of each character in the font, in logical units. The **X** member contains the width, while the **Y** member contains the height. -Remarks -------- +## Remarks To obtain the size of the font, pass the font index to the [**GetConsoleFontSize**](getconsolefontsize.md) function. -Requirements ------------- +## Requirements - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincon.h (include Windows.h)
- -## See also +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | WinCon.h (include Windows.h) | +## See also [**COORD**](coord-str.md) diff --git a/docs/console-font-infoex.md b/docs/console-font-infoex.md index b8196ef..f4c9e9f 100644 --- a/docs/console-font-infoex.md +++ b/docs/console-font-infoex.md @@ -25,7 +25,7 @@ topic_type: api_name: - CONSOLE_FONT_INFOEX api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -36,8 +36,7 @@ api_type: Contains extended information for a console font. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_FONT_INFOEX { @@ -50,8 +49,7 @@ typedef struct _CONSOLE_FONT_INFOEX { } CONSOLE_FONT_INFOEX, *PCONSOLE_FONT_INFOEX; ``` -Members -------- +## Members **cbSize** The size of this structure, in bytes. This member must be set to `sizeof(CONSOLE_FONT_INFOEX)` before calling [**GetCurrentConsoleFontEx**](getcurrentconsolefontex.md) or it will fail. @@ -71,35 +69,18 @@ The font weight. The weight can range from 100 to 1000, in multiples of 100. For **FaceName** The name of the typeface (such as Courier or Arial). -Remarks -------- +## Remarks To obtain the size of the font, pass the font index to the [**GetConsoleFontSize**](getconsolefontsize.md) function. -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Wincon.h (include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | WinCon.h (include Windows.h) | + +## See also [**GetCurrentConsoleFontEx**](getcurrentconsolefontex.md) diff --git a/docs/console-functions.md b/docs/console-functions.md index 368d67a..3bf4377 100644 --- a/docs/console-functions.md +++ b/docs/console-functions.md @@ -17,11 +17,10 @@ ms.assetid: 2a0e5dcc-be48-42ab-a05a-96f68d012a67 # Console Functions - The following functions are used to access a console. | Function | Description | -|---|---| +|-|-| | [**AddConsoleAlias**](addconsolealias.md) | Defines a console alias for the specified executable. | | [**AllocConsole**](allocconsole.md) | Allocates a new console for the calling process. | | [**AttachConsole**](attachconsole.md) | Attaches the calling process to the console of the specified process. | diff --git a/docs/console-handles.md b/docs/console-handles.md index 35cde3f..54eee3b 100644 --- a/docs/console-handles.md +++ b/docs/console-handles.md @@ -17,7 +17,6 @@ ms.assetid: dc723046-b3e9-418a-b386-79be411e5ac8 # Console Handles - A console process uses handles to access the input and screen buffers of its console. A process can use the [**GetStdHandle**](getstdhandle.md), [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858), or [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function to open one of these handles. The [**GetStdHandle**](getstdhandle.md) function provides a mechanism for retrieving the standard input (`STDIN`), standard output (`STDOUT`), and standard error (`STDERR`) handles associated with a process. During console creation, the system creates these handles. Initially, `STDIN` is a handle to the console's input buffer, and `STDOUT` and `STDERR` are handles of the console's active screen buffer. However, the [**SetStdHandle**](setstdhandle.md) function can redirect the standard handles by changing the handle associated with `STDIN`, `STDOUT`, or `STDERR`. Because the parent's standard handles are inherited by any child process, subsequent calls to **GetStdHandle** return the redirected handle. A handle returned by **GetStdHandle** may, therefore, refer to something other than console I/O. For example, before creating a child process, a parent process can use **SetStdHandle** to set a pipe handle to be the `STDIN` handle that is inherited by the child process. When the child process calls **GetStdHandle**, it gets the pipe handle. This means that the parent process can control the standard handles of the child process. The handles returned by **GetStdHandle** have `GENERIC_READ | GENERIC_WRITE` access unless **SetStdHandle** has been used to set the standard handle to have lesser access. @@ -30,7 +29,7 @@ The [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function creat Console handles returned by [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) and [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) can be used in any of the console functions that require a handle to a console's input buffer or of a console screen buffer. Handles returned by [**GetStdHandle**](getstdhandle.md) can be used by the console functions if they have not been redirected to refer to something other than console I/O. If a standard handle has been redirected to refer to a file or a pipe, however, the handle can only be used by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions. [**GetFileType**](https://docs.microsoft.com/windows/win32/api/fileapi/nf-fileapi-getfiletype) can assist in determining what device type the handle refers to. A console handle presents as `FILE_TYPE_CHAR`. -A process can use the [**DuplicateHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724251) function to create a duplicate console handle that has different access or inheritability from the original handle. Note, however, that a process can create a duplicate console handle only for its own use. This differs from other handle types (such as file, pipe, or mutex objects), for which **DuplicateHandle** can create a duplicate that is valid for a different process. +A process can use the [**DuplicateHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724251) function to create a duplicate console handle that has different access or inheritability from the original handle. Note, however, that a process can create a duplicate console handle only for its own use. This differs from other handle types (such as file, pipe, or mutex objects), for which **DuplicateHandle** can create a duplicate that is valid for a different process. Access to a console must be shared during [creation](creation-of-a-console.md) of the other process or may be requested by the other process through the [**AttachConsole**](attachconsole.md) mechanism. To close a console handle, a process can use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. diff --git a/docs/console-history-info.md b/docs/console-history-info.md index ad41df8..33ba565 100644 --- a/docs/console-history-info.md +++ b/docs/console-history-info.md @@ -25,7 +25,7 @@ topic_type: api_name: - CONSOLE_HISTORY_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -36,8 +36,7 @@ api_type: Contains information about the console history. -Syntax ------- +## Syntax ```C typedef struct { @@ -48,8 +47,7 @@ typedef struct { } CONSOLE_HISTORY_INFO, *PCONSOLE_HISTORY_INFO; ``` -Members -------- +## Members **cbSize** The size of the structure, in bytes. Set this member to `sizeof(CONSOLE_HISTORY_INFO)`. @@ -63,55 +61,19 @@ The number of history buffers kept for this console process. **dwFlags** This parameter can be zero or the following value. - ---- - - - - - - - - - - - - -
ValueMeaning
-HISTORY_NO_DUP_FLAG -0x1

Duplicate entries will not be stored in the history buffer.

- -  - -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)
- -## See also +| Value | Meaning | +|-|-| +| **HISTORY_NO_DUP_FLAG** 0x1 | Duplicate entries will not be stored in the history buffer. +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | + +## See also [**GetConsoleHistoryInfo**](getconsolehistoryinfo.md) diff --git a/docs/console-input-buffer.md b/docs/console-input-buffer.md index eda90d9..723c79b 100644 --- a/docs/console-input-buffer.md +++ b/docs/console-input-buffer.md @@ -17,7 +17,6 @@ ms.assetid: 6e536658-8a27-478e-82ee-d1e11f351301 # Console Input Buffer - Each console has an input buffer that contains a queue of input event records. When a console's window has the keyboard focus, a console formats each input event (such as a single keystroke, a movement of the mouse, or a mouse-button click) as an input record that it places in the console's input buffer. Applications can access a console's input buffer indirectly by using the [high-level console I/O functions](high-level-console-input-and-output-functions.md), or directly by using the [low-level console input functions](low-level-console-input-functions.md). The high-level input functions filter and process the data in the input buffer, returning only a stream of input characters. The low-level input functions enable applications to read input records directly from a console's input buffer, or to place input records into the input buffer. To open a handle to a console's input buffer, specify the **CONIN$** value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function. @@ -26,8 +25,7 @@ An input record is a structure containing information about the type of event th Focus and menu events are placed in a console's input buffer for internal use by the system and should be ignored by applications. -## Keyboard Events - +## Keyboard Events Keyboard events are generated when any key is pressed or released; this includes control keys. However, the ALT key has special meaning to the system when pressed and released without being combined with another character, and it is not passed through to the application. Also, the CTRL+C key combination is not passed through if the input handle is in processed mode. @@ -40,8 +38,7 @@ If the input event is a keystroke, the **Event** member in [**INPUT\_RECORD**](i - The translated Unicode™ or ANSI character. - A flag variable indicating the state of the control keys (the ALT, CTRL, SHIFT, NUM LOCK, SCROLL LOCK, and CAPS LOCK keys) and indicating whether an enhanced key was pressed. Enhanced keys for the IBM® 101-key and 102-key keyboards are the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad and the divide (/) and ENTER keys in the numeric keypad. -## Mouse Events - +## Mouse Events Mouse events are generated whenever the user moves the mouse or presses or releases one of the mouse buttons. Mouse events are placed in the input buffer only if the following conditions are met: @@ -56,14 +53,12 @@ If the input event is a mouse event, the **Event** member in [**INPUT\_RECORD**] - A flag variable indicating the state of the control keys (ALT, CTRL, SHIFT, NUM LOCK, SCROLL LOCK, and CAPS LOCK) and indicating whether an enhanced key was pressed. Enhanced keys for the IBM 101-key and 102-key keyboards are the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad and the divide (/) and ENTER keys in the numeric keypad. - A flag variable indicating whether the event was a normal button-press or button-release event, a mouse movement event, or the second click of a double-click event. -**Note**  The mouse position coordinates are in terms of the console screen buffer, not the console window. The screen buffer may have been scrolled with respect to the window, so the upper left corner of the window is not necessarily the (0,0) coordinate of the console screen buffer. To determine the coordinates of the mouse relative to the coordinate system of the window, subtract the window origin coordinates from the mouse position coordinates. Use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the window origin coordinates. - -  +> [!NOTE] +>The mouse position coordinates are in terms of the console screen buffer, not the console window. The screen buffer may have been scrolled with respect to the window, so the upper left corner of the window is not necessarily the (0,0) coordinate of the console screen buffer. To determine the coordinates of the mouse relative to the coordinate system of the window, subtract the window origin coordinates from the mouse position coordinates. Use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the window origin coordinates. The **dwButtonState** member of the [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) structure has a bit corresponding to each mouse button. The bit is 1 if the button is down and 0 if the button is up. A button-release event is detected by a 0 value for the **dwEventFlags** member of **MOUSE\_EVENT\_RECORD** and a change in a button's bit from 1 to 0. The [**GetNumberOfConsoleMouseButtons**](getnumberofconsolemousebuttons.md) function retrieves the number of buttons on the mouse. -## Buffer-Resizing Events - +## Buffer-Resizing Events A console window's menu enables the user to change the size of the active screen buffer; this change generates a buffer-resizing event. Buffer-resizing events are placed in the input buffer if the console's input mode is set to **ENABLE\_WINDOW\_INPUT** (that is, the default mode is disabled). diff --git a/docs/console-modes.md b/docs/console-modes.md index efedd70..7463571 100644 --- a/docs/console-modes.md +++ b/docs/console-modes.md @@ -21,4 +21,6 @@ Associated with each console input buffer is a set of input modes that affects i The [**GetConsoleMode**](getconsolemode.md) function reports the current input mode of a console's input buffer or the current output mode of a screen buffer. The [**SetConsoleMode**](setconsolemode.md) function sets the current mode of either a console input buffer or a screen buffer. If a console has multiple screen buffers, the output modes of each can be different. An application can change I/O modes at any time. For more information about the console modes that affect high-level and low-level I/O operations, see [High-Level Console Modes](high-level-console-modes.md) and [Low-Level Console Modes](low-level-console-modes.md). +A command-line application should expect that other command-line applications may change the console mode at any time and may not restore it to its original form before control is returned. Additionally, we recommend that all command-line applications should capture the initial console mode at startup and attempt to restore it when exiting to ensure minimal impact on other command-line applications attached to the same console. + The [**GetConsoleDisplayMode**](getconsoledisplaymode.md) function reports whether the current console is in full-screen mode and whether it communicates directly with the hardware. diff --git a/docs/console-readconsole-control.md b/docs/console-readconsole-control.md index ebf5e4a..40cd121 100644 --- a/docs/console-readconsole-control.md +++ b/docs/console-readconsole-control.md @@ -25,7 +25,7 @@ topic_type: api_name: - CONSOLE_READCONSOLE_CONTROL api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -34,8 +34,7 @@ api_type: Contains information for a console read operation. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_READCONSOLE_CONTROL { @@ -46,8 +45,7 @@ typedef struct _CONSOLE_READCONSOLE_CONTROL { } CONSOLE_READCONSOLE_CONTROL, *PCONSOLE_READCONSOLE_CONTROL; ``` -Members -------- +## Members **nLength** The size of the structure. Set this member to `sizeof(CONSOLE_READCONSOLE_CONTROL)`. @@ -61,113 +59,26 @@ A user-defined control character used to signal that the read is complete. **dwControlKeyState** The state of the control keys. This member can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-CAPSLOCK_ON -0x0080

The CAPS LOCK light is on.

-ENHANCED_KEY -0x0100

The key is enhanced.

-LEFT_ALT_PRESSED -0x0002

The left ALT key is pressed.

-LEFT_CTRL_PRESSED -0x0008

The left CTRL key is pressed.

-NUMLOCK_ON -0x0020

The NUM LOCK light is on.

-RIGHT_ALT_PRESSED -0x0001

The right ALT key is pressed.

-RIGHT_CTRL_PRESSED -0x0004

The right CTRL key is pressed.

-SCROLLLOCK_ON -0x0040

The SCROLL LOCK light is on.

-SHIFT_PRESSED -0x0010

The SHIFT key is pressed.

+| Value | Meaning | +|-|-| +| **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | +| **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | +| **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | +| **RIGHT_ALT_PRESSED** 0x0001 | The right ALT key is pressed. | +| **RIGHT_CTRL_PRESSED** 0x0004 | The right CTRL key is pressed. | +| **SCROLLLOCK_ON** 0x0040 | The SCROLL LOCK light is on. | +| **SHIFT_PRESSED** 0x0010 | The SHIFT key is pressed. | -Requirements ------------- +## Requirements - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)
+| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | -## See also +## See also [**ReadConsole**](readconsole.md) diff --git a/docs/console-screen-buffer-info-str.md b/docs/console-screen-buffer-info-str.md index f58d6ab..9c31fb1 100644 --- a/docs/console-screen-buffer-info-str.md +++ b/docs/console-screen-buffer-info-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - CONSOLE_SCREEN_BUFFER_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -35,8 +35,7 @@ api_type: Contains information about a console screen buffer. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_SCREEN_BUFFER_INFO { @@ -48,8 +47,7 @@ typedef struct _CONSOLE_SCREEN_BUFFER_INFO { } CONSOLE_SCREEN_BUFFER_INFO; ``` -Members -------- +## Members **dwSize** A [**COORD**](coord-str.md) structure that contains the size of the console screen buffer, in character columns and rows. @@ -58,7 +56,7 @@ A [**COORD**](coord-str.md) structure that contains the size of the console scre A [**COORD**](coord-str.md) structure that contains the column and row coordinates of the cursor in the console screen buffer. **wAttributes** -The attributes of the characters written to a screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**WriteConsole**](writeconsole.md) functions, or echoed to a screen buffer by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md) functions. For more information, see [Character Attributes](console-screen-buffers.md#_win32_font_attributes). +The attributes of the characters written to a screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**WriteConsole**](writeconsole.md) functions, or echoed to a screen buffer by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md) functions. For more information, see [Character Attributes](console-screen-buffers.md#character-attributes). **srWindow** A [**SMALL\_RECT**](small-rect-str.md) structure that contains the console screen buffer coordinates of the upper-left and lower-right corners of the display window. @@ -66,37 +64,19 @@ A [**SMALL\_RECT**](small-rect-str.md) structure that contains the console scree **dwMaximumWindowSize** A [**COORD**](coord-str.md) structure that contains the maximum size of the console window, in character columns and rows, given the current screen buffer size and font and the screen size. -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | + +## See also [**COORD**](coord-str.md) @@ -111,11 +91,3 @@ Requirements [**WriteConsole**](writeconsole.md) [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) - -  - -  - - - - diff --git a/docs/console-screen-buffer-infoex.md b/docs/console-screen-buffer-infoex.md index dd14579..20662ab 100644 --- a/docs/console-screen-buffer-infoex.md +++ b/docs/console-screen-buffer-infoex.md @@ -25,18 +25,16 @@ topic_type: api_name: - CONSOLE_SCREEN_BUFFER_INFOEX api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- # CONSOLE\_SCREEN\_BUFFER\_INFOEX structure - Contains extended information about a console screen buffer. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_SCREEN_BUFFER_INFOEX { @@ -52,8 +50,7 @@ typedef struct _CONSOLE_SCREEN_BUFFER_INFOEX { } CONSOLE_SCREEN_BUFFER_INFOEX, *PCONSOLE_SCREEN_BUFFER_INFOEX; ``` -Members -------- +## Members **cbSize** The size of this structure, in bytes. @@ -65,7 +62,7 @@ A [**COORD**](coord-str.md) structure that contains the size of the console scre A [**COORD**](coord-str.md) structure that contains the column and row coordinates of the cursor in the console screen buffer. **wAttributes** -The attributes of the characters written to a screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**WriteConsole**](writeconsole.md) functions, or echoed to a screen buffer by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md) functions. For more information, see [Character Attributes](console-screen-buffers.md#_win32_font_attributes). +The attributes of the characters written to a screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**WriteConsole**](writeconsole.md) functions, or echoed to a screen buffer by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md) functions. For more information, see [Character Attributes](console-screen-buffers.md#character-attributes). **srWindow** A [**SMALL\_RECT**](small-rect-str.md) structure that contains the console screen buffer coordinates of the upper-left and lower-right corners of the display window. @@ -77,37 +74,20 @@ A [**COORD**](coord-str.md) structure that contains the maximum size of the cons The fill attribute for console pop-ups. **bFullscreenSupported** -If this member is TRUE, full-screen mode is supported; otherwise, it is not. +If this member is `TRUE`, full-screen mode is supported; otherwise, it is not. **ColorTable** An array of [**COLORREF**](https://msdn.microsoft.com/library/windows/desktop/dd183449) values that describe the console's color settings. -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +## See also [**COORD**](coord-str.md) diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index 12e6a7d..bd47233 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -17,7 +17,6 @@ ms.assetid: f94995fc-5f5f-4fcd-969d-7e10020634c2 # Console Screen Buffers - A *screen buffer* is a two-dimensional array of character and color data for output in a console window. A console can have multiple screen buffers. The *active screen buffer* is the one that is displayed on the screen. The system creates a screen buffer whenever it creates a new console. To open a handle to a console's active screen buffer, specify the **CONOUT$** value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function. A process can use the [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function to create additional screen buffers for its console. A new screen buffer is not active until its handle is specified in a call to the [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) function. However, screen buffers can be accessed for reading and writing whether they are active or inactive. @@ -36,39 +35,38 @@ When a screen buffer is created, it contains space characters in every position. Applications that change any of the console screen buffer properties should either create their own screen buffer or save the state of the inherited screen buffer during startup and restore it at exit. This cooperative behavior is required to ensure that other applications sharing the same console session are not impacted by the changes. -## Cursor Appearance and Position - +## Cursor Appearance and Position A screen buffer's cursor can be visible or hidden. When it is visible, its appearance can vary, ranging from completely filling a character cell to appearing as a horizontal line at the bottom of the cell. To retrieve information about the appearance and visibility of the cursor, use the [**GetConsoleCursorInfo**](getconsolecursorinfo.md) function. This function reports whether the cursor is visible and describes the appearance of the cursor as the percentage of a character cell that it fills. To set the appearance and visibility of the cursor, use the [**SetConsoleCursorInfo**](setconsolecursorinfo.md) function. Characters written by the [high-level console I/O functions](high-level-console-i-o.md) are written at the current cursor location, advancing the cursor to the next location. To determine the current cursor position in the coordinate system of a screen buffer, use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md). You can use [**SetConsoleCursorPosition**](setconsolecursorposition.md) to set the cursor position and, thereby, control the placement of text that is written or echoed by the high-level I/O functions. If you move the cursor, text at the new cursor location is overwritten. -The position, appearance, and visibility of the cursor are set independently for each screen buffer. - -## Character Attributes - +> [!NOTE] +> Using the low-level functions to find the cursor position is discouraged. It is recommended to use [virtual terminal sequences](console-virtual-terminal-sequences.md) to query this position if necessary for advanced layouts. More information about preferring virtual terminal sequences can be found in the **[classic functions versus virtual terminal](classic-vs-vt.md)** document. -Character attributes can be divided into two classes: color and DBCS. The following attributes are defined in the `wincon.h` header file. - - -| Attribute | Meaning | -|-----------------------------------|-----------------------------------------------| -| **FOREGROUND\_BLUE** | Text color contains blue. | -| **FOREGROUND\_GREEN** | Text color contains green. | -| **FOREGROUND\_RED** | Text color contains red. | -| **FOREGROUND\_INTENSITY** | Text color is intensified. | -| **BACKGROUND\_BLUE** | Background color contains blue. | -| **BACKGROUND\_GREEN** | Background color contains green. | -| **BACKGROUND\_RED** | Background color contains red. | -| **BACKGROUND\_INTENSITY** | Background color is intensified. | -| **COMMON\_LVB\_LEADING\_BYTE** | Leading byte. | -| **COMMON\_LVB\_TRAILING\_BYTE** | Trailing byte. | -| **COMMON\_LVB\_GRID\_HORIZONTAL** | Top horizontal. | -| **COMMON\_LVB\_GRID\_LVERTICAL** | Left vertical. | -| **COMMON\_LVB\_GRID\_RVERTICAL** | Right vertical. | -| **COMMON\_LVB\_REVERSE\_VIDEO** | Reverse foreground and background attributes. | -| **COMMON\_LVB\_UNDERSCORE** | Underscore. | +The position, appearance, and visibility of the cursor are set independently for each screen buffer. +## Character Attributes + +Character attributes can be divided into two classes: color and DBCS. The following attributes are defined in the `WinCon.h` header file. + +| Attribute | Meaning | +|-|-| +| **FOREGROUND\_BLUE** | Text color contains blue. | +| **FOREGROUND\_GREEN** | Text color contains green. | +| **FOREGROUND\_RED** | Text color contains red. | +| **FOREGROUND\_INTENSITY** | Text color is intensified. | +| **BACKGROUND\_BLUE** | Background color contains blue. | +| **BACKGROUND\_GREEN** | Background color contains green. | +| **BACKGROUND\_RED** | Background color contains red. | +| **BACKGROUND\_INTENSITY** | Background color is intensified. | +| **COMMON\_LVB\_LEADING\_BYTE** | Leading byte. | +| **COMMON\_LVB\_TRAILING\_BYTE** | Trailing byte. | +| **COMMON\_LVB\_GRID\_HORIZONTAL** | Top horizontal. | +| **COMMON\_LVB\_GRID\_LVERTICAL** | Left vertical. | +| **COMMON\_LVB\_GRID\_RVERTICAL** | Right vertical. | +| **COMMON\_LVB\_REVERSE\_VIDEO** | Reverse foreground and background attributes. | +| **COMMON\_LVB\_UNDERSCORE** | Underscore. | The foreground attributes specify the text color. The background attributes specify the color used to fill the cell's background. The other attributes are used with [DBCS](https://msdn.microsoft.com/library/windows/desktop/dd317794). @@ -84,9 +82,14 @@ Each screen buffer character cell stores the color attributes for the colors use An application can use [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) to determine the current text attributes of a screen buffer and the [**SetConsoleTextAttribute**](setconsoletextattribute.md) function to set the character attributes. Changing a screen buffer's attributes does not affect the display of characters previously written. These text attributes do not affect characters written by the low-level console I/O functions (such as the [**WriteConsoleOutput**](writeconsoleoutput.md) or [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) function), which either explicitly specify the attributes for each cell that is written or leave the attributes unchanged. -## Font Attributes +> [!NOTE] +> Using the low-level functions to manipulate default and specific text attributes is discouraged. It is recommended to use [virtual terminal sequences](console-virtual-terminal-sequences.md) to set text attributes. More information about preferring virtual terminal sequences can be found in the **[classic functions versus virtual terminal](classic-vs-vt.md)** document. +## Font Attributes The [**GetCurrentConsoleFont**](getcurrentconsolefont.md) function retrieves information about the current console font. The information stored in the [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) structure includes the width and height of each character in the font. The [**GetConsoleFontSize**](getconsolefontsize.md) function retrieves the size of the font used by the specified console screen buffer. + +> [!NOTE] +> Using functions to find and manipulate font information is discouraged. It is recommended to operate command-line applications in a font neutral manner to ensure cross-platform compatibility as well as compatibility with host environments that allow the user to customize the font. More information user preferences and host environments including terminals, please see the **[ecosystem roadmap](ecosystem-roadmap.md)**. diff --git a/docs/console-selection-info-str.md b/docs/console-selection-info-str.md index 21278d4..8c308fc 100644 --- a/docs/console-selection-info-str.md +++ b/docs/console-selection-info-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - CONSOLE_SELECTION_INFO api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -37,8 +37,7 @@ api_type: Contains information for a console selection. -Syntax ------- +## Syntax ```C typedef struct _CONSOLE_SELECTION_INFO { @@ -48,64 +47,18 @@ typedef struct _CONSOLE_SELECTION_INFO { } CONSOLE_SELECTION_INFO, *PCONSOLE_SELECTION_INFO; ``` -Members -------- +## Members **dwFlags** The selection indicator. This member can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-CONSOLE_MOUSE_DOWN -0x0008

Mouse is down

-CONSOLE_MOUSE_SELECTION -0x0004

Selecting with the mouse

-CONSOLE_NO_SELECTION -0x0000

No selection

-CONSOLE_SELECTION_IN_PROGRESS -0x0001

Selection has begun

-CONSOLE_SELECTION_NOT_EMPTY -0x0002

Selection rectangle is not empty

- -  +| Value | Meaning | +|-|-| +| **CONSOLE_MOUSE_DOWN** 0x0008 | Mouse is down. The user is actively adjusting the selection rectangle with a mouse. | +| **CONSOLE_MOUSE_SELECTION** 0x0004 | Selecting with the mouse. If off, the user is operating `conhost.exe` mark mode selection with the keyboard. | +| **CONSOLE_NO_SELECTION** 0x0000 | No selection. | +| **CONSOLE_SELECTION_IN_PROGRESS** 0x0001 | Selection has begun. If a mouse selection, this will typically not occur without the `CONSOLE_SELECTION_NOT_EMPTY` flag. If a keyboard selection, this may occur when mark mode has been entered but the user is still navigating to the initial position. | +| **CONSOLE_SELECTION_NOT_EMPTY** 0x0002 | Selection rectangle not empty. The payload of *dwSelectionAnchor* and *srSelection* are valid. | **dwSelectionAnchor** A [**COORD**](coord-str.md) structure that specifies the selection anchor, in characters. @@ -113,32 +66,15 @@ A [**COORD**](coord-str.md) structure that specifies the selection anchor, in ch **srSelection** A [**SMALL\_RECT**](small-rect-str.md) structure that specifies the selection rectangle. -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | + +## See also [**COORD**](coord-str.md) diff --git a/docs/console-structures.md b/docs/console-structures.md index a16bc91..0a0a3b2 100644 --- a/docs/console-structures.md +++ b/docs/console-structures.md @@ -17,23 +17,22 @@ ms.assetid: 60f59616-d42b-469a-acf1-c1b71e68f560 # Console Structures - The following structures are used to access a console. -[**CHAR\_INFO**](char-info-str.md) -[**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) -[**CONSOLE\_FONT\_INFO**](console-font-info-str.md) -[**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) -[**CONSOLE\_HISTORY\_INFO**](console-history-info.md) -[**CONSOLE\_READCONSOLE\_CONTROL**](console-readconsole-control.md) -[**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) -[**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) -[**CONSOLE\_SELECTION\_INFO**](console-selection-info-str.md) -[**COORD**](coord-str.md) -[**FOCUS\_EVENT\_RECORD**](focus-event-record-str.md) -[**INPUT\_RECORD**](input-record-str.md) -[**KEY\_EVENT\_RECORD**](key-event-record-str.md) -[**MENU\_EVENT\_RECORD**](menu-event-record-str.md) -[**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) -[**SMALL\_RECT**](small-rect-str.md) -[**WINDOW\_BUFFER\_SIZE\_RECORD**](window-buffer-size-record-str.md) +- [**CHAR\_INFO**](char-info-str.md) +- [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) +- [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) +- [**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) +- [**CONSOLE\_HISTORY\_INFO**](console-history-info.md) +- [**CONSOLE\_READCONSOLE\_CONTROL**](console-readconsole-control.md) +- [**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) +- [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) +- [**CONSOLE\_SELECTION\_INFO**](console-selection-info-str.md) +- [**COORD**](coord-str.md) +- [**FOCUS\_EVENT\_RECORD**](focus-event-record-str.md) +- [**INPUT\_RECORD**](input-record-str.md) +- [**KEY\_EVENT\_RECORD**](key-event-record-str.md) +- [**MENU\_EVENT\_RECORD**](menu-event-record-str.md) +- [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) +- [**SMALL\_RECT**](small-rect-str.md) +- [**WINDOW\_BUFFER\_SIZE\_RECORD**](window-buffer-size-record-str.md) diff --git a/docs/console-virtual-terminal-sequences.md b/docs/console-virtual-terminal-sequences.md index 0cfab4d..df95fa4 100644 --- a/docs/console-virtual-terminal-sequences.md +++ b/docs/console-virtual-terminal-sequences.md @@ -49,12 +49,10 @@ Cursor movement will be bounded by the current viewport into the buffer. Scrolli -**Note** -\* If there are scroll margins set, RI inside the margins will scroll only the contents of the margins, and leave the viewport unchanged. (See Scrolling Margins) - -\*\*There will be no value saved in memory until the first use of the save command. The only way to access the saved value is with the restore command. - - +> [!NOTE] +>\* If there are scroll margins set, RI inside the margins will scroll only the contents of the margins, and leave the viewport unchanged. (See Scrolling Margins) +> +>\*\*There will be no value saved in memory until the first use of the save command. The only way to access the saved value is with the restore command. ## Cursor Positioning @@ -90,10 +88,10 @@ Cursor movement will be bounded by the current viewport into the buffer. Scrolli -**Note** -\*<x> and <y> parameters have the same limitations as <n> above. If <x> and <y> are omitted, they will be set to 1;1. - -\*\*ANSI.sys historical documentation can be found at and is implemented for convenience/compatibility. +> [!NOTE] +>\*<x> and <y> parameters have the same limitations as <n> above. If <x> and <y> are omitted, they will be set to 1;1. +> +>\*\*ANSI.sys historical documentation can be found at and is implemented for convenience/compatibility. @@ -151,8 +149,8 @@ All commands in this section are generally equivalent to calling [**FillConsoleO -**Note** -For IL and DL, only the lines in the scrolling margins (see Scrolling Margins) are affected. If no margins are set, the default margin borders are the current viewport. If lines would be shifted below the margins, they are discarded. When lines are deleted, blank lines are inserted at the bottom of the margins, lines from outside the viewport are never affected. +> [!NOTE] +>For IL and DL, only the lines in the scrolling margins (see Scrolling Margins) are affected. If no margins are set, the default margin borders are the current viewport. If lines would be shifted below the margins, they are discarded. When lines are deleted, blank lines are inserted at the bottom of the margins, lines from outside the viewport are never affected. For each of the sequences, the default value for <n> if it is omitted is 0. @@ -299,7 +297,8 @@ See the Cursor Keys and Numpad & Function Keys sections for the sequences emitte All commands in this section are generally equivalent to calling Get\* console APIs to retrieve status information about the current console buffer state. -**Note** These queries will emit their responses into the console input stream immediately after being recognized on the output stream while ENABLE\_VIRTUAL\_TERMINAL\_PROCESSING is set. The ENABLE\_VIRTUAL\_TERMINAL\_INPUT flag does not apply to query commands as it is assumed that an application making the query will always want to receive the reply. +> [!NOTE] +>These queries will emit their responses into the console input stream immediately after being recognized on the output stream while ENABLE\_VIRTUAL\_TERMINAL\_PROCESSING is set. The ENABLE\_VIRTUAL\_TERMINAL\_INPUT flag does not apply to query commands as it is assumed that an application making the query will always want to receive the reply. @@ -526,7 +525,8 @@ Ctrl is generally passed through exactly as received from the system. This is ty -**Note** Left Ctrl + Right Alt is treated as AltGr. When both are seen together, they will be stripped and the Unicode value of the character presented by the system will be passed into the target. The system will pre-translate AltGr values according to the current system input settings. +> [!NOTE] +>Left Ctrl + Right Alt is treated as AltGr. When both are seen together, they will be stripped and the Unicode value of the character presented by the system will be passed into the target. The system will pre-translate AltGr values according to the current system input settings. @@ -577,7 +577,8 @@ int main() } ``` -**Note** In the previous example, the string '`\x1b[31m`' is the implementation of **ESC \[ <n> m** with <n> being 31. +> [!NOTE] +>In the previous example, the string '`\x1b[31m`' is the implementation of **ESC \[ <n> m** with <n> being 31. diff --git a/docs/console-winevents.md b/docs/console-winevents.md index ba8f137..a3f8690 100644 --- a/docs/console-winevents.md +++ b/docs/console-winevents.md @@ -50,98 +50,24 @@ api_type: > WinEvents are part of the legacy **[Microsoft Active Accessibility](https://docs.microsoft.com/windows/win32/winauto/microsoft-active-accessibility)** framework. Development using these events is strongly discouraged in favor of the **[Microsoft UI Automation](https://docs.microsoft.com/windows/win32/winauto/entry-uiauto-win32)** framework which provides a more robust and comprehensive suite of interfaces for accessibility and automation applications to interact with the console. > [!WARNING] -> Registering for these events is a global activity and will significantly impact performance of all command-line applications running on a system at the same time, including services and background utilities. +> Registering for these events is a global activity and will significantly impact performance of all command-line applications running on a system at the same time, including services and background utilities. The **Microsoft UI Automation** framework is console session specific and overcomes this limitation. The following event constants are used in the *event* parameter of the [*WinEventProc*](https://msdn.microsoft.com/library/windows/desktop/dd373885(v=vs.85).aspx) callback function. For more information, see [WinEvents](https://msdn.microsoft.com/library/windows/desktop/dd373889). - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Constant/valueDescription
-EVENT_CONSOLE_CARET -0x4001

The console caret has moved. The idObject parameter is one or more of the following values: CONSOLE_CARET_SELECTION or CONSOLE_CARET_VISIBLE.

-

The idChild parameter is a COORD structure that specifies the cursor's current position.

-EVENT_CONSOLE_END_APPLICATION -0x4007

A console process has exited. The idObject parameter contains the process identifier of the terminated process.

-EVENT_CONSOLE_LAYOUT -0x4005

The console layout has changed.

-EVENT_CONSOLE_START_APPLICATION -0x4006

A new console process has started. The idObject parameter contains the process identifier of the newly created process. If the application is a 16-bit application, the idChild parameter is CONSOLE_APPLICATION_16BIT and idObject is the process identifier of the NTVDM session associated with the console.

-EVENT_CONSOLE_UPDATE_REGION -0x4002

More than one character has changed. The idObject parameter is a COORD structure that specifies the start of the changed region. The idChild parameter is a COORD structure that specifies the end of the changed region.

-EVENT_CONSOLE_UPDATE_SCROLL -0x4004

The console has scrolled. The idObject parameter is the horizontal distance the console has scrolled. The idChild parameter is the vertical distance the console has scrolled.

-EVENT_CONSOLE_UPDATE_SIMPLE -0x4003

A single character has changed. The idObject parameter is a COORD structure that specifies the character that has changed. The idChild parameter specifies the character in the low word and the character attributes in the high word.

+| Constant/value | Description | +|-|-| +| **EVENT_CONSOLE_CARET** 0x4001 | The console caret has moved. The *idObject* parameter is one or more of the following values: **CONSOLE_CARET_SELECTION** or **CONSOLE_CARET_VISIBLE**. The *idChild* parameter is a **[COORD](coord-str)** structure that specifies the cursor's current position. | +| **EVENT_CONSOLE_END_APPLICATION** 0x4007 | A console process has exited. The *idObject* parameter contains the process identifier of the terminated process. | +| **EVENT_CONSOLE_LAYOUT** 0x4005 | The console layout has changed. | +| **EVENT_CONSOLE_START_APPLICATION** 0x4006 | A new console process has started. The *idObject* parameter contains the process identifier of the newly created process. If the application is a 16-bit application, the *idChild* parameter is **CONSOLE_APPLICATION_16BIT** and *idObject* is the process identifier of the NTVDM session associated with the console. | +|**EVENT_CONSOLE_UPDATE_REGION** 0x4002 | More than one character has changed. The *idObject* parameter is a **[COORD](coord-str)** structure that specifies the start of the changed region. The *idChild* parameter is a **COORD** structure that specifies the end of the changed region. | +|**EVENT_CONSOLE_UPDATE_SCROLL** 0x4004 | The console has scrolled. The *idObject* parameter is the horizontal distance the console has scrolled. The *idChild* parameter is the vertical distance the console has scrolled. | +|**EVENT_CONSOLE_UPDATE_SIMPLE** 0x4003 | A single character has changed. The *idObject* parameter is a **[COORD](coord-str)** structure that specifies the character that has changed. The *idChild* parameter specifies the character in the low word and the **[character attributes](console-screen-buffers.md#character-attributes)** in the high word. | -Requirements ------------- +## Requirements - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winuser.h
+| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | Winuser.h | diff --git a/docs/consoles.md b/docs/consoles.md index 77aa349..c3fda2a 100644 --- a/docs/consoles.md +++ b/docs/consoles.md @@ -17,10 +17,13 @@ ms.assetid: 16148ce6-d3be-40dd-b82e-50ea1df67c4e # Consoles -A *console* (or *terminal*) is an application that provides I/O to character-mode applications. This processor-independent mechanism makes it easy to port existing character-mode applications or to create new character-mode tools and applications. +A *console* is an application that provides I/O services to character-mode applications. This processor-independent mechanism makes it easy to port existing character-mode applications or to create new character-mode tools and applications. A console consists of an input buffer and one or more screen buffers. The *input buffer* contains a queue of input records, each of which contains information about an input event. The input queue always includes key-press and key-release events. It may also include mouse events (pointer movements and button presses and releases) and events during which user actions affect the size of the active screen buffer. A *screen buffer* is a two-dimensional array of character and color data for output in a console window. Any number of processes can share a console. +> [!TIP] +>A broader idea of consoles and how they relate to terminals and command-line client applications can be found in the **[ecosystem roadmap](ecosystem-roadmap)**. + - [Creation of a Console](creation-of-a-console.md) - [Attaching to a Console](attaching-to-a-console.md) - [Closing a Console](closing-a-console.md) diff --git a/docs/coord-str.md b/docs/coord-str.md index 26db9eb..705a3b8 100644 --- a/docs/coord-str.md +++ b/docs/coord-str.md @@ -26,18 +26,16 @@ topic_type: api_name: - COORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- # COORD structure - Defines the coordinates of a character cell in a console screen buffer. The origin of the coordinate system (0,0) is at the top, left cell of the buffer. -Syntax ------- +## Syntax ```C typedef struct _COORD { @@ -46,8 +44,7 @@ typedef struct _COORD { } COORD, *PCOORD; ``` -Members -------- +## Members **X** The horizontal coordinate or column value. The units depend on the function call. @@ -55,37 +52,19 @@ The horizontal coordinate or column value. The units depend on the function call **Y** The vertical coordinate or row value. The units depend on the function call. -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) @@ -124,11 +103,3 @@ Requirements [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index afac040..0deb505 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -37,8 +37,7 @@ api_type: Creates a console screen buffer. -Syntax ------- +## Syntax ```C HANDLE WINAPI CreateConsoleScreenBuffer( @@ -50,8 +49,7 @@ HANDLE WINAPI CreateConsoleScreenBuffer( ); ``` -Parameters ----------- +## Parameters *dwDesiredAccess* \[in\] The access to the console screen buffer. For a list of access rights, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -59,34 +57,10 @@ The access to the console screen buffer. For a list of access rights, see [Conso *dwShareMode* \[in\] This parameter can be zero, indicating that the buffer cannot be shared, or it can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
-FILE_SHARE_READ -0x00000001

Other open operations can be performed on the console screen buffer for read access.

-FILE_SHARE_WRITE -0x00000002

Other open operations can be performed on the console screen buffer for write access.

- -  +| Value | Meaning | +|-|-| +| **FILE_SHARE_READ** 0x00000001 | Other open operations can be performed on the console screen buffer for read access. | +| **FILE_SHARE_WRITE** 0x00000002 | Other open operations can be performed on the console screen buffer for write access. | *lpSecurityAttributes* \[in, optional\] A pointer to a [**SECURITY\_ATTRIBUTES**](https://msdn.microsoft.com/library/windows/desktop/aa379560) structure that determines whether the returned handle can be inherited by child processes. If *lpSecurityAttributes* is **NULL**, the handle cannot be inherited. The **lpSecurityDescriptor** member of the structure specifies a security descriptor for the new console screen buffer. If *lpSecurityAttributes* is **NULL**, the console screen buffer gets a default security descriptor. The ACLs in the default security descriptor for a console screen buffer come from the primary or impersonation token of the creator. @@ -94,22 +68,21 @@ A pointer to a [**SECURITY\_ATTRIBUTES**](https://msdn.microsoft.com/library/win *dwFlags* \[in\] The type of console screen buffer to create. The only supported screen buffer type is **CONSOLE\_TEXTMODE\_BUFFER**. -*lpScreenBufferData* +*lpScreenBufferData* Reserved; should be **NULL**. -Return value ------------- +## Return value If the function succeeds, the return value is a handle to the new console screen buffer. If the function fails, the return value is **INVALID\_HANDLE\_VALUE**. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A console can have multiple screen buffers but only one active screen buffer. Inactive screen buffers can be accessed for reading and writing, but only the active screen buffer is displayed. To make the new screen buffer the active screen buffer, use the [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) function. The newly created screen buffer will copy some properties from the active screen buffer at the time that this function is called. The behavior is as follows: + - `Font` - copied from active screen buffer - `Display Window Size` - copied from active screen buffer - `Buffer Size` - matched to `Display Window Size` (**NOT** copied) @@ -122,50 +95,21 @@ The calling process can use the [**DuplicateHandle**](https://msdn.microsoft.com To close the console screen buffer handle, use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. -Examples --------- +## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/createpseudoconsole.md b/docs/createpseudoconsole.md index 4db3a2d..eac2e1a 100644 --- a/docs/createpseudoconsole.md +++ b/docs/createpseudoconsole.md @@ -23,11 +23,9 @@ api_type: # CreatePseudoConsole function - Creates a new pseudoconsole object for the calling process. -Syntax ------- +## Syntax ```C HRESULT WINAPI CreatePseudoConsole( @@ -39,8 +37,7 @@ HRESULT WINAPI CreatePseudoConsole( ); ``` -Parameters ----------- +## Parameters *size* \[in\] The dimensions of the window/buffer in count of characters that will be used on initial creation of the pseudoconsole. This can be adjusted later with [ResizePseudoConsole](resizepseudoconsole.md). @@ -53,49 +50,28 @@ An open handle to a stream of data that represents application output from the d *dwFlags* \[in\] The value can be one of the following: - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
0

Perform a standard pseudoconsole creation.

-PSEUDOCONSOLE_INHERIT_CURSOR -(DWORD)1

The created pseudoconsole session will attempt to inherit the cursor position of the parent console.

+ +| Value | Meaning | +|-|-| +| **0** | Perform a standard pseudoconsole creation. | +| **PSEUDOCONSOLE_INHERIT_CURSOR** (DWORD)1 | The created pseudoconsole session will attempt to inherit the cursor position of the paernt console. | *phPC* \[out\] Pointer to a location that will receive a handle to the new pseudoconsole device. -Return value ------------- +## Return value Type: **HRESULT** If this method succeeds, it returns **S_OK**. Otherwise, it returns an **HRESULT** error code. -Remarks -------- +## Remarks This function is primarily used by applications attempting to be a terminal window for a command-line user interface (CUI) application. The callers become responsible for presentation of the information on the output stream and for collecting user input and serializing it into the input stream. -The input and output streams encoded as UTF-8 contain plain text interleaved with [Virtual Terminal Sequences](console-virtual-terminal-sequences.md). +The input and output streams encoded as UTF-8 contain plain text interleaved with [Virtual Terminal Sequences](console-virtual-terminal-sequences.md). -On the output stream, the [virtual terminal sequences](console-virtual-terminal-sequences.md) can be decoded by the calling application to layout and present the plain text in a display window. +On the output stream, the [virtual terminal sequences](console-virtual-terminal-sequences.md) can be decoded by the calling application to layout and present the plain text in a display window. On the input stream, plain text represents standard keyboard keys input by a user. More complicated operations are represented by encoding control keys and mouse movements as [virtual terminal sequences](console-virtual-terminal-sequences.md) embedded in this stream. @@ -103,51 +79,21 @@ The handle created by this function must be closed with [ClosePseudoConsole](clo If using `PSEUDOCONSOLE_INHERIT_CURSOR`, the calling application should be prepared to respond to the request for the cursor state in an asynchronous fashion on a background thread by forwarding or interpreting the request for cursor information that will be received on `hOutput` and replying on `hInput`. Failure to do so may cause the calling application to hang while making another request of the pseudoconsole system. -Examples --------- +## Examples For a full walkthrough on using this function to establish a psuedoconsole session, please see [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 10 1809 [desktop apps only]

Minimum supported server

Windows Server 2019 [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | +| Minimum supported server | Windows Server 2019 \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Pseudoconsoles](pseudoconsoles.md) diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index ff368b2..dd560d7 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -22,21 +22,20 @@ Complete examples of using the Pseudoconsole are available on our GitHub reposit The first step is to create a pair of synchronous communication channels that will be provided during creation of the pseudoconsole session for bidirectional communication with the hosted application. These channels are processed by the pseudoconsole system using [**ReadFile**](https://docs.microsoft.com/windows/desktop/api/fileapi/nf-fileapi-readfile) and [**WriteFile**](https://docs.microsoft.com/windows/desktop/api/fileapi/nf-fileapi-writefile) with [synchronous I/O](https://docs.microsoft.com/windows/desktop/Sync/synchronization-and-overlapped-input-and-output). File or I/O device handles like a file stream or pipe are acceptable as long as an [**OVERLAPPED**](https://docs.microsoft.com/windows/desktop/api/minwinbase/ns-minwinbase-_overlapped) structure is not required for asynchronous communication. -**NOTE:** - -To prevent race conditions and deadlocks, we highly recommend that each of the communication channels is serviced on a separate thread that maintains its own client buffer state and messaging queue inside your application. Servicing all of the pseudoconsole activities on the same thread may result in a deadlock where one of the communications buffers is filled and waiting for your action while you attempt to dispatch a blocking request on another channel. +> [!WARNING] +>To prevent race conditions and deadlocks, we highly recommend that each of the communication channels is serviced on a separate thread that maintains its own client buffer state and messaging queue inside your application. Servicing all of the pseudoconsole activities on the same thread may result in a deadlock where one of the communications buffers is filled and waiting for your action while you attempt to dispatch a blocking request on another channel. ## Creating the Pseudoconsole With the communications channels that have been established, identify the "read" end of the input channel and the "write" end of the output channel. This pair of handles is provided on calling [**CreatePseudoConsole**](createpseudoconsole.md) to create the object. -When creating, a size representing the X and Y dimensions (in count of characters) is also provided. This is the dimensions that will apply to the display surface for the final (terminal) presentation window. The values are used to create an in-memory buffer inside the pseudoconsole system. +When creating, a size representing the X and Y dimensions (in count of characters) is also provided. This is the dimensions that will apply to the display surface for the final (terminal) presentation window. The values are used to create an in-memory buffer inside the pseudoconsole system. The buffer size provide answers to client character-mode applications that probe for information using the [client-side console functions](console-functions.md) like [**GetConsoleScreenBufferInfoEx**](getconsolescreenbufferinfoex.md) and dictates the layout and positioning of text when clients use functions like [**WriteConsoleOutput**](writeconsoleoutput.md). Finally, a flags field is provided on creation of a pseudoconsole to perform special functionality. By default, set this to 0 to have no special functionality. -At this time, only one special flag is available to request the inheritence of the cursor position from a console session already attached to the caller of the pseudoconsole API. This is intended for use in more advanced scenarios where a hosting application that is preparing a pseudoconsole session is itself also a client character-mode application of a another console environment. +At this time, only one special flag is available to request the inheritence of the cursor position from a console session already attached to the caller of the pseudoconsole API. This is intended for use in more advanced scenarios where a hosting application that is preparing a pseudoconsole session is itself also a client character-mode application of a another console environment. A sample snippet is provided below utilizing [**CreatePipe**](https://msdn.microsoft.com/library/windows/desktop/aa365152(v=vs.85).aspx) to establish a pair of communication channels and create the pseudoconsole. @@ -49,10 +48,10 @@ HRESULT SetUpPseudoConsole(COORD size) // Create communication channels // - Close these after CreateProcess of child application with pseudoconsole object. - HANDLE inputReadSide, outputWriteSide; + HANDLE inputReadSide, outputWriteSide; - // - Hold onto these and use them for communication with the child through the pseudoconsole. - HANDLE outputReadSide, inputWriteSide; + // - Hold onto these and use them for communication with the child through the pseudoconsole. + HANDLE outputReadSide, inputWriteSide; if (!CreatePipe(&inputReadSide, &inputWriteSide, NULL, 0)) { @@ -71,15 +70,13 @@ HRESULT SetUpPseudoConsole(COORD size) return hr; } - // ... + // ... } ``` - -**NOTE**: - -This snippet is incomplete and used for demonstration of this specific call only. You will need to manage the lifetime of the **HANDLE**s appropriately. Failure to manage the lifetime of **HANDLE**s correctly can result in deadlock scenarios, especially with synchronous I/O calls. +> [!NOTE] +>This snippet is incomplete and used for demonstration of this specific call only. You will need to manage the lifetime of the **HANDLE**s appropriately. Failure to manage the lifetime of **HANDLE**s correctly can result in deadlock scenarios, especially with synchronous I/O calls. Upon completion of the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) call to create the client character-mode application attached to the pseudoconsole, the handles given during creation should be freed from this process. This will decrease the reference count on the underlying device object and allow I/O operations to properly detect a broken channel when the pseudoconsole session closes its copy of the handles. @@ -105,7 +102,7 @@ HRESULT PrepareStartupInformation(HPCON hpc, STARTUPINFOEX* psi) // Discover the size required for the list size_t bytesRequired; InitializeProcThreadAttributeList(NULL, 1, 0, &bytesRequired); - + // Allocate memory to represent the list si.lpAttributeList = (PPROC_THREAD_ATTRIBUTE_LIST)HeapAlloc(GetProcessHeap(), 0, bytesRequired); if (!si.lpAttributeList) @@ -185,15 +182,14 @@ HRESULT SetUpPseudoConsole(COORD size) } ``` -**NOTE:** - -Closing the pseudoconsole session while the hosted process is still starting up and connecting can result in an error dialog being shown by the client application. The same error dialog is shown if the hosted process is given an invalid pseudoconsole handle for startup. To the hosted process initialization code, the two circumstances are identical. The pop-up dialog from the hosted client application on failure will read `0xc0000142` with a localized message detailing failure to initialize. +> [!NOTE] +> Closing the pseudoconsole session while the hosted process is still starting up and connecting can result in an error dialog being shown by the client application. The same error dialog is shown if the hosted process is given an invalid pseudoconsole handle for startup. To the hosted process initialization code, the two circumstances are identical. The pop-up dialog from the hosted client application on failure will read `0xc0000142` with a localized message detailing failure to initialize. ## Communicating with the Pseudoconsole Session -Once the process is created successfully, the hosting application can use the write end of the input pipe to send user interaction information into the pseudoconsole and the read end of the output pipe to receive graphical presentation information from the pseudo console. +Once the process is created successfully, the hosting application can use the write end of the input pipe to send user interaction information into the pseudoconsole and the read end of the output pipe to receive graphical presentation information from the pseudo console. -It is completely up to the hosting application to decide how to handle further activity. The hosting application could launch a window in another thread to collect user interaction input and serialize it into the write end of the input pipe for the pseudoconsole and the hosted character-mode application. Another thread could be launched to drain the read end of the output pipe for the pseudoconsole, decode the text and [virtual terminal sequence](console-virtual-terminal-sequences.md) information, and present that to the screen. +It is completely up to the hosting application to decide how to handle further activity. The hosting application could launch a window in another thread to collect user interaction input and serialize it into the write end of the input pipe for the pseudoconsole and the hosted character-mode application. Another thread could be launched to drain the read end of the output pipe for the pseudoconsole, decode the text and [virtual terminal sequence](console-virtual-terminal-sequences.md) information, and present that to the screen. Threads could also be used to relay the information from the pseudoconsole channels out to a different channel or device including a network to remote information to another process or machine and avoiding any local transcoding of the information. @@ -209,7 +205,7 @@ This can be done with the [**ResizePseudoConsole**](resizepseudoconsole.md) func // on Source property. void OnWindowResize(Event e) { - // Retrieve width and height dimensions of display in + // Retrieve width and height dimensions of display in // characters using theoretical height/width functions // that can retrieve the properties from the display // attached to the event. @@ -226,6 +222,5 @@ void OnWindowResize(Event e) To end the session, call the [**ClosePseudoConsole**](closepseudoconsole.md) function with the handle from the original pseudoconsole creation. Any attached client character-mode applications, such as the one from the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) call, will be terminated when the session is closed. If the original child was a shell-type application that creates other processes, any related attached processes in the tree will also be terminated. -**NOTE:** - -Closing the session has several side effects which can result in a deadlock condition if the pseudoconsole is used in a single-threaded synchronous fashion. The act of closing the pseudoconsole session may emit a final frame update to `hOutput` which should be drained from the communications channel buffer. Additionally, if `PSEUDOCONSOLE_INHERIT_CURSOR` was selected while creating the pseudoconsole, attempting to close the pseudoconsole without responding to the cursor inheritence query message (received on `hOutput` and replied to via `hInput`) may result in another deadlock condition. It is recommended that communications channels for the pseudoconsole are serviced on individual threads and remain drained and processed until broken of their own accord by the client application exiting or by the completion of teardown activities in calling the [**ClosePseudoConsole**](closepseudoconsole.md) function. +> [!WARNING] +>Closing the session has several side effects which can result in a deadlock condition if the pseudoconsole is used in a single-threaded synchronous fashion. The act of closing the pseudoconsole session may emit a final frame update to `hOutput` which should be drained from the communications channel buffer. Additionally, if `PSEUDOCONSOLE_INHERIT_CURSOR` was selected while creating the pseudoconsole, attempting to close the pseudoconsole without responding to the cursor inheritence query message (received on `hOutput` and replied to via `hInput`) may result in another deadlock condition. It is recommended that communications channels for the pseudoconsole are serviced on individual threads and remain drained and processed until broken of their own accord by the client application exiting or by the completion of teardown activities in calling the [**ClosePseudoConsole**](closepseudoconsole.md) function. diff --git a/docs/creation-of-a-console.md b/docs/creation-of-a-console.md index ba87a77..a6211b3 100644 --- a/docs/creation-of-a-console.md +++ b/docs/creation-of-a-console.md @@ -42,9 +42,8 @@ The system uses default values if the [**STARTUPINFO**](https://msdn.microsoft.c A process cannot change the location of its console window on the screen, but the following console functions are available to set or retrieve the other properties specified in the [**STARTUPINFO**](https://msdn.microsoft.com/library/windows/desktop/ms686331) structure. - | Function | Description | -|---|---| +|-|-| | [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) | Retrieves the window size, screen buffer size, and color attributes. | | [**SetConsoleWindowInfo**](setconsolewindowinfo.md) | Changes the size of the console window. | | [**SetConsoleScreenBufferSize**](setconsolescreenbuffersize.md) | Changes the size of the console screen buffer. | diff --git a/docs/ctrl-c-and-ctrl-break-signals.md b/docs/ctrl-c-and-ctrl-break-signals.md index 2d3387c..77f45dc 100644 --- a/docs/ctrl-c-and-ctrl-break-signals.md +++ b/docs/ctrl-c-and-ctrl-break-signals.md @@ -17,7 +17,6 @@ ms.assetid: 5357ed99-920b-47a0-a922-d5faed7bf23e # CTRL+C and CTRL+BREAK Signals - The CTRL+C and CTRL+BREAK key combinations receive special handling by console processes. By default, when a console window has the keyboard focus, CTRL+C or CTRL+BREAK is treated as a signal (SIGINT or SIGBREAK) and not as keyboard input. By default, these signals are passed to all console processes that are attached to the console. (Detached processes are not affected. See [**Creation of a Console**](creation-of-a-console.md).) The system creates a new thread in each client process to handle the event. The thread raises an exception if the process is being debugged. The debugger can handle the exception or continue with the exception unhandled. CTRL+BREAK is always treated as a signal, but an application can change the default CTRL+C behavior in two ways that prevent the handler functions from being called: diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index 7768c75..7460852 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -37,8 +37,7 @@ api_type: Sets the character attributes for a specified number of character cells, beginning at the specified coordinates in a screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI FillConsoleOutputAttribute( @@ -50,14 +49,13 @@ BOOL WINAPI FillConsoleOutputAttribute( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). *wAttribute* \[in\] -The attributes to use when writing to the console screen buffer. For more information, see [Character Attributes](console-screen-buffers.md#_win32_font_attributes). +The attributes to use when writing to the console screen buffer. For more information, see [Character Attributes](console-screen-buffers.md#character-attributes). *nLength* \[in\] The number of character cells to be set to the specified color attributes. @@ -68,59 +66,29 @@ A [**COORD**](coord-str.md) structure that specifies the character coordinates o *lpNumberOfAttrsWritten* \[out\] A pointer to a variable that receives the number of character cells whose attributes were actually set. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of character cells whose attributes are to be set extends beyond the end of the specified row in the console screen buffer, the cells of the next row are set. If the number of cells to write to extends beyond the end of the console screen buffer, the cells are written up to the end of the console screen buffer. The character values at the positions written to are not changed. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/fillconsoleoutputcharacter.md b/docs/fillconsoleoutputcharacter.md index b61429f..16a5b09 100644 --- a/docs/fillconsoleoutputcharacter.md +++ b/docs/fillconsoleoutputcharacter.md @@ -45,8 +45,7 @@ api_type: Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates. -Syntax ------- +## Syntax ```C BOOL WINAPI FillConsoleOutputCharacter( @@ -58,8 +57,7 @@ BOOL WINAPI FillConsoleOutputCharacter( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -76,68 +74,32 @@ A [**COORD**](coord-str.md) structure that specifies the character coordinates o *lpNumberOfCharsWritten* \[out\] A pointer to a variable that receives the number of characters actually written to the console screen buffer. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of characters to write to extends beyond the end of the specified row in the console screen buffer, characters are written to the next row. If the number of characters to write to extends beyond the end of the console screen buffer, the characters are written up to the end of the console screen buffer. The attribute values at the positions written are not changed. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

FillConsoleOutputCharacterW (Unicode) and FillConsoleOutputCharacterA (ANSI)

- -## See also +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **FillConsoleOutputCharacterW** (Unicode) and **FillConsoleOutputCharacterA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/flushconsoleinputbuffer.md b/docs/flushconsoleinputbuffer.md index 8471ca7..14ba31d 100644 --- a/docs/flushconsoleinputbuffer.md +++ b/docs/flushconsoleinputbuffer.md @@ -34,8 +34,7 @@ api_type: Flushes the console input buffer. All input records currently in the input buffer are discarded. -Syntax ------- +## Syntax ```C BOOL WINAPI FlushConsoleInputBuffer( @@ -43,59 +42,28 @@ BOOL WINAPI FlushConsoleInputBuffer( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/focus-event-record-str.md b/docs/focus-event-record-str.md index 33a24f0..5158d29 100644 --- a/docs/focus-event-record-str.md +++ b/docs/focus-event-record-str.md @@ -26,18 +26,16 @@ topic_type: api_name: - FOCUS_EVENT_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- # FOCUS\_EVENT\_RECORD structure - Describes a focus event in a console [**INPUT\_RECORD**](input-record-str.md) structure. These events are used internally and should be ignored. -Syntax ------- +## Syntax ```C typedef struct _FOCUS_EVENT_RECORD { @@ -45,37 +43,19 @@ typedef struct _FOCUS_EVENT_RECORD { } FOCUS_EVENT_RECORD; ``` -Members -------- +## Members **bSetFocus** Reserved. -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
+## Requirements -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**INPUT\_RECORD**](input-record-str.md) diff --git a/docs/freeconsole.md b/docs/freeconsole.md index 2a549b9..9ec71f5 100644 --- a/docs/freeconsole.md +++ b/docs/freeconsole.md @@ -33,75 +33,41 @@ api_type: # FreeConsole function - Detaches the calling process from its console. -Syntax ------- +## Syntax ```C BOOL WINAPI FreeConsole(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A process can be attached to at most one console. If the calling process is not already attached to a console, the error code returned is **ERROR\_INVALID\_PARAMETER** (87). A process can use the **FreeConsole** function to detach itself from its console. If other processes share the console, the console is not destroyed, but the process that called **FreeConsole** cannot refer to it. A console is closed when the last process attached to it terminates or calls **FreeConsole**. After a process calls **FreeConsole**, it can call the [**AllocConsole**](allocconsole.md) function to create a new console or [**AttachConsole**](attachconsole.md) to attach to another console. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [**AllocConsole**](allocconsole.md) diff --git a/docs/generateconsolectrlevent.md b/docs/generateconsolectrlevent.md index b5a0d11..3e4de9a 100644 --- a/docs/generateconsolectrlevent.md +++ b/docs/generateconsolectrlevent.md @@ -33,11 +33,9 @@ api_type: # GenerateConsoleCtrlEvent function - Sends a specified signal to a console process group that shares the console associated with the calling process. -Syntax ------- +## Syntax ```C BOOL WINAPI GenerateConsoleCtrlEvent( @@ -46,100 +44,44 @@ BOOL WINAPI GenerateConsoleCtrlEvent( ); ``` -Parameters ----------- +## Parameters *dwCtrlEvent* \[in\] The type of signal to be generated. This parameter can be one of the following values. - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
-CTRL_C_EVENT -0

Generates a CTRL+C signal. This signal cannot be generated for process groups. If dwProcessGroupId is nonzero, this function will succeed, but the CTRL+C signal will not be received by processes within the specified process group.

-CTRL_BREAK_EVENT -1

Generates a CTRL+BREAK signal.

- -  +| Value | Meaning | +|-|-| +| **CTRL_C_EVENT** 0 | Generates a CTRL+C signal. This signal cannot be generated for process groups. If *dwProcessGroupId* is nonzero, this function will succeed, but the CTRL+C signal will not be received by processes within the specified process group. | +| **CTRL_BREAK_EVENT** 1 | Generates a CTRL+BREAK signal. | *dwProcessGroupId* \[in\] The identifier of the process group to receive the signal. A process group is created when the **CREATE\_NEW\_PROCESS\_GROUP** flag is specified in a call to the [**CreateProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682425) function. The process identifier of the new process is also the process group identifier of a new process group. The process group includes all processes that are descendants of the root process. Only those processes in the group that share the same console as the calling process receive the signal. In other words, if a process in the group creates a new console, that process does not receive the signal, nor do its descendants. If this parameter is zero, the signal is generated in all processes that share the console of the calling process. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **GenerateConsoleCtrlEvent** causes the control handler functions of processes in the target group to be called. All console processes have a default handler function that calls the [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) function. A console process can use the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function to install or remove other handler functions. [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) can also enable an inheritable attribute that causes the calling process to ignore CTRL+C signals. If **GenerateConsoleCtrlEvent** sends a CTRL+C signal to a process for which this attribute is enabled, the handler functions for that process are not called. CTRL+BREAK signals always cause the handler functions to be called. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Control Handlers](console-control-handlers.md) diff --git a/docs/getconsolealias.md b/docs/getconsolealias.md index 3cba579..0bebd4a 100644 --- a/docs/getconsolealias.md +++ b/docs/getconsolealias.md @@ -41,8 +41,7 @@ api_type: Retrieves the text for the specified console alias and executable. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleAlias( @@ -53,8 +52,7 @@ DWORD WINAPI GetConsoleAlias( ); ``` -Parameters ----------- +## Parameters *lpSource* \[in\] The console alias whose text is to be retrieved. @@ -68,64 +66,28 @@ The size of the buffer pointed to by *lpTargetBuffer*, in bytes. *lpExeName* \[in\] The name of the executable file. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleAliasW (Unicode) and GetConsoleAliasA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleAliasW** (Unicode) and **GetConsoleAliasA** (ANSI) | + +## See also [Console Aliases](console-aliases.md) diff --git a/docs/getconsolealiases.md b/docs/getconsolealiases.md index 8be5dfc..7e6102f 100644 --- a/docs/getconsolealiases.md +++ b/docs/getconsolealiases.md @@ -41,8 +41,7 @@ api_type: Retrieves all defined console aliases for the specified executable. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleAliases( @@ -52,8 +51,7 @@ DWORD WINAPI GetConsoleAliases( ); ``` -Parameters ----------- +## Parameters *lpAliasBuffer* \[out\] A pointer to a buffer that receives the aliases. @@ -66,66 +64,30 @@ The size of the buffer pointed to by *lpAliasBuffer*, in bytes. *lpExeName* \[in\] The executable file whose aliases are to be retrieved. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To determine the required size for the *lpExeName* buffer, use the [**GetConsoleAliasesLength**](getconsolealiaseslength.md) function. To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleAliasesW (Unicode) and GetConsoleAliasesA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleAliasesW** (Unicode) and **GetConsoleAliasesA** (ANSI) | + +## See also [**AddConsoleAlias**](addconsolealias.md) diff --git a/docs/getconsolealiaseslength.md b/docs/getconsolealiaseslength.md index 857477d..5026814 100644 --- a/docs/getconsolealiaseslength.md +++ b/docs/getconsolealiaseslength.md @@ -41,8 +41,7 @@ api_type: Retrieves the required size for the buffer used by the [**GetConsoleAliases**](getconsolealiases.md) function. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleAliasesLength( @@ -50,68 +49,31 @@ DWORD WINAPI GetConsoleAliasesLength( ); ``` -Parameters ----------- +## Parameters *lpExeName* \[in\] The name of the executable file whose console aliases are to be retrieved. -Return value ------------- +## Return value The size of the buffer required to store all console aliases defined for this executable file, in bytes. -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleAliasesLengthW (Unicode) and GetConsoleAliasesLengthA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleAliasesLengthW** (Unicode) and **GetConsoleAliasesLengthA** (ANSI) | + +## See also [**AddConsoleAlias**](addconsolealias.md) diff --git a/docs/getconsolealiasexes.md b/docs/getconsolealiasexes.md index fe56eee..a0087d3 100644 --- a/docs/getconsolealiasexes.md +++ b/docs/getconsolealiasexes.md @@ -41,8 +41,7 @@ api_type: Retrieves the names of all executable files with console aliases defined. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleAliasExes( @@ -51,8 +50,7 @@ DWORD WINAPI GetConsoleAliasExes( ); ``` -Parameters ----------- +## Parameters *lpExeNameBuffer* \[out\] A pointer to a buffer that receives the names of the executable files. @@ -60,66 +58,30 @@ A pointer to a buffer that receives the names of the executable files. *ExeNameBufferLength* \[in\] The size of the buffer pointed to by *lpExeNameBuffer*, in bytes. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To determine the required size for the *lpExeNameBuffer* buffer, use the [**GetConsoleAliasExesLength**](getconsolealiasexeslength.md) function. To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleAliasExesW (Unicode) and GetConsoleAliasExesA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleAliasExesW** (Unicode) and **GetConsoleAliasExesA** (ANSI) | + +## See also [**AddConsoleAlias**](addconsolealias.md) diff --git a/docs/getconsolealiasexeslength.md b/docs/getconsolealiasexeslength.md index 45d1b89..0bef58e 100644 --- a/docs/getconsolealiasexeslength.md +++ b/docs/getconsolealiasexeslength.md @@ -41,74 +41,36 @@ api_type: Retrieves the required size for the buffer used by the [**GetConsoleAliasExes**](getconsolealiasexes.md) function. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleAliasExesLength(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value The size of the buffer required to store the names of all executable files that have console aliases defined, in bytes. -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleAliasExesLengthW (Unicode) and GetConsoleAliasExesLengthA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleAliasExesLengthW** (Unicode) and **GetConsoleAliasExesLengthA** (ANSI) | + +## See also [**AddConsoleAlias**](addconsolealias.md) diff --git a/docs/getconsolecp.md b/docs/getconsolecp.md index 69ea158..16dfdfb 100644 --- a/docs/getconsolecp.md +++ b/docs/getconsolecp.md @@ -34,75 +34,41 @@ api_type: # GetConsoleCP function - Retrieves the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value. -Syntax ------- +## Syntax ```C UINT WINAPI GetConsoleCP(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value The return value is a code that identifies the code page. For a list of identifiers, see [Code Page Identifiers](https://msdn.microsoft.com/library/windows/desktop/dd317756). If the return value is zero, the function has failed. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. To retrieve more information about a code page, including it's name, see the [**GetCPInfoEx**](https://msdn.microsoft.com/library/windows/desktop/dd318081) function. To set a console's input code page, use the [**SetConsoleCP**](setconsolecp.md) function. To set and query a console's output code page, use the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**GetConsoleOutputCP**](getconsoleoutputcp.md) functions. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Code Pages](console-code-pages.md) diff --git a/docs/getconsolecursorinfo.md b/docs/getconsolecursorinfo.md index 60b40fe..f5ad55a 100644 --- a/docs/getconsolecursorinfo.md +++ b/docs/getconsolecursorinfo.md @@ -37,8 +37,7 @@ api_type: Retrieves information about the size and visibility of the cursor for the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleCursorInfo( @@ -47,8 +46,7 @@ BOOL WINAPI GetConsoleCursorInfo( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,53 +54,23 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *lpConsoleCursorInfo* \[out\] A pointer to a [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) structure that receives information about the console's cursor. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsoledisplaymode.md b/docs/getconsoledisplaymode.md index c1c6d9a..10dc5b7 100644 --- a/docs/getconsoledisplaymode.md +++ b/docs/getconsoledisplaymode.md @@ -34,8 +34,7 @@ api_type: Retrieves the display mode of the current console. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleDisplayMode( @@ -43,93 +42,40 @@ BOOL WINAPI GetConsoleDisplayMode( ); ``` -Parameters ----------- +## Parameters *lpModeFlags* \[out\] The display mode of the console. This parameter can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
-CONSOLE_FULLSCREEN -1

Full-screen console. The console is in this mode as soon as the window is maximized. At this point, the transition to full-screen mode can still fail.

-CONSOLE_FULLSCREEN_HARDWARE -2

Full-screen console communicating directly with the video hardware. This mode is set after the console is in CONSOLE_FULLSCREEN mode to indicate that the transition to full-screen mode has completed.

- -  - -Return value ------------- +| Value | Meaning | +|-|-| +| **CONSOLE_FULLSCREEN** 1 | Full-screen console. The console is in this mode as soon as the window is maximized. At this point, the transition to full-screen mode can still fail. | +| **CONSOLE_FULLSCREEN_HARDWARE** 2 | Full-screen console communicating directly with the video hardware. This mode is set after the console is in **CONSOLE_FULLSCREEN** mode to indicate that the transition to full-screen mode has completed. | + +> [!NOTE] +> The transition to a 100% full screen video hardware mode was removed in Windows Vista (TODO: citation needed) with the replatforming of the graphics stack to WDDM (TODO: insert link). On later versions of Windows, the maximum resulting state is **CONSOLE_FULLSCREEN** representing a frameless window that appears full screen but isn't in exclusive control of the hardware. + +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsolefontsize.md b/docs/getconsolefontsize.md index 67dfbf8..bb61f39 100644 --- a/docs/getconsolefontsize.md +++ b/docs/getconsolefontsize.md @@ -34,8 +34,7 @@ api_type: Retrieves the size of the font used by the specified console screen buffer. -Syntax ------- +## Syntax ```C COORD WINAPI GetConsoleFontSize( @@ -44,8 +43,7 @@ COORD WINAPI GetConsoleFontSize( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -53,8 +51,7 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *nFont* \[in\] The index of the font whose size is to be retrieved. This index is obtained by calling the [**GetCurrentConsoleFont**](getcurrentconsolefont.md) function. -Return value ------------- +## Return value If the function succeeds, the return value is a [**COORD**](coord-str.md) structure that contains the width and height of each character in the font, in logical units. The **X** member contains the width, while the **Y** member contains the height. @@ -62,46 +59,17 @@ If the function fails, the width and the height are zero. To get extended error To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsolehistoryinfo.md b/docs/getconsolehistoryinfo.md index 6a72357..cdeb0db 100644 --- a/docs/getconsolehistoryinfo.md +++ b/docs/getconsolehistoryinfo.md @@ -33,8 +33,7 @@ api_type: Retrieves the history settings for the calling process's console. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleHistoryInfo( @@ -42,64 +41,32 @@ BOOL WINAPI GetConsoleHistoryInfo( ); ``` -Parameters ----------- +## Parameters *lpConsoleHistoryInfo* \[out\] A pointer to a [**CONSOLE\_HISTORY\_INFO**](console-history-info.md) structure that receives the history settings for the calling process's console. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the calling process is not a console process, the function fails and sets the last error to **ERROR\_ACCESS\_DENIED**. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsolemode.md b/docs/getconsolemode.md index 920613e..cbf6b67 100644 --- a/docs/getconsolemode.md +++ b/docs/getconsolemode.md @@ -34,11 +34,9 @@ api_type: # GetConsoleMode function - Retrieves the current input mode of a console's input buffer or the current output mode of a console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleMode( @@ -47,8 +45,7 @@ BOOL WINAPI GetConsoleMode( ); ``` -Parameters ----------- +## Parameters *hConsoleHandle* \[in\] A handle to the console input buffer or the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,213 +53,35 @@ A handle to the console input buffer or the console screen buffer. The handle mu *lpMode* \[out\] A pointer to a variable that receives the current mode of the specified buffer. -If the *hConsoleHandle* parameter is an input handle, the mode can be one or more of the following values. When a console is created, all input modes except **ENABLE\_WINDOW\_INPUT** are enabled by default. - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-ENABLE_ECHO_INPUT -0x0004

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_INSERT_MODE -0x0020

When enabled, text entered in a console window will be inserted at the current cursor location and all text following that location will not be overwritten. When disabled, all following text will be overwritten.

-ENABLE_LINE_INPUT -0x0002

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_MOUSE_INPUT -0x0010

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.

-ENABLE_PROCESSED_INPUT -0x0001

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 line feed characters are handled by the system.

-ENABLE_QUICK_EDIT_MODE -0x0040

This flag enables the user to use the mouse to select and edit text.

-

To enable this mode, use ENABLE_QUICK_EDIT_MODE | ENABLE_EXTENDED_FLAGS. To disable this mode, use ENABLE_EXTENDED_FLAGS without this flag.

-ENABLE_WINDOW_INPUT -0x0008

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_VIRTUAL_TERMINAL_INPUT -0x0200

Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into Console Virtual Terminal Sequences that can be retrieved by a supporting application through WriteFile or WriteConsole functions.

-

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences.

- -  - -If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one or more of the following values. When a screen buffer is created, both output modes are enabled by default. - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-ENABLE_PROCESSED_OUTPUT -0x0001

Characters written by the WriteFile or WriteConsole function or echoed by the ReadFile or ReadConsole function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and line feed characters are processed.

-ENABLE_WRAP_AT_EOL_OUTPUT -0x0002

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 console screen buffer to scroll up (discarding the top row of the console screen buffer) when the cursor advances beyond the last row in the console screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.

-ENABLE_VIRTUAL_TERMINAL_PROCESSING -0x0004

When writing with WriteFile or WriteConsole, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see Console Virtual Terminal Sequences.

-DISABLE_NEWLINE_AUTO_RETURN -0x0008

When writing with WriteFile or WriteConsole, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

-

Normally when ENABLE_WRAP_AT_EOL_OUTPUT is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if ENABLE_WRAP_AT_EOL_OUTPUT was off, but the next printable character will be printed as if ENABLE_WRAP_AT_EOL_OUTPUT is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

-

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior.

-ENABLE_LVB_GRID_WORLDWIDE -0x0010

The APIs for writing character attributes including WriteConsoleOutput and WriteConsoleOutputAttribute allow the usage of flags from character attributes to adjust the color of the foreground and background of text. Additionally, a range of DBCS flags was specified with the COMMON_LVB prefix. Historically, these flags only functioned in DBCS code pages for Chinese, Japanese, and Korean languages.

-

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (swap foreground and background colors) can be useful for other languages to emphasize portions of output.

-

Setting this console mode flag will allow these attributes to be used in every code page on every language.

-

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

-

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via Console Virtual Terminal Sequences.

+[!INCLUDE [console-mode-flags](./includes/console-mode-flags.md)] -  - -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -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 or 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**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a function defined by the application. +## Remarks -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**](readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md). - -The **ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT** modes only affect processes using [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md). +[!INCLUDE [console-mode-remarks](./includes/console-mode-remarks.md)] To change a console's I/O modes, call [**SetConsoleMode**](setconsolemode.md) function. -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
+## Requirements -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsoleoriginaltitle.md b/docs/getconsoleoriginaltitle.md index eb4d3cd..b29bf4b 100644 --- a/docs/getconsoleoriginaltitle.md +++ b/docs/getconsoleoriginaltitle.md @@ -41,8 +41,7 @@ api_type: Retrieves the original title for the current console window. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleOriginalTitle( @@ -51,8 +50,7 @@ DWORD WINAPI GetConsoleOriginalTitle( ); ``` -Parameters ----------- +## Parameters *lpConsoleTitle* \[out\] A pointer to a buffer that receives a null-terminated string containing the original title. @@ -60,8 +58,7 @@ A pointer to a buffer that receives a null-terminated string containing the orig *nSize* \[in\] The size of the *lpConsoleTitle* buffer, in characters. -Return value ------------- +## Return value If the function succeeds, the return value is the length of the string copied to the buffer, in characters. @@ -69,59 +66,24 @@ If the buffer is not large enough to store the title, the return value is zero a If the function fails, the return value is zero and [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360) returns the error code. -Remarks -------- +## Remarks To set the title for a console window, use the [**SetConsoleTitle**](setconsoletitle.md) function. To retrieve the current title string, use the [**GetConsoleTitle**](getconsoletitle.md) function. To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0600 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleOriginalTitleW (Unicode) and GetConsoleOriginalTitleA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleOriginalTitleW** (Unicode) and **GetConsoleOriginalTitleA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsoleoutputcp.md b/docs/getconsoleoutputcp.md index cdec567..76bcc5e 100644 --- a/docs/getconsoleoutputcp.md +++ b/docs/getconsoleoutputcp.md @@ -36,71 +36,39 @@ api_type: Retrieves the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. -Syntax ------- +## Syntax ```C UINT WINAPI GetConsoleOutputCP(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value The return value is a code that identifies the code page. For a list of identifiers, see [Code Page Identifiers](https://msdn.microsoft.com/library/windows/desktop/dd317756). If the return value is zero, the function has failed. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. To retrieve more information about a code page, including it's name, see the [**GetCPInfoEx**](https://msdn.microsoft.com/library/windows/desktop/dd318081) function. To set a console's output code page, use the [**SetConsoleOutputCP**](setconsoleoutputcp.md) function. To set and query a console's input code page, use the [**SetConsoleCP**](setconsolecp.md) and [**GetConsoleCP**](getconsolecp.md) functions. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Code Pages](console-code-pages.md) diff --git a/docs/getconsoleprocesslist.md b/docs/getconsoleprocesslist.md index fee01b3..8981b24 100644 --- a/docs/getconsoleprocesslist.md +++ b/docs/getconsoleprocesslist.md @@ -32,8 +32,7 @@ api_type: Retrieves a list of the processes attached to the current console. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleProcessList( @@ -42,8 +41,7 @@ DWORD WINAPI GetConsoleProcessList( ); ``` -Parameters ----------- +## Parameters *lpdwProcessList* \[out\] A pointer to a buffer that receives an array of process identifiers upon success. This must be a valid buffer and cannot be `NULL`. The buffer must have space to receive at least 1 returned process id. @@ -51,8 +49,7 @@ A pointer to a buffer that receives an array of process identifiers upon success *dwProcessCount* \[in\] The maximum number of process identifiers that can be stored in the *lpdwProcessList* buffer. This must be greater than 0. -Return value ------------- +## Return value If the function succeeds, the return value is less than or equal to *dwProcessCount* and represents the number of process identifiers stored in the *lpdwProcessList* buffer. @@ -62,51 +59,21 @@ If the return value is zero, the function has failed, because every console has If a `NULL` process list was provided or the process count was 0, the call will return 0 and `GetLastError` will return `ERROR_INVALID_PARAMETER`. Please provide a buffer of at least one element to call this function. Allocate a larger buffer and call again if the return code is larger than the length of the provided buffer. -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [**AttachConsole**](attachconsole.md) diff --git a/docs/getconsolescreenbufferinfo.md b/docs/getconsolescreenbufferinfo.md index cd2f60b..612bc0c 100644 --- a/docs/getconsolescreenbufferinfo.md +++ b/docs/getconsolescreenbufferinfo.md @@ -27,8 +27,7 @@ api_type: Retrieves information about the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleScreenBufferInfo( @@ -37,8 +36,7 @@ BOOL WINAPI GetConsoleScreenBufferInfo( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -46,65 +44,33 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *lpConsoleScreenBufferInfo* \[out\] A pointer to a [**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) structure that receives the console screen buffer information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The rectangle returned in the **srWindow** member of the [**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) structure can be modified and then passed to the [**SetConsoleWindowInfo**](setconsolewindowinfo.md) function to scroll the console screen buffer in the window, to change the size of the window, or both. All coordinates returned in the [**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the console screen buffer. -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsolescreenbufferinfoex.md b/docs/getconsolescreenbufferinfoex.md index 7e1c5e4..05db9a8 100644 --- a/docs/getconsolescreenbufferinfoex.md +++ b/docs/getconsolescreenbufferinfoex.md @@ -36,8 +36,7 @@ api_type: Retrieves extended information about the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleScreenBufferInfoEx( @@ -46,8 +45,7 @@ BOOL WINAPI GetConsoleScreenBufferInfoEx( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -55,60 +53,29 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *lpConsoleScreenBufferInfoEx* \[out\] A [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) structure that receives the requested console screen buffer information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The rectangle returned in the **srWindow** member of the [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) structure can be modified and then passed to the [**SetConsoleWindowInfo**](setconsolewindowinfo.md) function to scroll the console screen buffer in the window, to change the size of the window, or both. All coordinates returned in the [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the console screen buffer. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsoleselectioninfo.md b/docs/getconsoleselectioninfo.md index d0dfacb..2941be3 100644 --- a/docs/getconsoleselectioninfo.md +++ b/docs/getconsoleselectioninfo.md @@ -34,8 +34,7 @@ api_type: Retrieves information about the current console selection. -Syntax ------- +## Syntax ```C BOOL WINAPI GetConsoleSelectionInfo( @@ -43,64 +42,32 @@ BOOL WINAPI GetConsoleSelectionInfo( ); ``` -Parameters ----------- +## Parameters *lpConsoleSelectionInfo* \[out\] A pointer to a [**CONSOLE\_SELECTION\_INFO**](console-selection-info-str.md) structure that receives the selection information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsoletitle.md b/docs/getconsoletitle.md index 90c6e45..a6b98eb 100644 --- a/docs/getconsoletitle.md +++ b/docs/getconsoletitle.md @@ -47,8 +47,7 @@ api_type: Retrieves the title for the current console window. -Syntax ------- +## Syntax ```C DWORD WINAPI GetConsoleTitle( @@ -57,8 +56,7 @@ DWORD WINAPI GetConsoleTitle( ); ``` -Parameters ----------- +## Parameters *lpConsoleTitle* \[out\] A pointer to a buffer that receives a null-terminated string containing the title. If the buffer is too small to store the title, the function stores as many characters of the title as will fit in the buffer, ending with a null terminator. @@ -66,71 +64,34 @@ A pointer to a buffer that receives a null-terminated string containing the titl *nSize* \[in\] The size of the buffer pointed to by the *lpConsoleTitle* parameter, in characters. -Return value ------------- +## Return value If the function succeeds, the return value is the length of the console window's title, in characters. If the function fails, the return value is zero and [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360) returns the error code. -Remarks -------- +## Remarks To set the title for a console window, use the [**SetConsoleTitle**](setconsoletitle.md) function. To retrieve the original title string, use the [**GetConsoleOriginalTitle**](getconsoleoriginaltitle.md) function. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] -Examples --------- +## Examples For an example, see [**SetConsoleTitle**](setconsoletitle.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetConsoleTitleW (Unicode) and GetConsoleTitleA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **GetConsoleTitleW** (Unicode) and **GetConsoleTitleA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getconsolewindow.md b/docs/getconsolewindow.md index 9fb55b7..e68e4bc 100644 --- a/docs/getconsolewindow.md +++ b/docs/getconsolewindow.md @@ -42,67 +42,36 @@ api_type: Retrieves the window handle used by the console associated with the calling process. -Syntax ------- +## Syntax ```C HWND WINAPI GetConsoleWindow(void); ``` -Parameters ----------- +## Parameters This function has no parameters. -Return value ------------- +## Return value The return value is a handle to the window used by the console associated with the calling process or **NULL** if there is no such associated console. -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
+## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | -## See also + +## See also [Console Functions](console-functions.md) diff --git a/docs/getcurrentconsolefont.md b/docs/getcurrentconsolefont.md index 9101110..9af4b9a 100644 --- a/docs/getcurrentconsolefont.md +++ b/docs/getcurrentconsolefont.md @@ -34,8 +34,7 @@ api_type: Retrieves information about the current console font. -Syntax ------- +## Syntax ```C BOOL WINAPI GetCurrentConsoleFont( @@ -45,8 +44,7 @@ BOOL WINAPI GetCurrentConsoleFont( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -57,57 +55,27 @@ If this parameter is **TRUE**, font information is retrieved for the maximum win *lpConsoleCurrentFont* \[out\] A pointer to a [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) structure that receives the requested font information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getcurrentconsolefontex.md b/docs/getcurrentconsolefontex.md index 9c911f6..eebc40e 100644 --- a/docs/getcurrentconsolefontex.md +++ b/docs/getcurrentconsolefontex.md @@ -33,8 +33,7 @@ api_type: Retrieves extended information about the current console font. -Syntax ------- +## Syntax ```C BOOL WINAPI GetCurrentConsoleFontEx( @@ -44,8 +43,7 @@ BOOL WINAPI GetCurrentConsoleFontEx( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,53 +54,23 @@ If this parameter is **TRUE**, font information is retrieved for the maximum win *lpConsoleCurrentFontEx* \[out\] A pointer to a [**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) structure that receives the requested font information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getlargestconsolewindowsize.md b/docs/getlargestconsolewindowsize.md index db52d9c..a020d4b 100644 --- a/docs/getlargestconsolewindowsize.md +++ b/docs/getlargestconsolewindowsize.md @@ -37,8 +37,7 @@ api_type: Retrieves the size of the largest possible console window, based on the current font and the size of the display. -Syntax ------- +## Syntax ```C COORD WINAPI GetLargestConsoleWindowSize( @@ -46,64 +45,32 @@ COORD WINAPI GetLargestConsoleWindowSize( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. -Return value ------------- +## Return value If the function succeeds, the return value is a [**COORD**](coord-str.md) structure that specifies the number of character cell columns (**X** member) and rows (**Y** member) in the largest possible console window. Otherwise, the members of the structure are zero. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The function does not take into consideration the size of the console screen buffer, which means that the window size returned may be larger than the size of the console screen buffer. The [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function can be used to determine the maximum size of the console window, given the current screen buffer size, the current font, and the display size. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getnumberofconsoleinputevents.md b/docs/getnumberofconsoleinputevents.md index 5a1fd99..b192e86 100644 --- a/docs/getnumberofconsoleinputevents.md +++ b/docs/getnumberofconsoleinputevents.md @@ -38,8 +38,7 @@ api_type: Retrieves the number of unread input records in the console's input buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI GetNumberOfConsoleInputEvents( @@ -48,8 +47,7 @@ BOOL WINAPI GetNumberOfConsoleInputEvents( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -57,15 +55,13 @@ A handle to the console input buffer. The handle must have the **GENERIC\_READ** *lpcNumberOfEvents* \[out\] A pointer to a variable that receives the number of unread input records in the console's input buffer. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The **GetNumberOfConsoleInputEvents** function reports the total number of unread input records in the input buffer, including keyboard, mouse, and window-resizing input records. Processes using the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) function can only read keyboard input. Processes using the [**ReadConsoleInput**](readconsoleinput.md) function can read all types of input records. @@ -73,46 +69,17 @@ A process can specify a console input buffer handle in one of the [wait function To read input records from a console input buffer without affecting the number of unread records, use the [**PeekConsoleInput**](peekconsoleinput.md) function. To discard all unread records in a console's input buffer, use the [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) function. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getnumberofconsolemousebuttons.md b/docs/getnumberofconsolemousebuttons.md index e93e0d1..384d8c8 100644 --- a/docs/getnumberofconsolemousebuttons.md +++ b/docs/getnumberofconsolemousebuttons.md @@ -34,8 +34,7 @@ api_type: Retrieves the number of buttons on the mouse used by the current console. -Syntax ------- +## Syntax ```C BOOL WINAPI GetNumberOfConsoleMouseButtons( @@ -43,64 +42,32 @@ BOOL WINAPI GetNumberOfConsoleMouseButtons( ); ``` -Parameters ----------- +## Parameters *lpNumberOfMouseButtons* \[out\] A pointer to a variable that receives the number of mouse buttons. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks When a console receives mouse input, an [**INPUT\_RECORD**](input-record-str.md) structure containing a [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) structure is placed in the console's input buffer. The **dwButtonState** member of **MOUSE\_EVENT\_RECORD** has a bit indicating the state of each mouse button. The bit is 1 if the button is down and 0 if the button is up. To determine the number of bits that are significant, use **GetNumberOfConsoleMouseButtons**. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index e6af22b..bccabe0 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -37,8 +37,7 @@ api_type: Retrieves a handle to the specified standard device (standard input, standard output, or standard error). -Syntax ------- +## Syntax ```C HANDLE WINAPI GetStdHandle( @@ -46,47 +45,18 @@ HANDLE WINAPI GetStdHandle( ); ``` -Parameters ----------- +## Parameters *nStdHandle* \[in\] The standard device. This parameter can be one of the following values. - ---- - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-STD_INPUT_HANDLE -(DWORD) -10

The standard input device. Initially, this is the console input buffer, CONIN$.

-STD_OUTPUT_HANDLE -(DWORD) -11

The standard output device. Initially, this is the active console screen buffer, CONOUT$.

-STD_ERROR_HANDLE -(DWORD) -12

The standard error device. Initially, this is the active console screen buffer, CONOUT$.

- -Return value ------------- +| Value | Meaning | +|-|-| +| **STD_INPUT_HANDLE** (DWORD) -10 | The standard input device. Initially, this is the console input buffer, `CONIN$`. | +| **STD_OUTPUT_HANDLE** (DWORD) -11 | The standard output device. Initially, this is the active console screen buffer, `CONOUT$`. | +| **STD_ERROR_HANDLE** (DWORD) -12 | The standard error device. Initially, this is the active console screen buffer, `CONOUT$`. | + +## Return value If the function succeeds, the return value is a handle to the specified device, or a redirected handle set by a previous call to [**SetStdHandle**](setstdhandle.md). The handle has **GENERIC\_READ** and **GENERIC\_WRITE** access rights, unless the application has used **SetStdHandle** to set a standard handle with lesser access. @@ -94,68 +64,38 @@ If the function fails, the return value is **INVALID\_HANDLE\_VALUE**. To get ex If an application does not have associated standard handles, such as a service running on an interactive desktop, and has not redirected them, the return value is **NULL**. -Remarks -------- +## Remarks Handles returned by **GetStdHandle** can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle to the console's input buffer, and the standard output and standard error handles are handles of the console's active screen buffer. These handles can be used by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, the [**ReadConsoleInput**](readconsoleinput.md), [**WriteConsole**](writeconsole.md), or [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) functions). The standard handles of a process may be redirected by a call to [**SetStdHandle**](setstdhandle.md), in which case **GetStdHandle** returns the redirected handle. If the standard handles have been redirected, you can specify the `CONIN$` value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function to get a handle to a console's input buffer. Similarly, you can specify the `CONOUT$` value to get a handle to a console's active screen buffer. -### Attach/detach behavior +### Attach/detach behavior When attaching to a new console, standard handles are always replaced with console handles unless **STARTF\_USESTDHANDLES** was specified during process creation. If the existing value of the standard handle is **NULL**, or the existing value of the standard handle looks like a console pseudohandle, the handle is replaced with a console handle. -When a parent uses both **CREATE\_NEW\_CONSOLE** and **STARTF\_USESTDHANDLES** to create a console process, standard handles will not be replaced unless the existing value of the standard handle is NULL or a console pseudohandle. +When a parent uses both **CREATE\_NEW\_CONSOLE** and **STARTF\_USESTDHANDLES** to create a console process, standard handles will not be replaced unless the existing value of the standard handle is **NULL** or a console pseudohandle. -**NOTE:** Console processes *must* start with the standard handles filled or they will be filled automatically with appropriate handles to a new console. Graphical user interface (GUI) applications can be started without the standard handles and they will not be automatically filled. +> [!NOTE] +>Console processes *must* start with the standard handles filled or they will be filled automatically with appropriate handles to a new console. Graphical user interface (GUI) applications can be started without the standard handles and they will not be automatically filled. -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ProcessEnv.h (via Winbase.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ProcessEnv.h (via Winbase.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/handlerroutine.md b/docs/handlerroutine.md index cc176bb..1a99d38 100644 --- a/docs/handlerroutine.md +++ b/docs/handlerroutine.md @@ -23,7 +23,7 @@ topic_type: api_name: - HandlerRoutine api_location: -- Wincon.h +- WinCon.h api_type: - UserDefined --- @@ -34,8 +34,7 @@ An application-defined function used with the [**SetConsoleCtrlHandler**](setcon The **PHANDLER\_ROUTINE** type defines a pointer to this callback function. **HandlerRoutine** is a placeholder for the application-defined function name. -Syntax ------- +## Syntax ```C BOOL WINAPI HandlerRoutine( @@ -43,74 +42,24 @@ BOOL WINAPI HandlerRoutine( ); ``` -Parameters ----------- +## Parameters *dwCtrlType* \[in\] The type of control signal received by the handler. This parameter can be one of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-CTRL_C_EVENT -0

A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function.

-CTRL_BREAK_EVENT -1

A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent.

-CTRL_CLOSE_EVENT -2

A signal that the system sends to all processes attached to a console when the user closes the console (either by clicking Close on the console window's window menu, or by clicking the End Task button command from Task Manager).

-CTRL_LOGOFF_EVENT -5

A signal that the system sends to all console processes when a user is logging off. This signal does not indicate which user is logging off, so no assumptions can be made.

-

Note that this signal is received only by services. Interactive applications are terminated at logoff, so they are not present when the system sends this signal.

-CTRL_SHUTDOWN_EVENT -6

A signal that the system sends when the system is shutting down. Interactive applications are not present by the time the system sends this signal, therefore it can be received only be services in this situation. Services also have their own notification mechanism for shutdown events. For more information, see Handler.

-

This signal can also be generated by an application using GenerateConsoleCtrlEvent.

- -  - -Return value ------------- +| Value | Meaning | +|-|-| +| **CTRL_C_EVENT** 0 | A CTRL+C signal was received, either from keyboard input or from a signal generated by the **[GenerateConsoleCtrlEvent](generateconsolectrlevent.md)** function. | +| **CTRL_BREAK_EVENT** 1 | A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by **[GenerateConsoleCtrlEvent](generateconsolectrlevent.md)**. | +| **CTRL_CLOSE_EVENT** 2 | A signal that the system sends to all processes attached to a console when the user closes the console (either by clicking **Close** on the console window's window menu, or by clicking the **End Task** button command from Task Manager). | +| **CTRL_LOGOFF_EVENT** 5 | A signal that the system sends to all console processes when a user is logging off. This signal does not indicate which user is logging off, so no assumptions can be made.

Note that this signal is received only by services. Interactive applications are terminated at logoff, so they are not present when the system sends this signal. | +| **CTRL_SHUTDOWN_EVENT** 6 | A signal that the system sends when the system is shutting down. Interactive applications are not present by the time the system sends this signal, therefore it can be received only be services in this situation. Services also have their own notification mechanism for shutdown events. For more information, see **[Handler](https://msdn.microsoft.com/library/windows/desktop/ms683240)**.

This signal can also be generated by an application using **[GenerateConsoleCtrlEvent](generateconsolectrlevent.md)**. | + +## Return value If the function handles the control signal, it should return **TRUE**. If it returns **FALSE**, the next handler function in the list of handlers for this process is used. -Remarks -------- +## Remarks Because the system creates a new thread in the process to execute the handler function, it is possible that the handler function will be terminated by another thread in the process. Be sure to synchronize threads in the process with the thread for the handler function. @@ -142,32 +91,15 @@ Note that a third-party library or DLL can install a console control handler for _[1]: "quick" events are never used, but there's still code to support them._ -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +## See also [Console Control Handlers](console-control-handlers.md) diff --git a/docs/high-level-console-i-o.md b/docs/high-level-console-i-o.md index 61e86ec..9264094 100644 --- a/docs/high-level-console-i-o.md +++ b/docs/high-level-console-i-o.md @@ -17,12 +17,11 @@ ms.assetid: 6d191fee-87bb-4659-8056-910149e591f7 # High-Level Console I/O - The high-level I/O functions provide a simple way to read a stream of characters from console input or to write a stream of characters to console output. A high-level read operation gets input characters from a console's input buffer and stores them in a specified buffer. A high-level write operation takes characters from a specified buffer and writes them to a screen buffer at the current cursor location, advancing the cursor as each character is written. -High-level I/O gives you a choice between the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions and the [**ReadConsole**](readconsole.md) and [**WriteConsole**](writeconsole.md) functions. They are identical, except for two important differences. The console functions support the use of either Unicode characters or the ANSI character set; the file I/O functions do not support Unicode. Also, the file I/O functions can be used to access files, pipes, and serial communications devices; the console functions can only be used with console handles. This distinction is important if an application relies on standard handles that may have been redirected. +High-level I/O gives you a choice between the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions and the [**ReadConsole**](readconsole.md) and [**WriteConsole**](writeconsole.md) functions. They are identical, except for two important differences. The console functions support the use of either Unicode characters or the ANSI character set through the A and W variants of each function; the file I/O functions do not support Unicode except for UTF-8 set with the `CP_UTF8` constant on the **[SetConsoleCP](setconsolecp.md)** and **[SetConsoleOutputCP](setconsoleoutputcp.md)** functions prior to use. Also, the file I/O functions can be used to access files, pipes, and serial communications devices; the console functions can only be used with console handles. This distinction is important if an application relies on standard handles that may have been redirected. -When using either set of high-level functions, an application can control the text and background colors used to display characters subsequently written to a screen buffer. An application can also use the console modes that affect high-level console I/O to enable or disable the following properties: +When using either set of high-level functions, an application can control the text and background colors used to display characters subsequently written to a screen buffer with the preferred mechanism being via **[virtual terminal sequences](console-virtual-terminal-sequences.md)**. An application can also use the console modes that affect high-level console I/O to enable or disable the following properties: - Echoing of keyboard input to the active screen buffer - Line input, in which a read operation does not return until the ENTER key is pressed @@ -34,3 +33,4 @@ For more information, see the following topics: - [Console Modes](console-modes.md) - [High-Level Console Modes](high-level-console-modes.md) - [High-Level Console Input and Output Functions](high-level-console-input-and-output-functions.md) +- [Classic functions versus virtual terminal sequences](classic-vs-vt.md) diff --git a/docs/high-level-console-input-and-output-functions.md b/docs/high-level-console-input-and-output-functions.md index 6b4b181..78a7b71 100644 --- a/docs/high-level-console-input-and-output-functions.md +++ b/docs/high-level-console-input-and-output-functions.md @@ -17,17 +17,18 @@ ms.assetid: 086b1bec-85f8-4e31-848d-7cb2d2703a3d # High-Level Console Input and Output Functions - The [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) functions, or the [**ReadConsole**](readconsole.md) and [**WriteConsole**](writeconsole.md) functions, enable an application to read console input and write console output as a stream of characters. **ReadConsole** and **WriteConsole** behave exactly like **ReadFile** and **WriteFile** except that they can be used either as wide-character functions (in which text arguments must use Unicode) or as ANSI functions (in which text arguments must use characters from the Windows character set). Applications that need to maintain a single set of sources to support either Unicode or the ANSI character set should use **ReadConsole** and **WriteConsole**. [**ReadConsole**](readconsole.md) and [**WriteConsole**](writeconsole.md) can only be used with console handles; [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) can be used with other handles (such as files or pipes). **ReadConsole** and **WriteConsole** fail if used with a standard handle that has been redirected and is no longer a console handle. -To get keyboard input, a process can use [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) with a handle to the console's input buffer, or it can use **ReadFile** to read input from a file or a pipe if STDIN has been redirected. These functions only return keyboard events that can be translated into ANSI characters (or Unicode characters in the case of **ReadConsole**). The input that can be returned includes control key combinations. The functions do not return keyboard events involving the function keys or arrow keys. Input events generated by mouse, window, focus, or menu input are discarded. +To get keyboard input, a process can use [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) with a handle to the console's input buffer, or it can use **ReadFile** to read input from a file or a pipe if `STDIN` has been redirected. These functions only return keyboard events that can be translated into ANSI or Unicode characters. The input that can be returned includes control key combinations. The functions do not return keyboard events involving the function keys or arrow keys. Input events generated by mouse, window, focus, or menu input are discarded. If line input mode is enabled (the default mode), [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md) do not return to the calling application until the ENTER key is pressed. If line input mode is disabled, the functions do not return until at least one character is available. In either mode, all available characters are read until either no more keys are available or the specified number of characters has been read. Unread characters are buffered until the next read operation. The functions report the total number of characters actually read. If echo input mode is enabled, characters read by these functions are written to the active screen buffer at the current cursor position. A process can use [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or **WriteConsole** to write to either an active or inactive screen buffer, or it can use **WriteFile** to write to a file or a pipe if STDOUT has been redirected. Processed output mode and wrap at EOL output mode control the way characters are written or echoed to a screen buffer. -Characters written by [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md), or echoed by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md), are inserted in a screen buffer at the current cursor position. As each character is written, the cursor position advances to the next character cell; however, the behavior at the end of a row depends on the console screen buffer's wrap at EOL output mode. An application can use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the current cursor position and the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function to set the cursor position. +Characters written by [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md), or echoed by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md), are inserted in a screen buffer at the current cursor position. As each character is written, the cursor position advances to the next character cell; however, the behavior at the end of a row depends on the console screen buffer's wrap at EOL output mode. + +Further detail about the position of the cursor can be found through **[virtual terminals sequences](console-virtual-terminal-sequences.md)**, specifically in the **[query state](console-virtual-terminal-sequences#query-state)** category for finding the current position and the **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** category for setting the current position. Alternatively, an application can use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the current cursor position and the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function to set the cursor position. However, the **virtual terminal sequences** mechanism is preferred for all new and ongoing development. More details on the strategy behind this decision can be found in the **[classic functions versus virtual terminal](classic-vs-vt.md)** and **[ecosystem roadmap](ecosystem-roadmap.md)** documentation. For an example that uses the high-level console I/O functions, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). diff --git a/docs/high-level-console-modes.md b/docs/high-level-console-modes.md index 7432eb5..0de2e07 100644 --- a/docs/high-level-console-modes.md +++ b/docs/high-level-console-modes.md @@ -17,7 +17,6 @@ ms.assetid: 3ec915eb-333d-484d-a14d-46377b503ecc # High-Level Console Modes - The behavior of the high-level console functions is affected by the console input and output modes. All of the following console input modes are enabled for a console's input buffer when a console is created: - Line input mode @@ -33,44 +32,10 @@ All three input modes, along with processed output mode, are designed to work to An application can use the [**GetConsoleMode**](getconsolemode.md) function to determine the current mode of a console's input buffer or screen buffer. You can enable or disable any of these modes by using the following values in the [**SetConsoleMode**](setconsolemode.md) function. Note that setting the output mode of one screen buffer does not affect the output mode of other screen buffers. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModeDescription
ENABLE_PROCESSED_INPUTUsed with a console input handle to cause the system to process any system editing or control key input rather than returning it as input in the read operation's buffer. If line input is also enabled, backspaces and carriage returns are handled correctly. A backspace causes the cursor to move back one space without affecting the character at the cursor position. A carriage return is converted to carriage return – line feed character combination. If echo input mode is enabled and the output should reflect system editing, processed output must be enabled for the active screen buffer. If processed input is enabled, the CTRL+C key combination is passed on to the appropriate handler regardless of whether line input is enabled. For more information about control handlers, see Console Control Handlers.
ENABLE_LINE_INPUTUsed with a console input handle to cause the ReadFile and ReadConsole functions to return when the ENTER key is pressed. If line input mode is disabled, the functions return when one or more characters are available in the input buffer.
ENABLE_ECHO_INPUTUsed with a console input handle to cause keyboard input read by the ReadFile or ReadConsole function to be echoed to the active screen buffer. Characters are echoed only if the process that calls ReadFile or ReadConsole has an open handle to the active screen buffer. Echo mode cannot be enabled unless line input is also enabled. The output mode of the active screen buffer affects the way echoed input is displayed.
ENABLE_PROCESSED_OUTPUTUsed with a console screen buffer handle to cause the system to perform the appropriate action for ANSI control characters that are written to a screen buffer. The backspace, tab, bell, carriage return, and line feed characters are processed. A tab character moves the cursor to the next tab stop, which occurs every eight characters. A bell character sounds a short tone.
ENABLE_WRAP_AT_EOL_OUTPUTUsed with a console screen buffer handle to cause the current output position (cursor position) to move to the first column in the next row (line) when the end of the current row is reached. If the bottom of the window region is reached, the window origin is moved down one row. This movement has the effect of scrolling the contents of the window up one row. If the bottom of the console screen buffer is reached, the contents of the console screen buffer are scrolled up one row, and the top row of the console screen buffer is discarded. -

If this mode is disabled, the last character in the row is overwritten with any subsequent characters.

+| Mode | Description | +|-|-| +| **ENABLE_PROCESSED_INPUT** | Used with a console input handle to cause the system to process any system editing or control key input rather than returning it as input in the read operation's buffer. If line input is also enabled, backspaces and carriage returns are handled correctly. A backspace causes the cursor to move back one space without affecting the character at the cursor position. A carriage return is converted to carriage return – line feed character combination. If echo input mode is enabled and the output should reflect system editing, processed output must be enabled for the active screen buffer. If processed input is enabled, the CTRL+C key combination is passed on to the appropriate handler regardless of whether line input is enabled. For more information about control handlers, see [Console Control Handlers](console-control-handlers.md). | +| **ENABLE_LINE_INPUT** | Used with a console input handle to cause the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** and **[ReadConsole](readconsole.md)** functions to return when the ENTER key is pressed. If line input mode is disabled, the functions return when one or more characters are available in the input buffer. | +| **ENABLE_ECHO_INPUT** | Used with a console input handle to cause keyboard input read by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** and **[ReadConsole](readconsole.md)** function to be echoed to the active screen buffer. Characters are echoed only if the process that calls **ReadFile** or **ReadConsole** has an open handle to the active screen buffer. Echo mode cannot be enabled unless line input is also enabled. The output mode of the active screen buffer affects the way echoed input is displayed. | +| **ENABLE_PROCESSED_OUTPUT** | Used with a console screen buffer handle to cause the system to perform the appropriate action for ANSI control characters that are written to a screen buffer. The backspace, tab, bell, carriage return, and line feed characters are processed. A tab character moves the cursor to the next tab stop, which occurs every eight characters. A bell character sounds a short tone. | +| **ENABLE_WRAP_AT_EOL_OUTPUT** | Used with a console screen buffer handle to cause the current output position (cursor position) to move to the first column in the next row (line) when the end of the current row is reached. If the bottom of the window region is reached, the window origin is moved down one row. This movement has the effect of scrolling the contents of the window up one row. If the bottom of the console screen buffer is reached, the contents of the console screen buffer are scrolled up one row, and the top row of the console screen buffer is discarded.

If this mode is disabled, the last character in the row is overwritten with any subsequent characters. | diff --git a/docs/includes/console-mode-flags.md b/docs/includes/console-mode-flags.md new file mode 100644 index 0000000..dc636a4 --- /dev/null +++ b/docs/includes/console-mode-flags.md @@ -0,0 +1,22 @@ +If the *hConsoleHandle* parameter is an input handle, the mode can be one or more of the following values. When a console is created, all input modes except **ENABLE\_WINDOW\_INPUT** are enabled by default. + +| Value | Meaning | +|-|-| +| **ENABLE_ECHO_INPUT** 0x0004 | Characters read by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** 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_INSERT_MODE** 0x0020 | When enabled, text entered in a console window will be inserted at the current cursor location and all text following that location will not be overwritten. When disabled, all following text will be overwritten. | +| **ENABLE_LINE_INPUT** 0x0002 | The **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** 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_MOUSE_INPUT** 0x0010 | 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](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, even when this mode is enabled. | +| **ENABLE_PROCESSED_INPUT** 0x0001 | CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, 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 line feed characters are handled by the system. | +| **ENABLE_QUICK_EDIT_MODE** 0x0040 | This flag enables the user to use the mouse to select and edit text.

To enable this mode, use `ENABLE_QUICK_EDIT_MODE | ENABLE_EXTENDED_FLAGS`. To disable this mode, use **ENABLE_EXTENDED_FLAGS** without this flag. | +| **ENABLE_WINDOW_INPUT** 0x0008 | 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](readconsoleinput.md)** function, but not by those using **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**. | +| **ENABLE_VIRTUAL_TERMINAL_INPUT** 0x0200 | Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)** that can be retrieved by a supporting application through **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** functions.

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences. | + +If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one or more of the following values. When a screen buffer is created, both output modes are enabled by default. + +| Value | Meaning | +|-|-| +| **ENABLE_PROCESSED_OUTPUT** 0x0001 | Characters written by the **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** function or echoed by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and line feed characters are processed. | +| **ENABLE_WRAP_AT_EOL_OUTPUT** 0x0002 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** or echoing with **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, 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 console screen buffer to scroll up (discarding the top row of the console screen buffer) when the cursor advances beyond the last row in the console screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters. | +| **ENABLE_VIRTUAL_TERMINAL_PROCESSING** 0x0004 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)**, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)**. | +| **DISABLE_NEWLINE_AUTO_RETURN** 0x0008 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)**, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

Normally when **ENABLE_WRAP_AT_EOL_OUTPUT** is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if **ENABLE_WRAP_AT_EOL_OUTPUT** was off, but the next printable character will be printed as if **ENABLE_WRAP_AT_EOL_OUTPUT** is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

The typical usage of this flag is intended in conjunction with setting **ENABLE_VIRTUAL_TERMINAL_PROCESSING** to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior. | +| **ENABLE_LVB_GRID_WORLDWIDE** 0x0010 | The APIs for writing character attributes including **[WriteConsoleOutput](writeconsoleoutput.md)** and **[WriteConsoleOutputAttribute](writeconsoleoutputattribute.md)** allow the usage of flags from **[character attributes](console-screen-buffers.md#character-attributes)** to adjust the color of the foreground and background of text. Additionally, a range of DBCS flags was specified with the COMMON_LVB prefix. Historically, these flags only functioned in DBCS code pages for Chinese, Japanese, and Korean languages.

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (swap foreground and background colors) can be useful for other languages to emphasize portions of output.

Setting this console mode flag will allow these attributes to be used in every code page on every language.

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)**. | diff --git a/docs/includes/console-mode-remarks.md b/docs/includes/console-mode-remarks.md new file mode 100644 index 0000000..100750f --- /dev/null +++ b/docs/includes/console-mode-remarks.md @@ -0,0 +1,7 @@ +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 or 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**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a 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**](readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md). + +The **ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT** modes only affect processes using [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md). diff --git a/docs/includes/setting-codepage-mode-remarks.md b/docs/includes/setting-codepage-mode-remarks.md new file mode 100644 index 0000000..e196eb5 --- /dev/null +++ b/docs/includes/setting-codepage-mode-remarks.md @@ -0,0 +1 @@ +This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. Legacy consumers may also use the **chcp** or **mode con cp select=** commands, but it is not recommended for new development. \ No newline at end of file diff --git a/docs/input-and-output-methods.md b/docs/input-and-output-methods.md index d599a09..dba6e84 100644 --- a/docs/input-and-output-methods.md +++ b/docs/input-and-output-methods.md @@ -17,14 +17,19 @@ ms.assetid: 55a86d5d-d0b1-4d0c-b42f-7342809289ad # Input and Output Methods - There are two different approaches to console I/O, the choice of which depends on how much flexibility and control an application needs. The high-level approach enables simple character stream I/O, but it limits access to a console's input and screen buffers. The low-level approach requires that developers write more code and choose among a greater range of functions, but it also gives an application more flexibility. +> [!NOTE] +> The low-level approach is not recommended for new and ongoing development. Applications needing functionality from the low-level console I/O functions are encouraged to use **[virtual terminal sequences](console-virtual-terminal-sequences.md)** and explore our documentation on both **[classic functions versus virtual terminal](classic-vs-vt.md)** and **[the ecosystem roadmap](ecosystem-roadmap.md)**. + An application can use the file I/O functions, [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747), and the console functions, [**ReadConsole**](readconsole.md) and [**WriteConsole**](writeconsole.md), for high-level I/O that provides indirect access to a console's input and screen buffers. The high-level input functions filter and process the data in a console's input buffer to return input as a stream of characters, discarding mouse and buffer-resizing input. Similarly, the high-level output functions write a stream of characters that are displayed at the current cursor location in a screen buffer. An application controls the way these functions work by setting a console's I/O modes. The low-level I/O functions provide direct access to a console's input and screen buffers, enabling an application to access mouse and buffer-resizing input events and extended information for keyboard events. Low-level output functions enable an application to read from or write to a specified number of consecutive character cells in a screen buffer, or to read or write to rectangular blocks of character cells at a specified location in a screen buffer. A console's input modes affect low-level input by enabling the application to determine whether mouse and buffer-resizing events are placed in the input buffer. A console's output modes have no effect on low-level output. -The high-level and low-level I/O methods are not mutually exclusive, and an application can use any combination of these functions. Typically, however, an application uses one approach or the other exclusively. +The high-level and low-level I/O methods are not mutually exclusive, and an application can use any combination of these functions. Typically, however, an application uses one approach or the other exclusively and we recommend focusing on one particular paradigm for optimal results. + +> [!TIP] +> The ideal forward looking application will focus on the high-level methods and augment further needs with **[virtual terminal sequences](console-virtual-terminal-sequences.md)** through the high-level I/O methods when necessary avoiding the use of low-level I/O functions entirely. The following topics describe the console modes and the high-level and low-level I/O functions. @@ -32,6 +37,9 @@ The following topics describe the console modes and the high-level and low-level - [High-Level Console I/O](high-level-console-i-o.md) - [High-Level Console Modes](high-level-console-modes.md) - [High-Level Console Input and Output Functions](high-level-console-input-and-output-functions.md) +- [Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md) +- [Classic Functions versus Virtual Terminal Sequences](classic-vs-vt.md) +- [Ecosystem Roadmap](ecosystem-roadmap.md) - [Low-Level Console I/O](low-level-console-i-o.md) - [Low-Level Console Modes](low-level-console-modes.md) - [Low-Level Console Input Functions](low-level-console-input-functions.md) diff --git a/docs/input-record-str.md b/docs/input-record-str.md index bcc4dac..1978246 100644 --- a/docs/input-record-str.md +++ b/docs/input-record-str.md @@ -26,18 +26,16 @@ topic_type: api_name: - INPUT_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- # INPUT\_RECORD structure - Describes an input event in the console input buffer. These records can be read from the input buffer by using the [**ReadConsoleInput**](readconsoleinput.md) or [**PeekConsoleInput**](peekconsoleinput.md) function, or written to the input buffer by using the [**WriteConsoleInput**](writeconsoleinput.md) function. -Syntax ------- +## Syntax ```C typedef struct _INPUT_RECORD { @@ -52,101 +50,37 @@ typedef struct _INPUT_RECORD { } INPUT_RECORD; ``` -Members -------- +## Members **EventType** A handle to the type of input event and the event record stored in the **Event** member. This member can be one of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-FOCUS_EVENT -0x0010

The Event member contains a FOCUS_EVENT_RECORD structure. These events are used internally and should be ignored.

-KEY_EVENT -0x0001

The Event member contains a KEY_EVENT_RECORD structure with information about a keyboard event.

-MENU_EVENT -0x0008

The Event member contains a MENU_EVENT_RECORD structure. These events are used internally and should be ignored.

-MOUSE_EVENT -0x0002

The Event member contains a MOUSE_EVENT_RECORD structure with information about a mouse movement or button press event.

-WINDOW_BUFFER_SIZE_EVENT -0x0004

The Event member contains a WINDOW_BUFFER_SIZE_RECORD structure with information about the new size of the console screen buffer.

- -  +| Value | Meaning | +|-|-| +| **FOCUS_EVENT** 0x0010 | The **Event** member contains a **[FOCUS_EVENT_RECORD](focus-event-record-str.md)** structure. These events are used internally and should be ignored. | +| **KEY_EVENT** 0x0001 | The **Event** member contains a **[KEY_EVENT_RECORD](key-event-record-str.md)** structure with information about a keyboard event. | +| **MENU_EVENT** 0x0008 | The **Event** member contains a **[MENU_EVENT_RECORD](menu-event-record-str.md)** structure. These events are used internally and should be ignored. | +| **MOUSE_EVENT** 0x0002 | The **Event** member contains a **[MOUSE_EVENT_RECORD](mouse-event-record-str.md)** structure with information about a mouse movement or button press event. | +| **WINDOW_BUFFER_SIZE_EVENT** 0x0004 | The **Event** member contains a **[WINDOW_BUFFER_SIZE_RECORD](window-buffer-size-record-str.md)** structure with information about the new size of the console screen buffer. | **Event** The event information. The format of this member depends on the event type specified by the **EventType** member. -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**FOCUS\_EVENT\_RECORD**](focus-event-record-str.md) diff --git a/docs/key-event-record-str.md b/docs/key-event-record-str.md index 4109dc5..0a92668 100644 --- a/docs/key-event-record-str.md +++ b/docs/key-event-record-str.md @@ -26,18 +26,16 @@ topic_type: api_name: - KEY_EVENT_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- # KEY\_EVENT\_RECORD structure - Describes a keyboard input event in a console [**INPUT\_RECORD**](input-record-str.md) structure. -Syntax ------- +## Syntax ```C typedef struct _KEY_EVENT_RECORD { @@ -53,8 +51,7 @@ typedef struct _KEY_EVENT_RECORD { } KEY_EVENT_RECORD; ``` -Members -------- +## Members **bKeyDown** If the key is pressed, this member is **TRUE**. Otherwise, this member is **FALSE** (the key is released). @@ -80,129 +77,37 @@ Translated ASCII character. **dwControlKeyState** The state of the control keys. This member can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-CAPSLOCK_ON -0x0080

The CAPS LOCK light is on.

-ENHANCED_KEY -0x0100

The key is enhanced.

-LEFT_ALT_PRESSED -0x0002

The left ALT key is pressed.

-LEFT_CTRL_PRESSED -0x0008

The left CTRL key is pressed.

-NUMLOCK_ON -0x0020

The NUM LOCK light is on.

-RIGHT_ALT_PRESSED -0x0001

The right ALT key is pressed.

-RIGHT_CTRL_PRESSED -0x0004

The right CTRL key is pressed.

-SCROLLLOCK_ON -0x0040

The SCROLL LOCK light is on.

-SHIFT_PRESSED -0x0010

The SHIFT key is pressed.

- -  - -Remarks -------- +| Value | Meaning | +|-|-| +| **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | +| **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | +| **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | +| **RIGHT_ALT_PRESSED** 0x0001 | The right ALT key is pressed. | +| **RIGHT_CTRL_PRESSED** 0x0004 | The right CTRL key is pressed. | +| **SCROLLLOCK_ON** 0x0040 | The SCROLL LOCK light is on. | +| **SHIFT_PRESSED** 0x0010 | The SHIFT key is pressed. | + +## Remarks Enhanced keys for the IBM® 101- and 102-key keyboards are the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and direction keys in the clusters to the left of the keypad; and the divide (/) and ENTER keys in the keypad. Keyboard input events are generated when any key, including control keys, is pressed or released. However, the ALT key when pressed and released without combining with another character, has special meaning to the system and is not passed through to the application. Also, the CTRL+C key combination is not passed through if the input handle is in processed mode (**ENABLE\_PROCESSED\_INPUT**). -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**PeekConsoleInput**](peekconsoleinput.md) diff --git a/docs/legacymode.md b/docs/legacymode.md index 9904843..5711381 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -21,7 +21,8 @@ Right-click on the application title bar and choose the `Properties` menu option The setting can be reverted by returning to the same property sheet menu and unchecking the box then pressing `OK`. -**NOTE:** This setting is globally applied to all sessions that start after the preference is changed. Sessions that are already open will not be changed. +> [!NOTE] +>This setting is globally applied to all sessions that start after the preference is changed. Sessions that are already open will not be changed. ## Differences between modes @@ -37,6 +38,6 @@ The legacy Console Host embedded the suggestion portion of the IME inside the ho ### API Differences -The major known difference between legacy and current is the implementation of UTF-8. The legacy host has extremely rudimentary and often incorrect support of UTF-8 with [code page 65001](https://docs.microsoft.com/windows/win32/intl/code-pages). The current console host contains incremental improvements release-over-release of Windows 10 to improve this support. Applications that are attempting to rely on predicting "known incorrect" interpretations of UTF-8 from the legacy console will find themselves receiving different answers as support is improved. +The major known difference between legacy and current is the implementation of UTF-8. The legacy host has extremely rudimentary and often incorrect support of UTF-8 with [code page 65001](https://docs.microsoft.com/windows/win32/intl/code-pages). The current console host contains incremental improvements release-over-release of Windows 10 to improve this support. Applications that are attempting to rely on predicting "known incorrect" interpretations of UTF-8 from the legacy console will find themselves receiving different answers as support is improved. Other differences experienced with APIs should be reported to [Microsoft/Terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. diff --git a/docs/low-level-console-input-functions.md b/docs/low-level-console-input-functions.md index fb7795d..dbf5303 100644 --- a/docs/low-level-console-input-functions.md +++ b/docs/low-level-console-input-functions.md @@ -33,16 +33,12 @@ The [**ReadConsoleInput**](readconsoleinput.md), [**PeekConsoleInput**](peekcons Following are descriptions of the low-level console input functions. - -| Function | Description | -|---|---| -| [**ReadConsoleInput**](readconsoleinput.md) | Reads and removes input records from an input buffer. The function does not return until at least one record is available to be read. Then all available records are transferred to the buffer of the calling process until either no more records are available or the specified number of records has been read. Unread records remain in the input buffer for the next read operation. The function reports the total number of records that have been read. For an example that uses [**ReadConsoleInput**](readconsoleinput.md), see [Reading Input Buffer Events](reading-input-buffer-events.md). | -| [**PeekConsoleInput**](peekconsoleinput.md) | Reads without removing the pending input records in an input buffer. All available records up to the specified number are copied into the buffer of the calling process. If no records are available, the function returns immediately. The function reports the total number of records that have been read. | -| [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) | Determines the number of unread input records in an input buffer. | -| [**WriteConsoleInput**](writeconsoleinput.md) | Places input records into the input buffer behind any pending records in the buffer. The input buffer grows dynamically, if necessary, to hold as many records as are written. To use this function, the specified input buffer handle must have the GENERIC\_READ access right. | -| [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) | Discards all unread events in the input buffer. To use this function, the specified input buffer handle must have the GENERIC\_READ access right. | - - - - -A thread of an application's process can perform a wait operation to wait for input to be available in an input buffer. To initiate a wait operation, specify a handle to the input buffer in a call to any of the [wait functions](https://msdn.microsoft.com/library/windows/desktop/ms687069). These functions can return when the state of one or more objects is signaled. The state of a console input handle becomes signaled when there are unread records in its input buffer. The state is reset to nonsignaled when the input buffer becomes empty. If there is no input available, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the conditions of the wait operation to be satisfied. +| Function | Description | +|-|-| +| [**ReadConsoleInput**](readconsoleinput.md) | Reads and removes input records from an input buffer. The function does not return until at least one record is available to be read. Then all available records are transferred to the buffer of the calling process until either no more records are available or the specified number of records has been read. Unread records remain in the input buffer for the next read operation. The function reports the total number of records that have been read. For an example that uses [**ReadConsoleInput**](readconsoleinput.md), see [Reading Input Buffer Events](reading-input-buffer-events.md). | +| [**PeekConsoleInput**](peekconsoleinput.md) | Reads without removing the pending input records in an input buffer. All available records up to the specified number are copied into the buffer of the calling process. If no records are available, the function returns immediately. The function reports the total number of records that have been read. | +| [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) | Determines the number of unread input records in an input buffer. | +| [**WriteConsoleInput**](writeconsoleinput.md) | Places input records into the input buffer behind any pending records in the buffer. The input buffer grows dynamically, if necessary, to hold as many records as are written. To use this function, the specified input buffer handle must have the GENERIC\_READ access right. | +| [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) | Discards all unread events in the input buffer. To use this function, the specified input buffer handle must have the GENERIC\_READ access right. | + +A thread of an application's process can perform a wait operation to wait for input to be available in an input buffer. To initiate a wait operation, specify a handle to the input buffer in a call to any of the [wait functions](https://msdn.microsoft.com/library/windows/desktop/ms687069). These functions can return when the state of one or more objects is signaled. The state of a console input handle becomes signaled when there are unread records in its input buffer. The state is reset to non-signaled when the input buffer becomes empty. If there is no input available, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the conditions of the wait operation to be satisfied. diff --git a/docs/low-level-console-modes.md b/docs/low-level-console-modes.md index 53824d0..f853841 100644 --- a/docs/low-level-console-modes.md +++ b/docs/low-level-console-modes.md @@ -21,13 +21,10 @@ ms.assetid: 41bfdc51-27cb-4d5e-898c-507ffc8789b9 The types of input events reported in a console's input buffer depend on the console's mouse and window input modes. The console's processed input mode determines how the system handles the CTRL+C key combination. To set or retrieve the state of a console's input modes, an application can specify a console input buffer handle in a call to the [**SetConsoleMode**](setconsolemode.md) or [**GetConsoleMode**](getconsolemode.md) function. The following modes are used with console input handles. - -| Mode | Description | -|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Mode | Description | +|-|-| | **ENABLE\_MOUSE\_INPUT** | Controls whether mouse events are reported in the input buffer. By default, mouse input is enabled and window input is disabled. Changing either of these modes affects only input that occurs after the mode is set; pending mouse or window events in the input buffer are not flushed. The mouse pointer is displayed regardless of the mouse mode. | | **ENABLE\_WINDOW\_INPUT** | Controls whether buffer-resizing events are reported in the input buffer. By default, mouse input is enabled and window input is disabled. Changing either of these modes affects only input that occurs after the mode is set; pending mouse or window events in the input buffer are not flushed. The mouse pointer is displayed regardless of the mouse mode. | | **ENABLE\_PROCESSED\_INPUT** | Controls the processing of input for applications using the high-level console I/O functions. However, if processed input mode is enabled, the CTRL+C key combination is not reported in the console's input buffer. Instead, it is passed on to the appropriate control handler function. For more information about control handlers, see [Console Control Handlers](console-control-handlers.md). | - - The output modes of a screen buffer do not affect the behavior of the low-level output functions. diff --git a/docs/low-level-console-output-functions.md b/docs/low-level-console-output-functions.md index ba37e90..b52d1ed 100644 --- a/docs/low-level-console-output-functions.md +++ b/docs/low-level-console-output-functions.md @@ -23,9 +23,8 @@ The low-level console output functions provide direct access to the character ce The following functions read from or write to a specified number of consecutive character cells in a screen buffer, beginning with a specified cell. - | Function | Description | -|---|---| +|-|-| | [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a string of Unicode or ANSI characters from a screen buffer. | | [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) | Writes a string of Unicode or ANSI characters to a screen buffer. | | [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a string of text and background color attributes from a screen buffer. | @@ -33,19 +32,15 @@ The following functions read from or write to a specified number of consecutive | [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a single Unicode or ANSI character to a specified number of consecutive cells in a screen buffer. | | [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Writes a text and background color attribute combination to a specified number of consecutive cells in a screen buffer. | - For all of these functions, when the last cell of a row is encountered, reading or writing wraps around to the first cell of the next row. When the end of the last row of the console screen buffer is encountered, the write functions discard all unwritten characters or attributes, and the read functions report the number of characters or attributes actually written. The following functions read from or write to rectangular blocks of character cells at a specified location in a screen buffer. - | Function | Description | -|---|---| +|-|-| | [**ReadConsoleOutput**](readconsoleoutput.md) | Copies character and color data from a specified block of screen buffer cells into a given block in a destination buffer. | | [**WriteConsoleOutput**](writeconsoleoutput.md) | Writes character and color data to a specified block of screen buffer cells from a given block in a source buffer. | - - These functions treat screen buffers and source or destination buffers as two-dimensional arrays of [**CHAR\_INFO**](char-info-str.md) structures (containing character and color attribute data for each cell). The functions specify the width and height, in character cells, of the source or destination buffer, and the pointer to the buffer is treated as a pointer to the origin cell (0,0) of the two-dimensional array. The functions use a [**SMALL\_RECT**](small-rect-str.md) structure to specify which rectangle to access in the console screen buffer, and the coordinates of the upper left cell in the source or destination buffer determine the location of the corresponding rectangle in that buffer. These functions automatically clip the specified screen buffer rectangle to fit within the boundaries of the console screen buffer. For example, if the rectangle specifies lower right coordinates that are (column 100, row 50) and the console screen buffer is only 80 columns wide, the coordinates are clipped so that they are (column 79, row 50). Similarly, this adjusted rectangle is again clipped to fit within the boundaries of the source or destination buffer. The screen buffer coordinates of the actual rectangle that was read from or written to are specified. For an example that uses these functions, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). diff --git a/docs/menu-event-record-str.md b/docs/menu-event-record-str.md index b59cf9f..5c14f8c 100644 --- a/docs/menu-event-record-str.md +++ b/docs/menu-event-record-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - MENU_EVENT_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -37,8 +37,7 @@ api_type: Describes a menu event in a console [**INPUT\_RECORD**](input-record-str.md) structure. These events are used internally and should be ignored. -Syntax ------- +## Syntax ```C typedef struct _MENU_EVENT_RECORD { @@ -46,37 +45,19 @@ typedef struct _MENU_EVENT_RECORD { } MENU_EVENT_RECORD, *PMENU_EVENT_RECORD; ``` -Members -------- +## Members **dwCommandId** Reserved. -Requirements ------------- +## Requirements - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**INPUT\_RECORD**](input-record-str.md) diff --git a/docs/mouse-event-record-str.md b/docs/mouse-event-record-str.md index 2fc5b71..1e0329f 100644 --- a/docs/mouse-event-record-str.md +++ b/docs/mouse-event-record-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - MOUSE_EVENT_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -37,8 +37,7 @@ api_type: Describes a mouse input event in a console [**INPUT\_RECORD**](input-record-str.md) structure. -Syntax ------- +## Syntax ```C typedef struct _MOUSE_EVENT_RECORD { @@ -49,8 +48,7 @@ typedef struct _MOUSE_EVENT_RECORD { } MOUSE_EVENT_RECORD; ``` -Members -------- +## Members **dwMousePosition** A [**COORD**](coord-str.md) structure that contains the location of the cursor, in terms of the console screen buffer's character-cell coordinates. @@ -60,235 +58,58 @@ The status of the mouse buttons. The least significant bit corresponds to the le The following constants are defined for the first five mouse buttons. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-FROM_LEFT_1ST_BUTTON_PRESSED -0x0001

The leftmost mouse button.

-FROM_LEFT_2ND_BUTTON_PRESSED -0x0004

The second button from the left.

-FROM_LEFT_3RD_BUTTON_PRESSED -0x0008

The third button from the left.

-FROM_LEFT_4TH_BUTTON_PRESSED -0x0010

The fourth button from the left.

-RIGHTMOST_BUTTON_PRESSED -0x0002

The rightmost mouse button.

- -  +| Value | Meaning | +|-|-| +| **FROM_LEFT_1ST_BUTTON_PRESSED** 0x0001 | The leftmost mouse button. | +| **FROM_LEFT_2ND_BUTTON_PRESSED** 0x0004 | The second button fom the left. | +| **FROM_LEFT_3RD_BUTTON_PRESSED** 0x0008 | The third button from the left. | +| **FROM_LEFT_4TH_BUTTON_PRESSED** 0x0010 | The fourth button from the left. | +| **RIGHTMOST_BUTTON_PRESSED** 0x0002 | The rightmost mouse button. | **dwControlKeyState** The state of the control keys. This member can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-CAPSLOCK_ON -0x0080

The CAPS LOCK light is on.

-ENHANCED_KEY -0x0100

The key is enhanced.

-LEFT_ALT_PRESSED -0x0002

The left ALT key is pressed.

-LEFT_CTRL_PRESSED -0x0008

The left CTRL key is pressed.

-NUMLOCK_ON -0x0020

The NUM LOCK light is on.

-RIGHT_ALT_PRESSED -0x0001

The right ALT key is pressed.

-RIGHT_CTRL_PRESSED -0x0004

The right CTRL key is pressed.

-SCROLLLOCK_ON -0x0040

The SCROLL LOCK light is on.

-SHIFT_PRESSED -0x0010

The SHIFT key is pressed.

- -  +| Value | Meaning | +|-|-| +| **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | +| **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | +| **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | +| **RIGHT_ALT_PRESSED** 0x0001 | The right ALT key is pressed. | +| **RIGHT_CTRL_PRESSED** 0x0004 | The right CTRL key is pressed. | +| **SCROLLLOCK_ON** 0x0040 | The SCROLL LOCK light is on. | +| **SHIFT_PRESSED** 0x0010 | The SHIFT key is pressed. | **dwEventFlags** The type of mouse event. If this value is zero, it indicates a mouse button being pressed or released. Otherwise, this member is one of the following values. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-DOUBLE_CLICK -0x0002

The second click (button press) of a double-click occurred. The first click is returned as a regular button-press event.

-MOUSE_HWHEELED -0x0008

The horizontal mouse wheel was moved.

-

If the high word of the dwButtonState member contains a positive value, the wheel was rotated to the right. Otherwise, the wheel was rotated to the left.

-MOUSE_MOVED -0x0001

A change in mouse position occurred.

-MOUSE_WHEELED -0x0004

The vertical mouse wheel was moved.

-

If the high word of the dwButtonState member contains a positive value, the wheel was rotated forward, away from the user. Otherwise, the wheel was rotated backward, toward the user.

+| Value | Meaning | +|-|-| +| **DOUBLE_CLICK** 0x0002 | The second click (button press) of a double-click occurred. The first click is returned as a regular button-press event. | +| **MOUSE_HWHEELED** 0x0008 | The horizontal mouse wheel was moved.

If the high word of the **dwButtonState** member contains a positive value, the wheel was rotated to the right. Otherwise, the wheel was rotated to the left. | +| **MOUSE_MOVED** 0x0001 | A change in mouse position occurred. | +| **MOUSE_WHEELED** 0x0004 | The vertical mouse wheel was moved.

If the high word of the **dwButtonState** member contains a positive value, the wheel was rotated forward, away from the user. Otherwise, the wheel was rotated backward, toward the user. | -  - -Remarks -------- +## Remarks Mouse events are placed in the input buffer when the console is in mouse mode (**ENABLE\_MOUSE\_INPUT**). Mouse events are generated whenever the user moves the mouse, or presses or releases one of the mouse buttons. Mouse events are placed in a console's input buffer only when the console group has the keyboard focus and the cursor is within the borders of the console's window. -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
+## Requirements -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | +## See also [**COORD**](coord-str.md) diff --git a/docs/peekconsoleinput.md b/docs/peekconsoleinput.md index 6a3e654..6e2cfcc 100644 --- a/docs/peekconsoleinput.md +++ b/docs/peekconsoleinput.md @@ -47,8 +47,7 @@ api_type: Reads data from the specified console input buffer without removing it from the buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI PeekConsoleInput( @@ -59,8 +58,7 @@ BOOL WINAPI PeekConsoleInput( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -74,66 +72,30 @@ The size of the array pointed to by the *lpBuffer* parameter, in array elements. *lpNumberOfEventsRead* \[out\] A pointer to a variable that receives the number of input records read. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of records requested exceeds the number of records available in the buffer, the number available is read. If no data is available, the function returns immediately. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

PeekConsoleInputW (Unicode) and PeekConsoleInputA (ANSI)

- -## See also +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **PeekConsoleInputW** (Unicode) and **PeekConsoleInputA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/pseudoconsoles.md b/docs/pseudoconsoles.md index 7e458c2..0207807 100644 --- a/docs/pseudoconsoles.md +++ b/docs/pseudoconsoles.md @@ -11,7 +11,7 @@ keywords: console, character mode applications, command line applications, termi # Pseudoconsoles -A *pseudoconsole* is a device type that allows applications to become the host for character-mode applications. +A *pseudoconsole* is a device type that allows applications to become the host for character-mode applications. This is in contrast to a typical console session where the operating system will create a hosting window on behalf of the character-mode application to handle graphical output and user input. diff --git a/docs/readconsole.md b/docs/readconsole.md index 8b7490a..ad649b8 100644 --- a/docs/readconsole.md +++ b/docs/readconsole.md @@ -44,8 +44,7 @@ api_type: Reads character input from the console input buffer and removes it from the buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI ReadConsole( @@ -57,8 +56,7 @@ BOOL WINAPI ReadConsole( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -77,15 +75,13 @@ A pointer to a [**CONSOLE\_READCONSOLE\_CONTROL**](console-readconsole-control.m This parameter requires Unicode input by default. For ANSI mode, set this parameter to **NULL**. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **ReadConsole** reads keyboard input from a console's input buffer. It behaves like the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) function, except that it can read in either Unicode (wide-character) or ANSI mode. To have applications that maintain a single set of sources compatible with both modes, use **ReadConsole** rather than **ReadFile**. Although **ReadConsole** can only be used with a console input buffer handle, **ReadFile** can be used with other handles (such as files or pipes). **ReadConsole** fails if used with a standard handle that has been redirected to be something other than a console handle. @@ -93,58 +89,24 @@ All of the input modes that affect the behavior of [**ReadFile**](https://msdn.m If the input buffer contains input events other than keyboard events (such as mouse events or window-resizing events), they are discarded. Those events can only be read by using the [**ReadConsoleInput**](readconsoleinput.md) function. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] The *pInputControl* parameter can be used to enable intermediate wakeups from the read in response to a file-completion control character specified in a [**CONSOLE\_READCONSOLE\_CONTROL**](console-readconsole-control.md) structure. This feature requires command extensions to be enabled, the standard output handle to be a console output handle, and input to be Unicode. **Windows Server 2003 and Windows XP/2000:** The intermediate read feature is not supported. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReadConsoleW (Unicode) and ReadConsoleA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **ReadConsoleW** (Unicode) and **ReadConsoleA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/readconsoleinput.md b/docs/readconsoleinput.md index eb9c1d5..6b793cc 100644 --- a/docs/readconsoleinput.md +++ b/docs/readconsoleinput.md @@ -42,11 +42,9 @@ api_type: # ReadConsoleInput function - Reads data from a console input buffer and removes it from the buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI ReadConsoleInput( @@ -57,8 +55,7 @@ BOOL WINAPI ReadConsoleInput( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -72,15 +69,13 @@ The size of the array pointed to by the *lpBuffer* parameter, in array elements. *lpNumberOfEventsRead* \[out\] A pointer to a variable that receives the number of input records read. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of records requested in the *nLength* parameter exceeds the number of records available in the buffer, the number available is read. The function does not return until at least one input record has been read. @@ -88,59 +83,24 @@ A process can specify a console input buffer handle in one of the [wait function To determine the number of unread input records in a console's input buffer, use the [**GetNumberOfConsoleInputEvents**](getnumberofconsoleinputevents.md) function. To read input records from a console input buffer without affecting the number of unread records, use the [**PeekConsoleInput**](peekconsoleinput.md) function. To discard all unread records in a console's input buffer, use the [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) function. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReadConsoleInputW (Unicode) and ReadConsoleInputA (ANSI)

- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **ReadConsoleInputW** (Unicode) and **ReadConsoleInputA** (ANSI) | +## See also [Console Functions](console-functions.md) diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index 8cf2b71..748972f 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -45,8 +45,7 @@ api_type: Reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI ReadConsoleOutput( @@ -58,8 +57,7 @@ BOOL WINAPI ReadConsoleOutput( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -76,15 +74,13 @@ The coordinates of the upper-left cell in the *lpBuffer* parameter that receives *lpReadRegion* \[in, out\] A pointer to a [**SMALL\_RECT**](small-rect-str.md) structure. On input, the structure members specify the upper-left and lower-right coordinates of the console screen buffer rectangle from which the function is to read. On output, the structure members specify the actual rectangle that was used. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **ReadConsoleOutput** treats the console screen buffer and the destination buffer as two-dimensional arrays (columns and rows of character cells). The rectangle pointed to by the *lpReadRegion* parameter specifies the size and location of the block to be read from the console screen buffer. A destination rectangle of the same size is located with its upper-left cell at the coordinates of the *dwBufferCoord* parameter in the *lpBuffer* array. Data read from the cells in the console screen buffer source rectangle is copied to the corresponding cells in the destination buffer. If the corresponding cell is outside the boundaries of the destination buffer rectangle (whose dimensions are specified by the *dwBufferSize* parameter), the data is not copied. @@ -96,61 +92,26 @@ If the rectangle specified by *lpReadRegion* lies completely outside the boundar The **ReadConsoleOutput** function has no effect on the console screen buffer's cursor position. The contents of the console screen buffer are not changed by the function. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] [!INCLUDE [no-vt-equiv-banner](./includes/no-vt-equiv-banner.md)] -Examples --------- +## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReadConsoleOutputW (Unicode) and ReadConsoleOutputA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **ReadConsoleOutputW** (Unicode) and **ReadConsoleOutputA** (ANSI) | + +## See also [Console Functions](console-functions.md) @@ -171,11 +132,3 @@ Requirements [**CHAR\_INFO**](char-info-str.md) [**COORD**](coord-str.md) - -  - -  - - - - diff --git a/docs/readconsoleoutputattribute.md b/docs/readconsoleoutputattribute.md index b6e9123..0d40d8c 100644 --- a/docs/readconsoleoutputattribute.md +++ b/docs/readconsoleoutputattribute.md @@ -37,8 +37,7 @@ api_type: Copies a specified number of character attributes from consecutive cells of a console screen buffer, beginning at a specified location. -Syntax ------- +## Syntax ```C BOOL WINAPI ReadConsoleOutputAttribute( @@ -50,8 +49,7 @@ BOOL WINAPI ReadConsoleOutputAttribute( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -59,7 +57,7 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *lpAttribute* \[out\] A pointer to a buffer that receives the attributes being used by the console screen buffer. -For more information, see [Character Attributes](console-screen-buffers.md#_win32_font_attributes). +For more information, see [Character Attributes](console-screen-buffers.md#character-attributes). *nLength* \[in\] The number of screen buffer character cells from which to read. The size of the buffer pointed to by the *lpAttribute* parameter should be `nLength * sizeof(WORD)`. @@ -70,58 +68,27 @@ The coordinates of the first cell in the console screen buffer from which to rea *lpNumberOfAttrsRead* \[out\] A pointer to a variable that receives the number of attributes actually read. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of attributes to be read from extends beyond the end of the specified screen buffer row, attributes are read from the next row. If the number of attributes to be read from extends beyond the end of the console screen buffer, attributes up to the end of the console screen buffer are read. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/readconsoleoutputcharacter.md b/docs/readconsoleoutputcharacter.md index 09b47a3..ff03e34 100644 --- a/docs/readconsoleoutputcharacter.md +++ b/docs/readconsoleoutputcharacter.md @@ -45,8 +45,7 @@ api_type: Copies a number of characters from consecutive cells of a console screen buffer, beginning at a specified location. -Syntax ------- +## Syntax ```C BOOL WINAPI ReadConsoleOutputCharacter( @@ -58,8 +57,7 @@ BOOL WINAPI ReadConsoleOutputCharacter( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -76,66 +74,30 @@ The coordinates of the first cell in the console screen buffer from which to rea *lpNumberOfCharsRead* \[out\] A pointer to a variable that receives the number of characters actually read. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of characters to be read from extends beyond the end of the specified screen buffer row, characters are read from the next row. If the number of characters to be read from extends beyond the end of the console screen buffer, characters up to the end of the console screen buffer are read. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReadConsoleOutputCharacterW (Unicode) and ReadConsoleOutputCharacterA (ANSI)

- -## See also +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **ReadConsoleOutputCharacterW** (Unicode) and **ReadConsoleOutputCharacterA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/reading-and-writing-blocks-of-characters-and-attributes.md b/docs/reading-and-writing-blocks-of-characters-and-attributes.md index 4a9af0f..264f1a6 100644 --- a/docs/reading-and-writing-blocks-of-characters-and-attributes.md +++ b/docs/reading-and-writing-blocks-of-characters-and-attributes.md @@ -24,105 +24,105 @@ The [**ReadConsoleOutput**](readconsoleoutput.md) function copies a rectangular The following example uses the [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) function to create a new screen buffer. After the [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) function makes this the active screen buffer, a block of characters and color attributes is copied from the top two rows of the STDOUT screen buffer into a temporary buffer. The data is then copied from the temporary buffer into the new active screen buffer. When the application is finished using the new screen buffer, it calls **SetConsoleActiveScreenBuffer** to restore the original STDOUT screen buffer. ```C -#include +#include #include - -int main(void) -{ - HANDLE hStdout, hNewScreenBuffer; - SMALL_RECT srctReadRect; - SMALL_RECT srctWriteRect; - CHAR_INFO chiBuffer[160]; // [2][80]; - COORD coordBufSize; - COORD coordBufCoord; - BOOL fSuccess; - - // Get a handle to the STDOUT screen buffer to copy from and - // create a new screen buffer to copy to. - - hStdout = GetStdHandle(STD_OUTPUT_HANDLE); - hNewScreenBuffer = CreateConsoleScreenBuffer( - GENERIC_READ | // read/write access - GENERIC_WRITE, - FILE_SHARE_READ | - FILE_SHARE_WRITE, // shared - NULL, // default security attributes - CONSOLE_TEXTMODE_BUFFER, // must be TEXTMODE - NULL); // reserved; must be NULL - if (hStdout == INVALID_HANDLE_VALUE || - hNewScreenBuffer == INVALID_HANDLE_VALUE) + +int main(void) +{ + HANDLE hStdout, hNewScreenBuffer; + SMALL_RECT srctReadRect; + SMALL_RECT srctWriteRect; + CHAR_INFO chiBuffer[160]; // [2][80]; + COORD coordBufSize; + COORD coordBufCoord; + BOOL fSuccess; + + // Get a handle to the STDOUT screen buffer to copy from and + // create a new screen buffer to copy to. + + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + hNewScreenBuffer = CreateConsoleScreenBuffer( + GENERIC_READ | // read/write access + GENERIC_WRITE, + FILE_SHARE_READ | + FILE_SHARE_WRITE, // shared + NULL, // default security attributes + CONSOLE_TEXTMODE_BUFFER, // must be TEXTMODE + NULL); // reserved; must be NULL + if (hStdout == INVALID_HANDLE_VALUE || + hNewScreenBuffer == INVALID_HANDLE_VALUE) { - printf("CreateConsoleScreenBuffer failed - (%d)\n", GetLastError()); + printf("CreateConsoleScreenBuffer failed - (%d)\n", GetLastError()); return 1; } - - // Make the new screen buffer the active screen buffer. - - if (! SetConsoleActiveScreenBuffer(hNewScreenBuffer) ) + + // Make the new screen buffer the active screen buffer. + + if (! SetConsoleActiveScreenBuffer(hNewScreenBuffer) ) { - printf("SetConsoleActiveScreenBuffer failed - (%d)\n", GetLastError()); + printf("SetConsoleActiveScreenBuffer failed - (%d)\n", GetLastError()); return 1; } - - // Set the source rectangle. - - srctReadRect.Top = 0; // top left: row 0, col 0 - srctReadRect.Left = 0; - srctReadRect.Bottom = 1; // bot. right: row 1, col 79 - srctReadRect.Right = 79; - - // The temporary buffer size is 2 rows x 80 columns. - - coordBufSize.Y = 2; - coordBufSize.X = 80; - - // The top left destination cell of the temporary buffer is - // row 0, col 0. - - coordBufCoord.X = 0; - coordBufCoord.Y = 0; - - // Copy the block from the screen buffer to the temp. buffer. - - fSuccess = ReadConsoleOutput( - hStdout, // screen buffer to read from - chiBuffer, // buffer to copy into - coordBufSize, // col-row size of chiBuffer - coordBufCoord, // top left dest. cell in chiBuffer - &srctReadRect); // screen buffer source rectangle - if (! fSuccess) + + // Set the source rectangle. + + srctReadRect.Top = 0; // top left: row 0, col 0 + srctReadRect.Left = 0; + srctReadRect.Bottom = 1; // bot. right: row 1, col 79 + srctReadRect.Right = 79; + + // The temporary buffer size is 2 rows x 80 columns. + + coordBufSize.Y = 2; + coordBufSize.X = 80; + + // The top left destination cell of the temporary buffer is + // row 0, col 0. + + coordBufCoord.X = 0; + coordBufCoord.Y = 0; + + // Copy the block from the screen buffer to the temp. buffer. + + fSuccess = ReadConsoleOutput( + hStdout, // screen buffer to read from + chiBuffer, // buffer to copy into + coordBufSize, // col-row size of chiBuffer + coordBufCoord, // top left dest. cell in chiBuffer + &srctReadRect); // screen buffer source rectangle + if (! fSuccess) { - printf("ReadConsoleOutput failed - (%d)\n", GetLastError()); + printf("ReadConsoleOutput failed - (%d)\n", GetLastError()); return 1; } - - // Set the destination rectangle. - - srctWriteRect.Top = 10; // top lt: row 10, col 0 - srctWriteRect.Left = 0; - srctWriteRect.Bottom = 11; // bot. rt: row 11, col 79 - srctWriteRect.Right = 79; - - // Copy from the temporary buffer to the new screen buffer. - - fSuccess = WriteConsoleOutput( - hNewScreenBuffer, // screen buffer to write to - chiBuffer, // buffer to copy from - coordBufSize, // col-row size of chiBuffer - coordBufCoord, // top left src cell in chiBuffer - &srctWriteRect); // dest. screen buffer rectangle - if (! fSuccess) + + // Set the destination rectangle. + + srctWriteRect.Top = 10; // top lt: row 10, col 0 + srctWriteRect.Left = 0; + srctWriteRect.Bottom = 11; // bot. rt: row 11, col 79 + srctWriteRect.Right = 79; + + // Copy from the temporary buffer to the new screen buffer. + + fSuccess = WriteConsoleOutput( + hNewScreenBuffer, // screen buffer to write to + chiBuffer, // buffer to copy from + coordBufSize, // col-row size of chiBuffer + coordBufCoord, // top left src cell in chiBuffer + &srctWriteRect); // dest. screen buffer rectangle + if (! fSuccess) { - printf("WriteConsoleOutput failed - (%d)\n", GetLastError()); + printf("WriteConsoleOutput failed - (%d)\n", GetLastError()); return 1; } - Sleep(5000); - - // Restore the original active screen buffer. - - if (! SetConsoleActiveScreenBuffer(hStdout)) + Sleep(5000); + + // Restore the original active screen buffer. + + if (! SetConsoleActiveScreenBuffer(hStdout)) { - printf("SetConsoleActiveScreenBuffer failed - (%d)\n", GetLastError()); + printf("SetConsoleActiveScreenBuffer failed - (%d)\n", GetLastError()); return 1; } diff --git a/docs/reading-input-buffer-events.md b/docs/reading-input-buffer-events.md index fd7fc0d..bcb65f1 100644 --- a/docs/reading-input-buffer-events.md +++ b/docs/reading-input-buffer-events.md @@ -17,103 +17,102 @@ ms.assetid: 57570f3b-4a37-4789-bf6c-474fae60171d # Reading Input Buffer Events - The [**ReadConsoleInput**](readconsoleinput.md) function can be used to directly access a console's input buffer. When a console is created, mouse input is enabled and window input is disabled. To ensure that the process receives all types of events, this example uses the [**SetConsoleMode**](setconsolemode.md) function to enable window and mouse input. Then it goes into a loop that reads and handles 100 console input events. For example, the message "Keyboard event" is displayed when the user presses a key and the message "Mouse event" is displayed when the user interacts with the mouse. ```C #include #include -HANDLE hStdin; +HANDLE hStdin; DWORD fdwSaveOldMode; VOID ErrorExit(LPSTR); -VOID KeyEventProc(KEY_EVENT_RECORD); -VOID MouseEventProc(MOUSE_EVENT_RECORD); -VOID ResizeEventProc(WINDOW_BUFFER_SIZE_RECORD); - -int main(VOID) -{ - DWORD cNumRead, fdwMode, i; - INPUT_RECORD irInBuf[128]; +VOID KeyEventProc(KEY_EVENT_RECORD); +VOID MouseEventProc(MOUSE_EVENT_RECORD); +VOID ResizeEventProc(WINDOW_BUFFER_SIZE_RECORD); + +int main(VOID) +{ + DWORD cNumRead, fdwMode, i; + INPUT_RECORD irInBuf[128]; int counter=0; - - // Get the standard input handle. - - hStdin = GetStdHandle(STD_INPUT_HANDLE); - if (hStdin == INVALID_HANDLE_VALUE) - ErrorExit("GetStdHandle"); - - // Save the current input mode, to be restored on exit. - - if (! GetConsoleMode(hStdin, &fdwSaveOldMode) ) - ErrorExit("GetConsoleMode"); - - // Enable the window and mouse input events. - - fdwMode = ENABLE_WINDOW_INPUT | ENABLE_MOUSE_INPUT; - if (! SetConsoleMode(hStdin, fdwMode) ) - ErrorExit("SetConsoleMode"); - - // Loop to read and handle the next 100 input events. - - while (counter++ <= 100) - { - // Wait for the events. - - if (! ReadConsoleInput( - hStdin, // input buffer handle - irInBuf, // buffer to read into - 128, // size of read buffer - &cNumRead) ) // number of records read - ErrorExit("ReadConsoleInput"); - - // Dispatch the events to the appropriate handler. - - for (i = 0; i < cNumRead; i++) + + // Get the standard input handle. + + hStdin = GetStdHandle(STD_INPUT_HANDLE); + if (hStdin == INVALID_HANDLE_VALUE) + ErrorExit("GetStdHandle"); + + // Save the current input mode, to be restored on exit. + + if (! GetConsoleMode(hStdin, &fdwSaveOldMode) ) + ErrorExit("GetConsoleMode"); + + // Enable the window and mouse input events. + + fdwMode = ENABLE_WINDOW_INPUT | ENABLE_MOUSE_INPUT; + if (! SetConsoleMode(hStdin, fdwMode) ) + ErrorExit("SetConsoleMode"); + + // Loop to read and handle the next 100 input events. + + while (counter++ <= 100) + { + // Wait for the events. + + if (! ReadConsoleInput( + hStdin, // input buffer handle + irInBuf, // buffer to read into + 128, // size of read buffer + &cNumRead) ) // number of records read + ErrorExit("ReadConsoleInput"); + + // Dispatch the events to the appropriate handler. + + for (i = 0; i < cNumRead; i++) { - switch(irInBuf[i].EventType) - { - case KEY_EVENT: // keyboard input - KeyEventProc(irInBuf[i].Event.KeyEvent); - break; - - case MOUSE_EVENT: // mouse input - MouseEventProc(irInBuf[i].Event.MouseEvent); - break; - - case WINDOW_BUFFER_SIZE_EVENT: // scrn buf. resizing - ResizeEventProc( irInBuf[i].Event.WindowBufferSizeEvent ); - break; - - case FOCUS_EVENT: // disregard focus events - - case MENU_EVENT: // disregard menu events - break; - - default: - ErrorExit("Unknown event type"); - break; - } + switch(irInBuf[i].EventType) + { + case KEY_EVENT: // keyboard input + KeyEventProc(irInBuf[i].Event.KeyEvent); + break; + + case MOUSE_EVENT: // mouse input + MouseEventProc(irInBuf[i].Event.MouseEvent); + break; + + case WINDOW_BUFFER_SIZE_EVENT: // scrn buf. resizing + ResizeEventProc( irInBuf[i].Event.WindowBufferSizeEvent ); + break; + + case FOCUS_EVENT: // disregard focus events + + case MENU_EVENT: // disregard menu events + break; + + default: + ErrorExit("Unknown event type"); + break; + } } - } + } // Restore input mode on exit. SetConsoleMode(hStdin, fdwSaveOldMode); - - return 0; + + return 0; } -VOID ErrorExit (LPSTR lpszMessage) -{ - fprintf(stderr, "%s\n", lpszMessage); +VOID ErrorExit (LPSTR lpszMessage) +{ + fprintf(stderr, "%s\n", lpszMessage); // Restore input mode on exit. SetConsoleMode(hStdin, fdwSaveOldMode); - ExitProcess(0); + ExitProcess(0); } VOID KeyEventProc(KEY_EVENT_RECORD ker) @@ -131,7 +130,7 @@ VOID MouseEventProc(MOUSE_EVENT_RECORD mer) #define MOUSE_HWHEELED 0x0008 #endif printf("Mouse event: "); - + switch(mer.dwEventFlags) { case 0: diff --git a/docs/registering-a-control-handler-function.md b/docs/registering-a-control-handler-function.md index 807a7ff..793284c 100644 --- a/docs/registering-a-control-handler-function.md +++ b/docs/registering-a-control-handler-function.md @@ -17,7 +17,6 @@ ms.assetid: f1c72277-f06c-4147-a74c-6aaf6feb730e # Registering a Control Handler Function - This is an example of the [**SetConsoleCtrlHandler**](setconsolectrlhandler.md) function that is used to install a control handler. When a CTRL+C signal is received, the control handler returns **TRUE**, indicating that it has handled the signal. Doing this prevents other control handlers from being called. @@ -32,26 +31,26 @@ When a **CTRL\_BREAK\_EVENT**, **CTRL\_LOGOFF\_EVENT**, or **CTRL\_SHUTDOWN\_EVE #include "pch.h" -#include -#include +#include +#include BOOL WINAPI CtrlHandler(DWORD fdwCtrlType) { switch (fdwCtrlType) { - // Handle the CTRL-C signal. + // Handle the CTRL-C signal. case CTRL_C_EVENT: printf("Ctrl-C event\n\n"); Beep(750, 300); return TRUE; - // CTRL-CLOSE: confirm that the user wants to exit. + // CTRL-CLOSE: confirm that the user wants to exit. case CTRL_CLOSE_EVENT: Beep(600, 200); printf("Ctrl-Close event\n\n"); return TRUE; - // Pass other signals to the next handler. + // Pass other signals to the next handler. case CTRL_BREAK_EVENT: Beep(900, 200); printf("Ctrl-Break event\n\n"); diff --git a/docs/resizepseudoconsole.md b/docs/resizepseudoconsole.md index cd04d2b..ddf9762 100644 --- a/docs/resizepseudoconsole.md +++ b/docs/resizepseudoconsole.md @@ -25,8 +25,7 @@ api_type: Resizes the internal buffers for a pseudoconsole to the given size. -Syntax ------- +## Syntax ```C HRESULT WINAPI ResizePseudoConsole( @@ -35,66 +34,35 @@ HRESULT WINAPI ResizePseudoConsole( ); ``` -Parameters ----------- +## Parameters *hPC* \[in\] A handle to an active psuedoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). *size* \[in\] -The dimensions of the window/buffer in count of characters that will be used for the internal buffer of this pseudoconsole. +The dimensions of the window/buffer in count of characters that will be used for the internal buffer of this pseudoconsole. -Return value ------------- +## Return value Type: **HRESULT** If this method succeeds, it returns **S_OK**. Otherwise, it returns an **HRESULT** error code. -Remarks -------- +## Remarks This function can resize the internal buffers in the pseudoconsole session to match the window/buffer size being used for display on the terminal end. This ensures that attached Command-Line Interface (CUI) applications using the [Console Functions](console-functions.md) to communicate will have the correct dimensions returned in their calls. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 10 1809 [desktop apps only]

Minimum supported server

Windows Server 2019 [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | +| Minimum supported server | Windows Server 2019 \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Pseudoconsoles](pseudoconsoles.md) diff --git a/docs/scrollconsolescreenbuffer.md b/docs/scrollconsolescreenbuffer.md index d232c1e..225fb18 100644 --- a/docs/scrollconsolescreenbuffer.md +++ b/docs/scrollconsolescreenbuffer.md @@ -41,8 +41,7 @@ api_type: Moves a block of data in a screen buffer. The effects of the move can be limited by specifying a clipping rectangle, so the contents of the console screen buffer outside the clipping rectangle are unchanged. -Syntax ------- +## Syntax ```C BOOL WINAPI ScrollConsoleScreenBuffer( @@ -54,8 +53,7 @@ BOOL WINAPI ScrollConsoleScreenBuffer( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -72,15 +70,13 @@ A [**COORD**](coord-str.md) structure that specifies the upper-left corner of th *lpFill* \[in\] A pointer to a [**CHAR\_INFO**](char-info-str.md) structure that specifies the character and color attributes to be used in filling the cells within the intersection of *lpScrollRectangle* and *lpClipRectangle* that were left empty as a result of the move. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **ScrollConsoleScreenBuffer** copies the contents of a rectangular region of a screen buffer, specified by the *lpScrollRectangle* parameter, to another area of the console screen buffer. The target rectangle has the same dimensions as the *lpScrollRectangle* rectangle with its upper-left corner at the coordinates specified by the *dwDestinationOrigin* parameter. Those parts of *lpScrollRectangle* that do not overlap with the target rectangle are filled in with the character and color attributes specified by the *lpFill* parameter. @@ -88,59 +84,24 @@ The clipping rectangle applies to changes made in both the *lpScrollRectangle* r If the scroll or target regions extend beyond the dimensions of the console screen buffer, they are clipped. For example, if *lpScrollRectangle* is the region contained by (0,0) and (19,19) and *dwDestinationOrigin* is (10,15), the target rectangle is the region contained by (10,15) and (29,34). However, if the console screen buffer is 50 characters wide and 30 characters high, the target rectangle is clipped to (10,15) and (29,29). Changes to the console screen buffer are also clipped according to *lpClipRectangle*, if the parameter specifies a [**SMALL\_RECT**](small-rect-str.md) structure. If the clipping rectangle is specified as (0,0) and (49,19), only the changes that occur in that region of the console screen buffer are made. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ScrollConsoleScreenBufferW (Unicode) and ScrollConsoleScreenBufferA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **ScrollConsoleScreenBufferW** (Unicode) and **ScrollConsoleScreenBufferA** (ANSI) | + +## See also [**CHAR\_INFO**](char-info-str.md) diff --git a/docs/scrolling-a-screen-buffer-s-contents.md b/docs/scrolling-a-screen-buffer-s-contents.md index 2c86e39..030bd1e 100644 --- a/docs/scrolling-a-screen-buffer-s-contents.md +++ b/docs/scrolling-a-screen-buffer-s-contents.md @@ -31,75 +31,74 @@ The following example shows the use of a clipping rectangle to scroll only the b int main( void ) { - HANDLE hStdout; - CONSOLE_SCREEN_BUFFER_INFO csbiInfo; - SMALL_RECT srctScrollRect, srctClipRect; - CHAR_INFO chiFill; - COORD coordDest; + HANDLE hStdout; + CONSOLE_SCREEN_BUFFER_INFO csbiInfo; + SMALL_RECT srctScrollRect, srctClipRect; + CHAR_INFO chiFill; + COORD coordDest; int i; printf("\nPrinting 20 lines for reference. "); printf("Notice that line 6 is discarded during scrolling.\n"); for(i=0; i<=20; i++) printf("%d\n", i); - - hStdout = GetStdHandle(STD_OUTPUT_HANDLE); - if (hStdout == INVALID_HANDLE_VALUE) + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + + if (hStdout == INVALID_HANDLE_VALUE) { - printf("GetStdHandle failed with %d\n", GetLastError()); + printf("GetStdHandle failed with %d\n", GetLastError()); return 1; } - - // Get the screen buffer size. - - if (!GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) + + // Get the screen buffer size. + + if (!GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) { - printf("GetConsoleScreenBufferInfo failed %d\n", GetLastError()); + printf("GetConsoleScreenBufferInfo failed %d\n", GetLastError()); return 1; } - - // The scrolling rectangle is the bottom 15 rows of the - // screen buffer. - - srctScrollRect.Top = csbiInfo.dwSize.Y - 16; - srctScrollRect.Bottom = csbiInfo.dwSize.Y - 1; - srctScrollRect.Left = 0; - srctScrollRect.Right = csbiInfo.dwSize.X - 1; - - // The destination for the scroll rectangle is one row up. - - coordDest.X = 0; - coordDest.Y = csbiInfo.dwSize.Y - 17; - - // The clipping rectangle is the same as the scrolling rectangle. - // The destination row is left unchanged. - - srctClipRect = srctScrollRect; - - // Fill the bottom row with green blanks. - - chiFill.Attributes = BACKGROUND_GREEN | FOREGROUND_RED; - chiFill.Char.AsciiChar = (char)' '; - - // Scroll up one line. - + + // The scrolling rectangle is the bottom 15 rows of the + // screen buffer. + + srctScrollRect.Top = csbiInfo.dwSize.Y - 16; + srctScrollRect.Bottom = csbiInfo.dwSize.Y - 1; + srctScrollRect.Left = 0; + srctScrollRect.Right = csbiInfo.dwSize.X - 1; + + // The destination for the scroll rectangle is one row up. + + coordDest.X = 0; + coordDest.Y = csbiInfo.dwSize.Y - 17; + + // The clipping rectangle is the same as the scrolling rectangle. + // The destination row is left unchanged. + + srctClipRect = srctScrollRect; + + // Fill the bottom row with green blanks. + + chiFill.Attributes = BACKGROUND_GREEN | FOREGROUND_RED; + chiFill.Char.AsciiChar = (char)' '; + + // Scroll up one line. + if(!ScrollConsoleScreenBuffer( - hStdout, // screen buffer handle - &srctScrollRect, // scrolling rectangle - &srctClipRect, // clipping rectangle - coordDest, // top left destination cell + hStdout, // screen buffer handle + &srctScrollRect, // scrolling rectangle + &srctClipRect, // clipping rectangle + coordDest, // top left destination cell &chiFill)) // fill character and color { - printf("ScrollConsoleScreenBuffer failed %d\n", GetLastError()); + printf("ScrollConsoleScreenBuffer failed %d\n", GetLastError()); return 1; } return 0; } ``` -## Related topics - +## Related topics [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md) diff --git a/docs/scrolling-a-screen-buffer-s-window.md b/docs/scrolling-a-screen-buffer-s-window.md index de86b50..8c1c654 100644 --- a/docs/scrolling-a-screen-buffer-s-window.md +++ b/docs/scrolling-a-screen-buffer-s-window.md @@ -28,38 +28,38 @@ The following example scrolls the view of the console screen buffer up by modify #include #include -HANDLE hStdout; +HANDLE hStdout; int ScrollByAbsoluteCoord(int iRows) { - CONSOLE_SCREEN_BUFFER_INFO csbiInfo; - SMALL_RECT srctWindow; - - // Get the current screen buffer size and window position. - - if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) + CONSOLE_SCREEN_BUFFER_INFO csbiInfo; + SMALL_RECT srctWindow; + + // Get the current screen buffer size and window position. + + if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) { - printf("GetConsoleScreenBufferInfo (%d)\n", GetLastError()); + printf("GetConsoleScreenBufferInfo (%d)\n", GetLastError()); return 0; } - - // Set srctWindow to the current window size and location. - - srctWindow = csbiInfo.srWindow; - + + // Set srctWindow to the current window size and location. + + srctWindow = csbiInfo.srWindow; + // Check whether the window is too close to the screen buffer top - - if ( srctWindow.Top >= iRows ) - { + + if ( srctWindow.Top >= iRows ) + { srctWindow.Top -= (SHORT)iRows; // move top up srctWindow.Bottom -= (SHORT)iRows; // move bottom up - if (! SetConsoleWindowInfo( - hStdout, // screen buffer handle - TRUE, // absolute coordinates - &srctWindow)) // specifies new location + if (! SetConsoleWindowInfo( + hStdout, // screen buffer handle + TRUE, // absolute coordinates + &srctWindow)) // specifies new location { - printf("SetConsoleWindowInfo (%d)\n", GetLastError()); + printf("SetConsoleWindowInfo (%d)\n", GetLastError()); return 0; } return iRows; @@ -73,32 +73,32 @@ int ScrollByAbsoluteCoord(int iRows) int ScrollByRelativeCoord(int iRows) { - CONSOLE_SCREEN_BUFFER_INFO csbiInfo; - SMALL_RECT srctWindow; + CONSOLE_SCREEN_BUFFER_INFO csbiInfo; + SMALL_RECT srctWindow; - // Get the current screen buffer window position. - - if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) + // Get the current screen buffer window position. + + if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) { - printf("GetConsoleScreenBufferInfo (%d)\n", GetLastError()); + printf("GetConsoleScreenBufferInfo (%d)\n", GetLastError()); return 0; } - + // Check whether the window is too close to the screen buffer top - - if (csbiInfo.srWindow.Top >= iRows) - { + + if (csbiInfo.srWindow.Top >= iRows) + { srctWindow.Top =- (SHORT)iRows; // move top up - srctWindow.Bottom =- (SHORT)iRows; // move bottom up - srctWindow.Left = 0; // no change - srctWindow.Right = 0; // no change - - if (! SetConsoleWindowInfo( - hStdout, // screen buffer handle + srctWindow.Bottom =- (SHORT)iRows; // move bottom up + srctWindow.Left = 0; // no change + srctWindow.Right = 0; // no change + + if (! SetConsoleWindowInfo( + hStdout, // screen buffer handle FALSE, // relative coordinates - &srctWindow)) // specifies new location + &srctWindow)) // specifies new location { - printf("SetConsoleWindowInfo (%d)\n", GetLastError()); + printf("SetConsoleWindowInfo (%d)\n", GetLastError()); return 0; } return iRows; @@ -120,7 +120,7 @@ int main( void ) for(i=0; i<=20; i++) printf("%d\n", i); - hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); if(ScrollByAbsoluteCoord(5)) _getch(); @@ -132,8 +132,7 @@ int main( void ) } ``` -## Related topics - +## Related topics [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md) diff --git a/docs/setconsoleactivescreenbuffer.md b/docs/setconsoleactivescreenbuffer.md index 9306d92..4dfe084 100644 --- a/docs/setconsoleactivescreenbuffer.md +++ b/docs/setconsoleactivescreenbuffer.md @@ -37,8 +37,7 @@ api_type: Sets the specified screen buffer to be the currently displayed console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleActiveScreenBuffer( @@ -46,69 +45,36 @@ BOOL WINAPI SetConsoleActiveScreenBuffer( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A console can have multiple screen buffers. **SetConsoleActiveScreenBuffer** determines which one is displayed. You can write to an inactive screen buffer and then use **SetConsoleActiveScreenBuffer** to display the buffer's contents. -Examples --------- +## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolecp.md b/docs/setconsolecp.md index ed89fbe..08b02c6 100644 --- a/docs/setconsolecp.md +++ b/docs/setconsolecp.md @@ -33,11 +33,9 @@ api_type: # SetConsoleCP function - Sets the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleCP( @@ -45,27 +43,24 @@ BOOL WINAPI SetConsoleCP( ); ``` -Parameters ----------- +## Parameters *wCodePageID* \[in\] The identifier of the code page to be set. For more information, see Remarks. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. To find the code pages that are installed or supported by the operating system, use the [**EnumSystemCodePages**](https://msdn.microsoft.com/library/windows/desktop/dd317825) function. The identifiers of the code pages available on the local computer are also stored in the registry under the following key: -**HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Nls\\CodePage** +`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage` However, it is better to use [**EnumSystemCodePages**](https://msdn.microsoft.com/library/windows/desktop/dd317825) to enumerate code pages because the registry can differ in different versions of Windows. @@ -73,46 +68,17 @@ To determine whether a particular code page is valid, use the [**IsValidCodePage To determine a console's current input code page, use the [**GetConsoleCP**](getconsolecp.md) function. To set and retrieve a console's output code page, use the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**GetConsoleOutputCP**](getconsoleoutputcp.md) functions. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Code Pages](console-code-pages.md) diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 7bf37c4..20384ce 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -38,8 +38,7 @@ Adds or removes an application-defined [**HandlerRoutine**](handlerroutine.md) f If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleCtrlHandler( @@ -48,8 +47,7 @@ BOOL WINAPI SetConsoleCtrlHandler( ); ``` -Parameters ----------- +## Parameters *HandlerRoutine* \[in, optional\] A pointer to the application-defined [**HandlerRoutine**](handlerroutine.md) function to be added or removed. This parameter can be **NULL**. @@ -59,15 +57,13 @@ If this parameter is **TRUE**, the handler is added; if it is **FALSE**, the han If the *HandlerRoutine* parameter is **NULL**, a **TRUE** value causes the calling process to ignore CTRL+C input, and a **FALSE** value restores normal processing of CTRL+C input. This attribute of ignoring or processing CTRL+C is inherited by child processes. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks This function provides a similar notification for console application and services that [**WM\_QUERYENDSESSION**](https://msdn.microsoft.com/library/windows/desktop/aa376890) provides for graphical applications with a message pump. You could also use this function from a graphical application, but there is no guarantee it would arrive before the notification from **WM\_QUERYENDSESSION**. @@ -91,51 +87,22 @@ If a console application loads the gdi32.dll or user32.dll library, the [**Handl To receive events when a user signs out or the device shuts down in these circumstances, create a hidden window in your console application, and then handle the [**WM\_QUERYENDSESSION**](https://msdn.microsoft.com/library/windows/desktop/aa376890) and [**WM\_ENDSESSION**](https://msdn.microsoft.com/library/windows/desktop/aa376889) window messages that the hidden window receives. You can create a hidden window by calling the [**CreateWindowEx**](https://msdn.microsoft.com/library/windows/desktop/ms632680) method with the *dwExStyle* parameter set to 0. -Examples --------- +## Examples For an example, see [Registering a Control Handler Function](registering-a-control-handler-function.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | | + +## See also [Console Control Handlers](console-control-handlers.md) diff --git a/docs/setconsolecursorinfo.md b/docs/setconsolecursorinfo.md index dff821b..fcbe0bf 100644 --- a/docs/setconsolecursorinfo.md +++ b/docs/setconsolecursorinfo.md @@ -37,8 +37,7 @@ api_type: Sets the size and visibility of the cursor for the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleCursorInfo( @@ -47,8 +46,7 @@ BOOL WINAPI SetConsoleCursorInfo( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,58 +54,27 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *lpConsoleCursorInfo* \[in\] A pointer to a [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) structure that provides the new specifications for the console screen buffer's cursor. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks When a screen buffer's cursor is visible, its appearance can vary, ranging from completely filling a character cell to showing up as a horizontal line at the bottom of the cell. The **dwSize** member of the [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) structure specifies the percentage of a character cell that is filled by the cursor. If this member is less than 1 or greater than 100, **SetConsoleCursorInfo** fails. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolecursorposition.md b/docs/setconsolecursorposition.md index 9dc80f8..6a769cd 100644 --- a/docs/setconsolecursorposition.md +++ b/docs/setconsolecursorposition.md @@ -37,8 +37,7 @@ api_type: Sets the cursor position in the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleCursorPosition( @@ -47,8 +46,7 @@ BOOL WINAPI SetConsoleCursorPosition( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,65 +54,33 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *dwCursorPosition* \[in\] A [**COORD**](coord-str.md) structure that specifies the new cursor position, in characters. The coordinates are the column and row of a screen buffer character cell. The coordinates must be within the boundaries of the console screen buffer. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The cursor position determines where characters written by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md) function, or echoed by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) function, are displayed. To determine the current position of the cursor, use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function. If the new cursor position is not within the boundaries of the console screen buffer's window, the window origin changes to make the cursor visible. -Examples --------- +## Examples For an example, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsoledisplaymode.md b/docs/setconsoledisplaymode.md index be4564f..0ab1e6f 100644 --- a/docs/setconsoledisplaymode.md +++ b/docs/setconsoledisplaymode.md @@ -33,8 +33,7 @@ api_type: Sets the display mode of the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleDisplayMode( @@ -44,8 +43,7 @@ BOOL WINAPI SetConsoleDisplayMode( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. @@ -53,85 +51,31 @@ A handle to the console screen buffer. *dwFlags* \[in\] The display mode of the console. This parameter can be one or more of the following values. - ---- - - - - - - - - - - - - - - - - -
ValueMeaning
-CONSOLE_FULLSCREEN_MODE -1

Text is displayed in full-screen mode.

-CONSOLE_WINDOWED_MODE -2

Text is displayed in a console window.

- -  +| Value | Meaning | +|-|-| +| **CONSOLE_FULLSCREEN_MODE** 1 | Text is displayed in full-screen mode. | +| **CONSOLE_WINDOWED_MODE** 2 | Text is displayed in a console window. | *lpNewScreenBufferDimensions* \[out, optional\] A pointer to a [**COORD**](coord-str.md) structure that receives the new dimensions of the screen buffer, in characters. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows XP \[desktop apps only\] | +| Minimum supported server | Windows Server 2003 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolehistoryinfo.md b/docs/setconsolehistoryinfo.md index 7c89f40..c83d626 100644 --- a/docs/setconsolehistoryinfo.md +++ b/docs/setconsolehistoryinfo.md @@ -33,8 +33,7 @@ api_type: Sets the history settings for the calling process's console. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleHistoryInfo( @@ -42,64 +41,32 @@ BOOL WINAPI SetConsoleHistoryInfo( ); ``` -Parameters ----------- +## Parameters *lpConsoleHistoryInfo* \[in\] A pointer to a [**CONSOLE\_HISTORY\_INFO**](console-history-info.md) structure that contains the history settings for the process's console. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the calling process is not a console process, the function fails and sets the last error code to **ERROR\_ACCESS\_DENIED**. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index f944f33..8557eb4 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -36,8 +36,7 @@ api_type: Sets the input mode of a console's input buffer or the output mode of a console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleMode( @@ -46,229 +45,43 @@ BOOL WINAPI SetConsoleMode( ); ``` -Parameters ----------- +## Parameters *hConsoleHandle* \[in\] A handle to the console input buffer or a console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). *dwMode* \[in\] -The input or output mode to be set. If the *hConsoleHandle* parameter is an input handle, the mode can be one or more of the following values. When a console is created, all input modes except **ENABLE\_WINDOW\_INPUT** are enabled by default. +The input or output mode to be set. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-ENABLE_ECHO_INPUT -0x0004

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_EXTENDED_FLAGS -0x0080

Required to enable or disable extended flags. See ENABLE_INSERT_MODE and ENABLE_QUICK_EDIT_MODE.

-ENABLE_INSERT_MODE -0x0020

When enabled, text entered in a console window will be inserted at the current cursor location and all text following that location will not be overwritten. When disabled, all following text will be overwritten.

-

To enable this mode, use ENABLE_INSERT_MODE | ENABLE_EXTENDED_FLAGS. To disable this mode, use ENABLE_EXTENDED_FLAGS without this flag.

-ENABLE_LINE_INPUT -0x0002

The ReadFile or ReadConsole function returns only when a carriage return character ('\r' or 0x0D) is read. If this mode is disabled, the functions return when one or more characters are available.

-ENABLE_MOUSE_INPUT -0x0010

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. Use ReadConsoleInput to receive these events.

-ENABLE_PROCESSED_INPUT -0x0001

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 line feed characters are handled by the system.

-ENABLE_QUICK_EDIT_MODE -0x0040

This flag enables the user to use the mouse to select and edit text.

-

To enable this mode, use ENABLE_QUICK_EDIT_MODE | ENABLE_EXTENDED_FLAGS. To disable this mode, use ENABLE_EXTENDED_FLAGS without this flag.

-ENABLE_WINDOW_INPUT -0x0008

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_VIRTUAL_TERMINAL_INPUT -0x0200

Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into Console Virtual Terminal Sequences that can be retrieved by a supporting application through ReadFile or ReadConsole functions.

-

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences.

+[!INCLUDE [console-mode-flags](./includes/console-mode-flags.md)] -  - -If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one or more of the following values. When a screen buffer is created, both output modes are enabled by default. - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-ENABLE_PROCESSED_OUTPUT -0x0001

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 ('\b' or 0x08), tab ('\t' or 0x09), bell ('\a' or 0x07), carriage return ('\r' or 0x0D), and line feed ('\n' or 0x0A) characters are processed.

-ENABLE_WRAP_AT_EOL_OUTPUT -0x0002

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 console screen buffer to scroll up (discarding the top row of the console screen buffer) when the cursor advances beyond the last row in the console screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.

-ENABLE_VIRTUAL_TERMINAL_PROCESSING -0x0004

When writing with WriteFile or WriteConsole, characters are parsed for "ANSI escape", "virtual terminal", and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the Console APIs. For more information, see Console Virtual Terminal Sequences.

-DISABLE_NEWLINE_AUTO_RETURN -0x0008

When writing with WriteFile or WriteConsole, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

-

Normally when ENABLE_WRAP_AT_EOL_OUTPUT is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if ENABLE_WRAP_AT_EOL_OUTPUT was off, but the next printable character will be printed as if ENABLE_WRAP_AT_EOL_OUTPUT is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

-

The typical usage of this flag is intended in conjunction with setting ENABLE_VIRTUAL_TERMINAL_PROCESSING to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior.

-ENABLE_LVB_GRID_WORLDWIDE -0x0010

The APIs for writing character attributes including WriteConsoleOutput and WriteConsoleOutputAttribute allow the usage of flags from character attributes to adjust the color of the foreground and background of text. Additionally, a range of DBCS flags was specified with the COMMON_LVB prefix. Historically, these flags only functioned in DBCS code pages for Chinese, Japanese, and Korean languages.

-

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (swap foreground and background colors) can be useful for other languages to emphasize portions of output.

-

Setting this console mode flag will allow these attributes to be used in every code page on every language.

-

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

-

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via Console Virtual Terminal Sequences.

- -  - -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## 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**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a [**HandlerRoutine**](handlerroutine.md) 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**](readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md). - -The **ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT** modes only affect processes using [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md). +[!INCLUDE [console-mode-remarks](./includes/console-mode-remarks.md)] To determine the current mode of a console input buffer or a screen buffer, use the [**GetConsoleMode**](getconsolemode.md) function. -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
+## Requirements -## See also +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsoleoutputcp.md b/docs/setconsoleoutputcp.md index a54c69c..4d0ef58 100644 --- a/docs/setconsoleoutputcp.md +++ b/docs/setconsoleoutputcp.md @@ -35,8 +35,7 @@ api_type: Sets the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleOutputCP( @@ -44,21 +43,18 @@ BOOL WINAPI SetConsoleOutputCP( ); ``` -Parameters ----------- +## Parameters *wCodePageID* \[in\] The identifier of the code page to set. For more information, see Remarks. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. @@ -66,53 +62,24 @@ If the current font is a fixed-pitch Unicode font, **SetConsoleOutputCP** change To find the code pages that are installed or supported by the operating system, use the [EnumSystemCodePages](https://go.microsoft.com/fwlink/p/?linkid=178051) function. The identifiers of the code pages available on the local computer are also stored in the registry under the following key: -**HKEY\_LOCAL\_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Nls\\CodePage** +`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage` However, it is better to use [EnumSystemCodePages](https://go.microsoft.com/fwlink/p/?linkid=178051) to enumerate code pages because the registry can differ in different versions of Windows. To determine whether a particular code page is valid, use the [IsValidCodePage](https://go.microsoft.com/fwlink/p/?linkid=178053) function. To retrieve more information about a code page, including its name, use the [**GetCPInfoEx**](https://msdn.microsoft.com/library/windows/desktop/dd318081) function. For a list of available code page identifiers, see [Code Page Identifiers](https://msdn.microsoft.com/library/windows/desktop/dd317756). To determine a console's current output code page, use the [**GetConsoleOutputCP**](getconsoleoutputcp.md) function. To set and retrieve a console's input code page, use the [**SetConsoleCP**](setconsolecp.md) and [**GetConsoleCP**](getconsolecp.md) functions. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Code Pages](console-code-pages.md) diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index fb25c80..ecd7a77 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -36,8 +36,7 @@ api_type: Sets extended information about the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleScreenBufferInfoEx( @@ -46,8 +45,7 @@ BOOL WINAPI SetConsoleScreenBufferInfoEx( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -55,53 +53,23 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE *lpConsoleScreenBufferInfoEx* \[in\] A [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) structure that contains the console screen buffer information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolescreenbuffersize.md b/docs/setconsolescreenbuffersize.md index d273c41..0dd8ceb 100644 --- a/docs/setconsolescreenbuffersize.md +++ b/docs/setconsolescreenbuffersize.md @@ -37,8 +37,7 @@ api_type: Changes the size of the specified console screen buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleScreenBufferSize( @@ -47,8 +46,7 @@ BOOL WINAPI SetConsoleScreenBufferSize( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,53 +54,23 @@ A handle to the console screen buffer. The handle must have the **GENERIC\_READ* *dwSize* \[in\] A [**COORD**](coord-str.md) structure that specifies the new size of the console screen buffer, in character rows and columns. The specified width and height cannot be less than the width and height of the console screen buffer's window. The specified dimensions also cannot be less than the minimum size allowed by the system. This minimum depends on the current font size for the console (selected by the user) and the **SM\_CXMIN** and **SM\_CYMIN** values returned by the [**GetSystemMetrics**](https://msdn.microsoft.com/library/windows/desktop/ms724385) function. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsoletextattribute.md b/docs/setconsoletextattribute.md index 55d4964..6a1b6b1 100644 --- a/docs/setconsoletextattribute.md +++ b/docs/setconsoletextattribute.md @@ -37,8 +37,7 @@ api_type: Sets the attributes of characters written to the console screen buffer by the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md) function, or echoed by the [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) function. This function affects text written after the function call. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleTextAttribute( @@ -47,72 +46,39 @@ BOOL WINAPI SetConsoleTextAttribute( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). *wAttributes* \[in\] -The [character attributes](console-screen-buffers.md#_win32_font_attributes). +The [character attributes](console-screen-buffers.md#character-attributes). -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To determine the current color attributes of a screen buffer, call the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function. -Examples --------- +## Examples For an example, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsoletitle.md b/docs/setconsoletitle.md index 16d0546..7fcabf6 100644 --- a/docs/setconsoletitle.md +++ b/docs/setconsoletitle.md @@ -53,8 +53,7 @@ api_type: Sets the title for the current console window. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleTitle( @@ -62,28 +61,24 @@ BOOL WINAPI SetConsoleTitle( ); ``` -Parameters ----------- +## Parameters *lpConsoleTitle* \[in\] The string to be displayed in the title bar of the console window. The total size must be less than 64K. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks When the process terminates, the system restores the original console title. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] -Examples --------- +## Examples The following example shows how to retrieve and modify the console title. @@ -121,52 +116,18 @@ int main( void ) } ``` -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

SetConsoleTitleW (Unicode) and SetConsoleTitleA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **SetConsoleTitleW** (Unicode) and **SetConsoleTitleA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setconsolewindowinfo.md b/docs/setconsolewindowinfo.md index 8b4a6c0..5148323 100644 --- a/docs/setconsolewindowinfo.md +++ b/docs/setconsolewindowinfo.md @@ -37,8 +37,7 @@ api_type: Sets the current size and position of a console screen buffer's window. -Syntax ------- +## Syntax ```C BOOL WINAPI SetConsoleWindowInfo( @@ -48,8 +47,7 @@ BOOL WINAPI SetConsoleWindowInfo( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_READ** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -60,15 +58,13 @@ If this parameter is **TRUE**, the coordinates specify the new upper-left and lo *lpConsoleWindow* \[in\] A pointer to a [**SMALL\_RECT**](small-rect-str.md) structure that specifies the new upper-left and lower-right corners of the window. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The function fails if the specified window rectangle extends beyond the boundaries of the console screen buffer. This means that the **Top** and **Left** members of the *lpConsoleWindow* rectangle (or the calculated top and left coordinates, if *bAbsolute* is FALSE) cannot be less than zero. Similarly, the **Bottom** and **Right** members (or the calculated bottom and right coordinates) cannot be greater than (screen buffer height – 1) and (screen buffer width – 1), respectively. The function also fails if the **Right** member (or calculated right coordinate) is less than or equal to the **Left** member (or calculated left coordinate) or if the **Bottom** member (or calculated bottom coordinate) is less than or equal to the **Top** member (or calculated top coordinate). @@ -78,51 +74,21 @@ To determine the current size and position of a screen buffer's window, use the **SetConsoleWindowInfo** can be used to scroll the contents of the console screen buffer by shifting the position of the window rectangle without changing its size. -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setcurrentconsolefontex.md b/docs/setcurrentconsolefontex.md index d442842..128c42a 100644 --- a/docs/setcurrentconsolefontex.md +++ b/docs/setcurrentconsolefontex.md @@ -33,8 +33,7 @@ api_type: Sets extended information about the current console font. -Syntax ------- +## Syntax ```C BOOL WINAPI SetCurrentConsoleFontEx( @@ -44,8 +43,7 @@ BOOL WINAPI SetCurrentConsoleFontEx( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -56,58 +54,27 @@ If this parameter is **TRUE**, font information is set for the maximum window si *lpConsoleCurrentFontEx* \[in\] A pointer to a [**CONSOLE\_FONT\_INFOEX**](console-font-infoex.md) structure that contains the font information. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

ConsoleApi3.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows Vista \[desktop apps only\] | +| Minimum supported server | Windows Server 2008 \[desktop apps only\] | +| Header | ConsoleApi3.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/setstdhandle.md b/docs/setstdhandle.md index 5f37c92..aeefdfd 100644 --- a/docs/setstdhandle.md +++ b/docs/setstdhandle.md @@ -37,8 +37,7 @@ api_type: Sets the handle for the specified standard device (standard input, standard output, or standard error). -Syntax ------- +## Syntax ```cpp BOOL WINAPI SetStdHandle( @@ -47,107 +46,45 @@ BOOL WINAPI SetStdHandle( ); ``` -Parameters ----------- +## Parameters *nStdHandle* \[in\] The standard device for which the handle is to be set. This parameter can be one of the following values. - ---- - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
-STD_INPUT_HANDLE -(DWORD)-10

The standard input device.

-STD_OUTPUT_HANDLE -(DWORD)-11

The standard output device.

-STD_ERROR_HANDLE -(DWORD)-12

The standard error device.

- -  +| Value | Meaning | +|-|-| +| **STD_INPUT_HANDLE** (DWORD) -10 | The standard input device. Initially, this is the console input buffer, `CONIN$`. | +| **STD_OUTPUT_HANDLE** (DWORD) -11 | The standard output device. Initially, this is the active console screen buffer, `CONOUT$`. | +| **STD_ERROR_HANDLE** (DWORD) -12 | The standard error device. Initially, this is the active console screen buffer, `CONOUT$`. | *hHandle* \[in\] The handle for the standard device. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The standard handles of a process may have been redirected by a call to **SetStdHandle**, in which case [**GetStdHandle**](getstdhandle.md) will return the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the [**CreateFile**](https://msdn.microsoft.com/library/windows/desktop/aa363858) function to get a handle to a console's input buffer. Similarly, you can specify the CONOUT$ value to get a handle to the console's active screen buffer. -Examples --------- +## Examples For an example, see [Creating a Child Process with Redirected Input and Output](https://msdn.microsoft.com/library/windows/desktop/ms682499). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ProcessEnv.h (via Winbase.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ProcessEnv.h (via Winbase.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also [Console Functions](console-functions.md) diff --git a/docs/small-rect-str.md b/docs/small-rect-str.md index efeb443..12fe77e 100644 --- a/docs/small-rect-str.md +++ b/docs/small-rect-str.md @@ -23,7 +23,7 @@ topic_type: api_name: - SMALL_RECT api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -32,8 +32,7 @@ api_type: Defines the coordinates of the upper left and lower right corners of a rectangle. -Syntax ------- +## Syntax ```C typedef struct _SMALL_RECT { @@ -44,8 +43,7 @@ typedef struct _SMALL_RECT { } SMALL_RECT; ``` -Members -------- +## Members **Left** The x-coordinate of the upper left corner of the rectangle. @@ -59,42 +57,23 @@ The x-coordinate of the lower right corner of the rectangle. **Bottom** The y-coordinate of the lower right corner of the rectangle. -Remarks -------- +## Remarks This structure is used by console functions to specify rectangular areas of console screen buffers, where the coordinates specify the rows and columns of screen-buffer character cells. -Examples --------- +## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | + +## See also [**RECT**](https://msdn.microsoft.com/library/windows/desktop/dd162897) diff --git a/docs/using-the-high-level-input-and-output-functions.md b/docs/using-the-high-level-input-and-output-functions.md index 1ca4272..ebf91d1 100644 --- a/docs/using-the-high-level-input-and-output-functions.md +++ b/docs/using-the-high-level-input-and-output-functions.md @@ -26,180 +26,180 @@ The example assumes that the default I/O modes are in effect initially for the f The example's `NewLine` function is used when line input mode is disabled. It handles carriage returns by moving the cursor position to the first cell of the next row. If the cursor is already in the last row of the console screen buffer, the contents of the console screen buffer are scrolled up one line. ```C -#include - -void NewLine(void); -void ScrollScreenBuffer(HANDLE, INT); - -HANDLE hStdout, hStdin; -CONSOLE_SCREEN_BUFFER_INFO csbiInfo; - -int main(void) -{ +#include + +void NewLine(void); +void ScrollScreenBuffer(HANDLE, INT); + +HANDLE hStdout, hStdin; +CONSOLE_SCREEN_BUFFER_INFO csbiInfo; + +int main(void) +{ LPSTR lpszPrompt1 = "Type a line and press Enter, or q to quit: "; LPSTR lpszPrompt2 = "Type any key, or q to quit: "; - CHAR chBuffer[256]; - DWORD cRead, cWritten, fdwMode, fdwOldMode; - WORD wOldColorAttrs; + CHAR chBuffer[256]; + DWORD cRead, cWritten, fdwMode, fdwOldMode; + WORD wOldColorAttrs; - // Get handles to STDIN and STDOUT. + // Get handles to STDIN and STDOUT. - hStdin = GetStdHandle(STD_INPUT_HANDLE); - hStdout = GetStdHandle(STD_OUTPUT_HANDLE); - if (hStdin == INVALID_HANDLE_VALUE || - hStdout == INVALID_HANDLE_VALUE) + hStdin = GetStdHandle(STD_INPUT_HANDLE); + hStdout = GetStdHandle(STD_OUTPUT_HANDLE); + if (hStdin == INVALID_HANDLE_VALUE || + hStdout == INVALID_HANDLE_VALUE) { - MessageBox(NULL, TEXT("GetStdHandle"), TEXT("Console Error"), + MessageBox(NULL, TEXT("GetStdHandle"), TEXT("Console Error"), MB_OK); return 1; } - // Save the current text colors. + // Save the current text colors. - if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) + if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) { - MessageBox(NULL, TEXT("GetConsoleScreenBufferInfo"), - TEXT("Console Error"), MB_OK); + MessageBox(NULL, TEXT("GetConsoleScreenBufferInfo"), + TEXT("Console Error"), MB_OK); return 1; } - wOldColorAttrs = csbiInfo.wAttributes; + wOldColorAttrs = csbiInfo.wAttributes; - // Set the text attributes to draw red text on black background. + // Set the text attributes to draw red text on black background. - if (! SetConsoleTextAttribute(hStdout, FOREGROUND_RED | + if (! SetConsoleTextAttribute(hStdout, FOREGROUND_RED | FOREGROUND_INTENSITY)) { - MessageBox(NULL, TEXT("SetConsoleTextAttribute"), + MessageBox(NULL, TEXT("SetConsoleTextAttribute"), TEXT("Console Error"), MB_OK); return 1; } - // Write to STDOUT and read from STDIN by using the default - // modes. Input is echoed automatically, and ReadFile - // does not return until a carriage return is typed. - // - // The default input modes are line, processed, and echo. - // The default output modes are processed and wrap at EOL. - - while (1) - { - if (! WriteFile( - hStdout, // output handle - lpszPrompt1, // prompt string - lstrlenA(lpszPrompt1), // string length - &cWritten, // bytes written - NULL) ) // not overlapped + // Write to STDOUT and read from STDIN by using the default + // modes. Input is echoed automatically, and ReadFile + // does not return until a carriage return is typed. + // + // The default input modes are line, processed, and echo. + // The default output modes are processed and wrap at EOL. + + while (1) + { + if (! WriteFile( + hStdout, // output handle + lpszPrompt1, // prompt string + lstrlenA(lpszPrompt1), // string length + &cWritten, // bytes written + NULL) ) // not overlapped { - MessageBox(NULL, TEXT("WriteFile"), TEXT("Console Error"), - MB_OK); + MessageBox(NULL, TEXT("WriteFile"), TEXT("Console Error"), + MB_OK); return 1; } - if (! ReadFile( - hStdin, // input handle - chBuffer, // buffer to read into - 255, // size of buffer - &cRead, // actual bytes read - NULL) ) // not overlapped - break; - if (chBuffer[0] == 'q') break; - } + if (! ReadFile( + hStdin, // input handle + chBuffer, // buffer to read into + 255, // size of buffer + &cRead, // actual bytes read + NULL) ) // not overlapped + break; + if (chBuffer[0] == 'q') break; + } - // Turn off the line input and echo input modes + // Turn off the line input and echo input modes - if (! GetConsoleMode(hStdin, &fdwOldMode)) + if (! GetConsoleMode(hStdin, &fdwOldMode)) { MessageBox(NULL, TEXT("GetConsoleMode"), TEXT("Console Error"), - MB_OK); + MB_OK); return 1; } - fdwMode = fdwOldMode & - ~(ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT); - if (! SetConsoleMode(hStdin, fdwMode)) + fdwMode = fdwOldMode & + ~(ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT); + if (! SetConsoleMode(hStdin, fdwMode)) { MessageBox(NULL, TEXT("SetConsoleMode"), TEXT("Console Error"), - MB_OK); + MB_OK); return 1; } // ReadFile returns when any input is available. - // WriteFile is used to echo input. + // WriteFile is used to echo input. NewLine(); - while (1) - { - if (! WriteFile( - hStdout, // output handle - lpszPrompt2, // prompt string - lstrlenA(lpszPrompt2), // string length - &cWritten, // bytes written - NULL) ) // not overlapped + while (1) + { + if (! WriteFile( + hStdout, // output handle + lpszPrompt2, // prompt string + lstrlenA(lpszPrompt2), // string length + &cWritten, // bytes written + NULL) ) // not overlapped { - MessageBox(NULL, TEXT("WriteFile"), TEXT("Console Error"), + MessageBox(NULL, TEXT("WriteFile"), TEXT("Console Error"), MB_OK); return 1; } - if (! ReadFile(hStdin, chBuffer, 1, &cRead, NULL)) - break; + if (! ReadFile(hStdin, chBuffer, 1, &cRead, NULL)) + break; if (chBuffer[0] == '\r') NewLine(); - else if (! WriteFile(hStdout, chBuffer, cRead, + else if (! WriteFile(hStdout, chBuffer, cRead, &cWritten, NULL)) break; else NewLine(); - if (chBuffer[0] == 'q') break; - } + if (chBuffer[0] == 'q') break; + } - // Restore the original console mode. + // Restore the original console mode. SetConsoleMode(hStdin, fdwOldMode); - // Restore the original text colors. + // Restore the original text colors. SetConsoleTextAttribute(hStdout, wOldColorAttrs); return 0; } -// The NewLine function handles carriage returns when the processed -// input mode is disabled. It gets the current cursor position -// and resets it to the first cell of the next row. - -void NewLine(void) -{ - if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) +// The NewLine function handles carriage returns when the processed +// input mode is disabled. It gets the current cursor position +// and resets it to the first cell of the next row. + +void NewLine(void) +{ + if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo)) { - MessageBox(NULL, TEXT("GetConsoleScreenBufferInfo"), - TEXT("Console Error"), MB_OK); + MessageBox(NULL, TEXT("GetConsoleScreenBufferInfo"), + TEXT("Console Error"), MB_OK); return; } - csbiInfo.dwCursorPosition.X = 0; + csbiInfo.dwCursorPosition.X = 0; - // If it is the last line in the screen buffer, scroll - // the buffer up. + // If it is the last line in the screen buffer, scroll + // the buffer up. - if ((csbiInfo.dwSize.Y-1) == csbiInfo.dwCursorPosition.Y) - { - ScrollScreenBuffer(hStdout, 1); - } + if ((csbiInfo.dwSize.Y-1) == csbiInfo.dwCursorPosition.Y) + { + ScrollScreenBuffer(hStdout, 1); + } - // Otherwise, advance the cursor to the next line. + // Otherwise, advance the cursor to the next line. - else csbiInfo.dwCursorPosition.Y += 1; - - if (! SetConsoleCursorPosition(hStdout, - csbiInfo.dwCursorPosition)) + else csbiInfo.dwCursorPosition.Y += 1; + + if (! SetConsoleCursorPosition(hStdout, + csbiInfo.dwCursorPosition)) { - MessageBox(NULL, TEXT("SetConsoleCursorPosition"), - TEXT("Console Error"), MB_OK); + MessageBox(NULL, TEXT("SetConsoleCursorPosition"), + TEXT("Console Error"), MB_OK); return; } -} +} void ScrollScreenBuffer(HANDLE h, INT x) { @@ -209,31 +209,31 @@ void ScrollScreenBuffer(HANDLE h, INT x) srctScrollRect.Left = 0; srctScrollRect.Top = 1; - srctScrollRect.Right = csbiInfo.dwSize.X - (SHORT)x; - srctScrollRect.Bottom = csbiInfo.dwSize.Y - (SHORT)x; - - // The destination for the scroll rectangle is one row up. - - coordDest.X = 0; - coordDest.Y = 0; - - // The clipping rectangle is the same as the scrolling rectangle. - // The destination row is left unchanged. - - srctClipRect = srctScrollRect; - - // Set the fill character and attributes. - - chiFill.Attributes = FOREGROUND_RED|FOREGROUND_INTENSITY; - chiFill.Char.AsciiChar = (char)' '; - - // Scroll up one line. - - ScrollConsoleScreenBuffer( - h, // screen buffer handle - &srctScrollRect, // scrolling rectangle - &srctClipRect, // clipping rectangle - coordDest, // top left destination cell - &chiFill); // fill character and color + srctScrollRect.Right = csbiInfo.dwSize.X - (SHORT)x; + srctScrollRect.Bottom = csbiInfo.dwSize.Y - (SHORT)x; + + // The destination for the scroll rectangle is one row up. + + coordDest.X = 0; + coordDest.Y = 0; + + // The clipping rectangle is the same as the scrolling rectangle. + // The destination row is left unchanged. + + srctClipRect = srctScrollRect; + + // Set the fill character and attributes. + + chiFill.Attributes = FOREGROUND_RED|FOREGROUND_INTENSITY; + chiFill.Char.AsciiChar = (char)' '; + + // Scroll up one line. + + ScrollConsoleScreenBuffer( + h, // screen buffer handle + &srctScrollRect, // scrolling rectangle + &srctClipRect, // clipping rectangle + coordDest, // top left destination cell + &chiFill); // fill character and color } ``` diff --git a/docs/window-and-screen-buffer-size.md b/docs/window-and-screen-buffer-size.md index 014dd54..75de0de 100644 --- a/docs/window-and-screen-buffer-size.md +++ b/docs/window-and-screen-buffer-size.md @@ -17,9 +17,11 @@ ms.assetid: 55246039-31eb-41ca-ad8e-d314cb508644 # Window and Screen Buffer Size - The size of a screen buffer is expressed in terms of a coordinate grid based on character cells. The width is the number of character cells in each row, and the height is the number of rows. Associated with each screen buffer is a window that determines the size and location of the rectangular portion of the console screen buffer displayed in the console window. A screen buffer's window is defined by specifying the character-cell coordinates of the upper left and lower right cells of the window's rectangle. +> [!NOTE] +> In the **[virtual terminal sequences](console-virtual-terminal-sequences.md)** world, the size of the window and the size of the screen buffer are fixed to the same value. The terminal handles any scrollback region that would be the equivalent of a console with a screen buffer size larger than its window size. That content belongs to the terminal and is generally no longer a part of the addressable area. For more information, please see our comparison of the **[classic console functions versus virtual terminal sequences](classic-vs-vt.md)**. + A screen buffer can be any size, limited only by available memory. The dimensions of a screen buffer's window cannot exceed the corresponding dimensions of either the console screen buffer or the maximum window that can fit on the screen based on the current font size (controlled exclusively by the user). The [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function returns the following information about a screen buffer and its window: diff --git a/docs/window-buffer-size-record-str.md b/docs/window-buffer-size-record-str.md index 4175c5c..de4a906 100644 --- a/docs/window-buffer-size-record-str.md +++ b/docs/window-buffer-size-record-str.md @@ -26,7 +26,7 @@ topic_type: api_name: - WINDOW_BUFFER_SIZE_RECORD api_location: -- Wincon.h +- WinCon.h api_type: - HeaderDef --- @@ -35,8 +35,7 @@ api_type: Describes a change in the size of the console screen buffer. -Syntax ------- +## Syntax ```C typedef struct _WINDOW_BUFFER_SIZE_RECORD { @@ -44,48 +43,28 @@ typedef struct _WINDOW_BUFFER_SIZE_RECORD { } WINDOW_BUFFER_SIZE_RECORD; ``` -Members -------- +## Members **dwSize** A [**COORD**](coord-str.md) structure that contains the size of the console screen buffer, in character cell columns and rows. -Remarks -------- +## Remarks Buffer size events are placed in the input buffer when the console is in window-aware mode (**ENABLE\_WINDOW\_INPUT**). -Examples --------- +## Examples For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

WinConTypes.h (via Wincon.h, include Windows.h)
- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | WinConTypes.h (via WinCon.h, include Windows.h) | + +## See also [**COORD**](coord-str.md) diff --git a/docs/writeconsole.md b/docs/writeconsole.md index 00f2efe..d66b0c3 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -44,8 +44,7 @@ api_type: Writes a character string to a console screen buffer beginning at the current cursor location. -Syntax ------- +## Syntax ```C BOOL WINAPI WriteConsole( @@ -57,8 +56,7 @@ BOOL WINAPI WriteConsole( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -72,18 +70,16 @@ The number of characters to be written. If the total size of the specified numbe *lpNumberOfCharsWritten* \[out, optional\] A pointer to a variable that receives the number of characters actually written. -*lpReserved* +*lpReserved* Reserved; must be **NULL**. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks The **WriteConsole** function writes characters to the console screen buffer at the current cursor position. The cursor position advances as characters are written. The [**SetConsoleCursorPosition**](setconsolecursorposition.md) function sets the current cursor position. @@ -91,7 +87,7 @@ Characters are written using the foreground and background color attributes asso All of the input modes that affect the behavior of the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) function have the same effect on **WriteConsole**. To retrieve and set the output modes of a console screen buffer, use the [**GetConsoleMode**](getconsolemode.md) and [**SetConsoleMode**](setconsolemode.md) functions. -The **WriteConsole** function uses either Unicode characters or ANSI characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] **WriteConsole** fails if it is used with a standard handle that is redirected to a file. If an application processes multilingual output that can be redirected, determine whether the output handle is a console handle (one method is to call the [**GetConsoleMode**](getconsolemode.md) function and check whether it succeeds). If the handle is a console handle, call **WriteConsole**. If the handle is not a console handle, the output is redirected and you should call [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) to perform the I/O. Be sure to prefix a Unicode plain text file with a byte order mark. For more information, see [Using Byte Order Marks](https://msdn.microsoft.com/library/windows/desktop/dd374101). @@ -99,52 +95,18 @@ Although an application can use **WriteConsole** in ANSI mode to write ANSI char When virtual terminal escape sequences are not enabled, console functions can provide equivalent functionality. For more information, see [**SetCursorPos**](https://msdn.microsoft.com/library/windows/desktop/ms648394(v=vs.85).aspx), [**SetConsoleTextAttribute**](setconsoletextattribute.md), and [**GetConsoleCursorInfo**](getconsolecursorinfo.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

WriteConsoleW (Unicode) and WriteConsoleA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **WriteConsoleW** (Unicode) and **WriteConsoleA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/writeconsoleinput.md b/docs/writeconsoleinput.md index d2c4ba0..2a9f2ba 100644 --- a/docs/writeconsoleinput.md +++ b/docs/writeconsoleinput.md @@ -45,8 +45,7 @@ api_type: Writes data directly to the console input buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI WriteConsoleInput( @@ -57,8 +56,7 @@ BOOL WINAPI WriteConsoleInput( ); ``` -Parameters ----------- +## Parameters *hConsoleInput* \[in\] A handle to the console input buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -72,66 +70,30 @@ The number of input records to be written. *lpNumberOfEventsWritten* \[out\] A pointer to a variable that receives the number of input records actually written. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **WriteConsoleInput** places input records into the input buffer behind any pending events in the buffer. The input buffer grows dynamically, if necessary, to hold as many events as are written. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

WriteConsoleInputW (Unicode) and WriteConsoleInputA (ANSI)

- -## See also +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **WriteConsoleInputW** (Unicode) and **WriteConsoleInputA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index 6db7022..cb481e6 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -43,8 +43,7 @@ api_type: Writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer. -Syntax ------- +## Syntax ```C BOOL WINAPI WriteConsoleOutput( @@ -56,8 +55,7 @@ BOOL WINAPI WriteConsoleOutput( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -74,15 +72,13 @@ The coordinates of the upper-left cell in the buffer pointed to by the *lpBuffer *lpWriteRegion* \[in, out\] A pointer to a [**SMALL\_RECT**](small-rect-str.md) structure. On input, the structure members specify the upper-left and lower-right coordinates of the console screen buffer rectangle to write to. On output, the structure members specify the actual rectangle that was used. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks **WriteConsoleOutput** treats the source buffer and the destination screen buffer as two-dimensional arrays (columns and rows of character cells). The rectangle pointed to by the *lpWriteRegion* parameter specifies the size and location of the block to be written to in the console screen buffer. A rectangle of the same size is located with its upper-left cell at the coordinates of the *dwBufferCoord* parameter in the *lpBuffer* array. Data from the cells that are in the intersection of this rectangle and the source buffer rectangle (whose dimensions are specified by the *dwBufferSize* parameter) is written to the destination rectangle. @@ -94,59 +90,24 @@ If the rectangle specified by *lpWriteRegion* lies completely outside the bounda **WriteConsoleOutput** has no effect on the cursor position. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] -Examples --------- +## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

WriteConsoleOutputW (Unicode) and WriteConsoleOutputA (ANSI)

- -## See also +## Requirements +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **WriteConsoleOutputW** (Unicode) and **WriteConsoleOutputA** (ANSI) | + +## See also [Console Functions](console-functions.md) diff --git a/docs/writeconsoleoutputattribute.md b/docs/writeconsoleoutputattribute.md index d914f32..1766775 100644 --- a/docs/writeconsoleoutputattribute.md +++ b/docs/writeconsoleoutputattribute.md @@ -33,11 +33,9 @@ api_type: # WriteConsoleOutputAttribute function - Copies a number of character attributes to consecutive cells of a console screen buffer, beginning at a specified location. -Syntax ------- +## Syntax ```C BOOL WINAPI WriteConsoleOutputAttribute( @@ -49,14 +47,13 @@ BOOL WINAPI WriteConsoleOutputAttribute( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). *lpAttribute* \[in\] -The attributes to be used when writing to the console screen buffer. For more information, see [Character Attributes](console-screen-buffers.md#_win32_font_attributes). +The attributes to be used when writing to the console screen buffer. For more information, see [Character Attributes](console-screen-buffers.md#character-attributes). *nLength* \[in\] The number of screen buffer character cells to which the attributes will be copied. @@ -67,60 +64,29 @@ A [**COORD**](coord-str.md) structure that specifies the character coordinates o *lpNumberOfAttrsWritten* \[out\] A pointer to a variable that receives the number of attributes actually written to the console screen buffer. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of attributes to be written to extends beyond the end of the specified row in the console screen buffer, attributes are written to the next row. If the number of attributes to be written to extends beyond the end of the console screen buffer, the attributes are written up to the end of the console screen buffer. The character values at the positions written to are not changed. -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll
- -## See also +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +## See also [Console Functions](console-functions.md) @@ -137,11 +103,3 @@ Requirements [**WriteConsoleOutput**](writeconsoleoutput.md) [**WriteConsoleOutputCharacter**](writeconsoleoutputcharacter.md) - -  - -  - - - - diff --git a/docs/writeconsoleoutputcharacter.md b/docs/writeconsoleoutputcharacter.md index d8b0859..39583df 100644 --- a/docs/writeconsoleoutputcharacter.md +++ b/docs/writeconsoleoutputcharacter.md @@ -40,11 +40,9 @@ api_type: # WriteConsoleOutputCharacter function - Copies a number of characters to consecutive cells of a console screen buffer, beginning at a specified location. -Syntax ------- +## Syntax ```C BOOL WINAPI WriteConsoleOutputCharacter( @@ -56,8 +54,7 @@ BOOL WINAPI WriteConsoleOutputCharacter( ); ``` -Parameters ----------- +## Parameters *hConsoleOutput* \[in\] A handle to the console screen buffer. The handle must have the **GENERIC\_WRITE** access right. For more information, see [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md). @@ -74,68 +71,32 @@ A [**COORD**](coord-str.md) structure that specifies the character coordinates o *lpNumberOfCharsWritten* \[out\] A pointer to a variable that receives the number of characters actually written. -Return value ------------- +## Return value 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). -Remarks -------- +## Remarks If the number of characters to be written to extends beyond the end of the specified row in the console screen buffer, characters are written to the next row. If the number of characters to be written to extends beyond the end of the console screen buffer, characters are written up to the end of the console screen buffer. The attribute values at the positions written to are not changed. -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions, or use the **chcp** or **mode con cp select=** commands. - -Requirements ------------- - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ConsoleApi2.h (via Wincon.h, include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

WriteConsoleOutputCharacterW (Unicode) and WriteConsoleOutputCharacterA (ANSI)

- -## See also +[!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] + +## Requirements + +| | | +|-|-| +| Minimum supported client | Windows 2000 Professional \[desktop apps only\] | +| Minimum supported server | Windows 2000 Server \[desktop apps only\] | +| Header | ConsoleApi2.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | +| Unicode and ANSI names | **WriteConsoleOutputCharacterW** (Unicode) and **WriteConsoleOutputCharacterA** (ANSI) | +## See also [Console Functions](console-functions.md) @@ -156,11 +117,3 @@ Requirements [**WriteConsoleOutput**](writeconsoleoutput.md) [**WriteConsoleOutputAttribute**](writeconsoleoutputattribute.md) - -  - -  - - - - From 6ca0e831a2e15d159a5d9b561608e5e533e062da Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Mon, 5 Oct 2020 16:40:10 -0700 Subject: [PATCH 16/53] disrecommend writing to specific coordinate. --- docs/writeconsoleoutput.md | 2 ++ docs/writeconsoleoutputattribute.md | 2 ++ docs/writeconsoleoutputcharacter.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index cb481e6..59040a4 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -41,6 +41,8 @@ api_type: # WriteConsoleOutput function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] + Writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer. ## Syntax diff --git a/docs/writeconsoleoutputattribute.md b/docs/writeconsoleoutputattribute.md index 1766775..26f442c 100644 --- a/docs/writeconsoleoutputattribute.md +++ b/docs/writeconsoleoutputattribute.md @@ -33,6 +33,8 @@ api_type: # WriteConsoleOutputAttribute function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] + Copies a number of character attributes to consecutive cells of a console screen buffer, beginning at a specified location. ## Syntax diff --git a/docs/writeconsoleoutputcharacter.md b/docs/writeconsoleoutputcharacter.md index 39583df..9a41ce9 100644 --- a/docs/writeconsoleoutputcharacter.md +++ b/docs/writeconsoleoutputcharacter.md @@ -40,6 +40,8 @@ api_type: # WriteConsoleOutputCharacter function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] + Copies a number of characters to consecutive cells of a console screen buffer, beginning at a specified location. ## Syntax From ef936f6c9e9dfb585e954d87520fcdbb9d5962df Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Mon, 5 Oct 2020 16:40:46 -0700 Subject: [PATCH 17/53] somehow missed these two. --- docs/ctrl-close-signal.md | 1 - docs/high-level-console-i-o.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/ctrl-close-signal.md b/docs/ctrl-close-signal.md index 82e6f5d..31b3777 100644 --- a/docs/ctrl-close-signal.md +++ b/docs/ctrl-close-signal.md @@ -17,7 +17,6 @@ ms.assetid: a327dd55-3250-40ee-b1c4-6ba3b80984a8 # CTRL+CLOSE Signal - The system generates a CTRL+CLOSE signal when the user closes a console. All processes attached to the console receive the signal, giving each process an opportunity to clean up before termination. When a process receives this signal, the handler function can take one of the following actions after performing any cleanup operations: - Call [**ExitProcess**](https://msdn.microsoft.com/library/windows/desktop/ms682658) to terminate the process. diff --git a/docs/high-level-console-i-o.md b/docs/high-level-console-i-o.md index 9264094..b95861a 100644 --- a/docs/high-level-console-i-o.md +++ b/docs/high-level-console-i-o.md @@ -33,4 +33,4 @@ For more information, see the following topics: - [Console Modes](console-modes.md) - [High-Level Console Modes](high-level-console-modes.md) - [High-Level Console Input and Output Functions](high-level-console-input-and-output-functions.md) -- [Classic functions versus virtual terminal sequences](classic-vs-vt.md) +- [Classic APIs Versus Virtual Terminal Sequences](classic-vs-vt.md) From 0c1973b19f2a0b76a816c0cac5e72fb9a09808c6 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Mon, 5 Oct 2020 17:02:04 -0700 Subject: [PATCH 18/53] more vt tips. --- docs/console-aliases.md | 4 ++-- docs/createconsolescreenbuffer.md | 3 +++ docs/ecosystem-roadmap.md | 2 ++ docs/fillconsoleoutputattribute.md | 3 +++ docs/fillconsoleoutputcharacter.md | 3 +++ docs/getconsolealias.md | 2 ++ docs/getconsolealiases.md | 2 ++ docs/getconsolealiaseslength.md | 2 ++ docs/getconsolealiasexes.md | 2 ++ docs/getconsolealiasexeslength.md | 2 ++ docs/getconsolehistoryinfo.md | 2 ++ 11 files changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/console-aliases.md b/docs/console-aliases.md index 77326bd..764d3ee 100644 --- a/docs/console-aliases.md +++ b/docs/console-aliases.md @@ -27,8 +27,8 @@ To define a console alias, use `Doskey.exe` to create a macro, or use the [**Add The following call to [**AddConsoleAlias**](addconsolealias.md) creates the same console alias: ``` C -AddConsoleAlias( TEXT("test"), - TEXT("cd \\\\test"), +AddConsoleAlias( TEXT("test"), + TEXT("cd \\\\test"), TEXT("cmd.exe")); ``` diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index 0deb505..c44a516 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -95,6 +95,9 @@ The calling process can use the [**DuplicateHandle**](https://msdn.microsoft.com To close the console screen buffer handle, use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. +> [!TIP] +> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. + ## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 6157700..1560e5f 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -10,3 +10,5 @@ ms.prod: console --- # Windows Console and Terminal Ecosystem Roadmap + + diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index 7460852..236a1e1 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -78,6 +78,9 @@ If the number of character cells whose attributes are to be set extends beyond t The character values at the positions written to are not changed. +> [!TIP] +> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. + ## Requirements | | | diff --git a/docs/fillconsoleoutputcharacter.md b/docs/fillconsoleoutputcharacter.md index 16a5b09..3c36434 100644 --- a/docs/fillconsoleoutputcharacter.md +++ b/docs/fillconsoleoutputcharacter.md @@ -88,6 +88,9 @@ The attribute values at the positions written are not changed. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. + ## Requirements | | | diff --git a/docs/getconsolealias.md b/docs/getconsolealias.md index 0bebd4a..5c9ae5a 100644 --- a/docs/getconsolealias.md +++ b/docs/getconsolealias.md @@ -76,6 +76,8 @@ If the function fails, the return value is zero. To get extended error informati To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/getconsolealiases.md b/docs/getconsolealiases.md index 7e6102f..c36229e 100644 --- a/docs/getconsolealiases.md +++ b/docs/getconsolealiases.md @@ -76,6 +76,8 @@ To determine the required size for the *lpExeName* buffer, use the [**GetConsole To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/getconsolealiaseslength.md b/docs/getconsolealiaseslength.md index 5026814..bde9cc6 100644 --- a/docs/getconsolealiaseslength.md +++ b/docs/getconsolealiaseslength.md @@ -62,6 +62,8 @@ The size of the buffer required to store all console aliases defined for this ex To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/getconsolealiasexes.md b/docs/getconsolealiasexes.md index a0087d3..ee71b33 100644 --- a/docs/getconsolealiasexes.md +++ b/docs/getconsolealiasexes.md @@ -70,6 +70,8 @@ To determine the required size for the *lpExeNameBuffer* buffer, use the [**GetC To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/getconsolealiasexeslength.md b/docs/getconsolealiasexeslength.md index 0bef58e..3197058 100644 --- a/docs/getconsolealiasexeslength.md +++ b/docs/getconsolealiasexeslength.md @@ -59,6 +59,8 @@ The size of the buffer required to store the names of all executable files that To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/getconsolehistoryinfo.md b/docs/getconsolehistoryinfo.md index cdeb0db..502ff50 100644 --- a/docs/getconsolehistoryinfo.md +++ b/docs/getconsolehistoryinfo.md @@ -56,6 +56,8 @@ If the function fails, the return value is zero. To get extended error informati If the calling process is not a console process, the function fails and sets the last error to **ERROR\_ACCESS\_DENIED**. +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | From ef45b97f24629e3d12be8bd6352d99218f54131e Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 11:27:09 -0700 Subject: [PATCH 19/53] Draft classic vs vt. --- docs/classic-vs-vt.md | 69 ++++++++++++++++++++++++++++++ docs/ecosystem-roadmap.md | 2 - docs/fillconsoleoutputattribute.md | 2 +- 3 files changed, 70 insertions(+), 3 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index e1fc8a6..ad8a517 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -10,3 +10,72 @@ ms.prod: console --- # Classic Console APIs versus Virtual Terminal Sequences + +This article will discuss the difference between the classic Windows Console API surface, defined as the series of C language functional interfaces on `kernel32.dll` with "Console" in the name, and [Virtual Terminal Sequences](console-virtual-terminal-sequences.md), defined as a language of commands embedded in the standard input and standard output streams utilizing non-printable escape characters for signaling commands interleaved with normal printable text. + +## History + +The Windows Console has provided a broad API surface for client command-line applications to manipulate both the output display buffer and the user input buffer. However, other non-Windows platforms have never afforded this specific API-driven approach to their command-line environments, choosing instead to use virtual terminal sequences embedded within the standard input and standard output streams. For a time, Microsoft supported this behavior too in early editions editions of DOS and Windows through a driver called ANSI.SYS. + +By contrast, all other platforms derive their command-line environment operations from various dialects of virtual terminal sequences. These sequences are rooted in an [ECMA Standard](https://www.ecma-international.org/publications/standards/Ecma-048.htm) and series of extensions by many vendors tracing back to Digital Equipment Corporation and Tektronix terminals through more modern and common software terminals like [xterm](https://invisible-island.net/xterm/). Many extensions exist within the virtual terminal sequence domain and some sequences are more widely supported than others, but it is safe to say that the world has standardized on this as the command language for command-line experiences with a well-known subset being supported by virtually every terminal and command-line client application. + +## Comparisons + +### Cross-Platform Support + +As every platform in the world, except Windows, natively spoke virtual terminal sequences, both terminal applications and command-line utilities have been easily portable between versions and variations of those operating systems. By contrast, Windows APIs are only supported on Windows. An extensive adapter or translation library has to be written between Windows and VT or vice versa when attempting to port command-line utilities from one platform or another. + +### Remote Access + +Virtual Terminal Sequences hold a major advantage for remote access as they require no additional work to transport or perform remote procedure calls over what is required to set up a standard remote command-line connection. Simply connecting an outbound and an inbound transport channel (or a single bidirectional channel) over a pipe, socket, file, serial port, or any other device is sufficient to completely carry all information necessary required for an application speaking these sequences to a remote host. On the contrary, the Windows Console APIs have only been accessible on the local machine and all efforts to remote them would require building an entire remote calling and transport interface layer beyond just a simple channel. + +### Separation of Concerns + +Some of the Windows Console APIs provide low-level access to the input and output buffers or convenience functions for interactive command-lines like aliases and command history programmed within the console subsystem and host environment, instead of within the command-line client application itself. This is in contrast to other platforms where both the memory of the current state of the application and convenience functionality is the responsibility of the command-line utility or shell itself. + +While the Windows way of handling this responsibility in the console host and API makes it quicker and easier to write a command-line application with these features and without responsibility of remembering drawing state or handling editing convenience features, it makes it nearly impossible to connect those activities remotely across platforms, versions, or scenarios due to variations in implementations and availability. It also makes the final interactive experience of these Windows command-line applications completely dependent on the console host's implementation, priorities, and release cycle. + +By contrast, other platforms handle these activities and virtual terminal communication itself through reusable client-side libraries like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and [ncurses](https://invisible-island.net/ncurses/ncurses.html). The final terminal is only responsible for displaying information and receiving input through that bidirectional communication channel. + +### Wrong-Way Verbs + +On Windows, some actions can be performed in the opposite-to-natural direction on the input and output streams. This allows Windows command-line applications to both avoid the concern of managing their own buffers and to perform advanced operations like simulating/injecting input on behalf of a user or reading back some of the history of what was written. While this provides additional power to Windows applications operating in a specific user context on a single machine, it also provides a vector to cross security and privilege levels or domains when used in scenarios between contexts on the same machine or even across contexts to another machine or environment. Other platforms do not allow this activity and our intent is to converge with that strategy for both interoperability and security reasons. + +### Direct Window Access + +On Windows, the exact window handle to the hosting window is available through the Console API surface. This allows a command-line utility to perform advanced window operations by reaching into the wide gamut of Win32 APIs permitted against a window handle and manipulate the window state, frame, icon, or other properties about the window. By contrast, on other platforms with virtual terminal sequences, there is a specific gamut of commands that can be performed against the window to do things like changing its size or displayed title and they must be done in the same band and under the same control as the remainder of the stream. + +As Windows has evolved, the security controls and restrictions on window handles have increased. Additionally, the nature and existence of an application-addressable window handle on any specific user interface element has evolved, especially with the increased support of device form factors and platforms. This makes direct window access to command-line applications fragile as the platform and experiences evolve. + +### Unicode + +The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist, but generally speaking, when otherwise undefined, using UTF-8 is accepted as the appropriate default balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. + +The Windows console platform has and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development and also accept UTF-16 as an algorithmically-translatable alternative representation of the same information that is more compatible with Windows' historical Unicode philosophies extending from initial UCS-2 implementations. + +UTF-8 support in the console can be found via the _A_ variant of all Console APIs or the filesystem [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) methods against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. + +UTF-16 support in the console can be found with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. + +## Recommendations + +For all new and ongoing development on Windows, virtual terminal sequences are recommended as the way of interacting with the terminal. This will converge Windows command-line client applications with the style of application programming on all other platforms. + +A limited subset of Windows Console APIs are still necessary to establish the initial environment as the Windows platform still differs from others in process, signal, device, and encoding handling: + +- The standard handles to a process will still be controlled with **[GetStdHandle](getstdhandle.md)** and **[SetStdHandle](setsetdhandle.md)**. +- Configuration of the console modes on a handle to opt in to Virtual Terminal Sequence support will be handled with **[GetConsoleMode](getconsolemode.md)** and **[SetConsoleMode](setconsolemode.md)**. +- Declaration of code page or UTF-8 support is conducted with [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods. +- Some level of overall process management may be required with the [**AllocConsole**](allocconsole.md), [**AttachConsole**](attachconsole.md) and [**FreeConsole**](freeconsole.md) to join or leave a console device session. +- Signals and signal handling will continue to be conducted with [**SetConsoleCtrlHandler**](setconsolectrlhandler.md), [**HandlerRoutine**](handlerroutine.md), and [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md). +- Communication with the console device handles can be conducted with [**WriteConsole**](writeconsole.md), [**ReadConsole**](readconsole.md), [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467). + - These may also be leveraged through programming language runtimes in the forms of: + - C Runtime (CRT): [Stream I/O](https://docs.microsoft.com/cpp/c-runtime-library/stream-i-o) like **printf**, **scanf**, **putc**, **getc**, or [other levels of I/O functions](https://docs.microsoft.com/cpp/c-runtime-library/input-and-output). + - C++ Standard Library (STL): [iostream](https://docs.microsoft.com/cpp/standard-library/iostream) like **cout** and **cin**. + - .NET Runtime: [System.Console](https://docs.microsoft.com/dotnet/api/system.console) like **Console.WriteLine**. + +There are no plans to remove the Windows console APIs from the platform. On the contrary, the Windows console host has provided the [pseudoconsole](pseudoconsoles.md) technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. This translation is not perfect and requires the console host window to maintain a simulated environment of what Windows would have displayed to the user and project a replica of that to the pseudoconsole host. Any console API call without an equivalent is operated within the simulated environment to serve the needs of the legacy command-line client application and only the effects are propagated onto the final host. + +A command-line application desiring full compatibility across platforms and full support of all new features and scenarios both on Windows and elsewhere is therefore recommended to move to Virtual Terminal sequences and adjust the architecture of command-line applications to align with all platforms. + +More information about this Windows transition for command-line applications can be found on our [ecosystem roadmap](ecosystem-roadmap.md). diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 1560e5f..6157700 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -10,5 +10,3 @@ ms.prod: console --- # Windows Console and Terminal Ecosystem Roadmap - - diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index 236a1e1..257198c 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -79,7 +79,7 @@ If the number of character cells whose attributes are to be set extends beyond t The character values at the positions written to are not changed. > [!TIP] -> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. +> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. ## Requirements From 857d2f46e72e1e6f90b1606b60b91f6b8964c3a3 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 13:24:17 -0700 Subject: [PATCH 20/53] ecosystem roadmap --- docs/ecosystem-roadmap.md | 58 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 6157700..5c549fb 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -10,3 +10,61 @@ ms.prod: console --- # Windows Console and Terminal Ecosystem Roadmap + +This document is intended to provide a high-level overview of the Windows Console and Windows Terminal products, how they fit into the ecosystem of command-line applications across Windows and other operating systems, and a general roadmap of the products, features, and strategies that are a part of building the platform and building for this platform. + +## Definitions + +We'll start with some definitions of command words and phrases in this space that can help you understand the overall strategy and be used as reference throughout this document set. + +### Command Line Applications + +Command line applications, or sometimes called "console applications" and/or referred to as "clients" of the console subsystem, are programs that operate mainly on a stream of text or character information. They generally contain no user interface elements of their own and delegate both the output/display and the input/interaction roles to a hosting application. Command line applications receive a stream of text on their standard input `STDIN` handle which represents a user's keyboard input, process that information, then respond with a stream of text on their standard output `STDOUT` for display back to the user's monitor. Of course, this has evolved over time for additional input devices and remote scenarios, but the same basic philosophy remains the same: command-line clients operate on text and someone else manages display/input. + +### Standard Handles + +The standard handles are a series of handles, `STDIN`, `STDOUT`, and `STDERR`, that are introduced a part of process space on startup and represent a place where information can be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts and are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither of the first two are specified/permitted. For classic windows applications, these may be blank on startup, but can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. + +Standard handles do not imply a specific type of attached device, though in the case of command-line applications, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. + +### TTY/PTY + +On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that represent the same as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. + +### Clients and Servers + +Within this space, we're referring to "clients" as applications that do the work of processing information and running commands. The "server" applications are those that are responsible for the user interface and are workers to translate input and output into standard forms on behalf of the clients. + +### Console Subsystem + +This is a catch-all term representing all modules in the console team's space. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). + +The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. + +### Console Host + +The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. + +### Psuedoconsole + +This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. + +### Terminal + +A terminal is the user-interface and interaction module for a command-line application. Today, it's a software representation of what used to be historically a physical device with a display monitor, a keyboard, and a bidirectional serial communication channel. It is responsible for gathering input from the user in a variety of forms, translating it and encoding it and any special command information into a single text stream, and submitting it to the PTY for transmission on to the `STDIN` channel of the command-line client application. It is also responsible for receiving back information, via the PTY, that came from a client application's `STDOUT` channel, decoding any special information in the payload, laying out all the text and additional commands, and presenting that graphically to the end user. + +## Products + +## Architecture + +## Roadmap + +### Virtual Terminal client + +### Virtual Terminal server + +### Terminal applications + +### Sequence Passthrough + +### Client support library From 62b8d6b6a5658ebcfcb5fe61798484ea47e64941 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 13:34:44 -0700 Subject: [PATCH 21/53] Products, ecosystem --- docs/ecosystem-roadmap.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 5c549fb..21928a2 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -55,7 +55,17 @@ A terminal is the user-interface and interaction module for a command-line appli ## Products -## Architecture +All of our products are now available on GitHub in our open source repository, [Microsoft/Terminal](https://github.com/microsoft/terminal). + +### Windows Console Host + +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the pseudoconsole infrastructure with a modern terminal application. + +### Windows Terminal + +This is the new Windows interface for command-line applications, intended as a first-party example of using the pseudoconsole to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. + +## Architecture ## Roadmap From 8de0d675518feee55e65f591f8193b97c966969e Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 15:25:32 -0700 Subject: [PATCH 22/53] timeline/roadmap, move definitions out. --- docs/classic-vs-vt.md | 2 +- docs/definitions.md | 49 ++++++++++++++++++++++++++++++ docs/ecosystem-roadmap.md | 63 +++++++++++++++++++-------------------- 3 files changed, 80 insertions(+), 34 deletions(-) create mode 100644 docs/definitions.md diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index ad8a517..d451070 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -27,7 +27,7 @@ As every platform in the world, except Windows, natively spoke virtual terminal ### Remote Access -Virtual Terminal Sequences hold a major advantage for remote access as they require no additional work to transport or perform remote procedure calls over what is required to set up a standard remote command-line connection. Simply connecting an outbound and an inbound transport channel (or a single bidirectional channel) over a pipe, socket, file, serial port, or any other device is sufficient to completely carry all information necessary required for an application speaking these sequences to a remote host. On the contrary, the Windows Console APIs have only been accessible on the local machine and all efforts to remote them would require building an entire remote calling and transport interface layer beyond just a simple channel. +Virtual Terminal Sequences hold a major advantage for remote access as they require no additional work to transport or perform remote procedure calls over what is required to set up a standard remote command-line connection. Simply connecting an outbound and an inbound transport channel (or a single bidirectional channel) over a pipe, socket, file, serial port, or any other device is sufficient to completely carry all information required for an application speaking these sequences to a remote host. On the contrary, the Windows Console APIs have only been accessible on the local machine and all efforts to remote them would require building an entire remote calling and transport interface layer beyond just a simple channel. ### Separation of Concerns diff --git a/docs/definitions.md b/docs/definitions.md new file mode 100644 index 0000000..756f872 --- /dev/null +++ b/docs/definitions.md @@ -0,0 +1,49 @@ +--- +title: Windows Console and Terminal Definitions +description: Provides definitions of words and phrases commonly used in this space and document set related to the console and terminal system. +author: miniksa +ms.author: miniksa +ms.topic: conceptual +keywords: console, terminal, virtual terminal, console host, command-line, subsystem, definitions +ms.prod: console +--- + +## Definitions + +This document provides the definitions of specific words and phrases in this space and be used as reference throughout this document set. + +### Command Line Applications + +Command line applications, or sometimes called "console applications" and/or referred to as "clients" of the console subsystem, are programs that operate mainly on a stream of text or character information. They generally contain no user interface elements of their own and delegate both the output/display and the input/interaction roles to a hosting application. Command line applications receive a stream of text on their standard input `STDIN` handle which represents a user's keyboard input, process that information, then respond with a stream of text on their standard output `STDOUT` for display back to the user's monitor. Of course, this has evolved over time for additional input devices and remote scenarios, but the same basic philosophy remains the same: command-line clients operate on text and someone else manages display/input. + +### Standard Handles + +The standard handles are a series of handles, `STDIN`, `STDOUT`, and `STDERR`, that are introduced a part of process space on startup and represent a place where information can be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts and are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither of the first two are specified/permitted. For classic windows applications, these may be blank on startup, but can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. + +Standard handles do not imply a specific type of attached device, though in the case of command-line applications, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. + +### TTY/PTY + +On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that represent the same as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. + +### Clients and Servers + +Within this space, we're referring to "clients" as applications that do the work of processing information and running commands. The "server" applications are those that are responsible for the user interface and are workers to translate input and output into standard forms on behalf of the clients. + +### Console Subsystem + +This is a catch-all term representing all modules in the console team's space. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). + +The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. + +### Console Host + +The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. + +### Psuedoconsole + +This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. + +### Terminal + +A terminal is the user-interface and interaction module for a command-line application. Today, it's a software representation of what used to be historically a physical device with a display monitor, a keyboard, and a bidirectional serial communication channel. It is responsible for gathering input from the user in a variety of forms, translating it and encoding it and any special command information into a single text stream, and submitting it to the PTY for transmission on to the `STDIN` channel of the command-line client application. It is also responsible for receiving back information, via the PTY, that came from a client application's `STDOUT` channel, decoding any special information in the payload, laying out all the text and additional commands, and presenting that graphically to the end user. \ No newline at end of file diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 21928a2..8566d81 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -6,7 +6,6 @@ ms.author: miniksa ms.topic: conceptual keywords: console, terminal, virtual terminal, console host, command-line, subsystem, roadmap, ecosystem ms.prod: console - --- # Windows Console and Terminal Ecosystem Roadmap @@ -15,66 +14,64 @@ This document is intended to provide a high-level overview of the Windows Consol ## Definitions -We'll start with some definitions of command words and phrases in this space that can help you understand the overall strategy and be used as reference throughout this document set. - -### Command Line Applications +It is highly recommended to familiarize yourself with the [definitions](definitions.md) behind common terminology in this space before proceeding with the remainder of this document. -Command line applications, or sometimes called "console applications" and/or referred to as "clients" of the console subsystem, are programs that operate mainly on a stream of text or character information. They generally contain no user interface elements of their own and delegate both the output/display and the input/interaction roles to a hosting application. Command line applications receive a stream of text on their standard input `STDIN` handle which represents a user's keyboard input, process that information, then respond with a stream of text on their standard output `STDOUT` for display back to the user's monitor. Of course, this has evolved over time for additional input devices and remote scenarios, but the same basic philosophy remains the same: command-line clients operate on text and someone else manages display/input. +## Products -### Standard Handles +All of our products are now available on GitHub in our open source repository, [Microsoft/Terminal](https://github.com/microsoft/terminal). -The standard handles are a series of handles, `STDIN`, `STDOUT`, and `STDERR`, that are introduced a part of process space on startup and represent a place where information can be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts and are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither of the first two are specified/permitted. For classic windows applications, these may be blank on startup, but can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. +### Windows Console Host -Standard handles do not imply a specific type of attached device, though in the case of command-line applications, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the pseudoconsole infrastructure with a modern terminal application. -### TTY/PTY +### Windows Terminal -On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that represent the same as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. +This is the new Windows interface for command-line applications, intended as a first-party example of using the pseudoconsole to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. -### Clients and Servers +## Architecture -Within this space, we're referring to "clients" as applications that do the work of processing information and running commands. The "server" applications are those that are responsible for the user interface and are workers to translate input and output into standard forms on behalf of the clients. +## Roadmap -### Console Subsystem +This roadmap starts with a brief history of major milestones in the console subsystem prior to 2015. It then moves into an overview of work performed since 2015 when the renewed focus on the command-line was formed in the Windows 10 era and finishes with what is intended to come next. -This is a catch-all term representing all modules in the console team's space. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). +### Implementation -The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. +**\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the Command Prompt, `cmd.exe`, that is a representation of that DOS environemnt and shares responsibilities and privileges with that interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. -### Console Host +### DBCS for CJK -The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. +**\[1997-1999\]** Around this time, DBCS support ("Double-byte character set") is introduced to support CJK (Chinese, Japanese, and Korean) markets. This effort results in a bifurcation of many of the writing and reading methods inside the console to provide both "western" versions to deal with single-byte characters as well as an alternative representation for "eastern" versions where two bytes are required to represent the vast array of characters. This also included the expansion of the representation of a cell in the console environment to be either 1 or 2 cells wide, where 1 cell is narrow (taller than it is wide) and 2 cells is wide, full-width, or otherwise a square in which typical Chinese, Japanese, and Korean ideographs can be inscribed. -### Psuedoconsole +### Security/Isolation -This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. +**\[2005-2009\]** With the console subsystem experience running inside the critical system process, `csrss.exe`, connecting assorted client applications at varying access levels to a single super-critical and privileged process was noticed as particularly dangerous. In this era, the console subsystem was split out into client, driver, and server applications that can each run in their own context, reducing the responsibilities and privilege in each. This isolation also increased general robustness of the system as any failure in the console subsystem no longer affected other critical process functionality. -### Terminal +### Windows 10 User Experience Improvements -A terminal is the user-interface and interaction module for a command-line application. Today, it's a software representation of what used to be historically a physical device with a display monitor, a keyboard, and a bidirectional serial communication channel. It is responsible for gathering input from the user in a variety of forms, translating it and encoding it and any special command information into a single text stream, and submitting it to the PTY for transmission on to the `STDIN` channel of the command-line client application. It is also responsible for receiving back information, via the PTY, that came from a client application's `STDOUT` channel, decoding any special information in the payload, laying out all the text and additional commands, and presenting that graphically to the end user. +**\[2014-2016\]** After a long time of general scattered maintenance of the console subsystem by assorted teams across the organization, a new developer focused team was formed to own and drive improvements in the console. This time frame included line selection, smooth window resizing, reflowing text, copy and paste, high DPI support, and a focus on Unicode including the convergence of the split between "western" and "eastern" storage and stream manipulation algorithms. -## Products +### Virtual Terminal client -All of our products are now available on GitHub in our open source repository, [Microsoft/Terminal](https://github.com/microsoft/terminal). +**\[2015-2017\]** With the advent of the Windows Subsystem for Linux, Microsoft efforts to improve the experience of Docker on Windows, and the adoption of OpenSSH by the PowerShell team as the premier command-line remote execution technology, the initial implementations of Virtual Terminal Sequences were introduced into the console host. This allowed the existing console to act as the terminal attached directly to those Linux-native applications in their respective environments, rendering graphical and text attributes to the display and returning user input in the appropriate dialect. -### Windows Console Host +### Virtual Terminal server -This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the pseudoconsole infrastructure with a modern terminal application. +**\[2018\]** Over the past twenty years, third-party alternatives for the inbox console host had arisen to offer additional developer productivity prominently centered in rich customizations and tabbed interfaces. These applications were still beholden to run and hide the console host window and attach as a secondary "client" application to scrape out buffer information in polling loops as the primary command-line client application operated. Their goal was to be a terminal, like on other platforms, but in the Windows world where terminals were not replaceable. -### Windows Terminal +In this time period, the psuedoconsole infrastructure was introduced, to permit any application in this position to launch the console host in a non-interactive mode and become the final terminal interface for the user. The main limitation in this effort was the continued compatibility promise of Windows in servicing all published Windows Console APIs for the indefinite future while providing a replacement server hosting interface that matched what is expected on all other platforms: virtual terminal sequences. As such, this effort performed the mirror image of the client phase: the pseudoconsole projects what would be displayed onto the screen as virtual terminal sequences for a delegated host and interprets replies into Windows-format input sequences for client application consumption. -This is the new Windows interface for command-line applications, intended as a first-party example of using the pseudoconsole to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. +### Terminal applications -## Architecture +**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [Microsoft/Terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for pseudoconsoles to bring a first class terminal experience directly to developers on the Windows platform. -## Roadmap +It is intended not only as a showcase for the platform including the WinUI technology, the MSIX packaging model, and the C++/WinRT component architecture, but also as a validation of the platform itself, driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal's unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. -### Virtual Terminal client +Inside the Windows operating system, this also includes retiring the classic console host user interface from its default position in favor of the Terminal, ConPTY, and VT sequence experience. And finally, it is intended to offer full choice over the default experience, whether it is the Windows Terminal product or any alternative terminals. -### Virtual Terminal server +### Client support library -### Terminal applications +**\[Future\]** With the support and documentation of virtual terminal sequences on the client side, we strongly encourage Windows command-line utility developers to use VT sequences first over the classic Windows APIs to gain the benefit of a united ecosystem with all platforms. However, one significant missing piece is that other platforms have a wide array of client-side helper libraries for handling input like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and graphical display like [ncurses](https://invisible-island.net/ncurses/ncurses.html). This particular future road map element represents the exploration of what the ecosystem offers and how we can accelerate the adoption of VT sequences in Windows command-line applications over the classic Console API. ### Sequence Passthrough -### Client support library +**\[Future\]** While the combination of virtual terminal client and server implementations allows the full mixing and matching of client command-line and terminal hosting applications that speak either the classic Windows Console APIs or Virtual Terminal Sequences, there is an overhead cost to translating the world into the classic compatible Windows method and then back into the more universal VT method. Once the market is sufficiently virtual terminal sequences and UTF-8 on Windows, the conversion/interpretation job of the console host can be optionally disabled and turn into a simple API call servicer and relay from device calls to the hosting application via the psuedoconsole. This increases performance and maximizes the dialect of sequences that can be spoken between client application and the terminal enabling additional interactivity scenarios and finally bringing the Windows world into the family with all other platforms in the command-line application space. From e4c3e30e784eb331f4983cef6ca1d4f8a9d3c3e0 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 16:13:51 -0700 Subject: [PATCH 23/53] some cleanup and add links --- docs/definitions.md | 20 +++++++-------- docs/ecosystem-roadmap.md | 54 ++++++++++++++++++++++++++++----------- 2 files changed, 49 insertions(+), 25 deletions(-) diff --git a/docs/definitions.md b/docs/definitions.md index 756f872..ce98fc8 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -8,42 +8,42 @@ keywords: console, terminal, virtual terminal, console host, command-line, subsy ms.prod: console --- -## Definitions +# Definitions This document provides the definitions of specific words and phrases in this space and be used as reference throughout this document set. -### Command Line Applications +## Command Line Applications Command line applications, or sometimes called "console applications" and/or referred to as "clients" of the console subsystem, are programs that operate mainly on a stream of text or character information. They generally contain no user interface elements of their own and delegate both the output/display and the input/interaction roles to a hosting application. Command line applications receive a stream of text on their standard input `STDIN` handle which represents a user's keyboard input, process that information, then respond with a stream of text on their standard output `STDOUT` for display back to the user's monitor. Of course, this has evolved over time for additional input devices and remote scenarios, but the same basic philosophy remains the same: command-line clients operate on text and someone else manages display/input. -### Standard Handles +## Standard Handles The standard handles are a series of handles, `STDIN`, `STDOUT`, and `STDERR`, that are introduced a part of process space on startup and represent a place where information can be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts and are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither of the first two are specified/permitted. For classic windows applications, these may be blank on startup, but can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. Standard handles do not imply a specific type of attached device, though in the case of command-line applications, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. -### TTY/PTY +## TTY/PTY On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that represent the same as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. -### Clients and Servers +## Clients and Servers Within this space, we're referring to "clients" as applications that do the work of processing information and running commands. The "server" applications are those that are responsible for the user interface and are workers to translate input and output into standard forms on behalf of the clients. -### Console Subsystem +## Console Subsystem This is a catch-all term representing all modules in the console team's space. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. -### Console Host +## Console Host The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. -### Psuedoconsole +## Psuedoconsole This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. -### Terminal +## Terminal -A terminal is the user-interface and interaction module for a command-line application. Today, it's a software representation of what used to be historically a physical device with a display monitor, a keyboard, and a bidirectional serial communication channel. It is responsible for gathering input from the user in a variety of forms, translating it and encoding it and any special command information into a single text stream, and submitting it to the PTY for transmission on to the `STDIN` channel of the command-line client application. It is also responsible for receiving back information, via the PTY, that came from a client application's `STDOUT` channel, decoding any special information in the payload, laying out all the text and additional commands, and presenting that graphically to the end user. \ No newline at end of file +A terminal is the user-interface and interaction module for a command-line application. Today, it's a software representation of what used to be historically a physical device with a display monitor, a keyboard, and a bidirectional serial communication channel. It is responsible for gathering input from the user in a variety of forms, translating it and encoding it and any special command information into a single text stream, and submitting it to the PTY for transmission on to the `STDIN` channel of the command-line client application. It is also responsible for receiving back information, via the PTY, that came from a client application's `STDOUT` channel, decoding any special information in the payload, laying out all the text and additional commands, and presenting that graphically to the end user. diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 8566d81..fac69f8 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -16,62 +16,86 @@ This document is intended to provide a high-level overview of the Windows Consol It is highly recommended to familiarize yourself with the [definitions](definitions.md) behind common terminology in this space before proceeding with the remainder of this document. +## Architecture + +The general architecture of the system is in four parts: client, device, server, and terminal. Each is connected to the adjacent items in the list with the two ends as the respective source and destination to command-line communication. + +### Client + +A client is a command-line application that interprets a user's desires through a text-based interface, performs work or dispatches further commands, and returns a text representation of the result. On Windows, the console API or the standard console handles with device control APIs provide a communications layer between the client and the device. + +### Device + +The device is an intermediate message handling communications layer between two processes, the client and the server. On Windows, this is the console driver, while on other platforms, it is the TTY or PTY device. Other devices like files, pipes, and sockets may be used as this communication channel if the entire transaction is in plain text or contains [virtual terminal sequences](console-virtual-terminal-sequences.md), but not with [Windows Console APIs](console-functions.md). + +### Server + +The server interprets the requested API calls or messages from the client. On Windows in the classic operating mode, it also creates a user interface to present the output to the screen and collects input to send back in response messages to the client via the driver, like a terminal bundled in the same module. With the [pseudoconsole](pseudoconsoles.md) mode, it instead is only a translator to present this information in [virtual terminal sequences](console-virtual-terminal-sequences.md) to an attached Terminal. + +### Terminal + +The terminal is the final layer providing graphical display and interactivity services to the user. It is responsible for capturing input and encoding it as [virtual terminal sequences](console-virtual-terminal-sequences.md) to eventually reach the client's `STDIN` and decoding and presenting the plain text and _virtual terminal sequences_ it received back from the client's `STDOUT`. + +#### Further Connections + +As an addendum, further connections can be performed by chaining applications that serve multiple roles into one of the endpoints. For instance, an SSH session has two roles: it is a Terminal for the command-line application running on one device, but it forwards all received information on to a Client role on another device. This chaining can occur indefinitely across devices and contexts offering broad scenario flexibility. + +On non-Windows platforms, the Server and Terminal roles are a single unit because there is no need for a translation compatibility layer between an API set and [virtual terminal sequences](console-virtual-terminal-sequences.md) as there is on Windows. + ## Products All of our products are now available on GitHub in our open source repository, [Microsoft/Terminal](https://github.com/microsoft/terminal). ### Windows Console Host -This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the pseudoconsole infrastructure with a modern terminal application. +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the [pseudoconsole](pseudoconsoles.md) infrastructure with a modern terminal application. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _psuedoconsole_ infrastructure. ### Windows Terminal -This is the new Windows interface for command-line applications, intended as a first-party example of using the pseudoconsole to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. - -## Architecture +This is the new Windows interface for command-line applications, intended as a first-party example of using the [pseudoconsole](pseudoconsoles.md) to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. Per the definitions above, this product operates in a terminal role. ## Roadmap -This roadmap starts with a brief history of major milestones in the console subsystem prior to 2015. It then moves into an overview of work performed since 2015 when the renewed focus on the command-line was formed in the Windows 10 era and finishes with what is intended to come next. +This roadmap starts with a brief history of major milestones in the console subsystem prior to 2014. It then moves into an overview of work performed since 2014 when the renewed focus on the command-line was formed in the Windows 10 era and finishes with what is intended to come next. ### Implementation -**\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the Command Prompt, `cmd.exe`, that is a representation of that DOS environemnt and shares responsibilities and privileges with that interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. +**\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the [Command Prompt](https://docs.microsoft.com/windows-server/administration/windows-commands/cmd), `cmd.exe`, that is a representation of that DOS environment and shares responsibilities and privileges with that interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. ### DBCS for CJK -**\[1997-1999\]** Around this time, DBCS support ("Double-byte character set") is introduced to support CJK (Chinese, Japanese, and Korean) markets. This effort results in a bifurcation of many of the writing and reading methods inside the console to provide both "western" versions to deal with single-byte characters as well as an alternative representation for "eastern" versions where two bytes are required to represent the vast array of characters. This also included the expansion of the representation of a cell in the console environment to be either 1 or 2 cells wide, where 1 cell is narrow (taller than it is wide) and 2 cells is wide, full-width, or otherwise a square in which typical Chinese, Japanese, and Korean ideographs can be inscribed. +**\[1997-1999\]** Around this time, [DBCS](https://docs.microsoft.com/windows/win32/intl/double-byte-character-sets) support ("Double-byte character set") is introduced to support CJK (Chinese, Japanese, and Korean) markets. This effort results in a bifurcation of many of the writing and reading methods inside the console to provide both "western" versions to deal with single-byte characters as well as an alternative representation for "eastern" versions where two bytes are required to represent the vast array of characters. This also included the expansion of the representation of a cell in the console environment to be either 1 or 2 cells wide, where 1 cell is narrow (taller than it is wide) and 2 cells is wide, full-width, or otherwise a square in which typical Chinese, Japanese, and Korean ideographs can be inscribed. ### Security/Isolation **\[2005-2009\]** With the console subsystem experience running inside the critical system process, `csrss.exe`, connecting assorted client applications at varying access levels to a single super-critical and privileged process was noticed as particularly dangerous. In this era, the console subsystem was split out into client, driver, and server applications that can each run in their own context, reducing the responsibilities and privilege in each. This isolation also increased general robustness of the system as any failure in the console subsystem no longer affected other critical process functionality. -### Windows 10 User Experience Improvements +### User Experience Improvements **\[2014-2016\]** After a long time of general scattered maintenance of the console subsystem by assorted teams across the organization, a new developer focused team was formed to own and drive improvements in the console. This time frame included line selection, smooth window resizing, reflowing text, copy and paste, high DPI support, and a focus on Unicode including the convergence of the split between "western" and "eastern" storage and stream manipulation algorithms. ### Virtual Terminal client -**\[2015-2017\]** With the advent of the Windows Subsystem for Linux, Microsoft efforts to improve the experience of Docker on Windows, and the adoption of OpenSSH by the PowerShell team as the premier command-line remote execution technology, the initial implementations of Virtual Terminal Sequences were introduced into the console host. This allowed the existing console to act as the terminal attached directly to those Linux-native applications in their respective environments, rendering graphical and text attributes to the display and returning user input in the appropriate dialect. +**\[2015-2017\]** With the advent of the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/), Microsoft efforts to improve the experience of [Docker on Windows](https://docs.microsoft.com/dotnet/architecture/microservices/container-docker-introduction/docker-defined), and the adoption of [OpenSSH](https://docs.microsoft.com/windows-server/administration/openssh/openssh_overview) as the premier command-line remote execution technology, the initial implementations of [virtual terminal sequences](console-virtual-terminal-sequences.md) were introduced into the console host. This allowed the existing console to act as the terminal attached directly to those Linux-native applications in their respective environments, rendering graphical and text attributes to the display and returning user input in the appropriate dialect. ### Virtual Terminal server -**\[2018\]** Over the past twenty years, third-party alternatives for the inbox console host had arisen to offer additional developer productivity prominently centered in rich customizations and tabbed interfaces. These applications were still beholden to run and hide the console host window and attach as a secondary "client" application to scrape out buffer information in polling loops as the primary command-line client application operated. Their goal was to be a terminal, like on other platforms, but in the Windows world where terminals were not replaceable. +**\[2018\]** Over the past twenty years, third-party alternatives for the inbox console host had arisen to offer additional developer productivity prominently centered in rich customizations and tabbed interfaces. These applications were still beholden to run and hide the console host window and attach as a secondary "client" application to scrape out buffer information in polling loops as the primary command-line client application operated. Their goal was to be a terminal, like on other platforms, but in the Windows world where terminals were not replaceable. -In this time period, the psuedoconsole infrastructure was introduced, to permit any application in this position to launch the console host in a non-interactive mode and become the final terminal interface for the user. The main limitation in this effort was the continued compatibility promise of Windows in servicing all published Windows Console APIs for the indefinite future while providing a replacement server hosting interface that matched what is expected on all other platforms: virtual terminal sequences. As such, this effort performed the mirror image of the client phase: the pseudoconsole projects what would be displayed onto the screen as virtual terminal sequences for a delegated host and interprets replies into Windows-format input sequences for client application consumption. +In this time period, the [pseudoconsole](pseudoconsoles.md) infrastructure was introduced, to permit any application in this position to launch the console host in a non-interactive mode and become the final terminal interface for the user. The main limitation in this effort was the continued compatibility promise of Windows in servicing all published [Windows Console APIs](console-functions.md) for the indefinite future while providing a replacement server hosting interface that matched what is expected on all other platforms: [virtual terminal sequences](console-virtual-terminal-sequences.md). As such, this effort performed the mirror image of the client phase: the _pseudoconsole_ projects what would be displayed onto the screen as _virtual terminal sequences_ for a delegated host and interprets replies into Windows-format input sequences for client application consumption. ### Terminal applications -**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [Microsoft/Terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for pseudoconsoles to bring a first class terminal experience directly to developers on the Windows platform. +**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [Microsoft/Terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for [pseudoconsole](pseudoconsoles.md)s to bring a first class terminal experience directly to developers on the Windows platform. -It is intended not only as a showcase for the platform including the WinUI technology, the MSIX packaging model, and the C++/WinRT component architecture, but also as a validation of the platform itself, driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal's unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. +It is intended not only as a showcase for the platform including the [WinUI](https://docs.microsoft.com/windows/apps/winui/) technology, the [MSIX](https://docs.microsoft.com/windows/msix/) packaging model, and the [C++/WinRT](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/) component architecture, but also as a validation of the platform itself, driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal's unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. Inside the Windows operating system, this also includes retiring the classic console host user interface from its default position in favor of the Terminal, ConPTY, and VT sequence experience. And finally, it is intended to offer full choice over the default experience, whether it is the Windows Terminal product or any alternative terminals. ### Client support library -**\[Future\]** With the support and documentation of virtual terminal sequences on the client side, we strongly encourage Windows command-line utility developers to use VT sequences first over the classic Windows APIs to gain the benefit of a united ecosystem with all platforms. However, one significant missing piece is that other platforms have a wide array of client-side helper libraries for handling input like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and graphical display like [ncurses](https://invisible-island.net/ncurses/ncurses.html). This particular future road map element represents the exploration of what the ecosystem offers and how we can accelerate the adoption of VT sequences in Windows command-line applications over the classic Console API. +**\[Future\]** With the support and documentation of [virtual terminal sequences](console-virtual-terminal-sequences.md) on the client side, we strongly encourage Windows command-line utility developers to use VT sequences first over the classic Windows APIs to gain the benefit of a united ecosystem with all platforms. However, one significant missing piece is that other platforms have a wide array of client-side helper libraries for handling input like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and graphical display like [ncurses](https://invisible-island.net/ncurses/ncurses.html). This particular future road map element represents the exploration of what the ecosystem offers and how we can accelerate the adoption of VT sequences in Windows command-line applications over the classic Console API. ### Sequence Passthrough -**\[Future\]** While the combination of virtual terminal client and server implementations allows the full mixing and matching of client command-line and terminal hosting applications that speak either the classic Windows Console APIs or Virtual Terminal Sequences, there is an overhead cost to translating the world into the classic compatible Windows method and then back into the more universal VT method. Once the market is sufficiently virtual terminal sequences and UTF-8 on Windows, the conversion/interpretation job of the console host can be optionally disabled and turn into a simple API call servicer and relay from device calls to the hosting application via the psuedoconsole. This increases performance and maximizes the dialect of sequences that can be spoken between client application and the terminal enabling additional interactivity scenarios and finally bringing the Windows world into the family with all other platforms in the command-line application space. +**\[Future\]** While the combination of virtual terminal client and server implementations allows the full mixing and matching of client command-line and terminal hosting applications that speak either the classic [Windows Console APIs](console-functions.md) or [virtual terminal sequences](console-virtual-terminal-sequences.md), there is an overhead cost to translating the world into the classic compatible Windows method and then back into the more universal VT method. Once the market is sufficiently _virtual terminal sequences_ and UTF-8 on Windows, the conversion/interpretation job of the console host can be optionally disabled and turn into a simple API call servicer and relay from device calls to the hosting application via the [pseudoconsole](pseudoconsoles.md). This increases performance and maximizes the dialect of sequences that can be spoken between client application and the terminal enabling additional interactivity scenarios and finally bringing the Windows world into the family with all other platforms in the command-line application space. From dd186a13d2e52ad6c37ed98d477956841eed4db0 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 16:15:58 -0700 Subject: [PATCH 24/53] Add to TOC here? --- docs/TOC.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/TOC.md b/docs/TOC.md index 754b13a..c9b08bd 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -1,4 +1,9 @@ # [Home](index.md) + +## [Ecosystem Roadmap](ecosystem-roadmap.md) +## [Definitions](definitions.md) +## [Console APIs vs. Virtual Terminal](classic-vs-vt.md) + # [About Character Mode Applications](about-character-mode-applications.md) ## [Input And Output Methods](input-and-output-methods.md) ## [Console Code Pages](console-code-pages.md) From d91952205ed26ce424bd76d854a69650b89fbbd5 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 16:26:50 -0700 Subject: [PATCH 25/53] fix links --- docs/classic-vs-vt.md | 2 +- docs/console-buffer-security-and-access-rights.md | 2 +- docs/console-code-pages.md | 2 +- docs/console-control-handlers.md | 2 +- docs/console-readconsole-control.md | 2 +- docs/console-winevents.md | 6 +++--- docs/consoles.md | 2 +- docs/createconsolescreenbuffer.md | 2 +- docs/fillconsoleoutputattribute.md | 2 +- docs/fillconsoleoutputcharacter.md | 2 +- docs/high-level-console-input-and-output-functions.md | 2 +- docs/includes/no-vt-equiv-banner.md | 2 +- docs/includes/no-vt-equiv-shell-banner.md | 2 +- docs/includes/not-recommended-banner.md | 2 +- docs/key-event-record-str.md | 2 +- docs/mouse-event-record-str.md | 2 +- 16 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index d451070..84b5adf 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -63,7 +63,7 @@ For all new and ongoing development on Windows, virtual terminal sequences are r A limited subset of Windows Console APIs are still necessary to establish the initial environment as the Windows platform still differs from others in process, signal, device, and encoding handling: -- The standard handles to a process will still be controlled with **[GetStdHandle](getstdhandle.md)** and **[SetStdHandle](setsetdhandle.md)**. +- The standard handles to a process will still be controlled with **[GetStdHandle](getstdhandle.md)** and **[SetStdHandle](setstdhandle.md)**. - Configuration of the console modes on a handle to opt in to Virtual Terminal Sequence support will be handled with **[GetConsoleMode](getconsolemode.md)** and **[SetConsoleMode](setconsolemode.md)**. - Declaration of code page or UTF-8 support is conducted with [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods. - Some level of overall process management may be required with the [**AllocConsole**](allocconsole.md), [**AttachConsole**](attachconsole.md) and [**FreeConsole**](freeconsole.md) to join or leave a console device session. diff --git a/docs/console-buffer-security-and-access-rights.md b/docs/console-buffer-security-and-access-rights.md index 8be29d3..f66cd21 100644 --- a/docs/console-buffer-security-and-access-rights.md +++ b/docs/console-buffer-security-and-access-rights.md @@ -44,7 +44,7 @@ The term "wrong-way verbs" is intended to apply to the operation that is the con The two scenarios where this can be found are: 1. **[Universal Windows Platform console apps](https://docs.microsoft.com/windows/uwp/launch-resume/console-uwp)**. As these are cousins of other Universal Windows Platform applications, they hold a promise that they are isolated from other applications and provide user guarantees around the effects of their operation. -1. Any console application intentionally launched with a lower **[integrity level](https://docs.microsoft.com/windows/win32/secauthz/mandatory-integrity-control)** than the existing session which can be accomplished with **[labeling or token manipulation during CreateProcess](https://docs.microsoft.com/en-us/previous-versions/dotnet/articles/bb625960(v=msdn.10))**. +1. Any console application intentionally launched with a lower **[integrity level](https://docs.microsoft.com/windows/win32/secauthz/mandatory-integrity-control)** than the existing session which can be accomplished with **[labeling or token manipulation during CreateProcess](https://docs.microsoft.com/previous-versions/dotnet/articles/bb625960(v=msdn.10))**. If either of these scenarios is detected, the console will apply the "wrong-way verbs" flag to the command-line application connection and reject calls to the following APIs to reduce the surface of communication between the levels: diff --git a/docs/console-code-pages.md b/docs/console-code-pages.md index 6f6c172..ceed477 100644 --- a/docs/console-code-pages.md +++ b/docs/console-code-pages.md @@ -27,4 +27,4 @@ The identifiers of the code pages available on the local computer are stored in For information about using the registry functions to determine the available code pages, see [**Registry**](https://msdn.microsoft.com/library/windows/desktop/ms724871). > [!TIP] -> It is recommended for all new and updated command-line applications to avoid code pages and use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. UTF-16 formatted text can be sent to the *W* family of console APIs. UTF-8 formatted text can be sent to the *A* family of console APIs after ensuring the code page is first set to **[65001 (CP_UTF8)](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)** with the [**SetConsoleCP**](setconsolecp.md) and [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. +> It is recommended for all new and updated command-line applications to avoid code pages and use **[Unicode](https://docs.microsoft.com/windows/win32/intl/unicode)**. UTF-16 formatted text can be sent to the *W* family of console APIs. UTF-8 formatted text can be sent to the *A* family of console APIs after ensuring the code page is first set to **[65001 (CP_UTF8)](https://docs.microsoft.com/windows/win32/intl/code-page-identifiers)** with the [**SetConsoleCP**](setconsolecp.md) and [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. diff --git a/docs/console-control-handlers.md b/docs/console-control-handlers.md index 0b84375..2cb6f8c 100644 --- a/docs/console-control-handlers.md +++ b/docs/console-control-handlers.md @@ -21,6 +21,6 @@ Each console process has its own list of control handler functions that are call The function's *dwCtrlType* parameter identifies which control signal was received, and the return value indicates whether the signal was handled. -A new thread is started inside the command-line client process to run the handler routines. More information on the timeout values and action of this thread can be found in the [**HandlerRoutine**](handlerroutine#remarks) function documentation. +A new thread is started inside the command-line client process to run the handler routines. More information on the timeout values and action of this thread can be found in the [**HandlerRoutine**](handlerroutine.md#remarks) function documentation. For an example of a control handler function, see [Registering a Control Handler Function](registering-a-control-handler-function.md). diff --git a/docs/console-readconsole-control.md b/docs/console-readconsole-control.md index 40cd121..a1b68b0 100644 --- a/docs/console-readconsole-control.md +++ b/docs/console-readconsole-control.md @@ -62,7 +62,7 @@ The state of the control keys. This member can be one or more of the following v | Value | Meaning | |-|-| | **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | -| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str.md#remarks). | | **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | | **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | | **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | diff --git a/docs/console-winevents.md b/docs/console-winevents.md index a3f8690..cc9fe72 100644 --- a/docs/console-winevents.md +++ b/docs/console-winevents.md @@ -56,13 +56,13 @@ The following event constants are used in the *event* parameter of the [*WinEven | Constant/value | Description | |-|-| -| **EVENT_CONSOLE_CARET** 0x4001 | The console caret has moved. The *idObject* parameter is one or more of the following values: **CONSOLE_CARET_SELECTION** or **CONSOLE_CARET_VISIBLE**. The *idChild* parameter is a **[COORD](coord-str)** structure that specifies the cursor's current position. | +| **EVENT_CONSOLE_CARET** 0x4001 | The console caret has moved. The *idObject* parameter is one or more of the following values: **CONSOLE_CARET_SELECTION** or **CONSOLE_CARET_VISIBLE**. The *idChild* parameter is a **[COORD](coord-str.md)** structure that specifies the cursor's current position. | | **EVENT_CONSOLE_END_APPLICATION** 0x4007 | A console process has exited. The *idObject* parameter contains the process identifier of the terminated process. | | **EVENT_CONSOLE_LAYOUT** 0x4005 | The console layout has changed. | | **EVENT_CONSOLE_START_APPLICATION** 0x4006 | A new console process has started. The *idObject* parameter contains the process identifier of the newly created process. If the application is a 16-bit application, the *idChild* parameter is **CONSOLE_APPLICATION_16BIT** and *idObject* is the process identifier of the NTVDM session associated with the console. | -|**EVENT_CONSOLE_UPDATE_REGION** 0x4002 | More than one character has changed. The *idObject* parameter is a **[COORD](coord-str)** structure that specifies the start of the changed region. The *idChild* parameter is a **COORD** structure that specifies the end of the changed region. | +|**EVENT_CONSOLE_UPDATE_REGION** 0x4002 | More than one character has changed. The *idObject* parameter is a **[COORD](coord-str.md)** structure that specifies the start of the changed region. The *idChild* parameter is a **COORD** structure that specifies the end of the changed region. | |**EVENT_CONSOLE_UPDATE_SCROLL** 0x4004 | The console has scrolled. The *idObject* parameter is the horizontal distance the console has scrolled. The *idChild* parameter is the vertical distance the console has scrolled. | -|**EVENT_CONSOLE_UPDATE_SIMPLE** 0x4003 | A single character has changed. The *idObject* parameter is a **[COORD](coord-str)** structure that specifies the character that has changed. The *idChild* parameter specifies the character in the low word and the **[character attributes](console-screen-buffers.md#character-attributes)** in the high word. | +|**EVENT_CONSOLE_UPDATE_SIMPLE** 0x4003 | A single character has changed. The *idObject* parameter is a **[COORD](coord-str.md)** structure that specifies the character that has changed. The *idChild* parameter specifies the character in the low word and the **[character attributes](console-screen-buffers.md#character-attributes)** in the high word. | ## Requirements diff --git a/docs/consoles.md b/docs/consoles.md index c3fda2a..a1a18db 100644 --- a/docs/consoles.md +++ b/docs/consoles.md @@ -22,7 +22,7 @@ A *console* is an application that provides I/O services to character-mode appli A console consists of an input buffer and one or more screen buffers. The *input buffer* contains a queue of input records, each of which contains information about an input event. The input queue always includes key-press and key-release events. It may also include mouse events (pointer movements and button presses and releases) and events during which user actions affect the size of the active screen buffer. A *screen buffer* is a two-dimensional array of character and color data for output in a console window. Any number of processes can share a console. > [!TIP] ->A broader idea of consoles and how they relate to terminals and command-line client applications can be found in the **[ecosystem roadmap](ecosystem-roadmap)**. +>A broader idea of consoles and how they relate to terminals and command-line client applications can be found in the **[ecosystem roadmap](ecosystem-roadmap.md)**. - [Creation of a Console](creation-of-a-console.md) - [Attaching to a Console](attaching-to-a-console.md) diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index c44a516..e049c17 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -96,7 +96,7 @@ The calling process can use the [**DuplicateHandle**](https://msdn.microsoft.com To close the console screen buffer handle, use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. > [!TIP] -> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. +> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences.md#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. ## Examples diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index 257198c..cbe07ba 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -79,7 +79,7 @@ If the number of character cells whose attributes are to be set extends beyond t The character values at the positions written to are not changed. > [!TIP] -> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. +> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences.md#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences.md#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. ## Requirements diff --git a/docs/fillconsoleoutputcharacter.md b/docs/fillconsoleoutputcharacter.md index 3c36434..ed957a0 100644 --- a/docs/fillconsoleoutputcharacter.md +++ b/docs/fillconsoleoutputcharacter.md @@ -89,7 +89,7 @@ The attribute values at the positions written are not changed. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] > [!TIP] -> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. +> This API is not recommended and does not have a specific **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Filling the region outside the viewable window is not supported and is reserved for the terminal's history space. Filling a visible region with new text or color is performed through **[moving the cursor](console-virtual-terminal-sequences.md#cursor-positioning)**, **[setting the new attributes](console-virtual-terminal-sequences.md#text-formatting)**, then writing the desired text for that region, repeating characters if necessary for the length of the fill run. Additional cursor movement may be required followed by writing the desired text to fill a rectangular region. The client application is expected to keep its own memory of what is on the screen and is not able to query the remote state. More information can be found in **[classic console versus virtual terminal](classic-vs-vt.md)** documentation. ## Requirements diff --git a/docs/high-level-console-input-and-output-functions.md b/docs/high-level-console-input-and-output-functions.md index 78a7b71..2f5e06d 100644 --- a/docs/high-level-console-input-and-output-functions.md +++ b/docs/high-level-console-input-and-output-functions.md @@ -29,6 +29,6 @@ A process can use [**WriteFile**](https://msdn.microsoft.com/library/windows/des Characters written by [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md), or echoed by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md), are inserted in a screen buffer at the current cursor position. As each character is written, the cursor position advances to the next character cell; however, the behavior at the end of a row depends on the console screen buffer's wrap at EOL output mode. -Further detail about the position of the cursor can be found through **[virtual terminals sequences](console-virtual-terminal-sequences.md)**, specifically in the **[query state](console-virtual-terminal-sequences#query-state)** category for finding the current position and the **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** category for setting the current position. Alternatively, an application can use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the current cursor position and the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function to set the cursor position. However, the **virtual terminal sequences** mechanism is preferred for all new and ongoing development. More details on the strategy behind this decision can be found in the **[classic functions versus virtual terminal](classic-vs-vt.md)** and **[ecosystem roadmap](ecosystem-roadmap.md)** documentation. +Further detail about the position of the cursor can be found through **[virtual terminals sequences](console-virtual-terminal-sequences.md)**, specifically in the **[query state](console-virtual-terminal-sequences.md#query-state)** category for finding the current position and the **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** category for setting the current position. Alternatively, an application can use the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function to determine the current cursor position and the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function to set the cursor position. However, the **virtual terminal sequences** mechanism is preferred for all new and ongoing development. More details on the strategy behind this decision can be found in the **[classic functions versus virtual terminal](classic-vs-vt.md)** and **[ecosystem roadmap](ecosystem-roadmap.md)** documentation. For an example that uses the high-level console I/O functions, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). diff --git a/docs/includes/no-vt-equiv-banner.md b/docs/includes/no-vt-equiv-banner.md index e23659d..e397bb9 100644 --- a/docs/includes/no-vt-equiv-banner.md +++ b/docs/includes/no-vt-equiv-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/includes/no-vt-equiv-shell-banner.md b/docs/includes/no-vt-equiv-shell-banner.md index bc69216..685dc73 100644 --- a/docs/includes/no-vt-equiv-shell-banner.md +++ b/docs/includes/no-vt-equiv-shell-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file diff --git a/docs/includes/not-recommended-banner.md b/docs/includes/not-recommended-banner.md index 7c74372..fb76346 100644 --- a/docs/includes/not-recommended-banner.md +++ b/docs/includes/not-recommended-banner.md @@ -1,2 +1,2 @@ > [!IMPORTANT] -> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt)** document. \ No newline at end of file +> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap.md)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt.md)** document. \ No newline at end of file diff --git a/docs/key-event-record-str.md b/docs/key-event-record-str.md index 0a92668..4aaddcf 100644 --- a/docs/key-event-record-str.md +++ b/docs/key-event-record-str.md @@ -80,7 +80,7 @@ The state of the control keys. This member can be one or more of the following v | Value | Meaning | |-|-| | **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | -| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str.md#remarks). | | **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | | **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | | **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | diff --git a/docs/mouse-event-record-str.md b/docs/mouse-event-record-str.md index 1e0329f..02c6f1d 100644 --- a/docs/mouse-event-record-str.md +++ b/docs/mouse-event-record-str.md @@ -72,7 +72,7 @@ The state of the control keys. This member can be one or more of the following v | Value | Meaning | |-|-| | **CAPSLOCK_ON** 0x0080 | The CAPS LOCK light is on. | -| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str#remarks). | +| **ENHANCED_KEY** 0x0100 | The key is enhanced. See [remarks](key-event-record-str.md#remarks). | | **LEFT_ALT_PRESSED** 0x0002 | The left ALT key is pressed. | | **LEFT_CTRL_PRESSED** 0x0008 | The left CTRL key is pressed. | | **NUMLOCK_ON** 0x0020 | The NUM LOCK light is on. | From b0399d2382e22da5f6b50b65ec0fdc13122beeaf Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 16:28:36 -0700 Subject: [PATCH 26/53] Try headerless table to see if it shows correctly on the website. --- docs/setstdhandle.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/setstdhandle.md b/docs/setstdhandle.md index aeefdfd..9747fba 100644 --- a/docs/setstdhandle.md +++ b/docs/setstdhandle.md @@ -76,6 +76,24 @@ For an example, see [Creating a Child Process with Redirected Input and Output]( ## Requirements +:::row::: + :::column::: + Minimum supported client + :::column-end::: + :::column::: + Windows 2000 Professional \[desktop apps only\] + :::column-end::: +:::row-end::: +:::row::: + :::column::: + Minimum supported server + :::column-end::: + :::column::: + Windows 2000 Server \[desktop apps only\] + :::column-end::: +:::row-end::: + + | | | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | From 5bf81a4e99c489d9566d3292474af660b0840113 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Tue, 6 Oct 2020 16:44:17 -0700 Subject: [PATCH 27/53] dustin comments + a bunch of psuedo/pseudo fixes. --- docs/classic-vs-vt.md | 18 ++++++++++-------- docs/closepseudoconsole.md | 2 +- docs/createpseudoconsole.md | 2 +- docs/definitions.md | 4 ++-- docs/ecosystem-roadmap.md | 2 +- docs/resizepseudoconsole.md | 2 +- 6 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 84b5adf..690521c 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -33,7 +33,9 @@ Virtual Terminal Sequences hold a major advantage for remote access as they requ Some of the Windows Console APIs provide low-level access to the input and output buffers or convenience functions for interactive command-lines like aliases and command history programmed within the console subsystem and host environment, instead of within the command-line client application itself. This is in contrast to other platforms where both the memory of the current state of the application and convenience functionality is the responsibility of the command-line utility or shell itself. -While the Windows way of handling this responsibility in the console host and API makes it quicker and easier to write a command-line application with these features and without responsibility of remembering drawing state or handling editing convenience features, it makes it nearly impossible to connect those activities remotely across platforms, versions, or scenarios due to variations in implementations and availability. It also makes the final interactive experience of these Windows command-line applications completely dependent on the console host's implementation, priorities, and release cycle. +While the Windows way of handling this responsibility in the console host and API makes it quicker and easier to write a command-line application with these features and without responsibility of remembering drawing state or handling editing convenience features, it makes it nearly impossible to connect those activities remotely across platforms, versions, or scenarios due to variations in implementations and availability. It also makes the final interactive experience of these Windows command-line applications completely dependent on the console host's implementation, priorities, and release cycle. + +For example, advanced line editing features like syntax highlighting and complex selection are only possible when a command-line application handles editing concerns itself. The console could never have enough context to fully understand these scenarios in a broad manner like the client application can. By contrast, other platforms handle these activities and virtual terminal communication itself through reusable client-side libraries like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and [ncurses](https://invisible-island.net/ncurses/ncurses.html). The final terminal is only responsible for displaying information and receiving input through that bidirectional communication channel. @@ -43,32 +45,32 @@ On Windows, some actions can be performed in the opposite-to-natural direction o ### Direct Window Access -On Windows, the exact window handle to the hosting window is available through the Console API surface. This allows a command-line utility to perform advanced window operations by reaching into the wide gamut of Win32 APIs permitted against a window handle and manipulate the window state, frame, icon, or other properties about the window. By contrast, on other platforms with virtual terminal sequences, there is a specific gamut of commands that can be performed against the window to do things like changing its size or displayed title and they must be done in the same band and under the same control as the remainder of the stream. +On Windows, the exact window handle to the hosting window is available through the Console API surface. This allows a command-line utility to perform advanced window operations by reaching into the wide gamut of Win32 APIs permitted against a window handle and manipulate the window state, frame, icon, or other properties about the window. By contrast, on other platforms with virtual terminal sequences, there is a narrow set of commands that can be performed against the window to do things like changing its size or displayed title and they must be done in the same band and under the same control as the remainder of the stream. As Windows has evolved, the security controls and restrictions on window handles have increased. Additionally, the nature and existence of an application-addressable window handle on any specific user interface element has evolved, especially with the increased support of device form factors and platforms. This makes direct window access to command-line applications fragile as the platform and experiences evolve. ### Unicode -The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist, but generally speaking, when otherwise undefined, using UTF-8 is accepted as the appropriate default balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. +The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist. However, when otherwise undefined, using UTF-8 is widely accepted as the appropriate default. It represents the balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. -The Windows console platform has and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development and also accept UTF-16 as an algorithmically-translatable alternative representation of the same information that is more compatible with Windows' historical Unicode philosophies extending from initial UCS-2 implementations. +The Windows console platform has supported and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development and also accept UTF-16 as an algorithmically-translatable alternative. -UTF-8 support in the console can be found via the _A_ variant of all Console APIs or the filesystem [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) methods against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. +UTF-8 support in the console can be found via the _A_ variant of all Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. -UTF-16 support in the console can be found with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. +UTF-16 support in the console can be utilized with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. ## Recommendations For all new and ongoing development on Windows, virtual terminal sequences are recommended as the way of interacting with the terminal. This will converge Windows command-line client applications with the style of application programming on all other platforms. -A limited subset of Windows Console APIs are still necessary to establish the initial environment as the Windows platform still differs from others in process, signal, device, and encoding handling: +A limited subset of Windows Console APIs is still necessary to establish the initial environment as the Windows platform still differs from others in process, signal, device, and encoding handling: - The standard handles to a process will still be controlled with **[GetStdHandle](getstdhandle.md)** and **[SetStdHandle](setstdhandle.md)**. - Configuration of the console modes on a handle to opt in to Virtual Terminal Sequence support will be handled with **[GetConsoleMode](getconsolemode.md)** and **[SetConsoleMode](setconsolemode.md)**. - Declaration of code page or UTF-8 support is conducted with [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods. - Some level of overall process management may be required with the [**AllocConsole**](allocconsole.md), [**AttachConsole**](attachconsole.md) and [**FreeConsole**](freeconsole.md) to join or leave a console device session. - Signals and signal handling will continue to be conducted with [**SetConsoleCtrlHandler**](setconsolectrlhandler.md), [**HandlerRoutine**](handlerroutine.md), and [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md). -- Communication with the console device handles can be conducted with [**WriteConsole**](writeconsole.md), [**ReadConsole**](readconsole.md), [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) and [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467). +- Communication with the console device handles can be conducted with [**WriteConsole**](writeconsole.md) and [**ReadConsole**](readconsole.md). - These may also be leveraged through programming language runtimes in the forms of: - C Runtime (CRT): [Stream I/O](https://docs.microsoft.com/cpp/c-runtime-library/stream-i-o) like **printf**, **scanf**, **putc**, **getc**, or [other levels of I/O functions](https://docs.microsoft.com/cpp/c-runtime-library/input-and-output). - C++ Standard Library (STL): [iostream](https://docs.microsoft.com/cpp/standard-library/iostream) like **cout** and **cin**. diff --git a/docs/closepseudoconsole.md b/docs/closepseudoconsole.md index db9cdb4..5aa6996 100644 --- a/docs/closepseudoconsole.md +++ b/docs/closepseudoconsole.md @@ -33,7 +33,7 @@ void WINAPI ClosePseudoConsole( ## Parameters *hPC* \[in\] -A handle to an active psuedoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). +A handle to an active pseudoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). ## Return value diff --git a/docs/createpseudoconsole.md b/docs/createpseudoconsole.md index eac2e1a..1c373f4 100644 --- a/docs/createpseudoconsole.md +++ b/docs/createpseudoconsole.md @@ -81,7 +81,7 @@ If using `PSEUDOCONSOLE_INHERIT_CURSOR`, the calling application should be prepa ## Examples -For a full walkthrough on using this function to establish a psuedoconsole session, please see [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md). +For a full walkthrough on using this function to establish a pseudoconsole session, please see [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md). ## Requirements diff --git a/docs/definitions.md b/docs/definitions.md index ce98fc8..fdfa212 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -32,7 +32,7 @@ Within this space, we're referring to "clients" as applications that do the work ## Console Subsystem -This is a catch-all term representing all modules in the console team's space. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). +This is a catch-all term representing all modules affecting console and command-line operations. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. @@ -40,7 +40,7 @@ The console host, command-line client applications, the console driver, the cons The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. -## Psuedoconsole +## Pseudoconsole This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index fac69f8..51d51d8 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -48,7 +48,7 @@ All of our products are now available on GitHub in our open source repository, [ ### Windows Console Host -This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the [pseudoconsole](pseudoconsoles.md) infrastructure with a modern terminal application. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _psuedoconsole_ infrastructure. +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the [pseudoconsole](pseudoconsoles.md) infrastructure with a modern terminal application. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _pseudoconsole_ infrastructure. ### Windows Terminal diff --git a/docs/resizepseudoconsole.md b/docs/resizepseudoconsole.md index ddf9762..6945895 100644 --- a/docs/resizepseudoconsole.md +++ b/docs/resizepseudoconsole.md @@ -37,7 +37,7 @@ HRESULT WINAPI ResizePseudoConsole( ## Parameters *hPC* \[in\] -A handle to an active psuedoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). +A handle to an active pseudoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). *size* \[in\] The dimensions of the window/buffer in count of characters that will be used for the internal buffer of this pseudoconsole. From a38e503cef3890f1d9819f8efc27f3ca4a3ae4a7 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 09:51:12 -0700 Subject: [PATCH 28/53] try markdig grid table --- docs/getstdhandle.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index bccabe0..38fff33 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -87,8 +87,11 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | -|-|-| ++---------+---------+ +| This is | a table | + + ++----+----+ | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | | Header | ProcessEnv.h (via Winbase.h, include Windows.h) | From fe8a8fb8e1c769b7f64f3a346b37778b3b146335 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 09:53:54 -0700 Subject: [PATCH 29/53] Revert "try markdig grid table" This reverts commit a38e503cef3890f1d9819f8efc27f3ca4a3ae4a7. --- docs/getstdhandle.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index 38fff33..bccabe0 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -87,11 +87,8 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -+---------+---------+ -| This is | a table | - - -+----+----+ +| | | +|-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | | Header | ProcessEnv.h (via Winbase.h, include Windows.h) | From e90972f95afe0bc4887484fb6d998776aa21f2b0 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 09:54:01 -0700 Subject: [PATCH 30/53] Revert "Try headerless table to see if it shows correctly on the website." This reverts commit b0399d2382e22da5f6b50b65ec0fdc13122beeaf. --- docs/setstdhandle.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/setstdhandle.md b/docs/setstdhandle.md index 9747fba..aeefdfd 100644 --- a/docs/setstdhandle.md +++ b/docs/setstdhandle.md @@ -76,24 +76,6 @@ For an example, see [Creating a Child Process with Redirected Input and Output]( ## Requirements -:::row::: - :::column::: - Minimum supported client - :::column-end::: - :::column::: - Windows 2000 Professional \[desktop apps only\] - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Minimum supported server - :::column-end::: - :::column::: - Windows 2000 Server \[desktop apps only\] - :::column-end::: -:::row-end::: - - | | | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | From 8583f05a94221e0fff4cc81cc9195f144c69c913 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 15:20:46 -0700 Subject: [PATCH 31/53] A bunch more cleanup and tips. --- README.md | 2 +- docs/about-character-mode-applications.md | 2 +- docs/classic-vs-vt.md | 4 +++- docs/clearing-the-screen.md | 27 +++------------------- docs/console-modes.md | 2 +- docs/console-screen-buffer-infoex.md | 2 +- docs/console-screen-buffers.md | 3 +++ docs/console-virtual-terminal-sequences.md | 2 +- docs/consoles.md | 2 +- docs/createconsolescreenbuffer.md | 3 +-- docs/creating-a-pseudoconsole-session.md | 4 ++-- docs/definitions.md | 8 +++---- docs/ecosystem-roadmap.md | 6 ++--- docs/flushconsoleinputbuffer.md | 7 ++++++ docs/getconsolecursorinfo.md | 4 ++++ docs/getconsoledisplaymode.md | 4 +++- docs/getconsolefontsize.md | 4 ++++ docs/getconsoleoriginaltitle.md | 3 +++ docs/getconsoleprocesslist.md | 2 ++ docs/getconsolescreenbufferinfo.md | 5 ++-- docs/getconsolescreenbufferinfoex.md | 5 ++-- docs/getconsoleselectioninfo.md | 2 ++ docs/getconsoletitle.md | 3 +++ docs/getconsolewindow.md | 3 +++ docs/getcurrentconsolefont.md | 2 ++ docs/getcurrentconsolefontex.md | 2 ++ docs/getlargestconsolewindowsize.md | 2 ++ docs/getnumberofconsoleinputevents.md | 2 -- docs/getnumberofconsolemousebuttons.md | 3 +++ docs/high-level-console-modes.md | 8 +------ docs/includes/no-vt-equiv-alt-buf.md | 2 ++ docs/includes/no-vt-equiv-banner.md | 2 +- docs/includes/no-vt-equiv-local-context.md | 2 ++ docs/includes/no-vt-equiv-shell-banner.md | 2 +- docs/includes/no-vt-equiv-user-priv.md | 2 ++ docs/includes/no-vt-equiv-wrong-way.md | 2 ++ docs/legacymode.md | 4 ++-- docs/peekconsoleinput.md | 2 -- docs/readconsoleoutputattribute.md | 2 ++ docs/readconsoleoutputcharacter.md | 2 ++ docs/scrollconsolescreenbuffer.md | 3 +++ docs/setconsoleactivescreenbuffer.md | 2 ++ docs/setconsolecursorinfo.md | 3 +++ docs/setconsolecursorposition.md | 3 +++ 44 files changed, 99 insertions(+), 62 deletions(-) create mode 100644 docs/includes/no-vt-equiv-alt-buf.md create mode 100644 docs/includes/no-vt-equiv-local-context.md create mode 100644 docs/includes/no-vt-equiv-user-priv.md create mode 100644 docs/includes/no-vt-equiv-wrong-way.md diff --git a/README.md b/README.md index 14a6a03..30abd57 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Welcome to the Windows Console documentation repo. The MSDN Console Docs are generated from the markdown stored in this repo. The published docs can be found at [https://docs.microsoft.com/windows/console/](https://docs.microsoft.com/windows/console/) -For code issues related to the Windows Console, Windows Terminal, and related command-line and terminal tooling products acquired with Windows, from the Windows Store, or other sources like GitHub, please check out the [Microsoft/Terminal](https://github.com/microsoft/terminal) repository. +For code issues related to the Windows Console, Windows Terminal, and related command-line and terminal tooling products acquired with Windows, from the Windows Store, or other sources like GitHub, please check out the [microsoft/terminal](https://github.com/microsoft/terminal) repository. # Metadata Each content page in this repo requires some metadata expressed as [YAML](https://en.wikipedia.org/wiki/YAML), stored at the top of each doc between '---' markers. For example: diff --git a/docs/about-character-mode-applications.md b/docs/about-character-mode-applications.md index 70c475d..f6154c3 100644 --- a/docs/about-character-mode-applications.md +++ b/docs/about-character-mode-applications.md @@ -25,7 +25,7 @@ Character mode (or "command-line") applications: Character mode applications communicate with the end-user through a "console" (or "terminal") application. A console converts user input from keyboard, mouse, touch-screen, pen, etc., and sends it to a character mode application's stdin. A console may also display a character mode application's text output on the user's screen. -In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user. However, in the recent era, the console team is encouraging all character mode applications to be developed with [virtual terminal sequences](console-virtual-terminal-sequences.md) over the classic API calls for maximum compatibility between Windows and other operating system platforms. More details on this transition and the trade offs involved can be found in our discussion of [classic APIs versus virtual terminal sequences](classic-vs-vt.md). +In Windows, the console is built-in and provides a rich API through which character mode applications can interact with the user. However, in the recent era, the console team is encouraging all character mode applications to be developed with [virtual terminal sequences](console-virtual-terminal-sequences.md) over the classic API calls for maximum compatibility between Windows and other operating systems. More details on this transition and the trade offs involved can be found in our discussion of [classic APIs versus virtual terminal sequences](classic-vs-vt.md). - [Consoles](consoles.md) - [Input and Output Methods](input-and-output-methods.md) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 690521c..3bd6a8b 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -75,8 +75,10 @@ A limited subset of Windows Console APIs is still necessary to establish the ini - C Runtime (CRT): [Stream I/O](https://docs.microsoft.com/cpp/c-runtime-library/stream-i-o) like **printf**, **scanf**, **putc**, **getc**, or [other levels of I/O functions](https://docs.microsoft.com/cpp/c-runtime-library/input-and-output). - C++ Standard Library (STL): [iostream](https://docs.microsoft.com/cpp/standard-library/iostream) like **cout** and **cin**. - .NET Runtime: [System.Console](https://docs.microsoft.com/dotnet/api/system.console) like **Console.WriteLine**. + - Applications that must be aware of window size changes will still need to use [**ReadConsoleInput**](readconsoleinput.md) to receive them interleaved with key events as **ReadConsole** alone will discard them. +- Finding the window size must still be performed with [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) for applications attempting to draw columns, grids, or fill the display. Window and buffer size will match in a [pseudoconsole](pseudoconsole.md) session. -There are no plans to remove the Windows console APIs from the platform. On the contrary, the Windows console host has provided the [pseudoconsole](pseudoconsoles.md) technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. This translation is not perfect and requires the console host window to maintain a simulated environment of what Windows would have displayed to the user and project a replica of that to the pseudoconsole host. Any console API call without an equivalent is operated within the simulated environment to serve the needs of the legacy command-line client application and only the effects are propagated onto the final host. +There are no plans to remove the Windows console APIs from the platform. On the contrary, the Windows console host has provided the [pseudoconsole](pseudoconsoles.md) technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. This translation is not perfect and requires the console host window to maintain a simulated environment of what Windows would have displayed to the user and project a replica of that to the pseudoconsole host. All console API calls are operated within the simulated environment to serve the needs of the legacy command-line client application and only the effects are propagated onto the final host. A command-line application desiring full compatibility across platforms and full support of all new features and scenarios both on Windows and elsewhere is therefore recommended to move to Virtual Terminal sequences and adjust the architecture of command-line applications to align with all platforms. diff --git a/docs/clearing-the-screen.md b/docs/clearing-the-screen.md index 4fcf203..74be93b 100644 --- a/docs/clearing-the-screen.md +++ b/docs/clearing-the-screen.md @@ -62,6 +62,9 @@ int main( void ) return ::GetLastError(); } + // To also clear the scroll back, emit L"\x1b[3J" as well. + // 2J only clears the visible window and 3J only clears the scroll back. + // Restore the mode on the way out to be nice to other command-line applications. SetConsoleMode(hStdOut, originalMode); @@ -69,16 +72,6 @@ int main( void ) } ``` -A variation on this command is to use the "clear buffer" command to remove all history scrolling up and down, not just what is visible within the window. - -```C -... - -PCWSTR sequence = L"\x1b[3J"; - -... -``` - You can find additional variations on this command in the virtual terminal sequences documentation on **[Erase In Display](console-virtual-terminal-sequences.md#text-modification)**. ## Example 2 @@ -205,17 +198,3 @@ int main(void) return 0; } ``` - -## Example 4 - -The fourth method is to use the C run-time **system** function. The **system** function invokes the **cls** command provided by the command interpreter `cmd.exe` to clear the screen. - -```C -#include - -int main(void) -{ - system("cls"); - return 0; -} -``` diff --git a/docs/console-modes.md b/docs/console-modes.md index 7463571..a77b920 100644 --- a/docs/console-modes.md +++ b/docs/console-modes.md @@ -23,4 +23,4 @@ The [**GetConsoleMode**](getconsolemode.md) function reports the current input m A command-line application should expect that other command-line applications may change the console mode at any time and may not restore it to its original form before control is returned. Additionally, we recommend that all command-line applications should capture the initial console mode at startup and attempt to restore it when exiting to ensure minimal impact on other command-line applications attached to the same console. -The [**GetConsoleDisplayMode**](getconsoledisplaymode.md) function reports whether the current console is in full-screen mode and whether it communicates directly with the hardware. +The [**GetConsoleDisplayMode**](getconsoledisplaymode.md) function reports whether the current console is in full-screen mode. diff --git a/docs/console-screen-buffer-infoex.md b/docs/console-screen-buffer-infoex.md index 20662ab..d6789fd 100644 --- a/docs/console-screen-buffer-infoex.md +++ b/docs/console-screen-buffer-infoex.md @@ -74,7 +74,7 @@ A [**COORD**](coord-str.md) structure that contains the maximum size of the cons The fill attribute for console pop-ups. **bFullscreenSupported** -If this member is `TRUE`, full-screen mode is supported; otherwise, it is not. +If this member is `TRUE`, full-screen mode is supported; otherwise, it is not. This will always be `FALSE` for systems after Windows Vista with the [WDDM driver model](https://docs.microsoft.com/windows-hardware/drivers/display/introduction-to-the-windows-vista-and-later-display-driver-model) as true direct VGA access to the monitor is no longer available. **ColorTable** An array of [**COLORREF**](https://msdn.microsoft.com/library/windows/desktop/dd183449) values that describe the console's color settings. diff --git a/docs/console-screen-buffers.md b/docs/console-screen-buffers.md index bd47233..790adc8 100644 --- a/docs/console-screen-buffers.md +++ b/docs/console-screen-buffers.md @@ -35,6 +35,9 @@ When a screen buffer is created, it contains space characters in every position. Applications that change any of the console screen buffer properties should either create their own screen buffer or save the state of the inherited screen buffer during startup and restore it at exit. This cooperative behavior is required to ensure that other applications sharing the same console session are not impacted by the changes. +> [!TIP] +> It is recommended to use the [**alternate buffer mode**](console-virtual-terminal-sequences.md#alternate-screen-buffer) going forward, if possible, instead of creating a second screen buffer for this purpose. **Alternate buffer mode** offers increased compatibility across remote devices and with other platforms. Please see our discussion on [**classic console APIs versus virtual terminal**](classic-vs-vt.md) for more information. + ## Cursor Appearance and Position A screen buffer's cursor can be visible or hidden. When it is visible, its appearance can vary, ranging from completely filling a character cell to appearing as a horizontal line at the bottom of the cell. To retrieve information about the appearance and visibility of the cursor, use the [**GetConsoleCursorInfo**](getconsolecursorinfo.md) function. This function reports whether the cursor is visible and describes the appearance of the cursor as the percentage of a character cell that it fills. To set the appearance and visibility of the cursor, use the [**SetConsoleCursorInfo**](setconsolecursorinfo.md) function. diff --git a/docs/console-virtual-terminal-sequences.md b/docs/console-virtual-terminal-sequences.md index df95fa4..a7ba02f 100644 --- a/docs/console-virtual-terminal-sequences.md +++ b/docs/console-virtual-terminal-sequences.md @@ -526,7 +526,7 @@ Ctrl is generally passed through exactly as received from the system. This is ty > [!NOTE] ->Left Ctrl + Right Alt is treated as AltGr. When both are seen together, they will be stripped and the Unicode value of the character presented by the system will be passed into the target. The system will pre-translate AltGr values according to the current system input settings. +>Left Ctrl + Right Alt is treated as AltGr. When both are seen together, they will be stripped and the Unicode value of the character presented by the system will be passed into the target. The system will pre-translate AltGr values according to the current system input settings. diff --git a/docs/consoles.md b/docs/consoles.md index a1a18db..9c66511 100644 --- a/docs/consoles.md +++ b/docs/consoles.md @@ -17,7 +17,7 @@ ms.assetid: 16148ce6-d3be-40dd-b82e-50ea1df67c4e # Consoles -A *console* is an application that provides I/O services to character-mode applications. This processor-independent mechanism makes it easy to port existing character-mode applications or to create new character-mode tools and applications. +A *console* is an application that provides I/O services to character-mode applications. A console consists of an input buffer and one or more screen buffers. The *input buffer* contains a queue of input records, each of which contains information about an input event. The input queue always includes key-press and key-release events. It may also include mouse events (pointer movements and button presses and releases) and events during which user actions affect the size of the active screen buffer. A *screen buffer* is a two-dimensional array of character and color data for output in a console window. Any number of processes can share a console. diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index e049c17..427032e 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -95,8 +95,7 @@ The calling process can use the [**DuplicateHandle**](https://msdn.microsoft.com To close the console screen buffer handle, use the [**CloseHandle**](https://msdn.microsoft.com/library/windows/desktop/ms724211) function. -> [!TIP] -> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences.md#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. +[!INCLUDE [no-vt-equiv-alt-buf](./includes/no-vt-equiv-alt-buf.md)] ## Examples diff --git a/docs/creating-a-pseudoconsole-session.md b/docs/creating-a-pseudoconsole-session.md index dd560d7..d5d5f2d 100644 --- a/docs/creating-a-pseudoconsole-session.md +++ b/docs/creating-a-pseudoconsole-session.md @@ -16,7 +16,7 @@ Hosting a pseudoconsole session is a bit different than a traditional console se You can find additional background information about this system on the [initial announcement blog post](https://blogs.msdn.microsoft.com/commandline/2018/08/02/windows-command-line-introducing-the-windows-pseudo-console-conpty/). -Complete examples of using the Pseudoconsole are available on our GitHub repository [Microsoft/terminal](https://github.com/Microsoft/terminal) in the samples directory. +Complete examples of using the Pseudoconsole are available on our GitHub repository [microsoft/terminal](https://github.com/microsoft/terminal) in the samples directory. ## Preparing the communication channels @@ -29,7 +29,7 @@ The first step is to create a pair of synchronous communication channels that wi With the communications channels that have been established, identify the "read" end of the input channel and the "write" end of the output channel. This pair of handles is provided on calling [**CreatePseudoConsole**](createpseudoconsole.md) to create the object. -When creating, a size representing the X and Y dimensions (in count of characters) is also provided. This is the dimensions that will apply to the display surface for the final (terminal) presentation window. The values are used to create an in-memory buffer inside the pseudoconsole system. +On creation, a size representing the X and Y dimensions (in count of characters) is required. These are the dimensions that will apply to the display surface for the final (terminal) presentation window. The values are used to create an in-memory buffer inside the pseudoconsole system. The buffer size provide answers to client character-mode applications that probe for information using the [client-side console functions](console-functions.md) like [**GetConsoleScreenBufferInfoEx**](getconsolescreenbufferinfoex.md) and dictates the layout and positioning of text when clients use functions like [**WriteConsoleOutput**](writeconsoleoutput.md). diff --git a/docs/definitions.md b/docs/definitions.md index fdfa212..5609039 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -24,7 +24,7 @@ Standard handles do not imply a specific type of attached device, though in the ## TTY/PTY -On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that represent the same as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. +On non-Windows platforms, the TTY and PTY devices represent respectively either a true physical device or a software-created pseudo-device that are the same concept as a Windows console session: a channel where communication between a command-line client application and a server host interactivity application or physical keyboard/display device can exchange text-based information. ## Clients and Servers @@ -34,15 +34,15 @@ Within this space, we're referring to "clients" as applications that do the work This is a catch-all term representing all modules affecting console and command-line operations. It specifically refers to a flag that is a part of the Portable Executable header that specifies whether the starting application is either a command-line/console application (and must have standard handles to start) or a windows application (and does not need them). -The console host, command-line client applications, the console driver, the console API surface, the psuedoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. +The console host, command-line client applications, the console driver, the console API surface, the pseudoconsole infrastructure, terminals, configuration property sheets, the mechanisms and stubs inside the process loader, and any utilities related to the workings of these forms of applications are considered to belong to this group. ## Console Host -The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, this binary will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. +The Windows Console Host, or `conhost.exe`, is both the server application for all of the Windows Console APIs as well as the classic Windows user interface for working with command-line applications. The complete contents of this binary, both the API server and the UI, historically belonged to Windows `csrss.exe`, a critical system process, and was diverged for security and isolation purposes. Going forward, `conhost.exe` will continue to be responsible for API call servicing and translation, but the user-interface components are intended to be delegated through a pseudoconsole to a terminal. ## Pseudoconsole -This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving the API servicing, translation, and compatibility efforts with that OS component. +This is the Windows simulation of a pseudoterminal or "PTY" from other platforms. It tries to match the general interface philosophy of PTYs, providing a simple bidirectional channel of text based communication, but it supplements it on Windows with a large compatibility layer to translate the breadth of Windows applications written prior to this design philosophy change from the classic console API surface into the simple text channel communication form. Terminals can use the pseudoconsole to take ownership of the user-interface elements away from the console host, `conhost.exe`, while leaving it in charge of the API servicing, translation, and compatibility efforts. ## Terminal diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 51d51d8..2bc7d4c 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -44,11 +44,11 @@ On non-Windows platforms, the Server and Terminal roles are a single unit becaus ## Products -All of our products are now available on GitHub in our open source repository, [Microsoft/Terminal](https://github.com/microsoft/terminal). +All of our products are now available on GitHub in our open source repository, [microsoft/terminal](https://github.com/microsoft/terminal). ### Windows Console Host -This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be redistributed from the open source repository for a more up-to-date usage of the [pseudoconsole](pseudoconsoles.md) infrastructure with a modern terminal application. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _pseudoconsole_ infrastructure. +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found in the system directory as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be found in other Microsoft products built from the open source repository for a more up-to-date implementation of the [pseudoconsole](pseudoconsoles.md) infrastructure. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _pseudoconsole_ infrastructure. ### Windows Terminal @@ -86,7 +86,7 @@ In this time period, the [pseudoconsole](pseudoconsoles.md) infrastructure was i ### Terminal applications -**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [Microsoft/Terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for [pseudoconsole](pseudoconsoles.md)s to bring a first class terminal experience directly to developers on the Windows platform. +**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [microsoft/terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for [pseudoconsole](pseudoconsoles.md)s to bring a first class terminal experience directly to developers on the Windows platform. It is intended not only as a showcase for the platform including the [WinUI](https://docs.microsoft.com/windows/apps/winui/) technology, the [MSIX](https://docs.microsoft.com/windows/msix/) packaging model, and the [C++/WinRT](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/) component architecture, but also as a validation of the platform itself, driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal's unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. diff --git a/docs/flushconsoleinputbuffer.md b/docs/flushconsoleinputbuffer.md index 14ba31d..24f019c 100644 --- a/docs/flushconsoleinputbuffer.md +++ b/docs/flushconsoleinputbuffer.md @@ -32,6 +32,8 @@ api_type: # FlushConsoleInputBuffer function +[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] + Flushes the console input buffer. All input records currently in the input buffer are discarded. ## Syntax @@ -53,6 +55,11 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Attempting to empty the input queue all at once can destroy state in the queue in an unexpected manner. + ## Requirements | | | diff --git a/docs/getconsolecursorinfo.md b/docs/getconsolecursorinfo.md index f5ad55a..3786473 100644 --- a/docs/getconsolecursorinfo.md +++ b/docs/getconsolecursorinfo.md @@ -60,6 +60,10 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getconsoledisplaymode.md b/docs/getconsoledisplaymode.md index 10dc5b7..7a3f3be 100644 --- a/docs/getconsoledisplaymode.md +++ b/docs/getconsoledisplaymode.md @@ -53,7 +53,7 @@ The display mode of the console. This parameter can be one or more of the follow | **CONSOLE_FULLSCREEN_HARDWARE** 2 | Full-screen console communicating directly with the video hardware. This mode is set after the console is in **CONSOLE_FULLSCREEN** mode to indicate that the transition to full-screen mode has completed. | > [!NOTE] -> The transition to a 100% full screen video hardware mode was removed in Windows Vista (TODO: citation needed) with the replatforming of the graphics stack to WDDM (TODO: insert link). On later versions of Windows, the maximum resulting state is **CONSOLE_FULLSCREEN** representing a frameless window that appears full screen but isn't in exclusive control of the hardware. +> The transition to a 100% full screen video hardware mode was removed in Windows Vista with the replatforming of the graphics stack to [WDDM](https://docs.microsoft.com//windows-hardware/drivers/display/introduction-to-the-windows-vista-and-later-display-driver-model). On later versions of Windows, the maximum resulting state is **CONSOLE_FULLSCREEN** representing a frameless window that appears full screen but isn't in exclusive control of the hardware. ## Return value @@ -65,6 +65,8 @@ If the function fails, the return value is zero. To get extended error informati To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getconsolefontsize.md b/docs/getconsolefontsize.md index bb61f39..d5b37f5 100644 --- a/docs/getconsolefontsize.md +++ b/docs/getconsolefontsize.md @@ -57,8 +57,12 @@ If the function succeeds, the return value is a [**COORD**](coord-str.md) struct If the function fails, the width and the height are zero. To get extended error information, call [**GetLastError**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getconsoleoriginaltitle.md b/docs/getconsoleoriginaltitle.md index b29bf4b..22ece6d 100644 --- a/docs/getconsoleoriginaltitle.md +++ b/docs/getconsoleoriginaltitle.md @@ -72,6 +72,9 @@ To set the title for a console window, use the [**SetConsoleTitle**](setconsolet To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0600 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. + ## Requirements | | | diff --git a/docs/getconsoleprocesslist.md b/docs/getconsoleprocesslist.md index 8981b24..f871778 100644 --- a/docs/getconsoleprocesslist.md +++ b/docs/getconsoleprocesslist.md @@ -63,6 +63,8 @@ If a `NULL` process list was provided or the process count was 0, the call will To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0501 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-local-context](./includes/no-vt-equiv-local-context.md)] + ## Requirements | | | diff --git a/docs/getconsolescreenbufferinfo.md b/docs/getconsolescreenbufferinfo.md index 612bc0c..22f824b 100644 --- a/docs/getconsolescreenbufferinfo.md +++ b/docs/getconsolescreenbufferinfo.md @@ -23,8 +23,6 @@ api_type: # GetConsoleScreenBufferInfo function -[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] - Retrieves information about the specified console screen buffer. ## Syntax @@ -56,6 +54,9 @@ The rectangle returned in the **srWindow** member of the [**CONSOLE\_SCREEN\_BUF All coordinates returned in the [**CONSOLE\_SCREEN\_BUFFER\_INFO**](console-screen-buffer-info-str.md) structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the console screen buffer. +> [!TIP] +> This API does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Its use may still be required for applications that are attempting to draw columns, grids, or fill the display to retrieve the window size. This window state is managed by the TTY/PTY/Pseudoconsole outside of the normal stream flow and is generally considered a user privilege not adjustable by the client application. Updates can be received on [**ReadConsoleInput**](readconsoleinput.md). + ## Examples For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md). diff --git a/docs/getconsolescreenbufferinfoex.md b/docs/getconsolescreenbufferinfoex.md index 05db9a8..cd39567 100644 --- a/docs/getconsolescreenbufferinfoex.md +++ b/docs/getconsolescreenbufferinfoex.md @@ -32,8 +32,6 @@ api_type: # GetConsoleScreenBufferInfoEx function -[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] - Retrieves extended information about the specified console screen buffer. ## Syntax @@ -65,6 +63,9 @@ The rectangle returned in the **srWindow** member of the [**CONSOLE\_SCREEN\_BUF All coordinates returned in the [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-screen-buffer-infoex.md) structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the console screen buffer. +> [!TIP] +> This API does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Its use may still be required for applications that are attempting to draw columns, grids, or fill the display to retrieve the window size. This window state is managed by the TTY/PTY/Pseudoconsole outside of the normal stream flow and is generally considered a user privilege not adjustable by the client application. Updates can be received on [**ReadConsoleInput**](readconsoleinput.md). + ## Requirements | | | diff --git a/docs/getconsoleselectioninfo.md b/docs/getconsoleselectioninfo.md index 2941be3..d303764 100644 --- a/docs/getconsoleselectioninfo.md +++ b/docs/getconsoleselectioninfo.md @@ -57,6 +57,8 @@ If the function fails, the return value is zero. To get extended error informati To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getconsoletitle.md b/docs/getconsoletitle.md index a6b98eb..c8930d5 100644 --- a/docs/getconsoletitle.md +++ b/docs/getconsoletitle.md @@ -76,6 +76,9 @@ To set the title for a console window, use the [**SetConsoleTitle**](setconsolet [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. + ## Examples For an example, see [**SetConsoleTitle**](setconsoletitle.md). diff --git a/docs/getconsolewindow.md b/docs/getconsolewindow.md index e68e4bc..32682e4 100644 --- a/docs/getconsolewindow.md +++ b/docs/getconsolewindow.md @@ -60,6 +60,9 @@ The return value is a handle to the window used by the console associated with t To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). + +[!INCLUDE [no-vt-equiv-local-context](./includes/no-vt-equiv-local-context.md)] + ## Requirements | | | diff --git a/docs/getcurrentconsolefont.md b/docs/getcurrentconsolefont.md index 9af4b9a..5766f68 100644 --- a/docs/getcurrentconsolefont.md +++ b/docs/getcurrentconsolefont.md @@ -65,6 +65,8 @@ If the function fails, the return value is zero. To get extended error informati To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getcurrentconsolefontex.md b/docs/getcurrentconsolefontex.md index eebc40e..0056bad 100644 --- a/docs/getcurrentconsolefontex.md +++ b/docs/getcurrentconsolefontex.md @@ -60,6 +60,8 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getlargestconsolewindowsize.md b/docs/getlargestconsolewindowsize.md index a020d4b..3abf1a5 100644 --- a/docs/getlargestconsolewindowsize.md +++ b/docs/getlargestconsolewindowsize.md @@ -60,6 +60,8 @@ To get extended error information, call [**GetLastError**](https://msdn.microsof The function does not take into consideration the size of the console screen buffer, which means that the window size returned may be larger than the size of the console screen buffer. The [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function can be used to determine the maximum size of the console window, given the current screen buffer size, the current font, and the display size. +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/getnumberofconsoleinputevents.md b/docs/getnumberofconsoleinputevents.md index b192e86..d053a2c 100644 --- a/docs/getnumberofconsoleinputevents.md +++ b/docs/getnumberofconsoleinputevents.md @@ -34,8 +34,6 @@ api_type: # GetNumberOfConsoleInputEvents function -[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] - Retrieves the number of unread input records in the console's input buffer. ## Syntax diff --git a/docs/getnumberofconsolemousebuttons.md b/docs/getnumberofconsolemousebuttons.md index 384d8c8..f584458 100644 --- a/docs/getnumberofconsolemousebuttons.md +++ b/docs/getnumberofconsolemousebuttons.md @@ -57,6 +57,9 @@ If the function fails, the return value is zero. To get extended error informati When a console receives mouse input, an [**INPUT\_RECORD**](input-record-str.md) structure containing a [**MOUSE\_EVENT\_RECORD**](mouse-event-record-str.md) structure is placed in the console's input buffer. The **dwButtonState** member of **MOUSE\_EVENT\_RECORD** has a bit indicating the state of each mouse button. The bit is 1 if the button is down and 0 if the button is up. To determine the number of bits that are significant, use **GetNumberOfConsoleMouseButtons**. +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. + ## Requirements | | | diff --git a/docs/high-level-console-modes.md b/docs/high-level-console-modes.md index 0de2e07..af409d6 100644 --- a/docs/high-level-console-modes.md +++ b/docs/high-level-console-modes.md @@ -32,10 +32,4 @@ All three input modes, along with processed output mode, are designed to work to An application can use the [**GetConsoleMode**](getconsolemode.md) function to determine the current mode of a console's input buffer or screen buffer. You can enable or disable any of these modes by using the following values in the [**SetConsoleMode**](setconsolemode.md) function. Note that setting the output mode of one screen buffer does not affect the output mode of other screen buffers. -| Mode | Description | -|-|-| -| **ENABLE_PROCESSED_INPUT** | Used with a console input handle to cause the system to process any system editing or control key input rather than returning it as input in the read operation's buffer. If line input is also enabled, backspaces and carriage returns are handled correctly. A backspace causes the cursor to move back one space without affecting the character at the cursor position. A carriage return is converted to carriage return – line feed character combination. If echo input mode is enabled and the output should reflect system editing, processed output must be enabled for the active screen buffer. If processed input is enabled, the CTRL+C key combination is passed on to the appropriate handler regardless of whether line input is enabled. For more information about control handlers, see [Console Control Handlers](console-control-handlers.md). | -| **ENABLE_LINE_INPUT** | Used with a console input handle to cause the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** and **[ReadConsole](readconsole.md)** functions to return when the ENTER key is pressed. If line input mode is disabled, the functions return when one or more characters are available in the input buffer. | -| **ENABLE_ECHO_INPUT** | Used with a console input handle to cause keyboard input read by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** and **[ReadConsole](readconsole.md)** function to be echoed to the active screen buffer. Characters are echoed only if the process that calls **ReadFile** or **ReadConsole** has an open handle to the active screen buffer. Echo mode cannot be enabled unless line input is also enabled. The output mode of the active screen buffer affects the way echoed input is displayed. | -| **ENABLE_PROCESSED_OUTPUT** | Used with a console screen buffer handle to cause the system to perform the appropriate action for ANSI control characters that are written to a screen buffer. The backspace, tab, bell, carriage return, and line feed characters are processed. A tab character moves the cursor to the next tab stop, which occurs every eight characters. A bell character sounds a short tone. | -| **ENABLE_WRAP_AT_EOL_OUTPUT** | Used with a console screen buffer handle to cause the current output position (cursor position) to move to the first column in the next row (line) when the end of the current row is reached. If the bottom of the window region is reached, the window origin is moved down one row. This movement has the effect of scrolling the contents of the window up one row. If the bottom of the console screen buffer is reached, the contents of the console screen buffer are scrolled up one row, and the top row of the console screen buffer is discarded.

If this mode is disabled, the last character in the row is overwritten with any subsequent characters. | +[!INCLUDE [console-mode-flags](./includes/console-mode-flags.md)] diff --git a/docs/includes/no-vt-equiv-alt-buf.md b/docs/includes/no-vt-equiv-alt-buf.md new file mode 100644 index 0000000..230dc2e --- /dev/null +++ b/docs/includes/no-vt-equiv-alt-buf.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences.md#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. \ No newline at end of file diff --git a/docs/includes/no-vt-equiv-banner.md b/docs/includes/no-vt-equiv-banner.md index e397bb9..f133004 100644 --- a/docs/includes/no-vt-equiv-banner.md +++ b/docs/includes/no-vt-equiv-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-local-context.md b/docs/includes/no-vt-equiv-local-context.md new file mode 100644 index 0000000..3a748ef --- /dev/null +++ b/docs/includes/no-vt-equiv-local-context.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-shell-banner.md b/docs/includes/no-vt-equiv-shell-banner.md index 685dc73..8056fd2 100644 --- a/docs/includes/no-vt-equiv-shell-banner.md +++ b/docs/includes/no-vt-equiv-shell-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. \ No newline at end of file +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-user-priv.md b/docs/includes/no-vt-equiv-user-priv.md new file mode 100644 index 0000000..10eff17 --- /dev/null +++ b/docs/includes/no-vt-equiv-user-priv.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the user is granted full control over this presentation option. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-wrong-way.md b/docs/includes/no-vt-equiv-wrong-way.md new file mode 100644 index 0000000..3a748ef --- /dev/null +++ b/docs/includes/no-vt-equiv-wrong-way.md @@ -0,0 +1,2 @@ +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/legacymode.md b/docs/legacymode.md index 5711381..4a957dc 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -26,7 +26,7 @@ The setting can be reverted by returning to the same property sheet menu and unc ## Differences between modes -The Console Host team strives to minimize differences between the Legacy and current modes of the console to ensure that as many customers as possible can run the most up-to-date version. If you experience an issue that requires you to use the legacy console that is not documented here, please contact the team on the [Microsoft/Terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for assistance. +The Console Host team strives to minimize differences between the Legacy and current modes of the console to ensure that as many customers as possible can run the most up-to-date version. If you experience an issue that requires you to use the legacy console that is not documented here, please contact the team on the [microsoft/terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for assistance. ### 16-bit applications on 32-bit Windows @@ -40,4 +40,4 @@ The legacy Console Host embedded the suggestion portion of the IME inside the ho The major known difference between legacy and current is the implementation of UTF-8. The legacy host has extremely rudimentary and often incorrect support of UTF-8 with [code page 65001](https://docs.microsoft.com/windows/win32/intl/code-pages). The current console host contains incremental improvements release-over-release of Windows 10 to improve this support. Applications that are attempting to rely on predicting "known incorrect" interpretations of UTF-8 from the legacy console will find themselves receiving different answers as support is improved. -Other differences experienced with APIs should be reported to [Microsoft/Terminal](https://github.com/microsoft/terminal/) GitHub repository or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. +Other differences experienced with APIs should be reported to [microsoft/terminal GitHub repository](https://github.com/microsoft/terminal/) or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. diff --git a/docs/peekconsoleinput.md b/docs/peekconsoleinput.md index 6e2cfcc..e161684 100644 --- a/docs/peekconsoleinput.md +++ b/docs/peekconsoleinput.md @@ -43,8 +43,6 @@ api_type: # PeekConsoleInput function -[!INCLUDE [not-recommended-banner](./includes/not-recommended-banner.md)] - Reads data from the specified console input buffer without removing it from the buffer. ## Syntax diff --git a/docs/readconsoleoutputattribute.md b/docs/readconsoleoutputattribute.md index 0d40d8c..f6a1372 100644 --- a/docs/readconsoleoutputattribute.md +++ b/docs/readconsoleoutputattribute.md @@ -78,6 +78,8 @@ If the function fails, the return value is zero. To get extended error informati If the number of attributes to be read from extends beyond the end of the specified screen buffer row, attributes are read from the next row. If the number of attributes to be read from extends beyond the end of the console screen buffer, attributes up to the end of the console screen buffer are read. +[!INCLUDE [no-vt-equiv-banner](./includes/no-vt-equiv-banner.md)] + ## Requirements | | | diff --git a/docs/readconsoleoutputcharacter.md b/docs/readconsoleoutputcharacter.md index ff03e34..c7ab374 100644 --- a/docs/readconsoleoutputcharacter.md +++ b/docs/readconsoleoutputcharacter.md @@ -86,6 +86,8 @@ If the number of characters to be read from extends beyond the end of the specif [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +[!INCLUDE [no-vt-equiv-banner](./includes/no-vt-equiv-banner.md)] + ## Requirements | | | diff --git a/docs/scrollconsolescreenbuffer.md b/docs/scrollconsolescreenbuffer.md index 225fb18..54297a1 100644 --- a/docs/scrollconsolescreenbuffer.md +++ b/docs/scrollconsolescreenbuffer.md @@ -86,6 +86,9 @@ If the scroll or target regions extend beyond the dimensions of the console scre [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. Use can be approximated with **[scroll margins](console-virtual-terminal-sequences.md#scrolling-margins)** to fix an area of the screen, **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** to set the active position outside the region, and newlines to force text to move. The remaining space can be filled by moving the cursor, **[setting graphical attributes](console-virtual-terminal-sequences.md#text-formatting)**, and writing normal text. + ## Examples For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). diff --git a/docs/setconsoleactivescreenbuffer.md b/docs/setconsoleactivescreenbuffer.md index 4dfe084..7d0698b 100644 --- a/docs/setconsoleactivescreenbuffer.md +++ b/docs/setconsoleactivescreenbuffer.md @@ -60,6 +60,8 @@ If the function fails, the return value is zero. To get extended error informati A console can have multiple screen buffers. **SetConsoleActiveScreenBuffer** determines which one is displayed. You can write to an inactive screen buffer and then use **SetConsoleActiveScreenBuffer** to display the buffer's contents. +[!INCLUDE [no-vt-equiv-alt-buf](./includes/no-vt-equiv-alt-buf.md)] + ## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). diff --git a/docs/setconsolecursorinfo.md b/docs/setconsolecursorinfo.md index fcbe0bf..a3a1980 100644 --- a/docs/setconsolecursorinfo.md +++ b/docs/setconsolecursorinfo.md @@ -64,6 +64,9 @@ If the function fails, the return value is zero. To get extended error informati When a screen buffer's cursor is visible, its appearance can vary, ranging from completely filling a character cell to showing up as a horizontal line at the bottom of the cell. The **dwSize** member of the [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) structure specifies the percentage of a character cell that is filled by the cursor. If this member is less than 1 or greater than 100, **SetConsoleCursorInfo** fails. +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[cursor visibility](console-virtual-terminal-sequences.md#cursor-visibility)** section with the `^[[?25h` and `^[[?25l` sequences. + ## Requirements | | | diff --git a/docs/setconsolecursorposition.md b/docs/setconsolecursorposition.md index 6a769cd..bf8d172 100644 --- a/docs/setconsolecursorposition.md +++ b/docs/setconsolecursorposition.md @@ -66,6 +66,9 @@ The cursor position determines where characters written by the [**WriteFile**](h If the new cursor position is not within the boundaries of the console screen buffer's window, the window origin changes to make the cursor visible. +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[simple cursor positioning](console-virtual-terminal-sequences.md#simple-cursor-positioning)** and **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** sections. Use of the newline, carriage return, backspace, and tab control sequences can also assist with cursor positioning. + ## Examples For an example, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). From fce0187181ce47fbaf4394629d90ddf36401879d Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 15:55:27 -0700 Subject: [PATCH 32/53] fix all tips I didn't finish earlier today. --- docs/includes/no-vt-equiv-wrong-way.md | 2 -- docs/setconsoledisplaymode.md | 4 ++++ docs/setconsolehistoryinfo.md | 2 ++ docs/setconsolescreenbufferinfoex.md | 5 +++++ docs/setconsolescreenbuffersize.md | 4 ++++ docs/setconsoletextattribute.md | 3 +++ docs/setconsoletitle.md | 3 +++ docs/setconsolewindowinfo.md | 2 ++ docs/setcurrentconsolefontex.md | 2 ++ docs/writeconsoleinput.md | 3 +++ docs/writeconsoleoutput.md | 3 +++ docs/writeconsoleoutputattribute.md | 3 +++ docs/writeconsoleoutputcharacter.md | 3 +++ 13 files changed, 37 insertions(+), 2 deletions(-) delete mode 100644 docs/includes/no-vt-equiv-wrong-way.md diff --git a/docs/includes/no-vt-equiv-wrong-way.md b/docs/includes/no-vt-equiv-wrong-way.md deleted file mode 100644 index 3a748ef..0000000 --- a/docs/includes/no-vt-equiv-wrong-way.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/setconsoledisplaymode.md b/docs/setconsoledisplaymode.md index 0ab1e6f..6f063e3 100644 --- a/docs/setconsoledisplaymode.md +++ b/docs/setconsoledisplaymode.md @@ -65,6 +65,10 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/setconsolehistoryinfo.md b/docs/setconsolehistoryinfo.md index c83d626..60a79c6 100644 --- a/docs/setconsolehistoryinfo.md +++ b/docs/setconsolehistoryinfo.md @@ -56,6 +56,8 @@ If the function fails, the return value is zero. To get extended error informati If the calling process is not a console process, the function fails and sets the last error code to **ERROR\_ACCESS\_DENIED**. +[!INCLUDE [no-vt-equiv-shell-banner](./includes/no-vt-equiv-shell-banner.md)] + ## Requirements | | | diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index ecd7a77..ca605eb 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -59,6 +59,11 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + +> [!TIP] +> This API has a partial **[virtual terminal](console-virtual-terminal-sequences)** equivalent. **[Cursor positioning buffer](console-virtual-terminal-sequences#cursor-positioning)** and **[text attributes](console-virtual-terminal-sequences#text-formatting)** have specific sequence equivalents. The color table is not configurable, but **[extended colors](console-virtual-terminal-sequences#extended-colors)** are available beyond what is normally available through **[console functions](console-functions.md)**. Popup attributes have no equivalent as popup menus are the responsibility of the command-line client application in the **virtual terminal** world. Finally, the size of the window and the full screen status are considered privileges owned by the user in the **virtual terminal** world have no equivalent sequence. + ## Requirements | | | diff --git a/docs/setconsolescreenbuffersize.md b/docs/setconsolescreenbuffersize.md index 0dd8ceb..09bc3c3 100644 --- a/docs/setconsolescreenbuffersize.md +++ b/docs/setconsolescreenbuffersize.md @@ -60,6 +60,10 @@ 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**](https://msdn.microsoft.com/library/windows/desktop/ms679360). +## Remarks + +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/setconsoletextattribute.md b/docs/setconsoletextattribute.md index 6a1b6b1..cd87276 100644 --- a/docs/setconsoletextattribute.md +++ b/docs/setconsoletextattribute.md @@ -64,6 +64,9 @@ If the function fails, the return value is zero. To get extended error informati To determine the current color attributes of a screen buffer, call the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function. +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. + ## Examples For an example, see [Using the High-Level Input and Output Functions](using-the-high-level-input-and-output-functions.md). diff --git a/docs/setconsoletitle.md b/docs/setconsoletitle.md index 7fcabf6..f1ac194 100644 --- a/docs/setconsoletitle.md +++ b/docs/setconsoletitle.md @@ -78,6 +78,9 @@ When the process terminates, the system restores the original console title. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[window title](console-virtual-terminal-sequences#window-title)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. + ## Examples The following example shows how to retrieve and modify the console title. diff --git a/docs/setconsolewindowinfo.md b/docs/setconsolewindowinfo.md index 5148323..311dab1 100644 --- a/docs/setconsolewindowinfo.md +++ b/docs/setconsolewindowinfo.md @@ -74,6 +74,8 @@ To determine the current size and position of a screen buffer's window, use the **SetConsoleWindowInfo** can be used to scroll the contents of the console screen buffer by shifting the position of the window rectangle without changing its size. +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Examples For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md). diff --git a/docs/setcurrentconsolefontex.md b/docs/setcurrentconsolefontex.md index 128c42a..4f90d79 100644 --- a/docs/setcurrentconsolefontex.md +++ b/docs/setcurrentconsolefontex.md @@ -64,6 +64,8 @@ If the function fails, the return value is zero. To get extended error informati To compile an application that uses this function, define **\_WIN32\_WINNT** as 0x0500 or later. For more information, see [Using the Windows Headers](https://msdn.microsoft.com/library/windows/desktop/aa383745). +[!INCLUDE [no-vt-equiv-user-priv](./includes/no-vt-equiv-user-priv.md)] + ## Requirements | | | diff --git a/docs/writeconsoleinput.md b/docs/writeconsoleinput.md index 2a9f2ba..3a29d0a 100644 --- a/docs/writeconsoleinput.md +++ b/docs/writeconsoleinput.md @@ -82,6 +82,9 @@ If the function fails, the return value is zero. To get extended error informati [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This operation is considered the **[wrong-way verb](console-buffer-security-and-access-rights.md#wrong-way-verbs)** for this buffer. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. + ## Requirements | | | diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index 59040a4..01efcd3 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -94,6 +94,9 @@ If the rectangle specified by *lpWriteRegion* lies completely outside the bounda [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out the text. _Virtual terminal sequences_ are recommended for all new and ongoing development. + ## Examples For an example, see [Reading and Writing Blocks of Characters and Attributes](reading-and-writing-blocks-of-characters-and-attributes.md). diff --git a/docs/writeconsoleoutputattribute.md b/docs/writeconsoleoutputattribute.md index 26f442c..888f444 100644 --- a/docs/writeconsoleoutputattribute.md +++ b/docs/writeconsoleoutputattribute.md @@ -78,6 +78,9 @@ If the number of attributes to be written to extends beyond the end of the speci The character values at the positions written to are not changed. +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to apply color to an area without also emitting text. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. + ## Requirements | | | diff --git a/docs/writeconsoleoutputcharacter.md b/docs/writeconsoleoutputcharacter.md index 9a41ce9..df4ec0e 100644 --- a/docs/writeconsoleoutputcharacter.md +++ b/docs/writeconsoleoutputcharacter.md @@ -87,6 +87,9 @@ The attribute values at the positions written to are not changed. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] +> [!TIP] +> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to emit text to an area without also applying the active color formatting. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. + ## Requirements | | | From f0ab1748f4319c14ef19ddcb155500f5ed222c45 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Wed, 7 Oct 2020 15:56:27 -0700 Subject: [PATCH 33/53] typo --- docs/classic-vs-vt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 3bd6a8b..057a900 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -15,7 +15,7 @@ This article will discuss the difference between the classic Windows Console API ## History -The Windows Console has provided a broad API surface for client command-line applications to manipulate both the output display buffer and the user input buffer. However, other non-Windows platforms have never afforded this specific API-driven approach to their command-line environments, choosing instead to use virtual terminal sequences embedded within the standard input and standard output streams. For a time, Microsoft supported this behavior too in early editions editions of DOS and Windows through a driver called ANSI.SYS. +The Windows Console has provided a broad API surface for client command-line applications to manipulate both the output display buffer and the user input buffer. However, other non-Windows platforms have never afforded this specific API-driven approach to their command-line environments, choosing instead to use virtual terminal sequences embedded within the standard input and standard output streams. For a time, Microsoft supported this behavior too in early editions of DOS and Windows through a driver called ANSI.SYS. By contrast, all other platforms derive their command-line environment operations from various dialects of virtual terminal sequences. These sequences are rooted in an [ECMA Standard](https://www.ecma-international.org/publications/standards/Ecma-048.htm) and series of extensions by many vendors tracing back to Digital Equipment Corporation and Tektronix terminals through more modern and common software terminals like [xterm](https://invisible-island.net/xterm/). Many extensions exist within the virtual terminal sequence domain and some sequences are more widely supported than others, but it is safe to say that the world has standardized on this as the command language for command-line experiences with a well-known subset being supported by virtually every terminal and command-line client application. From e5c6e3a587881dc4fa54f91d86294af9549e4764 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:08:03 -0700 Subject: [PATCH 34/53] two dustin nits --- docs/legacymode.md | 2 +- docs/setconsolescreenbufferinfoex.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/legacymode.md b/docs/legacymode.md index 4a957dc..2b37d70 100644 --- a/docs/legacymode.md +++ b/docs/legacymode.md @@ -40,4 +40,4 @@ The legacy Console Host embedded the suggestion portion of the IME inside the ho The major known difference between legacy and current is the implementation of UTF-8. The legacy host has extremely rudimentary and often incorrect support of UTF-8 with [code page 65001](https://docs.microsoft.com/windows/win32/intl/code-pages). The current console host contains incremental improvements release-over-release of Windows 10 to improve this support. Applications that are attempting to rely on predicting "known incorrect" interpretations of UTF-8 from the legacy console will find themselves receiving different answers as support is improved. -Other differences experienced with APIs should be reported to [microsoft/terminal GitHub repository](https://github.com/microsoft/terminal/) or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. +Other differences experienced with APIs should be reported to the [microsoft/terminal GitHub repository](https://github.com/microsoft/terminal/) or via the [Feedback Hub](https://docs.microsoft.com/windows-insider/feedback-hub/feedback-hub-app) for triage and possible remediation. diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index ca605eb..3727c3b 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -62,7 +62,7 @@ If the function fails, the return value is zero. To get extended error informati ## Remarks > [!TIP] -> This API has a partial **[virtual terminal](console-virtual-terminal-sequences)** equivalent. **[Cursor positioning buffer](console-virtual-terminal-sequences#cursor-positioning)** and **[text attributes](console-virtual-terminal-sequences#text-formatting)** have specific sequence equivalents. The color table is not configurable, but **[extended colors](console-virtual-terminal-sequences#extended-colors)** are available beyond what is normally available through **[console functions](console-functions.md)**. Popup attributes have no equivalent as popup menus are the responsibility of the command-line client application in the **virtual terminal** world. Finally, the size of the window and the full screen status are considered privileges owned by the user in the **virtual terminal** world have no equivalent sequence. +> This API has a partial **[virtual terminal](console-virtual-terminal-sequences)** equivalent. **[Cursor positioning buffer](console-virtual-terminal-sequences#cursor-positioning)** and **[text attributes](console-virtual-terminal-sequences#text-formatting)** have specific sequence equivalents. The color table is not configurable, but **[extended colors](console-virtual-terminal-sequences#extended-colors)** are available beyond what is normally available through **[console functions](console-functions.md)**. Popup attributes have no equivalent as popup menus are the responsibility of the command-line client application in the **virtual terminal** world. Finally, the size of the window and the full screen status are considered privileges owned by the user in the **virtual terminal** world and have no equivalent sequence. ## Requirements From 7cdbdcca025337a101b6082606d126f0c32aa4e9 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:37:55 -0700 Subject: [PATCH 35/53] trickery --- docs/addconsolealias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/addconsolealias.md b/docs/addconsolealias.md index d8a551c..7ad746f 100644 --- a/docs/addconsolealias.md +++ b/docs/addconsolealias.md @@ -79,7 +79,7 @@ For an example, see [Console Aliases](console-aliases.md). ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | From 80deb7c572c4d9f32ed7d4f7d020c384696aa583 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:38:06 -0700 Subject: [PATCH 36/53] fix broken links --- docs/classic-vs-vt.md | 2 +- docs/setconsolescreenbufferinfoex.md | 2 +- docs/setconsoletextattribute.md | 2 +- docs/setconsoletitle.md | 2 +- docs/writeconsoleoutput.md | 2 +- docs/writeconsoleoutputattribute.md | 2 +- docs/writeconsoleoutputcharacter.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 057a900..fe460d5 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -76,7 +76,7 @@ A limited subset of Windows Console APIs is still necessary to establish the ini - C++ Standard Library (STL): [iostream](https://docs.microsoft.com/cpp/standard-library/iostream) like **cout** and **cin**. - .NET Runtime: [System.Console](https://docs.microsoft.com/dotnet/api/system.console) like **Console.WriteLine**. - Applications that must be aware of window size changes will still need to use [**ReadConsoleInput**](readconsoleinput.md) to receive them interleaved with key events as **ReadConsole** alone will discard them. -- Finding the window size must still be performed with [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) for applications attempting to draw columns, grids, or fill the display. Window and buffer size will match in a [pseudoconsole](pseudoconsole.md) session. +- Finding the window size must still be performed with [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) for applications attempting to draw columns, grids, or fill the display. Window and buffer size will match in a [pseudoconsole](pseudoconsoles.md) session. There are no plans to remove the Windows console APIs from the platform. On the contrary, the Windows console host has provided the [pseudoconsole](pseudoconsoles.md) technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. This translation is not perfect and requires the console host window to maintain a simulated environment of what Windows would have displayed to the user and project a replica of that to the pseudoconsole host. All console API calls are operated within the simulated environment to serve the needs of the legacy command-line client application and only the effects are propagated onto the final host. diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index 3727c3b..9befffb 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -62,7 +62,7 @@ If the function fails, the return value is zero. To get extended error informati ## Remarks > [!TIP] -> This API has a partial **[virtual terminal](console-virtual-terminal-sequences)** equivalent. **[Cursor positioning buffer](console-virtual-terminal-sequences#cursor-positioning)** and **[text attributes](console-virtual-terminal-sequences#text-formatting)** have specific sequence equivalents. The color table is not configurable, but **[extended colors](console-virtual-terminal-sequences#extended-colors)** are available beyond what is normally available through **[console functions](console-functions.md)**. Popup attributes have no equivalent as popup menus are the responsibility of the command-line client application in the **virtual terminal** world. Finally, the size of the window and the full screen status are considered privileges owned by the user in the **virtual terminal** world and have no equivalent sequence. +> This API has a partial **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. **[Cursor positioning buffer](console-virtual-terminal-sequences.md#cursor-positioning)** and **[text attributes](console-virtual-terminal-sequences.md#text-formatting)** have specific sequence equivalents. The color table is not configurable, but **[extended colors](console-virtual-terminal-sequences.md#extended-colors)** are available beyond what is normally available through **[console functions](console-functions.md)**. Popup attributes have no equivalent as popup menus are the responsibility of the command-line client application in the **virtual terminal** world. Finally, the size of the window and the full screen status are considered privileges owned by the user in the **virtual terminal** world and have no equivalent sequence. ## Requirements diff --git a/docs/setconsoletextattribute.md b/docs/setconsoletextattribute.md index cd87276..cb10858 100644 --- a/docs/setconsoletextattribute.md +++ b/docs/setconsoletextattribute.md @@ -65,7 +65,7 @@ If the function fails, the return value is zero. To get extended error informati To determine the current color attributes of a screen buffer, call the [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) function. > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences.md#text-formatting)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. ## Examples diff --git a/docs/setconsoletitle.md b/docs/setconsoletitle.md index f1ac194..740a52e 100644 --- a/docs/setconsoletitle.md +++ b/docs/setconsoletitle.md @@ -79,7 +79,7 @@ When the process terminates, the system restores the original console title. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[window title](console-virtual-terminal-sequences#window-title)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[window title](console-virtual-terminal-sequences.md#window-title)** sequences. _Virtual terminal sequences_ are recommended for all new and ongoing development. ## Examples diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index 01efcd3..b864594 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -95,7 +95,7 @@ If the rectangle specified by *lpWriteRegion* lies completely outside the bounda [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out the text. _Virtual terminal sequences_ are recommended for all new and ongoing development. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting.md)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning.md)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out the text. _Virtual terminal sequences_ are recommended for all new and ongoing development. ## Examples diff --git a/docs/writeconsoleoutputattribute.md b/docs/writeconsoleoutputattribute.md index 888f444..dcae02d 100644 --- a/docs/writeconsoleoutputattribute.md +++ b/docs/writeconsoleoutputattribute.md @@ -79,7 +79,7 @@ If the number of attributes to be written to extends beyond the end of the speci The character values at the positions written to are not changed. > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to apply color to an area without also emitting text. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences.md#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to apply color to an area without also emitting text. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. ## Requirements diff --git a/docs/writeconsoleoutputcharacter.md b/docs/writeconsoleoutputcharacter.md index df4ec0e..54cf7cd 100644 --- a/docs/writeconsoleoutputcharacter.md +++ b/docs/writeconsoleoutputcharacter.md @@ -88,7 +88,7 @@ The attribute values at the positions written to are not changed. [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to emit text to an area without also applying the active color formatting. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences.md#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out text to fill. There is no equivalent to emit text to an area without also applying the active color formatting. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. ## Requirements From 5c92ba2918980a800e176687711ca2cc83719b5a Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:41:03 -0700 Subject: [PATCH 37/53] bulk trickery --- docs/allocconsole.md | 2 +- docs/attachconsole.md | 2 +- docs/char-info-str.md | 2 +- docs/closepseudoconsole.md | 2 +- docs/console-cursor-info-str.md | 2 +- docs/console-font-info-str.md | 2 +- docs/console-font-infoex.md | 2 +- docs/console-history-info.md | 2 +- docs/console-readconsole-control.md | 2 +- docs/console-screen-buffer-info-str.md | 2 +- docs/console-screen-buffer-infoex.md | 2 +- docs/console-selection-info-str.md | 2 +- docs/console-winevents.md | 2 +- docs/coord-str.md | 2 +- docs/createconsolescreenbuffer.md | 2 +- docs/createpseudoconsole.md | 2 +- docs/fillconsoleoutputattribute.md | 2 +- docs/fillconsoleoutputcharacter.md | 2 +- docs/flushconsoleinputbuffer.md | 2 +- docs/focus-event-record-str.md | 2 +- docs/freeconsole.md | 2 +- docs/generateconsolectrlevent.md | 2 +- docs/getconsolealias.md | 2 +- docs/getconsolealiases.md | 2 +- docs/getconsolealiaseslength.md | 2 +- docs/getconsolealiasexes.md | 2 +- docs/getconsolealiasexeslength.md | 2 +- docs/getconsolecp.md | 2 +- docs/getconsolecursorinfo.md | 2 +- docs/getconsoledisplaymode.md | 2 +- docs/getconsolefontsize.md | 2 +- docs/getconsolehistoryinfo.md | 2 +- docs/getconsolemode.md | 2 +- docs/getconsoleoriginaltitle.md | 2 +- docs/getconsoleoutputcp.md | 2 +- docs/getconsoleprocesslist.md | 2 +- docs/getconsolescreenbufferinfo.md | 2 +- docs/getconsolescreenbufferinfoex.md | 2 +- docs/getconsoleselectioninfo.md | 2 +- docs/getconsoletitle.md | 2 +- docs/getconsolewindow.md | 2 +- docs/getcurrentconsolefont.md | 2 +- docs/getcurrentconsolefontex.md | 2 +- docs/getlargestconsolewindowsize.md | 2 +- docs/getnumberofconsoleinputevents.md | 2 +- docs/getnumberofconsolemousebuttons.md | 2 +- docs/getstdhandle.md | 2 +- docs/handlerroutine.md | 2 +- docs/input-record-str.md | 2 +- docs/key-event-record-str.md | 2 +- docs/menu-event-record-str.md | 2 +- docs/mouse-event-record-str.md | 2 +- docs/peekconsoleinput.md | 2 +- docs/readconsole.md | 2 +- docs/readconsoleinput.md | 2 +- docs/readconsoleoutput.md | 2 +- docs/readconsoleoutputattribute.md | 2 +- docs/readconsoleoutputcharacter.md | 2 +- docs/resizepseudoconsole.md | 2 +- docs/scrollconsolescreenbuffer.md | 2 +- docs/setconsoleactivescreenbuffer.md | 2 +- docs/setconsolecp.md | 2 +- docs/setconsolectrlhandler.md | 2 +- docs/setconsolecursorinfo.md | 2 +- docs/setconsolecursorposition.md | 2 +- docs/setconsoledisplaymode.md | 2 +- docs/setconsolehistoryinfo.md | 2 +- docs/setconsolemode.md | 2 +- docs/setconsoleoutputcp.md | 2 +- docs/setconsolescreenbufferinfoex.md | 2 +- docs/setconsolescreenbuffersize.md | 2 +- docs/setconsoletextattribute.md | 2 +- docs/setconsoletitle.md | 2 +- docs/setconsolewindowinfo.md | 2 +- docs/setcurrentconsolefontex.md | 2 +- docs/setstdhandle.md | 2 +- docs/small-rect-str.md | 2 +- docs/window-buffer-size-record-str.md | 2 +- docs/writeconsole.md | 2 +- docs/writeconsoleinput.md | 2 +- docs/writeconsoleoutput.md | 2 +- docs/writeconsoleoutputattribute.md | 2 +- docs/writeconsoleoutputcharacter.md | 2 +- 83 files changed, 83 insertions(+), 83 deletions(-) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index ba41d6a..f4c3066 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -63,7 +63,7 @@ This function is primarily used by a graphical user interface (GUI) application ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/attachconsole.md b/docs/attachconsole.md index 198f884..867936a 100644 --- a/docs/attachconsole.md +++ b/docs/attachconsole.md @@ -68,7 +68,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/char-info-str.md b/docs/char-info-str.md index 5045673..b0dd84a 100644 --- a/docs/char-info-str.md +++ b/docs/char-info-str.md @@ -86,7 +86,7 @@ For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-bu ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/closepseudoconsole.md b/docs/closepseudoconsole.md index 5aa6996..5867e31 100644 --- a/docs/closepseudoconsole.md +++ b/docs/closepseudoconsole.md @@ -47,7 +47,7 @@ A final painted frame may arrive on `hOutput` from the pseudoconsole when this A ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | | Minimum supported server | Windows Server 2019 \[desktop apps only\] | diff --git a/docs/console-cursor-info-str.md b/docs/console-cursor-info-str.md index fba2bcb..16abbcf 100644 --- a/docs/console-cursor-info-str.md +++ b/docs/console-cursor-info-str.md @@ -59,7 +59,7 @@ The visibility of the cursor. If the cursor is visible, this member is **TRUE**. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/console-font-info-str.md b/docs/console-font-info-str.md index 8b7b378..664489d 100644 --- a/docs/console-font-info-str.md +++ b/docs/console-font-info-str.md @@ -59,7 +59,7 @@ To obtain the size of the font, pass the font index to the [**GetConsoleFontSize ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/console-font-infoex.md b/docs/console-font-infoex.md index f4c9e9f..91f0019 100644 --- a/docs/console-font-infoex.md +++ b/docs/console-font-infoex.md @@ -75,7 +75,7 @@ To obtain the size of the font, pass the font index to the [**GetConsoleFontSize ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/console-history-info.md b/docs/console-history-info.md index 33ba565..bac49fc 100644 --- a/docs/console-history-info.md +++ b/docs/console-history-info.md @@ -67,7 +67,7 @@ This parameter can be zero or the following value. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/console-readconsole-control.md b/docs/console-readconsole-control.md index a1b68b0..40ed04b 100644 --- a/docs/console-readconsole-control.md +++ b/docs/console-readconsole-control.md @@ -73,7 +73,7 @@ The state of the control keys. This member can be one or more of the following v ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/console-screen-buffer-info-str.md b/docs/console-screen-buffer-info-str.md index 9c31fb1..370488b 100644 --- a/docs/console-screen-buffer-info-str.md +++ b/docs/console-screen-buffer-info-str.md @@ -70,7 +70,7 @@ For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-bu ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/console-screen-buffer-infoex.md b/docs/console-screen-buffer-infoex.md index d6789fd..8535cc7 100644 --- a/docs/console-screen-buffer-infoex.md +++ b/docs/console-screen-buffer-infoex.md @@ -81,7 +81,7 @@ An array of [**COLORREF**](https://msdn.microsoft.com/library/windows/desktop/dd ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/console-selection-info-str.md b/docs/console-selection-info-str.md index 8c308fc..4370f93 100644 --- a/docs/console-selection-info-str.md +++ b/docs/console-selection-info-str.md @@ -68,7 +68,7 @@ A [**SMALL\_RECT**](small-rect-str.md) structure that specifies the selection re ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/console-winevents.md b/docs/console-winevents.md index cc9fe72..31caebf 100644 --- a/docs/console-winevents.md +++ b/docs/console-winevents.md @@ -66,7 +66,7 @@ The following event constants are used in the *event* parameter of the [*WinEven ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/coord-str.md b/docs/coord-str.md index 705a3b8..d01f2ed 100644 --- a/docs/coord-str.md +++ b/docs/coord-str.md @@ -58,7 +58,7 @@ For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-bu ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/createconsolescreenbuffer.md b/docs/createconsolescreenbuffer.md index 427032e..9e60014 100644 --- a/docs/createconsolescreenbuffer.md +++ b/docs/createconsolescreenbuffer.md @@ -103,7 +103,7 @@ For an example, see [Reading and Writing Blocks of Characters and Attributes](re ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/createpseudoconsole.md b/docs/createpseudoconsole.md index 1c373f4..fb9370f 100644 --- a/docs/createpseudoconsole.md +++ b/docs/createpseudoconsole.md @@ -85,7 +85,7 @@ For a full walkthrough on using this function to establish a pseudoconsole sessi ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | | Minimum supported server | Windows Server 2019 \[desktop apps only\] | diff --git a/docs/fillconsoleoutputattribute.md b/docs/fillconsoleoutputattribute.md index cbe07ba..ef79639 100644 --- a/docs/fillconsoleoutputattribute.md +++ b/docs/fillconsoleoutputattribute.md @@ -83,7 +83,7 @@ The character values at the positions written to are not changed. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/fillconsoleoutputcharacter.md b/docs/fillconsoleoutputcharacter.md index ed957a0..90eb21f 100644 --- a/docs/fillconsoleoutputcharacter.md +++ b/docs/fillconsoleoutputcharacter.md @@ -93,7 +93,7 @@ The attribute values at the positions written are not changed. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/flushconsoleinputbuffer.md b/docs/flushconsoleinputbuffer.md index 24f019c..b6672d3 100644 --- a/docs/flushconsoleinputbuffer.md +++ b/docs/flushconsoleinputbuffer.md @@ -62,7 +62,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/focus-event-record-str.md b/docs/focus-event-record-str.md index 5158d29..bade2b6 100644 --- a/docs/focus-event-record-str.md +++ b/docs/focus-event-record-str.md @@ -50,7 +50,7 @@ Reserved. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/freeconsole.md b/docs/freeconsole.md index 9ec71f5..9d66bf8 100644 --- a/docs/freeconsole.md +++ b/docs/freeconsole.md @@ -59,7 +59,7 @@ A process can use the **FreeConsole** function to detach itself from its console ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/generateconsolectrlevent.md b/docs/generateconsolectrlevent.md index 3e4de9a..51bd7b8 100644 --- a/docs/generateconsolectrlevent.md +++ b/docs/generateconsolectrlevent.md @@ -73,7 +73,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolealias.md b/docs/getconsolealias.md index 5c9ae5a..d3ccbbf 100644 --- a/docs/getconsolealias.md +++ b/docs/getconsolealias.md @@ -80,7 +80,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolealiases.md b/docs/getconsolealiases.md index c36229e..92714ca 100644 --- a/docs/getconsolealiases.md +++ b/docs/getconsolealiases.md @@ -80,7 +80,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolealiaseslength.md b/docs/getconsolealiaseslength.md index bde9cc6..9192db6 100644 --- a/docs/getconsolealiaseslength.md +++ b/docs/getconsolealiaseslength.md @@ -66,7 +66,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolealiasexes.md b/docs/getconsolealiasexes.md index ee71b33..726a44d 100644 --- a/docs/getconsolealiasexes.md +++ b/docs/getconsolealiasexes.md @@ -74,7 +74,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolealiasexeslength.md b/docs/getconsolealiasexeslength.md index 3197058..4ae8c34 100644 --- a/docs/getconsolealiasexeslength.md +++ b/docs/getconsolealiasexeslength.md @@ -63,7 +63,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolecp.md b/docs/getconsolecp.md index 16dfdfb..f5c1f8c 100644 --- a/docs/getconsolecp.md +++ b/docs/getconsolecp.md @@ -60,7 +60,7 @@ To set a console's input code page, use the [**SetConsoleCP**](setconsolecp.md) ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolecursorinfo.md b/docs/getconsolecursorinfo.md index 3786473..1a95f25 100644 --- a/docs/getconsolecursorinfo.md +++ b/docs/getconsolecursorinfo.md @@ -66,7 +66,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsoledisplaymode.md b/docs/getconsoledisplaymode.md index 7a3f3be..a68768a 100644 --- a/docs/getconsoledisplaymode.md +++ b/docs/getconsoledisplaymode.md @@ -69,7 +69,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/getconsolefontsize.md b/docs/getconsolefontsize.md index d5b37f5..e0c5d86 100644 --- a/docs/getconsolefontsize.md +++ b/docs/getconsolefontsize.md @@ -65,7 +65,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/getconsolehistoryinfo.md b/docs/getconsolehistoryinfo.md index 502ff50..a6409cd 100644 --- a/docs/getconsolehistoryinfo.md +++ b/docs/getconsolehistoryinfo.md @@ -60,7 +60,7 @@ If the calling process is not a console process, the function fails and sets the ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/getconsolemode.md b/docs/getconsolemode.md index cbf6b67..1550c11 100644 --- a/docs/getconsolemode.md +++ b/docs/getconsolemode.md @@ -73,7 +73,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsoleoriginaltitle.md b/docs/getconsoleoriginaltitle.md index 22ece6d..91ea1f5 100644 --- a/docs/getconsoleoriginaltitle.md +++ b/docs/getconsoleoriginaltitle.md @@ -77,7 +77,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/getconsoleoutputcp.md b/docs/getconsoleoutputcp.md index 76bcc5e..d980947 100644 --- a/docs/getconsoleoutputcp.md +++ b/docs/getconsoleoutputcp.md @@ -60,7 +60,7 @@ To set a console's output code page, use the [**SetConsoleOutputCP**](setconsole ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsoleprocesslist.md b/docs/getconsoleprocesslist.md index f871778..a874876 100644 --- a/docs/getconsoleprocesslist.md +++ b/docs/getconsoleprocesslist.md @@ -67,7 +67,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/getconsolescreenbufferinfo.md b/docs/getconsolescreenbufferinfo.md index 22f824b..4d98c41 100644 --- a/docs/getconsolescreenbufferinfo.md +++ b/docs/getconsolescreenbufferinfo.md @@ -63,7 +63,7 @@ For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buff ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolescreenbufferinfoex.md b/docs/getconsolescreenbufferinfoex.md index cd39567..7728e73 100644 --- a/docs/getconsolescreenbufferinfoex.md +++ b/docs/getconsolescreenbufferinfoex.md @@ -68,7 +68,7 @@ All coordinates returned in the [**CONSOLE\_SCREEN\_BUFFER\_INFOEX**](console-sc ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/getconsoleselectioninfo.md b/docs/getconsoleselectioninfo.md index d303764..edf7750 100644 --- a/docs/getconsoleselectioninfo.md +++ b/docs/getconsoleselectioninfo.md @@ -61,7 +61,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/getconsoletitle.md b/docs/getconsoletitle.md index c8930d5..fce2dbb 100644 --- a/docs/getconsoletitle.md +++ b/docs/getconsoletitle.md @@ -85,7 +85,7 @@ For an example, see [**SetConsoleTitle**](setconsoletitle.md). ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getconsolewindow.md b/docs/getconsolewindow.md index 32682e4..2c325d9 100644 --- a/docs/getconsolewindow.md +++ b/docs/getconsolewindow.md @@ -65,7 +65,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getcurrentconsolefont.md b/docs/getcurrentconsolefont.md index 5766f68..f8a3199 100644 --- a/docs/getcurrentconsolefont.md +++ b/docs/getcurrentconsolefont.md @@ -69,7 +69,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/getcurrentconsolefontex.md b/docs/getcurrentconsolefontex.md index 0056bad..c7cafc1 100644 --- a/docs/getcurrentconsolefontex.md +++ b/docs/getcurrentconsolefontex.md @@ -64,7 +64,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/getlargestconsolewindowsize.md b/docs/getlargestconsolewindowsize.md index 3abf1a5..ccbc22a 100644 --- a/docs/getlargestconsolewindowsize.md +++ b/docs/getlargestconsolewindowsize.md @@ -64,7 +64,7 @@ The function does not take into consideration the size of the console screen buf ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getnumberofconsoleinputevents.md b/docs/getnumberofconsoleinputevents.md index d053a2c..d9a9405 100644 --- a/docs/getnumberofconsoleinputevents.md +++ b/docs/getnumberofconsoleinputevents.md @@ -69,7 +69,7 @@ To read input records from a console input buffer without affecting the number o ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getnumberofconsolemousebuttons.md b/docs/getnumberofconsolemousebuttons.md index f584458..fa287b5 100644 --- a/docs/getnumberofconsolemousebuttons.md +++ b/docs/getnumberofconsolemousebuttons.md @@ -62,7 +62,7 @@ When a console receives mouse input, an [**INPUT\_RECORD**](input-record-str.md) ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/getstdhandle.md b/docs/getstdhandle.md index bccabe0..b545e09 100644 --- a/docs/getstdhandle.md +++ b/docs/getstdhandle.md @@ -87,7 +87,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/handlerroutine.md b/docs/handlerroutine.md index 1a99d38..04242c0 100644 --- a/docs/handlerroutine.md +++ b/docs/handlerroutine.md @@ -93,7 +93,7 @@ _[1]: "quick" events are never used, but there's still code to support them._ ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/input-record-str.md b/docs/input-record-str.md index 1978246..2165f65 100644 --- a/docs/input-record-str.md +++ b/docs/input-record-str.md @@ -74,7 +74,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/key-event-record-str.md b/docs/key-event-record-str.md index 4aaddcf..788e0d6 100644 --- a/docs/key-event-record-str.md +++ b/docs/key-event-record-str.md @@ -101,7 +101,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/menu-event-record-str.md b/docs/menu-event-record-str.md index 5c14f8c..e20821f 100644 --- a/docs/menu-event-record-str.md +++ b/docs/menu-event-record-str.md @@ -52,7 +52,7 @@ Reserved. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/mouse-event-record-str.md b/docs/mouse-event-record-str.md index 02c6f1d..252c983 100644 --- a/docs/mouse-event-record-str.md +++ b/docs/mouse-event-record-str.md @@ -103,7 +103,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/peekconsoleinput.md b/docs/peekconsoleinput.md index e161684..8dc2565 100644 --- a/docs/peekconsoleinput.md +++ b/docs/peekconsoleinput.md @@ -84,7 +84,7 @@ If the number of records requested exceeds the number of records available in th ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/readconsole.md b/docs/readconsole.md index ad649b8..6092ecd 100644 --- a/docs/readconsole.md +++ b/docs/readconsole.md @@ -97,7 +97,7 @@ The *pInputControl* parameter can be used to enable intermediate wakeups from th ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/readconsoleinput.md b/docs/readconsoleinput.md index 6b793cc..1a2a4d8 100644 --- a/docs/readconsoleinput.md +++ b/docs/readconsoleinput.md @@ -91,7 +91,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/readconsoleoutput.md b/docs/readconsoleoutput.md index 748972f..7b417f9 100644 --- a/docs/readconsoleoutput.md +++ b/docs/readconsoleoutput.md @@ -102,7 +102,7 @@ For an example, see [Reading and Writing Blocks of Characters and Attributes](re ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/readconsoleoutputattribute.md b/docs/readconsoleoutputattribute.md index f6a1372..224f726 100644 --- a/docs/readconsoleoutputattribute.md +++ b/docs/readconsoleoutputattribute.md @@ -82,7 +82,7 @@ If the number of attributes to be read from extends beyond the end of the specif ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/readconsoleoutputcharacter.md b/docs/readconsoleoutputcharacter.md index c7ab374..693e82b 100644 --- a/docs/readconsoleoutputcharacter.md +++ b/docs/readconsoleoutputcharacter.md @@ -90,7 +90,7 @@ If the number of characters to be read from extends beyond the end of the specif ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/resizepseudoconsole.md b/docs/resizepseudoconsole.md index 6945895..9bf8254 100644 --- a/docs/resizepseudoconsole.md +++ b/docs/resizepseudoconsole.md @@ -54,7 +54,7 @@ This function can resize the internal buffers in the pseudoconsole session to ma ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 10 October 2018 Update (version 1809) \[desktop apps only\] | | Minimum supported server | Windows Server 2019 \[desktop apps only\] | diff --git a/docs/scrollconsolescreenbuffer.md b/docs/scrollconsolescreenbuffer.md index 54297a1..6a83c2a 100644 --- a/docs/scrollconsolescreenbuffer.md +++ b/docs/scrollconsolescreenbuffer.md @@ -95,7 +95,7 @@ For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-bu ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsoleactivescreenbuffer.md b/docs/setconsoleactivescreenbuffer.md index 7d0698b..03e7e36 100644 --- a/docs/setconsoleactivescreenbuffer.md +++ b/docs/setconsoleactivescreenbuffer.md @@ -68,7 +68,7 @@ For an example, see [Reading and Writing Blocks of Characters and Attributes](re ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolecp.md b/docs/setconsolecp.md index 08b02c6..16ca51e 100644 --- a/docs/setconsolecp.md +++ b/docs/setconsolecp.md @@ -70,7 +70,7 @@ To determine a console's current input code page, use the [**GetConsoleCP**](get ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolectrlhandler.md b/docs/setconsolectrlhandler.md index 20384ce..9a172db 100644 --- a/docs/setconsolectrlhandler.md +++ b/docs/setconsolectrlhandler.md @@ -93,7 +93,7 @@ For an example, see [Registering a Control Handler Function](registering-a-contr ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolecursorinfo.md b/docs/setconsolecursorinfo.md index a3a1980..a05fee3 100644 --- a/docs/setconsolecursorinfo.md +++ b/docs/setconsolecursorinfo.md @@ -69,7 +69,7 @@ When a screen buffer's cursor is visible, its appearance can vary, ranging from ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolecursorposition.md b/docs/setconsolecursorposition.md index bf8d172..b31fc9d 100644 --- a/docs/setconsolecursorposition.md +++ b/docs/setconsolecursorposition.md @@ -75,7 +75,7 @@ For an example, see [Using the High-Level Input and Output Functions](using-the- ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsoledisplaymode.md b/docs/setconsoledisplaymode.md index 6f063e3..4b0e457 100644 --- a/docs/setconsoledisplaymode.md +++ b/docs/setconsoledisplaymode.md @@ -71,7 +71,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows XP \[desktop apps only\] | | Minimum supported server | Windows Server 2003 \[desktop apps only\] | diff --git a/docs/setconsolehistoryinfo.md b/docs/setconsolehistoryinfo.md index 60a79c6..f39df99 100644 --- a/docs/setconsolehistoryinfo.md +++ b/docs/setconsolehistoryinfo.md @@ -60,7 +60,7 @@ If the calling process is not a console process, the function fails and sets the ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/setconsolemode.md b/docs/setconsolemode.md index 8557eb4..2277c4e 100644 --- a/docs/setconsolemode.md +++ b/docs/setconsolemode.md @@ -73,7 +73,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsoleoutputcp.md b/docs/setconsoleoutputcp.md index 4d0ef58..793475f 100644 --- a/docs/setconsoleoutputcp.md +++ b/docs/setconsoleoutputcp.md @@ -71,7 +71,7 @@ To determine a console's current output code page, use the [**GetConsoleOutputCP ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolescreenbufferinfoex.md b/docs/setconsolescreenbufferinfoex.md index 9befffb..68d053b 100644 --- a/docs/setconsolescreenbufferinfoex.md +++ b/docs/setconsolescreenbufferinfoex.md @@ -66,7 +66,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/setconsolescreenbuffersize.md b/docs/setconsolescreenbuffersize.md index 09bc3c3..9c5f2ca 100644 --- a/docs/setconsolescreenbuffersize.md +++ b/docs/setconsolescreenbuffersize.md @@ -66,7 +66,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsoletextattribute.md b/docs/setconsoletextattribute.md index cb10858..732732d 100644 --- a/docs/setconsoletextattribute.md +++ b/docs/setconsoletextattribute.md @@ -73,7 +73,7 @@ For an example, see [Using the High-Level Input and Output Functions](using-the- ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsoletitle.md b/docs/setconsoletitle.md index 740a52e..92d0259 100644 --- a/docs/setconsoletitle.md +++ b/docs/setconsoletitle.md @@ -121,7 +121,7 @@ int main( void ) ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setconsolewindowinfo.md b/docs/setconsolewindowinfo.md index 311dab1..890a09e 100644 --- a/docs/setconsolewindowinfo.md +++ b/docs/setconsolewindowinfo.md @@ -82,7 +82,7 @@ For an example, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buff ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/setcurrentconsolefontex.md b/docs/setcurrentconsolefontex.md index 4f90d79..b49b8fb 100644 --- a/docs/setcurrentconsolefontex.md +++ b/docs/setcurrentconsolefontex.md @@ -68,7 +68,7 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows Vista \[desktop apps only\] | | Minimum supported server | Windows Server 2008 \[desktop apps only\] | diff --git a/docs/setstdhandle.md b/docs/setstdhandle.md index aeefdfd..fdb5c98 100644 --- a/docs/setstdhandle.md +++ b/docs/setstdhandle.md @@ -76,7 +76,7 @@ For an example, see [Creating a Child Process with Redirected Input and Output]( ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/small-rect-str.md b/docs/small-rect-str.md index 12fe77e..283e904 100644 --- a/docs/small-rect-str.md +++ b/docs/small-rect-str.md @@ -67,7 +67,7 @@ For an example, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-bu ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/window-buffer-size-record-str.md b/docs/window-buffer-size-record-str.md index de4a906..6b27960 100644 --- a/docs/window-buffer-size-record-str.md +++ b/docs/window-buffer-size-record-str.md @@ -58,7 +58,7 @@ For an example, see [Reading Input Buffer Events](reading-input-buffer-events.md ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/writeconsole.md b/docs/writeconsole.md index d66b0c3..39b2ab2 100644 --- a/docs/writeconsole.md +++ b/docs/writeconsole.md @@ -97,7 +97,7 @@ When virtual terminal escape sequences are not enabled, console functions can pr ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/writeconsoleinput.md b/docs/writeconsoleinput.md index 3a29d0a..3c63198 100644 --- a/docs/writeconsoleinput.md +++ b/docs/writeconsoleinput.md @@ -87,7 +87,7 @@ If the function fails, the return value is zero. To get extended error informati ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index b864594..4a9807f 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -103,7 +103,7 @@ For an example, see [Reading and Writing Blocks of Characters and Attributes](re ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/writeconsoleoutputattribute.md b/docs/writeconsoleoutputattribute.md index dcae02d..e0efe8b 100644 --- a/docs/writeconsoleoutputattribute.md +++ b/docs/writeconsoleoutputattribute.md @@ -83,7 +83,7 @@ The character values at the positions written to are not changed. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | diff --git a/docs/writeconsoleoutputcharacter.md b/docs/writeconsoleoutputcharacter.md index 54cf7cd..7807603 100644 --- a/docs/writeconsoleoutputcharacter.md +++ b/docs/writeconsoleoutputcharacter.md @@ -92,7 +92,7 @@ The attribute values at the positions written to are not changed. ## Requirements -| | | +|   |   | |-|-| | Minimum supported client | Windows 2000 Professional \[desktop apps only\] | | Minimum supported server | Windows 2000 Server \[desktop apps only\] | From fdf3c757543268d98e50f7929d5e463bda23381a Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:45:52 -0700 Subject: [PATCH 38/53] try adjusting link paths to parent. --- docs/includes/not-recommended-banner.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/not-recommended-banner.md b/docs/includes/not-recommended-banner.md index fb76346..5b6b407 100644 --- a/docs/includes/not-recommended-banner.md +++ b/docs/includes/not-recommended-banner.md @@ -1,2 +1,2 @@ > [!IMPORTANT] -> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](ecosystem-roadmap.md)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](console-virtual-terminal-sequences.md)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](classic-vs-vt.md)** document. \ No newline at end of file +> This document describes console platform functionality that is no longer a part of our **[ecosystem roadmap](../ecosystem-roadmap.md)**. We do not recommend using this content in new products, but we will continue to support existing usages for the indefinite future. Our preferred modern solution focuses on **[virtual terminal sequences](../console-virtual-terminal-sequences.md)** for maximum compatibility in cross-platform scenarios. You can find more information about this design decision in our **[classic console vs. virtual terminal](../classic-vs-vt.md)** document. \ No newline at end of file From e144aceebdc2a663ab86fa4e2a88533b51f44eea Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 7 Oct 2020 16:52:44 -0700 Subject: [PATCH 39/53] try to fix last batch of warnings. --- docs/includes/console-mode-flags.md | 22 +++++++++---------- docs/includes/console-mode-remarks.md | 6 ++--- docs/includes/no-vt-equiv-alt-buf.md | 2 +- docs/includes/no-vt-equiv-banner.md | 2 +- docs/includes/no-vt-equiv-local-context.md | 2 +- docs/includes/no-vt-equiv-shell-banner.md | 2 +- docs/includes/no-vt-equiv-user-priv.md | 2 +- .../includes/setting-codepage-mode-remarks.md | 2 +- docs/scrolling-the-screen-buffer.md | 4 ++-- docs/writeconsoleoutput.md | 2 +- 10 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/includes/console-mode-flags.md b/docs/includes/console-mode-flags.md index dc636a4..f59dd9c 100644 --- a/docs/includes/console-mode-flags.md +++ b/docs/includes/console-mode-flags.md @@ -2,21 +2,21 @@ If the *hConsoleHandle* parameter is an input handle, the mode can be one or mor | Value | Meaning | |-|-| -| **ENABLE_ECHO_INPUT** 0x0004 | Characters read by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** 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_ECHO_INPUT** 0x0004 | Characters read by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)** 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_INSERT_MODE** 0x0020 | When enabled, text entered in a console window will be inserted at the current cursor location and all text following that location will not be overwritten. When disabled, all following text will be overwritten. | -| **ENABLE_LINE_INPUT** 0x0002 | The **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** 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_MOUSE_INPUT** 0x0010 | 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](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, even when this mode is enabled. | -| **ENABLE_PROCESSED_INPUT** 0x0001 | CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, 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 line feed characters are handled by the system. | +| **ENABLE_LINE_INPUT** 0x0002 | The **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)** 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_MOUSE_INPUT** 0x0010 | 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](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)**, even when this mode is enabled. | +| **ENABLE_PROCESSED_INPUT** 0x0001 | CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)**, 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 line feed characters are handled by the system. | | **ENABLE_QUICK_EDIT_MODE** 0x0040 | This flag enables the user to use the mouse to select and edit text.

To enable this mode, use `ENABLE_QUICK_EDIT_MODE | ENABLE_EXTENDED_FLAGS`. To disable this mode, use **ENABLE_EXTENDED_FLAGS** without this flag. | -| **ENABLE_WINDOW_INPUT** 0x0008 | 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](readconsoleinput.md)** function, but not by those using **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**. | -| **ENABLE_VIRTUAL_TERMINAL_INPUT** 0x0200 | Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)** that can be retrieved by a supporting application through **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** functions.

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences. | +| **ENABLE_WINDOW_INPUT** 0x0008 | 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](../readconsoleinput.md)** function, but not by those using **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)**. | +| **ENABLE_VIRTUAL_TERMINAL_INPUT** 0x0200 | Setting this flag directs the Virtual Terminal processing engine to convert user input received by the console window into **[Console Virtual Terminal Sequences](../console-virtual-terminal-sequences.md)** that can be retrieved by a supporting application through **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](../writeconsole.md)** functions.

The typical usage of this flag is intended in conjunction with ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle to connect to an application that communicates exclusively via virtual terminal sequences. | If the *hConsoleHandle* parameter is a screen buffer handle, the mode can be one or more of the following values. When a screen buffer is created, both output modes are enabled by default. | Value | Meaning | |-|-| -| **ENABLE_PROCESSED_OUTPUT** 0x0001 | Characters written by the **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** function or echoed by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)** function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and line feed characters are processed. | -| **ENABLE_WRAP_AT_EOL_OUTPUT** 0x0002 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)** or echoing with **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](readconsole.md)**, 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 console screen buffer to scroll up (discarding the top row of the console screen buffer) when the cursor advances beyond the last row in the console screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters. | -| **ENABLE_VIRTUAL_TERMINAL_PROCESSING** 0x0004 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)**, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)**. | -| **DISABLE_NEWLINE_AUTO_RETURN** 0x0008 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](writeconsole.md)**, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

Normally when **ENABLE_WRAP_AT_EOL_OUTPUT** is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if **ENABLE_WRAP_AT_EOL_OUTPUT** was off, but the next printable character will be printed as if **ENABLE_WRAP_AT_EOL_OUTPUT** is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

The typical usage of this flag is intended in conjunction with setting **ENABLE_VIRTUAL_TERMINAL_PROCESSING** to better emulate a terminal emulator where writing the final character on the screen (in the bottom right corner) without triggering an immediate scroll is the desired behavior. | -| **ENABLE_LVB_GRID_WORLDWIDE** 0x0010 | The APIs for writing character attributes including **[WriteConsoleOutput](writeconsoleoutput.md)** and **[WriteConsoleOutputAttribute](writeconsoleoutputattribute.md)** allow the usage of flags from **[character attributes](console-screen-buffers.md#character-attributes)** to adjust the color of the foreground and background of text. Additionally, a range of DBCS flags was specified with the COMMON_LVB prefix. Historically, these flags only functioned in DBCS code pages for Chinese, Japanese, and Korean languages.

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (swap foreground and background colors) can be useful for other languages to emphasize portions of output.

Setting this console mode flag will allow these attributes to be used in every code page on every language.

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via **[Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md)**. | +| **ENABLE_PROCESSED_OUTPUT** 0x0001 | Characters written by the **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](../writeconsole.md)** function or echoed by the **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)** function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and line feed characters are processed. | +| **ENABLE_WRAP_AT_EOL_OUTPUT** 0x0002 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](../writeconsole.md)** or echoing with **[ReadFile](https://msdn.microsoft.com/library/windows/desktop/aa365467)** or **[ReadConsole](../readconsole.md)**, 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 console screen buffer to scroll up (../discarding the top row of the console screen buffer) when the cursor advances beyond the last row in the console screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters. | +| **ENABLE_VIRTUAL_TERMINAL_PROCESSING** 0x0004 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](../writeconsole.md)**, characters are parsed for VT100 and similar control character sequences that control cursor movement, color/font mode, and other operations that can also be performed via the existing Console APIs. For more information, see **[Console Virtual Terminal Sequences](../console-virtual-terminal-sequences.md)**. | +| **DISABLE_NEWLINE_AUTO_RETURN** 0x0008 | When writing with **[WriteFile](https://msdn.microsoft.com/library/windows/desktop/aa365747)** or **[WriteConsole](../writeconsole.md)**, this adds an additional state to end-of-line wrapping that can delay the cursor move and buffer scroll operations.

Normally when **ENABLE_WRAP_AT_EOL_OUTPUT** is set and text reaches the end of the line, the cursor will immediately move to the next line and the contents of the buffer will scroll up by one line. In contrast with this flag set, the scroll operation and cursor move is delayed until the next character arrives. The written character will be printed in the final position on the line and the cursor will remain above this character as if **ENABLE_WRAP_AT_EOL_OUTPUT** was off, but the next printable character will be printed as if **ENABLE_WRAP_AT_EOL_OUTPUT** is on. No overwrite will occur. Specifically, the cursor quickly advances down to the following line, a scroll is performed if necessary, the character is printed, and the cursor advances one more position.

The typical usage of this flag is intended in conjunction with setting **ENABLE_VIRTUAL_TERMINAL_PROCESSING** to better emulate a terminal emulator where writing the final character on the screen (../in the bottom right corner) without triggering an immediate scroll is the desired behavior. | +| **ENABLE_LVB_GRID_WORLDWIDE** 0x0010 | The APIs for writing character attributes including **[WriteConsoleOutput](../writeconsoleoutput.md)** and **[WriteConsoleOutputAttribute](../writeconsoleoutputattribute.md)** allow the usage of flags from **[character attributes](../console-screen-buffers.md#character-attributes)** to adjust the color of the foreground and background of text. Additionally, a range of DBCS flags was specified with the COMMON_LVB prefix. Historically, these flags only functioned in DBCS code pages for Chinese, Japanese, and Korean languages.

With exception of the leading byte and trailing byte flags, the remaining flags describing line drawing and reverse video (../swap foreground and background colors) can be useful for other languages to emphasize portions of output.

Setting this console mode flag will allow these attributes to be used in every code page on every language.

It is off by default to maintain compatibility with known applications that have historically taken advantage of the console ignoring these flags on non-CJK machines to store bits in these fields for their own purposes or by accident.

Note that using the ENABLE_VIRTUAL_TERMINAL_PROCESSING mode can result in LVB grid and reverse video flags being set while this flag is still off if the attached application requests underlining or inverse video via **[Console Virtual Terminal Sequences](../console-virtual-terminal-sequences.md)**. | diff --git a/docs/includes/console-mode-remarks.md b/docs/includes/console-mode-remarks.md index 100750f..7dd89e0 100644 --- a/docs/includes/console-mode-remarks.md +++ b/docs/includes/console-mode-remarks.md @@ -1,7 +1,7 @@ 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 or 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**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) 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**](readconsoleinput.md) function) or is passed to a function defined by the application. +The **ENABLE\_LINE\_INPUT** and **ENABLE\_ECHO\_INPUT** modes only affect processes that use [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](../readconsole.md) 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**](../readconsoleinput.md) function) or is passed to a 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**](readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](readconsole.md). +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**](../readconsoleinput.md), but they are always filtered by [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) and [**ReadConsole**](../readconsole.md). -The **ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT** modes only affect processes using [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](readconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](writeconsole.md). +The **ENABLE\_PROCESSED\_OUTPUT** and **ENABLE\_WRAP\_AT\_EOL\_OUTPUT** modes only affect processes using [**ReadFile**](https://msdn.microsoft.com/library/windows/desktop/aa365467) or [**ReadConsole**](../readconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) or [**WriteConsole**](../writeconsole.md). diff --git a/docs/includes/no-vt-equiv-alt-buf.md b/docs/includes/no-vt-equiv-alt-buf.md index 230dc2e..21e591f 100644 --- a/docs/includes/no-vt-equiv-alt-buf.md +++ b/docs/includes/no-vt-equiv-alt-buf.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended but it does have an approximate **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[alternate screen buffer](console-virtual-terminal-sequences.md#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. \ No newline at end of file +> This API is not recommended but it does have an approximate **[virtual terminal](../console-virtual-terminal-sequences.md)** equivalent in the **[alternate screen buffer](../console-virtual-terminal-sequences.md#alternate-screen-buffer)** sequence. Setting the _alternate screen buffer_ can provide an application with a separate, isolated space for drawing over the course of its session runtime while preserving the content that was displayed by the application's invoker. This maintains that drawing information for simple restoration on process exit. diff --git a/docs/includes/no-vt-equiv-banner.md b/docs/includes/no-vt-equiv-banner.md index f133004..5284489 100644 --- a/docs/includes/no-vt-equiv-banner.md +++ b/docs/includes/no-vt-equiv-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. +> This API is not recommended and does not have a **[virtual terminal](../console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application is expected to remember its own drawn state for further manipulation. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-local-context.md b/docs/includes/no-vt-equiv-local-context.md index 3a748ef..1d8d0df 100644 --- a/docs/includes/no-vt-equiv-local-context.md +++ b/docs/includes/no-vt-equiv-local-context.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. +> This API is not recommended and does not have a **[virtual terminal](../console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems. This state is only relevant to the local user, session, and privilege context. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-shell-banner.md b/docs/includes/no-vt-equiv-shell-banner.md index 8056fd2..8494634 100644 --- a/docs/includes/no-vt-equiv-shell-banner.md +++ b/docs/includes/no-vt-equiv-shell-banner.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. +> This API is not recommended and does not have a **[virtual terminal](../console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the individual client application acting as a shell or interpreter is expected to maintain its own user-convenience functionality like line reading and manipulation behavior including aliases and command history. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/no-vt-equiv-user-priv.md b/docs/includes/no-vt-equiv-user-priv.md index 10eff17..0e105fe 100644 --- a/docs/includes/no-vt-equiv-user-priv.md +++ b/docs/includes/no-vt-equiv-user-priv.md @@ -1,2 +1,2 @@ > [!TIP] -> This API is not recommended and does not have a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the user is granted full control over this presentation option. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. +> This API is not recommended and does not have a **[virtual terminal](../console-virtual-terminal-sequences.md)** equivalent. This decision intentionally aligns the Windows platform with other operating systems where the user is granted full control over this presentation option. Applications remoting via cross-platform utilities and transports like SSH may not work as expected if using this API. diff --git a/docs/includes/setting-codepage-mode-remarks.md b/docs/includes/setting-codepage-mode-remarks.md index e196eb5..d0d8b0d 100644 --- a/docs/includes/setting-codepage-mode-remarks.md +++ b/docs/includes/setting-codepage-mode-remarks.md @@ -1 +1 @@ -This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](setconsolecp.md) or [**SetConsoleOutputCP**](setconsoleoutputcp.md) functions. Legacy consumers may also use the **chcp** or **mode con cp select=** commands, but it is not recommended for new development. \ No newline at end of file +This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the [**SetConsoleCP**](../setconsolecp.md) or [**SetConsoleOutputCP**](../setconsoleoutputcp.md) functions. Legacy consumers may also use the **chcp** or **mode con cp select=** commands, but it is not recommended for new development. \ No newline at end of file diff --git a/docs/scrolling-the-screen-buffer.md b/docs/scrolling-the-screen-buffer.md index c08382a..b3d2c22 100644 --- a/docs/scrolling-the-screen-buffer.md +++ b/docs/scrolling-the-screen-buffer.md @@ -25,7 +25,7 @@ The window rectangle can change to display different parts of the console screen - When [**SetConsoleWindowInfo**](setconsolewindowinfo.md) is called to specify a new window rectangle, it scrolls the view of the console screen buffer by changing the position of the window rectangle without changing the size of the window. For examples of scrolling the window's contents, see [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md). - ![screen buffer window](images/cscon-01.png) + ![screen buffer window panning around large buffer of content](images/cscon-01.png) - When using the [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) function to write to a screen buffer with wrap at end-of-line (EOL) output mode enabled, the window rectangle shifts automatically, so the cursor is always displayed. - When the [**SetConsoleCursorPosition**](setconsolecursorposition.md) function specifies a new cursor position that is outside the boundaries of the current window rectangle, the window rectangle shifts automatically to display the cursor. @@ -40,6 +40,6 @@ In each of these situations, the window rectangle shifts to display a different The illustration shows a [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) operation that scrolls the entire contents of the console screen buffer up by several rows. The contents of the top rows are discarded, and the bottom rows are filled with a specified character and color. -![screen buffer window](images/cscon-02.png) +![screen buffer window scrolling content off top to discard](images/cscon-02.png) The effects of [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) can be limited by specifying an optional clipping rectangle so that the contents of the console screen buffer outside the clipping rectangle are unchanged. The effect of clipping is to create a subwindow (the clipping rectangle) whose contents are scrolled without affecting the rest of the console screen buffer. For an example that uses **ScrollConsoleScreenBuffer**, see [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md). diff --git a/docs/writeconsoleoutput.md b/docs/writeconsoleoutput.md index 4a9807f..79a2a71 100644 --- a/docs/writeconsoleoutput.md +++ b/docs/writeconsoleoutput.md @@ -95,7 +95,7 @@ If the rectangle specified by *lpWriteRegion* lies completely outside the bounda [!INCLUDE [setting-codepage-mode-remarks](./includes/setting-codepage-mode-remarks.md)] > [!TIP] -> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences#text-formatting.md)** and **[cursor positioning](console-virtual-terminal-sequences#cursor-positioning.md)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out the text. _Virtual terminal sequences_ are recommended for all new and ongoing development. +> This API has a **[virtual terminal](console-virtual-terminal-sequences.md)** equivalent in the **[text formatting](console-virtual-terminal-sequences.md#text-formatting)** and **[cursor positioning](console-virtual-terminal-sequences.md#cursor-positioning)** sequences. Move the cursor to the location to insert, apply the formatting desired, and write out the text. _Virtual terminal sequences_ are recommended for all new and ongoing development. ## Examples From 357a1b2cbbe6b5a5dca182decbdd2c8eb159cdcd Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Thu, 8 Oct 2020 16:23:17 -0700 Subject: [PATCH 40/53] Minor reorg to improve framing intent --- docs/classic-vs-vt.md | 74 ++++++++++++++++++++++++++++++------------- 1 file changed, 52 insertions(+), 22 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index fe460d5..384ae57 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -11,41 +11,57 @@ ms.prod: console # Classic Console APIs versus Virtual Terminal Sequences -This article will discuss the difference between the classic Windows Console API surface, defined as the series of C language functional interfaces on `kernel32.dll` with "Console" in the name, and [Virtual Terminal Sequences](console-virtual-terminal-sequences.md), defined as a language of commands embedded in the standard input and standard output streams utilizing non-printable escape characters for signaling commands interleaved with normal printable text. +Our recommendation is to replace the classic **Windows Console API** with **virtual terminal sequences**. This article will outline the difference between the two and discuss the reasons for our recommendation. + +## Definitions + +The classic **Windows Console API** surface is defined as the series of C language functional interfaces on `kernel32.dll` with "Console" in the name. + +**[Virtual terminal sequences](console-virtual-terminal-sequences.md)** is defined as a language of commands that's embedded in the standard input and standard output streams. Virtual terminal sequences use non-printable escape characters for signaling commands interleaved with normal printable text. ## History -The Windows Console has provided a broad API surface for client command-line applications to manipulate both the output display buffer and the user input buffer. However, other non-Windows platforms have never afforded this specific API-driven approach to their command-line environments, choosing instead to use virtual terminal sequences embedded within the standard input and standard output streams. For a time, Microsoft supported this behavior too in early editions of DOS and Windows through a driver called ANSI.SYS. +The **Windows Console** provides a broad API surface for client command-line applications to manipulate both the output display buffer and the user input buffer. However, other non-Windows platforms have never afforded this specific API-driven approach to their command-line environments, choosing instead to use virtual terminal sequences embedded within the standard input and standard output streams. *(For a time, Microsoft supported this behavior too in early editions of DOS and Windows through a driver called ANSI.SYS.)* -By contrast, all other platforms derive their command-line environment operations from various dialects of virtual terminal sequences. These sequences are rooted in an [ECMA Standard](https://www.ecma-international.org/publications/standards/Ecma-048.htm) and series of extensions by many vendors tracing back to Digital Equipment Corporation and Tektronix terminals through more modern and common software terminals like [xterm](https://invisible-island.net/xterm/). Many extensions exist within the virtual terminal sequence domain and some sequences are more widely supported than others, but it is safe to say that the world has standardized on this as the command language for command-line experiences with a well-known subset being supported by virtually every terminal and command-line client application. +By contrast, **virtual terminal sequences** (in a variety of dialects) drive the command-line environment operations for all other platforms. These sequences are rooted in an [ECMA Standard](https://www.ecma-international.org/publications/standards/Ecma-048.htm) and series of extensions by many vendors tracing back to Digital Equipment Corporation and Tektronix terminals, through to more modern and common software terminals, like [xterm](https://invisible-island.net/xterm/). Many extensions exist within the virtual terminal sequence domain and some sequences are more widely supported than others, but it is safe to say that the world has standardized on this as the command language for command-line experiences with a well-known subset being supported by virtually every terminal and command-line client application. -## Comparisons +## Cross-Platform Support -### Cross-Platform Support +**Virtual terminal sequences** are natively supported across platforms, making terminal applications and command-line utilities easily portable between versions and variations of operating systems, with the exception of Windows. -As every platform in the world, except Windows, natively spoke virtual terminal sequences, both terminal applications and command-line utilities have been easily portable between versions and variations of those operating systems. By contrast, Windows APIs are only supported on Windows. An extensive adapter or translation library has to be written between Windows and VT or vice versa when attempting to port command-line utilities from one platform or another. +By contrast, **Windows Console APIs** are only supported on Windows. An extensive adapter or translation library must be written between Windows and virtual terminal, or vice-versa, when attempting to port command-line utilities from one platform or another. ### Remote Access -Virtual Terminal Sequences hold a major advantage for remote access as they require no additional work to transport or perform remote procedure calls over what is required to set up a standard remote command-line connection. Simply connecting an outbound and an inbound transport channel (or a single bidirectional channel) over a pipe, socket, file, serial port, or any other device is sufficient to completely carry all information required for an application speaking these sequences to a remote host. On the contrary, the Windows Console APIs have only been accessible on the local machine and all efforts to remote them would require building an entire remote calling and transport interface layer beyond just a simple channel. +**Virtual terminal sequences** hold a major advantage for remote access. They require no additional work to transport, or perform remote procedure calls, over what is required to set up a standard remote command-line connection. Simply connecting an outbound and an inbound transport channel (or a single bidirectional channel) over a pipe, socket, file, serial port, or any other device is sufficient to completely carry all information required for an application speaking these sequences to a remote host. + +On the contrary, the **Windows Console APIs** have only been accessible on the local machine and all efforts to remote them would require building an entire remote calling and transport interface layer beyond just a simple channel. ### Separation of Concerns -Some of the Windows Console APIs provide low-level access to the input and output buffers or convenience functions for interactive command-lines like aliases and command history programmed within the console subsystem and host environment, instead of within the command-line client application itself. This is in contrast to other platforms where both the memory of the current state of the application and convenience functionality is the responsibility of the command-line utility or shell itself. +Some **Windows Console APIs** provide low-level access to the input and output buffers or convenience functions for interactive command-lines. This might include aliases and command history programmed within the console subsystem and host environment, instead of within the command-line client application itself. + +By contrast, **other platforms** make memory of the current state of the application and convenience functionality the responsibility of the command-line utility or shell itself. -While the Windows way of handling this responsibility in the console host and API makes it quicker and easier to write a command-line application with these features and without responsibility of remembering drawing state or handling editing convenience features, it makes it nearly impossible to connect those activities remotely across platforms, versions, or scenarios due to variations in implementations and availability. It also makes the final interactive experience of these Windows command-line applications completely dependent on the console host's implementation, priorities, and release cycle. +The **Windows Console** way of handling this responsibility in the console host and API makes it quicker and easier to write a command-line application with these features, removing the responsibility of remembering drawing state or handling editing convenience features. However, this makes it nearly impossible to connect those activities remotely across platforms, versions, or scenarios due to variations in implementations and availability. This way of handling responsibility also makes the final interactive experience of these Windows command-line applications completely dependent on the console host's implementation, priorities, and release cycle. -For example, advanced line editing features like syntax highlighting and complex selection are only possible when a command-line application handles editing concerns itself. The console could never have enough context to fully understand these scenarios in a broad manner like the client application can. +For example, advanced line editing features, like syntax highlighting and complex selection, are only possible when a command-line application handles editing concerns itself. The console could never have enough context to fully understand these scenarios in a broad manner like the client application can. -By contrast, other platforms handle these activities and virtual terminal communication itself through reusable client-side libraries like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and [ncurses](https://invisible-island.net/ncurses/ncurses.html). The final terminal is only responsible for displaying information and receiving input through that bidirectional communication channel. +By contrast, other platforms use **virtual terminal sequences** to handle these activities and virtual terminal communication itself through reusable client-side libraries, like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and [ncurses](https://invisible-island.net/ncurses/ncurses.html). The final terminal is only responsible for displaying information and receiving input through that bidirectional communication channel. ### Wrong-Way Verbs -On Windows, some actions can be performed in the opposite-to-natural direction on the input and output streams. This allows Windows command-line applications to both avoid the concern of managing their own buffers and to perform advanced operations like simulating/injecting input on behalf of a user or reading back some of the history of what was written. While this provides additional power to Windows applications operating in a specific user context on a single machine, it also provides a vector to cross security and privilege levels or domains when used in scenarios between contexts on the same machine or even across contexts to another machine or environment. Other platforms do not allow this activity and our intent is to converge with that strategy for both interoperability and security reasons. +With **Windows Console**, some actions can be performed in the opposite-to-natural direction on the input and output streams. This allows Windows command-line applications to avoid the concern of managing their own buffers. It also allows Windows command-line apps to perform advanced operations, like simulating/injecting input on behalf of a user, or reading back some of the history of what was written. + +While this provides additional power to Windows applications operating in a specific user-context on a single machine, it also provides a vector to cross security and privilege-levels or domains when used in certain scenarios. Such scenarios include operating between contexts on the same machine, or across contexts to another machine or environment. + +Other platforms, which use **virtual terminal sequences**, do not allow this activity. The intent of our recommendation to transition from classic Windows Console to virtual terminal sequences is to converge with this strategy for both interoperability and security reasons. ### Direct Window Access -On Windows, the exact window handle to the hosting window is available through the Console API surface. This allows a command-line utility to perform advanced window operations by reaching into the wide gamut of Win32 APIs permitted against a window handle and manipulate the window state, frame, icon, or other properties about the window. By contrast, on other platforms with virtual terminal sequences, there is a narrow set of commands that can be performed against the window to do things like changing its size or displayed title and they must be done in the same band and under the same control as the remainder of the stream. +**Windows Console API surface** provides the exact window handle to the hosting window. This allows a command-line utility to perform advanced window operations by reaching into the wide gamut of Win32 APIs permitted against a window handle. These Win32 APIs can manipulate the window state, frame, icon, or other properties about the window. + +By contrast, on other platforms with **virtual terminal sequences**, there is a narrow set of commands that can be performed against the window. These commands can do things like changing the window size or displayed title, but they must be done in the same band and under the same control as the remainder of the stream. As Windows has evolved, the security controls and restrictions on window handles have increased. Additionally, the nature and existence of an application-addressable window handle on any specific user interface element has evolved, especially with the increased support of device form factors and platforms. This makes direct window access to command-line applications fragile as the platform and experiences evolve. @@ -53,33 +69,47 @@ As Windows has evolved, the security controls and restrictions on window handles The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist. However, when otherwise undefined, using UTF-8 is widely accepted as the appropriate default. It represents the balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. -The Windows console platform has supported and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development and also accept UTF-16 as an algorithmically-translatable alternative. +The **Windows Console** platform has supported and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development. We also accept UTF-16 as an algorithmically-translatable alternative. -UTF-8 support in the console can be found via the _A_ variant of all Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. +UTF-8 support in the console can be found via the _A_ variant of all Console APIs against console handles after setting the code page to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods, as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. UTF-16 support in the console can be utilized with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. ## Recommendations -For all new and ongoing development on Windows, virtual terminal sequences are recommended as the way of interacting with the terminal. This will converge Windows command-line client applications with the style of application programming on all other platforms. +For all new and ongoing development on Windows, **virtual terminal sequences are recommended** as the way of interacting with the terminal. This will converge Windows command-line client applications with the style of application programming on all other platforms. -A limited subset of Windows Console APIs is still necessary to establish the initial environment as the Windows platform still differs from others in process, signal, device, and encoding handling: +### Exceptions for using Windows Console APIs + +A **limited subset of Windows Console APIs is still necessary** to establish the initial environment. The Windows platform still differs from others in process, signal, device, and encoding handling: - The standard handles to a process will still be controlled with **[GetStdHandle](getstdhandle.md)** and **[SetStdHandle](setstdhandle.md)**. + - Configuration of the console modes on a handle to opt in to Virtual Terminal Sequence support will be handled with **[GetConsoleMode](getconsolemode.md)** and **[SetConsoleMode](setconsolemode.md)**. + - Declaration of code page or UTF-8 support is conducted with [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods. + - Some level of overall process management may be required with the [**AllocConsole**](allocconsole.md), [**AttachConsole**](attachconsole.md) and [**FreeConsole**](freeconsole.md) to join or leave a console device session. + - Signals and signal handling will continue to be conducted with [**SetConsoleCtrlHandler**](setconsolectrlhandler.md), [**HandlerRoutine**](handlerroutine.md), and [**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md). -- Communication with the console device handles can be conducted with [**WriteConsole**](writeconsole.md) and [**ReadConsole**](readconsole.md). - - These may also be leveraged through programming language runtimes in the forms of: + +- Communication with the console device handles can be conducted with [**WriteConsole**](writeconsole.md) and [**ReadConsole**](readconsole.md). These may also be leveraged through programming language runtimes in the forms of: - C Runtime (CRT): [Stream I/O](https://docs.microsoft.com/cpp/c-runtime-library/stream-i-o) like **printf**, **scanf**, **putc**, **getc**, or [other levels of I/O functions](https://docs.microsoft.com/cpp/c-runtime-library/input-and-output). - C++ Standard Library (STL): [iostream](https://docs.microsoft.com/cpp/standard-library/iostream) like **cout** and **cin**. - .NET Runtime: [System.Console](https://docs.microsoft.com/dotnet/api/system.console) like **Console.WriteLine**. - - Applications that must be aware of window size changes will still need to use [**ReadConsoleInput**](readconsoleinput.md) to receive them interleaved with key events as **ReadConsole** alone will discard them. + +- Applications that must be aware of window size changes will still need to use [**ReadConsoleInput**](readconsoleinput.md) to receive them interleaved with key events as **ReadConsole** alone will discard them. + - Finding the window size must still be performed with [**GetConsoleScreenBufferInfo**](getconsolescreenbufferinfo.md) for applications attempting to draw columns, grids, or fill the display. Window and buffer size will match in a [pseudoconsole](pseudoconsoles.md) session. -There are no plans to remove the Windows console APIs from the platform. On the contrary, the Windows console host has provided the [pseudoconsole](pseudoconsoles.md) technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. This translation is not perfect and requires the console host window to maintain a simulated environment of what Windows would have displayed to the user and project a replica of that to the pseudoconsole host. All console API calls are operated within the simulated environment to serve the needs of the legacy command-line client application and only the effects are propagated onto the final host. +## Future planning and pseudoconsole + +There are no plans to remove the Windows console APIs from the platform. + +On the contrary, the Windows Console host has provided the **[pseudoconsole](pseudoconsoles.md)** technology to translate existing Windows command-line application calls into virtual terminal sequences and forward them to another hosting environment remotely or across platforms. + +This translation is not perfect. It requires the console host window to maintain a simulated environment of what Windows would have displayed to the user. It then projects a replica of this simulated environment to the **pseudoconsole** host. All Windows Console API calls are operated within the simulated environment to serve the needs of the legacy command-line client application. Only the effects are propagated onto the final host. -A command-line application desiring full compatibility across platforms and full support of all new features and scenarios both on Windows and elsewhere is therefore recommended to move to Virtual Terminal sequences and adjust the architecture of command-line applications to align with all platforms. +A command-line application desiring full compatibility across platforms and full support of all new features and scenarios both on Windows and elsewhere is therefore recommended to move to virtual terminal sequences and adjust the architecture of command-line applications to align with all platforms. More information about this Windows transition for command-line applications can be found on our [ecosystem roadmap](ecosystem-roadmap.md). From 5ebc90ef1e1289870eaf59506a1f3b3c2760aed6 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Mon, 12 Oct 2020 16:35:55 -0700 Subject: [PATCH 41/53] Editorial review suggestions --- docs/ecosystem-roadmap.md | 74 +++++++++++++-------- docs/images/command-line-communication.png | Bin 0 -> 17214 bytes 2 files changed, 45 insertions(+), 29 deletions(-) create mode 100644 docs/images/command-line-communication.png diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 2bc7d4c..35842df 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -10,92 +10,108 @@ ms.prod: console # Windows Console and Terminal Ecosystem Roadmap -This document is intended to provide a high-level overview of the Windows Console and Windows Terminal products, how they fit into the ecosystem of command-line applications across Windows and other operating systems, and a general roadmap of the products, features, and strategies that are a part of building the platform and building for this platform. +This document a high-level roadmap of the Windows Console and Windows Terminal products. It covers: + +- how Windows Console and Windows Terminal fit into the ecosystem of command-line applications across Windows and other operating systems; and + +- a general roadmap of the products, features, and strategies that are part of building the platform and building for this platform. + +The focus of the current console/terminal era at Microsoft is to bring a first-class terminal experience directly to developers on the Windows platform and to [phase out](classic-vs-vt.md) classic Windows Console APIs, replacing them with [virtual terminal sequences](console-virtual-terminal-sequences.md) utilizing [pseudoconsole](pseudoconsoles.md). **[Windows Terminal](/terminal/get-started)** showcases this transition into a first-class experience, inviting [open source collaboration](https://github.com/microsoft/terminal) from the developer community, supporting a full spectrum of mixing and matching of client command-line and terminal hosting applications, and unifying the Windows ecosystem with all other platforms. ## Definitions -It is highly recommended to familiarize yourself with the [definitions](definitions.md) behind common terminology in this space before proceeding with the remainder of this document. +It is recommended to familiarize yourself with the [definitions](definitions.md) of common terminology used in this space before proceeding. Common terminology includes: [Command Line (or Console) applications](./definitions#command-line-applications), [standard handles (`STDIN`, `STDOUT`, `STDERR`)](./definitions#standard-handles), [TTY and PTY devices](./definitions#ttypty), [clients and servers](./definitions#clients-and-servers), [console subsystem](./definitions#console-subsystem), [console host](./definitions#console-host), [pseudoconsole](./definitions#pseudoconsole), and [terminal](./definitions#terminal). ## Architecture -The general architecture of the system is in four parts: client, device, server, and terminal. Each is connected to the adjacent items in the list with the two ends as the respective source and destination to command-line communication. +The general architecture of the system is in four parts: client, device, server, and terminal. + +![Command Line Communication flow chart source to destination running from client to device to server to terminal](images/command-line-communication.png) ### Client -A client is a command-line application that interprets a user's desires through a text-based interface, performs work or dispatches further commands, and returns a text representation of the result. On Windows, the console API or the standard console handles with device control APIs provide a communications layer between the client and the device. +The client is a command-line application that uses a text-based interface to enable the user to enter commands (rather than a mouse-based user interface), returning a text representation of the result. On Windows, the Console API provides a communications layer between the client and the device. (This can also be a standard console handle with device control APIs). ### Device -The device is an intermediate message handling communications layer between two processes, the client and the server. On Windows, this is the console driver, while on other platforms, it is the TTY or PTY device. Other devices like files, pipes, and sockets may be used as this communication channel if the entire transaction is in plain text or contains [virtual terminal sequences](console-virtual-terminal-sequences.md), but not with [Windows Console APIs](console-functions.md). +The device is an intermediate message-handling communications layer between two processes, the client and the server. On Windows, this is the console driver. On other platforms, it is the TTY or PTY device. Other devices like files, pipes, and sockets may be used as this communication channel if the entire transaction is in plain text or contains [virtual terminal sequences](console-virtual-terminal-sequences.md), but not with [Windows Console APIs](console-functions.md). ### Server -The server interprets the requested API calls or messages from the client. On Windows in the classic operating mode, it also creates a user interface to present the output to the screen and collects input to send back in response messages to the client via the driver, like a terminal bundled in the same module. With the [pseudoconsole](pseudoconsoles.md) mode, it instead is only a translator to present this information in [virtual terminal sequences](console-virtual-terminal-sequences.md) to an attached Terminal. +The server interprets the requested API calls or messages from the client. On Windows in the classic operating mode, the server also creates a user interface to present the output to the screen. The server additionally collects input to send back in response messages to the client, via the driver, like a terminal bundled in the same module. Using [pseudoconsole](pseudoconsoles.md) mode, it instead is only a translator to present this information in [virtual terminal sequences](console-virtual-terminal-sequences.md) to an attached terminal. ### Terminal -The terminal is the final layer providing graphical display and interactivity services to the user. It is responsible for capturing input and encoding it as [virtual terminal sequences](console-virtual-terminal-sequences.md) to eventually reach the client's `STDIN` and decoding and presenting the plain text and _virtual terminal sequences_ it received back from the client's `STDOUT`. +The terminal is the final layer providing graphical display and interactivity services to the user. It is responsible for capturing input and encoding it as [virtual terminal sequences](console-virtual-terminal-sequences.md). These virtual terminal sequences eventually reach the clients `STDIN`, decoding and presenting the plain text and _virtual terminal sequences_ it received back from the clients `STDOUT`. -#### Further Connections +#### Further connections -As an addendum, further connections can be performed by chaining applications that serve multiple roles into one of the endpoints. For instance, an SSH session has two roles: it is a Terminal for the command-line application running on one device, but it forwards all received information on to a Client role on another device. This chaining can occur indefinitely across devices and contexts offering broad scenario flexibility. +As an addendum, further connections can be performed by chaining applications that serve multiple roles into one of the endpoints. For instance, an SSH session has two roles: it is a **terminal** for the command-line application running on one device, but it forwards all received information on to a **client** role on another device. This chaining can occur indefinitely across devices and contexts offering broad scenario flexibility. -On non-Windows platforms, the Server and Terminal roles are a single unit because there is no need for a translation compatibility layer between an API set and [virtual terminal sequences](console-virtual-terminal-sequences.md) as there is on Windows. +On non-Windows platforms, the **server** and **terminal** roles are a single unit because there is no need for a translation compatibility layer between an API set and [virtual terminal sequences](console-virtual-terminal-sequences.md). -## Products +## Microsoft products -All of our products are now available on GitHub in our open source repository, [microsoft/terminal](https://github.com/microsoft/terminal). +All of the Microsoft Windows command-line products are now available on GitHub in an open source repository, [microsoft/terminal](https://github.com/microsoft/terminal). ### Windows Console Host -This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application as well as the graphical user interface representation on behalf of all of those applications. It is found in the system directory as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system and can be found in other Microsoft products built from the open source repository for a more up-to-date implementation of the [pseudoconsole](pseudoconsoles.md) infrastructure. Per the definitions above, it operates in either a combined server and terminal role traditionally, or a server-only role through the preferred _pseudoconsole_ infrastructure. +This is the traditional Windows user-interface for command-line applications. It handles all console API servicing called from any attached command-line application. Windows Console also handles the graphical user interface (GUI) representation on behalf of all of those applications. It is found in the system directory as `conhost.exe`, or `openconsole.exe` in its open source form. It comes with the Windows operating system. It can also be found in other Microsoft products built from the open source repository for a more up-to-date implementation of the [pseudoconsole](pseudoconsoles.md) infrastructure. Per the definitions above, it operates in either a combined server-and-terminal role traditionally or a server-only role through the preferred _pseudoconsole_ infrastructure. ### Windows Terminal -This is the new Windows interface for command-line applications, intended as a first-party example of using the [pseudoconsole](pseudoconsoles.md) to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. It is intended to be the flagship text mode user interface for Windows and demonstrate the capabilities of the ecosystem, drive Windows development toward a unification with other platforms, and be an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. Per the definitions above, this product operates in a terminal role. +This is the new Windows interface for command-line applications. Windows Terminal serves as a first-party example of using the [pseudoconsole](pseudoconsoles.md) to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. -## Roadmap +Windows Terminal is the flagship text-mode user interface for Windows. It demonstrates the capabilities of the ecosystem and is driving Windows development toward unifying with other platforms. Windows Terminal is also an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. Per the definitions above, this product operates in a terminal role. -This roadmap starts with a brief history of major milestones in the console subsystem prior to 2014. It then moves into an overview of work performed since 2014 when the renewed focus on the command-line was formed in the Windows 10 era and finishes with what is intended to come next. +## Major historical milestones -### Implementation +The major historical milestones for the console subsystem are broken into implementation prior to 2014 and then moves into an overview of work performed since 2014, when the renewed focus on the command-line was formed in the Windows 10 era. -**\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the [Command Prompt](https://docs.microsoft.com/windows-server/administration/windows-commands/cmd), `cmd.exe`, that is a representation of that DOS environment and shares responsibilities and privileges with that interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. +### Implementation prior to 2014 + +**\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the [Command Prompt](https://docs.microsoft.com/windows-server/administration/windows-commands/cmd), `cmd.exe`, that is a representation of that DOS environment. The console host system code shares responsibilities and privileges with the Command Prompt interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. ### DBCS for CJK -**\[1997-1999\]** Around this time, [DBCS](https://docs.microsoft.com/windows/win32/intl/double-byte-character-sets) support ("Double-byte character set") is introduced to support CJK (Chinese, Japanese, and Korean) markets. This effort results in a bifurcation of many of the writing and reading methods inside the console to provide both "western" versions to deal with single-byte characters as well as an alternative representation for "eastern" versions where two bytes are required to represent the vast array of characters. This also included the expansion of the representation of a cell in the console environment to be either 1 or 2 cells wide, where 1 cell is narrow (taller than it is wide) and 2 cells is wide, full-width, or otherwise a square in which typical Chinese, Japanese, and Korean ideographs can be inscribed. +**\[1997-1999\]** Around this time, [DBCS](https://docs.microsoft.com/windows/win32/intl/double-byte-character-sets) support ("Double-byte character set") is introduced to support CJK (Chinese, Japanese, and Korean) markets. This effort results in a bifurcation of many of the writing and reading methods inside the console to provide both "western" versions to deal with single-byte characters as well as an alternative representation for "eastern" versions where two bytes are required to represent the vast array of characters. This bifurcation included the expanding representation of a cell in the console environment to be either 1 or 2 cells wide, where 1 cell is narrow (taller than it is wide) and 2 cells is wide, full-width, or otherwise a square in which typical Chinese, Japanese, and Korean ideographs can be inscribed. ### Security/Isolation -**\[2005-2009\]** With the console subsystem experience running inside the critical system process, `csrss.exe`, connecting assorted client applications at varying access levels to a single super-critical and privileged process was noticed as particularly dangerous. In this era, the console subsystem was split out into client, driver, and server applications that can each run in their own context, reducing the responsibilities and privilege in each. This isolation also increased general robustness of the system as any failure in the console subsystem no longer affected other critical process functionality. +**\[2005-2009\]** With the console subsystem experience running inside the critical system process, `csrss.exe`, connecting assorted client applications, at varying access levels, to a single super-critical and privileged process was noticed as particularly dangerous. In this era, the console subsystem was split into client, driver, and server applications. Each application could run in their own context, reducing the responsibilities and privilege in each. This isolation increased the general robustness of the system, as any failure in the console subsystem no longer affected other critical process functionality. ### User Experience Improvements -**\[2014-2016\]** After a long time of general scattered maintenance of the console subsystem by assorted teams across the organization, a new developer focused team was formed to own and drive improvements in the console. This time frame included line selection, smooth window resizing, reflowing text, copy and paste, high DPI support, and a focus on Unicode including the convergence of the split between "western" and "eastern" storage and stream manipulation algorithms. +**\[2014-2016\]** After a long time of generally scattered maintenance of the console subsystem by assorted teams across the organization, a new developer-focused team was formed to own and drive improvements in the console. Improvements during this time included: line selection, smooth window resizing, reflowing text, copy and paste, high DPI support, and a focus on Unicode, including the convergence of the split between "western" and "eastern" storage and stream manipulation algorithms. ### Virtual Terminal client -**\[2015-2017\]** With the advent of the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/), Microsoft efforts to improve the experience of [Docker on Windows](https://docs.microsoft.com/dotnet/architecture/microservices/container-docker-introduction/docker-defined), and the adoption of [OpenSSH](https://docs.microsoft.com/windows-server/administration/openssh/openssh_overview) as the premier command-line remote execution technology, the initial implementations of [virtual terminal sequences](console-virtual-terminal-sequences.md) were introduced into the console host. This allowed the existing console to act as the terminal attached directly to those Linux-native applications in their respective environments, rendering graphical and text attributes to the display and returning user input in the appropriate dialect. +**\[2015-2017\]** With the arrival of the [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/), Microsoft efforts to improve the experience of [Docker on Windows](https://docs.microsoft.com/dotnet/architecture/microservices/container-docker-introduction/docker-defined), and the adoption of [OpenSSH](https://docs.microsoft.com/windows-server/administration/openssh/openssh_overview) as the premier command-line remote execution technology, the initial implementations of [virtual terminal sequences](console-virtual-terminal-sequences.md) were introduced into the console host. This allowed the existing console to act as the terminal, attached directly to those Linux-native applications in their respective environments, rendering graphical and text attributes to the display and returning user input in the appropriate dialect. ### Virtual Terminal server -**\[2018\]** Over the past twenty years, third-party alternatives for the inbox console host had arisen to offer additional developer productivity prominently centered in rich customizations and tabbed interfaces. These applications were still beholden to run and hide the console host window and attach as a secondary "client" application to scrape out buffer information in polling loops as the primary command-line client application operated. Their goal was to be a terminal, like on other platforms, but in the Windows world where terminals were not replaceable. +**\[2018\]** Over the past twenty years, third-party alternatives for the inbox console host were created to offer additional developer productivity, prominently centered in rich customizations and tabbed interfaces. These applications still needed to run and hide the console host window. They attach as a secondary "client" application to scrape out buffer information in polling loops as the primary command-line client application operated. Their goal was to be a terminal, like on other platforms, but in the Windows world where terminals were not replaceable. + +In this time period, the [pseudoconsole](pseudoconsoles.md) infrastructure was introduced. Pseudoconsole permits any application to launch the console host in a non-interactive mode and become the final terminal interface for the user. The main limitation in this effort was the continued compatibility promise of Windows in servicing all published [Windows Console APIs](console-functions.md) for the indefinite future, while providing a replacement server-hosting interface that matched what is expected on all other platforms: [virtual terminal sequences](console-virtual-terminal-sequences.md). As such, this effort performed the mirror image of the client phase: the _pseudoconsole_ projects what would be displayed onto the screen as _virtual terminal sequences_ for a delegated host and interprets replies into Windows-format input sequences for client application consumption. -In this time period, the [pseudoconsole](pseudoconsoles.md) infrastructure was introduced, to permit any application in this position to launch the console host in a non-interactive mode and become the final terminal interface for the user. The main limitation in this effort was the continued compatibility promise of Windows in servicing all published [Windows Console APIs](console-functions.md) for the indefinite future while providing a replacement server hosting interface that matched what is expected on all other platforms: [virtual terminal sequences](console-virtual-terminal-sequences.md). As such, this effort performed the mirror image of the client phase: the _pseudoconsole_ projects what would be displayed onto the screen as _virtual terminal sequences_ for a delegated host and interprets replies into Windows-format input sequences for client application consumption. +## Roadmap for the future ### Terminal applications -**\[2019-Now\]** This era is the open source era for the console subsystem including the new Windows Terminal project. As of the Microsoft Build conference in May 2019, the entire project is on GitHub at [microsoft/terminal](https://github.com/microsoft/terminal). The focus now is building the Windows Terminal application on top of the refined platform for [pseudoconsole](pseudoconsoles.md)s to bring a first class terminal experience directly to developers on the Windows platform. +**\[2019-Now\]** This is the open source era for the console subsystem, focusing on the new Windows Terminal. Announced during the Microsoft Build conference in May 2019, Windows Terminal is entirely on GitHub at [microsoft/terminal](https://github.com/microsoft/terminal). Building the Windows Terminal application on top of the refined platform for [pseudoconsole](pseudoconsoles.md) will be the focus of this era, bringing a first-class terminal experience directly to developers on the Windows platform. -It is intended not only as a showcase for the platform including the [WinUI](https://docs.microsoft.com/windows/apps/winui/) technology, the [MSIX](https://docs.microsoft.com/windows/msix/) packaging model, and the [C++/WinRT](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/) component architecture, but also as a validation of the platform itself, driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal's unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. +**[Windows Terminal](/terminal/get-started)** intends not only to showcase the platform — including the [WinUI](/apps/winui/) interface technology, the [MSIX](/msix/) packaging model, and the [C++/WinRT](/uwp/cpp-and-winrt-apis/) component architecture — but also as a validation of the platform itself. Windows Terminal is driving the Windows organization to open and evolve the app platform as necessary to continue to lift the productivity of developers. The Windows Terminal unique set of power user and developer requirements drive the modern Windows platform requirements for what those markets truly need from Windows. -Inside the Windows operating system, this also includes retiring the classic console host user interface from its default position in favor of the Terminal, ConPTY, and VT sequence experience. And finally, it is intended to offer full choice over the default experience, whether it is the Windows Terminal product or any alternative terminals. +Inside the Windows operating system, this includes [retiring the classic console host user interface](./classic-vs-vt.md) from its default position in favor of [Windows Terminal](/terminal/get-started), [ConPTY](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/), and [virtual terminal sequences](console-virtual-terminal-sequences.md). + +Lastly, this era intends to offer full choice over the default experience, whether it is the Windows Terminal product or any alternative terminals. ### Client support library -**\[Future\]** With the support and documentation of [virtual terminal sequences](console-virtual-terminal-sequences.md) on the client side, we strongly encourage Windows command-line utility developers to use VT sequences first over the classic Windows APIs to gain the benefit of a united ecosystem with all platforms. However, one significant missing piece is that other platforms have a wide array of client-side helper libraries for handling input like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and graphical display like [ncurses](https://invisible-island.net/ncurses/ncurses.html). This particular future road map element represents the exploration of what the ecosystem offers and how we can accelerate the adoption of VT sequences in Windows command-line applications over the classic Console API. +**\[Future\]** With the support and documentation of [virtual terminal sequences](console-virtual-terminal-sequences.md) on the client side, we strongly encourage Windows command-line utility developers to use virtual terminal sequences first over the classic Windows APIs to gain the benefit of a unified ecosystem with all platforms. However, one significant missing piece is that other platforms have a wide array of client-side helper libraries for handling input like [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) and graphical display like [ncurses](https://invisible-island.net/ncurses/ncurses.html). This particular future road map element represents the exploration of what the ecosystem offers and how we can accelerate the adoption of virtual terminal sequences in Windows command-line applications over the classic Console API. ### Sequence Passthrough -**\[Future\]** While the combination of virtual terminal client and server implementations allows the full mixing and matching of client command-line and terminal hosting applications that speak either the classic [Windows Console APIs](console-functions.md) or [virtual terminal sequences](console-virtual-terminal-sequences.md), there is an overhead cost to translating the world into the classic compatible Windows method and then back into the more universal VT method. Once the market is sufficiently _virtual terminal sequences_ and UTF-8 on Windows, the conversion/interpretation job of the console host can be optionally disabled and turn into a simple API call servicer and relay from device calls to the hosting application via the [pseudoconsole](pseudoconsoles.md). This increases performance and maximizes the dialect of sequences that can be spoken between client application and the terminal enabling additional interactivity scenarios and finally bringing the Windows world into the family with all other platforms in the command-line application space. +**\[Future\]** The combination of virtual terminal client and server implementations allows the full mixing and matching of client command-line and terminal hosting applications. This combination can speak to either the classic [Windows Console APIs](console-functions.md) or [virtual terminal sequences](console-virtual-terminal-sequences.md), however, there is an overhead cost to translating this into the classic compatible Windows method and then back into the more universal virtual terminal method. + +Once the market sufficiently adopts _virtual terminal sequences_ and UTF-8 on Windows, the conversion/interpretation job of the console host can be optionally disabled. The console host would then become a simple API call servicer and relay from device calls to the hosting application via the [pseudoconsole](pseudoconsoles.md). This change will increase performance and maximize the dialect of sequences that can be spoken between the client application and the terminal. Through this change additional interactivity scenarios would be enabled and *(finally)* bring the Windows world into alignment with the family of all other platforms in the command-line application space. diff --git a/docs/images/command-line-communication.png b/docs/images/command-line-communication.png new file mode 100644 index 0000000000000000000000000000000000000000..9f9744ea18e9fb234fe301359edaf860aaed98f8 GIT binary patch literal 17214 zcmeHud03NY+AmJ0bvjOmajfFPGS=1|Q&eOPnJ!8dl_JU(NUVra!Xif2ki>qibwS9q z0%1*B5fC9s2_`XMl2(N%fuwASNgz>D5=lrROWr_2lJf?%?VNAE@0|1BIp-R#%L|^@ z_kEuGxu5&~-RpDZ)5GC!{c-Id-Q3*X+W*PNN8H?AFL85QvgZ$PfKR$UenSKPT7o$e z{-GO9yqo=65`loiksVq1N%Sz;AkGg zFcQ(W`*Hl!eB52Xq{X!zU$1{p@`mcfKIlQq-|JR=7;yfB-z9w-@!_%d zV@*eoeRIIF?8w;j?@9v5q804WufH~C;bCq3DASckmmj_O6HJ?Tr9hRt1YFwf!qtn( zuHSC7xIh=ZZcqRHz{Q4t=EsE)+oSNXbNMQp(vrz_+D!zjPW{mQ@r%FKOimluyx~@I z{Ml+Z^7>Uv2qp{OM1cHp-=y}|rPn{S{)KXp>rtW?kE}B5MUFMa7nxI`f~@V=kh@V80VDufW=A?mnE{E>Z);s!ox``>Gib;N}pn?Nm@yQf1z zf*-_5P1+vu`))7tR+TI{UYGX4)>WGhv~ouT_XmYB5JV@;^qr$HJqjsY10%`!gIBbz zp_C|FVHYKczPyX$IJg5!LJ_`NasdyX_=UH0$R~BP)1|W)dE4KZ9do2K!vZjrO5g6u zcN|GL=%yKl$9-C13?V2fXDL_e@!Iq_rXr;#oSXkI>%s zc&{k$5cXbEGIfLwT*j>)lB)w!4d6gX(3H?0TF+eaLH@hyX zy)(t;D^=aLApa^|Wg9ZRmk=B|ckK>+8@<>-1?)Y?nvod@#CPdo4XeyQSBwabkt( zv+)9r5!;8~BOhID4g*QMC2rk|^NqGNrK$AZzFu{^12Q6X>WOUPgAFhYMvG`SrSQXR zc2z|q#e;rA02=lM+ER@*)#ucx#b|^FlU{5oH;_R3q~2}Wdgf4f81~xhZts_;^Ut{b zue&l-zNGTY9dCN zkhDg7!F>LK8n!Z^D)=xL=Wh06U!EpO4~^&c$?%4(12V|08EDcM3(`p>I?P^~`HnQKUWw|>y3u4|AH((d>RLmr z-iK=GyoQOy2(rz3(6cd2GstAyQn~?-U8f#oYN;yp?t0~>U~3IVCl+Ch@wl4P-NSw# zVru~VrP%}yl6f~^(mdh6H-BWX^+6TxYC)*PGt+35+d<(O#%IkJ__#gwER0=xVWkdv znS^gbCig=0o&7fsb>MX1TMZ&O#OH(;c(CXYk4Y+kI`>p=nkG#w+l zA|=@yK-rWGo262J^BQ=ts4DsG2*ob5t+oJ%dn?+)zMR}+fKxJiCv~_seKQ-DyWQA$GG)izL&(bF+7dBg5U!?leP0 z5&S_&eB0^%st{-YJ0G@=-Amzb26=e+3Z_)|`aha37BO(+1?8(g06#T)e_5YAWcn`s z0M6m7LstglWjqVC3Oyc&(MfkCO|La;H`CG|_s?lrLlSasFL$fL$0e*ajS~UcxClj& zR$1gPJy#T%(Zmx(OXEx{=#|lYZJNqg@JI6`1N%Ok$~yH6uH2>q;>DT zibY1=3H)@MZEqzw@u20irlzc|3K9)Nly{es855i3g+}K%V@o(f2CdD#8Nn$dthLiONvp>pK zo{lbAsnZuFjOiC~)aH2G-EC8p^M*Gx+%7ctLqn9|@gJq> zecxE|hmxc*a1j!|D<{SFwdFZShk;tW#n8-3YuHIkS_VAbkS{GH|EE(u(aY@FLN9J; z;dC+8f6=u*0!GfYe1G0u1B&atNYLC^oLjuz4&RvnaDEthRga|A`D*|dugX^~O$F5g zGZQ5BZd7KbUXyrk+U~Ut0b_GxRP=hBbgQ7qWglP4+aL!x!lyqEVqHtWC9X9fS-vA; zrUgA-_+1)os>a-^8KhJ<>EUw3cHA2ehFf*gaCl3;&u6{<5=#I;X}gmN{d2Uoc}O4x zAPQjhGLSH_t!b?r;vZJhmgV4-6CM^T$-zP21`j#GZ8Iowb>es* zlo3B9^=Bewyz|fqZHw4Hx5XM5EocWVfv-+aUfaR2-@@Lx1cYSR9?+n4k)C=?Uu&k}Ix4 zS18y@Z&1TND)pkLDUw|poMt=pnj7M7!H>z~B=zij?Gq{^TSGE`e`?9MN|Y|}yD)A4 z@BS`>bbI1N)<7BXld>5gd!*RBi~g2^EgiW8wAVEyryujd6#2VkFN+8aDouAC9E`+r zV){FbhWv|!IUJS-Z?O-a}kT>+m zCwlt<1JLyPe^?8nZC_gDq*ZR+_$bYCZHp;<9^)C(Z9MiiQe0|?kVYeIgRS!EE=sb> z>L{g?2;^W%jCoQR)OcI4*^!8dC2(U{rYxck*X<|tFYC@OH;AKD`u1}rn-z^ih}@$z z?qEhW;}qpnWNZ!L0M0n8Jt)Kf9Q2W_@ofRou9r%+H4EAWJuK#UnElI=%jD^xlQEA; zj4b8usA})B;y#{~TURq@3uKw8J#zKlv5NW}MX5hXcTHBI+wsD=%u{YZv`h)-t2Fq} z5!jlh&d)!Exb+xfok#e0+&+DY1uacFeHG{y*$_p4i%5<`C>(R3f^9#>mx30)I01_snRW_y>71b%>lvvpOEm z38jst1~e^O$ZL(v8JT20VF8u#+e+3Ps?DS}=@Hmovjd~U^mwuHkN}nLG^ZDbDpR)6U(V!x&FS!He z9GUhIuh*uK%e=31fD}LJ0pjCC8>0eUFE~lV-Sc3do&TK3!_R#In>%X#y!3qGWM~)W zaef7=-mz0kCURnQ5R73Cd>tHm>pQo55+=)hk{kmBN1FA!>oc>XbMyC2x0P2dpo_STXx52in4CaE+V?5`{TQGgNaHhW6T=XS42( zpQFbwebOJ;i8;sz=?dB@1$q;=)o#F~tH9a7q0v;jOhB>8L&leW(x2BkeUJdY#sOag z_g1?NlTHC&1BXUE_!`0Sd2GKs@#dtpNCg$o2tt4R#>)>3yu+Nc^Wg+wZsx&;GxtXG z8(^CF@x)5B?If*CRK{UNY7$&SOLq4~HEe!BeACB!zj~#3m)%c%K--yJsezNA5ZN zO;^d{;0f_!^8S%<0we32-8nOx)@|CK{BkfMxZiry_)iPG901AB;*MDUX@QpmTkF~F zO}2kp;N`#`7g#=s`=tJ{ zR(esr*&!8d=yvH@?V;_b9){Xl#dyoq10Va;cyscC{?!(9VvZ0O70;BWyQp?*KcfG6 zPW6>=@vHcr%VGA5rX>8NaMGce`p;w@;-2-i4~6ry=S1sZ`SReeT>3mB8!TEAHLv{~ zZ&S27rvLsgKI;HKGi*Y3+?%s!ITU9X-#Fv3>jwRv^+6*w`O(7q|3n?*qWZa-Vl$4_ z`Z#rG=)4pcOo%qZduB6z9GbCpbo=ZXqGR!CSK_uN!6Itp?ulL|=tJ>lHDg--th5no zD|2B|NOhXu25U8uV4E6YNeTrj-pQyHF*=$e%|d3GHgroCpq!v|J}EWIeu~ z;S^`L1;QVn=f6c-oTsVt+Vc&ReEZZFOB{f6asL(Q_lC@j!w*5&&}+gRohI1GB!Og* zu3E8wi(&_}wzvO&)=XKf)sguCB=}H@(xqZcI@NoB5{ZAljuguuFcH@6ShuOk zmuI=dDx~zaf@_}GHxud98)yrY2PdNmhkFs*iY2lNwE4(1CPV3~|JZUF#K5q8*-6&E z`3qz(y0QGt^~vXkj)c!mkd(nU-EmVP`qOMl% z?oKgrE%TR!9r2i}l-817aFa6JW1wT@K+!X!{_97iNCTm!~u$5d+;oGn$^M zdje@qo0vZ`g9snbeimr$@lf5HA0^r6JKq7xNZ3OfDq59}&c~~od8kRTF@o<^FXaHH zFnd9+GymJPntc#k{-%eCq5iOktQ?0w>GWX930e|lT_d!*$^vL|_3CMik+9u1vQ=SH zxi)wal~~@ac)p zFc}(6{;YT~s(_4kIw;D!^LOg_cG$YcK4DtrHlg^IY|oi5U#=QH-jvRrLIYY|3&Fu^f@ak}pn|pabu(d7 zypf`6pSL0jw)0G4S@FQ56qx?ue5GMq?Mp_FN5uz9p1;&S%FU*|Mc5s2GdtJU)K8GM zEIVw3%fKq}C0-q6G3&KsN{kB1S{)ZOR8 z{iHNf@jxBpY)fC;*}||@C6PxoO4wz1ppu=|_ZSlGniKy+$tYx1z5z?LFER+~v6G<< zd>F*A*OP<0|9~+N>=ZhJ=b-vPlP1+Jr2!owOnNN`fSr04SBH8wTe#hm^6kWrf0FUA z!1FiPkOh`lxaUME*Q0{q|Tk7V_tH+k_M<&CM@w_;G{E; zI5c*-@d2i*7q>^s`W2tsb%IA-XMSdAw<%0ys4gC&rFPDdcV&)jvpnZ{btZNo_8cZ| z#TprQ*7*ihFxF?1$rKbC^~9|mqMb3=MD&_!z;ka!Z6)N8q zA1227ZoHYs=Zvn7UXgf8A0$VonZ~Lxg0P6>pU9}@dNrk~?%JKRp14triaS5s$j7%^ zlT#KB02tP8Ycp50I+d8D5K~&Mk6z;4jB^hkzT~UDJ2orJ68#jluL|u1qUlLW>*s|1 z>{wY_jvmqg@36Fa3+O}BpLS3sRO~vg< z`7qD;?m6Mdu`RU|a?C@DT94i|DIX4^Od~$z&`2P4@W2wsvxrOtey&*+%KgH1z^Ssf zyJMH?S|%zC?q6Y`DEyOP({M29PJ91(X(re%OWlM}Vj|+c4Rg+Qq7xJzvC+WT?;Ab-KC+(6kwO3$~ zhwfz2IMcnwd$DBds9BaJeiF4W5md+*LnfpWXBj`_`R=;LC?UC%30vJ;_834{SFbw( zAD3`w{sEDP%6hM49g^{=O?G*MX5>?il7s#JJo!o3d#thyu6RRE>2j@H?3jj=kap|r zOPm|Gv z0TO4v6loe=?ZRJR!Z=x&QeLu7u?s^ln)`MoQV0|?>}__9d?$(Bpn1sZ8MIxs4Il=F zp@E}eM39rUX#Nay-Zl>f#lAq+_O@{{)N8JVjrpnHQa-DF(#S2JsFI4Rv#CwVC$-BA z*+WpPcd;_6hpA6d&)jn9ZRYK-DdRENB${oMCEdVnD zgWgmAS+7lqs5a!9KsQMJqi`dUd3_iI%JJRozdk-`W2RV8XBa|S>!Xd6?Gx+7{pbTS zG;ys^8Pfe|nIOxcniUZ#%E$Hv_1wi5w2{1W&p2EkrdR4SI5d`ISPw^w%D5DN%$aNO ze8aG#GL6sjwd6l6*{MskfzIu@InozSmqX+-LyebFX=2pY>jo)^wcZMC+8pnj$3XSg zj`B4AX7DNS9Q!NIc9TJ|ZrUlsr$a*rFq#s73$Fg|m|4b4r`BUv^~SfOWP!fija%t( z46c5H_b`ir(=)_-St_o}`CSTWJ2m>G4m9LkMB5mYbzR?ol2i+6seHE%C|s|g`&L){ zve7>0>=X75I)ARMF&Be$*>;S!qKTpIk}`008?@~b`JAsjIF<>Pe43bJ)*FF>L4U7& zN;qgE#7w73g`1u-n7l1)CrW+(E4lX8N`i*T0+_sI{)Gz!3xT zV809~iskGN=xv`cqiI35jo)jk1reZNLO>_QF@q+t33*O_S@42_%AjN}750QF=~`WHhj)5PFj8X5SPU?C$w2=46)sSJ6s%6@X9b2h{UIZPZ3ZCXr$L#t@q;L>rfbu2yIsC@I+U58wU9{`6kT5nrZe;|z3TyJUFo0G2D= zl~cNFJLqN43IcY(9H7so9KtO?>4FeK2cn&SO{Hu3{{EJeru^Q}mCSO4G(qkR;=k{k zJ%jV6*42DQv(KXV*txz)qjTY48W^aZZP`oamWvD0gePsZEug%WCxx?AYm9xjUSX+D zLis`zXzH!)@WndCID3^%nt%~W%JtV6HnM>o&K@Rhpl9w_unC}KTAr7``I#OKRGm-A z8cyS%CSq6`QEa=pdI&rZRD57bn5{kl!nY1(l9e)t%Z-_+RH>8;G$%XGhc~4p;Ttu{ojm@wFn>!#8$%Q|gdpkj6 z?T*-}FnNO!LmI9Zaa|<$xlsod$*v}!vJH*w+`=y{IoAM&Sw%=Ykut{pE#EDU*TE9N zNPl9sFdN+J*CTE9XnDV{l)@Yf17%3GTdKs6-va$@4j`*y><)*G#;f!-+2B#PO9nj) z%CWmoypon~&5s~d>{&YckzXy3Hu-5?eIIsT^yBb*Kp1Ku}pb#+KgjPZ1Q;Q*26M|L_V0 zT!!zXVveG9-XB}m7WH#mD%IhjSXI7sv41X^PJ7ff{$5#cROc`z7lP6DXy|Et-;`}tg?ZSb}$s(=Zn=?@&MNS zQvw973`eK(QmJ;tKoxd`+jZkS1XbBg+-Xg;NquaRF{a5rGd?mLyXP>3*(0Azg=tM++BG(0^4ui`Q!|KES?Jpg9K3FR zzM_n4O7l+FPH{MUQi}_Jvja4KhcLBx_8_}l)5`h{{o~rP3Czk-{iM7}ic)=1E-Fhx z{$g^mn~Ad0V^*e23z zt9|^WWejvNz1J|1L2354$R`qjnx#IViGA)eu}Fv2oviHi0|ogpQ+)Q3=5lzbUN&E5 z$c?D1$H@)psE+Ur*}tG5S@;qKZIyn_*$?$_OTnR}300LXKZungnZH)c%^A;@nNt>} zefIY$l7qh!8y1i}!`?Ml;}RG&FH5z6ggd9)pCGMr!u+r@8iW^?`4ZhfMN=|&nM0!u ziQ=igmd2Hq5YR`}{K&Dhf#lwP(GNwTN$X5r7qt;SAV`VitvMDm;^@1Iw>Dl;Ngn*1{o+vkXY%9ncARfZ=a|V zva|^Jwi1%TBW3#Oumg^r!5O)A*8-*ZDOUhLqqW%K_Fb|-?#~R))@r)XWQ%ILCIXX; z?!A}K!tOruN-e8wm1#5=jQeBalk}IRY@@lV{R!XS(h;#y0oi7A?8>EW?%@3rCW4V| zg!_!k2L<&r%{iOEG9gB$c=CjZqJ4e7*QX-JHzzwT*tx<;{3$$%jT4Y#~9n2LJJO+{11?Acvpo4j^&@P!K zPkI;kzw)1f#6WLDWkx#J@f)!==8_~;%q#uA=(m5BjCWI1$5~)#a9;T3Ss^+B%A>O+ zRcO)1vAbY2NRmYDn_ptHndV0qBQ_TR_Pc)^FWcoQ0R;mq&Q7NWI(=c=S1(AhXxrGAy6sJmOh)*b~XWC}iXj;Otl0!nV!V z9}a$;v#<$9COKMqC!C#_3`ZLR?-=L8!gZTB*e}?Bj4T9mpaBHn{FngDkAc#HA76Td zl}6qQ#xf;jy_{h?OPo794o!i5n_)++(pIc}5U$daL%KI(3`mDDn4k4jrK3CsKP|`8 z5>xeU*cmV;&q%RB8)I@rzNX1*mearFfXbkxMHiS#l`4O`4`V-m$EX-Iv@-F}pBWRQ za&WH%K1vpF^)Eaz(n%|+V!%UX=EaHqfYl&!o3FVS0KPl6kp@T5*;N7sVV z_0ucqV$AJOK+rR&_LTxLP<{J1@UyOYVi$8as}h9KD_fDhiT6D%~ka#e~k7jWBL`cet8Jjc6Vq&^j_5LKRJ%;1o~^5EYWiC zs5<>q!0=PMLk?~-Oaz7>vrBA6$XdrW&n+OstFgw6$zc@c%%8VS5BKBQiGqIaBShO# zu+s!;3417QQzOkf0(q{J ztF!IS-cU+?1%#1o?BiGq^N>@hCHUwrBMgIPqjD9|~W540P9Q8iAI*spN3>;*$MCe~dNnUQ_0n?u%qit37 zdP52g1!@WMldzgZ{;UFGC(T{R$AQ30$nmrThZ-0V+$tUu@W`!p!RUi=sf0n-fwjm`Q9SApBO zS#~dv$jJBCV~}|Lc=uw3Ipn||h_WsX(F@kygLl3vB)TesGfQRL({JRQy7(D&fx#IcHVp4Eq-rOeNaX5XzP>R-$&XE0#MSe{0GH*jCi5;?&Dx*-fx2%DJeHoL8?S`8a2! zkyv2cB8AaKYrxwBy!<&JmoW98t8A_h!HC$E$QCMK^PK|-+{@An9i9UB;f355tK=mM4JW!l^^LLomtPRZhJ3=(*Mu)lr|Z0Cao8qt&IJ&4tq9io ze&JjLBG7R^mQR>7beMkqru#&f3O^M>V&mWMBEWcy^~e9YSWB4guO=bq&$T#XdG9Rl zwzXn1*2gXxQ)FJ7{MS5pmDWi7xrc0s(^{A zJNO{t5uVo38-3pSU%ht8IYWU}K{eIRQ`>jb>yhXMB8>=r_JmpLnRsFT36D0IHCnphX+^gwfszHOP zK1qXi70n_&rK6c~^9vn`-(7cgBwDK@#o+5^5(g**TMG%5Xt5x1VHgL=cy@PoSgPdA z&n-o8=KCl($J8Z)wNhwuP6`IxZ{Dz-ruh!pOZ%-eZ{F*|t@$5Qv)yQKVXb&K`2pkouS zx!$t;9Ltu!sx8?YDw& zkY0HEjD5CDVE*V-)M{|r3*j=xSxM7h_?4GV z-=PzeY57nW=@HTNP1N|0w#u2LAZ&~5AvW)%vDA^=+kyM2g-{XuW+EKCo+bzGR$7^z7?bpC*EUt(`oG4!$$b{x`__kCRZZYN zS*A`d1a`g{6K5Nk2Mw_Sxpc|!7f_?WYyHZ>WrgTfzb`8A)hN+>A_TXPlyq^b3XSt& z_}?kO#kzW(FAO~e(Qtr4;d z2f;*P!!I~?5D@IS^k1V57{2V1Yub{n;rS%W^jEs$T4mXBW2_! zKB+};5{PSy58hYkd%Kfm&5p`H)N~9f?gu8SbcXtg!0(_j^Bf)vknfV=&3-pxWDrC^ zeHh}X5L2+Vr>BVuOcv ztD@0}Due<;1aeSNDF<&(Cd%1i+F>)(mIB;E5?}muQT?f^qMh^k7M=UPJ9h}&%sqcF z13~8e#<11q)&^jU+~T(hNLPWEbhLxo@$rxT0IvJu6Z7v><^I>}{cE9;G;$j`nxAt9 zw{_669-+9+jx?;$P45G{nUrjvfP+)$$pr-Pc3TcETt(+*XT6t&(JgJt$oN5D4KqJ$ z8qz*0fx9l1{RrMKu*OCBFsPMb5R+t*&E%eL&uB$_wN=i26uIWyq@1!v}i+r$9Wc;IKQ zZ`V=teVEqQ?z)85jV6t4ShabVd2LjOgrTiEge4!TNzU*+)4Mi?%F|5TjZmPocnnib z;3=-@Xe;uR9$TYegEyg+$hcq&)F}PB9RW>)?WPteBtKqDz$j89e6D_fhZ_SFvu?vK zz!NY@u2mo(aCtkKf3IvpN@>jDEYNvX@*$|xSA&SpZkFXS%Cbu!|gEi@2({dc4XsHjM;2& z%>I^$A;FFm^rvXa_o?QrHYTgyz$`cfiOwVvM8+tbJ=${i*KI5;1B%>F;eXL@AA-joLvU;K{+nx&h7ktu2;F_Jp-QwIRB`F2naH+%$B-Coi)+vH z+>~xsli@q?__24*P?4b{yEtQf7^|d*2ZH^7gO?g(++Ep&B?;4?C(02DYgj7W=g+Qr zX};7oDLU!L)H+F;Zu+E@H?~%1DfKy*gp;km0;{7IWB zo9|t(zo@o8_um z9&L$7{Sgi1)2s;$G(^FoMWskPT+~yTs0M`WChz%fD z7)vU)X2|=Cld$(VpKmWOIabo=;4tq%+cdZyF9-{)J-S%`6lyr}w5nXvoGOlQi|;V{ zXG1Y`q9qBQ@O&7v{(P_PwpfZlrwc)oK!GQ_E&vVt-6vc0%e@QU%bFf-7z}85TTz~I zy4f?6n9LNMAx5zT(p_dftK0ZkZuyJtA zL*NM=XQ*P519NTiiEOhu1>B^>2se3@*`iAIA{v_oKt<{3&M Date: Mon, 12 Oct 2020 16:41:26 -0700 Subject: [PATCH 42/53] fix def anchor links --- docs/ecosystem-roadmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 35842df..ebea696 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -20,7 +20,7 @@ The focus of the current console/terminal era at Microsoft is to bring a first-c ## Definitions -It is recommended to familiarize yourself with the [definitions](definitions.md) of common terminology used in this space before proceeding. Common terminology includes: [Command Line (or Console) applications](./definitions#command-line-applications), [standard handles (`STDIN`, `STDOUT`, `STDERR`)](./definitions#standard-handles), [TTY and PTY devices](./definitions#ttypty), [clients and servers](./definitions#clients-and-servers), [console subsystem](./definitions#console-subsystem), [console host](./definitions#console-host), [pseudoconsole](./definitions#pseudoconsole), and [terminal](./definitions#terminal). +It is recommended to familiarize yourself with the [definitions](definitions.md) of common terminology used in this space before proceeding. Common terminology includes: [Command Line (or Console) applications](definitions#command-line-applications), [standard handles (`STDIN`, `STDOUT`, `STDERR`)](definitions#standard-handles), [TTY and PTY devices](definitions#ttypty), [clients and servers](definitions#clients-and-servers), [console subsystem](definitions#console-subsystem), [console host](definitions#console-host), [pseudoconsole](definitions#pseudoconsole), and [terminal](definitions#terminal). ## Architecture From bf7f39cdfd13771b7d89e50d440862584bbec0ff Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Mon, 12 Oct 2020 16:50:54 -0700 Subject: [PATCH 43/53] fix def links add file type --- docs/ecosystem-roadmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index ebea696..5ca5343 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -20,7 +20,7 @@ The focus of the current console/terminal era at Microsoft is to bring a first-c ## Definitions -It is recommended to familiarize yourself with the [definitions](definitions.md) of common terminology used in this space before proceeding. Common terminology includes: [Command Line (or Console) applications](definitions#command-line-applications), [standard handles (`STDIN`, `STDOUT`, `STDERR`)](definitions#standard-handles), [TTY and PTY devices](definitions#ttypty), [clients and servers](definitions#clients-and-servers), [console subsystem](definitions#console-subsystem), [console host](definitions#console-host), [pseudoconsole](definitions#pseudoconsole), and [terminal](definitions#terminal). +It is recommended to familiarize yourself with the [definitions](definitions.md) of common terminology used in this space before proceeding. Common terminology includes: [Command Line (or Console) applications](definitions.md#command-line-applications), [standard handles (`STDIN`, `STDOUT`, `STDERR`)](definitions.md#standard-handles), [TTY and PTY devices](definitions.md#ttypty), [clients and servers](definitions.md#clients-and-servers), [console subsystem](definitions.md#console-subsystem), [console host](definitions.md#console-host), [pseudoconsole](definitions.md#pseudoconsole), and [terminal](definitions.md#terminal). ## Architecture From aab79d3a503dc21c7b8e7931e258960d2538a080 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 13 Oct 2020 10:35:08 -0700 Subject: [PATCH 44/53] typo Co-authored-by: Michael Niksa --- docs/ecosystem-roadmap.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 5ca5343..8d23357 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -10,7 +10,8 @@ ms.prod: console # Windows Console and Terminal Ecosystem Roadmap -This document a high-level roadmap of the Windows Console and Windows Terminal products. It covers: +This document is a high-level roadmap of the Windows Console and Windows Terminal products. It covers: + - how Windows Console and Windows Terminal fit into the ecosystem of command-line applications across Windows and other operating systems; and From 667b0139cf23bdd4899def68851a77a0f92c1257 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 13 Oct 2020 15:37:14 -0700 Subject: [PATCH 45/53] minor grammatical updates --- docs/definitions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/definitions.md b/docs/definitions.md index 5609039..137af7a 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -18,9 +18,9 @@ Command line applications, or sometimes called "console applications" and/or ref ## Standard Handles -The standard handles are a series of handles, `STDIN`, `STDOUT`, and `STDERR`, that are introduced a part of process space on startup and represent a place where information can be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts and are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither of the first two are specified/permitted. For classic windows applications, these may be blank on startup, but can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. +The standard handles are a series, `STDIN`, `STDOUT`, and `STDERR`, introduced as part of a process space on startup. They represent a place for information to be accepted on the way in and sent back on the way out (including a special place to report errors out). For command-line applications, these must always exist when the application starts. They are either inherited from the parent automatically, set explicitly by the parent, or created automatically by the operating system if neither are specified/permitted. For classic Windows applications, these may be blank on startup. However, they can be implicitly or explicitly inherited from the parent or allocated, attached, and freed during runtime by the application itself. -Standard handles do not imply a specific type of attached device, though in the case of command-line applications, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. +Standard handles do not imply a specific type of attached device. In the case of command-line applications, however, the device is most commonly a console device, file (from redirection in a shell), or a pipe (from a shell connecting the output of one utility to the input of the next). It may also be a socket or any other type of device. ## TTY/PTY From 9b0c64504bee6c30d2327e83b4eb9ee73b7f9e51 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 13 Oct 2020 15:46:24 -0700 Subject: [PATCH 46/53] Fix header Co-authored-by: Michael Niksa --- docs/ecosystem-roadmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 8d23357..aa1c740 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -69,7 +69,7 @@ Windows Terminal is the flagship text-mode user interface for Windows. It demons The major historical milestones for the console subsystem are broken into implementation prior to 2014 and then moves into an overview of work performed since 2014, when the renewed focus on the command-line was formed in the Windows 10 era. -### Implementation prior to 2014 +### Initial Implementation **\[1989-1990s]** The initial console host system was implemented as an emulation of the DOS environment within the Windows operating system. Its code is entangled and cooperative with the [Command Prompt](https://docs.microsoft.com/windows-server/administration/windows-commands/cmd), `cmd.exe`, that is a representation of that DOS environment. The console host system code shares responsibilities and privileges with the Command Prompt interpreter/shell. It also provides a base level of services for other command-line utilities to perform services in a CMD-like manner. From 109de60c174ea8b9b1ec5ac946bd4f0967505ff6 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 13 Oct 2020 15:46:44 -0700 Subject: [PATCH 47/53] typo Co-authored-by: Michael Niksa --- docs/ecosystem-roadmap.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index aa1c740..ee7b148 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -61,7 +61,8 @@ This is the traditional Windows user-interface for command-line applications. It ### Windows Terminal -This is the new Windows interface for command-line applications. Windows Terminal serves as a first-party example of using the [pseudoconsole](pseudoconsoles.md) to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. +This is the new Windows interface for command-line applications. Windows Terminal serves as a first-party example of using the [pseudoconsole](pseudoconsoles.md) to separate the concerns between API servicing and text-based application interfacing, much like all non-Windows platforms. + Windows Terminal is the flagship text-mode user interface for Windows. It demonstrates the capabilities of the ecosystem and is driving Windows development toward unifying with other platforms. Windows Terminal is also an example of how to build a robust and complex modern application that spans the history and gamut of Windows APIs and frameworks. Per the definitions above, this product operates in a terminal role. From 223c943b28938fc507de94b99917120531bfac71 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 13 Oct 2020 15:48:40 -0700 Subject: [PATCH 48/53] Update format of bullet list --- docs/ecosystem-roadmap.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index ee7b148..50dd87c 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -13,9 +13,9 @@ ms.prod: console This document is a high-level roadmap of the Windows Console and Windows Terminal products. It covers: -- how Windows Console and Windows Terminal fit into the ecosystem of command-line applications across Windows and other operating systems; and +- How Windows Console and Windows Terminal fit into the ecosystem of command-line applications across Windows and other operating systems. -- a general roadmap of the products, features, and strategies that are part of building the platform and building for this platform. +- A history and future roadmap of the products, features, and strategies that are part of building the platform, as well as building for this platform. The focus of the current console/terminal era at Microsoft is to bring a first-class terminal experience directly to developers on the Windows platform and to [phase out](classic-vs-vt.md) classic Windows Console APIs, replacing them with [virtual terminal sequences](console-virtual-terminal-sequences.md) utilizing [pseudoconsole](pseudoconsoles.md). **[Windows Terminal](/terminal/get-started)** showcases this transition into a first-class experience, inviting [open source collaboration](https://github.com/microsoft/terminal) from the developer community, supporting a full spectrum of mixing and matching of client command-line and terminal hosting applications, and unifying the Windows ecosystem with all other platforms. From ce92884d88e76862a9c67a261e093a2b58028933 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Thu, 15 Oct 2020 10:27:26 -0700 Subject: [PATCH 49/53] Update terminal explanation --- docs/ecosystem-roadmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ecosystem-roadmap.md b/docs/ecosystem-roadmap.md index 50dd87c..e725036 100644 --- a/docs/ecosystem-roadmap.md +++ b/docs/ecosystem-roadmap.md @@ -43,7 +43,7 @@ The server interprets the requested API calls or messages from the client. On Wi ### Terminal -The terminal is the final layer providing graphical display and interactivity services to the user. It is responsible for capturing input and encoding it as [virtual terminal sequences](console-virtual-terminal-sequences.md). These virtual terminal sequences eventually reach the clients `STDIN`, decoding and presenting the plain text and _virtual terminal sequences_ it received back from the clients `STDOUT`. +The terminal is the final layer providing graphical display and interactivity services to the user. It is responsible for capturing input and encoding it as [virtual terminal sequences](console-virtual-terminal-sequences.md), which eventually reach the client's `STDIN`. It will also receive and decode the *virtual terminal sequences* that it receives back from the client's `STDOUT` for presentation on the screen. #### Further connections From a9d7f8af0d8dcecc9629eec2251f8cd78b50c06d Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 28 Oct 2020 11:13:23 -0700 Subject: [PATCH 50/53] Proposed rephrasing of UTF8/16 support. --- docs/classic-vs-vt.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index fe460d5..e5da823 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -51,14 +51,16 @@ As Windows has evolved, the security controls and restrictions on window handles ### Unicode -The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist. However, when otherwise undefined, using UTF-8 is widely accepted as the appropriate default. It represents the balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. +The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist. However, when otherwise undefined, using UTF-8 is widely accepted as the appropriate default. It represents the balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. However, an algorithmic equivalent in UTF-16 was chosen as the primary Unicode support mechanism for the Windows platform. -The Windows console platform has supported and will continue to support all existing code pages and encodings, but we recommend UTF-8 for all forward looking development and also accept UTF-16 as an algorithmically-translatable alternative. - -UTF-8 support in the console can be found via the _A_ variant of all Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. +The Windows console platform has supported and will continue to support all existing code pages and encodings. It is recommended to focus on UTF-16 for maximum compatibility across Windows versions and performing algorithmic translation with UTF-8 if necessary. Increased support of UTF-8 is in progress for the console system. UTF-16 support in the console can be utilized with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. +UTF-8 support in the console can be found via the _A_ variant of Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. + +>[!NOTE] As of now, UTF-8 is supported fully on the standard output stream with the [**WriteConsole**](writeconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) methods. Support on the input stream varies depending on the input mode and will continue to improve over time. Notably the default **["cooked"](high-level-console-modes.md)** modes on input do not fully support UTF-8 yet. The current status of this work can be found at [**microsoft/terminal#7777**](https://github.com/microsoft/terminal/issues/7777) on GitHub. The workaround is to use the algorithmically-translatable UTF-16 for reading input through [**ReadConsoleW**](readconsole.md) or [**ReadConsoleInputW**](readconsoleinput.md) until the outstanding issues are resolved. + ## Recommendations For all new and ongoing development on Windows, virtual terminal sequences are recommended as the way of interacting with the terminal. This will converge Windows command-line client applications with the style of application programming on all other platforms. From 52b8e3f3de0316e84c04f70af6b719dfaeaaf777 Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 28 Oct 2020 11:18:07 -0700 Subject: [PATCH 51/53] fix warning --- docs/classic-vs-vt.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 0f765ca..9fe0e0c 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -75,7 +75,8 @@ UTF-16 support in the console can be utilized with no additional configuration v UTF-8 support in the console can be found via the _A_ variant of Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods, as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. ->[!NOTE] As of now, UTF-8 is supported fully on the standard output stream with the [**WriteConsole**](writeconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) methods. Support on the input stream varies depending on the input mode and will continue to improve over time. Notably the default **["cooked"](high-level-console-modes.md)** modes on input do not fully support UTF-8 yet. The current status of this work can be found at [**microsoft/terminal#7777**](https://github.com/microsoft/terminal/issues/7777) on GitHub. The workaround is to use the algorithmically-translatable UTF-16 for reading input through [**ReadConsoleW**](readconsole.md) or [**ReadConsoleInputW**](readconsoleinput.md) until the outstanding issues are resolved. +>[!NOTE] +> As of now, UTF-8 is supported fully on the standard output stream with the [**WriteConsole**](writeconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) methods. Support on the input stream varies depending on the input mode and will continue to improve over time. Notably the default **["cooked"](high-level-console-modes.md)** modes on input do not fully support UTF-8 yet. The current status of this work can be found at [**microsoft/terminal#7777**](https://github.com/microsoft/terminal/issues/7777) on GitHub. The workaround is to use the algorithmically-translatable UTF-16 for reading input through [**ReadConsoleW**](readconsole.md) or [**ReadConsoleInputW**](readconsoleinput.md) until the outstanding issues are resolved. ## Recommendations From 94fd0df84b52e028abea38b54827f8c7e6243b9f Mon Sep 17 00:00:00 2001 From: Michael Niksa Date: Wed, 28 Oct 2020 11:34:51 -0700 Subject: [PATCH 52/53] Revisions for Dustin commentary. --- docs/classic-vs-vt.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 9fe0e0c..0cc65ce 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -67,13 +67,13 @@ As Windows has evolved, the security controls and restrictions on window handles ### Unicode -The implicit standard for communication across platforms and the web is Unicode, specifically in the UTF-8 form. Of course, other encodings still exist. However, when otherwise undefined, using UTF-8 is widely accepted as the appropriate default. It represents the balance of portability, storage/transmission size, and breadth of expression required to support the world's languages and glyphs. However, an algorithmic equivalent in UTF-16 was chosen as the primary Unicode support mechanism for the Windows platform. +UTF-8 is the accepted encoding for Unicode data across almost all modern platforms, as it strikes the right balance between portability, storage size and processing time. However, Windows historically chose UTF-16 as its primary encoding for Unicode data. Support for UTF-8 is increasing in Windows and use of these Unicode formats does not preclude the usage of other encodings. -The **Windows Console** platform has supported and will continue to support all existing code pages and encodings. It is recommended to focus on UTF-16 for maximum compatibility across Windows versions and performing algorithmic translation with UTF-8 if necessary. Increased support of UTF-8 is in progress for the console system. +The **Windows Console** platform has supported and will continue to support all existing code pages and encodings. Use UTF-16 for maximum compatibility across Windows versions and perform algorithmic translation with UTF-8 if necessary. Increased support of UTF-8 is in progress for the console system. UTF-16 support in the console can be utilized with no additional configuration via the _W_ variant of all console APIs and is a more likely choice for applications already well versed in UTF-16 through communication with the `wchar_t` and _W_ variant of other Microsoft and Windows platform functions and products. -UTF-8 support in the console can be found via the _A_ variant of Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods, as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. +UTF-8 support in the console can be utilized via the _A_ variant of Console APIs against console handles after setting the codepage to `65001` or `CP_UTF8` with the [**SetConsoleOutputCP**](setconsoleoutputcp.md) and [**SetConsoleCP**](setconsolecp.md) methods, as appropriate. Setting the code pages in advance is only necessary if the machine has not chosen "Use Unicode UTF-8 for worldwide language support" in the settings for Non-Unicode applications in the Region section of the Control Panel. >[!NOTE] > As of now, UTF-8 is supported fully on the standard output stream with the [**WriteConsole**](writeconsole.md) and [**WriteFile**](https://msdn.microsoft.com/library/windows/desktop/aa365747) methods. Support on the input stream varies depending on the input mode and will continue to improve over time. Notably the default **["cooked"](high-level-console-modes.md)** modes on input do not fully support UTF-8 yet. The current status of this work can be found at [**microsoft/terminal#7777**](https://github.com/microsoft/terminal/issues/7777) on GitHub. The workaround is to use the algorithmically-translatable UTF-16 for reading input through [**ReadConsoleW**](readconsole.md) or [**ReadConsoleInputW**](readconsoleinput.md) until the outstanding issues are resolved. From 12225b35dafcbe6c54821ce2822d8ebf1f84dd44 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Wed, 28 Oct 2020 13:33:41 -0700 Subject: [PATCH 53/53] Link console api --- docs/classic-vs-vt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/classic-vs-vt.md b/docs/classic-vs-vt.md index 0cc65ce..0ad0072 100644 --- a/docs/classic-vs-vt.md +++ b/docs/classic-vs-vt.md @@ -15,7 +15,7 @@ Our recommendation is to replace the classic **Windows Console API** with **virt ## Definitions -The classic **Windows Console API** surface is defined as the series of C language functional interfaces on `kernel32.dll` with "Console" in the name. +The classic **[Windows Console API](console-functions.md)** surface is defined as the series of C language functional interfaces on `kernel32.dll` with "Console" in the name. **[Virtual terminal sequences](console-virtual-terminal-sequences.md)** is defined as a language of commands that's embedded in the standard input and standard output streams. Virtual terminal sequences use non-printable escape characters for signaling commands interleaved with normal printable text.