NAME

Win32::Console::DotNet - Win32 Console .NET interface

SYNOPSIS

Simply integrate this module into your package or script.

use Win32::Console::DotNet;
System::Console->WriteLine();

use Win32::Console::DotNet;
# using the System namespace
use System;
Console->WriteLine();

DESCRIPTION

The console is a window in which users interact with a text-based console application by entering text input via the computer keyboard and reading text output from the computer terminal.

The System::Console class provides basic support for applications that read characters from and write characters to the console.

Note: System::Console is singleton a class that has represents the standard input, output, and error streams for console applications.

Class

public class System::Console

Object Hierarchy

Class::Tiny::Object
  System::Console

Constants

_DEBUG

use constant _DEBUG => 1|undef;

_DEBUG is defined as 1 if the environment variable NDEBUG or PERL_NDEBUG is not defined as true and any of the following environment variables have been set to true, otherwise undefined.

PERL_STRICT
EXTENDED_TESTING
AUTHOR_TESTING
RELEASE_TESTING

see Devel::StrictMode

TRUE

FALSE

use constant {
  TRUE  => !! 1,
  FALSE => !! '',
};

Defines TRUE and FALSE constants.

see constant::boolean

DefaultConsoleBufferSize

use constant DefaultConsoleBufferSize => 256;

Defines the standard console buffer size.

MinBeepFrequency

MaxBeepFrequency

use constant {
  MinBeepFrequency  => 0x25,
  MaxBeepFrequency  => 0x7fff,
};

Beep range - see MSDN.

MaxConsoleTitleLength

use constant MaxConsoleTitleLength => 24500;

MSDN says console titles can be up to 64 KB in length. But I get an exception if I use buffer lengths longer than ~24500 Unicode characters. Oh well.

StdConUnicodeEncoding

use constant StdConUnicodeEncoding => { CodePage => Int, bigEndian => Int };

The value corresponds to the Windows code pages 1200 (little endian byte order) or 1201 (big endian byte order).

WinError.h

constant Win32Native::ERROR_INVALID_HANDLE = 0x6;

ERROR_INVALID_HANDLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions.

WinCon.h

use constant Win32Native::KEY_EVENT => 0x0001;

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

Attributes

BackgroundColor

field BackgroundColor ( is => rw, type => Int ) = 0;

A Color that specifies the background color of the console; that is, the color that appears behind each character. The default is black.

throws ArgumentException if the color specified in a set operation is not valid.

BufferHeight

field BufferHeight ( is => rw, type => Int );

The current height, in rows, of the buffer area.

throws ArgumentOutOfRangeException if the value in a set operation is less than or equal to zero or greater than or equal to 0x7fff or less than "WindowTop" + "WindowHeight".

throws An I/O error occurred.

BufferWidth

field BufferWidth ( is => rw, type => Int );

The current width, in columns, of the buffer area.

throws ArgumentOutOfRangeException if the value in a set operation is less than or equal to zero or greater than or equal to 0x7fff or less than "WindowLeft" + "WindowWidth".

CapsLock

field CapsLock ( is => rwp, type => Bool );

Gets a value indicating whether the CAPS LOCK keyboard toggle is turned on or turned off.

CursorLeft

field CursorLeft ( is => rw, type => Int );

The column position of the cursor within the buffer area.

throws ArgumentOutOfRangeException if the value in a set operation is less than zero or greater than or equal to "BufferWidth".

CursorSize

field CursorSize ( is => rw, type => Int );

The height of the cursor within a character cell.

The size of the cursor expressed as a percentage of the height of a character cell. The property value ranges from 1 to 100.

throws ArgumentOutOfRangeException if the value specified in a set operation is less than 1 or greater than 100.

CursorTop

field CursorTop ( is => rw, type => Int );

The row position of the cursor within the buffer area.

throws ArgumentOutOfRangeException if the value in a set operation is less than zero or greater than or equal to "BufferHeight".

CursorVisible

field CursorVisible ( is => rw, type => Bool );

The attribute indicating whether the cursor is visible.

True if the cursor is visible; otherwise, false.

Error

field Error ( is => rwp, type => Defined );

A FileHandle that represents the standard error stream.

ForegroundColor

field ForegroundColor ( is => rw, type => Int ) = $FG_LIGHTGRAY;

Color that specifies the foreground color of the console; that is, the color of each character that is displayed. The default is gray.

throws ArgumentException if the color specified in a set operation is not valid.

In

field In ( is => rwp, type => Defined );

A FileHandle that represents the standard input stream.

InputEncoding

field InputEncoding ( is => rw, type => Int );

Gets or sets the encoding the console uses to write input.

note A get operation may return a cached value instead of the console's current input encoding.

IsErrorRedirected

field IsErrorRedirected ( is => ro, type => Bool );

Gets a value that indicates whether error has been redirected from the standard error stream. True if error is redirected; otherwise, false.

IsInputRedirected

field IsInputRedirected ( is => ro, type => Bool );

Gets a value that indicates whether input has been redirected from the standard input stream. True if input is redirected; otherwise, false.

IsOutputRedirected

field IsOutputRedirected ( is => ro, type => Bool );

Gets a value that indicates whether output has been redirected from the standard output stream. True if output is redirected; otherwise, false.

KeyAvailable

field KeyAvailable ( is => ro, type => Bool );

Gets a value indicating whether a key press is available in the input stream.

LargestWindowHeight

field LargestWindowHeight ( is => ro, type => Int );

Gets the largest possible number of console window rows, based on the current font and screen resolution.

LargestWindowWidth

field LargestWindowWidth ( is => ro, type => Int );

Gets the largest possible number of console window columns, based on the current font and screen resolution.

NumberLock

field NumberLock ( is => ro, type => Bool );

Gets a value indicating whether the NUM LOCK keyboard toggle is turned on or turned off.

Out

field Out ( is => rwp, type => Defined );

A FileHandle that represents the standard output stream.

OutputEncoding

field OutputEncoding ( is => rw, type => Int );

Gets or sets the encoding the console uses to write output.

note A get operation may return a cached value instead of the console's current output encoding.

Title

field Title ( is => rw, type => Str ) = '';

The string to be displayed in the title bar of the console. The maximum length of the title string is 24500 characters.

throws ArgumentOutOfRangeException if in a set operation, the specified title is longer than 24500 characters.

throws Exception if in a set operation, the specified title is not a string.

TreatControlCAsInput

field TreatControlCAsInput ( is => rw, type => Bool ) = FALSE;

Indicating whether the combination of the Control modifier key and C console key (Ctrl+C) is treated as ordinary input or as an interruption that is handled by the operating system.

The attribute is true if Ctrl+C is treated as ordinary input; otherwise, false.

throws Exception if unable to get or set the input mode of the console input buffer.

WindowHeight

field WindowHeight ( is => rw, type => Int );

The height of the console window measured in rows.

throws ArgumentOutOfRangeException if the value is less than or equal to 0 or the value plus "WindowTop" is greater than or equal to 0x7fff or the value greater than the largest possible window height for the current screen resolution and console font.

throws Exception if an error occurs when reading or writing information.

WindowLeft

field WindowLeft ( is => rw, type => Int );

The leftmost console window position measured in columns.

throws ArgumentOutOfRangeException if the value is less than 0 or as a result of the assignment, WindowLeft plus "WindowWidth" would exceed "BufferWidth".

throws Exception if an error occurs when reading or writing information.

WindowTop

field WindowTop ( is => rw, type => Int );

The uppermost console window position measured in rows.

throws ArgumentOutOfRangeException if the value is less than 0 or as a result of the assignment, WindowTop plus "WindowHeight" would exceed "BufferHeight".

throws Exception if an error occurs when reading or writing information.

WindowWidth

field WindowWidth ( is => rw, type => Int );

The width of the console window measured in columns.

throws ArgumentOutOfRangeException if the value is less than or equal to 0 or the value plus "WindowLeft" is greater than or equal to 0x7fff or the value greater than the largest possible window width for the current screen resolution and console font.

throws Exception if an error occurs when reading or writing information.

Constructors

new

factory new() : System::Console

Public constructor.

instance

factory instance() : System::Console

This constructor instantiates an object instance if none exists, otherwise it returns an existing instance.

It is used to initialize the default I/O console.

Destructors

DEMOLISH

method DEMOLISH()

Restore the console before destroying the instance/object.

Methods

Beep

method Beep()

Plays the sound of a beep through the console speaker.

method Beep(Int frequency, Int duration)

Plays the sound of a beep of a specified frequency and duration through the console speaker.

param $frequency of the beep, ranging from 37 to 32767 hertz.

param $duration of the beep measured in milliseconds.

throws ArgumentOutOfRangeException if $frequency is less than 37 or more than 32767 hertz or $duration is less than or equal to zero.

Clear

method Clear()

Clears the console buffer and corresponding console window of display information.

throws IOException if an I/O error occurred.

GetCursorPosition

method GetCursorPosition() : ArrayRef[Int]

Gets the position of the cursor.

return the column and row position of the cursor as array reference.

MoveBufferArea

method MoveBufferArea(Int $sourceLeft, Int $sourceTop, Int $sourceWidth, 
  Int $sourceHeight, Int $targetLeft, Int $targetTop);

Copies a specified source area of the screen buffer to a specified destination area.

param $sourceLeft is the leftmost column of the source area.

param $sourceTop is the topmost row of the source area.

param $sourceWidth is the number of columns in the source area.

param $sourceHeight is the number of rows in the source area.

param $targetLeft is the leftmost column of the destination area.

param $targetTop is the topmost row of the destination area.

throws ArgumentOutOfRangeException if one or more of the parameters is less than zero or $sourceLeft or $targetLeft is greater than or equal to "BufferWidth" or $sourceTop or $targetTop is greater than or equal to "BufferHeight" or $sourceTop + $sourceHeight is greater than or equal to "BufferHeight" or $sourceLeft + $sourceWidth is greater than or equal to "BufferWidth".

throws IOException if an I/O error occurred.

note If the destination and source parameters specify a position located outside the boundaries of the current screen buffer, only the portion of the source area that fits within the destination area is copied. That is, the source area is clipped to fit the current screen buffer.

The MoveBufferArea method copies the source area to the destination area. If the destination area does not intersect the source area, the source area is filled with blanks using the current foreground and background colors. Otherwise, the intersected portion of the source area is not filled.

method MoveBufferArea(Int $sourceLeft, Int $sourceTop, Int $sourceWidth, 
  Int $sourceHeight, Int $targetLeft, Int $targetTop, Str $sourceChar, 
  Int $sourceForeColor, Int $sourceBackColor);

Copies a specified source area of the screen buffer to a specified destination area.

param $sourceLeft is the leftmost column of the source area.

param $sourceTop is the topmost row of the source area.

param $sourceWidth is the number of columns in the source area.

param $sourceHeight is the number of rows in the source area.

param $targetLeft is the leftmost column of the destination area.

param $targetTop is the topmost row of the destination area.

param $sourceChar is the character used to fill the source area.

param $sourceForeColor is the foreground color used to fill the source area.

param $sourceBackColor is the background color used to fill the source area.

throws ArgumentException if one or both of the color parameters is not valid.

throws IOException if an I/O error occurred.

The MoveBufferArea method copies the source area to the destination area. If the destination area does not intersect the source area, the source area is filled with the character specified by sourceChar, using the colors specified by $sourceForeColor and $sourceBackColor. Otherwise, the intersected portion of the source area is not filled.

The MoveBufferArea method performs no operation if $sourceWidth or $sourceHeight is zero.

OpenStandardError

method OpenStandardError() : FileHandle
method OpenStandardError(Int $bufferSize) : FileHandle

Acquires the standard error object.

return the standard error object.

OpenStandardInput

method OpenStandardInput() : FileHandle
method OpenStandardInput(Int $bufferSize) : FileHandle

Acquires the standard input object.

return the standard input object.

OpenStandardOutput

method OpenStandardOutput() : FileHandle
method OpenStandardOutput(Int $bufferSize) : FileHandle

Acquires the standard output object.

return the standard output object.

Read

method Read() : Int

Reads the next character from the standard input stream.

return the next character from the input stream, or negative one (-1) if there are currently no more characters to be read.

throws IOException if an I/O error occurred.

ReadKey

method ReadKey() : HashRef
method ReadKey(Bool $intercept) : HashRef

Obtains the next character or function key pressed by the user. The pressed key is optionally displayed in the console window.

param $intercept determines whether to display the pressed key in the console window. true to not display the pressed key; otherwise, false.

return an HashRef that describes the console key and unicode character, if any, that correspond to the pressed console key. The HashRef also describes, in a bitwise combination of values, whether one or more Shift, Alt, or Ctrl modifier keys was pressed simultaneously with the console key.

ReadLine

method ReadLine() : Str

Reads the next line of characters from the standard input stream.

return the next line of characters from the input stream, or undef if no more lines are available.

throws IOException if an I/O error occurred.

ResetColor

method ResetColor()

Sets the foreground and background console colors to their defaults.

throws IOException if an I/O error occurred.

SetBufferSize

method SetBufferSize(Int $width, Int $height)

Sets the height and width of the screen buffer area to the specified values.

param $width of the buffer area measured in columns.

param $height of the buffer area measured in rows.

SetCursorPosition

method SetCursorPosition(Int $left, Int $top)

Sets the position of the cursor.

param $left column position of the cursor. Columns are numbered from left to right starting at 0.

param $top row position of the cursor. Rows are numbered from top to bottom starting at 0.

SetError

method SetError(FileHandle $newError)

Sets the "Error" attribute to the specified error FileHandle.

param $newError represents a FileHandle that is the new standard error.

SetIn

method SetIn(FileHandle $newIn)

Sets the "In" attribute to the specified input FileHandle.

param $newIn represents a io handle that is the new standard input.

SetOut

method SetOut(FileHandle $newOut)

Sets the "Out" attribute to the specified output FileHandle.

param $newOut represents a io handle that is the new standard output.

SetWindowSize

method SetWindowSize(Int $width, Int $height)

Sets the height and width of the console window to the specified values.

param $width of the console window measured in columns.

param $height of the console window measured in rows.

SetWindowPosition

method SetWindowPosition(Int $left, Int $top)

Sets the position of the console window relative to the screen buffer.

param $left corner of the console window.

param $top corner of the console window.

Write

method Write(Str $format, Item $arg0, Item $arg1, ...)

Writes the text representation of the specified arguments to the standard output stream using the specified format information.

param $format is a composite format string.

param $arg0 is the first item to write using format.

param $arg1 is the second item to write using format.

param ...

throws IOException if an I/O error occurred.

throws ArgumentNullException if $format is undef.

note this method does not perform any formatting of its own: It uses the Perl function sprintf.

method Write(Int $value)

Writes the text representation of the specified integer value to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method Write(String $value)

Writes the specified string value to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method Write(Object $value)

Writes the text representation of the specified object to the standard output stream.

param $value is the value to write or undef.

throws IOException if an I/O error occurred.

note If $value is undef, nothing is written and no exception is thrown. Otherwise, the stringification method of $value is called to produce its string representation, and the resulting string is written to the standard output stream.

method Write(Num $value)

Writes the text representation of the specified floating-point value to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method Write(Bool $value)

Writes the text representation of the specified Boolean value to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

WriteLine

method WriteLine(Str $format, Item $arg0, Item $arg1, ...)

Writes the text representation of the specified objects, followed by the current line terminator, to the standard output stream using the specified format information.

param $format is a composite format string.

param $arg0 is the first item to write using format.

param $arg1 is the second item to write using format.

param ...

throws IOException if an I/O error occurred.

throws ArgumentNullException if $format is undef.

note this method does not perform any formatting of its own: It uses the Perl function sprintf.

method WriteLine(String $value)

Writes the specified string value, followed by the current line terminator, to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method WriteLine(Int $value)

Writes the text representation of the specified integer value, followed by the current line terminator, to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method WriteLine(Num $value)

Writes the text representation of the specified floating-point value, followed by the current line terminator, to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method WriteLine(Bool $value)

Writes the text representation of the specified Boolean value, followed by the current line terminator, to the standard output stream.

param $value is the value to write.

throws IOException if an I/O error occurred.

method WriteLine()

Writes the current line terminator to the standard output stream.

throws IOException if an I/O error occurred.

method WriteLine(Object $value)

Writes the text representation of the specified object, followed by the current line terminator, to the standard output stream.

param $value is the value to write or undef.

throws IOException if an I/O error occurred.

note If $value is undef only the line terminator is written. Otherwise, the stringification method of $value is called to produce its string representation, and the resulting string is written to the standard output stream.

Inheritance

Methods inherited from class Class::Tiny::Object

new, DESTROY

Methods inherited from class UNIVERSAL

can, DOES, isa, VERSION

COPYRIGHT AND LICENCE

This class provides access to the standard input, standard output
and standard error streams

Copyright (c) 2015 by Microsoft Corporation.

The library files are licensed under MIT licence.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

AUTHORS

2024 by J. Schneider https://github.com/brickpool/

DISCLAIMER OF WARRANTIES

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

CONTRIBUTORS

2008, 2009 by Piotr Roszatycki <dexter@cpan.org> (Code snippet from constant:boolean)
2011 by Joe Vornehm <joejr@vornehm.com> (Code snippet from RT64675)
2019-2021 by magiblot <magiblot@hotmail.com> (Code snippet from stdioctl.cpp)

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Class

Constants

Attributes

Constructors

Destructors

Methods

Inheritance

COPYRIGHT AND LICENCE

AUTHORS

DISCLAIMER OF WARRANTIES

CONTRIBUTORS

SEE ALSO

Module Install Instructions