Class Cursor
A cursor that is attached to a Console used for printing.
Implements
Inherited Members
Namespace: SadConsole.Components
Assembly: SadConsole.dll
Syntax
[DataContract]
[JsonObject(MemberSerialization = MemberSerialization.OptIn)]
public class Cursor : IComponent
Constructors
Cursor()
Creates a new instance of the cursor as a component.
Declaration
public Cursor()
Cursor(ICellSurface)
Creates a new instance of the cursor that works with the specified surface.
Declaration
public Cursor(ICellSurface surface)
Parameters
Type | Name | Description |
---|---|---|
ICellSurface | surface |
Fields
DefaultCursorGlyph
The default glyph used for a new cursor. Value 219.
Declaration
public static readonly int DefaultCursorGlyph
Field Value
Type | Description |
---|---|
int |
Properties
ApplyCursorEffect
When false, prevents the CursorRenderEffect from being applied.
Declaration
public bool ApplyCursorEffect { get; set; }
Property Value
Type | Description |
---|---|
bool |
AutomaticallyShiftRowsUp
Indicates that when the cursor goes past the last cell of the console, that the rows should be shifted up when the cursor is automatically reset to the next line.
Declaration
[DataMember]
public bool AutomaticallyShiftRowsUp { get; set; }
Property Value
Type | Description |
---|---|
bool |
Column
Gets or sets the column of the cursor postion.
Declaration
public int Column { get; set; }
Property Value
Type | Description |
---|---|
int |
CursorGlyph
Sets the glyph used in rendering. A shortcut to CursorRenderCell.
Declaration
public int CursorGlyph { get; set; }
Property Value
Type | Description |
---|---|
int |
CursorRenderCell
Cell used to render the cursor on the screen.
Declaration
[DataMember(Order = 0)]
public ColoredGlyphBase CursorRenderCell { get; set; }
Property Value
Type | Description |
---|---|
ColoredGlyphBase |
CursorRenderCellActiveState
Used in rendering. The cell after the effect has been applied.
Declaration
public ColoredGlyphBase CursorRenderCellActiveState { get; }
Property Value
Type | Description |
---|---|
ColoredGlyphBase |
CursorRenderEffect
This is the cursor visible effect, like blinking.
Declaration
[DataMember]
public ICellEffect? CursorRenderEffect { get; set; }
Property Value
Type | Description |
---|---|
ICellEffect |
DisablePrintAutomaticLineFeed
When true, printing characters to the end of a line won't wrap to the next line. Defaults to false, which moves the cursor to the next line if printing goes past the end of the line.
Declaration
public bool DisablePrintAutomaticLineFeed { get; set; }
Property Value
Type | Description |
---|---|
bool |
DisableWordBreak
When true, prevents any print method from breaking words up by spaces when wrapping lines.
Declaration
[DataMember]
public bool DisableWordBreak { get; set; }
Property Value
Type | Description |
---|---|
bool |
IsEnabled
When false, prevents the cursor from running on the host.
Declaration
[DataMember]
public bool IsEnabled { get; set; }
Property Value
Type | Description |
---|---|
bool |
IsVisible
Shows or hides the cursor. This does not affect how the cursor operates.
Declaration
[DataMember]
public bool IsVisible { get; set; }
Property Value
Type | Description |
---|---|
bool |
MouseClickReposition
When true, left-clicking on the host surface will reposition the cursor to the clicked position.
Declaration
[DataMember]
public bool MouseClickReposition { get; set; }
Property Value
Type | Description |
---|---|
bool |
MouseClickRepositionHandlesMouse
When true, returns a handled status from the mouse processor when the MouseClickReposition is enabled. This prevents further left-mouse processing on the host.
Declaration
[DataMember]
public bool MouseClickRepositionHandlesMouse { get; set; }
Property Value
Type | Description |
---|---|
bool |
Position
Gets or sets the location of the cursor on the console.
Declaration
[DataMember]
public Point Position { get; set; }
Property Value
Type | Description |
---|---|
Point |
PrintAppearance
Appearance used when printing text. PrintOnlyCharacterData must be set to false for this to apply.
Declaration
[DataMember]
public ColoredGlyphBase PrintAppearance { get; set; }
Property Value
Type | Description |
---|---|
ColoredGlyphBase |
PrintAppearanceMatchesHost
When true, printing will use the host's DefaultForeground and DefaultBackground color properties.
Declaration
[DataMember]
public bool PrintAppearanceMatchesHost { get; set; }
Property Value
Type | Description |
---|---|
bool |
PrintEffect
This effect is applied to each cell printed by the cursor.
Declaration
[DataMember]
public ICellEffect? PrintEffect { get; set; }
Property Value
Type | Description |
---|---|
ICellEffect |
PrintOnlyCharacterData
When true, indicates that the cursor, when printing, should not use the PrintAppearance property in determining the color/effect of the cell, but keep the cell the same as it was.
Declaration
[DataMember]
public bool PrintOnlyCharacterData { get; set; }
Property Value
Type | Description |
---|---|
bool |
Row
Gets or sets the row of the cursor postion.
Declaration
public int Row { get; set; }
Property Value
Type | Description |
---|---|
int |
SortOrder
Sets the sort order of this component within the host.
Declaration
[DataMember]
public uint SortOrder { get; set; }
Property Value
Type | Description |
---|---|
uint |
UseLinuxLineEndings
Enables linux-like string parsing where a \n behaves like a \r\n.
Declaration
[DataMember]
public bool UseLinuxLineEndings { get; set; }
Property Value
Type | Description |
---|---|
bool |
UsePrintEffect
When true, applies the PrintEffect to the cursor when it prints.
Declaration
[DataMember]
public bool UsePrintEffect { get; set; }
Property Value
Type | Description |
---|---|
bool |
UseStringParser
Indicates this cursor should process te string through the Parse(ReadOnlySpan<char>, int, ICellSurface?, ParseCommandStacks?) method from Parser to create a colored string when using Print(string) or Print(string, ColoredGlyphBase, ICellEffect?).
Declaration
[DataMember]
public bool UseStringParser { get; set; }
Property Value
Type | Description |
---|---|
bool |
Methods
ApplyDefaultCursorEffect()
Resets the CursorRenderEffect back to the default.
Declaration
public Cursor ApplyDefaultCursorEffect()
Returns
Type | Description |
---|---|
Cursor |
CarriageReturn()
Returns the cursor to the start of the current line.
Declaration
public Cursor CarriageReturn()
Returns
Type | Description |
---|---|
Cursor | The current cursor object. |
Down(int)
Moves the cusor down by the specified amount of lines.
Declaration
public Cursor Down(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of lines to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
Erase(int)
Clears the cell at the position of the cursor.
Declaration
public Cursor Erase(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cell. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseColumn(int)
Clears the cells in the same column as the cursor.
Declaration
public Cursor EraseColumn(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseDown(int)
Clears the cells below the cursor.
Declaration
public Cursor EraseDown(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseLeft(int)
Clears the cells to the left of the cursor.
Declaration
public Cursor EraseLeft(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseRight(int)
Clears the cells to the right of the cursor.
Declaration
public Cursor EraseRight(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseRow(int)
Clears the cells in the same row as the cursor.
Declaration
public Cursor EraseRow(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
EraseUp(int)
Clears the cells above the cursor.
Declaration
public Cursor EraseUp(int glyph = 0)
Parameters
Type | Name | Description |
---|---|---|
int | glyph | The glyph to set on the erased cells. Defaults to glyph index 0. |
Returns
Type | Description |
---|---|
Cursor | The cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when a host isn't attached to the cursor. |
Left(int)
Moves the cusor left by the specified amount of columns.
Declaration
public Cursor Left(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of columns to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
LeftWrap(int)
Moves the cusor left by the specified amount of columns, wrapping the cursor if needed.
Declaration
public Cursor LeftWrap(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of columns to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
LineFeed()
Moves the cursor down a line.
Declaration
public Cursor LineFeed()
Returns
Type | Description |
---|---|
Cursor | The current cursor object. |
Move(Point)
Moves the cursor to the specified position.
Declaration
public Cursor Move(Point position)
Parameters
Type | Name | Description |
---|---|---|
Point | position | The destination of the cursor. |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
Move(int, int)
Moves the cursor to the specified position.
Declaration
public Cursor Move(int x, int y)
Parameters
Type | Name | Description |
---|---|---|
int | x | The x (horizontal) of the position. |
int | y | The x (vertical) of the position. |
Returns
Type | Description |
---|---|
Cursor |
NewLine()
Calls the CarriageReturn() and LineFeed() methods in a single call.
Declaration
public Cursor NewLine()
Returns
Type | Description |
---|---|
Cursor | The current cursor object. |
Print(ColoredString)
Prints text to the console using the appearance of the colored string.
Declaration
public Cursor Print(ColoredString text)
Parameters
Type | Name | Description |
---|---|---|
ColoredString | text | The text to print. |
Returns
Type | Description |
---|---|
Cursor | Returns this cursor object. |
Print(string)
Prints text to the console using the default print appearance.
Declaration
public Cursor Print(string text)
Parameters
Type | Name | Description |
---|---|---|
string | text | The text to print. |
Returns
Type | Description |
---|---|
Cursor | Returns this cursor object. |
Print(string, ColoredGlyphBase, ICellEffect?)
Prints text on the console.
Declaration
public Cursor Print(string text, ColoredGlyphBase template, ICellEffect? templateEffect)
Parameters
Type | Name | Description |
---|---|---|
string | text | The text to print. |
ColoredGlyphBase | template | The way the text will look when it is printed. |
ICellEffect | templateEffect | Effect to apply to the text as its printed. Can be null. |
Returns
Type | Description |
---|---|
Cursor | Returns this cursor object. |
PrintCoroutine(ColoredString)
Prints text to the console using the appearance of the colored string, but with coroutine.
Declaration
public IEnumerator<Wait> PrintCoroutine(ColoredString text)
Parameters
Type | Name | Description |
---|---|---|
ColoredString | text | The text to print. |
Returns
Type | Description |
---|---|
IEnumerator<Wait> | An enumerator that returns at each character printed. |
RestartCursorEffect()
Clones and reassigns CursorRenderEffect to restart it.
Declaration
public Cursor RestartCursorEffect()
Returns
Type | Description |
---|---|
Cursor |
Right(int)
Moves the cusor right by the specified amount of columns.
Declaration
public Cursor Right(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of columns to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
RightWrap(int)
Moves the cusor right by the specified amount of columns, wrapping the cursor if needed.
Declaration
public Cursor RightWrap(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of columns to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
SetPrintAppearance(ColoredGlyphBase)
Sets PrintAppearance.
Declaration
public Cursor SetPrintAppearance(ColoredGlyphBase appearance)
Parameters
Type | Name | Description |
---|---|---|
ColoredGlyphBase | appearance | The appearance to set. |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
SetPrintAppearance(Color)
Sets PrintAppearance, only changing the foreground color.
Declaration
public Cursor SetPrintAppearance(Color foreground)
Parameters
Type | Name | Description |
---|---|---|
Color | foreground | The foreground color. |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
SetPrintAppearance(Color, Color)
Sets PrintAppearance.
Declaration
public Cursor SetPrintAppearance(Color foreground, Color background)
Parameters
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
SetPrintAppearanceToHost()
Sets the cursor appearance to the console's default foreground and background.
Declaration
public Cursor SetPrintAppearanceToHost()
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
Exceptions
Type | Condition |
---|---|
Exception | Thrown when the cursor is not attached to any surface. |
Up(int)
Moves the cusor up by the specified amount of lines.
Declaration
public Cursor Up(int amount)
Parameters
Type | Name | Description |
---|---|---|
int | amount | The amount of lines to move the cursor |
Returns
Type | Description |
---|---|
Cursor | This cursor object. |
Events
KeyboardPreview
Raised when the keyboard is processing keys. Each key is sent to this event and can be cancelled
Declaration
public event EventHandler<KeyboardHandledKeyEventArgs>? KeyboardPreview
Event Type
Type | Description |
---|---|
EventHandler<KeyboardHandledKeyEventArgs> |