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.

public class View : Responder, IDisposable, ISupportInitializeNotification, ISupportInitialize

Inheritance: object

Responder

View

Implements: IDisposable

ISupportInitializeNotification

ISupportInitialize

Derived: Button

CheckBox

ColorPicker

ComboBox

FrameView

GraphView

HexView

Label

LineView

ListView

MenuBar

PanelView

ProgressBar

RadioGroup

ScrollBarView

ScrollView

StatusBar

TabView

TableView

TextField

TextValidateField

TextView

Toplevel

TreeView<T>

Inherited Members: Responder.MouseEvent(MouseEvent)

Responder.Dispose()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

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 initialized. 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 parameter 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 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 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 View using Computed layout.

View(ustring, TextDirection, Border): Initializes a new instance of View using Computed layout.

View(int, int, ustring): Initializes a new instance of View using Absolute layout.

View(Rect): Initializes a new instance of a Absolute View class with the absolute dimensions specified in the frame parameter.

View(Rect, ustring, Border): Initializes a new instance of View using Absolute layout.

Properties

AutoSize: Gets or sets a flag that determines whether the View will be automatically resized to fit the Text. The default is false. Set to true to turn on AutoSize. If AutoSize is true the Width and Height will always be used if the text size is lower. If the text size is higher the bounds will be resized to fit it. In addition, if ForceValidatePosDim is true the new values of Width and Height must be of the same types of the existing one to avoid breaking the Dim settings.

Border

Bounds: The bounds represent the View-relative rectangle used for this view; the area inside of the view.

CanFocus: Gets or sets a value indicating whether this Responder 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.

Data: Gets or sets arbitrary data for the view.

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 view inside this view, or null if nothing is focused.

ForceValidatePosDim: Forces validation with Computed layout to avoid breaking the Pos and Dim settings.

Frame: Gets or sets the frame for the view. The frame is relative to the view's container (SuperView).

HasFocus: Gets or sets a value indicating whether this Responder has focus.

Height: Gets or sets the height of the view. Only used the LayoutStyle is Computed.

HotKey: Gets or sets the HotKey defined for this view. A user pressing HotKey on the keyboard while this view has focus will cause the Clicked event to fire.

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

Id: Gets or sets an identifier for the view;

IgnoreBorderPropertyOnRedraw: Get or sets whether the view will use Border (if Border is set) to draw a border. If false (the default), Redraw(Rect) will call DrawContent(View, bool) to draw the view's border. If true no border is drawn (and the view is expected to draw the border itself).

IsAdded: Gets information if the view was already added to the SuperView.

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

IsInitialized: Get or sets if the View was already initialized. This derived from ISupportInitializeNotification to allow notify all the views that are being initialized.

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.

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

PreserveTrailingSpaces: Gets or sets a flag that determines whether Text will have trailing spaces preserved or not when WordWrap(ustring, int, bool, int, TextDirection) is enabled. If true any trailing spaces will be trimmed when either the Text property is changed or when WordWrap(ustring, int, bool, int, TextDirection) is set to true. The default is false.

Shortcut: This is the global setting that can be used as a global shortcut to invoke an action if provided.

ShortcutAction: The action to run if the Shortcut is defined.

ShortcutTag: The keystroke combination used in the Shortcut as string.

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.

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

TabIndexes: This returns a tab index list of the subviews contained by this view.

TabStop: This only be true if the CanFocus is also true and the focus can be avoided by setting this to false

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 which can be handled differently by any derived class.

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

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

WantContinuousButtonPressed: Gets or sets a value indicating whether this View want continuous button pressed event.

WantMousePositionReports: Gets or sets a value indicating whether this View wants mouse position reports.

Width: Gets or sets the width of the view. Only used the LayoutStyle is Computed.

X: Gets or sets the X position for the view (the column). Only used if the LayoutStyle is Computed.

Y: Gets or sets the Y position for the view (the row). Only used if the LayoutStyle is Computed.

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?>)

States that the given View supports a given command and what f to perform to make that command happen

If the command already has an implementation the f will replace the old one

AddKeyBinding(Key, params Command[])

Adds a new key combination that will trigger the given command (if supported by the View - see GetSupportedCommands())

If the key is already bound to a different Command it will be rebound to this one

Commands are only ever applied to the current View(i.e. this feature cannot be used to switch focus to another view and perform multiple commands there)

AddRune(int, int, Rune): Displays the specified character in the specified column and row of the View.

BeginInit(): This derived from ISupportInitializeNotification to allow notify all the views that are beginning initialized.

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 the view region with the current color.

Clear(Rect): Clears the specified region with the current color.

ClearKeybinding(params Command[]): Removes all key bindings that trigger the given command. Views can have multiple different keys bound to the same command and this method will clear all of them.

ClearKeybinding(Key): Clears the existing keybinding (if any) for the given key.

ClearKeybindings(): Removes all bound keys from the View and resets the default bindings.

ClearLayoutNeeded(): Removes the SetNeedsLayout() setting on this view.

ClearNeedsDisplay(): Removes the SetNeedsDisplay() and the ChildNeedsDisplay setting on this view.

ClipToBounds(): Sets the ConsoleDriver's clip region to the current View's Bounds.

ContainsKeyBinding(Key): Checks if the key binding already exists.

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

DrawFrame(Rect, int, bool): Draws a frame in the current view, clipped by the boundary of this view

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

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

EndInit(): This derived from ISupportInitializeNotification to allow notify all the views that are ending initialized.

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

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.

GetAutoSize(): Gets the size to fit all text if AutoSize is true.

GetBoundsTextFormatterSize(): Gets the text formatter size from a Bounds size.

GetCurrentHeight(out int): Calculate the height based on the Height settings.

GetCurrentWidth(out int): Gets the current width based on the Width settings.

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

GetHotKeySpecifierLength(bool): Get the width or height of the HotKeySpecifier length.

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

GetKeyFromCommand(params Command[]): Gets the key used by a command.

GetMinWidthHeight(out Size): Verifies if the minimum width or height can be sets in the view.

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

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

GetTextFormatterBoundsSize(): Gets the bounds size from a Size.

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

InvokeKeybindings(KeyEvent): Invokes any binding that is registered on this View and matches the keyEvent

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, bool): This moves the cursor to the specified column and row in the view.

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

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

OnDrawContent(Rect): Enables overrides to draw infinitely scrolled content and/or a background behind added controls.

OnDrawContentComplete(Rect): Enables overrides after completed drawing infinitely scrolled content and/or a background behind removed controls.

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

OnEnter(View): Method invoked when a view gets focus.

OnKeyDown(KeyEvent): Method invoked when a key is pressed.

OnKeyUp(KeyEvent): Method invoked when a key is released.

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

OnMouseClick(MouseEventArgs): Invokes the MouseClick event.

OnMouseEnter(MouseEvent): Method invoked when a mouse event is generated for the first time.

OnMouseEvent(MouseEvent): Method invoked when a mouse event is generated

OnMouseLeave(MouseEvent): Method invoked when a mouse event is generated for the last time.

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

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.

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.

ProcessHotKey(KeyEvent): This method can be overwritten by view that want to provide accelerator functionality (Alt-key for example).

ProcessKey(KeyEvent): If the view is focused, gives the view a chance to process the keystroke.

ProcessResizeView(): Can be overridden if the view resize behavior is different than the default.

Redraw(Rect): Redraws this view and its subviews; only redraws the views that have been flagged for a re-display.

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.

ReplaceKeyBinding(Key, Key): Replaces a key combination already bound to Command.

ScreenToView(int, int): Converts a point from screen-relative coordinates to view-relative coordinates.

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

SetChildNeedsDisplay(): Indicates that any child views (in the Subviews list) need to be repainted.

SetClip(Rect): Sets the clip region to the specified view-relative region.

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

SetHeight(int, out int): Calculate the height based on the Height settings.

SetMinWidthHeight(): Sets the minimum width or height if the view can be resized.

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

SetNeedsDisplay(Rect): Flags the view-relative region on this View as needing to be repainted.

SetWidth(int, out int): Calculate the width based on the Width settings.

ToString(): Pretty prints the View

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

Events

Added: Event fired when a subview is being added to this view.

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

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.

HotKeyChanged: Event 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.

KeyDown: Invoked when a key is pressed.

KeyPress: Invoked when a character key is pressed and occurs after the key up event.

KeyUp: Invoked when a key is released.

LayoutComplete: Fired after the View's LayoutSubviews() method has completed.

LayoutStarted: Fired after the View's LayoutSubviews() method has completed.

Leave: Event fired when the view looses focus.

MouseClick: Event fired when a mouse event is generated.

MouseEnter: Event fired when the view receives the mouse event for the first time.

MouseLeave: Event fired when the view receives a mouse event for the last time.

Removed: Event fired when a subview is being removed from this view.