Class View

Nullable<LayoutParameters>

ClipOrigin

Origin position for the ClipSize.

public StardewUI.Layout.NineGridPlacement ClipOrigin { get; set; }

Property Value

NineGridPlacement

Remarks

If clipping is enabled by specifying a ClipSize, and the computed size of the clipping rectangle is not exactly equal to the view's OuterSize, then this determines how it will be aligned relative to this view's boundaries.

The default origin is the view's top-left corner (0, 0). This property has no effect unless the view's ClipSize is also defined.

ClipSize

Size of the clipping rectangle, outside which content will not be displayed.

public StardewUI.Layout.LayoutParameters? ClipSize { get; set; }

Property Value

Remarks

This is defined as a layout, but unlike the view's Layout, it is not computed against the available size provided by the parent; instead, its reference size is the view's OuterSize.

A common scenario is to set this to Fill() in order to prevent drawing outside the view's own boundaries, i.e. as an equivalent to CSS overflow: hidden. Note however that clipping occurs during the drawing phase, so a smaller clip region does not result in a smaller layout; the view will still have the same size it would have had without any clipping, but only part of it will actually get drawn. This can also be used intentionally to create some animated visual effects such as slides and wipes.

ContentBounds

The true bounds of this view's content; i.e. ActualBounds excluding margins.

public StardewUI.Layout.Bounds ContentBounds { get; }

Property Value

Bounds

ContentSize

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.

public Microsoft.Xna.Framework.Vector2 ContentSize { get; protected set; }

Property Value

Draggable

Whether or not this view should fire drag events such as DragStart and Drag.

public bool Draggable { get; set; }

Property Value

FloatingBounds

Contains the bounds of all floating elements in this view tree, including the current view and all descendants.

public System.Collections.Generic.IEnumerable<StardewUI.Layout.Bounds> FloatingBounds { get; }

Property Value

IEnumerable<Bounds>

FloatingElements

The floating elements to display relative to this view.

public System.Collections.Generic.IList<StardewUI.Layout.FloatingElement> FloatingElements { get; set; }

Property Value

IList<FloatingElement>

Focusable

Whether or not the view should be able to receive focus. Applies only to this specific view, not its children.

public bool Focusable { get; set; }

Property Value

Remarks

All views are non-focusable by default and must have their focus enabled explicitly. Subclasses may choose to override the default value if they should always be focusable.

HandlesOpacity

Whether the specific view type handles its own opacity.

protected bool HandlesOpacity { get; }

Property Value

Remarks

Subclasses can override this to provide their own, typically better optimized version of opacity; i.e. a basic text or image view could simply multiply its own background/foreground colors without requiring multiple render targets to handle the blending.

Any FloatingElements will still use the default opacity implementation.

InnerSize

The size allocated to the entire area inside the border, i.e. ContentSize plus any Padding. Does not include border or Margin.

public Microsoft.Xna.Framework.Vector2 InnerSize { get; }

Property Value

IsFocusable

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.

public bool IsFocusable { get; }

Property Value

Remarks

In other game UI code this is more typically referred to as "snap", since there is no true input focus. However, focus is the more general term and better explains what is happening with e.g. a text box.

LastAvailableSize

The most recent size used in a Measure(Vector2) pass. Used for additional dirty checks.

protected Microsoft.Xna.Framework.Vector2 LastAvailableSize { get; private set; }

Property Value

Layout

Layout settings for this view; determines how its dimensions will be computed.

public StardewUI.Layout.LayoutParameters Layout { get; set; }

Property Value

LayoutParameters

LayoutOffset

Pixel offset of the view's content, which is applied to all pointer events and child queries.

protected Microsoft.Xna.Framework.Vector2 LayoutOffset { get; }

Property Value

Remarks

A non-zero offset means that the nominal positions of any view children (e.g. as obtained from GetChildren(Boolean)) are different from their actual drawing positions on screen, for example in the case of a ScrollContainer that is not at the default scroll position.

If a view will internally shift content in this way without affecting layout, it should update the LayoutOffset property to ensure correctness of pointer events and coordinate-related queries such as GetLocalChildrenAt(Vector2), instead of attempting to correct for that offset locally.

Margin

Margins (whitespace outside border) for this view.

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

Property Value

Edges

Name

Simple name for this view, used in log/debug output; does not affect behavior.

public string Name { get; set; }

Property Value

string

Opacity

Opacity (alpha level) of the view.

public float Opacity { get; set; }

Property Value

Single

Remarks

Affects this view and all descendants; used to control opacity of an entire control or layout area.

OuterSize

The size of the entire area occupied by this view including margins, border and padding.

public Microsoft.Xna.Framework.Vector2 OuterSize { get; }

Property Value

Padding

Padding (whitespace inside border) for this view.

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

Property Value

Edges

PointerEventsEnabled

Whether this view should receive pointer events like Click or Drag.

public bool PointerEventsEnabled { get; set; }

Property Value

Remarks

By default, all views receive pointer events; this may be disabled for views that intentionally overlap other views but shouldn't block their input, such as local non-modal overlays.

PointerStyle

Pointer style to use when this view is hovered.

public StardewUI.Input.PointerStyle PointerStyle { get; set; }

Property Value

PointerStyle

Remarks

As with Tooltip, the lowest-level view takes precedence over any higher-level views.

ScrollWithChildren

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.

public StardewUI.Layout.Orientation? ScrollWithChildren { get; set; }

Property Value

Nullable<Orientation>

Remarks

For example, if the view lays out children horizontally, and some children may occupy only a very small amount of space near the top while others are much taller vertically or positioned near the bottom, it might be desirable to configure this with Vertical, so that the entire "row" is positioned within the scrollable viewport.

In other words, "if any part of me is made visible via scrolling, then all of me should be visible".

Property Value

Transform

TransformOrigin

Relative origin position for any Transform on this view.

public Microsoft.Xna.Framework.Vector2? TransformOrigin { get; set; }

Property Value

Nullable<Vector2>

Remarks

Expects a value that represents the fraction of the view's computed layout size. For example, (0, 0) is the top left, (0.5, 0.5) is the center, and 1, 1 is the bottom right. null values are equivalent to Zero.

Origins are not inherited; each view defines its own origin for its specific transform.

Visibility

Visibility for this view.

public StardewUI.Layout.Visibility Visibility { get; set; }

Property Value

Visibility

ZIndex

Z order for this view within its direct parent. Higher indices draw later (on top).

public int ZIndex { get; set; }

Property Value

Int32

Methods

ContainsPoint(Vector2)

Checks if a given point, relative to the view's origin, is within its bounds.

public bool ContainsPoint(Microsoft.Xna.Framework.Vector2 point);

Parameters

point Vector2
The point to test.

Returns

true if point is within the view bounds; otherwise false.

Dispose()

public void Dispose();

Draw(ISpriteBatch)

Draws the content for this view.

public void Draw(StardewUI.Graphics.ISpriteBatch b);

Parameters

b ISpriteBatch
Sprite batch to hold the drawing output.

Remarks

Drawing always happens after the measure pass, so ContentSize should be known and stable at this time, as long as the implementation itself is stable.

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.

protected virtual StardewUI.Input.FocusSearchResult FindFocusableDescendant(Microsoft.Xna.Framework.Vector2 contentPosition, StardewUI.Direction direction);

Parameters

contentPosition Vector2
The search position, relative to where this view's content starts (after applying margin, borders and padding).

direction Direction
The search direction.

Returns

FocusSearchResult

Remarks

This is the same as FocusSearch(Vector2, Direction) but in pre-transformed content coordinates, and does not require checking for "self-focus" as FocusSearch(Vector2, Direction) already does this. The default implementation simply returns null as most views do not have children; subclasses with children must override this.

FocusSearch(Vector2, Direction)

Finds the next focusable component in a given direction that does not overlap with a current position.

public StardewUI.Input.FocusSearchResult FocusSearch(Microsoft.Xna.Framework.Vector2 position, StardewUI.Direction direction);

Parameters

position Vector2
The current cursor position, relative to this view. May have dimensions that are negative or outside the view bounds, indicating that the cursor is not currently within the view.

direction Direction
The direction of cursor movement.

Returns

FocusSearchResult

Remarks

This will first call FindFocusableDescendant(Vector2, Direction) to see if the specific view type wants to implement its own focus search. If there is no focusable descendant, then this will return a reference to the current view if Focusable is true and the position is not already within the view's bounds - meaning, any focusable view can accept focus from any direction, but will not consider itself a result if it is already focused (since we are trying to "move" focus).

GetBorderThickness()

Measures the thickness of each edge of the border, if the view has a border.

protected virtual StardewUI.Layout.Edges GetBorderThickness();

Returns

Edges

The border edge thicknesses.

Remarks

Used only by views that will implement a border via OnDrawBorder(ISpriteBatch). The border thickness is considered during layout, and generally treated as additional Padding for the purposes of setting allowed content size.

Borders usually have a static size, but if the thickness can change, then implementations must account for it in their dirty checking (IsContentDirty()).

GetChildAt(Vector2, bool, bool)

Finds the child at a given position.

public StardewUI.ViewChild GetChildAt(Microsoft.Xna.Framework.Vector2 position, bool preferFocusable, bool requirePointerEvents);

Parameters

position Vector2
The search position, relative to the view's top-left coordinate.

preferFocusable Boolean
true to prioritize a focusable child over a non-focusable child with a higher z-index in case of overlap; false to always use the topmost child.

requirePointerEvents Boolean
Whether to exclude views whose PointerEventsEnabled is currently false.

Returns

ViewChild

The view at position, or null if there is no match.

Remarks

If multiple children overlap the same position, then this returns the topmost child, i.e. with the highest ZIndex.

GetChildPosition(IView)

Computes or retrieves the position of a given direct child.

public Microsoft.Xna.Framework.Vector2? GetChildPosition(StardewUI.IView childView);

Parameters

childView IView
The child of this view.

Returns

Nullable<Vector2>

The local coordinates of the childView, or null if the childView is not a current or direct child.

Remarks

Implementation of this may be O(N) and therefore it should not be called every frame; it is intended for use in directional movement and other user-initiated events.

GetChildren(bool)

Gets the current children of this view.

public System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetChildren(bool includeFloatingElements);

Parameters

includeFloatingElements Boolean
Whether to include views that are not direct children, but instead members of the floating elements collection of an IFloatContainer implementation.

Returns

GetChildrenAt(Vector2)

Finds all children at a given position.

public System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetChildrenAt(Microsoft.Xna.Framework.Vector2 position);

Parameters

position Vector2
The search position, relative to the view's top-left coordinate.

Returns

A sequence of views at the specified position, in front-to-back (reverse ZIndex) order.

GetDefaultFocusChild()

Gets the direct child that should contain cursor focus when a menu or overlay containing this view is first opened.

public virtual StardewUI.ViewChild GetDefaultFocusChild();

Returns

ViewChild

The child view and position where initial focus should be, either directly or indirectly as a result of a descendant receiving focus. If this IView is itself IsFocusable, then the result may be a ViewChild referencing this view.

GetLocalChildren()

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

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

Returns

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.

GetLocalChildrenAt(Vector2)

Searches for all views at a given position relative to the content area.

protected virtual System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetLocalChildrenAt(Microsoft.Xna.Framework.Vector2 contentPosition);

Parameters

contentPosition Vector2
The search position, relative to where this view's content starts (after applying margin, borders and padding).

Returns

The views at the specified contentPosition, in original layout order.

Remarks

The default implementation performs a linear search on all children and returns all whose bounds overlap the specified contentPosition. Views can override this to provide optimized implementations for their layout, or handle overlapping views.

HasOutOfBoundsContent()

Checks if the view has content or elements that are all or partially outside the ActualBounds.

public bool HasOutOfBoundsContent();

Returns

Remarks

This may be the case for e.g. floating elements, and covers not only the view's immediate content/children but also that of any descendants.

HasOwnContent()

Checks if this view displays its own content, independent of any floating elements or children.

protected virtual bool HasOwnContent();

Returns

Remarks

This is used by IsVisible(Vector2?) to determine whether children need to be searched. If a view provides its own content, e.g. a label or image displaying text or a sprite, or a frame displaying a background/border, then the entire view's bounds are understood to have visible content. Otherwise, the view is only considered visible as a whole if at least one child is visible, and is only visible at any given point if there is an intersecting child at that point.

IsContentDirty()

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

protected virtual bool IsContentDirty();

Returns

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.

IsDirty()

Checks whether or not the view is dirty - i.e. requires a new layout with a full Measure(Vector2).

public bool IsDirty();

Returns

true if the view must be measured again; otherwise false.

Remarks

Typically, a view will be considered dirty if and only if one of the following are true:

The Layout has changed
The content has changed in a way that could affect layout, e.g. the text has changed in a Content configuration
The availableSize is not the same as the previously-seen value (see remarks in Measure(Vector2))

A correct implementation is important for performance, as full layout can be very expensive to run on every frame.

IsVisible(Vector2?)

Checks if the view is effectively visible, i.e. if it has anything to draw.

public bool IsVisible(Microsoft.Xna.Framework.Vector2? position);

Parameters

position Nullable<Vector2>
Optional position at which to test for visibility. If not specified, the result indicates whether any part of the view is visible.

Returns

Remarks

While Visibility acts as a master on/off switch, there may be many other reasons for a view not to have any visible content, such as views with zero Opacity, layout views with no visible children, or labels or images with no current text or sprite.

LogFocusSearch(string)

Outputs a debug log entry with the current view type, name and specified message.

protected void LogFocusSearch(string message);

Parameters

message string
The message to log in addition to the view type and name.

Remarks

Used primarily for debugging focus searches and requires the DEBUG_FOCUS_SEARCH compiler flag.

Measure(Vector2)

Performs layout on this view, updating its OuterSize, ActualBounds and ContentBounds, and arranging any children in their respective positions.

public bool Measure(Microsoft.Xna.Framework.Vector2 availableSize);

Parameters

availableSize Vector2
The width/height that is still available in the container/parent.

Returns

Whether or not any layout was performed as a result of this pass. Callers may use this to propagate layout back up the tree, or perform expensive follow-up actions.

Remarks

Most views should save the value of availableSize for use in IsDirty() checks.

OnButtonPress(ButtonEventArgs)

Called when a button press is received while this view is in the focus path.

public virtual void OnButtonPress(StardewUI.Events.ButtonEventArgs e);

Parameters

e ButtonEventArgs
The event data.

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.

public virtual void OnButtonRepeat(StardewUI.Events.ButtonEventArgs e);

Parameters

e ButtonEventArgs
The event data.

OnClick(ClickEventArgs)

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

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

Parameters

e ClickEventArgs
The event data.

OnDispose()

Performs additional cleanup when Dispose() is called.

protected virtual void OnDispose();

Remarks

The default implementation is a stub. Subclasses may override this if they require separate cleanup.

OnDrag(PointerEventArgs)

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

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

Parameters

e PointerEventArgs
The event data.

OnDrawBorder(ISpriteBatch)

Draws the view's border, if it has one.

protected virtual void OnDrawBorder(StardewUI.Graphics.ISpriteBatch b);

Parameters

b ISpriteBatch
Sprite batch to hold the drawing output.

Remarks

This is called from Draw(ISpriteBatch) after applying Margin but before Padding.

OnDrawContent(ISpriteBatch)

Draws the inner content of this view.

protected virtual 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.

OnDrop(PointerEventArgs)

Called when the mouse button is released after at least one OnDrag(PointerEventArgs).

public virtual void OnDrop(StardewUI.Events.PointerEventArgs e);

Parameters

e PointerEventArgs
The event data.

OnMeasure(Vector2)

Performs the internal layout.

protected virtual 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().

OnPointerMove(PointerMoveEventArgs)

Called when a pointer movement related to this view occurs.

public virtual void OnPointerMove(StardewUI.Events.PointerMoveEventArgs e);

Parameters

e PointerMoveEventArgs
The event data.

Remarks

This can either be the pointer entering the view, leaving the view, or moving within the view. The method is used to trigger events such as PointerEnter and PointerLeave.

OnPropertyChanged(PropertyChangedEventArgs)

Raises the PropertyChanged event.

protected virtual void OnPropertyChanged(System.ComponentModel.PropertyChangedEventArgs args);

Parameters

args PropertyChangedEventArgs
The event arguments.

OnPropertyChanged(string)

Raises the PropertyChanged event.

protected virtual void OnPropertyChanged(string propertyName);

Parameters

propertyName string
The name of the property that was changed.

OnUpdate(TimeSpan)

Runs on every update tick.

public virtual void OnUpdate(System.TimeSpan elapsed);

Parameters

elapsed TimeSpan
Time elapsed since last game tick.

Remarks

When overriding OnUpdate(TimeSpan), be sure to call base.OnUpdate() to ensure that any view children also receive their updates.

OnWheel(WheelEventArgs)

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

public virtual void OnWheel(StardewUI.Events.WheelEventArgs e);

Parameters

e WheelEventArgs
The event data.

ResetDirty()

Resets any dirty state associated with this view.

protected virtual void ResetDirty();

Remarks

This is called at the end of Measure(Vector2), so that on the next pass, all state appears clean unless it was marked dirty after the last pass completed. The default implementation is a no-op; subclasses should use it to clear any private dirty state, e.g. via ResetDirty().

ScrollIntoView(IEnumerable<ViewChild>, Vector2)

Attempts to scroll the specified target into view, including all of its ancestors, if not fully in view.

public virtual bool ScrollIntoView(System.Collections.Generic.IEnumerable<StardewUI.ViewChild> path, out Microsoft.Xna.Framework.Vector2 distance);

Parameters

path IEnumerable<ViewChild>
The path to the view that should be visible, starting from (and not including) this view; each element has the local position within its own parent, so the algorithm can run recursively. This is a slice of the same path returned in a FocusSearchResult.

distance Vector2
The total distance that was scrolled, including distance scrolled by descendants.

Returns

EventHandler<ButtonEventArgs>

Remarks

The default implementation does no scrolling of its own, only passes the request down to the child and aborts if the child returns true. Scrollable views must override this to provide scrolling behavior.

ToString()

public override string ToString();

Returns

string

Events

ButtonPress

Event raised when any button on any input device is pressed.

public event EventHandler<StardewUI.Events.ButtonEventArgs>? ButtonPress;

Event Type

Remarks

Only the views in the current focus path should receive these events.

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.

public event EventHandler<StardewUI.Events.ButtonEventArgs>? ButtonRepeat;

Event Type

EventHandler<ButtonEventArgs>

Remarks

Because the game has its own logic to repeat key presses, which would cause ButtonPress to fire repeatedly, this event generally applies only to the controller; that is, it exists to allow callers to decide whether they want the handler to repeat while the button is held or to only fire when first pressed, providing slightly more control than keyboard events whose repetition is up to the whims of the vanilla game.

Only the views in the current focus path should receive these events.

Click

Event raised when the view receives a click.

public event EventHandler<StardewUI.Events.ClickEventArgs>? Click;

Event Type

EventHandler<ClickEventArgs>

Drag

Event raised when the view is being dragged using the mouse.

public event EventHandler<StardewUI.Events.PointerEventArgs>? Drag;

Event Type

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.

public event EventHandler<StardewUI.Events.PointerEventArgs>? DragEnd;

Event Type

DragStart

Event raised when mouse dragging is first activated. Always raised before the first Drag, and only once per drag operation.

public event EventHandler<StardewUI.Events.PointerEventArgs>? DragStart;

Event Type

EventHandler<ClickEventArgs>

LeftClick

Event raised when the view receives a click initiated from the left mouse button, or the controller's action button (A).

public event EventHandler<StardewUI.Events.ClickEventArgs>? LeftClick;

Event Type

PointerEnter

Event raised when the pointer enters the view.

public event EventHandler<StardewUI.Events.PointerEventArgs>? PointerEnter;

Event Type

PointerLeave

Event raised when the pointer exits the view.

public event EventHandler<StardewUI.Events.PointerEventArgs>? PointerLeave;

Event Type