ScrollContainer
A scrollable Control area with managed content and scrollbars.
ScrollContainer clips the visible content area and offsets content horizontally/vertically. For a list, add one VBoxContainer and put items inside it; several direct children do not automatically form a list. ClipContents is enabled. Parent layout supplies the visible size; content minimum determines the range.
ScrollHorizontal/ScrollVertical are integer logical offsets. Their setters change scrollbar values and cancel active dragging; a layout pass updates content rectangles. With normal Range settings the upper bound is MaxValue − Page rather than MaxValue. Read bounds and ValueChanged from GetHScrollBar/GetVScrollBar. These are internal children: do not free them separately; the container recalculates MaxValue/Page. If a scrollbar value is fractional, the ScrollContainer integer getter truncates it.
Axis modes differ: Disabled disables scrolling on that axis and contributes the content minimum to the container minimum; Auto shows a bar when needed; ShowAlways always shows it; ShowNever hides the bar while retaining scrolling; Reserve reserves its space even while hidden. MaximizeFirst initially considers content size up to a finite container maximum; without a suitable maximum the area can grow instead of scrolling as expected. Disabled and ShowNever do not impose equivalent constraints.
EnsureControlVisible requires a descendant and uses its current rectangle to calculate an offset. After changing children, wait for layout, for example with a deferred call after creating the list. It does not assign focus or guarantee fitting a target larger than the visible area. FollowFocus triggers a reveal when focus changes to a descendant; enabling the flag alone does not automatically reveal an already focused item.
ScrollStarted/ScrollEnded describe dragging after ScrollDeadzone is crossed, including cancellation; not every value change. Observe scrollbar ValueChanged for offset changes. ScrollHorizontalByDefault selects the preferred wheel axis and Shift changes the choice. CustomStep belongs to the internal scrollbar; a negative value uses its normal Step. Container wheel/gesture logic does not necessarily move by CustomStep.
ScrollHintMode/TileScrollHint control decorative hints using theme resources. DrawFocusBorder controls an existing focus outline without choosing a focused item. Check appearance and physical devices separately.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
ScrollContainerConstructor
public ScrollContainer();Creates an area with Auto on both axes, ClipContents = true and FollowFocus = false. Put the list in one child Container and let parent layout supply its visible size.
Properties12
DrawFocusBorderProperty
public bool DrawFocusBorder { get; set; }Draws an outline for eligible own/descendant focus; false by default. Does not call GrabFocus or create keyboard routing. Can affect internal styled margins.
FollowFocusProperty
public bool FollowFocus { get; set; }Automatic reveal when focus changes to a descendant, false by default. Does not define Tab/arrow order. Enabling it does not immediately reveal an already focused item.
HorizontalScrollModeProperty
public ScrollContainer.ScrollMode HorizontalScrollMode { get; set; }Horizontal-axis mode, Auto by default. Disabled affects content minimum while ShowNever only hides the bar. Changing it requests layout rather than changing child-list orientation.
ScrollDeadzoneProperty
public int ScrollDeadzone { get; set; }Accumulated touch-drag movement threshold in logical pixels before scrolling starts. Initialized from gui/common/default_scroll_deadzone. Neither a setter minimum offset nor a wheel step.
ScrollHintModeProperty
public ScrollContainer.ScrollHintModeEnum ScrollHintMode { get; set; }Which edges show decorative scroll hints; Disabled by default. Requires suitable theme textures/colors. Does not enable/disable scrolling itself.
ScrollHorizontalProperty
public int ScrollHorizontal { get; set; }Integer horizontal offset in logical pixels. Normal range is bounded by scrollbar MaxValue − Page. Setter cancels dragging; layout repositions content. Getter truncates a fractional scrollbar Value.
ScrollHorizontalByDefaultProperty
public bool ScrollHorizontalByDefault { get; set; }Prefers the horizontal wheel axis, false by default; Shift changes the choice. Does not replace HorizontalScrollMode or reorient content.
ScrollHorizontalCustomStepProperty
public float ScrollHorizontalCustomStep { get; set; }Internal horizontal scrollbar step. Negative values, default -1, use normal Step; nonnegative values set a custom step. Not a universal wheel, pan or touch-drag speed.
ScrollVerticalProperty
public int ScrollVertical { get; set; }Integer vertical offset; normal upper bound is scrollbar MaxValue − Page. Neither content height nor item index. Setter cancels dragging and an immediate descendant rectangle can still be stale.
ScrollVerticalCustomStepProperty
public float ScrollVerticalCustomStep { get; set; }Internal vertical scrollbar step; default -1 uses its Step. 0 sets a zero custom step rather than disabling all scrolling methods. Container wheel input follows separate logic.
TileScrollHintProperty
public bool TileScrollHint { get; set; }Tiles hint textures instead of stretching them, false by default. Affects hint appearance rather than scroll step/range.
VerticalScrollModeProperty
public ScrollContainer.ScrollMode VerticalScrollMode { get; set; }Vertical-axis mode, Auto by default. ShowNever keeps scrolling without a bar; Reserve keeps its space. Disabled/MaximizeFirst can make content height contribute to the container minimum.
Methods27
EnsureControlVisiblevoid
public void EnsureControlVisible(Control control);Scrolls toward a descendant using its current rectangle. Call after layout; sizes immediately after AddChild can be stale. Neither assigns focus nor enlarges the visible area for an oversized target.
| Name | Type | Default |
|---|---|---|
control | Control | — |
controlLive descendant Control of this ScrollContainer with current geometry; neither the container itself nor an unrelated item.
GetDeadzoneint
public int GetDeadzone();Accumulated touch-drag movement threshold in logical pixels before scrolling starts. Initialized from gui/common/default_scroll_deadzone. Neither a setter minimum offset nor a wheel step.
intCurrent stored setting rather than verification of rendering or physical input devices.
GetDrawFocusBorderbool
public bool GetDrawFocusBorder();Draws an outline for eligible own/descendant focus; false by default. Does not call GrabFocus or create keyboard routing. Can affect internal styled margins.
boolCurrent stored setting rather than verification of rendering or physical input devices.
GetHScrollint
public int GetHScroll();Integer horizontal offset in logical pixels. Normal range is bounded by scrollbar MaxValue − Page. Setter cancels dragging; layout repositions content. Getter truncates a fractional scrollbar Value.
intCurrent integer offset; fractional Value is truncated.
GetHScrollBarHScrollBar
public HScrollBar GetHScrollBar();Returns the internal HScrollBar owned by ScrollContainer. Exposes ValueChanged and Range bounds. Do not free it separately; the container recalculates MaxValue/Page.
HScrollBarShared reference to the internal child scrollbar rather than an object to Free/Dispose independently.
GetHorizontalCustomStepfloat
public float GetHorizontalCustomStep();Internal horizontal scrollbar step. Negative values, default -1, use normal Step; nonnegative values set a custom step. Not a universal wheel, pan or touch-drag speed.
floatCurrent stored setting rather than verification of rendering or physical input devices.
GetHorizontalScrollModeScrollContainer.ScrollMode
public ScrollContainer.ScrollMode GetHorizontalScrollMode();Horizontal-axis mode, Auto by default. Disabled affects content minimum while ShowNever only hides the bar. Changing it requests layout rather than changing child-list orientation.
ScrollContainer.ScrollModeCurrent stored setting rather than verification of rendering or physical input devices.
GetScrollHintModeScrollContainer.ScrollHintModeEnum
public ScrollContainer.ScrollHintModeEnum GetScrollHintMode();Which edges show decorative scroll hints; Disabled by default. Requires suitable theme textures/colors. Does not enable/disable scrolling itself.
ScrollContainer.ScrollHintModeEnumCurrent stored setting rather than verification of rendering or physical input devices.
GetVScrollint
public int GetVScroll();Integer vertical offset; normal upper bound is scrollbar MaxValue − Page. Neither content height nor item index. Setter cancels dragging and an immediate descendant rectangle can still be stale.
intCurrent integer offset; fractional Value is truncated.
GetVScrollBarVScrollBar
public VScrollBar GetVScrollBar();Returns the internal VScrollBar rather than a new independent resource. ValueChanged observes offset changes from different sources. Retain the reference only while the parent remains alive.
VScrollBarShared reference to the internal child scrollbar rather than an object to Free/Dispose independently.
GetVerticalCustomStepfloat
public float GetVerticalCustomStep();Internal vertical scrollbar step; default -1 uses its Step. 0 sets a zero custom step rather than disabling all scrolling methods. Container wheel input follows separate logic.
floatCurrent stored setting rather than verification of rendering or physical input devices.
GetVerticalScrollModeScrollContainer.ScrollMode
public ScrollContainer.ScrollMode GetVerticalScrollMode();Vertical-axis mode, Auto by default. ShowNever keeps scrolling without a bar; Reserve keeps its space. Disabled/MaximizeFirst can make content height contribute to the container minimum.
ScrollContainer.ScrollModeCurrent stored setting rather than verification of rendering or physical input devices.
IsFollowingFocusbool
public bool IsFollowingFocus();Automatic reveal when focus changes to a descendant, false by default. Does not define Tab/arrow order. Enabling it does not immediately reveal an already focused item.
boolCurrent stored setting rather than verification of rendering or physical input devices.
IsScrollHintTiledbool
public bool IsScrollHintTiled();Tiles hint textures instead of stretching them, false by default. Affects hint appearance rather than scroll step/range.
boolCurrent stored setting rather than verification of rendering or physical input devices.
IsScrollHorizontalByDefaultbool
public bool IsScrollHorizontalByDefault();Prefers the horizontal wheel axis, false by default; Shift changes the choice. Does not replace HorizontalScrollMode or reorient content.
boolCurrent stored setting rather than verification of rendering or physical input devices.
SetDeadzonevoid
public void SetDeadzone(int deadzone);Accumulated touch-drag movement threshold in logical pixels before scrolling starts. Initialized from gui/common/default_scroll_deadzone. Neither a setter minimum offset nor a wheel step.
| Name | Type | Default |
|---|---|---|
deadzone | int | — |
deadzoneNonnegative drag threshold in logical pixels. Setter stores the number without its own range validation.
SetDrawFocusBordervoid
public void SetDrawFocusBorder(bool draw);Draws an outline for eligible own/descendant focus; false by default. Does not call GrabFocus or create keyboard routing. Can affect internal styled margins.
| Name | Type | Default |
|---|---|---|
draw | bool | — |
drawtrue permits an eligible focus outline without calling GrabFocus.
SetFollowFocusvoid
public void SetFollowFocus(bool enabled);Automatic reveal when focus changes to a descendant, false by default. Does not define Tab/arrow order. Enabling it does not immediately reveal an already focused item.
| Name | Type | Default |
|---|---|---|
enabled | bool | — |
enabledtrue reacts to subsequent descendant focus changes; false disables automatic reveal.
SetHScrollvoid
public void SetHScroll(int value);Integer horizontal offset in logical pixels. Normal range is bounded by scrollbar MaxValue − Page. Setter cancels dragging; layout repositions content. Getter truncates a fractional scrollbar Value.
| Name | Type | Default |
|---|---|---|
value | int | — |
valueInteger logical offset; normal Range clamps it to MinValue and MaxValue − Page.
SetHorizontalCustomStepvoid
public void SetHorizontalCustomStep(float value);Internal horizontal scrollbar step. Negative values, default -1, use normal Step; nonnegative values set a custom step. Not a universal wheel, pan or touch-drag speed.
| Name | Type | Default |
|---|---|---|
value | float | — |
valueFinite scrollbar step: negative uses normal Step, nonnegative selects a custom step.
SetHorizontalScrollModevoid
public void SetHorizontalScrollMode(ScrollContainer.ScrollMode enable);Horizontal-axis mode, Auto by default. Disabled affects content minimum while ShowNever only hides the bar. Changing it requests layout rather than changing child-list orientation.
| Name | Type | Default |
|---|---|---|
enable | ScrollContainer.ScrollMode | — |
enableScrollMode enum value despite the enable name; not a bool.
SetScrollHintModevoid
public void SetScrollHintMode(ScrollContainer.ScrollHintModeEnum scrollHintMode);Which edges show decorative scroll hints; Disabled by default. Requires suitable theme textures/colors. Does not enable/disable scrolling itself.
| Name | Type | Default |
|---|---|---|
scrollHintMode | ScrollContainer.ScrollHintModeEnum | — |
scrollHintModeScrollHintModeEnum selecting edges, or Disabled for no hints.
SetScrollHorizontalByDefaultvoid
public void SetScrollHorizontalByDefault(bool enable);Prefers the horizontal wheel axis, false by default; Shift changes the choice. Does not replace HorizontalScrollMode or reorient content.
| Name | Type | Default |
|---|---|---|
enable | bool | — |
enabletrue prefers horizontal wheel input; false uses normal vertical preference.
SetTileScrollHintvoid
public void SetTileScrollHint(bool tileScrollHint);Tiles hint textures instead of stretching them, false by default. Affects hint appearance rather than scroll step/range.
| Name | Type | Default |
|---|---|---|
tileScrollHint | bool | — |
tileScrollHinttrue tiles hint textures; false stretches them.
SetVScrollvoid
public void SetVScroll(int value);Integer vertical offset; normal upper bound is scrollbar MaxValue − Page. Neither content height nor item index. Setter cancels dragging and an immediate descendant rectangle can still be stale.
| Name | Type | Default |
|---|---|---|
value | int | — |
valueInteger logical offset; normal Range clamps it to MinValue and MaxValue − Page.
SetVerticalCustomStepvoid
public void SetVerticalCustomStep(float value);Internal vertical scrollbar step; default -1 uses its Step. 0 sets a zero custom step rather than disabling all scrolling methods. Container wheel input follows separate logic.
| Name | Type | Default |
|---|---|---|
value | float | — |
valueFinite scrollbar step: negative uses normal Step, nonnegative selects a custom step.
SetVerticalScrollModevoid
public void SetVerticalScrollMode(ScrollContainer.ScrollMode enable);Vertical-axis mode, Auto by default. ShowNever keeps scrolling without a bar; Reserve keeps its space. Disabled/MaximizeFirst can make content height contribute to the container minimum.
| Name | Type | Default |
|---|---|---|
enable | ScrollContainer.ScrollMode | — |
enableScrollMode enum value despite the enable name; not a bool.
Signals and events2
ScrollEndedEvent
public event Action ScrollEnded;Signal when a drag that crossed the deadzone ends or is canceled. Setting an offset can cancel active dragging. Not completion of every programmatic move.
ScrollStartedEvent
public event Action ScrollStarted;Signal when drag scrolling crosses the deadzone. Not guaranteed for wheel input or SetVScroll/SetHScroll; use scrollbar ValueChanged to observe values.
ScrollContainer.ScrollHintModeEnum
| Value | Description |
|---|---|
All = 1 | Scroll hints will be shown at the top and bottom (if vertical), or left and right (if horizontal). |
Bottom = 7 | Scroll hint will be shown at the bottom. |
BottomAndRight = 3 | Scroll hints will be shown at the bottom (if horizontal), or the right (if horizontal). |
Disabled = 0 | Scroll hints will never be shown. |
Left = 8 | Scroll hint will be shown on the left. |
LeftAndRight = 5 | Scroll hints will be shown on the left and right. |
Right = 9 | Scroll hint will be shown on the right. |
Top = 6 | Scroll hint will be shown at the top. |
TopAndBottom = 4 | Scroll hints will be shown at the top and bottom. |
TopAndLeft = 2 | Scroll hints will be shown at the top (if vertical), or the left (if horizontal). |
ScrollContainer.ScrollMode
| Value | Description |
|---|---|
Auto = 1 | Scrolling enabled, scrollbar will be visible only if necessary, i.e. container's content is bigger than the container. |
Disabled = 0 | Scrolling disabled, scrollbar will be invisible. |
MaximizeFirst = 5 | Behaves like |
Reserve = 4 | Combines |
ShowAlways = 2 | Scrolling enabled, scrollbar will be always visible. |
ShowNever = 3 | Scrolling enabled, scrollbar will be hidden. |
Theme properties
These are Theme resource keys, not C# properties. Use the matching Control GetTheme…() and AddTheme…Override() methods for each value type.
| Key and type | Description |
|---|---|
scroll_hint_horizontal_colorColor |
Color(0, 0, 0, 1) |
scroll_hint_vertical_colorColor |
Color(0, 0, 0, 1) |
scrollbar_h_separationint | The space between the ScrollContainer's vertical scroll bar and its content, in pixels. No space will be added when the content's minimum size is larger than the ScrollContainer's size. Default:0 |
scrollbar_margin_bottomint | The bottom margin of the horizontal scrollbar. When negative, uses -1 |
scrollbar_margin_leftint | The left margin of the horizontal scrollbar. When negative, uses -1 |
scrollbar_margin_rightint | The right margin of the horizontal scrollbar. When negative, uses -1 |
scrollbar_margin_topint | The top margin of the horizontal scrollbar. When negative, uses -1 |
scrollbar_v_separationint | The space between the ScrollContainer's horizontal scroll bar and its content, in pixels. No space will be added when the content's minimum size is larger than the ScrollContainer's size. Default:0 |
scroll_hint_horizontalTexture2D | The indicator that will be shown when the content can still be scrolled horizontally. See |
scroll_hint_verticalTexture2D | The indicator that will be shown when the content can still be scrolled vertically. See |
focusStyleBox | The focus border |
panelStyleBox | The background |