Модуль: kivy.uix.scrollview
Added in 1.0.4
Элемент ScrollView
обеспечивает прокрутку для возможности просмотра области, выходящей за его пределы.
ScrollView принимает только один дочерний элемент и применяет к нему область просмотра в соответствии со свойствами scroll_x
и scroll_y
. Прикосновения анализируются, чтобы определить, хочет ли пользователь прокручивать или управлять дочерним элементом каким-либо другим способом: вы не можете делать и то, и то одновременно. Чтобы определить, является ли взаимодействие жестом прокрутки, используются следующие свойства:
scroll_distance
: минимальное расстояние для перемещения, по умолчанию 20 пикселейscroll_timeout
: максимальный период времени, по умолчанию 55 миллисекунд
Если касание перемещает пиксели scroll_distance
в течение периода scroll_timeout
, оно распознается как жест прокрутки, и начнется перевод (прокрутка/панорамирование). Если тайм-аут происходит, событие касания вниз отправляется дочернему элементу.
Значение по умолчанию для этих параметров можно изменить в файле конфигурации:
[widgets] scroll_timeout = 250 scroll_distance = 20
Начиная с версии 1.1.1, ScrollView
теперь анимирует прокрутку в Y при использовании колесика мыши.
Ограничение прокрутки по оси X или Y:
По умолчанию ScrollView позволяет прокручивать как по оси X, так и по оси Y. Вы можете явно отключить прокрутку по оси, установив свойства do_scroll_x
или do_scroll_y
в значение False
.
Управление размером и положением контента:
ScrollView управляет положением своих дочерних элементов аналогично RelativeLayout, но не использует size_hint
. Вы должны тщательно указать размер вашего контента, чтобы получить желаемый эффект прокрутки/панорамирования.
По умолчанию size_hint
равен (1, 1)
, поэтому размер содержимого будет точно соответствовать вашему ScrollView (вам нечего будет прокручивать). Для включения прокрутки необходимо деактивировать хотя бы одну из инструкций size_hint
(x или y) дочернего элемента. Установка значения size_hint_mine
равным None также позволит выполнить прокрутку для этого измерения, если размер ScrollView меньше минимального размера.
Чтобы прокрутить GridLayout по его оси Y / вертикали, установите ширину дочернего элемента в ширину ScrollView (size_hint_x=1
) и установите свойство size_hint_y
равным None
:
from kivy.uix.gridlayout import GridLayout from kivy.uix.button import Button from kivy.uix.scrollview import ScrollView from kivy.core.window import Window from kivy.app import runTouchApp layout = GridLayout(cols=1, spacing=10, size_hint_y=None) # убеждаемся, что высота такая, что есть место для прокрутки: layout.bind(minimum_height=layout.setter('height')) for i in range(100): btn = Button(text=str(i), size_hint_y=None, height=40) layout.add_widget(btn) root = ScrollView(size_hint=(1, None), size=(Window.width, Window.height)) root.add_widget(layout) runTouchApp(root)
Аналогичный пример kv-language:
ScrollView: do_scroll_x: False do_scroll_y: True Label: size_hint_y: None height: self.texture_size[1] text_size: self.width padding: 10, 10 text: 'really some amazing text\n' * 100
Описание API класса ScrollView:
- class
kivy.uix.scrollview.
ScrollView
(**kwargs)
События:
- on_scroll_start — генерирует событие, когда прокрутка начинается с касания
- on_scroll_move — генерирует событие во время прокрутки
- on_scroll_stop — генерирует событие, когда прокрутка остановлена касанием
Каждое из этих событий принимает аргумент touch типа MotionEvent и возвращает булево значение. Аргумент touch содержит координаты касания в родительской системе координат. Возвращаемое значение в случае True остановит отправку события касания, False — продолжит.
Методы и атрибуты:
- add_widget(widget, index=0)
- Метод в неизменном виде унаследован от Widget и добавляет новый виджет как дочерний элемент в наш ScrollView. Параметры:
- widget:
Widget
- виджет для добавления
- index:
int
, по умолчанию 0 - Индекс для вставки виджета в список. Обратите внимание, что значение по умолчанию 0 означает, что виджет вставляется в начале списка и, таким образом, будет отображаться поверх других родственных виджетов.
- canvas:
str
, по умолчанию None - Добавлен в версии 1.9.0. — объект
Canvas
для добавления холста для виджета. Может иметь значения ‘before’, ‘after’ или None. (последнее является значением по умолчанию)
- widget:
- bar_width=2
- Устанавливает ширину скроллбара вертикальной/горизонтальной прокрутки. Ширина для горизонтального понимается как его высота. Является NumericProperty и по умолчанию имеет значение 2
- remove_widget(widget)
- Удаляет виджет из списка дочерних элементов ScrollView
- scroll_distance=20
- NumericProperty. Задает расстояние для перемещения перед прокруткой ScrollView, в пикселях. Как только расстояние будет пройдено, ScrollView начнет прокручиваться, и никакое событие касания не перейдет к дочерним элементам. Желательно, чтобы вы основывали это значение на dpi экрана вашего целевого устройства
- scroll_timeout=55
- Тайм-аут, разрешенный для запуска scroll_distance, в миллисекундах. Если пользователь не переместил scroll_distance в течение таймаута, прокрутка будет отключена, и событие касания перейдет к дочерним элементам.
- scroll_to(widget, padding=10, animate=True)
- Прокручивает видовой экран, чтобы убедиться, что данный виджет виден, при необходимости с дополнением и анимацией. Если animate имеет значение True (по умолчанию), то будут использоваться параметры анимации по умолчанию. В противном случае это должен быть дикт, содержащий аргументы для передачи конструктору анимации.
- scroll_type=[‘content’]
- OptionProperty. Задает тип прокрутки, используемый для содержимого scrollview. Доступные опции: [‘content‘], [’bars‘], [’bars‘,’content’]. [‘content’] означает, что содержимое прокручивается путем перетаскивания или прокрутки содержимого напрямую, [‘bars’] — прокрутки скроллбара, [’bars‘,’content’] — оба варианта..
- scroll_x=0
- NumericProperty. X значение прокрутки, между 0 и 1. Если 0, то левая сторона содержимого будет касаться левой стороны ScrollView. Если 1, правая сторона содержимого будет касаться правой стороны.
- scroll_y=0
- NumericProperty. То же самое, но для Y ординат
- smooth_scroll_end=None
- Следует ли использовать плавный конец прокрутки при прокрутке колесиком мыши и коэффициент преобразования расстояния прокрутки в скорость. Эта опция также включает значение добавления скорости, если вы прокручиваете больше, вы будете прокручивать быстрее и дальше. Рекомендуемое значение-10. Скорость рассчитывается как scroll_wheel_distance * smooth_scroll_end.
- to_local(x, y, **k)
- Преобразование родительских координат в локальные координаты. Измените значение на True, если вы хотите перевести координаты в относительные координаты виджета.
- to_parent(x, y, **k)
- Преобразование локальных координат в родительские координаты. Измените значение на True, если вы хотите перевести координаты в относительные координаты родителя.
- update_from_scroll(*largs)
- Провоцирует перемещение содержания контента в соответствии с текущим значением scroll_x и scroll_your.
Этот метод подобно событию автоматически вызывается при изменении одного из свойств scroll_x, scroll_y, pos или size или при изменении размера содержимого. - vbar
- Возвращает кортеж (pos, size) вертикальной полосы прокрутки. Положение и размер являются дробным числом между 0-1 и представляют собой процент от текущей высоты прокрутки. Это свойство используется внутренне для рисования небольшой вертикальной полосы при прокрутке. Только для чтения
- viewport_size
- (внутренний) размер внутреннего видового экрана. Это размер вашего единственного дочернего элемента в scrollview.
Англоязычный источник тут. Исходники тут. На момент написания статьи недоступны без vpn.
от