Class TextInput

Namespace

MLEM.Input

Assembly

MLEM.dll

A class that contains all of the necessary tools to create a text input field or box. This text input features single- and Multiline input, InputRule sets, free caret movement, copying and pasting, and more. To use this class, OnTextInput(Keys, char), Update(GameTime, InputHandler) and Draw(SpriteBatch, Vector2, float, float, Color) have to be called regularly. While this class is used by MLEM.Ui's TextField, it is designed to be used for custom or external UI systems.

public class TextInput

Inheritance

object

TextInput

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Constructors

TextInput(GenericFont, Vector2, float, Rule, Action<string>, Func<string>)

Creates a new text input with the given settings.

public TextInput(GenericFont font, Vector2 size, float textScale, TextInput.Rule inputRule = null, Action<string> copyToClipboardFunction = null, Func<string> pasteFromClipboardFunction = null)

Parameters

font GenericFont

The Font to use.

size Vector2

The Size to set.

textScale float

The TextScale to set.

inputRule TextInput.Rule

The InputRule to set.

copyToClipboardFunction Action<string>

The CopyToClipboardFunctionto set.

pasteFromClipboardFunction Func<string>

The PasteFromClipboardFunction to set.

Fields

CopyToClipboardFunction

A function that is invoked when a string of text should be copied to the clipboard. MLEM.Ui uses the TextCopy package for this, but other options are available.

public Action<string> CopyToClipboardFunction

Field Value

Action<string>

DefaultRule

A TextInput.Rule that allows any visible character and spaces

public static readonly TextInput.Rule DefaultRule

Field Value

TextInput.Rule

FileNames

A TextInput.Rule that only allows characters not contained in GetInvalidFileNameChars()

public static readonly TextInput.Rule FileNames

Field Value

TextInput.Rule

InputRule

The rule used for text input. Rules allow only certain characters to be allowed inside of a text input.

public TextInput.Rule InputRule

Field Value

TextInput.Rule

LettersNumbers

A TextInput.Rule that only allows letters and numerals

public static readonly TextInput.Rule LettersNumbers

Field Value

TextInput.Rule

MaximumCharacters

The maximum amount of characters that can be input into this text input. If this is set, the length of Text will never exceed this value.

public int? MaximumCharacters

Field Value

int?

OnTextChange

An event that gets called when Text changes, either through input, or through a manual change.

public TextInput.TextChanged OnTextChange

Field Value

TextInput.TextChanged

OnlyLetters

A TextInput.Rule that only allows letters

public static readonly TextInput.Rule OnlyLetters

Field Value

TextInput.Rule

OnlyNumbers

A TextInput.Rule that only allows numerals

public static readonly TextInput.Rule OnlyNumbers

Field Value

TextInput.Rule

PasteFromClipboardFunction

A function that is invoked when a string of text should be pasted from the clipboard. MLEM.Ui uses the TextCopy package for this, but other options are available.

public Func<string> PasteFromClipboardFunction

Field Value

Func<string>

PathNames

A TextInput.Rule that only allows characters not contained in GetInvalidPathChars()

public static readonly TextInput.Rule PathNames

Field Value

TextInput.Rule

Properties

CaretLine

The line of text that the caret is currently on. This can only be only non-0 if Multiline is true.

public int CaretLine { get; }

Property Value

int

CaretPos

The position of the caret within the text. This is always between 0 and the Length of Text

public int CaretPos { get; set; }

Property Value

int

CaretPosInLine

The position in the current CaretLine that the caret is currently on. If Multiline is false, this value is always equal to CaretPos.

public int CaretPosInLine { get; }

Property Value

int

FirstVisibleLine

The index of the first line that is currently visible. This value can be changed using ShowLine(int).

public int FirstVisibleLine { get; }

Property Value

int

Font

The font that this text input is currently using.

public GenericFont Font { get; set; }

Property Value

GenericFont

Length

The length that this TextInput's text has.

public int Length { get; }

Property Value

int

Lines

The total amount of lines of text that this text input currently has, including additional lines added by automatic wrapping. If this is not a Multiline text input, this value is always 1.

public int Lines { get; }

Property Value

int

MaskingCharacter

A character that should be displayed instead of this text input's Text content. The amount of masking characters displayed will be equal to the Text's length. This behavior is useful for password inputs or similar.

public char? MaskingCharacter { get; set; }

Property Value

char?

MaxDisplayedLines

The maximum amount of lines that can be visible in this text input, based on its Size, the used Font and its TextScale. Note that this may return a number higher than 1 even if this is not a Multiline text input.

public int MaxDisplayedLines { get; }

Property Value

int

Multiline

Whether this text input should support multi-line editing. If this is true, pressing Microsoft.Xna.Framework.Input.Keys.Enter will insert a new line into the Text if the InputRule allows it. Additionally, text will be rendered with horizontal soft wraps, and lines that are outside of the text input's bounds will be hidden.

public bool Multiline { get; set; }

Property Value

bool

Size

The size of this text input, which is the size that this text input's Text will be bounded to in Draw(SpriteBatch, Vector2, float, float, Color). Note that TextScale gets applied to the text for calculations involving this size.

public Vector2 Size { get; set; }

Property Value

Vector2

Text

This text input's current text

public string Text { get; }

Property Value

string

TextScale

The scale that this text input's text has. In Draw(SpriteBatch, Vector2, float, float, Color), this is multiplied with the drawScale parameter.

public float TextScale { get; set; }

Property Value

float

Methods

Draw(SpriteBatch, Vector2, float, float, Color)

Draws this text input's displayed Text along with its caret, if caretWidth is greater than 0.

public void Draw(SpriteBatch batch, Vector2 textPos, float drawScale, float caretWidth, Color textColor)

Parameters

batch SpriteBatch

The sprite batch to draw with.

textPos Vector2

The position to draw the text at.

drawScale float

The draw scale, which is multiplied with TextScale before drawing.

caretWidth float

The width that the caret should have, which is multiplied with drawScale before drawing.

textColor Color

The color to draw the text and caret with.

InsertText(object, bool)

Inserts the given text at the CaretPos. If the resulting Text exceeds MaximumCharacters, the end will be cropped to fit.

public bool InsertText(object text, bool removeMismatching = false)

Parameters

text object

The text to insert

removeMismatching bool

If any characters that don't match the InputRule should be left out

Returns

bool

MoveCaretToLine(int)

Moves the CaretPos to the given line, if it exists. Additionally maintains the CaretPosInLine roughly based on the visual distance that the caret has from the left border of the current CaretLine.

public bool MoveCaretToLine(int line)

Parameters

line int

The line to move the caret to

Returns

bool

True if the caret was moved, false if it was not (which indicates that the line with the given line index does not exist)

OnTextInput(Keys, char)

A method that should be called when the given text should be entered into this text input. This method is designed to be used with AddTextInputListener(GameWindow, TextInputCallback) or the TextInput event provided by MonoGame and FNA.

public bool OnTextInput(Keys key, char character)

Parameters

key Keys

The key that was pressed.

character char

The character that the key represents.

Returns

bool

Whether text was successfully input.

RemoveText(int, int)

Removes the given amount of text at the given index

public bool RemoveText(int index, int length)

Parameters

index int

The index

length int

The amount of text to remove

Returns

bool

SetText(object, bool)

Replaces this text input's text with the given text. If the resulting Text exceeds MaximumCharacters, the end will be cropped to fit.

public void SetText(object text, bool removeMismatching = false)

Parameters

text object

The new text

removeMismatching bool

If any characters that don't match the InputRule should be left out

ShowLine(int)

Moves visual focus into such bounds that the given line will be the first visible line of this text input.

public bool ShowLine(int line)

Parameters

line int

The first line that should be visible.

Returns

bool

Whether the line can be the fist visible line, and wasn't already the first visible line.

Update(GameTime, InputHandler)

Updates this text input, including querying input using the given InputHandler and updating the caret's blink timer.

public void Update(GameTime time, InputHandler input)

Parameters

time GameTime

The current game time.

input InputHandler

The input handler to use for input querying.