Class View

Namespace: Terminal.Gui

Assembly: Terminal.Gui.dll

View is the base class all visible elements. View 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.

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 SetNeedsDraw(Rectangle) . To flag the entire view for redraw call SetNeedsDraw().

The SetNeedsLayout() method is called when the size or layout of a view has changed. The MainLoop will cause Layout() to be called on the next Iteration so there is normally no reason to direclty call see Layout().

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 arranging this 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.

The Border provides the UI for mouse and keyboard arrangement of the View. See Arrangement.

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 be focused.

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

ContentSizeTracksViewport: Gets or sets a value indicating whether the view's content size tracks the Viewport's size or not.

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: Gets or sets whether diagnostic information will be drawn. This is a bit-field of ViewDiagnosticFlags.e 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: Gets the currently focused Subview or Adornment of this view, or null if nothing is focused.

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

HasFocus: Gets or sets whether this view has focus.

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

HighlightStyle: Gets or sets whether the View will be highlighted visually by mouse interaction.

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 HotKey. By default, the HotKey is set to the first character of Text that is prefixed with HotKeySpecifier.

A HotKey is a keypress that causes a visible UI item to perform an action. For example, in a Dialog, with a Button with the text of "_Text" Alt+T will cause the button to gain focus and to raise its Accepting event. 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.

View subclasses can use AddCommand(Command, CommandImplementation) to define the behavior of the hot key.

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.

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 down the subview-hierarchy.

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

NeedsLayout: Indicates the View's Frame or the layout of the View's subviews (including Adornments) have changed since the last time the View was laid out.

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.

ShadowStyle: Gets or sets whether the View is shown with a shadow effect. The shadow is drawn on the right and bottom sides of the Margin.

SubViewNeedsDraw: 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 OnDrawingBorderAndPadding() method will be called to render the borders.

TabStop: Gets or sets the behavior of AdvanceFocus(NavigationDirection, TabBehavior?) 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 GetContentSize(), or GetContentSize() 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 View is visible.

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 for each command they support.

If AddCommand has already been called for commandimpl will replace the old one.

AddCommand(Command, CommandImplementation)

Sets the function that will be invoked for a Command. Views should call AddCommand for each command they support.

If AddCommand has already been called for commandimpl will replace the old one.

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

AddRune(char): Adds the specified char to the display at the current cursor position. This method is a convenience method that calls AddRune(Rune) with the Rune constructor.

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

AddRune(Rune): Draws the specified character at the current draw position.

AddStr(string): Adds the str to the display at the current draw position.

AdvanceFocus(NavigationDirection, TabBehavior?): Advances the focus to the next or previous view in the focus chain, based on direction. itself.

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

ClearNeedsDraw(): Clears NeedsDraw and SubViewNeedsDraw.

ClearViewport(): Clears Viewport with the normal background.

ClipViewport(): Changes the Clip to the intersection of the current Clip and the Viewport of this View.

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 if it needs to be drawn.

DrawBorderAndPadding(): Causes Border and Padding to be drawn.

DrawHotString(string, bool): 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.

DrawSubviews(): Draws the Subviews.

DrawText(): Draws the Text of the View using the TextFormatter.

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

ExcludeFromClip(Rectangle): Removes the specified rectangle from the Clip.

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

FillRect(Rectangle, Rune): Fills the specified Viewport-relative rectangle.

FocusDeepest(NavigationDirection, TabBehavior?): Focuses the deepest focusable Subview if one exists. If there are no focusable Subviews then the focus is set to the view itself.

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

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

GetAttribute(): Gets the current Attribute.

GetClip(): Gets the current Clip region.

GetContentSize(): Gets the size of the View's content.

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

GetHotFocusColor(): 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, CommandContext): Invokes the specified command.

InvokeCommand(Command, Key?, KeyBinding?): Invokes the specified command.

InvokeCommands(Command[], Key?, KeyBinding?): Invokes the specified commands.

InvokeCommands(Key, KeyBindingScope)

Invokes the Commands bound to key.

See for an overview of Terminal.Gui keyboard APIs.

IsHotKeyBound(Key, out View?): Returns true if Key is bound in this view hierarchy. For debugging

Layout(): Performs layout of the view and its subviews using the content size of either the SuperView or Screen.

Layout(Size): Performs layout of the view and its subviews within the specified content size.

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

MoveSubviewToEnd(View): Moves subview to the end of the Subviews list.

MoveSubviewToStart(View): Moves subview to the start of the Subviews list.

MoveSubviewTowardsEnd(View): Moves subview one position towards the end of the Subviews list.

MoveSubviewTowardsStart(View): Moves subview one position towards the start of the Subviews list.

NewKeyDownEvent(Key): If the view is enabled, raises the related key down events on the view, and returns true if the event was handled.

NewKeyUpEvent(Key): If the view is enabled, raises the related key up events on the view, and returns true if the event was handled.

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

OnAccepting(CommandEventArgs): Called when the user is accepting the state of the View and the Accept has been invoked. Set CommandEventArgs.Cancel to true and return true to stop processing.

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

OnAdvancingFocus(NavigationDirection, TabBehavior?): Called when AdvanceFocus(NavigationDirection, TabBehavior?) is about to advance focus.

OnBorderStyleChanging(CancelEventArgs<LineStyle>): Called when the BorderStyle is changing.

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

OnClearingViewport(): Called when the Viewport is to be cleared.

OnContentSizeChanged(SizeChangedEventArgs): Called when GetContentSize() has changed.

OnDrawComplete(): Called when the View is completed drawing.

OnDrawingBorderAndPadding(): Called when the View's Adornments are to be drawn. 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.

OnDrawingContent(): Called when the View's content is to be drawn. The default implementation does nothing.

OnDrawingSubviews(): Called when the Subviews are to be drawn.

OnDrawingText(): Called when the Text of the View is to be drawn.

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

OnHandlingHotKey(CommandEventArgs): Called when the View is handling the user pressing the View's HotKey. Set CommandEventArgs.Cancel to true to stop processing.

OnHasFocusChanged(bool, View?, View?): Invoked after HasFocus has changed. This method is called before the HasFocusChanged event is raised.

OnHasFocusChanging(bool, bool, View?, View?): Invoked when HasFocus is about to change. This method is called before the HasFocusChanging event is raised.

OnHighlight(CancelEventArgs<HighlightStyle>): Called when the view is to be highlighted. The HighlightStyle passed in the event indicates the highlight style that will be applied. The view can modify the highlight style by setting the NewValue property.

OnKeyDown(Key): Called when the user presses a key, allowing subscribers to pre-process the key down event. Called before key bindings are invoked and KeyDownNotHandled is raised. Set Handled to true to stop the key from being processed further.

OnKeyDownNotHandled(Key): Called when the user has pressed key it wasn't handled by KeyDown and was not bound to a key binding.

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

OnMouseClick(MouseEventArgs): Called when a mouse click occurs. Check Flags to see which button was clicked.

OnMouseEnter(CancelEventArgs): Called when the mouse moves over the View's Frame and no other non-Subview occludes it. MouseLeave will be raised when the mouse is no longer over the Frame.

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

OnMouseLeave(): Called when the mouse moves outside View's Frame, or is occluded by another non-SubView.

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

OnRenderingLineCanvas(): Called when the LineCanvas is to be rendered. See RenderLineCanvas().

OnSelecting(CommandEventArgs): Called when the user has performed an action (e.g. Select) causing the View to change state. Set CommandEventArgs.Cancel to true and return true to cancel the state change. The default implementation does nothing.

OnSettingAttribute(): Called when the normal attribute for the View is to be set. This is called before the View is drawn.

OnSubviewLayout(LayoutEventArgs): Called from LayoutSubviews() before any subviews have been laid out.

OnSubviewsLaidOut(LayoutEventArgs): Called from LayoutSubviews() after all sub-views have been laid out.

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

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

OnTitleChanging(ref 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(): Called when Visible has changed.

OnVisibleChanging(): Called when Visible is changing. Can be cancelled by returning true.

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

RaiseAccepting(CommandContext): Called when the user is accepting the state of the View and the Accept has been invoked. Calls OnAccepting(CommandEventArgs) which can be cancelled; if not cancelled raises Accepting. event. The default Accept handler calls this method.

RaiseHandlingHotKey(): Called when the View is handling the user pressing the View's HotKeys. Calls OnHandlingHotKey(CommandEventArgs) which can be cancelled; if not cancelled raises Accepting. event. The default HotKey handler calls this method.

RaiseMouseClickEvent(MouseEventArgs): Raises the OnMouseClick(MouseEventArgs)/MouseClick event.

RaiseMouseEvent(MouseEventArgs): Raises the RaiseMouseEvent(MouseEventArgs)/MouseEvent event.

RaiseSelecting(CommandContext): Called when the user has performed an action (e.g. Select) causing the View to change state. Calls OnSelecting(CommandEventArgs) which can be cancelled; if not cancelled raises Accepting. event. The default Select handler calls this method.

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.

RenderLineCanvas(): Causes the contents of LineCanvas to be drawn. 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.

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.

SetAttribute(Attribute): Selects the specified attribute as the attribute to use for future calls to AddRune and AddString.

SetBorderStyle(LineStyle): Sets the BorderStyle of the view to the specified value.

SetClip(Region?): Sets the Clip to the specified region.

SetClipToScreen(): Sets the Clip to be the rectangle of the screen.

SetContentSize(Size?): Sets the size of the View's content.

SetFocus(): Causes this view to be focused. Calling this method has the same effect as setting HasFocus to true but with the added benefit of returning a value indicating whether the focus was set.

SetNeedsDraw(): Sets that the Viewport of this View needs to be redrawn.

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

SetNeedsLayout(): Sets NeedsLayout to return true, indicating this View and all of it's subviews (including adornments) need to be laid out in the next Application iteration.

SetNormalAttribute(): Sets the attribute for the View. This is called before the View is drawn.

SetRelativeLayout(Size): Sets the position and size of this view, relative to the SuperView's ContentSize (nominally the same as this.SuperView.GetContentSize ()) based on the values of X, Y, Width, and Height.

SetSubViewNeedsDraw(): Sets SubViewNeedsDraw 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

Accepting: Cancelable event raised when the user is accepting the state of the View and the Accept has been invoked. Set CommandEventArgs.Cancel to cancel the event.

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

AdvancingFocus: Raised when AdvanceFocus(NavigationDirection, TabBehavior?) is about to advance focus.

BorderStyleChanging: Fired when the BorderStyle is changing. Allows the event to be cancelled.

CanFocusChanged: Raised when CanFocus has been changed.

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

ContentSizeChanged: Event raised when the GetContentSize() changes.

DrawComplete: Raised when the View is completed drawing.

DrawingContent: Raised when the View's content is to be drawn.

DrawingSubviews: Raised when the Subviews are to be drawn.

DrawingText: Raised when the Text of the View is to be drawn.

EnabledChanged: Raised when the Enabled value is being changed.

HandlingHotKey: Cancelable event raised when the View is handling the user pressing the View's HotKey. Set CommandEventArgs.Cancel to cancel the event.

HasFocusChanged: Raised after HasFocus has changed.

HasFocusChanging: Raised when HasFocus is about to change.

Highlight: Raised when the view is to be highlighted. The HighlightStyle passed in the event indicates the highlight style that will be applied. The view can modify the highlight style by setting the NewValue property. Set to true, to cancel, indicating custom highlighting.

HotKeyChanged: Raised when the HotKey is changed.

Initialized: Raised once when the View is being initialized for the first time. Allows configurations and assignments to be performed before the View being shown. View implements ISupportInitializeNotification to allow for more sophisticated initialization.

KeyDown: Raised when the user presses a key, allowing subscribers to pre-process the key down event. Called before key bindings are invoked and KeyDownNotHandled is raised. Set Handled to true to stop the key from being processed further.

KeyDownNotHandled: Raised when the user has pressed key it wasn't handled by KeyDown and was not bound to a key binding.

KeyUp

Raised 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.