Pygame обрабатывает все сообщения об событиях через очередь событий. Функции в этом модуле помогают вам управлять этой очередью событий. Очередь ввода сильно зависит от модуля pygame.display. Если отображение не было инициализировано и режим видео не задан, очередь событий может работать неправильно.

Очередь событий имеет верхний предел на количество событий, которое она может содержать. Когда очередь становится полной, новые события тихо пропускаются. Чтобы предотвратить потерю событий, особенно событий ввода, которые сигнализируют о команде выхода, ваша программа должна обрабатывать события каждый кадр (с pygame.event.get(), pygame.event.pump(), pygame.event.wait(), pygame.event.peek() или pygame.event.clear()) и обрабатывать их. Необработка событий может привести к тому, что ваша система решит, что ваша программа зависла. Чтобы ускорить обработку очереди, используйте pygame.event.set_blocked() для ограничения того, какие события попадают в очередь.

Чтобы получить состояние различных устройств ввода, вы можете обойти очередь событий и получить доступ к устройствам ввода напрямую с помощью соответствующих модулей: pygame.mouse, pygame.key и pygame.joystick. Если вы используете этот метод, помните, что pygame требует определенной формы общения с диспетчером окон системы и другими частями платформы. Чтобы поддерживать pygame в синхронизации с системой, вам нужно будет вызвать pygame.event.pump(), чтобы всё было актуально. Обычно это должно вызываться один раз за цикл игры. Примечание: джойстики не будут отправлять какие-либо события, пока устройство не будет инициализировано.

Очередь событий содержит объекты событий pygame.event.Event. Существует множество способов доступа к событиям в очереди, от простой проверки существования событий до непосредственного извлечения их из стека. Очередь событий также предлагает некоторую простую фильтрацию, которая может немного улучшить производительность, блокируя определённые типы событий в очереди. Используйте pygame.event.set_allowed() и pygame.event.set_blocked() для изменения этой фильтрации. По умолчанию все типы событий могут помещаться в очередь.

Все экземпляры pygame.event.Event содержат идентификатор типа события и атрибуты, специфичные для этого типа события. Идентификатор типа события доступен как свойство pygame.event.Event.type. Любой из атрибутов, специфичных для события, можно получить через атрибут pygame.event.Event.__dict__ или непосредственно как атрибут объекта события (так как запросы к членам передаются значениям словаря объекта).

Объект события не имеет функций-методов. Пользователи могут создавать свои собственные новые события с помощью функции pygame.event.Event().

Идентификатор типа события находится в диапазоне значений от NOEVENT до NUMEVENTS. Пользовательские события должны иметь значение в закрытом диапазоне от USEREVENT до NUMEVENTS - 1. Пользовательские события могут получить уникальный номер события с помощью pygame.event.custom_type(). Рекомендуется, чтобы все пользовательские события следовали этой системе.

События поддерживают сравнения на равенство и неравенство. Два события равны, если они одного типа и имеют одинаковые значения атрибутов.

При отладке и экспериментировании вы можете распечатать объект события для быстрого отображения его типа и членов. Функция pygame.event.event_name() может быть использована для получения строки, представляющей имя типа события.

События, поступающие от системы, будут иметь гарантированный набор атрибутов членов, основанный на типе. Ниже приведён список типов событий с их специфическими атрибутами.

QUIT              none
ACTIVEEVENT       gain, state
KEYDOWN           key, mod, unicode, scancode
KEYUP             key, mod, unicode, scancode
MOUSEMOTION       pos, rel, buttons, touch
MOUSEBUTTONUP     pos, button, touch
MOUSEBUTTONDOWN   pos, button, touch
JOYAXISMOTION     joy (deprecated), instance_id, axis, value
JOYBALLMOTION     joy (deprecated), instance_id, ball, rel
JOYHATMOTION      joy (deprecated), instance_id, hat, value
JOYBUTTONUP       joy (deprecated), instance_id, button
JOYBUTTONDOWN     joy (deprecated), instance_id, button
VIDEORESIZE       size, w, h
VIDEOEXPOSE       none
USEREVENT         code

Обратите внимание, что ACTIVEEVENT, VIDEORESIZE и VIDEOEXPOSE считаются «устаревшими» событиями. Рекомендуется использовать API pygame2 WINDOWEVENT вместо использования этого более старого API.

Вы также можете найти список констант для клавиш клавиатуры здесь.

При компиляции с SDL2, pygame имеет эти дополнительные события и их атрибуты.

AUDIODEVICEADDED   which, iscapture (SDL backend >= 2.0.4)
AUDIODEVICEREMOVED which, iscapture (SDL backend >= 2.0.4)
FINGERMOTION       touch_id, finger_id, x, y, dx, dy
FINGERDOWN         touch_id, finger_id, x, y, dx, dy
FINGERUP           touch_id, finger_id, x, y, dx, dy
MOUSEWHEEL         which, flipped, x, y, touch, precise_x, precise_y
MULTIGESTURE       touch_id, x, y, pinched, rotated, num_fingers
TEXTEDITING        text, start, length
TEXTINPUT          text

Атрибут touch событий MOUSE указывает, были ли события сгенерированы устройством сенсорного ввода, а не реальной мышью. Возможно, вы захотите игнорировать такие события, если ваше приложение уже обрабатывает события FINGERMOTION, FINGERDOWN и FINGERUP.

В pygame 2 было введено много новых событий.

pygame может распознавать текст или файлы, перетащенные в его окно. Если файл перетащен, будет отправлено событие DROPFILE, а file будет его путём. Событие DROPTEXT поддерживается только на X11.

MIDIIN и MIDIOUT — события, зарезервированные для использования с pygame.midi.

pygame 2 также поддерживает подключаемые устройства управления.

Event name               Attributes and notes

DROPFILE                 file
DROPBEGIN                (SDL backend >= 2.0.5)
DROPCOMPLETE             (SDL backend >= 2.0.5)
DROPTEXT                 text (SDL backend >= 2.0.5)
MIDIIN
MIDIOUT
CONTROLLERDEVICEADDED    device_index
JOYDEVICEADDED           device_index
CONTROLLERDEVICEREMOVED  instance_id
JOYDEVICEREMOVED         instance_id
CONTROLLERDEVICEREMAPPED instance_id
KEYMAPCHANGED            (SDL backend >= 2.0.4)
CLIPBOARDUPDATE
RENDER_TARGETS_RESET     (SDL backend >= 2.0.2)
RENDER_DEVICE_RESET      (SDL backend >= 2.0.4)
LOCALECHANGED            (SDL backend >= 2.0.14)

Также в этой версии были добавлены атрибуты instance_id к событиям джойстика, а атрибут joy был устаревшим.

KEYMAPCHANGED — это тип события, отправляемого при изменении раскладки клавиатуры из-за системного события, такого как изменение языка ввода или раскладки клавиатуры.

CLIPBOARDUPDATE — это событие, отправляемое при изменении буфера обмена. Это всё ещё можно считать экспериментальной функцией, некоторые виды изменений в буфере обмена могут не вызывать это событие.

LOCALECHANGED — это событие, отправляемое при изменении региональных настроек пользователя.

С pygame 2.0.1 есть новый набор событий, называемые событиями окна. Вот список всех событий окна вместе с кратким описанием

Event type                Short description

WINDOWSHOWN            Window became shown
WINDOWHIDDEN           Window became hidden
WINDOWEXPOSED          Window got updated by some external event
WINDOWMOVED            Window got moved
WINDOWRESIZED          Window got resized
WINDOWSIZECHANGED      Window changed its size
WINDOWMINIMIZED        Window was minimized
WINDOWMAXIMIZED        Window was maximized
WINDOWRESTORED         Window was restored
WINDOWENTER            Mouse entered the window
WINDOWLEAVE            Mouse left the window
WINDOWFOCUSGAINED      Window gained focus
WINDOWFOCUSLOST        Window lost focus
WINDOWCLOSE            Window was closed
WINDOWTAKEFOCUS        Window was offered focus (SDL backend >= 2.0.5)
WINDOWHITTEST          Window has a special hit test (SDL backend >= 2.0.5)
WINDOWICCPROFCHANGED   Window ICC profile changed (SDL backend >= 2.0.18)
WINDOWDISPLAYCHANGED   Window moved on a new display (SDL backend >= 2.0.18)

WINDOWMOVED, WINDOWRESIZED и WINDOWSIZECHANGED имеют атрибуты x и y, а WINDOWDISPLAYCHANGED имеет атрибут display_index. Все события окна имеют атрибут window.

На Android могут генерироваться следующие события

Event type                 Short description

APP_TERMINATING           OS is terminating the application
APP_LOWMEMORY             OS is low on memory, try to free memory if possible
APP_WILLENTERBACKGROUND   Application is entering background
APP_DIDENTERBACKGROUND    Application entered background
APP_WILLENTERFOREGROUND   Application is entering foreground
APP_DIDENTERFOREGROUND    Application entered foreground

pygame.event.pump()

внутренняя обработка обработчиков событий pygame

pump() -> None

Для каждого кадра вашей игры вам нужно будет сделать вызов очереди событий. Это гарантирует, что ваша программа может взаимодействовать с остальной частью операционной системы. Если вы не используете другие функции событий в своей игре, вы должны вызвать pygame.event.pump(), чтобы позволить pygame обрабатывать внутренние действия.

Эта функция не нужна, если ваша программа постоянно обрабатывает события в очереди с помощью других функций pygame.event.

Существуют важные вещи, которые должны быть обработаны внутри очереди событий. Главное окно может потребоваться перерисовать или ответить на системный запрос. Если вы не делаете вызов очереди событий слишком долго, система может решить, что ваша программа зависла.

Внимание

Эта функция должна вызываться только в потоке, который инициализировал pygame.display.

pygame.event.get()

получить события из очереди

get(eventtype=None) -> Eventlist

get(eventtype=None, pump=True) -> Eventlist

get(eventtype=None, pump=True, exclude=None) -> Eventlist

Это получит все сообщения и удалит их из очереди. Если указан тип или последовательность типов, будут удалены и возвращены только эти сообщения из очереди.

Если в аргументе exclude передан тип или последовательность типов, тогда будут удалены только остальные сообщения из очереди. Если передан параметр exclude, параметр eventtype должен быть None.

Если вы берёте из очереди только определённые события, будьте внимательны, что очередь может в итоге заполниться событиями, которые вас не интересуют.

Если pump равно True (по умолчанию), то будет вызван pygame.event.pump().

Изменено в pygame 1.9.5: Добавлен аргумент pump

Изменено в pygame 2.0.2: Добавлен аргумент exclude

pygame.event.poll()

получить одно событие из очереди

poll() -> Event instance

Возвращает одно событие из очереди. Если очередь событий пуста, сразу же возвращается событие типа pygame.NOEVENT. Возвращённое событие удаляется из очереди.

Внимание

Эта функция должна вызываться только в потоке, который инициализировал pygame.display.

pygame.event.wait()

подождать одно событие из очереди

wait() -> Event instance

wait(timeout) -> Event instance

Возвращает одно событие из очереди. Если очередь пуста, функция будет ждать, пока не появится событие. Начиная с pygame 2.0.0, если передан аргумент timeout, функция вернёт событие типа pygame.NOEVENT, если в течение timeout миллисекунд в очередь не поступят события. Событие удаляется из очереди после того, как оно было возвращено. Пока программа ожидает, она будет находиться в режиме ожидания. Это важно для программ, которые хотят совместно использовать систему с другими приложениями.

Изменено в pygame 2.0.0.dev13: Добавлен аргумент timeout

Внимание

Эта функция должна вызываться только в потоке, который инициализировал pygame.display.

pygame.event.peek()

проверить, ждут ли события заданного типа в очереди

peek(eventtype=None) -> bool

peek(eventtype=None, pump=True) -> bool

Возвращает True, если в очереди есть какие-либо события заданного типа. Если передан список типов событий, это вернёт True, если в очереди есть любое из этих событий.

Если pump равно True (по умолчанию), то будет вызван pygame.event.pump().

Изменено в pygame 1.9.5: Добавлен аргумент pump

pygame.event.clear()

удалить все события из очереди

clear(eventtype=None) -> None

clear(eventtype=None, pump=True) -> None

Удаляет все события из очереди. Если передан аргумент eventtype, удаляются указанные события или последовательность событий. Это имеет тот же эффект, что и pygame.event.get(), за исключением того, что None не возвращается. Может быть немного эффективнее при очистке полной очереди событий.

Если pump равно True (по умолчанию), то будет вызван pygame.event.pump().

Изменено в pygame 1.9.5: Добавлен аргумент pump

pygame.event.event_name()

получить строку-имя из идентификатора события

event_name(type) -> string

Возвращает строку, представляющую имя (в стиле CapWords) данного типа события.

Для всех значений в диапазоне идентификаторов пользовательских событий возвращается "UserEvent". Если тип события не существует, возвращается "Unknown".

pygame.event.set_blocked()

управлять событиями, которые допускаются в очереди

set_blocked(type) -> None

set_blocked(typelist) -> None

set_blocked(None) -> None

Указанные типы событий не допускаются в очереди событий. По умолчанию все события могут быть помещены в очередь. Безопасно несколько раз отключать тип события.

Если в качестве аргумента передано None, все типы событий заблокированы от размещения в очереди.

pygame.event.set_allowed()

управлять событиями, которые допускаются в очереди

set_allowed(type) -> None

set_allowed(typelist) -> None

set_allowed(None) -> None

Указанные типы событий допускаются в очереди событий. По умолчанию все типы событий допускаются в очередь. Безопасно несколько раз разрешать тип события.

Если в качестве аргумента передано None, все типы событий разрешены для размещения в очереди.

pygame.event.get_blocked()

проверить, заблокирован ли тип события в очереди

get_blocked(type) -> bool

get_blocked(typelist) -> bool

Возвращает True, если указанный тип события заблокирован в очереди. Если передан список типов событий, функция вернёт True, если любой из этих типов событий заблокирован.

pygame.event.set_grab()

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

set_grab(bool) -> None

Когда ваша программа работает в оконном окружении, она будет совместно использовать устройства мыши и клавиатуры с другими приложениями, у которых фокус. Если ваша программа устанавливает захват событий в True, она заблокирует весь ввод для вашей программы.

Лучше не всегда захватывать ввод, так как это предотвращает выполнение пользователем других действий на системе.

pygame.event.get_grab()

проверить, захватываются ли события ввода для этой программы

get_grab() -> bool

Возвращает True, когда события ввода захвачены для этого приложения.

pygame.event.post()

поместить новое событие в очередь

post(Event) -> bool

Помещает указанное событие в конец очереди событий.

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

Возвращает булево значение о том, было ли событие помещено или нет. Заблокированные события не могут быть помещены, и эта функция возвращает False, если вы попытаетесь поместить их.

Изменено в pygame 2.0.1: возвращает булево значение, ранее возвращалось None

pygame.event.custom_type()

создать пользовательский тип события

custom_type() -> int

Зарезервировать pygame.USEREVENT для пользовательского использования.

Если создано слишком много событий, возникает pygame.error.

Добавлено в pygame 2.0.0.dev3.

pygame.event.Event

pygame объект для представления событий

Event(type, dict) -> Event

Event(type, **attributes) -> Event

Объект pygame, используемый для представления события. Event экземпляры поддерживают присваивание и удаление атрибутов.

При создании объекта атрибуты могут быть получены из аргумента словаря со строковыми ключами или из ключевых аргументов.

Примечание

С версии 2.1.3 EventType является алиасом для Event. Раньше Event была функцией, которая возвращала экземпляры EventType. Использование Event предпочтительнее EventType, поскольку последнее может быть устаревшим в будущей версии.

type

Идентификатор типа события.

type -> int

Только для чтения. Идентификатор типа события. Для созданных пользователем объектов событий это аргумент type, переданный pygame.event.Event().

Например, некоторые предопределенные идентификаторы событий — QUIT и MOUSEMOTION.

__dict__

Словарь атрибутов события

__dict__ -> dict

Только для чтения. Атрибуты, специфичные для типа события. Атрибут dict является синонимом для обратной совместимости.

Например, атрибуты события KEYDOWN будут unicode, key, и mod

Добавлено в pygame 1.9.2: Изменяемые атрибуты.