ScrollContainer — C# API

Прокручиваемая область Control с управляемым содержимым и полосами прокрутки.

class ScrollContainerReckfellSharpНаследует Container

ScrollContainer ограничивает видимую область содержимого и смещает его по горизонтали/вертикали. Для списка добавьте одну колонку VBoxContainer и поместите элементы в неё; несколько прямых детей не образуют список автоматически. Контейнер включает ClipContents. Размер видимой области задаёт родительская раскладка, минимум содержимого определяет диапазон.

ScrollHorizontal/ScrollVertical — целые логические смещения. Их setter меняет значение полосы и отменяет активный drag; прямоугольники содержимого обновляются проходом раскладки. При стандартных настройках Range верхний предел равен MaxValue − Page, а не MaxValue. Получить границы и ValueChanged можно у GetHScrollBar/GetVScrollBar. Это внутренние дочерние объекты: не освобождайте их отдельно; их MaxValue/Page пересчитываются контейнером. Если значение полосы дробное, целый getter ScrollContainer отбрасывает дробную часть.

Режимы оси различаются: Disabled отключает её прокрутку и включает соответствующий минимум содержимого в минимум контейнера; Auto показывает полосу при необходимости; ShowAlways показывает постоянно; ShowNever скрывает полосу, сохраняя прокрутку; Reserve резервирует место даже без видимой полосы. MaximizeFirst сначала учитывает желаемый размер содержимого до конечного максимума контейнера; без подходящего максимума область может вырасти вместо ожидаемой прокрутки. Не заменяйте Disabled на ShowNever в расчёте получить одинаковые ограничения.

EnsureControlVisible принимает потомка и рассчитывает необходимое смещение по его актуальному прямоугольнику. После добавления/изменения детей дождитесь раскладки, например отложенным вызовом после создания списка. Метод не устанавливает фокус и не обещает целиком вместить элемент, который больше видимой области. FollowFocus вызывает такой переход при смене фокуса на потомка; одно включение флага не прокручивает к уже выбранному элементу автоматически.

ScrollStarted/ScrollEnded относятся к drag после преодоления ScrollDeadzone, включая его отмену; это не универсальные события каждого изменения. Для наблюдения за значением подключайтесь к ValueChanged полос. ScrollHorizontalByDefault задаёт предпочтение оси колеса, Shift меняет выбор. CustomStep задаёт шаг внутренней полосы; отрицательное значение использует её обычный Step. Колесо контейнера и жесты имеют другую логику и не обязаны двигаться на CustomStep.

ScrollHintMode/TileScrollHint управляют декоративными подсказками с ресурсами темы. DrawFocusBorder управляет рамкой уже существующего фокуса и сам не выбирает элемент. Проверяйте оформление и реальные устройства отдельно.

Пример списка и перехода к пункту.

Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.

Конструкторы1

ScrollContainerКонструктор

# ScrollContainer

C#
public ScrollContainer();

Создаёт область с Auto по обеим осям, ClipContents = true и FollowFocus = false. Поместите список в один дочерний Container и задайте доступный размер родительской раскладкой.

Свойства12

DrawFocusBorderСвойство

# DrawFocusBorder

C#
public bool DrawFocusBorder { get; set; }

Рисует рамку при подходящем собственном/дочернем фокусе; по умолчанию false. Не вызывает GrabFocus и не включает клавиатурный маршрут сам. Настройка может менять внутренние отступы оформления.

FollowFocusСвойство

# FollowFocus

C#
public bool FollowFocus { get; set; }

Автоматический переход при смене фокуса на потомка, по умолчанию false. Не задаёт порядок Tab/стрелок. Включение не вызывает немедленный переход к уже сфокусированному элементу.

HorizontalScrollModeСвойство

# HorizontalScrollMode

C#
public ScrollContainer.ScrollMode HorizontalScrollMode { get; set; }

Режим горизонтальной оси, Auto по умолчанию. Disabled влияет на минимум содержимого, ShowNever только скрывает полосу. Смена режима запрашивает раскладку; не меняет ориентацию дочернего списка.

ScrollDeadzoneСвойство

# ScrollDeadzone

C#
public int ScrollDeadzone { get; set; }

Порог накопленного touch-drag движения в логических пикселях до начала прокрутки. Начальное значение берётся из gui/common/default_scroll_deadzone. Это не минимальное смещение setter и не шаг колеса.

ScrollHintModeСвойство

# ScrollHintMode

C#
public ScrollContainer.ScrollHintModeEnum ScrollHintMode { get; set; }

Какие края показывают декоративные подсказки прокрутки; по умолчанию Disabled. Нужны подходящие текстуры/цвета темы. Не включает/отключает саму прокрутку.

ScrollHorizontalСвойство

# ScrollHorizontal

C#
public int ScrollHorizontal { get; set; }

Целое горизонтальное смещение в логических пикселях. Стандартный диапазон ограничен MaxValue − Page полосы. Setter отменяет drag; содержимое перемещается проходом раскладки. Дробный Value полосы getter усечёт.

ScrollHorizontalByDefaultСвойство

# ScrollHorizontalByDefault

C#
public bool ScrollHorizontalByDefault { get; set; }

Предпочтение горизонтальной оси для колеса, по умолчанию false; Shift меняет выбор. Не заменяет HorizontalScrollMode и не переориентирует содержимое.

ScrollHorizontalCustomStepСвойство

# ScrollHorizontalCustomStep

C#
public float ScrollHorizontalCustomStep { get; set; }

Шаг внутренней горизонтальной полосы. Отрицательное значение, по умолчанию -1, использует обычный Step; неотрицательное задаёт custom step. Не универсальная скорость колеса, pan или touch-drag.

ScrollVerticalСвойство

# ScrollVertical

C#
public int ScrollVertical { get; set; }

Целое вертикальное смещение; стандартный максимум равен MaxValue − Page полосы. Не высота содержимого и не номер элемента. Setter отменяет drag, а немедленный прямоугольник потомка может ещё быть прежним.

ScrollVerticalCustomStepСвойство

# ScrollVerticalCustomStep

C#
public float ScrollVerticalCustomStep { get; set; }

Шаг внутренней вертикальной полосы; -1 по умолчанию использует её Step. 0 задаёт нулевой custom step, а не выключает все способы прокрутки. Колесо контейнера использует собственную логику.

TileScrollHintСвойство

# TileScrollHint

C#
public bool TileScrollHint { get; set; }

Повторение текстуры подсказки вместо растяжения, false по умолчанию. Влияет на рисунок hint, не на шаг или диапазон прокрутки.

VerticalScrollModeСвойство

# VerticalScrollMode

C#
public ScrollContainer.ScrollMode VerticalScrollMode { get; set; }

Режим вертикальной оси, Auto по умолчанию. ShowNever сохраняет прокрутку без полосы; Reserve сохраняет её место. Disabled/MaximizeFirst могут заставить контейнер учитывать высоту содержимого в минимуме.

Методы27

EnsureControlVisiblevoid

# EnsureControlVisible

C#
public void EnsureControlVisible(Control control);

Прокручивает к потомку по его актуальному прямоугольнику. Вызывайте после раскладки; сразу после AddChild размеры могут быть прежними. Не задаёт фокус и не увеличивает видимую область для слишком большого элемента.

Параметры
Имя	Тип	По умолчанию
`control`	`Control`	—

control

Живой Control-потомок этого ScrollContainer с актуальными размерами; не сам контейнер и не чужой элемент.

GetDeadzoneint

# GetDeadzone

C#
public int GetDeadzone();

Возвращает int

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetDrawFocusBorderbool

# GetDrawFocusBorder

C#
public bool GetDrawFocusBorder();

Возвращает bool

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetHScrollint

# GetHScroll

C#
public int GetHScroll();

Возвращает int

Текущее целое смещение; дробная часть Value отбрасывается.

GetHScrollBarHScrollBar

# GetHScrollBar

C#
public HScrollBar GetHScrollBar();

Возвращает внутренний HScrollBar, принадлежащий ScrollContainer. Через него доступны ValueChanged и границы Range. Не освобождайте отдельно; MaxValue/Page будут пересчитаны контейнером.

Возвращает HScrollBar

Общая ссылка на внутреннюю дочернюю полосу, не объект для отдельного Free/Dispose.

GetHorizontalCustomStepfloat

# GetHorizontalCustomStep

C#
public float GetHorizontalCustomStep();

Возвращает float

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetHorizontalScrollModeScrollContainer.ScrollMode

# GetHorizontalScrollMode

C#
public ScrollContainer.ScrollMode GetHorizontalScrollMode();

Возвращает ScrollContainer.ScrollMode

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetScrollHintModeScrollContainer.ScrollHintModeEnum

# GetScrollHintMode

C#
public ScrollContainer.ScrollHintModeEnum GetScrollHintMode();

Возвращает ScrollContainer.ScrollHintModeEnum

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetVScrollint

# GetVScroll

C#
public int GetVScroll();

Возвращает int

Текущее целое смещение; дробная часть Value отбрасывается.

GetVScrollBarVScrollBar

# GetVScrollBar

C#
public VScrollBar GetVScrollBar();

Возвращает внутренний VScrollBar, не новый независимый ресурс. ValueChanged полезен для наблюдения за смещением любого источника. Храните ссылку только пока жив родитель.

Возвращает VScrollBar

Общая ссылка на внутреннюю дочернюю полосу, не объект для отдельного Free/Dispose.

GetVerticalCustomStepfloat

# GetVerticalCustomStep

C#
public float GetVerticalCustomStep();

Возвращает float

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

GetVerticalScrollModeScrollContainer.ScrollMode

# GetVerticalScrollMode

C#
public ScrollContainer.ScrollMode GetVerticalScrollMode();

Возвращает ScrollContainer.ScrollMode

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

IsFollowingFocusbool

# IsFollowingFocus

C#
public bool IsFollowingFocus();

Возвращает bool

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

IsScrollHintTiledbool

# IsScrollHintTiled

C#
public bool IsScrollHintTiled();

Возвращает bool

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

IsScrollHorizontalByDefaultbool

# IsScrollHorizontalByDefault

C#
public bool IsScrollHorizontalByDefault();

Возвращает bool

Текущее сохранённое значение настройки. Не проверка рисунка или физического устройства ввода.

SetDeadzonevoid

# SetDeadzone

C#
public void SetDeadzone(int deadzone);

Параметры
Имя	Тип	По умолчанию
`deadzone`	`int`	—

deadzone

Неотрицательный порог drag в логических пикселях. Setter хранит переданное число без собственной проверки диапазона.

SetDrawFocusBordervoid

# SetDrawFocusBorder

C#
public void SetDrawFocusBorder(bool draw);

Параметры
Имя	Тип	По умолчанию
`draw`	`bool`	—

draw

true разрешает рамку подходящего фокуса; не вызывает GrabFocus.

SetFollowFocusvoid

# SetFollowFocus

C#
public void SetFollowFocus(bool enabled);

Параметры
Имя	Тип	По умолчанию
`enabled`	`bool`	—

enabled

true реагирует на следующие смены фокуса потомков; false выключает автоматический переход.

SetHScrollvoid

# SetHScroll

C#
public void SetHScroll(int value);

Параметры
Имя	Тип	По умолчанию
`value`	`int`	—

value

Целое логическое смещение; штатный Range ограничивает его своими MinValue и MaxValue − Page.

SetHorizontalCustomStepvoid

# SetHorizontalCustomStep

C#
public void SetHorizontalCustomStep(float value);

Параметры
Имя	Тип	По умолчанию
`value`	`float`	—

value

Конечный шаг полосы: отрицательный использует обычный Step, неотрицательный — custom step.

SetHorizontalScrollModevoid

# SetHorizontalScrollMode

C#
public void SetHorizontalScrollMode(ScrollContainer.ScrollMode enable);

Параметры
Имя	Тип	По умолчанию
`enable`	`ScrollContainer.ScrollMode`	—

enable

Значение enum ScrollMode, несмотря на имя enable; это не bool.

SetScrollHintModevoid

# SetScrollHintMode

C#
public void SetScrollHintMode(ScrollContainer.ScrollHintModeEnum scrollHintMode);

Параметры
Имя	Тип	По умолчанию
`scrollHintMode`	`ScrollContainer.ScrollHintModeEnum`	—

scrollHintMode

ScrollHintModeEnum выбранных краёв либо Disabled без подсказок.

SetScrollHorizontalByDefaultvoid

# SetScrollHorizontalByDefault

C#
public void SetScrollHorizontalByDefault(bool enable);

Параметры
Имя	Тип	По умолчанию
`enable`	`bool`	—

enable

true предпочитает горизонтальное колесо, false — обычный выбор вертикальной оси.

SetTileScrollHintvoid

# SetTileScrollHint

C#
public void SetTileScrollHint(bool tileScrollHint);

Параметры
Имя	Тип	По умолчанию
`tileScrollHint`	`bool`	—

tileScrollHint

true повторяет текстуры hint, false растягивает их.

SetVScrollvoid

# SetVScroll

C#
public void SetVScroll(int value);

Параметры
Имя	Тип	По умолчанию
`value`	`int`	—

value

Целое логическое смещение; штатный Range ограничивает его своими MinValue и MaxValue − Page.

SetVerticalCustomStepvoid

# SetVerticalCustomStep

C#
public void SetVerticalCustomStep(float value);

Параметры
Имя	Тип	По умолчанию
`value`	`float`	—

value

Конечный шаг полосы: отрицательный использует обычный Step, неотрицательный — custom step.

SetVerticalScrollModevoid

# SetVerticalScrollMode

C#
public void SetVerticalScrollMode(ScrollContainer.ScrollMode enable);

Параметры
Имя	Тип	По умолчанию
`enable`	`ScrollContainer.ScrollMode`	—

enable

Значение enum ScrollMode, несмотря на имя enable; это не bool.

Сигналы и события2

ScrollEndedСобытие

# ScrollEnded

public event Action ScrollEnded;

Сигнал завершения/отмены drag, который преодолел deadzone. Setter смещения может отменить активный drag. Это не сигнал окончания любого программного перехода.

ScrollStartedСобытие

# ScrollStarted

public event Action ScrollStarted;

Сигнал начала drag-прокрутки после преодоления deadzone. Не гарантируется для колеса или SetVScroll/SetHScroll; для изменения значения используйте ValueChanged полосы.

ScrollContainer.ScrollHintModeEnum

Значение	Описание
`All = 1`	Подсказки при прокрутке будут отображаться вверху и внизу (при вертикальной прокрутке) или слева и справа (при горизонтальной прокрутке).
`Bottom = 7`	Свиток будет показан внизу.
`BottomAndRight = 3`	Подсказки при прокрутке будут отображаться внизу (если горизонтальная прокрутка) или справа (если горизонтальная прокрутка).
`Disabled = 0`	Подсказки при прокрутке никогда не будут отображаться.
`Left = 8`	Слева будет показан намек на свиток.
`LeftAndRight = 5`	Свитки будут показаны слева и справа.
`Right = 9`	Справа будет показан намек на свиток.
`Top = 6`	Наверху будет показан намек на свиток.
`TopAndBottom = 4`	Подсказки при прокрутке будут отображаться вверху и внизу.
`TopAndLeft = 2`	Подсказки при прокрутке будут отображаться вверху (если прокрутка вертикальная) или слева (если прокрутка горизонтальная).

ScrollContainer.ScrollMode

Значение	Описание
`Auto = 1`	Прокрутка включена, полоса прокрутки будет видна только при необходимости, т. е. если содержимое контейнера больше самого контейнера.
`Disabled = 0`	Прокрутка отключена, полоса прокрутки будет невидима.
`MaximizeFirst = 5`	Ведёт себя как `ScrollContainer.ScrollMode.Auto`, но заставляет `ScrollContainer` сообщать минимальный размер на основе его содержимого (ограниченный `Control.CustomMaximumSize`, если он установлен на соответствующей оси). Это позволяет ему сначала увеличиваться и начинать прокрутку только после того, как он будет ограничен.
`Reserve = 4`	Объединяет `ScrollContainer.ScrollMode.Auto` и `ScrollContainer.ScrollMode.ShowAlways`. Полоса прокрутки видна только при необходимости, но размер контента регулируется так, как если бы он был виден всегда. Это полезно для обеспечения того, чтобы размер контента оставался неизменным независимо от того, видна ли полоса прокрутки.
`ShowAlways = 2`	Прокрутка включена, полоса прокрутки всегда будет видна.
`ShowNever = 3`	Прокрутка включена, полоса прокрутки будет скрыта.

Свойства темы

Это ключи ресурсов Theme, а не свойства C# класса. Используйте методы GetTheme…() и AddTheme…Override() у Control с соответствующим типом значения.

Ключ и тип	Описание
`scroll_hint_horizontal_color` `Color`	`Color` используется для модуляции текстуры `ScrollContainer.scroll_hint_horizontal`. По умолчанию: `Color(0, 0, 0, 1)`
`scroll_hint_vertical_color` `Color`	`Color` используется для модуляции текстуры `ScrollContainer.scroll_hint_vertical`. По умолчанию: `Color(0, 0, 0, 1)`
`scrollbar_h_separation` `int`	Расстояние между вертикальной полосой прокрутки ScrollContainer и его содержимым, в пикселях. Если минимальный размер содержимого превышает размер ScrollContainer, расстояние не добавляется. По умолчанию: `0`
`scrollbar_margin_bottom` `int`	Нижний предел горизонтального свитка. [:: нижняя окраина темы [тематическая дискуссия] По умолчанию: `-1`
`scrollbar_margin_left` `int`	В случае отрицательного, используется левая полоса горизонтального свитка. [b) левая сторона темы [тематическая дискуссия]. По умолчанию: `-1`
`scrollbar_margin_right` `int`	Правый край горизонтального свитка. [тема [на дискуссионном форуме] - правильная разница. По умолчанию: `-1`
`scrollbar_margin_top` `int`	Верхняя полоса горизонтального свитка. [:: верхняя окраина темы [тематическая дискуссия] По умолчанию: `-1`
`scrollbar_v_separation` `int`	Расстояние между горизонтальной полосой прокрутки ScrollContainer и его содержимым, в пикселях. Если минимальный размер содержимого превышает размер ScrollContainer, расстояние не добавляется. По умолчанию: `0`
`scroll_hint_horizontal` `Texture2D`	Индикатор, который будет отображаться, когда контент еще можно прокручивать по горизонтали. См. `ScrollContainer.ScrollHintMode`.
`scroll_hint_vertical` `Texture2D`	Индикатор, который будет отображаться, когда контент еще можно прокручивать вертикально. См. `ScrollContainer.ScrollHintMode`. Сосредоточься
`focus` `StyleBox`	Граница фокуса `StyleBox` `ScrollContainer`. Используется только если `ScrollContainer.DrawFocusBorder` равен `true`.
`panel` `StyleBox`	Фон `StyleBox` `ScrollContainer`.