Creating, Activating, and Destroying Screen Buffers

There are two ways that an application can obtain a reference to a screen buffer. When the console window is created, a default screen buffer is created and set as the active screen buffer. Windows applications can gain access to that screen buffer by calling the CreateFile API function to open a file called "CONOUT$". Opening CONOUT$ always returns a handle to the process's active screen buffer, provided, of course, that the application is attached to a console and has the proper permissions. In JConsole, the method GetActiveScreenBuffer opens CONOUT$ and creates a ConsoleScreenBuffer object instance that refers to the open handle. Applications that require only a single screen buffer can call GetActiveScreenBuffer and not worry about creating new buffers.

To use multiple screen buffers, you need to create the additional buffers yourself, by calling the ConsoleScreenBuffer constructor. There are actually two different constructors. The default constructor, which takes no parameters, calls the console API function CreateConsoleScreenBuffer, and initializes an object that references the newly created screen buffer.

Another constructor is used internally by JConsole.GetActiveScreenBuffer and not really intended for use by application programs. That constructor is marked internal so that it's only accessible in the CabDotNet namespace.

If you call JConsole.GetActiveScreenBuffer, the returned ConsoleScreenBuffer references the current active screen buffer and anything you write will appear in the console window. If you call the ConsoleScreenBuffer constructor, the object returned references an in-memory screen buffer. Anything you write to that buffer will not be shown in the console window until you make it the active screen buffer.

To make a screen buffer the active screen buffer and to have its contents shown in the console window, pass the ConsoleScreenBuffer object reference to JConsole.SetActiveScreenBuffer. The console window's contents will be replaced by the contents of the new screen buffer. Because the screen buffer also controls the size of the screen buffer window, the cursor position, and many other properties, setting the active screen buffer can have a dramatic effect on the appearance of the console window.

Remember that the console is a shared resource. As you saw in the previous article, multiple processes can attach to a single console window.

Read Jim Mischel's previous article, Extending the .NET Console Interface.

If one process changes the active screen buffer, output from other processes is not displayed unless those processes make another call to JConsole.GetActiveScreenBuffer. And they don't know they're supposed to do that unless the application that changed the active screen buffer notifies them of the change. One way around that problem would be to have applications always call GetActiveScreenBuffer to make sure that they're talking to the right screen buffer, but that presents a performance problem if the program does a lot of output. It's probably best to have a single screen buffer if you expect multiple processes to use the console. My rule of thumb is to have either multiple screen buffers or multiple processes, but not both.

When you're done using a screen buffer, you should call the object's Dispose method so that the object can free the resource handle that it allocates. ConsoleScreenBuffer implements the Dispose Design Pattern, so you should put any allocations (calls to GetActiveScreenScreenBuffer or to the ConsoleScreenBuffer constructor) in a try…finally block or in a using statement.

You shouldn't encounter a problem with one application pulling the rug out from under the other application when they're sharing multiple screen buffers. Each process gets its own handle to the screen buffer, and Windows won't destroy the underlying screen buffer object until all of the handles that point to it are closed. Since one process can't close another process's handles, you won't encounter a situation in which you're trying to access an invalid screen buffer handle.