Class Surface

Represents a surface and contains all its functionality.

Inheritance

Surface

Implements

ISurface

IDrawSurface

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Sharpie

Assembly: sharpie.dll

Syntax

[PublicAPI]
public abstract class Surface : ISurface, IDrawSurface, IDisposable

Properties

Area

Gets the area of the surface based on the Origin and Size.

Declaration

protected Rectangle Area { get; }

Property Value

Type	Description
Rectangle

Background

Gets or sets the surface background.

Declaration

public (Rune @char, Style style) Background { get; set; }

Property Value

Type	Description
(Rune char, Style style)

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

CaretLocation

Gets or sets the current position of the caret within the surface.

Declaration

public Point CaretLocation { get; set; }

Property Value

Type	Description
Point

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The `value` is outside the surface bounds.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

ColorMixture

Gets or sets the color mixture of the surface.

Declaration

public ColorMixture ColorMixture { get; set; }

Property Value

Type	Description
ColorMixture

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Curses

The curses backend.

Declaration

protected ICursesBackend Curses { get; }

Property Value

Type	Description
ICursesBackend

Dirty

Specifies whether the surface has some "dirty" parts that need to be synchronized to the console.

Declaration

public bool Dirty { get; }

Property Value

Type	Description
bool

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Disposed

Checks if the surface has been disposed and is no longer usable.

Declaration

public bool Disposed { get; }

Property Value

Type	Description
bool

Handle

The Curses handle for the surface.

Declaration

public nint Handle { get; }

Property Value

Type	Description
nint

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
ObjectDisposedException	Surface is no longer usable.

ManagedCaret

Controls whether the caret is managed by the application and should not be managed by the hardware.

Declaration

public bool ManagedCaret { get; set; }

Property Value

Type	Description
bool

Remarks

This operation is not thread safe.

Exceptions

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

Origin

Returns the origin of the surface (location within a potential parent). This implementation always returns (0, 0).

Declaration

protected virtual Point Origin { get; }

Property Value

Type	Description
Point

Scrollable

Gets or sets the ability of the surface to scroll its contents when writing needs a new line.

Declaration

public bool Scrollable { get; set; }

Property Value

Type	Description
bool

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Size

Gets the size of the surface.

Declaration

public Size Size { get; }

Property Value

Type	Description
Size

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Style

Gets or sets the style of the surface.

Declaration

public Style Style { get; set; }

Property Value

Type	Description
Style

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

Methods

AssertAlive()

Asserts that the surface is not disposed.

Declaration

protected void AssertAlive()

Exceptions

Type	Condition
ObjectDisposedException	The surface has been disposed.

AssertSynchronized()

Asserts that executing thread is bound to the correct synchronization context.

Declaration

protected abstract void AssertSynchronized()

Exceptions

Type	Condition
CursesSynchronizationException	Thrown if current thread is not bound to the correct context.

ChangeTextStyle(int, Style)

Changes the style of the text on the current line and starting from the caret position.

Declaration

public void ChangeTextStyle(int width, Style style)

Parameters

Type	Name	Description
int	width	The number of characters to change.
Style	style	The applied style.

Remarks

This operation is not thread safe.

Exceptions

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

Clear(ClearStrategy)

Clears the contents of the row/surface.

Declaration

public void Clear(ClearStrategy strategy = ClearStrategy.Full)

Parameters

Type	Name	Description
ClearStrategy	strategy	The strategy to use.

Remarks

This operation is not thread safe.

Exceptions

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

Delete()

Deletes the surface from the curses backend.

Declaration

protected virtual void Delete()

DeleteLines(int)

Deletes lines lines starting with the current caret position. All lines below move up.

Declaration

public void DeleteLines(int lines)

Parameters

Type	Name	Description
int	lines	Number of lines to inserts.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The `lines` is less than one or greater than the size of the surface.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

Destroy()

Removes the surface form the parent, destroys all children and itself.

Declaration

public void Destroy()

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.

DisableAttributes(VideoAttribute)

Disables specified attributes and keep the others untouched.

Declaration

public void DisableAttributes(VideoAttribute attributes)

Parameters

Type	Name	Description
VideoAttribute	attributes	The attributes to disable.

Remarks

This operation is not thread safe.

Exceptions

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

Dispose()

Disposes the current instance.

Declaration

public void Dispose()

Draw(Point, IDrawable)

Draws a given drawable to the surface.

Declaration

public void Draw(Point location, IDrawable drawable)

Parameters

Type	Name	Description
Point	location	The location of the drawing.
IDrawable	drawable	The drawing to draw.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `drawable` is `null`.
ArgumentOutOfRangeException	Thrown if `location` is out of bounds.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

Draw(Point, Rectangle, IDrawable)

Draws a given drawable to the surface.

Declaration

public void Draw(Point location, Rectangle area, IDrawable drawable)

Parameters

Type	Name	Description
Point	location	The location of the drawing.
Rectangle	area	The area of the drawing to draw.
IDrawable	drawable	The drawing to draw.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `drawable` is `null`.
ArgumentOutOfRangeException	Thrown if `location` or `area` are out of bounds.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

DrawBorder()

Draws a border around the surface's edges using standard characters.

Declaration

public void DrawBorder()

Remarks

This operation is not thread safe.

Exceptions

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

DrawBorder(Rune, Rune, Rune, Rune, Rune, Rune, Rune, Rune, Style)

Draws a vertical line from the current caret position downwards.

Declaration

public void DrawBorder(Rune leftSideChar, Rune rightSideChar, Rune topSideChar, Rune bottomSideChar, Rune topLeftCornerChar, Rune topRightCornerChar, Rune bottomLeftCornerChar, Rune bottomRightCornerChar, Style style)

Parameters

Type	Name	Description
Rune	leftSideChar	The left-side character.
Rune	rightSideChar	The right-side character.
Rune	topSideChar	The top-side character.
Rune	bottomSideChar	The bottom-side character.
Rune	topLeftCornerChar	The top-left corner character.
Rune	topRightCornerChar	The top-right corner character.
Rune	bottomLeftCornerChar	The bottom-left corner character.
Rune	bottomRightCornerChar	The bottom-right corner character.
Style	style	The style to use.

Remarks

This operation is not thread safe.

Exceptions

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

DrawHorizontalLine(int)

Draws a horizontal line using the standard line character from the current caret position downwards.

Declaration

public void DrawHorizontalLine(int length)

Parameters

Type	Name	Description
int	length	The length of the line.

Remarks

This operation is not thread safe.

Exceptions

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

DrawHorizontalLine(int, Rune, Style)

Draws a horizontal line from the current caret position downwards.

Declaration

public void DrawHorizontalLine(int length, Rune @char, Style style)

Parameters

Type	Name	Description
int	length	The length of the line.
Rune	char	The character to use for the line.
Style	style	The style to use.

Remarks

This operation is not thread safe.

Exceptions

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

DrawText(IAsciiFont, string, Style, bool, bool)

Draws text using an ASCII font at the caret position at the current surface and advances the caret.

Declaration

public void DrawText(IAsciiFont font, string text, Style style, bool interpretSpecialChars = true, bool wrap = true)

Parameters

Type	Name	Description
IAsciiFont	font	The ASCII font to draw with.
string	text	The text to write.
Style	style	The style of the text.
bool	interpretSpecialChars	If `true`, special characters will be treated as such (e.g. \n)
bool	wrap	If `true`, text will be wrapped automatically to next line.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `font` or `text` are `null`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

DrawText(IAsciiFont, string, bool, bool)

Draws text using an ASCII font at the caret position at the current surface and advances the caret.

Declaration

public void DrawText(IAsciiFont font, string text, bool interpretSpecialChars = true, bool wrap = true)

Parameters

Type	Name	Description
IAsciiFont	font	The ASCII font to draw with.
string	text	The text to write.
bool	interpretSpecialChars	If `true`, special characters will be treated as such (e.g. \n)
bool	wrap	If `true`, text will be wrapped automatically to next line.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `font` or `text` are `null`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

DrawVerticalLine(int)

Draws a vertical line using the standard line character from the current caret position downwards.

Declaration

public void DrawVerticalLine(int length)

Parameters

Type	Name	Description
int	length	The length of the line.

Remarks

This operation is not thread safe.

Exceptions

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

DrawVerticalLine(int, Rune, Style)

Draws a vertical line from the current caret position downwards.

Declaration

public void DrawVerticalLine(int length, Rune @char, Style style)

Parameters

Type	Name	Description
int	length	The length of the line.
Rune	char	The character to use for the line.
Style	style	The style to use.

Remarks

This operation is not thread safe.

Exceptions

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

EnableAttributes(VideoAttribute)

Enables specified attributes and keep the others untouched.

Declaration

public void EnableAttributes(VideoAttribute attributes)

Parameters

Type	Name	Description
VideoAttribute	attributes	The attributes to enable.

Remarks

This operation is not thread safe.

Exceptions

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

~Surface()

The destructor. Calls Destroy().

Declaration

protected ~Surface()

GetText(int)

Gets the text from the surface at the caret position to the right.

Declaration

public (Rune @char, Style style)[] GetText(int count)

Parameters

Type	Name	Description
int	count	The number of characters to get.

Returns

Type	Description
(Rune char, Style style)[]

Remarks

This operation is not thread safe.

Exceptions

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

InsertEmptyLines(int)

Inserts lines empty lines at the current caret position.

Declaration

public void InsertEmptyLines(int lines)

Parameters

Type	Name	Description
int	lines	Number of lines to inserts.

Remarks

This operation is not thread safe.

Exceptions

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

IsPointWithin(Point)

Checks if a given point fits within the current surface.

Declaration

public bool IsPointWithin(Point point)

Parameters

Type	Name	Description
Point	point

Returns

Type	Description
bool	The result of the check.

Remarks

This operation is not thread safe.

Exceptions

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

IsRectangleWithin(Rectangle)

Checks if a given rectangle fits within the current surface.

Declaration

public bool IsRectangleWithin(Rectangle rect)

Parameters

Type	Name	Description
Rectangle	rect

Returns

Type	Description
bool	The result of the check.

Remarks

This operation is not thread safe.

Exceptions

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

LineDirty(int)

Checks if the line at y is dirty.

Declaration

public bool LineDirty(int y)

Parameters

Type	Name	Description
int	y

Returns

Type	Description
bool

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.

MarkDirty()

Marks the entire contents of the surface as Dirty.

Declaration

public void MarkDirty()

Remarks

This operation is not thread safe.

Exceptions

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

MarkDirty(int, int)

Marks a number of lines within the surface as Dirty.

Declaration

public virtual void MarkDirty(int y, int count)

Parameters

Type	Name	Description
int	y	The line to start with.
int	count	The count of lines to mark dirty.

Remarks

This operation is not thread safe.

Exceptions

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

NextLine()

Helper method that moves the caret to the start of the next line. If the surface is Scrollable, and the caret if on the last line, it will push the contents of the surface up by one line.

Declaration

public void NextLine()

Remarks

This operation is not thread safe.

Exceptions

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

RemoveText(int)

Removes the text under the caret and moves the contents of the line to the left.

Declaration

public void RemoveText(int count)

Parameters

Type	Name	Description
int	count	The number of characters to remove.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
ArgumentOutOfRangeException	The `count` less than one.

Replace(ISurface, ReplaceStrategy)

Replaces the content of a given surface with the contents of the current surface.

Declaration

public virtual void Replace(ISurface surface, ReplaceStrategy strategy)

Parameters

Type	Name	Description
ISurface	surface	The surface to copy contents to.
ReplaceStrategy	strategy	The used strategy.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	The `surface` is null.
ArgumentException	The contents of `surface` cannot be replaced.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

Replace(ISurface, Rectangle, Point, ReplaceStrategy)

Replaces the content of a given surface with the contents of the current surface.

Declaration

public void Replace(ISurface surface, Rectangle srcRect, Point destPos, ReplaceStrategy strategy)

Parameters

Type	Name	Description
ISurface	surface	The surface to copy contents to.
Rectangle	srcRect	The source rectangle to copy.
Point	destPos	The destination position.
ReplaceStrategy	strategy	The used strategy.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	The `surface` is null.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

ScrollDown(int)

Scrolls the contents of the surface lines down. Only works for scrollable surfaces.

Declaration

public void ScrollDown(int lines)

Parameters

Type	Name	Description
int	lines	Number of lines to scroll.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
NotSupportedException	The Scrollable is `false`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

ScrollUp(int)

Scrolls the contents of the surface lines up. Only works for scrollable surfaces.

Declaration

public void ScrollUp(int lines)

Parameters

Type	Name	Description
int	lines	Number of lines to scroll.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The `lines` is less than one or greater than the size of the surface.
NotSupportedException	The Scrollable is `false`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

ToString()

Returns a string that represents the current object.

Declaration

public override string ToString()

Returns

Type	Description
string	A string that represents the current object.

Overrides

object.ToString()

WriteText(StyledText, bool)

Writes a text at the caret position at the current surface and advances the caret.

Declaration

public void WriteText(StyledText text, bool wrap = true)

Parameters

Type	Name	Description
StyledText	text	The styled text to write.
bool	wrap	If `true`, text will be wrapped automatically to next line.

Remarks

This operation is not thread safe.

Exceptions

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

WriteText(string, Style, bool)

Writes a text at the caret position at the current surface and advances the caret.

Declaration

public void WriteText(string text, Style style, bool wrap = true)

Parameters

Type	Name	Description
string	text	The text to write.
Style	style	The style of the text.
bool	wrap	If `true`, text will be wrapped automatically to next line.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	The `text` is `null`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

WriteText(string, bool)

Writes a text at the caret position at the current surface and advances the caret.

Declaration

public void WriteText(string text, bool wrap = true)

Parameters

Type	Name	Description
string	text	The text to write.
bool	wrap	If `true`, text will be wrapped automatically to next line.

Remarks

This operation is not thread safe.

Exceptions

Type	Condition
ArgumentNullException	The `text` is `null`.
ObjectDisposedException	Surface is no longer usable.
CursesSynchronizationException	Thrown if this operation was expected to run on the main thread/context but wasn't.
CursesOperationException	A Curses error occurred.

Implements

ISurface

IDrawSurface

IDisposable