MshHostRawUserInterface.cs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using System.Globalization;

#pragma warning disable 1634, 1691 // Stops compiler from warning about unknown warnings

namespace System.Management.Automation.Host
{
    #region Ancillary types.

    // I would have preferred to make these nested types within PSHostRawUserInterface, but that
    // is evidently discouraged by the .net design guidelines.

    /// <summary>
    /// Represents an (x,y) coordinate pair.
    /// </summary>
    public
    struct Coordinates
    {
        #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell

        private int x;
        private int y;

        #endregion

        /// <summary>
        /// Gets and sets the X coordinate.
        /// </summary>
        public int X
        {
            get { return x; }

            set { x = value; }
        }

        /// <summary>
        /// Gets and sets the Y coordinate.
        /// </summary>
        public int Y
        {
            get { return y; }

            set { y = value; }
        }

        /// <summary>
        /// Initializes a new instance of the Coordinates class and defines the X and Y values.
        /// </summary>
        /// <param name="x">
        /// The X coordinate
        /// </param>
        /// <param name="y">
        /// The Y coordinate
        /// </param>
        public
        Coordinates(int x, int y)
        {
            this.x = x;
            this.y = y;
        }

        /// <summary>
        /// Overrides <see cref="object.ToString"/>
        /// </summary>
        /// <returns>
        /// "a,b" where a and b are the values of the X and Y properties.
        /// </returns>
        public override
        string
        ToString()
        {
            return string.Create(CultureInfo.InvariantCulture, $"{X},{Y}");
        }

        /// <summary>
        /// Overrides <see cref="object.Equals(object)"/>
        /// </summary>
        /// <param name="obj">
        /// object to be compared for equality.
        /// </param>
        /// <returns>
        /// True if <paramref name="objB"/> is Coordinates and its X and Y values are the same as those of this instance,
        /// false if not.
        /// </returns>
        public override
        bool
        Equals(object obj)
        {
            bool result = false;

            if (obj is Coordinates)
            {
                result = this == ((Coordinates)obj);
            }

            return result;
        }

        /// <summary>
        /// Overrides <see cref="object.GetHashCode"/>
        /// </summary>
        /// <returns>
        /// Hash code for this instance.
        /// </returns>
        public override
        int
        GetHashCode()
        {
            // idea: consider X the high-order part of a 64-bit in, and Y the lower order half.  Then use the int64.GetHashCode.

            UInt64 i64 = 0;

            if (X < 0)
            {
                if (X == Int32.MinValue)
                {
                    // add one and invert to avoid an overflow.

                    i64 = (UInt64)(-1 * (X + 1));
                }
                else
                {
                    i64 = (UInt64)(-X);
                }
            }
            else
            {
                i64 = (UInt64)X;
            }

            // rotate 32 bits to the left.

            i64 *= 0x100000000U;

            // mask in Y

            if (Y < 0)
            {
                if (Y == Int32.MinValue)
                {
                    i64 += (UInt64)(-1 * (Y + 1));
                }
                else
                {
                    i64 += (UInt64)(-Y);
                }
            }
            else
            {
                i64 += (UInt64)Y;
            }

            int result = i64.GetHashCode();

            return result;
        }

        /// <summary>
        /// Compares two instances for equality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if the respective X and Y values are the same, false otherwise.
        /// </returns>
        public static
        bool
        operator ==(Coordinates first, Coordinates second)
        {
            bool result = first.X == second.X && first.Y == second.Y;

            return result;
        }

        /// <summary>
        /// Compares two instances for inequality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if any of the respective either X or Y field is not the same, false otherwise.
        /// </returns>
        public static
        bool
        operator !=(Coordinates first, Coordinates second)
        {
            return !(first == second);
        }
    }

    /// <summary>
    /// Represents a width and height pair.
    /// </summary>
    public
    struct Size
    {
        #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell

        private int width;
        private int height;

        #endregion

        /// <summary>
        /// Gets and sets the Width.
        /// </summary>
        public int Width
        {
            get { return width; }

            set { width = value; }
        }

        /// <summary>
        /// Gets and sets the Height.
        /// </summary>
        public int Height
        {
            get { return height; }

            set { height = value; }
        }

        /// <summary>
        /// Initialize a new instance of the Size class and defines the Width and Height values.
        /// </summary>
        /// <param name="width">
        /// The Width
        /// </param>
        /// <param name="height">
        /// The Height
        /// </param>
        public
        Size(int width, int height)
        {
            this.width = width;
            this.height = height;
        }

        /// <summary>
        /// Overloads <see cref="object.ToString"/>
        /// </summary>
        /// <returns>
        /// "a,b" where a and b are the values of the Width and Height properties.
        /// </returns>
        public override
        string
        ToString()
        {
            return string.Create(CultureInfo.InvariantCulture, $"{Width},{Height}");
        }

        /// <summary>
        /// Overrides <see cref="object.Equals(object)"/>
        /// </summary>
        /// <param name="obj">
        /// object to be compared for equality.
        /// </param>
        /// <returns>
        /// True if <paramref name="obj"/> is Size and its Width and Height values are the same as those of this instance,
        /// false if not.
        /// </returns>
        public override
        bool
        Equals(object obj)
        {
            bool result = false;

            if (obj is Size)
            {
                result = this == ((Size)obj);
            }

            return result;
        }

        /// <summary>
        /// Overrides <see cref="object.GetHashCode"/>
        /// </summary>
        /// <returns>
        /// Hash code for this instance.
        /// <!--
        /// consider Width the high-order part of a 64-bit in, and
        /// Height the lower order half.  Then use the int64.GetHashCode.-->
        /// </returns>
        public override
        int
        GetHashCode()
        {
            // idea: consider Width the high-order part of a 64-bit in, and Height the lower order half.  Then use the int64.GetHashCode.

            UInt64 i64 = 0;

            if (Width < 0)
            {
                if (Width == Int32.MinValue)
                {
                    // add one and invert to avoid an overflow.

                    i64 = (UInt64)(-1 * (Width + 1));
                }
                else
                {
                    i64 = (UInt64)(-Width);
                }
            }
            else
            {
                i64 = (UInt64)Width;
            }

            // rotate 32 bits to the left.

            i64 *= 0x100000000U;

            // mask in Height

            if (Height < 0)
            {
                if (Height == Int32.MinValue)
                {
                    i64 += (UInt64)(-1 * (Height + 1));
                }
                else
                {
                    i64 += (UInt64)(-Height);
                }
            }
            else
            {
                i64 += (UInt64)Height;
            }

            int result = i64.GetHashCode();

            return result;
        }

        /// <summary>
        /// Compares two instances for equality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if the respective Width and Height fields are the same, false otherwise.
        /// </returns>
        public static
        bool
        operator ==(Size first, Size second)
        {
            bool result = first.Width == second.Width && first.Height == second.Height;

            return result;
        }

        /// <summary>
        /// Compares two instances for inequality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if any of the respective Width and Height fields are not the same, false otherwise.
        /// </returns>
        public static
        bool
        operator !=(Size first, Size second)
        {
            return !(first == second);
        }
    }

    /// <summary>
    /// Governs the behavior of <see cref="System.Management.Automation.Host.PSHostRawUserInterface.ReadKey()"/>
    /// and <see cref="System.Management.Automation.Host.PSHostRawUserInterface.ReadKey(System.Management.Automation.Host.ReadKeyOptions)"/>
    /// </summary>
    [Flags]
    public
    enum
    ReadKeyOptions
    {
        /// <summary>
        /// Allow Ctrl-C to be processed as a keystroke, as opposed to causing a break event.
        /// </summary>
        AllowCtrlC = 0x0001,

        /// <summary>
        /// Do not display the character for the key in the window when pressed.
        /// </summary>
        NoEcho = 0x0002,

        /// <summary>
        /// Include key down events.  Either one of IncludeKeyDown and IncludeKeyUp or both must be specified.
        /// </summary>
        IncludeKeyDown = 0x0004,

        /// <summary>
        /// Include key up events.  Either one of IncludeKeyDown and IncludeKeyUp or both must be specified.
        /// </summary>
        IncludeKeyUp = 0x0008
    }

    /// <summary>
    /// Defines the states of Control Key.
    /// </summary>
    [Flags]
    public
    enum ControlKeyStates
    {
        /// <summary>
        /// The right alt key is pressed.
        /// </summary>
        RightAltPressed = 0x0001,

        /// <summary>
        /// The left alt key is pressed.
        /// </summary>
        LeftAltPressed = 0x0002,

        /// <summary>
        /// The right ctrl key is pressed.
        /// </summary>
        RightCtrlPressed = 0x0004,

        /// <summary>
        /// The left ctrl key is pressed.
        /// </summary>
        LeftCtrlPressed = 0x0008,

        /// <summary>
        /// The shift key is pressed.
        /// </summary>
        ShiftPressed = 0x0010,

        /// <summary>
        /// The numlock light is on.
        /// </summary>
        NumLockOn = 0x0020,

        /// <summary>
        /// The scrolllock light is on.
        /// </summary>
        ScrollLockOn = 0x0040,

        /// <summary>
        /// The capslock light is on.
        /// </summary>
        CapsLockOn = 0x0080,

        /// <summary>
        /// The key is enhanced.
        /// </summary>
        EnhancedKey = 0x0100
    }

    /// <summary>
    /// Represents information of a keystroke.
    /// </summary>
    public
    struct KeyInfo
    {
        #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell

        private int virtualKeyCode;
        private char character;
        private ControlKeyStates controlKeyState;
        private bool keyDown;

        #endregion

        /// <summary>
        /// Gets and set device-independent key.
        /// </summary>
        public int VirtualKeyCode
        {
            get { return virtualKeyCode; }

            set { virtualKeyCode = value; }
        }

        /// <summary>
        /// Gets and set unicode Character of the key.
        /// </summary>
        public char Character
        {
            get { return character; }

            set { character = value; }
        }

        /// <summary>
        /// State of the control keys.
        /// </summary>
        public ControlKeyStates ControlKeyState
        {
            get { return controlKeyState; }

            set { controlKeyState = value; }
        }

        /// <summary>
        /// Gets and set the status of whether this instance is generated by a key pressed or released.
        /// </summary>
        public bool KeyDown
        {
            get { return keyDown; }

            set { keyDown = value; }
        }

        /// <summary>
        /// Initialize a new instance of the KeyInfo class and defines the VirtualKeyCode,
        /// Character, ControlKeyState and KeyDown values.
        /// </summary>
        /// <param name="virtualKeyCode">
        /// The virtual key code
        /// </param>
        /// <param name="ch">
        /// The character
        /// </param>
        /// <param name="controlKeyState">
        /// The control key state
        /// </param>
        /// <param name="keyDown">
        /// Whether the key is pressed or released
        /// </param>
        public
        KeyInfo
        (
            int virtualKeyCode,
            char ch,
            ControlKeyStates controlKeyState,
            bool keyDown
        )
        {
            this.virtualKeyCode = virtualKeyCode;
            this.character = ch;
            this.controlKeyState = controlKeyState;
            this.keyDown = keyDown;
        }

        /// <summary>
        /// Overloads <see cref="object.ToString"/>
        /// </summary>
        /// <returns>
        /// "a,b,c,d" where a, b, c, and d are the values of the VirtualKeyCode, Character, ControlKeyState, and KeyDown properties.
        /// </returns>
        public override
        string
        ToString()
        {
            return string.Create(CultureInfo.InvariantCulture, $"{VirtualKeyCode},{Character},{ControlKeyState},{KeyDown}");
        }
        /// <summary>
        /// Overrides <see cref="object.Equals(object)"/>
        /// </summary>
        /// <param name="obj">
        /// object to be compared for equality.
        /// </param>
        /// <returns>
        /// True if <paramref name="obj"/> is KeyInfo and its VirtualKeyCode, Character, ControlKeyState, and KeyDown values are the
        /// same as those of this instance, false if not.
        /// </returns>
        public override
        bool
        Equals(object obj)
        {
            bool result = false;

            if (obj is KeyInfo)
            {
                result = this == ((KeyInfo)obj);
            }

            return result;
        }

        /// <summary>
        /// Overrides <see cref="object.GetHashCode"/>
        /// </summary>
        /// <returns>
        /// Hash code for this instance.
        /// <!--consider KeyDown (true == 1, false == 0) the highest-order nibble,
        ///                ControlKeyState the second to fourth highest-order nibbles
        ///                VirtualKeyCode the lower-order nibbles of a 32-bit int,
        ///       Then use the UInt32.GetHashCode.-->
        /// </returns>
        public override
        int
        GetHashCode()
        {
            // idea: consider KeyDown (true == 1, false == 0) the highest-order nibble,
            //                ControlKeyState the second to fourth highest-order nibbles
            //                VirtualKeyCode the lower-order nibbles of a 32-bit int,
            //       Then use the UInt32.GetHashCode.

            UInt32 i32 = KeyDown ? 0x10000000U : 0;

            // mask in ControlKeyState
            i32 |= ((uint)ControlKeyState) << 16;

            // mask in the VirtualKeyCode
            i32 |= (UInt32)VirtualKeyCode;

            return i32.GetHashCode();
        }

        /// <summary>
        /// Compares two instances for equality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if the respective Character, ControlKeyStates , KeyDown, and VirtualKeyCode fields
        /// are the same, false otherwise.
        /// </returns>
        /// <exception/>
        public static
        bool
        operator ==(KeyInfo first, KeyInfo second)
        {
            bool result = first.Character == second.Character && first.ControlKeyState == second.ControlKeyState &&
                          first.KeyDown == second.KeyDown && first.VirtualKeyCode == second.VirtualKeyCode;

            return result;
        }

        /// <summary>
        /// Compares two instances for inequality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if any of the respective Character, ControlKeyStates , KeyDown, or VirtualKeyCode fields
        /// are the different, false otherwise.
        /// </returns>
        /// <exception/>
        public static
        bool
        operator !=(KeyInfo first, KeyInfo second)
        {
            return !(first == second);
        }
    }

    /// <summary>
    /// Represents a rectangular region of the screen.
    /// <!--We use this structure instead of System.Drawing.Rectangle because S.D.R
    /// is way overkill and would bring in another assembly.-->
    /// </summary>
    public
    struct Rectangle
    {
        #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell

        private int left;
        private int top;
        private int right;
        private int bottom;

        #endregion

        /// <summary>
        /// Gets and sets the left side of the rectangle.
        /// </summary>
        public int Left
        {
            get { return left; }

            set { left = value; }
        }

        /// <summary>
        /// Gets and sets the top of the rectangle.
        /// </summary>
        public int Top
        {
            get { return top; }

            set { top = value; }
        }

        /// <summary>
        /// Gets and sets the right side of the rectangle.
        /// </summary>
        public int Right
        {
            get { return right; }

            set { right = value; }
        }

        /// <summary>
        /// Gets and sets the bottom of the rectangle.
        /// </summary>
        public int Bottom
        {
            get { return bottom; }

            set { bottom = value; }
        }

        /// <summary>
        /// Initialize a new instance of the Rectangle class and defines the Left, Top, Right, and Bottom values.
        /// </summary>
        /// <param name="left">
        /// The left side of the rectangle
        /// </param>
        /// <param name="top">
        /// The top of the rectangle
        /// </param>
        /// <param name="right">
        /// The right side of the rectangle
        /// </param>
        /// <param name="bottom">
        /// The bottom of the rectangle
        /// </param>
        /// <exception cref="ArgumentException">
        /// <paramref name="right"/> is less than <paramref name="left"/>;
        /// <paramref name="bottom"/> is less than <paramref name="top"/>
        /// </exception>
        public
        Rectangle(int left, int top, int right, int bottom)
        {
            if (right < left)
            {
                // "right" and "left" are not localizable
                throw PSTraceSource.NewArgumentException(nameof(right), MshHostRawUserInterfaceStrings.LessThanErrorTemplate, "right", "left");
            }

            if (bottom < top)
            {
                // "bottom" and "top" are not localizable
                throw PSTraceSource.NewArgumentException(nameof(bottom), MshHostRawUserInterfaceStrings.LessThanErrorTemplate, "bottom", "top");
            }

            this.left = left;
            this.top = top;
            this.right = right;
            this.bottom = bottom;
        }

        /// <summary>
        /// Initializes a new instance of the Rectangle class and defines the Left, Top, Right, and Bottom values
        /// by <paramref name="upperLeft"/>, the upper left corner and <paramref name="lowerRight"/>, the lower
        /// right corner.
        /// <!--
        /// Added based on feedback from review with BCL PM.
        /// -->
        /// </summary>
        /// <param name="upperLeft">
        /// The Coordinates of the upper left corner of the Rectangle
        /// </param>
        /// <param name="lowerRight">
        /// The Coordinates of the lower right corner of the Rectangle
        /// </param>
        /// <exception/>
        public
        Rectangle(Coordinates upperLeft, Coordinates lowerRight)
            : this(upperLeft.X, upperLeft.Y, lowerRight.X, lowerRight.Y)
        {
        }

        /// <summary>
        /// Overloads <see cref="object.ToString"/>
        /// </summary>
        /// <returns>
        /// "a,b ; c,d" where a, b, c, and d are values of the Left, Top, Right, and Bottom properties.
        /// </returns>
        public override
        string
        ToString()
        {
            return string.Create(CultureInfo.InvariantCulture, $"{Left},{Top} ; {Right},{Bottom}");
        }

        /// <summary>
        /// Overrides <see cref="object.Equals(object)"/>
        /// </summary>
        /// <param name="obj">
        /// object to be compared for equality.
        /// </param>
        /// <returns>
        /// True if <paramref name="obj"/> is Rectangle and its Left, Top, Right, and Bottom values are the same as those of this instance,
        /// false if not.
        /// </returns>
        public override
        bool
        Equals(object obj)
        {
            bool result = false;

            if (obj is Rectangle)
            {
                result = this == ((Rectangle)obj);
            }

            return result;
        }

        /// <summary>
        /// Overrides <see cref="object.GetHashCode"/>
        /// </summary>
        /// <returns>
        /// Hash code for this instance.
        /// <!-- consider (Top XOR Bottom) the high-order part of a 64-bit int,
        ///                (Left XOR Right) the lower order half.  Then use the int64.GetHashCode.-->
        /// </returns>
        /// <exception/>
        public override
        int
        GetHashCode()
        {
            // idea: consider (Top XOR Bottom) the high-order part of a 64-bit int,
            //                (Left XOR Right) the lower order half.  Then use the int64.GetHashCode.

            UInt64 i64 = 0;

            int upper = Top ^ Bottom;
            if (upper < 0)
            {
                if (upper == Int32.MinValue)
                {
                    // add one and invert to avoid an overflow.

                    i64 = (UInt64)(-1 * (upper + 1));
                }
                else
                {
                    i64 = (UInt64)(-upper);
                }
            }
            else
            {
                i64 = (UInt64)upper;
            }

            // rotate 32 bits to the left.

            i64 *= 0x100000000U;

            // mask in lower

            int lower = Left ^ Right;
            if (lower < 0)
            {
                if (lower == Int32.MinValue)
                {
                    i64 += (UInt64)(-1 * (lower + 1));
                }
                else
                {
                    i64 += (UInt64)(-upper);
                }
            }
            else
            {
                i64 += (UInt64)lower;
            }

            int result = i64.GetHashCode();

            return result;
        }

        /// <summary>
        /// Compares two instances for equality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if the respective Top, Left, Bottom, and Right fields are the same, false otherwise.
        /// </returns>
        public static
        bool
        operator ==(Rectangle first, Rectangle second)
        {
            bool result = first.Top == second.Top && first.Left == second.Left &&
             first.Bottom == second.Bottom && first.Right == second.Right;

            return result;
        }

        /// <summary>
        /// Compares two instances for inequality.
        /// </summary>
        /// <param name="first">
        /// The left side operand.
        /// </param>
        /// <param name="second">
        /// The right side operand.
        /// </param>
        /// <returns>
        /// true if any of the respective Top, Left, Bottom, and Right fields are not the same, false otherwise.
        /// </returns>
        /// <exception/>
        public static
        bool
        operator !=(Rectangle first, Rectangle second)
        {
            return !(first == second);
        }
    }

    /// <summary>
    /// Represents a character, a foregroundColor color, and background color.
    /// </summary>
    public
    struct BufferCell
    {
        #region DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting compatibility with Windows PowerShell

        private char character;
        private ConsoleColor foregroundColor;
        private ConsoleColor backgroundColor;
        private BufferCellType bufferCellType;

        #endregion

        /// <summary>
        /// Gets and sets the character value.
        /// </summary>
        public char Character
        {
            get { return character; }

            set { character = value; }
        }

        // we reuse System.ConsoleColor - it's in the core assembly, and I think it would be confusing to create another
        // essentially identical enum

        /// <summary>
        /// Gets and sets the foreground color.
        /// </summary>
        public ConsoleColor ForegroundColor
        {
            get { return foregroundColor; }

            set { foregroundColor = value; }
        }

        /// <summary>
        /// Gets and sets the background color.
        /// </summary>
        public ConsoleColor BackgroundColor
        {
            get { return backgroundColor; }

            set { backgroundColor = value; }
        }

        /// <summary>
        /// Gets and sets the type value.
        /// </summary>
        public BufferCellType BufferCellType
        {
            get { return bufferCellType; }

            set { bufferCellType = value; }
        }

        /// <summary>
        /// Initializes a new instance of the BufferCell class and defines the
        /// Character, ForegroundColor, BackgroundColor and Type values.
        /// </summary>
        /// <param name="character">
        /// The character in this BufferCell object
        /// </param>
        /// <param name="foreground">
        /// The foreground color of this BufferCell object