Class View

Namespace: Terminal.Gui

Assembly: Terminal.Gui.dll

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, called SubViews. View provides basic functionality for layout, positioning, and drawing. In addition, View provides keyboard and mouse event handling.

public class View : Responder, IDisposable, ISupportInitializeNotification, ISupportInitialize

Inheritance: object

Responder

View

Implements: IDisposable

ISupportInitializeNotification

ISupportInitialize

Inherited Members: Responder.Dispose()

Responder.Disposing

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Remarks

Term	Definition
SubView	A View that is contained in another view and will be rendered as part of the containing view's ContentArea. SubViews are added to another view via the Add(View)` method. A View may only be a SubView of a single View.
SuperView	The View that is a container for SubViews.

Focus is a concept that is used to describe which View is currently receiving user input. Only Views that are Enabled, Visible, and CanFocus will receive focus.

Views that are focusable should override PositionCursor() to make sure that the cursor is placed in a location that makes sense. Some 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 default implementation of PositionCursor() will place the cursor at either the hotkey (if defined) or 0,0.

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.

View supports two layout styles: Absolute or Computed. The style is determined by the values of X, Y, Width, and Height. If any of these is set to non-absolute Pos or Dim object, then the layout style is Computed. Otherwise it is Absolute .

To create a View using Absolute layout, call a constructor that takes a Rect parameter to specify the absolute position and size or simply set Frame). To create a View using Computed layout use a constructor that does not take a Rect parameter and set the X, Y, Width and Height properties on the view to non-absolute values. Both approaches use coordinates that are relative to the Viewport of the SuperView the View is added to.

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 adornments are resized or if the terminal size changes.

Absolute layout requires specifying coordinates and sizes of Views explicitly, and the View will typically 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 Viewport to be redrawn call SetNeedsDisplay(Rectangle) . To flag the entire view for redraw call SetNeedsDisplay().

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 Adornments for the views that use Computed.

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 can also opt-in to more sophisticated initialization by implementing overrides to BeginInit() and EndInit() which will be called when the view is added to a SuperView.

If first-run-only initialization is preferred, overrides to ISupportInitializeNotification can be implemented, in which case the ISupportInitialize methods will only be called if IsInitialized is false. This allows proper View inheritance hierarchies to override base class layout code optimally by doing so only on first run, instead of on every run.

See for an overview of View keyboard handling.

///

Constructors

View(): Initializes a new instance of View.

Properties

Arrangement: Gets or sets the user actions that are enabled for the view within it's SuperView.

Border: The Adornment that offsets the Viewport from the Margin. The Border provides the space for a visual border (drawn using line-drawing glyphs) and the Title. The Border expands inward; in other words if Border.Thickness.Top == 2 the border and title will take up the first row and the second row will be filled with spaces.

BorderStyle: Gets or sets whether the view has a one row/col thick border.

CanFocus: Gets or sets a value indicating whether this View can focus.

ClearOnVisibleFalse: Gets or sets whether a view is cleared if the Visible property is false.

ColorScheme: The color scheme for this view, if it is not defined, it returns the SuperView's color scheme.

ContentSize: Gets or sets the size of the View's content. If null, the value will be the same as the size of Viewport, and Viewport.Location will always be 0, 0.

CursorVisibility: Gets or sets the cursor style to be used when the view is focused. The default is Invisible.

Data: Gets or sets arbitrary data for the view.

Diagnostics: Flags to enable/disable View diagnostics.

Driver: Points to the current driver in use by the view, it is a convenience property for simplifying the development of new views.

Enabled: Gets or sets a value indicating whether this Responder can respond to user interaction.

Focused: Returns the currently focused Subview inside this view, or null if nothing is focused.

Frame: Gets or sets the absolute location and dimension of the view.

HasFocus

Height: Gets or sets the height dimension of the view.

HighlightStyle: Gets or sets whether the View will be highlighted visually while the mouse button is pressed.

HotKey

Gets or sets the hot key defined for this view. Pressing the hot key on the keyboard while this view has focus will invoke the HotKey and Accept commands. HotKey causes the view to be focused and Accept does nothing. By default, the HotKey is automatically set to the first character of Text that is prefixed with with HotKeySpecifier.

A HotKey is a keypress that selects a visible UI item. For selecting items across View`s (e.g.a Button in a Dialog) the keypress must include the WithAlt modifier. For selecting items within a View that are not Views themselves, the keypress can be key without the Alt modifier. For example, in a Dialog, a Button with the text of "_Text" can be selected with Alt-T. Or, in a Menu with "_File _Edit", Alt-F will select (show) the "_File" menu. If the "_File" menu has a sub-menu of "_New" `Alt-N` or `N` will ONLY select the "_New" sub-menu if the "_File" menu is already opened.

HotKeySpecifier: Gets or sets the specifier character for the hot key (e.g. '_'). Set to '\xffff' to disable automatic hot key setting support for this View instance. The default is '\xffff'.

Id: Gets or sets an identifier for the view;

IsAdded: Indicates whether the view was added to SuperView.

IsCurrentTop: Returns a value indicating if this View is currently on Top (Active)

IsInitialized: Get or sets if the View has been initialized (via BeginInit() and EndInit()).

KeyBindings: Gets the key bindings for this view.

LayoutStyle: Controls how the View's Frame is computed during LayoutSubviews(). 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.

LineCanvas: The canvas that any line drawing that is to be shared by subviews of this view should add lines to.

Margin: The Adornment that enables separation of a View from other SubViews of the same SuperView. The margin offsets the Viewport from the Frame.

MostFocused: Returns the most focused Subview in the chain of subviews (the leaf view that has the focus).

NeedsDisplay: Gets or sets whether the view needs to be redrawn.

Padding: The Adornment inside of the view that offsets the Viewport from the Border.

PreserveTrailingSpaces: Gets or sets whether trailing spaces at the end of word-wrapped lines are preserved or not when WordWrap is enabled. If true trailing spaces at the end of wrapped lines will be removed when Text is formatted for display. The default is false.

SubViewNeedsDisplay: Gets whether any Subviews need to be redrawn.

Subviews: This returns a list of the subviews contained by this view.

SuperView: Returns the container for this view, or null if this view has not been added to a container.

SuperViewRendersLineCanvas: Gets or sets whether this View will use it's SuperView's LineCanvas for rendering any lines. If true the rendering of any borders drawn by this Frame will be done by its parent's SuperView. If false (the default) this View's OnDrawAdornments() method will be called to render the borders.

TabIndex: Indicates the index of the current View from the TabIndexes list. See also: TabStop.

TabIndexes: Gets a list of the subviews that are TabStops.

TabStop: Gets or sets whether the view is a stop-point for keyboard navigation of focus. Will be true only if the CanFocus is also true. Set to false to prevent the view from being a stop-point for keyboard navigation.

Text: The text displayed by the View.

TextAlignment: Gets or sets how the View's Text is aligned horizontally when drawn. Changing this property will redisplay the View.

TextDirection: Gets or sets the direction of the View's Text. Changing this property will redisplay the View.

TextFormatter: Gets or sets the TextFormatter used to format Text.

Title: The title to be displayed for this View. The title will be displayed if Border. Top is greater than 0. The title can be used to set the HotKey for the view by prefixing character with HotKeySpecifier (e.g. "T_itle").

ValidatePosDim: Gets or sets whether validation of Pos and Dim occurs.

VerticalTextAlignment: Gets or sets how the View's Text is aligned vertically when drawn. Changing this property will redisplay the View.

Viewport: Gets or sets the rectangle describing the portion of the View's content that is visible to the user. The viewport Location is relative to the top-left corner of the inner rectangle of Padding. If the viewport Size is the same as ContentSize, or ContentSize is null the Location will be 0, 0.

ViewportSettings: Gets or sets how scrolling the Viewport on the View's Content Area is handled.

Visible: Gets or sets a value indicating whether this Responder and all its child controls are displayed.

WantContinuousButtonPressed: Gets or sets whether the View wants continuous button pressed events.

WantMousePositionReports: Gets or sets whether the View wants mouse position reports.

Width: Gets or sets the width dimension of the view.

X: Gets or sets the X position for the view (the column).

Y: Gets or sets the Y position for the view (the row).

Methods

Add(View): Adds a subview (child) to this view.

Add(params View[]): Adds the specified views (children) to the view.

AddCommand(Command, Func<bool?>)

Sets the function that will be invoked for a Command. Views should call AddCommand(Command, Func<bool?>) for each command they support.

If AddCommand(Command, Func<bool?>) has already been called for commandf will replace the old one.

AddKeyBindingsForHotKey(Key, Key): Adds key bindings for the specified HotKey. Useful for views that contain multiple items that each have their own HotKey such as RadioGroup.

AddRune(int, int, Rune): Draws the specified character in the specified viewport-relative column and row of the View.

BeginInit(): Signals the View that initialization is starting. See ISupportInitialize.

BringSubviewForward(View): Moves the subview backwards in the hierarchy, only one step

BringSubviewToFront(View): Brings the specified subview to the front so it is drawn on top of any other views.

Clear(): Clears Viewport with the normal background.

ClearLayoutNeeded(): Indicates that the view does not need to be laid out.

ClearNeedsDisplay(): Clears NeedsDisplay and SubViewNeedsDisplay.

Contains(in Point): Indicates whether the specified SuperView-relative coordinates are within the View's Frame.

ContentToScreen(in Point): Converts a Content-relative location to a Screen-relative location.

Dispose(bool): Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Draw(): Draws the view. Causes the following virtual methods to be called (along with their related events): OnDrawContent(Rectangle), OnDrawContentComplete(Rectangle).

DrawHotString(string, bool, ColorScheme): Utility function to draw strings that contains a hotkey using a ColorScheme and the "focused" state.

DrawHotString(string, Attribute, Attribute): Utility function to draw strings that contain a hotkey.

EndInit(): Signals the View that initialization is ending. See ISupportInitialize.

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

FillRect(Rectangle, Color?): Fills the specified Viewport-relative rectangle with the specified color.

FocusFirst(): Focuses the first focusable subview if one exists.

FocusLast(): Focuses the last focusable subview if one exists.

FocusNext(): Focuses the next view.

FocusPrev(): Focuses the previous view.

FrameToScreen(): Gets the Frame with a screen-relative location.

GetAdornmentsThickness(): Gets the thickness describing the sum of the Adornments' thicknesses.

GetFocusColor(): Determines the current ColorScheme based on the Enabled value.

GetHotNormalColor(): Determines the current ColorScheme based on the Enabled value.

GetNormalColor(): Determines the current ColorScheme based on the Enabled value.

GetSupportedCommands(): Returns all commands that are supported by this View.

GetTopSuperView(View, View): Get the top superview of a given View.

GetViewportOffsetFromFrame(): Helper to get the X and Y offset of the Viewport from the Frame. This is the sum of the Left and Top properties of Margin, Border and Padding.

InvokeCommand(Command): Invokes the specified command.

InvokeCommands(Command[]): Invokes the specified commands.

InvokeKeyBindings(Key)

Invokes any binding that is registered on this View and matches the key

See for an overview of Terminal.Gui keyboard APIs.

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.

Move(int, int): Moves the drawing cursor to the specified Viewport-relative location in the view.

NewKeyDownEvent(Key): If the view is enabled, processes a new key down event and returns true if the event was handled.

NewKeyUpEvent(Key): If the view is enabled, processes a new key up event and returns true if the event was handled. Called before NewKeyDownEvent(Key).

NewMouseEvent(MouseEvent): Processes a MouseEvent. This method is called by OnMouseEvent(MouseEvent) when a mouse event occurs.

OnAccept(): Called when the Accept command is invoked. Fires the Accept event.

OnAdded(SuperViewChangedEventArgs): Method invoked when a subview is being added to this view.

OnCanFocusChanged(): Method invoked when the CanFocus property from a view is changed.

OnContentSizeChanged(SizeChangedEventArgs): Called when ContentSize changes. Invokes the ContentSizeChanged event.

OnDrawAdornments(): Prepares LineCanvas. If SuperViewRendersLineCanvas is true, only the LineCanvas of this view's subviews will be rendered. If SuperViewRendersLineCanvas is false (the default), this method will cause the LineCanvas be prepared to be rendered.

OnDrawContent(Rectangle): Draws the view's content, including Subviews.

OnDrawContentComplete(Rectangle): Called after OnDrawContent(Rectangle) to enable overrides.

OnEnabledChanged(): Method invoked when the Enabled property from a view is changed.

OnEnter(View): Called when a view gets focus.

OnHighlight(HighlightStyle): Called when the view is to be highlighted.

OnInvokingKeyBindings(Key): Low-level API called when a user presses a key; invokes any key bindings set on the view. This is called during NewKeyDownEvent(Key) after OnKeyDown(Key) has returned.

OnKeyDown(Key): Low-level API called when the user presses a key, allowing a view to pre-process the key down event. This is called from NewKeyDownEvent(Key) before OnInvokingKeyBindings(Key).

OnKeyUp(Key): Method invoked when a key is released. This method is called from NewKeyUpEvent(Key).

OnLeave(View): Method invoked when a view loses focus.

OnMouseClick(MouseEventEventArgs): Invokes the MouseClick event.

OnMouseEnter(MouseEvent): Called by NewMouseEvent(MouseEvent) when the mouse enters Viewport. The view will then receive mouse events until OnMouseLeave(MouseEvent) is called indicating the mouse has left the view.

OnMouseEvent(MouseEvent): Called when a mouse event occurs within the view's Viewport.

OnMouseLeave(MouseEvent): Called by NewMouseEvent(MouseEvent) when a mouse leaves Viewport. The view will no longer receive mouse events.

OnProcessKeyDown(Key): Low-level API called when the user presses a key, allowing views do things during key down events. This is called from NewKeyDownEvent(Key) after OnInvokingKeyBindings(Key).

OnRemoved(SuperViewChangedEventArgs): Method invoked when a subview is being removed from this view.

OnRenderLineCanvas(): Renders LineCanvas. If SuperViewRendersLineCanvas is true, only the LineCanvas of this view's subviews will be rendered. If SuperViewRendersLineCanvas is false (the default), this method will cause the LineCanvas to be rendered.

OnTextChanged(string, string): Called when the Text has changed. Fires the TextChanged event.

OnTitleChanged(string, string): Called when the Title has been changed. Invokes the TitleChanged event.

OnTitleChanging(string, string): Called before the Title changes. Invokes the TitleChanging event, which can be cancelled.

OnViewportChanged(DrawEventArgs): Called when the Viewport changes. Invokes the ViewportChanged event.

OnVisibleChanged(): Method invoked when the Visible property from a view is changed.

PositionCursor(): Positions the cursor in the right position based on the currently focused view in the chain.

Remove(View): Removes a subview added via Add(View) or Add(params View[]) from this View.

RemoveAll(): Removes all subviews (children) added via Add(View) or Add(params View[]) from this View.

ScreenToContent(in Point): Converts a Screen-relative coordinate to a Content-relative coordinate.

ScreenToFrame(in Point): Converts a screen-relative coordinate to a Frame-relative coordinate. Frame-relative means relative to the View's SuperView's Viewport.

ScreenToViewport(in Point): Converts a screen-relative coordinate to a Viewport-relative coordinate.

ScrollHorizontal(int): Scrolls the view horizontally by the specified number of columns.

ScrollVertical(int): Scrolls the view vertically by the specified number of rows.

SendSubviewBackwards(View): Moves the subview backwards in the hierarchy, only one step

SendSubviewToBack(View): Sends the specified subview to the front so it is the first view drawn

SetClip(): Sets the ConsoleDriver's clip region to Viewport.

SetFocus(): Causes the specified view and the entire parent hierarchy to have the focused order updated.

SetNeedsDisplay(): Sets the area of this view needing to be redrawn to Viewport.

SetNeedsDisplay(Rectangle): Expands the area of this view needing to be redrawn to include region.

SetSubViewNeedsDisplay(): Sets SubViewNeedsDisplay to true for this View and all Superviews.

ToString(): Pretty prints the View

UpdateTextFormatterText(): Can be overridden if the Text has different format than the default.

ViewportToScreen(in Point): Converts a Viewport-relative location to a screen-relative location.

ViewportToScreen(in Rectangle): Converts a Viewport-relative location and size to a screen-relative location and size.

Events

Accept: Cancelable event fired when the Accept command is invoked. Set Cancel to cancel the event.

Added: Event fired when this view is added to another.

CanFocusChanged: Event fired when the CanFocus value is being changed.

ContentSizeChanged: Event raised when the ContentSize changes.

DrawContent: Event invoked when the content area of the View is to be drawn.

DrawContentComplete: Event invoked when the content area of the View is completed drawing.

EnabledChanged: Event fired when the Enabled value is being changed.

Enter: Event fired when the view gets focus.

Highlight: Fired when the view is highlighted. Set Cancel to true to implement a custom highlight scheme or prevent the view from being highlighted.

HotKeyChanged: Invoked when the HotKey is changed.

Initialized: Event called only once when the View is being initialized for the first time. Allows configurations and assignments to be performed before the View being shown. This derived from ISupportInitializeNotification to allow notify all the views that are being initialized.

InvokingKeyBindings: Invoked when a key is pressed that may be mapped to a key binding. Set Handled to true to stop the key from being processed by other views.

KeyDown: Invoked when the user presses a key, allowing subscribers to pre-process the key down event. This is fired from OnKeyDown(Key) before OnInvokingKeyBindings(Key). Set Handled to true to stop the key from being processed by other views.

KeyUp

Invoked when a key is released. Set Handled to true to stop the key up event from being processed by other views. Not all terminals support key distinct down/up notifications, Applications should avoid depending on distinct KeyDown and KeyUp events and instead should use KeyDown.