Class ViewExtensions
Definition
Namespace: StardewUI
Assembly: StardewUI.dll
Commonly-used extensions for the IView interface and related types.
Inheritance
Object ⇦ ViewExtensions
Members
Methods
| Name | Description |
|---|---|
| FocusablePath(IEnumerable<ViewChild>) | Returns the focusable component of the path to a view, typically a cursor target. |
| GetDefaultFocusPath(IView) | Retrieves a path to the default focus child/descendant of a view. |
| GetPathToPosition(IView, Vector2, Boolean, Boolean) | Retrieves a path to the view at a given position. |
| GetPathToView(IView, IView) | Retrieves the path to a descendant view. |
| ResolveChildPath(IView, IEnumerable<IView>) | Takes an existing view path and resolves it with child coordinates for the view at each level. |
| ToGlobalPositions(IEnumerable<ViewChild>) | Converts a view path in parent-relative coordinates (e.g. from GetPathToPosition(IView, Vector2, Boolean, Boolean) and transforms each element to have an absolute Position. |
| ZOrder(IEnumerable<ViewChild>, Boolean) | Sorts a sequence of children in ascending z-order. |
| ZOrderDescending(IEnumerable<ViewChild>, Boolean) | Sorts a sequence of children in descending z-order. |
Details
Methods
FocusablePath(IEnumerable<ViewChild>)
Returns the focusable component of the path to a view, typically a cursor target.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> FocusablePath(System.Collections.Generic.IEnumerable<StardewUI.ViewChild> path);
Parameters
path IEnumerable<ViewChild>
The view path.
Returns
The sequence of path elements ending with the last view for which IsFocusable is true. If there are no focusable views in the path, returns an empty sequence.
GetDefaultFocusPath(IView)
Retrieves a path to the default focus child/descendant of a view.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetDefaultFocusPath(StardewUI.IView view);
Parameters
view IView
The view at which to start the search.
Returns
A sequence of ViewChild elements with the IView and position (relative to parent) at each level, starting with the specified view and ending with the lowest-level IView in the default focus path. If no focusable descendant is found, returns an empty sequence.
GetPathToPosition(IView, Vector2, bool, bool)
Retrieves a path to the view at a given position.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetPathToPosition(StardewUI.IView view, Microsoft.Xna.Framework.Vector2 position, bool preferFocusable, bool requirePointerEvents);
Parameters
view IView
The view at which to start the search.
position Vector2
The position to search for, in coordinates relative to the view.
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. This short-circuits the pathing; if any ancestor of a view has pointer events disabled then it cannot be part of the path.
Returns
A sequence of ViewChild elements with the IView and position (relative to parent) at each level, starting with the specified view and ending with the lowest-level IView that still overlaps with the specified position. If no match is found, returns an empty sequence.
GetPathToView(IView, IView)
Retrieves the path to a descendant view.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> GetPathToView(StardewUI.IView view, StardewUI.IView descendant);
Parameters
view IView
The view at which to start the search.
descendant IView
The descendant view to search for.
Returns
A sequence of ViewChild elements with the IView and position (relative to parent) at each level, starting with the specified view and ending with the specified descendant. If no match is found, returns null.
Remarks
This method has worst-case O(N) performance, so avoid calling it in tight loops such as draw methods, and cache the result whenever possible.
ResolveChildPath(IView, IEnumerable<IView>)
Takes an existing view path and resolves it with child coordinates for the view at each level.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> ResolveChildPath(StardewUI.IView view, System.Collections.Generic.IEnumerable<StardewUI.IView> path);
Parameters
view IView
The root view.
path IEnumerable<IView>
The path from root down to some descendant, such as the path returned by GetPathToPosition(IView, Vector2, Boolean, Boolean).
Returns
A sequence of ViewChild elements, starting at the view, where each child's Position is the child's most current location within its parent.
ToGlobalPositions(IEnumerable<ViewChild>)
Converts a view path in parent-relative coordinates (e.g. from GetPathToPosition(IView, Vector2, Boolean, Boolean) and transforms each element to have an absolute Position.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> ToGlobalPositions(System.Collections.Generic.IEnumerable<StardewUI.ViewChild> path);
Parameters
path IEnumerable<ViewChild>
The path from root down to leaf view.
Returns
The path with positions in global coordinates.
Remarks
Since ViewChild does not specify whether the position is local (parent) or global (absolute), it is not possible to validate the incoming sequence and prevent a "double transformation". Callers are responsible for knowing whether or not the input sequence is local or global.
ZOrder(IEnumerable<ViewChild>, bool)
Sorts a sequence of children in ascending z-order.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> ZOrder(System.Collections.Generic.IEnumerable<StardewUI.ViewChild> children, bool focusPriority);
Parameters
children IEnumerable<ViewChild>
The view children.
focusPriority Boolean
true to sort focusable children first regardless of z-index; false to ignore IsFocusable.
Returns
The children ordered by the view's ZIndex and original sequence order.
Remarks
Order is preserved between views with the same ZIndex, so the resulting sequence will have a primary order of z-index (lower indices first) and a secondary order of original sequence position. This is the correct order for drawing views.
ZOrderDescending(IEnumerable<ViewChild>, bool)
Sorts a sequence of children in descending z-order.
public static System.Collections.Generic.IEnumerable<StardewUI.ViewChild> ZOrderDescending(System.Collections.Generic.IEnumerable<StardewUI.ViewChild> children, bool focusPriority);
Parameters
children IEnumerable<ViewChild>
The view children.
focusPriority Boolean
true to sort focusable children first regardless of z-index; false to ignore IsFocusable.
Returns
Remarks
The resulting sequence will have an order such that views with higher ZIndex appear first, and views with the same z-index will appear in the reverse order of the original sequence. This is the correct order for handling cursor events and any other actions that need to operate on the "topmost" view first.