Class View

View is the base class for all views on the screen and represents a visible element that can render itself and contains zero or more nested views.
Inheritance
System.Object
Responder
View
Button
CheckBox
ComboBox
FrameView
HexView
Label
ListView
MenuBar
ProgressBar
RadioGroup
ScrollBarView
ScrollView
StatusBar
TextField
TextView
Toplevel
Implements
System.Collections.IEnumerable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Terminal.Gui
Assembly: Terminal.Gui.dll
Syntax
public class View : Responder, IEnumerable
Remarks

The View defines the base functionality for user interface elements in Terminal.Gui. Views can contain one or more subviews, can respond to user input and render themselves on the screen.

Views supports two layout styles: Absolute or Computed. The choice as to which layout style is used by the View is determined when the View is initizlied. To create a View using Absolute layout, call a constructor that takes a Rect parameter to specify the absolute position and size (the View.Frame)/. To create a View using Computed layout use a constructor that does not take a Rect parametr and set the X, Y, Width and Height properties on the view. Both approaches use coordinates that are relative to the container they are being added to.

To switch between Absolute and Computed layout, use the LayoutStyle property.

Computed layout is more flexible and supports dynamic console apps where controls adjust layout as the terminal resizes or other Views change size or position. The X, Y, Width and Height properties are Dim and Pos objects that dynamically update the position of a view. The X and Y properties are of type Pos and you can use either absolute positions, percentages or anchor points. The Width and Height properties are of type Dim and can use absolute position, percentages and anchors. These are useful as they will take care of repositioning views when view's frames are resized or if the terminal size changes.

Absolute layout requires specifying coordiantes and sizes of Views explicitly, and the View will typcialy stay in a fixed position and size. To change the position and size use the Frame property.

Subviews (child views) can be added to a View by calling the Add(View) method. The container of a View can be accessed with the SuperView property.

To flag a region of the View's Bounds to be redrawn call SetNeedsDisplay(Rect). To flag the entire view for redraw call SetNeedsDisplay().

Views have a ColorScheme property that defines the default colors that subviews should use for rendering. This ensures that the views fit in the context where they are being used, and allows for themes to be plugged in. For example, the default colors for windows and toplevels uses a blue background, while it uses a white background for dialog boxes and a red background for errors.

Subclasses should not rely on ColorScheme being set at construction time. If a ColorScheme is not set on a view, the view will inherit the value from its SuperView and the value might only be valid once a view has been added to a SuperView.

By using ColorScheme applications will work both in color as well as black and white displays.

Views that are focusable should implement the PositionCursor() to make sure that the cursor is placed in a location that makes sense. Unix terminals do not have a way of hiding the cursor, so it can be distracting to have the cursor left at the last focused view. So views should make sure that they place the cursor in a visually sensible place.

The LayoutSubviews() method is invoked when the size or layout of a view has changed. The default processing system will keep the size and dimensions for views that use the Absolute, and will recompute the frames for the vies that use Computed.

Constructors

View()

Initializes a new instance of Computed View class.
Declaration
public View()
Remarks
Use X, Y, Width, and Height properties to dynamically control the size and location of the view.

View(Rect)

Initializes a new instance of a Absolute View class with the absolute dimensions specified in the frame parameter.
Declaration
public View(Rect frame)
Parameters
Type Name Description
Rect frame The region covered by this view.
Remarks
This constructor intitalize a View with a LayoutStyle of Absolute. Use View() to initialize a View with LayoutStyle of Computed

Properties

Bounds

The bounds represent the View-relative rectangle used for this view; the area inside of the view.
Declaration
public Rect Bounds { get; set; }
Property Value
Type Description
Rect The bounds.
Remarks

Updates to the Bounds update the Frame, and has the same side effects as updating the Frame.

Because Bounds coordinates are relative to the upper-left corner of the View, the coordinates of the upper-left corner of the rectangle returned by this property are (0,0). Use this property to obtain the size and coordinates of the client area of the control for tasks such as drawing on the surface of the control.

ColorScheme

The color scheme for this view, if it is not defined, it returns the SuperView's color scheme.
Declaration
public ColorScheme ColorScheme { get; set; }
Property Value
Type Description
ColorScheme

Driver

Points to the current driver in use by the view, it is a convenience property for simplifying the development of new views.
Declaration
public static ConsoleDriver Driver { get; }
Property Value
Type Description
ConsoleDriver

Focused

Returns the currently focused view inside this view, or null if nothing is focused.
Declaration
public View Focused { get; }
Property Value
Type Description
View The focused.

Frame

Gets or sets the frame for the view. The frame is relative to the view's container (SuperView).
Declaration
public virtual Rect Frame { get; set; }
Property Value
Type Description
Rect The frame.
Remarks

Change the Frame when using the Absolute layout style to move or resize views.

Altering the Frame of a view will trigger the redrawing of the view as well as the redrawing of the affected regions of the SuperView.

HasFocus

Gets or sets a value indicating whether this Responder has focus.
Declaration
public override bool HasFocus { get; }
Property Value
Type Description
System.Boolean true if has focus; otherwise, false.
Overrides

Height

Gets or sets the height of the view. Only used whe LayoutStyle is Computed.
Declaration
public Dim Height { get; set; }
Property Value
Type Description
Dim The height.

Id

Gets or sets an identifier for the view;
Declaration
public ustring Id { get; set; }
Property Value
Type Description
NStack.ustring The identifier.
Remarks
The id should be unique across all Views that share a SuperView.

IsCurrentTop

Returns a value indicating if this View is currently on Top (Active)
Declaration
public bool IsCurrentTop { get; }
Property Value
Type Description
System.Boolean

LayoutStyle

Controls how the View's Frame is computed during the LayoutSubviews method, if the style is set to Absolute, LayoutSubviews does not change the Frame. If the style is Computed the Frame is updated using the X, Y, Width, and Height properties.
Declaration
public LayoutStyle LayoutStyle { get; set; }
Property Value
Type Description
LayoutStyle The layout style.

MostFocused

Returns the most focused view in the chain of subviews (the leaf view that has the focus).
Declaration
public View MostFocused { get; }
Property Value
Type Description
View The most focused.

Subviews

This returns a list of the subviews contained by this view.
Declaration
public IList<View> Subviews { get; }
Property Value
Type Description
System.Collections.Generic.IList<View> The subviews.

SuperView

Returns the container for this view, or null if this view has not been added to a container.
Declaration
public View SuperView { get; }
Property Value
Type Description
View The super view.

WantContinuousButtonPressed

Gets or sets a value indicating whether this View want continuous button pressed event.
Declaration
public virtual bool WantContinuousButtonPressed { get; set; }
Property Value
Type Description
System.Boolean

WantMousePositionReports

Gets or sets a value indicating whether this View wants mouse position reports.
Declaration
public virtual bool WantMousePositionReports { get; set; }
Property Value
Type Description
System.Boolean true if want mouse position reports; otherwise, false.

Width

Gets or sets the width of the view. Only used whe LayoutStyle is Computed.
Declaration
public Dim Width { get; set; }
Property Value
Type Description
Dim The width.
Remarks
If LayoutStyle is Absolute changing this property has no effect and its value is indeterminate.

X

Gets or sets the X position for the view (the column). Only used whe LayoutStyle is Computed.
Declaration
public Pos X { get; set; }
Property Value
Type Description
Pos The X Position.
Remarks
If LayoutStyle is Absolute changing this property has no effect and its value is indeterminate.

Y

Gets or sets the Y position for the view (the row). Only used whe LayoutStyle is Computed.
Declaration
public Pos Y { get; set; }
Property Value
Type Description
Pos The y position (line).
Remarks
If LayoutStyle is Absolute changing this property has no effect and its value is indeterminate.

Methods

Add(View)

Adds a subview (child) to this view.
Declaration
public virtual void Add(View view)
Parameters
Type Name Description
View view
Remarks
The Views that have been added to this view can be retrieved via the Subviews property. See also Remove(View) RemoveAll()

Add(View[])

Adds the specified views (children) to the view.
Declaration
public void Add(params View[] views)
Parameters
Type Name Description
View[] views Array of one or more views (can be optional parameter).
Remarks
The Views that have been added to this view can be retrieved via the Subviews property. See also Remove(View) RemoveAll()

AddRune(Int32, Int32, Rune)

Displays the specified character in the specified column and row of the View.
Declaration
public void AddRune(int col, int row, Rune ch)
Parameters
Type Name Description
System.Int32 col Column (view-relative).
System.Int32 row Row (view-relative).
System.Rune ch Ch.

BringSubviewForward(View)

Moves the subview backwards in the hierarchy, only one step
Declaration
public void BringSubviewForward(View subview)
Parameters
Type Name Description
View subview The subview to send backwards
Remarks
If you want to send the view all the way to the back use SendSubviewToBack.

BringSubviewToFront(View)

Brings the specified subview to the front so it is drawn on top of any other views.
Declaration
public void BringSubviewToFront(View subview)
Parameters
Type Name Description
View subview The subview to send to the front
Remarks
SendSubviewToBack(View).

ChildNeedsDisplay()

Indicates that any child views (in the Subviews list) need to be repainted.
Declaration
public void ChildNeedsDisplay()

Clear()

Clears the view region with the current color.
Declaration
public void Clear()
Remarks

This clears the entire region used by this view.

Clear(Rect)

Clears the specified region with the current color.
Declaration
public void Clear(Rect regionScreen)
Parameters
Type Name Description
Rect regionScreen The screen-relative region to clear.
Remarks

ClearNeedsDisplay()

Removes the SetNeedsDisplay() and the ChildNeedsDisplay() setting on this view.
Declaration
protected void ClearNeedsDisplay()

ClipToBounds()

Sets the ConsoleDriver's clip region to the current View's Bounds.
Declaration
public Rect ClipToBounds()
Returns
Type Description
Rect The existing driver's clip region, which can be then re-eapplied by setting Driver.Clip (Clip).
Remarks
Bounds is View-relative.

DrawFrame(Rect, Int32, Boolean)

Draws a frame in the current view, clipped by the boundary of this view
Declaration
public void DrawFrame(Rect region, int padding = 0, bool fill = false)
Parameters
Type Name Description
Rect region View-relative region for the frame to be drawn.
System.Int32 padding The padding to add around the outside of the drawn frame.
System.Boolean fill If set to true it fill will the contents.

DrawHotString(ustring, Boolean, ColorScheme)

Utility function to draw strings that contains a hotkey using a ColorScheme and the "focused" state.
Declaration
public void DrawHotString(ustring text, bool focused, ColorScheme scheme)
Parameters
Type Name Description
NStack.ustring text String to display, the underscoore before a letter flags the next letter as the hotkey.
System.Boolean focused If set to true this uses the focused colors from the color scheme, otherwise the regular ones.
ColorScheme scheme The color scheme to use.

DrawHotString(ustring, Attribute, Attribute)

Utility function to draw strings that contain a hotkey.
Declaration
public void DrawHotString(ustring text, Attribute hotColor, Attribute normalColor)
Parameters
Type Name Description
NStack.ustring text String to display, the underscoore before a letter flags the next letter as the hotkey.
Attribute hotColor Hot color.
Attribute normalColor Normal color.
Remarks
The hotkey is any character following an underscore ('_') character.

EnsureFocus()

Finds the first view in the hierarchy that wants to get the focus if nothing is currently focused, otherwise, it does nothing.
Declaration
public void EnsureFocus()

FocusFirst()

Focuses the first focusable subview if one exists.
Declaration
public void FocusFirst()

FocusLast()

Focuses the last focusable subview if one exists.
Declaration
public void FocusLast()

FocusNext()

Focuses the next view.
Declaration
public bool FocusNext()
Returns
Type Description
System.Boolean true, if next was focused, false otherwise.

FocusPrev()

Focuses the previous view.
Declaration
public bool FocusPrev()
Returns
Type Description
System.Boolean true, if previous was focused, false otherwise.

GetEnumerator()

Gets an enumerator that enumerates the subviews in this view.
Declaration
public IEnumerator GetEnumerator()
Returns
Type Description
System.Collections.IEnumerator The enumerator.

LayoutSubviews()

Invoked when a view starts executing or when the dimensions of the view have changed, for example in response to the container view or terminal resizing.
Declaration
public virtual void LayoutSubviews()
Remarks
Calls Terminal.Gui.View.OnLayoutComplete(Terminal.Gui.View.LayoutEventArgs) (which raises the LayoutComplete event) before it returns.

Move(Int32, Int32)

This moves the cursor to the specified column and row in the view.
Declaration
public void Move(int col, int row)
Parameters
Type Name Description
System.Int32 col Col (view-relative).
System.Int32 row Row (view-relative).

OnDrawContent(Rect)

Enables overrides to draw infinitely scrolled content and/or a background behind added controls.
Declaration
public virtual void OnDrawContent(Rect viewport)
Parameters
Type Name Description
Rect viewport The view-relative rectangle describing the currently visible viewport into the View
Remarks
This method will be called before any subviews added with Add(View) have been drawn.

OnEnter()

Method invoked when a view gets focus.
Declaration
public override bool OnEnter()
Returns
Type Description
System.Boolean true, if the event was handled, false otherwise.
Overrides

OnKeyDown(KeyEvent)

Declaration
public override bool OnKeyDown(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides

OnKeyUp(KeyEvent)

Declaration
public override bool OnKeyUp(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides

OnLeave()

Method invoked when a view loses focus.
Declaration
public override bool OnLeave()
Returns
Type Description
System.Boolean true, if the event was handled, false otherwise.
Overrides

OnMouseEnter(MouseEvent)

Method invoked when a mouse event is generated for the first time.
Declaration
public override bool OnMouseEnter(MouseEvent mouseEvent)
Parameters
Type Name Description
MouseEvent mouseEvent
Returns
Type Description
System.Boolean true, if the event was handled, false otherwise.
Overrides

OnMouseEvent(MouseEvent)

Method invoked when a mouse event is generated
Declaration
public virtual bool OnMouseEvent(MouseEvent mouseEvent)
Parameters
Type Name Description
MouseEvent mouseEvent
Returns
Type Description
System.Boolean true, if the event was handled, false otherwise.

OnMouseLeave(MouseEvent)

Method invoked when a mouse event is generated for the last time.
Declaration
public override bool OnMouseLeave(MouseEvent mouseEvent)
Parameters
Type Name Description
MouseEvent mouseEvent
Returns
Type Description
System.Boolean true, if the event was handled, false otherwise.
Overrides

PositionCursor()

Positions the cursor in the right position based on the currently focused view in the chain.
Declaration
public virtual void PositionCursor()

ProcessColdKey(KeyEvent)

This method can be overwritten by views that want to provide accelerator functionality (Alt-key for example), but without interefering with normal ProcessKey behavior.
Declaration
public override bool ProcessColdKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides
Remarks

After keys are sent to the subviews on the current view, all the view are processed and the key is passed to the views to allow some of them to process the keystroke as a cold-key.

This functionality is used, for example, by default buttons to act on the enter key. Processing this as a hot-key would prevent non-default buttons from consuming the enter keypress when they have the focus.

ProcessHotKey(KeyEvent)

This method can be overwritten by view that want to provide accelerator functionality (Alt-key for example).
Declaration
public override bool ProcessHotKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent
Returns
Type Description
System.Boolean
Overrides
Remarks

Before keys are sent to the subview on the current view, all the views are processed and the key is passed to the widgets to allow some of them to process the keystroke as a hot-key.

For example, if you implement a button that has a hotkey ok "o", you would catch the combination Alt-o here. If the event is caught, you must return true to stop the keystroke from being dispatched to other views.

ProcessKey(KeyEvent)

If the view is focused, gives the view a chance to process the keystroke.
Declaration
public override bool ProcessKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
System.Boolean
Overrides
Remarks

Views can override this method if they are interested in processing the given keystroke. If they consume the keystroke, they must return true to stop the keystroke from being processed by other widgets or consumed by the widget engine. If they return false, the keystroke will be passed using the ProcessColdKey method to other views to process.

The View implementation does nothing but return false, so it is not necessary to call base.ProcessKey if you derive directly from View, but you should if you derive other View subclasses.

Redraw(Rect)

Redraws this view and its subviews; only redraws the views that have been flagged for a re-display.
Declaration
public virtual void Redraw(Rect bounds)
Parameters
Type Name Description
Rect bounds The bounds (view-relative region) to redraw.
Remarks

Always use Bounds (view-relative) when calling Redraw(Rect), NOT Frame (superview-relative).

Views should set the color that they want to use on entry, as otherwise this will inherit the last color that was set globaly on the driver.

Overrides of Redraw(Rect) must ensure they do not set Driver.Clip to a clip region larger than the region parameter.

Remove(View)

Removes a subview added via Add(View) or Add(View[]) from this View.
Declaration
public virtual void Remove(View view)
Parameters
Type Name Description
View view
Remarks

RemoveAll()

Removes all subviews (children) added via Add(View) or Add(View[]) from this View.
Declaration
public virtual void RemoveAll()

ScreenToView(Int32, Int32)

Converts a point from screen-relative coordinates to view-relative coordinates.
Declaration
public Point ScreenToView(int x, int y)
Parameters
Type Name Description
System.Int32 x X screen-coordinate point.
System.Int32 y Y screen-coordinate point.
Returns
Type Description
Point The mapped point.

SendSubviewBackwards(View)

Moves the subview backwards in the hierarchy, only one step
Declaration
public void SendSubviewBackwards(View subview)
Parameters
Type Name Description
View subview The subview to send backwards
Remarks
If you want to send the view all the way to the back use SendSubviewToBack.

SendSubviewToBack(View)

Sends the specified subview to the front so it is the first view drawn
Declaration
public void SendSubviewToBack(View subview)
Parameters
Type Name Description
View subview The subview to send to the front
Remarks
BringSubviewToFront(View).

SetClip(Rect)

Sets the clip region to the specified view-relative region.
Declaration
public Rect SetClip(Rect region)
Parameters
Type Name Description
Rect region View-relative clip region.
Returns
Type Description
Rect The previous screen-relative clip region.

SetFocus(View)

Causes the specified subview to have focus.
Declaration
public void SetFocus(View view)
Parameters
Type Name Description
View view View.

SetNeedsDisplay()

Sets a flag indicating this view needs to be redisplayed because its state has changed.
Declaration
public void SetNeedsDisplay()

SetNeedsDisplay(Rect)

Flags the view-relative region on this View as needing to be repainted.
Declaration
public void SetNeedsDisplay(Rect region)
Parameters
Type Name Description
Rect region The view-relative region that must be flagged for repaint.

ToString()

Pretty prints the View
Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

Events

DrawContent

Event invoked when the content area of the View is to be drawn.
Declaration
public event EventHandler<Rect> DrawContent
Event Type
Type Description
System.EventHandler<Rect>
Remarks

Will be invoked before any subviews added with Add(View) have been drawn.

Rect provides the view-relative rectangle describing the currently visible viewport into the View.

Enter

Event fired when the view gets focus.
Declaration
public event EventHandler<View.FocusEventArgs> Enter
Event Type
Type Description
System.EventHandler<View.FocusEventArgs>

KeyDown

Invoked when a key is pressed
Declaration
public event EventHandler<View.KeyEventEventArgs> KeyDown
Event Type
Type Description
System.EventHandler<View.KeyEventEventArgs>

KeyPress

Invoked when a character key is pressed and occurs after the key up event.
Declaration
public event EventHandler<View.KeyEventEventArgs> KeyPress
Event Type
Type Description
System.EventHandler<View.KeyEventEventArgs>

KeyUp

Invoked when a key is released
Declaration
public event EventHandler<View.KeyEventEventArgs> KeyUp
Event Type
Type Description
System.EventHandler<View.KeyEventEventArgs>

LayoutComplete

Fired after the Views's LayoutSubviews() method has completed.
Declaration
public event EventHandler<View.LayoutEventArgs> LayoutComplete
Event Type
Type Description
System.EventHandler<View.LayoutEventArgs>
Remarks
Subscribe to this event to perform tasks when the View has been resized or the layout has otherwise changed.

Leave

Event fired when the view looses focus.
Declaration
public event EventHandler<View.FocusEventArgs> Leave
Event Type
Type Description
System.EventHandler<View.FocusEventArgs>

MouseClick

Event fired when a mouse event is generated.
Declaration
public event EventHandler<View.MouseEventEventArgs> MouseClick
Event Type
Type Description
System.EventHandler<View.MouseEventEventArgs>

MouseEnter

Event fired when the view receives the mouse event for the first time.
Declaration
public event EventHandler<View.MouseEventEventArgs> MouseEnter
Event Type
Type Description
System.EventHandler<View.MouseEventEventArgs>

MouseLeave

Event fired when the view receives a mouse event for the last time.
Declaration
public event EventHandler<View.MouseEventEventArgs> MouseLeave
Event Type
Type Description
System.EventHandler<View.MouseEventEventArgs>

Implements

System.Collections.IEnumerable