MshHostRawUserInterface.cs

/********************************************************************++
Copyright (c) Microsoft Corporation.  All rights reserved.
--********************************************************************/


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
    {
        // DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting
        private int x;
        private int y;

        /// <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="System.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.Format(CultureInfo.InvariantCulture, "{0},{1}", X, Y);
        }



        /// <summary>
        /// 
        /// Overrides <see cref="System.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="System.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
    {
        // DO NOT REMOVE OR RENAME THESE FIELDS - it will break remoting
        private int width;
        private int height;

        /// <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="System.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.Format(CultureInfo.InvariantCulture, "{0},{1}", Width, Height);
        }

        /// <summary>
        /// 
        /// Overrides <see cref="System.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="System.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
    {
        /// <summary>
        /// 
        /// Gets and set device-independent key
        /// 
        /// </summary>

        public int VirtualKeyCode { get; set; }


        /// <summary>
        /// Gets and set unicode Character of the key
        /// </summary>

        public char Character { get; set; }


        /// <summary>
        /// State of the control keys.
        /// </summary>

        public ControlKeyStates ControlKeyState { get; set; }


        /// <summary>
        /// Gets and set the status of whether this instance is generated by a key pressed or released
        /// </summary>

        public bool KeyDown { get; set; }

        /// <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
        )
        {
            VirtualKeyCode = virtualKeyCode;
            Character = ch;
            ControlKeyState = controlKeyState;
            KeyDown = keyDown;
        }

        /// <summary>
        /// 
        /// Overloads <see cref="System.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.Format(CultureInfo.InvariantCulture, "{0},{1},{2},{3}", VirtualKeyCode, Character, ControlKeyState, KeyDown);
        }
        /// <summary>
        /// 
        /// Overrides <see cref="System.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="System.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
    {
        /// <summary>
        /// 
        /// Gets and sets the left side of the rectangle
        /// 
        /// </summary>

        public int Left { get; set; }


        /// <summary>
        /// 
        /// Gets and sets the top of the rectangle
        /// 
        /// </summary>

        public int Top { get; set; }


        /// <summary>
        /// 
        /// Gets and sets the right side of the rectangle 
        /// 
        /// </summary>

        public int Right { get; set; }


        /// <summary>
        /// 
        /// Gets and sets the bottom of the rectanngle
        /// 
        /// </summary>

        public int Bottom { get; set; }


        /// <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 rectanngle
        /// 
        /// </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("right", MshHostRawUserInterfaceStrings.LessThanErrorTemplate, "right", "left");
            }
            if (bottom < top)
            {
                // "bottom" and "top" are not localizable
                throw PSTraceSource.NewArgumentException("bottom", MshHostRawUserInterfaceStrings.LessThanErrorTemplate, "bottom", "top");
            }

            Left = left;
            Top = top;
            Right = right;
            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="System.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.Format(CultureInfo.InvariantCulture, "{0},{1} ; {2},{3}", Left, Top, Right, Bottom);
        }

        /// <summary>
        /// 
        /// Overrides <see cref="System.Object.Equals(object)"/>
        /// 
        /// </summary>
        /// <param name="obj">
        /// 
        /// object to be compared for equality.
        /// 
        /// </param>