Class TextInput

Framework View

The tag name of this view is <textinput>.

Definition

Namespace: StardewUI.Widgets
Assembly: StardewUI.dll

A text input field that allows typing from a physical or virtual keyboard.

[StardewUI.GenerateDescriptor]
public class TextInput : StardewUI.View, 
    StardewUI.Input.IKeyboardSubscriberOwnerView

Inheritance
Object ⇦ View ⇦ TextInput

Implements
IKeyboardSubscriberOwnerView

Members

Constructors

Name	Description
TextInput()	Initializes a new TextInput.

Fields

Name	Description
ParentScrollingBounds	The parent scrolling bounds propagated down from an ancestor ScrollContainer. (Inherited from View)

Properties

Name	Description
ActualBounds `actual-bounds`	The bounds of this view relative to the origin (0, 0). (Inherited from View)
Background `background`	For compatibility reasons Background is alias for Border. `(unofficial-mushymato)`
Border `border`	`(unofficial-mushymato)`
BorderSize `border-size`	The layout size (not edge thickness) of the entire drawn area including the border, i.e. the InnerSize plus any borders defined in GetBorderThickness(). Does not include the Margin. (Inherited from View)
BorderThickness `border-thickness`	The thickness of the border edges.
Caret `caret`	Sprite to draw for the cursor showing the current text position.
CaretPosition `caret-position`	The zero-based position of the caret within the text.
CaretSelectionSize `caret-selection-size`	Number of characters selected, stored as number of characters before or after the caret. `(unofficial-mushymato)`
CaretWidth `caret-width`	The width to draw the Caret, if different from the sprite's source width.
ClipOrigin `clip-origin`	Origin position for the ClipSize. (Inherited from View)
ClipSize `clip-size`	Size of the clipping rectangle, outside which content will not be displayed. (Inherited from View)
ContentBounds `content-bounds`	The true bounds of this view's content; i.e. ActualBounds excluding margins. (Inherited from View)
ContentSize `content-size`	The size of the view's content, which is drawn inside the padding. Subclasses set this in their OnMeasure(Vector2) method and padding, margins, etc. are handled automatically. (Inherited from View)
Draggable `draggable`	Whether or not this view should fire drag events such as DragStart and Drag. (Inherited from View)
Enabled `enabled`	Whether the input is enabled.
FloatingBounds `floating-bounds`	Contains the bounds of all floating elements in this view tree, including the current view and all descendants. (Inherited from View)
FloatingElements `floating-elements`	The floating elements to display relative to this view. (Inherited from View)
Focusable `focusable`	Whether or not the view should be able to receive focus. Applies only to this specific view, not its children. (Inherited from View)
FocusableTag `focusable-tag`	A string tag that identifies this view for use in FocusOnTaggedView(string). (Inherited from View)
Font `font`	The font with which to render text. Defaults to smallFont.
HandlesOpacity `handles-opacity`	Whether the specific view type handles its own opacity. (Inherited from View)
HoveredSubject `hovered-subject`	When Lookup Anything (Pathoschild.LookupAnything) is loaded, this Object or NPC subject is given to lookup anything for it's menu. `(unofficial-mushymato)` (Inherited from View)
InnerSize `inner-size`	The size allocated to the entire area inside the border, i.e. ContentSize plus any Padding. Does not include border or Margin. (Inherited from View)
IsFocusable `is-focusable`	Whether or not the view can receive controller focus, i.e. the stick/d-pad controlled cursor can move to this view. Not generally applicable for mouse controls. (Inherited from View)
IsWithinScrollBounds `is-within-scroll-bounds`	Whether this view is currently within the scrolling bounds, updated during Measure(Vector2). (Inherited from View)
ItemSpan `item-span`	Item span that defines how many cells this item takes up when it's the child of a grid. Span only considers the primary orientation and cannot exceed one row/col When this is -1, take the remainder of the row/col. `(unofficial-mushymato)` (Inherited from View)
LastAvailableSize `last-available-size`	The most recent size used in a Measure(Vector2) pass. Used for additional dirty checks. (Inherited from View)
Layout `layout`	Layout settings for this view; determines how its dimensions will be computed. (Inherited from View)
LayoutOffset `layout-offset`	Pixel offset of the view's content, which is applied to all pointer events and child queries. (Inherited from View)
Margin `margin`	Margins (whitespace outside border) for this view. (Inherited from View)
MaxLength `max-length`	The maximum number of characters allowed in this field.
Name `name`	Simple name for this view, used in log/debug output; does not affect behavior. (Inherited from View)
Opacity `opacity`	Opacity (alpha level) of the view. (Inherited from View)
OuterSize `outer-size`	The size of the entire area occupied by this view including margins, border and padding. (Inherited from View)
Padding `padding`	Padding (whitespace inside border) for this view. (Inherited from View)
Placeholder `placeholder`	Placeholder text to display when the Text is empty and input is not captured.
PlaceholderColor `placeholder-color`	Color of the Placeholder text when displayed.
PointerEventsEnabled `pointer-events-enabled`	Whether this view should receive pointer events like Click or Drag. (Inherited from View)
PointerStyle `pointer-style`	Pointer style to use when this view is hovered. (Inherited from View)
ScreenRead `screen-read`	When a screen reader mod (shoaib.stardewaccess) is loaded, this element will be announced by the screen reader using this value. `(unofficial-mushymato)` (Inherited from View)
ScrollWithChildren `scroll-with-children`	If set to an axis, specifies that when any child of the view is scrolled into view (using ScrollIntoView(IEnumerable<ViewChild>, Vector2)), then this entire view should be scrolled along with it. (Inherited from View)
SelectedText `selected-text`	Read-only property for selected text, set via changes to CaretSelectionSize. `(unofficial-mushymato)`
ShadowAlpha `shadow-alpha`	Alpha value for the shadow. If set to the default of zero, no shadow will be drawn.
ShadowOffset `shadow-offset`	Offset to draw the sprite shadow, which is a second copy of the Background drawn entirely black. Shadows will not be visible unless ShadowAlpha is non-zero.
Tags `tags`	The user-defined tags for this view. (Inherited from View)
Text `text`	The text currently entered.
TextColor `text-color`	Color of displayed text, as well as the Caret tint color.
Tooltip `tooltip`	Localized tooltip to display on hover, if any. (Inherited from View)
Transform `transform`	Local transformation to apply to this view, including any children and floating elements. (Inherited from View)
TransformOrigin `transform-origin`	Relative origin position for any Transform on this view. (Inherited from View)
Visibility `visibility`	Visibility for this view. (Inherited from View)
ZIndex `z-index`	Z order for this view within its direct parent. Higher indices draw later (on top). (Inherited from View)

Methods

Name	Description
ContainsPoint(Vector2)	Checks if a given point, relative to the view's origin, is within its bounds. (Inherited from View)
Dispose()	(Inherited from View)
Draw(ISpriteBatch)	Draws the content for this view. (Inherited from View)
FindFocusableDescendant(Vector2, Direction)	Searches for a focusable child within this view that is reachable in the specified `direction`, and returns a result containing the view and search path if found. (Inherited from View)
FocusSearch(Vector2, Direction)	Finds the next focusable component in a given direction that does not overlap with a current position. (Inherited from View)
GetBorderThickness()	Measures the thickness of each edge of the border, if the view has a border. (Inherited from View)
GetChildAt(Vector2, Boolean, Boolean)	Finds the child at a given position. (Inherited from View)
GetChildPosition(IView)	Computes or retrieves the position of a given direct child. (Inherited from View)
GetChildren(Boolean)	Gets the current children of this view. (Inherited from View)
GetChildrenAt(Vector2)	Finds all children at a given position. (Inherited from View)
GetDefaultFocusChild()	Gets the direct child that should contain cursor focus when a menu or overlay containing this view is first opened. (Inherited from View)
GetLocalChildren()	Gets the view's children with positions relative to the content area. (Overrides View.GetLocalChildren())
GetLocalChildrenAt(Vector2)	Searches for all views at a given position relative to the content area. (Inherited from View)
HandleSpecialKey(Keys)	Handle non-text entry key.
HasOutOfBoundsContent()	Checks if the view has content or elements that are all or partially outside the ActualBounds. (Inherited from View)
HasOwnContent()	Checks if this view displays its own content, independent of any floating elements or children. (Inherited from View)
InsertChar(Char)	Accept new entered char
InsertString(string)	Accept new entered string
IsContentDirty()	Checks whether or not the internal content/layout has changed. (Overrides View.IsContentDirty())
IsDirty()	Checks whether or not the view is dirty - i.e. requires a new layout with a full Measure(Vector2). (Inherited from View)
IsVisible(Vector2?)	Checks if the view is effectively visible, i.e. if it has anything to draw. (Inherited from View)
LogFocusSearch(string)	Outputs a debug log entry with the current view type, name and specified message. (Inherited from View)
Measure(Vector2)	Performs layout on this view, updating its OuterSize, ActualBounds and ContentBounds, and arranging any children in their respective positions. (Inherited from View)
OnButtonPress(ButtonEventArgs)	Called when a button press is received while this view is in the focus path. (Inherited from View)
OnButtonRepeat(ButtonEventArgs)	Called when a button press is first received, and at recurring intervals thereafter, for as long as the button is held and this view remains in the focus path. (Inherited from View)
OnClick(ClickEventArgs)	Called when a click is received within this view's bounds. (Overrides View.OnClick(ClickEventArgs))
OnDispose()	Performs additional cleanup when Dispose() is called. (Inherited from View)
OnDrag(PointerEventArgs)	Called when the view is being dragged (mouse moved while left button held). (Overrides View.OnDrag(PointerEventArgs))
OnDrawBorder(ISpriteBatch)	Draws the view's border, if it has one. (Inherited from View)
OnDrawContent(ISpriteBatch)	Draws the inner content of this view. (Overrides View.OnDrawContent(ISpriteBatch))
OnDrop(PointerEventArgs)	Called when the mouse button is released after at least one OnDrag(PointerEventArgs). (Inherited from View)
OnMeasure(Vector2)	Performs the internal layout. (Overrides View.OnMeasure(Vector2))
OnPointerMove(PointerMoveEventArgs)	Called when a pointer movement related to this view occurs. (Inherited from View)
OnPropertyChanged(PropertyChangedEventArgs)	Raises the PropertyChanged event. (Inherited from View)
OnPropertyChanged(string)	Raises the PropertyChanged event. (Inherited from View)
OnUpdate(TimeSpan)	Runs on every update tick. (Inherited from View)
OnWheel(WheelEventArgs)	Called when a wheel event is received within this view's bounds. (Inherited from View)
Release()	Function when the subscriber is released
ResetDirty()	Resets any dirty state associated with this view. (Inherited from View)
ScrollIntoView(IEnumerable<ViewChild>, Vector2)	Attempts to scroll the specified target into view, including all of its ancestors, if not fully in view. (Inherited from View)
ToString()	(Inherited from View)
UpdateParentScrollingBounds(Bounds)	Propagate new scrolling bounds to this view and it's children (Inherited from View)

Events

Name	Description
ButtonPress	Event raised when any button on any input device is pressed. (Inherited from View)
ButtonRepeat	Event raised when a button is being held while the view is in focus, and has been held long enough since the initial ButtonPress or the previous `ButtonRepeat` to trigger a repeated press. (Inherited from View)
Click	Event raised when the view receives a click. (Inherited from View)
Drag	Event raised when the view is being dragged using the mouse. (Inherited from View)
DragEnd	Event raised when mouse dragging is stopped, i.e. when the button is released. Always raised after the last Drag, and only once per drag operation. (Inherited from View)
DragStart	Event raised when mouse dragging is first activated. Always raised before the first Drag, and only once per drag operation. (Inherited from View)
LeftClick	Event raised when the view receives a click initiated from the left mouse button, or the controller's action button (A). (Inherited from View)
PointerEnter	Event raised when the pointer enters the view. (Inherited from View)
PointerLeave	Event raised when the pointer exits the view. (Inherited from View)
PointerMove	Event raised when the pointer moves within the view. (Inherited from View)
PropertyChanged	(Inherited from View)
RightClick	Event raised when the view receives a click initiated from the right mouse button, or the controller's tool-use button (X). (Inherited from View)
TextChanged	Event raised when the Text changes.
Wheel	Event raised when the scroll wheel moves. (Inherited from View)

Details

Constructors

TextInput()

Initializes a new TextInput.

public TextInput();

Properties

Background

For compatibility reasons Background is alias for Border. (unofficial-mushymato)

public StardewUI.Graphics.Sprite Background { get; set; }

Property Value

Sprite

Border

(unofficial-mushymato)

public StardewUI.Graphics.Sprite Border { get; set; }

Property Value

Sprite

BorderThickness

The thickness of the border edges.

public StardewUI.Layout.Edges BorderThickness { get; set; }

Property Value

Edges

Remarks

This property has no effect on the appearance of the Border, but affects how content is positioned inside the border. It is often correct to set it to the same value as the FixedEdges of the Border sprite, but the values are considered independent.

Caret

Sprite to draw for the cursor showing the current text position.

public StardewUI.Graphics.Sprite Caret { get; set; }

Property Value

Sprite

CaretPosition

The zero-based position of the caret within the text.

public int CaretPosition { get; set; }

Property Value

Int32

Remarks

This value is the string position; e.g. if the Text has a length of 5, and the current caret position is 2, then the caret is between the 2nd and 3rd characters. The value cannot be greater than the length of the current text.

CaretSelectionSize

Number of characters selected, stored as number of characters before or after the caret. (unofficial-mushymato)

public int CaretSelectionSize { get; set; }

Property Value

Int32

Remarks

This value does participate in TextBeforeCursor or TextAfterCursor adding up to equal total text length. When positive, it is always smaller than TextAfterCursor length. When negative, it's absolute value is always smaller TextBeforeCursor length.

CaretWidth

The width to draw the Caret, if different from the sprite's source width.

public float? CaretWidth { get; set; }

Property Value

Nullable<Single>

Enabled

Whether the input is enabled.

public bool Enabled { get; set; }

Property Value

Boolean

Remarks

Disabled text inputs have a darkened appearance and do not accept captures or text entry.

Font

The font with which to render text. Defaults to smallFont.

public Microsoft.Xna.Framework.Graphics.SpriteFont Font { get; set; }

Property Value

SpriteFont

MaxLength

The maximum number of characters allowed in this field.

public int MaxLength { get; set; }

Property Value

Int32

Remarks

The default value is 0 which does not impose any limit.

Placeholder

Placeholder text to display when the Text is empty and input is not captured.

public string Placeholder { get; set; }

Property Value

string

PlaceholderColor

Color of the Placeholder text when displayed.

public Microsoft.Xna.Framework.Color PlaceholderColor { get; set; }

Property Value

Color

SelectedText

Read-only property for selected text, set via changes to CaretSelectionSize. (unofficial-mushymato)

public string SelectedText { get; private set; }

Property Value

string

ShadowAlpha

Alpha value for the shadow. If set to the default of zero, no shadow will be drawn.

public float ShadowAlpha { get; set; }

Property Value

Single

ShadowOffset

Offset to draw the sprite shadow, which is a second copy of the Background drawn entirely black. Shadows will not be visible unless ShadowAlpha is non-zero.

public Microsoft.Xna.Framework.Vector2 ShadowOffset { get; set; }

Property Value

Vector2

Text

The text currently entered.

public string Text { get; set; }

Property Value

string

Remarks

Setting this to a new value will reset the caret position to the end of the text.

TextColor

Color of displayed text, as well as the Caret tint color.

public Microsoft.Xna.Framework.Color TextColor { get; set; }

Property Value

Color

Methods

GetLocalChildren()

Gets the view's children with positions relative to the content area.

protected override System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetLocalChildren();

Returns

IEnumerable<ViewChild>

Remarks

This has the same signature as GetChildren(Boolean) but assumes that coordinates are in the same space as those used in OnDrawContent(ISpriteBatch), i.e. not accounting for margin/border/padding. These coordinates are automatically adjusted in the GetChildren(Boolean) to be relative to the entire view.

The default implementation returns an empty sequence. Composite views must override this method in order for user interactions to behave correctly.

HandleSpecialKey(Keys)

Handle non-text entry key.

public void HandleSpecialKey(Microsoft.Xna.Framework.Input.Keys key);

Parameters

key Keys

InsertChar(char)

Accept new entered char

public void InsertChar(char c);

Parameters

c Char

InsertString(string)

Accept new entered string

public void InsertString(string text);

Parameters

text string

IsContentDirty()

Checks whether or not the internal content/layout has changed.

protected override bool IsContentDirty();

Returns

Boolean

true if content has changed; otherwise false.

Remarks

The base implementation of IsDirty() only checks if the base layout attributes have changed, i.e. Layout, Margin, Padding, etc. It does not know about content/data in any subclasses; those that accept content parameters (like text) will typically use DirtyTracker<T> to hold that content and should implement this method to check their IsDirty states.

OnClick(ClickEventArgs)

Called when a click is received within this view's bounds.

public override void OnClick(StardewUI.Events.ClickEventArgs e);

Parameters

e ClickEventArgs
The event data.

OnDrag(PointerEventArgs)

Called when the view is being dragged (mouse moved while left button held).

public override void OnDrag(StardewUI.Events.PointerEventArgs e);

Parameters

e PointerEventArgs
The event data.

OnDrawContent(ISpriteBatch)

Draws the inner content of this view.

protected override void OnDrawContent(StardewUI.Graphics.ISpriteBatch b);

Parameters

b ISpriteBatch
Sprite batch to hold the drawing output.

Remarks

This is called from Draw(ISpriteBatch) after applying both Margin and Padding.

OnMeasure(Vector2)

Performs the internal layout.

protected override void OnMeasure(Microsoft.Xna.Framework.Vector2 availableSize);

Parameters

availableSize Vector2
Size available in the container, after applying padding, margin and borders.

Remarks

This is called from Measure(Vector2) only when the layout is dirty (layout parameters or content changed) and a new layout is actually required. Subclasses must implement this and set ContentSize once layout is complete. Typically, Resolve(Vector2, Func<Vector2>) should be used in order to ensure that the original LayoutParameters are respected (e.g. if the actual content size is smaller than the configured size).

The availableSize provided to the method is pre-adjusted for Margin, Padding, and any border determined by GetBorderThickness().

Release()

Function when the subscriber is released

public void Release();

Events

TextChanged

Event raised when the Text changes.

public event EventHandler<System.EventArgs>? TextChanged;

Event Type

EventHandler<EventArgs>