Class Terminal

This class allows the developer to interact with the terminal and its settings. This is the main class that is used in a Curses-based application.

Inheritance

object

Terminal

Implements

ITerminal

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Sharpie

Assembly: sharpie.dll

Syntax

[PublicAPI]
public sealed class Terminal : ITerminal, IDisposable

Constructors

Terminal(ICursesBackend, TerminalOptions)

Creates a new instance of the terminal.

Declaration

public Terminal(ICursesBackend curses, TerminalOptions options)

Parameters

Type	Name	Description
ICursesBackend	curses	The curses backend.
TerminalOptions	options	The terminal options.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Some of the options are invalid.
InvalidOperationException	Another terminal instance is active.
ArgumentNullException	The curses is null.
CursesOperationException	A Curses error occurred.

Properties

BaudRate

Gets the terminal's baud rate.

Declaration

public int BaudRate { get; }

Property Value

Type	Description
int

Exceptions

Type	Condition
CursesOperationException	A Curses error occurred.

Colors

Provides access to the terminal's color management.

Declaration

public ColorManager Colors { get; }

Property Value

Type	Description
ColorManager

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

CurrentEraseChar

Gets the currently defined erase character. null is returned if none is defined.

Declaration

public Rune? CurrentEraseChar { get; }

Property Value

Type	Description
Rune?

CurrentKillChar

Gets the currently defined kill character. null is returned if none is defined.

Declaration

public Rune? CurrentKillChar { get; }

Property Value

Type	Description
Rune?

Curses

The Curses backend.

Declaration

public ICursesBackend Curses { get; }

Property Value

Type	Description
ICursesBackend

CursesVersion

Returns the version of the Curses library in use.

Declaration

public string? CursesVersion { get; }

Property Value

Type	Description
string

Description

Returns the long description of the terminal.

Declaration

public string? Description { get; }

Property Value

Type	Description
string

Disposed

Checks whether the terminal has been disposed of and is no longer usable.

Declaration

public bool Disposed { get; }

Property Value

Type	Description
bool

Events

The event pump instance that can be used to read events from the terminal.

Declaration

public EventPump Events { get; }

Property Value

Type	Description
EventPump

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

Footer

The footer surface. Only initialized if AllocateFooter was set.

Declaration

public TerminalSurface? Footer { get; }

Property Value

Type	Description
TerminalSurface

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

Header

The header surface. Only initialized if AllocateHeader was set.

Declaration

public TerminalSurface? Header { get; }

Property Value

Type	Description
TerminalSurface

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

Name

Returns the name of the terminal.

Declaration

public string? Name { get; }

Property Value

Type	Description
string

Options

Gets the options that are used by this terminal instance.

Declaration

public TerminalOptions Options { get; }

Property Value

Type	Description
TerminalOptions

Screen

The screen instance. Use this property to access the entire screen functionality.

Declaration

public Screen Screen { get; }

Property Value

Type	Description
Screen

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

SoftLabelKeys

Provides access to the terminal's color management.

Declaration

public SoftLabelKeyManager SoftLabelKeys { get; }

Property Value

Type	Description
SoftLabelKeyManager

Exceptions

Type	Condition
ObjectDisposedException	The terminal has been disposed.

SupportedAttributes

Gets the combination of supported terminal attributes.

Declaration

public VideoAttribute SupportedAttributes { get; }

Property Value

Type	Description
VideoAttribute

Methods

Alert(bool)

Attempts to notify the user with audio or flashing alert.

Declaration

public void Alert(bool silent)

Parameters

Type	Name	Description
bool	silent	The alert mode.

Remarks

The actual notification depends on terminal support.

Exceptions

Type	Condition
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

AtomicRefresh()

Creates a batch update lock.

Declaration

public IDisposable AtomicRefresh()

Returns

Type	Description
IDisposable	A disposable object that need to be disposed to release the batch update lock.

Delay(Func<Terminal, Task>, int)

Sets up a delayed action that is to be executed after some time.

Declaration

public IInterval Delay(Func<Terminal, Task> action, int delayMillis)

Parameters

Type	Name	Description
Func<Terminal, Task>	action	The action to be executed.
int	delayMillis	The delay in milliseconds.

Returns

Type	Description
IInterval	The interval object.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if delayMillis is negative.

Delay<TState>(Func<Terminal, TState?, Task>, int, TState?)

Sets up a delayed action that is to be executed after some time.

Declaration

public IInterval Delay<TState>(Func<Terminal, TState?, Task> action, int delayMillis, TState? state)

Parameters

Type	Name	Description
Func<Terminal, TState, Task>	action	The action to be executed.
int	delayMillis	The delay in milliseconds.
TState	state

Returns

Type	Description
IInterval	The interval object.

Type Parameters

Name	Description
TState

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if delayMillis is negative.

Delegate(Func<Task>)

Delegates an action to be executed on the main thread.

Declaration

public void Delegate(Func<Task> action)

Parameters

Type	Name	Description
Func<Task>	action	The action to execute.

Exceptions

Type	Condition
ArgumentNullException	Thrown if action is null.
ObjectDisposedException	The terminal has been disposed.

Dispose()

Disposes the current terminal instance.

Declaration

public void Dispose()

~Terminal()

The destructor. Calls Dispose() method.

Declaration

protected ~Terminal()

Repeat(Func<Terminal, Task>, int, bool)

Sets up a delayed action that is to be executed after some time.

Declaration

public IInterval Repeat(Func<Terminal, Task> action, int intervalMillis, bool immediate = false)

Parameters

Type	Name	Description
Func<Terminal, Task>	action	The action to be executed.
int	intervalMillis	The interval in milliseconds.
bool	immediate	If true, triggers the execution of the action immediately.

Returns

Type	Description
IInterval	The interval object.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if intervalMillis is negative.

Repeat<TState>(Func<Terminal, TState?, Task>, int, bool, TState?)

Sets up a delayed action that is to be executed after some time.

Declaration

public IInterval Repeat<TState>(Func<Terminal, TState?, Task> action, int intervalMillis, bool immediate = false, TState? state = default)

Parameters

Type	Name	Description
Func<Terminal, TState, Task>	action	The action to be executed.
int	intervalMillis	The interval in milliseconds.
bool	immediate	If true, triggers the execution of the action immediately.
TState	state

Returns

Type	Description
IInterval	The interval object.

Type Parameters

Name	Description
TState

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if intervalMillis is negative.

Run(Func<ITerminal, Event, Task>, bool)

Runs the application main loop and dispatches each event to eventAction.

Declaration

public void Run(Func<ITerminal, Event, Task> eventAction, bool stopOnCtrlC = true)

Parameters

Type	Name	Description
Func<ITerminal, Event, Task>	eventAction	The method to accept the events.
bool	stopOnCtrlC	Set to true if CTRL+C should interrupt the main loop.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	Thrown when eventAction is null.
InvalidOperationException	Thrown if another Run(Func<ITerminal, Event, Task>, bool) is already running.
ObjectDisposedException	The terminal has been disposed.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
ArgumentNullException	Thrown when eventAction is null.
InvalidOperationException	Thrown if another Run(Func<ITerminal, Event, Task>, bool) is already running.

SetTitle(string)

Sets the terminal title.

Declaration

public void SetTitle(string title)

Parameters

Type	Name	Description
string	title	The title of the terminal.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Stop(bool)

Enqueues a stop signal for the Run(Func<ITerminal, Event, Task>, bool) method.

Declaration

public void Stop(bool wait = false)

Parameters

Type	Name	Description
bool	wait	If true, waits until running completes.

Implements

ITerminal

IDisposable