How to Implement a Raw User Interface

This section shows how to implement a raw user interface class that derives from the PSHostRawUserInterface class. This class provides low-level host functionality, such as read and write actions, to support character-mode interaction with the user. The following host user interface class can be used as a template for creating your own custom host.

To implement a raw user interface class

  1. Define the raw user interface class that derives from the PSHostRawUserInterface class. In the Windows PowerShell samples, this class is implemented in a myrawuserinterface.cs file.

    internal class MyRawUserInterface : PSHostRawUserInterface
    
    
  2. Implement the BackgroundColor property to specify the background color of the displayed text.

    public override ConsoleColor BackgroundColor
    {
      get { return Console.BackgroundColor; }
      set { Console.BackgroundColor = value; }
    }
    
    
  3. Implement the BufferSize property to specify the size of the screen buffer that is used by the host.

    public override Size BufferSize
    {
      get { return new Size(Console.BufferWidth, Console.BufferHeight); }
      set { Console.SetBufferSize(value.Width, value.Height); }
    }
    
    
  4. Implement the CursorPosition property to specify the position of the cursor in the screen buffer.

    public override Coordinates CursorPosition
    {
      get { throw new NotImplementedException(
                 "The method or operation is not implemented."); }
      set { throw new NotImplementedException(
                 "The method or operation is not implemented."); }
    }
    
    
  5. Implement the CursorSize property to specify the size of the displayed cursor.

    public override int CursorSize
    {
      get { return Console.CursorSize; }
      set { Console.CursorSize = value; }
    }
    
    
  6. Implement the ForegroundColor property to specify the foreground color of the displayed text.

    public override ConsoleColor ForegroundColor
    {
      get { return Console.ForegroundColor; }
      set { Console.ForegroundColor = value; }
    }
    
    
  7. Implement the KeyAvailable property to detect when a key is pressed.

    public override bool KeyAvailable
    {
      get { return Console.KeyAvailable; }
    }
    
    
  8. Implement the MaxPhysicalWindowSize property to determine the maximum physical size of the displayed window.

    public override Size MaxPhysicalWindowSize
    {
      get { return new Size(Console.LargestWindowWidth, Console.LargestWindowHeight); }
    }
    
    
  9. Implement the MaxWindowSize property to determine the largest window that can be displayed.

    public override Size MaxWindowSize
    {
      get { return new Size(Console.LargestWindowWidth, Console.LargestWindowHeight); }
    }
    
    
  10. Implement the WindowPosition property to determine the location of the displayed window.

    public override Coordinates WindowPosition
    {
      get { return new Coordinates(Console.WindowLeft, Console.WindowTop); }
      set { Console.SetWindowPosition(value.X, value.Y); }
    }
    
    
  11. Implement the WindowSize property to determine the size of the displayed window.

    public override Size WindowSize
    {
      get { return new Size(Console.WindowWidth, Console.WindowHeight); }
      set { Console.SetWindowSize(value.Width, value.Height); }
    }
    
    
  12. Implement the WindowTitle property to specify the title of the displayed window.

    public override string WindowTitle
    {
      get { return Console.Title; }
      set { Console.Title = value; }
    }
    
    
  13. Implement the FlushInputBuffer method to clear the input buffer of the host.

    public override void FlushInputBuffer()
    {
    }
    
    
  14. Implement the GetBufferContents method to return a rectangular region of the screen buffer.

  15. Implement the ReadKey method to record a pressed, released, or pressed and released keystroke from the user, blocking processing until a keystroke is pressed that matches the specified keystroke options. In this example, this functionality is not needed so the method throws a NotImplementException exception.

    public override KeyInfo ReadKey(ReadKeyOptions options)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }
    
    
  16. Implement the ScrollBufferContents method to crop a region of the screen buffer. In this example, this functionality is not needed so the method throws a NotImplementException exception.

    public override void ScrollBufferContents(Rectangle source, Coordinates destination, Rectangle clip, BufferCell fill)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }
    
    
  17. Implement the System.Management.Automation.Host.PSHostRawUserInterface.SetBufferContents(System.Management.Automation.Host.Coordinates,System.Management.Automation.Host.BufferCell[0:,0:]) method to copy an array of buffer cells into the screen buffer at a specified location. In this example, this functionality is not needed so the method throws a NotImplementException exception.

    public override void SetBufferContents(Coordinates origin, 
                                           BufferCell[,] contents)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }
    
    
  18. Implement the System.Management.Automation.Host.PSHostRawUserInterface.SetBufferContents(System.Management.Automation.Host.Rectangle,System.Management.Automation.Host.BufferCell) method to copy a given character, foreground color, and background color to a region of the screen buffer. In this example, this functionality is not needed so the method throws a NotImplementException exception.

    public override void SetBufferContents(Rectangle rectangle, BufferCell fill)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }
    
    

The following methods are also defined in the base interface and can be used when implementing your own raw user interface.

Example

The following code is the implementation of the PSHostRawUserInterface class described in the previous procedure. For an example of how this interface is used in a host application, see Host02 Sample.

namespace Microsoft.Samples.PowerShell.Host
{
  using System;
  using System.Management.Automation.Host;
    
  /// <summary>
  /// A sample implementation of the PSHostRawUserInterface for console
  /// applications. Members of this class that easily map to the .NET 
  /// console class are implemented. More complex methods are not 
  /// implemented and throw a NotImplementedException exception.
  /// </summary>
  internal class MyRawUserInterface : PSHostRawUserInterface
  {
    /// <summary>
    /// Gets or sets the background color of the displayed text.
    /// This maps to the corresponding Console.Background property.
    /// </summary>
    public override ConsoleColor BackgroundColor
    {
      get { return Console.BackgroundColor; }
      set { Console.BackgroundColor = value; }
    }

    /// <summary>
    /// Gets or sets the size of the host buffer. In this example the 
    /// buffer size is adapted from the Console buffer size members.
    /// </summary>
    public override Size BufferSize
    {
      get { return new Size(Console.BufferWidth, Console.BufferHeight); }
      set { Console.SetBufferSize(value.Width, value.Height); }
    }

    /// <summary>
    /// Gets or sets the cursor position. In this example this 
    /// functionality is not needed so the property throws a 
    /// NotImplementException exception.
    /// </summary>
    public override Coordinates CursorPosition
    {
      get { throw new NotImplementedException(
                 "The method or operation is not implemented."); }
      set { throw new NotImplementedException(
                 "The method or operation is not implemented."); }
    }

    /// <summary>
    /// Gets or sets the size of the displayed cursor. In this example 
    /// the cursor size is taken directly from the Console.CursorSize 
    /// property.
    /// </summary>
    public override int CursorSize
    {
      get { return Console.CursorSize; }
      set { Console.CursorSize = value; }
    }

    /// <summary>
    /// Gets or sets the foreground color of the displayed text.
    /// This maps to the corresponding Console.ForgroundColor property.
    /// </summary>
    public override ConsoleColor ForegroundColor
    {
      get { return Console.ForegroundColor; }
      set { Console.ForegroundColor = value; }
    }

    /// <summary>
    /// Gets a value indicating whether the user has pressed a key. This maps   
    /// to the corresponding Console.KeyAvailable property.
    /// </summary>
    public override bool KeyAvailable
    {
      get { return Console.KeyAvailable; }
    }

    /// <summary>
    /// Gets the dimensions of the largest window that could be 
    /// rendered in the current display, if the buffer was at the least 
    /// that large. This example uses the Console.LargestWindowWidth and 
    /// Console.LargestWindowHeight properties to determine the returned 
    /// value of this property.
    /// </summary>
    public override Size MaxPhysicalWindowSize
    {
      get { return new Size(Console.LargestWindowWidth, Console.LargestWindowHeight); }
    }

    /// <summary>
    /// Gets the dimentions of the largest window size that can be 
    /// displayed. This example uses the Console.LargestWindowWidth and 
    /// console.LargestWindowHeight properties to determine the returned 
    /// value of this property.
    /// </summary>
    public override Size MaxWindowSize
    {
      get { return new Size(Console.LargestWindowWidth, Console.LargestWindowHeight); }
    }

    /// <summary>
    /// Gets or sets the position of the displayed window. This example 
    /// uses the Console window position APIs to determine the returned 
    /// value of this property.
    /// </summary>
    public override Coordinates WindowPosition
    {
      get { return new Coordinates(Console.WindowLeft, Console.WindowTop); }
      set { Console.SetWindowPosition(value.X, value.Y); }
    }

    /// <summary>
    /// Gets or sets the size of the displayed window. This example 
    /// uses the corresponding Console window size APIs to determine the  
    /// returned value of this property.
    /// </summary>
    public override Size WindowSize
    {
      get { return new Size(Console.WindowWidth, Console.WindowHeight); }
      set { Console.SetWindowSize(value.Width, value.Height); }
    }

    /// <summary>
    /// Gets or sets the title of the displayed window. The example 
    /// maps the Console.Title property to the value of this property.
    /// </summary>
    public override string WindowTitle
    {
      get { return Console.Title; }
      set { Console.Title = value; }
    }

    /// <summary>
    /// This API resets the input buffer. In this example this 
    /// functionality is not needed so the method returns nothing.
    /// </summary>
    public override void FlushInputBuffer()
    {
    }

    /// <summary>
    /// This API returns a rectangular region of the screen buffer. In 
    /// this example this functionality is not needed so the method throws 
    /// a NotImplementException exception.
    /// </summary>
    /// <param name="rectangle">Defines the size of the rectangle.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override BufferCell[,] GetBufferContents(Rectangle rectangle)
    {
      throw new NotImplementedException(
               "The method or operation is not implemented.");
    }

    /// <summary>
    /// This API reads a pressed, released, or pressed and released keystroke 
    /// from the keyboard device, blocking processing until a keystroke is 
    /// typed that matches the specified keystroke options. In this example 
    /// this functionality is not needed so the method throws a
    /// NotImplementException exception.
    /// </summary>
    /// <param name="options">Options, such as IncludeKeyDown,  used when 
    /// reading the keyboard.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override KeyInfo ReadKey(ReadKeyOptions options)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }

    /// <summary>
    /// This API crops a region of the screen buffer. In this example 
    /// this functionality is not needed so the method throws a
    /// NotImplementException exception.
    /// </summary>
    /// <param name="source">The region of the screen to be scrolled.</param>
    /// <param name="destination">The region of the screen to receive the 
    /// source region contents.</param>
    /// <param name="clip">The region of the screen to include in the operation.</param>
    /// <param name="fill">The character and attributes to be used to fill all cell.</param>
    public override void ScrollBufferContents(Rectangle source, Coordinates destination, Rectangle clip, BufferCell fill)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }

    /// <summary>
    /// This method copies an array of buffer cells into the screen buffer 
    /// at a specified location. In this example this functionality is 
    /// not needed so the method throws a NotImplementedException exception.
    /// </summary>
    /// <param name="origin">The parameter is not used.</param>
    /// <param name="contents">The parameter is not used.</param>
    public override void SetBufferContents(Coordinates origin, 
                                           BufferCell[,] contents)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }

    /// <summary>
    /// This method copies a given character, foreground color, and background 
    /// color to a region of the screen buffer. In this example this 
    /// functionality is not needed so the method throws a
    /// NotImplementException exception./// </summary>
    /// <param name="rectangle">Defines the area to be filled. </param>
    /// <param name="fill">Defines the fill character.</param>
    public override void SetBufferContents(Rectangle rectangle, BufferCell fill)
    {
      throw new NotImplementedException(
                "The method or operation is not implemented.");
    }
  }
}



Show:
© 2014 Microsoft