Terminal

open class Terminal

The Terminal class provides the terminal emulation engine, and can be used to feed data to the terminal emulator. Typically users will intereact with a higher-level implementation that provides a UI toolkit-specific rendering and connects the input to the UI toolkit.

A front-end would draw the contents of the terminal, and take input from the user, which is in turn either mapped to one of the public APIs here, or if it is user input is passed to the feed methods here.

The terminal is also connected to a backend that is conneted to the client, and data from this client is fed into the emulator by calling the sendResponse method

The behavior of the terminal is configured by implementing the TerminalDelegate protocol that is provided in the constructor call.

  • The current terminal columns (counting from 1)

    Declaration

    Swift

    public private(set) var cols: Int { get }

  • The current terminal rows (counting from 1)

    Declaration

    Swift

    public private(set) var rows: Int { get }

  • Undocumented

    Declaration

    Swift

    public var applicationCursor: Bool

  • Indicates that the application has toggled bracketed paste mode, which means that when content is pasted into the terminal, the content will be wrapped in “ESC [ 200 ~” to start, and “ESC [ 201 ~” to end.

    Declaration

    Swift

    public private(set) var bracketedPasteMode: Bool { get }

  • This variable if set, contains an URI representing the host and directory of the process running in the terminal it is often used by applciations to track the working directory. It might be nil, or might not be correct, the contents are entirely under the control of the remote application, and require the terminal to be trusted (see the isProcessTrusted method in the TerminalDelegate). When this is set the hostCurrentDirectoryUpdated method on the delegate is invoked.

    Declaration

    Swift

    public private(set) var hostCurrentDirectory: String? { get }

  • This variable if set, contains an URI representing the host and current document of the process running in the terminal. It might be nil, or might not be correct, the contents are entirely under the control of the remote application, and require the terminal to be trusted (see the isProcessTrusted method in the TerminalDelegate). When this is set the hostCurrentDocumentUpdated method on the delegate is invoked.

    Declaration

    Swift

    public private(set) var hostCurrentDocument: String? { get }

  • The current attribute used by the terminal by default

    Declaration

    Swift

    public var currentAttribute: Attribute { get }

  • This tracks the current foreground color for the application.

    Declaration

    Swift

    public var foregroundColor: Color { get set }

  • This tracks the current background color for the application.

    Declaration

    Swift

    public var backgroundColor: Color { get set }

  • Represents the mouse operation mode that the terminal is currently using and higher level implementations should use the functions in this enumeration to determine what events to send

    See more

    Declaration

    Swift

    public enum MouseMode

  • Undocumented

    Declaration

    Swift

    public private(set) var mouseMode: MouseMode { get set }

  • Returns the terminal dimensions 1-based values

    Declaration

    Swift

    public func getDims() -> (cols: Int, rows: Int)

  • Undocumented

    Declaration

    Swift

    public init(delegate: TerminalDelegate, options: TerminalOptions = TerminalOptions.default)

  • Installs the new colors as the default colors and recomputes the current and ansi palette. This will not change the UI layer, for that it is better to call the installColors method on TerminalView, which will both call this method, and update the display appropriately.

    Declaration

    Swift

    public func installPalette(colors: [Color])

    Parameters

    colors

    this should be an array of 16 values that correspond to the 16 ANSI colors, if the array does not contain 16 elements, it will not do anything

  • Returns the CharData at the specified column and row from the visible portion of the buffer, these are zero-based

    Declaration

    Swift

    public func getCharData(col: Int, row: Int) -> CharData?

    Parameters

    col

    column to retrieve, starts at 0
    row

    row to retrieve, starts at 0

    Return Value

    nil if the col or row are out of bounds, or the CharData contained in that cell otherwise

  • Returns the contents of a line as a BufferLine, or nil if the requested line is out of range

    The line is counted from start of scroll back, not what the terminal has visible right now.

    Declaration

    Swift

    public func getLine(row: Int) -> BufferLine?

    Parameters

    row

    the row to retrieve, relative to the scroll buffer, not the visible display

    Return Value

    nil if the col or row are out of bounds, or the BufferLine otherwise

  • Returns the contents of a line as a BufferLine counting from the begging of the scroll buffer.

    The line is counted from start of scroll back, not what the terminal has visible right now.

    Declaration

    Swift

    public func getScrollInvariantLine(row: Int) -> BufferLine?

    Parameters

    row

    the row to retrieve, relative to the scroll buffer, not the visible display

    Return Value

    nil if the col or row are out of bounds, or the BufferLine otherwise

  • Returns the character at the specified column and row, these are zero-based

    Declaration

    Swift

    public func getCharacter(col: Int, row: Int) -> Character?

    Parameters

    col

    column to retrieve, starts at 0
    row

    row to retrieve, starts at 0

    Return Value

    nil if the col or row are out of bounds, or the Character contained in that cell otherwise

  • Commands send to the windowCommand delegate for the front-end to implement capabilities on behalf of the client. The expected return strings in some of these enumeration values is documented below. Returns are only expected for the enum values that start with the prefix report

    See more

    Declaration

    Swift

    public enum WindowManipulationCommand

  • Performs a terminal soft-reset, the equivalent of the DECSTR sequence For a full reset see resetToInitialState

    Declaration

    Swift

    public func softReset()

  • Sends the provided text to the connected backend

    Declaration

    Swift

    public func sendResponse(text: String)

  • Sends the provided text to the connected backend, takes a variable list of arguments that could be either [UInt8], Strings, or a single UInt8 value.

    Declaration

    Swift

    public func sendResponse(_ items: Any...)

  • Undocumented

    Declaration

    Swift

    public var silentLog: Bool

  • Processes the provided byte-array coming from the backend

    Declaration

    Swift

    public func feed(byteArray: [UInt8])

  • Undocumented

    Declaration

    Swift

    public func feed(text: String)

  • Undocumented

    Declaration

    Swift

    public func feed(buffer: ArraySlice<UInt8>)

  • Undocumented

    Declaration

    Swift

    public func parse(buffer: ArraySlice<UInt8>)

  • Undocumented

    Declaration

    Swift

    public func updateFullScreen()

  • Returns the starting and ending lines that need to be redrawn, or nil if no part of the screen needs to be updated. Alternatively, you can get a Set with the changed lines by calling changedLines().

    UI toolkits should call clearUpdateRange to reset these changes after they have used this information, so that new changes only reflect the actual changes.

    Declaration

    Swift

    public func getUpdateRange() -> (startY: Int, endY: Int)?

  • Returns a set containing the lines that have been modified, the returned set is not sorted.

    UI toolkits should call clearUpdateRange to reset these changes after they have used this information, so that new changes only reflect the actual changes.

    Declaration

    Swift

    public func changedLines() -> Set<Int>

  • Check for payload identifiers that are not in use and stop retaining their payload, to avoid accumulting memory for images and URLs that are no longer visible or available by scrolling.

    Declaration

    Swift

    public func garbageCollectPayload()

  • Returns the starting and ending lines that need to be redrawn, or nil if no part of the screen needs to be updated.

    This is different from getUpdateRange() in that lines are from start of scroll back, not what the terminal has visible right now.

    Declaration

    Swift

    public func getScrollInvariantUpdateRange() -> (startY: Int, endY: Int)?

  • Clears the state of the pending display redraw region as well as the dirtyLines set.

    Declaration

    Swift

    public func clearUpdateRange()

  • Zero-based (row, column) of cursor location relative to visible part of display. Returns: a tuple, where the first element contains the column (x) and the second the row (y) where the cursor is.

    Declaration

    Swift

    public func getCursorLocation() -> (x: Int, y: Int)

  • Returns the uppermost visible row on the terminal buffer

    Declaration

    Swift

    public func getTopVisibleRow() -> Int

  • This performs a full reset of the terminal, like a soft reset, but additionally resets the buffer conents and scroll area. for a soft reset see softReset

    Declaration

    Swift

    public func resetToInitialState()

  • Undocumented

    Declaration

    Swift

    public func scroll(isWrapped: Bool = false)

  • Undocumented

    Declaration

    Swift

    public func emitLineFeed()

  • Undocumented

    Declaration

    Swift

    public func resize(cols: Int, rows: Int)

  • Registers that the region between startRow and endRow was modified and needs to be updated by the

    Declaration

    Swift

    public func refresh(startRow: Int, endRow: Int)

  • Undocumented

    Declaration

    Swift

    public func showCursor()

  • Undocumented

    Declaration

    Swift

    public func hideCursor()

  • Encodes the button action in the format expected by the client

    Declaration

    Swift

    public func encodeButton(button: Int, release: Bool, shift: Bool, meta: Bool, control: Bool) -> Int

    Parameters

    button

    The button to encode
    release

    true if this is a mouse release event
    shift

    true if the shift key is pressed
    meta

    true if the meta/alt key is pressed
    control

    true if the control key is pressed

    Return Value

    the encoded value

  • Sends a mouse event for a specific button at the specific location

    Declaration

    Swift

    public func sendEvent(buttonFlags: Int, x: Int, y: Int)

    Parameters

    buttonFlags

    Button flags encoded in Cb mode.
    x

    X coordinate for the event
    y

    Y coordinate for the event

  • Sends a mouse motion event for a specific button at the specific location

    Declaration

    Swift

    public func sendMotion(buttonFlags: Int, x: Int, y: Int)

    Parameters

    buttonFlags

    Button flags encoded in Cb mode.
    x

    X coordinate for the event
    y

    Y coordinate for the event

  • Undocumented

    Declaration

    Swift

    public func setTitle(text: String)

  • Undocumented

    Declaration

    Swift

    public func setIconTitle(text: String)

  • Provides a baseline set of environment variables that would be useful to run the terminal, you can customzie these accordingly.

    Declaration

    Swift

    public static func getEnvironmentVariables(termName: String? = nil, trueColor: Bool = true) -> [String]

    Return Value

    an array of default environment variables that include TERM set to the specified value, or xterm-256color, and if trueColor is true, COLORTERM=truecolor, the LANG=en_US.UTF-8 and it mirrors the currently set values for LOGNAME, USER, DISPLAY, LC_TYPE, USER and HOME.

  • Specified the kind of buffer is being requested from the terminal

    See more

    Declaration

    Swift

    public enum BufferKind

  • Returns the contents of the specified terminal buffer encoded as UTF8 in the provided Data buffer

    Declaration

    Swift

    public func getBufferAsData(kind: BufferKind = .active, encoding: String.Encoding = .utf8) -> Data

    Parameters

    kind

    which buffer to retrive the data for
    encoding

    which encoding to use for the returned value, defaults to utf8