Table Of Contents

• Event Manager
  • When to use an event manager
  • Defining and registering an event manager
  • Dispatching events to the widgets

Менеджер событий

EventManagerBase является абстрактным классом, предназначенным для конкретной реализации распределения событий движения (экземпляры MotionEvent) для виджетов через метод on_motion() класса Widget.

Предупреждение

Эта функция является экспериментальной и остаётся таковой, пока это предупреждение присутствует.

Менеджер - это прослойка между окном и его виджетами. WindowBase будет пересылать все события, которые он получает, в метод on_motion() всем менеджерам, которые заявили, что они хотят получать события этого типа. Событие будет продолжать проходить по списку менеджеров даже в том случае, если один из них его примет (вернёт True).

Когда использовать менеджер событий

Используйте менеджер, когда вам нужно:

• Распределять события касания, наведения, клавиатуры, джойстика или любые другие события к виджетам через метод on_motion().

• Распределять отфильтрованные события движения по каким-либо критериям, таким как device или profile.

• Объединять несколько событий движения (касание, наведение и так далее) в одно новое событие и распределять его по виджетам.

• Распределять одноразовые общие события, такие как приостановка/возобновление приложения.

• Создать симулятор событий, такой как симулятор касания, который рисует круг на холсте окна для каждого симулированного касания.

Определение и регистрация менеджера событий

1. Унаследуйтесь от EventManagerBase и определите, какие события должен получать этот менеджер, объявив типы событий в атрибуте EventManagerBase.type_ids.

2. Реализуйте метод < code class="xref py py-meth docutils literal notranslate">EventManagerBase.dispatch(), который будет вызван окном, чтобы передать тип события (один из “begin”, “update”, “end”) и событие.

3. Реализуйте методы EventManagerBase.start() и EventManagerBase.stop() для выделения и освобождения дополнительных ресурсов при необходимости.

4. Зарегистрируйте экземпляр менеджера в окне, используя метод register_event_manager(). Это можно сделать путем переопределения методов build() или on_start().

Все зарегистрированные менеджеры хранятся в списке event_managers. Чтобы отменить регистрацию менеджера, вызовите метод unregister_event_manager(), который в свою очередь может быть вызван в методе on_stop().

Распределение событий по виджетам

После регистрации окно запустит менеджера и пересылает все события указанных типов в атрибуте EventManagerBase.type_ids методу EventManagerBase.dispatch() менеджера. Это зависит от менеджера, каким образом он будет их распределять, либо путем прохода по списку EventManagerBase.window.children и распределения события on_motion, либо используя другую логику. Также менеджер может распределять захваченные события, если событие поддерживает функцию захвата (см. методы grab() и ungrab()).

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

Распределение событий в виджеты

После регистрации окно запустит менеджер и пересылает все события типов, объявленных в EventManagerBase.type_ids, в метод EventManagerBase.dispatch() менеджера. Менеджеру предоставляется право решать, как их распределять, будь то путем прохождения через список EventManagerBase.window.children и передачи события on_motion, или путем использования другой логики. Также менеджеру предоставляется возможность передачи захваченных событий, если функция захвата поддерживается событием (см. методы grab() и ungrab()).

Менеджер может назначить разный режим распределения, чтобы определить, как событие должно распространяться по всему дереву виджетов, изменив значение атрибута dispatch_mode. Перед изменением режима менеджер должен сохранить/восстановить текущий режим, либо используя локальную переменную, либо с помощью методов push() / pop() события.

На данный момент существует три режима распределения (поведения), распознаваемых методом on_motion в классе Widget:

1. Режим распределения по умолчанию (требует MODE_DEFAULT_DISPATCH) - событие будет проходить через список дочерних виджетов, начиная с первого виджета в списке, пока событие не будет принято или не будет достигнут последний виджет, зарегистрированный для этого события. Режим MODE_DEFAULT_DISPATCH назначается по умолчанию в классе MotionEvent.

2. Режим фильтрации распределения (требует MODE_FILTERED_DISPATCH) - событие будет проходить только через зарегистрированные дочерние виджеты.

3. Режим отсутствия распределения дочерним виджетам (требует MODE_DONT_DISPATCH) - событие не будет передаваться дочерним виджетам.

Обратите внимание, что у окна нет свойства motion_filter, и поэтому оно не имеет списка отфильтрованных виджетов из своего списка children.

Класс kivy.eventmanager.EventManagerBase

Базовый класс с методами start(), stop() и dispatch(), предназначенными для реализации в конкретном классе.

Пример менеджера, принимающего события касания и наведения:

class TouchHoverManager(EventManagerBase):

    type_ids = ('touch', 'hover')

    def start(self):
        # Создать дополнительные ресурсы, привязать обратные вызовы к self.window

    def dispatch(self, etype, me):
        if me.type_id == 'touch':
            # Обработать событие касания
        elif me.type_id == 'hover'
            # Обработать событие наведения

    def stop(self):
        # Освободить ресурсы

dispatch(etype, me)

Распределить событие me в виджеты в window.

Parameters

etype: str

Один из “begin”, “update” или “end”

me: MotionEvent

Текущее событие движения, которое передается.

Returns

bool True, чтобы остановить передачу событий

New in version 2.1.0.

start()

Запускает менеджер, привязывает обратные вызовы к объектам и создает дополнительные ресурсы. Атрибут window присваивается, когда этот метод вызывается.

Добавлено в версии 2.1.0.

stop()

Останавливает менеджер, отвязывается от объектов и освобождает все выделенные ресурсы.

Добавлено в версии 2.1.0.

type_ids = None

Переопределите этот атрибут, чтобы объявить идентификаторы типов событий, которые менеджер хочет получать. Этот атрибут будет использоваться WindowBase для определения, какие события передавать в метод dispatch().

Добавлено в версии 2.1.0.

window = None

Содержит экземпляр класса WindowBase.

Добавлено в версии 2.1.0.

kivy.eventmanager.MODE_DEFAULT_DISPATCH = 'default'

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

Добавлено в версии 2.1.0.

kivy.eventmanager.MODE_DONT_DISPATCH = 'none'

Назначьте этот режим, чтобы предотвратить передачу события дочерним виджетам.

Добавлено в версии 2.1.0.

kivy.eventmanager.MODE_FILTERED_DISPATCH = 'filtered'

Назначьте этот режим, чтобы событие передавалось только дочерним виджетам, которые были ранее зарегистрированы для получения событий того же типа type_id и не всем дочерним виджетам.

Добавлено в версии 2.1.0.

« Scroll effect

Garden »