The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Win32-Console-DotNet-0.005001
River stage zero No dependents
/ Win32::Console::DotNet

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("The current console title is: \"%s\"",
    System::Console->Title);
  System::Console->WriteLine("\t(Press any key to change the console title.)");
  System::Console->ReadKey(1);
  System::Console->Title( "The title has changed!" );
  System::Console->WriteLine("Note that the new console title is \"%s\"\n".
    "\t(Press any key to quit.)", System::Console->Title);
  System::Console->ReadKey(1);
  #
  # This example produces the following results:
  #     The current console title is: "Command Prompt - perl  samples\Title.pl"
  #         (Press any key to change the console title.)
  #     Note that the new console title is "The title has changed!"
  #         (Press any key to quit.)
  #

Alternatively, using the System namespace.

  use Time::Piece;
  use Win32::Console::DotNet;
  use System;
  #
  Console->Clear();
  my $dat = localtime;
  #
  Console->Write("\nToday is %s at %s.", $dat->mdy, $dat->hms);
  Console->Write("\nPress Enter key to continue... ");
  Console->ReadLine();
  #
  # The example displays output like the following:
  #     Today is 07/30/2024 at 08:32:54.
  #     Press Enter key to continue...
  #

DESCRIPTION

The Win32::Console::DotNet class offers fundamental support for Windows applications that read from and write to a console.

The Win32::Console::DotNet class is based on the Windows::Console module and provides an .NET compatible API.

The .NET API provides a number of benefits that allow developers to effectively create console applications and efficiently manage Windows console applications. Here are some of the key features:

  • Windows Console Functions: The .NET API offers a wide range of functions for handling input and output, such as reading keyboard inputs and writing text to the screen. These low-level functions such as ReadConsoleInput, WriteConsoleOutput, and SetConsoleCursorPosition are suitably abstracted by the .NET API.

  • Windows Console Structures: Access to low-level data structures such as CONSOLE_SCREEN_BUFFER_INFO or INPUT_RECORD is simplified by using the .NET API. These low-level console structures are effectively managed by this module.

  • Windows Console Extentions: It provides an extended compatibility layer to the classic Windows Console API. The .NET API provided in this module is well-known and thoroughly documented, transforming the otherwise complex Windows Console API into a powerful tool for developing Windows console applications.

To summarize: The .Net API provides easy direct access to console windows and allows detailed control over display and interaction, making your applications based on the classic Windows console API more robust and therefore better.

Note: System::Console is the singleton class that represents the Win32::Console::DotNet console applications. You can take a closer look at the use of System::Console in the examples provided.

Class

public class Win32::Console::DotNet

Object Hierarchy

  Class::Tiny::Object
    Win32::Console::DotNet

Constants

WinError.h
  use 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: IOException if 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 => Object );
  class_has InputEncoding ( is => rw, isa => Object, init_arg => undef );

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

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

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

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 );
  class_has IsInputRedirected ( is => ro, type => Bool, init_arg => undef );

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 );
  class_has IsOutputRedirected ( is => ro, type => Bool, init_arg => undef );

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 => Object );
  class_has OutputEncoding ( is => rw, isa => Object, init_arg => undef );

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

Remarks: 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 for set and 1024 for get.

Throws: InvalidOperationException in a get operation, if the specified title is longer than 24500 characters.

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

Throws: ArgumentNullException in a set operation, if the specified title is undef.

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

Note: The return value is a empty string if the specific length is > 1024.

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() : Win32::Console::DotNet

Public constructor.

instance
  factory instance() : Win32::Console::DotNet

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.

Returns: 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.

Remarks: 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: 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: ArgumentException if one or both of the color parameters is not valid.

Throws: IOException if an I/O error occurred.

Remarks: 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 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
  classmethod OpenStandardError() : FileHandle
  classmethod OpenStandardError(Int $bufferSize) : FileHandle

Acquires the standard error object.

Returns: the standard error object.

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

Acquires the standard input object.

Returns: the standard input object.

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

Acquires the standard output object.

Returns: the standard output object.

Read
  method Read() : Int

Reads the next character from the standard input stream.

Returns: 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() : ConsoleKeyInfo
  method ReadKey(Bool $intercept) : ConsoleKeyInfo

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.

Returns: an ConsoleKeyInfo (blessed HashRef) that describes the console key and unicode character, if any, that correspond to the pressed console key. The ConsoleKeyInfo 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.

Returns: 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.

Remarks: 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.

Remarks: If $value is undef, nothing is written and no exception is thrown. Otherwise, the stringification method of $value is called to produce its stringrepresentation, 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.

Remarks: 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.

Remarks: 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

DEPENDENCIES

This module is based on Win32::Console. Additionally, there are only a few dependencies on non-core modules.

The requirements necessary for the runtime are listed below:

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

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)

SEE ALSO

Win32::Console, console.cs