Class ScrollContainer
Definition
Namespace: StardewUI.Widgets
Assembly: StardewUI.dll
Renders inner content clipped to a boundary and with a modifiable scroll offset.
Inheritance
Object ⇦ View ⇦ ScrollContainer
Remarks
Does not provide its own scroll bar; scrolling UI and behavior can be controlled via adding a Scrollbar to any other part of the UI.
While nothing prevents a ScrollContainer from being set up with the Orientation dimension set to use Content, in general the container will only work correctly when the scrolled dimension is constrained (Px or Stretch). Scrolling behavior is enabled by providing an infinite available length to the Content view for layout, while constraining its own size.
Scrolling is not virtual. Regardless of the difference in size between scroll container and content, the full content will always be drawn on every frame, and simply clipped to the available area. This may therefore not be suitable for extremely long lists or other unbounded content.
Members
Constructors
| Name | Description |
|---|---|
| ScrollContainer() |
Properties
| Name | Description |
|---|---|
| ActualBounds | The bounds of this view relative to the origin (0, 0). (Inherited from View) |
| BorderSize | 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) |
| ClipOrigin | Origin position for the ClipSize. (Inherited from View) |
| ClipSize | Size of the clipping rectangle, outside which content will not be displayed. (Inherited from View) |
| Content | The inner content view which will be scrolled. |
| ContentBounds | The true bounds of this view's content; i.e. ActualBounds excluding margins. (Inherited from View) |
| 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. (Inherited from View) |
| ContentViewSize | The size of the current content view, or Zero if there is no content. |
| Draggable | Whether or not this view should fire drag events such as DragStart and Drag. (Inherited from View) |
| FloatingBounds | Contains the bounds of all floating elements in this view tree, including the current view and all descendants. (Inherited from View) |
| FloatingElements | The floating elements to display relative to this view. (Inherited from View) |
| Focusable | Whether or not the view should be able to receive focus. Applies only to this specific view, not its children. (Inherited from View) |
| HandlesOpacity | Whether the specific view type handles its own opacity. (Inherited from View) |
| InnerSize | 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 | 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) |
| LastAvailableSize | The most recent size used in a Measure(Vector2) pass. Used for additional dirty checks. (Inherited from View) |
| Layout | Layout settings for this view; determines how its dimensions will be computed. (Inherited from View) |
| LayoutOffset | Pixel offset of the view's content, which is applied to all pointer events and child queries. (Overrides View. get_LayoutOffset()) |
| Margin | Margins (whitespace outside border) for this view. (Inherited from View) |
| Name | Simple name for this view, used in log/debug output; does not affect behavior. (Inherited from View) |
| Opacity | Opacity (alpha level) of the view. (Inherited from View) |
| Orientation | The orientation, i.e. the direction of scrolling. |
| OuterSize | The size of the entire area occupied by this view including margins, border and padding. (Inherited from View) |
| Padding | Padding (whitespace inside border) for this view. (Inherited from View) |
| Peeking | The amount of "peeking" to add when scrolling a component into view; adds extra space before/after the visible element so that all or part of the previous/next element is also visible. |
| PointerEventsEnabled | Whether this view should receive pointer events like Click or Drag. (Inherited from View) |
| PointerStyle | Pointer style to use when this view is hovered. (Inherited from View) |
| ScrollOffset | The current scroll position along the Orientation axis. |
| ScrollSize | The maximum amount by which the container can be scrolled without exceeding the inner content bounds. |
| ScrollStep | Default scroll distance when calling ScrollForward() or ScrollBackward(). Does not prevent directly setting the scroll position via ScrollOffset. |
| 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. (Inherited from View) |
| Tags | The user-defined tags for this view. (Inherited from View) |
| Tooltip | Localized tooltip to display on hover, if any. (Inherited from View) |
| Transform | Local transformation to apply to this view, including any children and floating elements. (Inherited from View) |
| TransformOrigin | Relative origin position for any Transform on this view. (Inherited from View) |
| Visibility | Visibility for this view. (Inherited from View) |
| ZIndex | 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.(Overrides View.FindFocusableDescendant(Vector2, Direction)) |
| 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. (Overrides View.GetLocalChildrenAt(Vector2)) |
| 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. (Overrides View.HasOwnContent()) |
| 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. (Inherited from View) |
| 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). (Inherited from View) |
| 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. (Overrides View.OnPropertyChanged(PropertyChangedEventArgs)) |
| 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) |
| ResetDirty() | Resets any dirty state associated with this view. (Overrides View.ResetDirty()) |
| ScrollBackward() | Scrolls backward (up or left) by the distance configured in ScrollStep. |
| ScrollForward() | Scrolls forward (down or right) by the distance configured in ScrollStep. |
| ScrollIntoView(IEnumerable<ViewChild>, Vector2) | Attempts to scroll the specified target into view, including all of its ancestors, if not fully in view. (Overrides View.ScrollIntoView(IEnumerable<ViewChild>, Vector2)) |
| ToString() | (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) |
| ScrollChanged | Event raised when any aspect of the scrolling changes. |
| Wheel | Event raised when the scroll wheel moves. (Inherited from View) |
Details
Constructors
ScrollContainer()
Properties
Content
The inner content view which will be scrolled.
Property Value
ContentViewSize
The size of the current content view, or Zero if there is no content.
Property Value
LayoutOffset
Pixel offset of the view's content, which is applied to all pointer events and child queries.
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.
Orientation
The orientation, i.e. the direction of scrolling.
Property Value
Remarks
A single ScrollContainer can only scroll in one direction. If content needs to scroll both horizontally and vertically, a nested ScrollContainer can be used.
Peeking
The amount of "peeking" to add when scrolling a component into view; adds extra space before/after the visible element so that all or part of the previous/next element is also visible.
Property Value
Remarks
Nonzero values help with discoverability, making it clear that there is more content.
ScrollOffset
The current scroll position along the Orientation axis.
Property Value
ScrollSize
The maximum amount by which the container can be scrolled without exceeding the inner content bounds.
Property Value
ScrollStep
Default scroll distance when calling ScrollForward() or ScrollBackward(). Does not prevent directly setting the scroll position via ScrollOffset.
Property Value
Methods
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 override 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
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.
GetLocalChildren()
Gets the view's children with positions relative to the content area.
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 override 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.
HasOwnContent()
Checks if this view displays its own content, independent of any floating elements or children.
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.
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.
OnDrawContent(ISpriteBatch)
Draws the inner content of this view.
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.
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().
OnPropertyChanged(PropertyChangedEventArgs)
Raises the PropertyChanged event.
Parameters
args PropertyChangedEventArgs
The event arguments.
ResetDirty()
Resets any dirty state associated with this view.
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().
ScrollBackward()
Scrolls backward (up or left) by the distance configured in ScrollStep.
Returns
ScrollForward()
Scrolls forward (down or right) by the distance configured in ScrollStep.
Returns
ScrollIntoView(IEnumerable<ViewChild>, Vector2)
Attempts to scroll the specified target into view, including all of its ancestors, if not fully in view.
public override 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
Whether or not the scroll was successful; false prevents the request from bubbling.
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.
Events
ScrollChanged
Event raised when any aspect of the scrolling changes.
Event Type
Remarks
This tracks changes to the ScrollOffset but also the ScrollSize, even if the offset has not changed. ScrollStep is not included.