View

open class View : Responder, Hashable, CustomDebugStringConvertible

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.

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

Views can either be created with a constructor that takes a Rect as the frame to used for the view, which means that the view is using the .fixed LayoutStyle, or with the empty construtor, and then setting the x, y, width and height properties on the view which configures the view to use the .computed layout style.

The view layout system can be controlled by accessing the layoutStyle property, and is used to transition from the fixed to the computed mode.

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 your views if your view’s frames are resized or if the terminal size changes

Subviews can be added to a View by calling the addSubview method. The container of a view is the Superview.

Developers can call the setNeedsDisplay method on the view to flag a region or the entire view as requiring to be redrawn.

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.

If a ColorScheme is not set on a view, the result of the ColorScheme is the value of the SuperView and the value might only be valid once a view has been added to a SuperView, so your subclasses should not rely on ColorScheme being set at construction time.

Using ColorSchemes has the advantage that your application 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 metnod layoutSubviews 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 LayoutKind.Absolute, and will recompute the frames for the vies that use LayoutKind.Computed.

  • The superview points to the container where this view was added, or nil if this view has not been added to a container

    Declaration

    Swift

    public private(set) var superview: View? { get }

  • Returns the currently focused view inside this view, or nil if nothing is focused.

    Declaration

    Swift

    public private(set) var focused: View? { get }

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

    Declaration

    Swift

    public var subviewAdded: PassthroughSubject<View, Never>

  • Event fired when a subview was removed from this view.

    Declaration

    Swift

    public var subviewRemoved: PassthroughSubject<View, Never>

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

    Declaration

    Swift

    public var mouseEntered: PassthroughSubject<MouseEvent, Never>

  • Event fired when the view receives a mouse event because the mouse is outside its boundary

    Declaration

    Swift

    public var mouseLeft: PassthroughSubject<MouseEvent, Never>

  • Event fired when a mouse event is generated.

    Declaration

    Swift

    public var mouseClicked: PassthroughSubject<MouseEvent, Never>

  • This is a payload that can be set by user code to any value it desires

    Declaration

    Swift

    public var data: AnyObject?

  • The array containing the subviews added to this tree, sorted from back to front.

    Declaration

    Swift

    public var subviews: [View] { get }

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

    Declaration

    Swift

    public var tabStop: Bool { get set }

  • Controls how the view’s frame is computed during the layoutSubviews method, if absolute, then layoutSubviews does not change the frame properties, otherwise the frame is updated from the values in x, y, width and height properties.

    Declaration

    Swift

    public var layoutStyle: LayoutStyle { get set }

  • Declaration

    Swift

    public var canFocus: Bool { get set }

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

    Declaration

    Swift

    public var isCurrentTop: Bool { get }

  • Constructor for a view that will use computed layout style based on the values in Pos object (x, y) and Dim objects (width and height)

    Declaration

    Swift

    public init()

  • Constructor for a view that will use fixed layout style using frame as the dimension. When using this constructor, the view will not participate in automatic layout, but you can manually update the frame by overriding layoutSubviews

    Declaration

    Swift

    public init(frame: Rect)

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

    Declaration

    Swift

    public var wantMousePositionReports: Bool

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

    Declaration

    Swift

    public var wantContinuousButtonPressed: Bool

  • Gets or sets the frame for the view.

    The coordinate of the frame is relative to the parent, so position 10,5 will position the view is the column 10, row 5 in the container.

    Altering the Frame of a view will trigger the redrawing of the view as well as the redrawing of the affected regions in the superview and will also set the layoutStyle to be .fixed

    Declaration

    Swift

    public var frame: Rect { get set }

  • The bounds represent the View-relative rectangle used for this view.

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

    Declaration

    Swift

    public var bounds: Rect { get }

  • Convenience method to set one or more of x, y, width and height properties to their numeric values

    Declaration

    Swift

    public func set(x: Int? = nil, y: Int? = nil, width: Int? = nil, height: Int? = nil)

    Parameters

    x

    Optional value for the x property, equivalent to setting it to Pos.at (x)
    y

    Optional value for the y property, equivalent to setting it to Pos.at (y)
    width

    Optional value for the width property, equivalent to setting it to Dim.sized (width)
    height

    Optional value for the height property, equivalent to setting it to Dim.sized (height)

  • Invoke to flag that this view needs to be redisplayed, by any code that alters the state of the view.

    Declaration

    Swift

    public func setNeedsDisplay()

  • Flags the specified rectangle region on this view as needing to be repainted.

    Declaration

    Swift

    public func setNeedsDisplay(_ region: Rect)

    Parameters

    region

    The region that must be flagged for repaint, this is in the coordinates of the receiver.

  • Adds the provided view as a subview of this view

    Declaration

    Swift

    public func addSubview(_ view: View)

  • Sets the x, y, width and height to fill the container

    Declaration

    Swift

    public func fill(padding: Int = 0)

    Parameters

    padding

    any desired padding, if not specified, it defaults to zero

  • Sets the x, y, width and height to occupy the specified percentage of the container

    Declaration

    Swift

    public func fill(percentage: Float)

    Parameters

    percentage

    Number between 0 and 100

  • Adds the provided views as subviews of this view

    Declaration

    Swift

    public func addSubviews(_ views: [View])

  • Removes the specified view from the container

    Declaration

    Swift

    public func remove(_ view: View)

  • Removes all views from this container

    Declaration

    Swift

    public func removeAllSubviews()

  • Brings the specified subview to the front so it is drawn on top of any other views.

    Declaration

    Swift

    public func bringSubviewToFront(_ subview: View)

  • Moves the subview backwards in the hierarchy, only one step

    Declaration

    Swift

    public func sendSubviewToBack(_ subview: View)

  • Moves the subview backwards in the hierarchy, only one step

    Declaration

    Swift

    public func sendBackwards(subview: View)

  • Moves the subview backwards in the hierarchy, only one step

    Declaration

    Swift

    public func bringForward(subview: View)

  • Converts a point from screen coordinates into the view coordinate space.

    Declaration

    Swift

    public func screenToView(loc: Point) -> Point

    Parameters

    x

    Y screen-coordinate point.
    x

    Y screen-coordinate point.

    Return Value

    the mapped point

  • This moves the cursor to the specified column and row in the view, any additional drawing operation will start at the specified location

    Declaration

    Swift

    public func moveTo(col: Int, row: Int)

    Parameters

    col

    Column to move to
    row

    Row to move to.

  • Positions the cursor in the right position based on the currently focused view in the chain.

    Declaration

    Swift

    public func positionCursor()

  • True if this view currently has the focus (events go to this view)

    Declaration

    Swift

    public var hasFocus: Bool { get }

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

    Declaration

    Swift

    public func mostFocused() -> View?

  • The colorscheme used by this view

    Declaration

    Swift

    public var colorScheme: ColorScheme! { get set }

  • Removes the SetNeedsDisplay and the ChildNeedsDisplay setting on this view.

    Declaration

    Swift

    public func clearNeedsDisplay()

  • Performs a redraw of this view and its subviews, only redraws the views that have been flagged for a re-display.

    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.

    Declaration

    Swift

    open func redraw(region: Rect, painter: Painter)

    Parameters

    region

    The region to redraw, this is relative to the view itself.

  • Causes the specified view and the entire parent hierarchy to have the focused order updated.

    Declaration

    Swift

    public func setFocus(_ view: View?)

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

    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.

    Declaration

    Swift

    public func processHotKey(event: KeyEvent) -> Bool

  • If the view is focused, gives the view a chance to process the keystroke.

    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.

    Declaration

    Swift

    public func processKey(event: KeyEvent) -> Bool

  • This method can be overwritten by views that want to provide accelerator functionality (Alt-key for example), but without interefering with normal ProcessKey behavior.

    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.

    Declaration

    Swift

    public func processColdKey(event: KeyEvent) -> Bool

  • Method invoked when a mouse event is generated

    Declaration

    Swift

    public func mouseEvent(event: MouseEvent) -> Bool

  • Finds the first view in the hierarchy that wants to get the focus if nothing is currently focused, otherwise, it does nothing.

    Declaration

    Swift

    public func ensureFocus()

  • Focuses the first focusable subview if one exists.

    Declaration

    Swift

    public func focusFirst()

  • Focuses the last focusable subview if one exists.

    Declaration

    Swift

    public func focusLast()

  • Focuses the previous view in the focus chain

    Declaration

    Swift

    @discardableResult
public func focusPrev() -> Bool

    Return Value

    true if previous was focused, false otherwise

  • Focuses the next view in the focus chain

    Declaration

    Swift

    @discardableResult
public func focusNext() -> Bool

    Return Value

    true if previous was focused, false otherwise

  • x

    Gets or sets the X position for the view (the column). This is only used when the LayoutStyle is computed, if the LayoutStyle is set to absolute, this value is ignored.

    Declaration

    Swift

    public var x: Pos? { get set }
  • y

    Gets or sets the Y position for the view (the row). This is only used when the LayoutStyle is computed, if the LayoutStyle is set to absolute, this value is ignored.

    Declaration

    Swift

    public var y: Pos? { get set }

  • Gets or sets the width for the view. This is only used when the LayoutStyle is computed, if the LayoutStyle is set to absolute, this value is ignored.

    Declaration

    Swift

    public var width: Dim? { get set }

  • Gets or sets the height for the view. This is only used when the LayoutStyle is computed, if the LayoutStyle is set to absolute, this value is ignored.

    Declaration

    Swift

    public var height: Dim? { get set }

  • Declaration

    Swift

    public static func == (lhs: View, rhs: View) -> Bool

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

  • Undocumented

    Declaration

    Swift

    open func layoutSubviews() throws

  • Declaration

    Swift

    public func mouseEnter(event: MouseEvent) -> Bool

  • Declaration

    Swift

    public func mouseLeave(event: MouseEvent) -> Bool

  • Declaration

    Swift

    public func becomeFirstResponder() -> Bool

  • Declaration

    Swift

    public func resignFirstResponder() -> Bool

  • Declaration

    Swift

    public var debugDescription: String { get }

  • Helper utility that can be used to determine if the event contains a hotkey invocation, which is Alt+letter

    Declaration

    Swift

    public static func eventTriggersHotKey(event: KeyEvent, hotKey: Character?) -> Bool

    Parameters

    event

    the event provided by the Application
    hotKey

    A Character? that contains the letter that represents the hotkey

    Return Value

    True if hotkey is not nil, and the letter alt + this character (uppercase or lowercase) is pressed.