如何捕获处理游戏事件？以及创建和引发自定义事件等问题

Pygame 中的 event 模块

在 Pygame 中，事件消息是通过一个事件队列来传递的，该事件队列依赖于display模块，如果display模块没有初始化，那么事件队列可能无法正常工作。

如果事件队列所拥有的事件的数量达到了最大，那么新的事件将被丢弃，并且不会发出任何通知。为了防止这种情况发生，你应该及时的对事件进行处理，以减少队列中的事件，比如，在游戏循环中取出事件队列中的所有事件。

Pygame 的event模块，可用于捕获处理游戏中的各种事件，当然，这需要通过操作事件队列来完成。

Pygame 中的事件类型

pygame模块使用一系列的整数变量来表示不同的事件类型，这些变量可以在判断事件类型，以及调用与事件相关的函数时使用。当然，存在一些特殊的事件类型，用于表达某些特殊含义，以下为他们的说明。

QUIT 变量

QUIT变量表示游戏程序请求退出，比如，点击了窗口的关闭按钮。

NOEVENT 变量

NOEVENT变量表示没有事件，任何其他事件类型对应的整数应大于NOEVENT变量。

NUMEVENTS 变量

NUMEVENTS变量表示事件类型所对应的整数的上限，任何其他事件类型对应的整数应小于NUMEVENTS变量。

USEREVENT 变量

USEREVENT变量用于界定自定义事件的开始，任何自定义事件对应的整数应该大于USEREVENT变量。当然，你可以使用custom_type函数来生成自定义事件对应的整数，具体请查看生成自定义事件类型一段。

以下是与 Windows 系统事件有关的变量。所有 Windows 事件所对应的Event对象均拥有名称为window的变量。

WINDOWSHOWN 变量

WINDOWSHOWN变量表示游戏窗口已经显示。

WINDOWHIDDEN 变量

WINDOWHIDDEN变量表示游戏窗口已经隐藏。

WINDOWEXPOSED 变量

WINDOWEXPOSED变量表示游戏窗口被外部事件更新。

WINDOWMOVED 变量

WINDOWMOVED变量表示游戏窗口已经被移动。表示该事件的Event对象拥有表示窗口左上角坐标的变量x和y，其中x为 X 坐标，y为 Y 坐标。

WINDOWRESIZED 变量

WINDOWRESIZED变量表示游戏窗口被调正了大小。表示该事件的Event对象拥有表示窗口大小的变量x和y，其中x为宽度，y为高度。

WINDOWSIZECHANGED 变量

WINDOWSIZECHANGED变量表示游戏窗口大小发生了改变。表示该事件的Event对象拥有表示窗口大小的变量x和y，其中x为宽度，y为高度。

WINDOWMINIMIZED 变量

WINDOWMINIMIZED变量表示游戏窗口已经最小化。

WINDOWMAXIMIZED 变量

WINDOWMAXIMIZED变量表示游戏窗口已经最大化。

WINDOWRESTORED 变量

WINDOWRESTORED变量表示游戏窗口已经被还原。

WINDOWENTER 变量

WINDOWENTER变量表示鼠标已经进入了游戏窗口。

WINDOWLEAVE 变量

WINDOWLEAVE变量表示鼠标已经离开了游戏窗口。

WINDOWFOCUSGAINED 变量

WINDOWFOCUSGAINED变量表示游戏窗口已经获得了焦点。

WINDOWFOCUSLOST 变量

WINDOWFOCUSLOST变量表示游戏窗口已经失去了焦点。

WINDOWCLOSE 变量

WINDOWCLOSE变量表示游戏窗口已经关闭。

WINDOWTAKEFOCUS 变量

WINDOWTAKEFOCUS变量表示游戏窗口被给予了焦点（需要 SDL 版本为 2.0.5 或以上）。

WINDOWHITTEST 变量

WINDOWHITTEST变量表示游戏窗口有一个特殊的命中测试（需要 SDL 版本为 2.0.5 或以上）。

WINDOWICCPROFCHANGED 变量

WINDOWICCPROFCHANGED变量表示游戏窗口的 ICC 配置文件已更改（需要 SDL 版本为 2.0.18 或以上）。

WINDOWDISPLAYCHANGED 变量

WINDOWDISPLAYCHANGED变量表示游戏窗口被移动到了一个新的屏幕中（需要 SDL 版本为 2.0.18 或以上），表示该事件的Event对象拥有一个整数变量display_index，他表示了窗口目前所在的屏幕的索引（主屏幕的索引为0，其他屏幕的索引依次递增）。

以下是与 Android 系统事件有关的变量。

APP_TERMINATING 变量

APP_TERMINATING变量表示游戏正在被系统关闭。

APP_LOWMEMORY 变量

APP_LOWMEMORY变量表示系统内存不足，需要尽可能的释放内存。

APP_WILLENTERBACKGROUND 变量

APP_WILLENTERBACKGROUND变量表示游戏正在进入后台。

APP_DIDENTERBACKGROUND 变量

APP_DIDENTERBACKGROUND变量表示游戏已经进入后台。

APP_WILLENTERFOREGROUND 变量

APP_WILLENTERFOREGROUND变量表示游戏正在进入前台。

APP_DIDENTERFOREGROUND 变量

APP_DIDENTERFOREGROUND变量表示游戏已经进入前台。

以下是与音频设备有关的变量。所有音频设备事件所对应的Event对象均拥有名称为which和iscapture的变量，其中，which是表示音频设备索引的整数。

AUDIODEVICEADDED 变量

AUDIODEVICEADDED变量表示音频设备被添加（需要 SDL 版本为 2.0.4 或以上），如果在游戏启动前音频设备已经存在，那么该事件会在游戏启动时引发。

AUDIODEVICEREMOVED 变量

AUDIODEVICEREMOVED变量表示音频设备被移除（需要 SDL 版本为 2.0.4 或以上）。

以下是与拖放事件有关的变量。

DROPFILE 变量

DROPFILE变量表示拖放文件。

DROPTEXT 变量

DROPTEXT变量表示拖放文本。如果不支持对文本进行拖放，那么该事件不会引发。

DROPBEGIN 变量

DROPBEGIN变量表示拖放开始。

DROPCOMPLETE 变量

DROPCOMPLETE变量表示拖放完成。

以下是与某些不常使用事件相关的变量。

RENDER_TARGETS_RESET 变量

RENDER_TARGETS_RESET变量表示渲染目标重置（需要 SDL 版本为 2.0.2 或以上）。

RENDER_DEVICE_RESET 变量

RENDER_DEVICE_RESET变量表示渲染设备重置（需要 SDL 版本为 2.0.4 或以上）。

LOCALECHANGED 变量

LOCALECHANGED变量表示区域发生了变化（需要 SDL 版本为 2.0.14 或以上）。

至于其他的事件类型，及他们相关的变量，请查看内容分类一段列出的章节，或其他具体章节。

让 Pygame 自行处理事件队列中的事件

event模块的pump函数，可以让 Pygame 自行处理事件，处理不会导致事件队列中的事件被移除。

pump()

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


count = 0


while True:
	# 让 Pygame 自动处理事件
	event.pump()


	# 不断加 1，使窗口显示一段时间
	count += 1
	if count == 10000000:
		# 跳出循环会使程序结束，窗口也将关闭
		break

获取事件队列中的事件

如何在 Pygame 中捕获、过滤、处理事件

视频演示 YouTube

如何在 Pygame 中捕获、过滤、处理事件

视频演示 Bilibili

event模块的get函数，可用于获取事件队列中的事件，并将这些事件从事件队列中移除。

get(eventtype=None, pump=True, exclude=None)

eventtype 参数

eventtype参数用于指定需要获取的事件的类型，他可以是某个事件类型对应的整数，或一个包含事件类型对应整数的 Python 序列对象。如果该参数为空值None，则表示将获取任何类型的事件。

pump 参数

如果pump参数为True，那么get函数将调用pump方法。

exclude 参数

exclude参数用于指定需要排除的事件的类型，他可以是某个事件类型对应的整数，或一个包含事件类型对应整数的 Python 序列对象。如果你为该参数赋予了有效的值，那么get参数将返回事件队列中所有未被排除的事件。

返回值

get函数的返回值是一个包含Event对象的 Python 列表。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出，窗口移动，窗口最大化的变量
from pygame import QUIT, WINDOWMOVED, WINDOWMAXIMIZED
running = True


while running:
	# 获取队列中的退出，窗口移动事件
	for e in event.get((QUIT, WINDOWMOVED)):
		# 根据事件的类型进行不同的处理
		if e.type == QUIT:
			# 结束游戏循环
			running = False
			print(f'请求退出游戏')
		elif e.type == WINDOWMOVED:
			print(f'窗口位置：{e.x} {e.y}')


	# 获取队列中的其他事件，除了窗口最大化
	es = event.get(exclude=WINDOWMAXIMIZED)
	print(es)

event模块的poll函数，可用于获取事件队列中的一个事件，并将该事件从事件队列中移除。

poll()

返回值

poll函数的返回值是表示事件的Event对象。如果事件队列中没有任何事件，则poll函数将返回一个事件类型为NOEVENT的Event对象。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出和没有事件的变量
from pygame import QUIT, NOEVENT
running = True


while running:
	# 使用循环取出队列中的所有事件
	while True:
		e = event.poll()


		# 根据事件的类型进行不同的处理
		if e.type == QUIT:
			print('QUIT')
			# 结束游戏循环
			running = False
			break
		elif e.type == NOEVENT:
			# 队列中已经没有事件进入下一个游戏循环
			print('NOEVENT')
			break

与poll函数类似，event模块的wait函数，同样用于获取事件队列中的一个事件，并将该事件从事件队列中移除。但不同的是，如果事件队列中没有事件，wait函数会等待，在事件队列中出现一个新的事件后，将返回该事件。

wait(timeout=0)

timeout 参数

timeout参数是表示超时时间的整数（以毫秒为单位）。如果将该参数忽略或设置为0，那么在事件队列没有事件时，可以一直等待。

返回值

wait函数的返回值是表示事件的Event对象。如果等待时间超时，那么wait函数将返回一个事件类型为NOEVENT的Event对象。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示没有事件的变量
from pygame import NOEVENT


while True:
	# 获取队列中的所有事件
	event.get()
	# 等待一个新的事件，超时时间为 5 秒
	e = event.wait(5000)


	# 如果队列中没有事件，则退出
	if e.type == NOEVENT:
		break

判断事件队列中是否包含某种类型的事件

event模块的peek函数，可用于判断事件队列中是否包含某种类型的事件。

peek(eventtype=None, pump=True)

eventtype 参数

如果eventtype参数是一个整数，则判断该整数所对应的事件类型是否存在于事件队列中，如果eventtype参数一个 Python 整数序列对象，则判断这些整数所对应的事件类型中的任意一个是否存在于事件队列中。

pump 参数

如果pump参数为True，那么peek函数将调用pump方法。

返回值

如果peek函数的返回值为True，那么表示成功在事件队列中找到了指定类型的事件。如果eventtype参数为空值None，那么peek返回事件队列中的第一个事件（第一个Event对象）。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出，鼠标进入，鼠标离开的变量
from pygame import QUIT, WINDOWENTER, WINDOWLEAVE
running = True


while running:
	# 判断事件鼠标进入窗口或鼠标离开窗口是否存在
	if event.peek([WINDOWENTER, WINDOWLEAVE]):
		print('鼠标进入或鼠标离开')


	# 判断退出事件是否存在
	if event.peek(QUIT):
		running = False


	# 获取并显示所有的事件
	es = event.get()
	if len(es):
		print(es)

清除事件队列中的事件

event模块的clear函数，可用于清除事件队列中的事件，该效果类似于get函数对事件的移除，只不过clear函数不会返回列表，因此，他可能会比get函数快一些。

clear(eventtype=None, pump=True)

eventtype 参数

eventtype参数用于指定需要清除的事件的类型，他可以是某个事件类型对应的整数，或一个包含事件类型对应整数的 Python 序列对象。如果该参数为空值None，则表示将清除任何类型的事件。

pump 参数

如果pump参数为True，那么clear函数将调用pump方法。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出的变量
from pygame import QUIT


while True:
	# 如果存在退出事件，则结束游戏循环
	es = event.get(QUIT)
	if len(es):
		break


	# 清除队列中剩余的事件
	event.clear()

阻止某种事件类型

如果你不希望某些类型的事件出现在事件队列中，那么可以使用event模块的set_blocked函数，将指定的事件类型排除。这意味着，当某种事件类型被排除时，即便操作系统发送了该类型的事件，Pygame 也不会将其放入事件队列中。

set_blocked(type)

type 参数

type参数用于指定需要阻止的事件类型，他可以是某个事件类型对应的整数，或一个包含事件类型对应整数的 Python 序列对象。如果该参数为空值None，则表示阻止所有的事件类型。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出，鼠标进入的变量
from pygame import QUIT, WINDOWENTER
# 阻止鼠标进入事件
event.set_blocked(WINDOWENTER)


while True:
	# 检查队列中是否出现了鼠标进入事件
	if event.peek(WINDOWENTER):
		print('居然存在鼠标进入？！')


	# 一次取出一个事件，并判断是否需要退出循环
	if event.poll().type == QUIT:
		break

判断事件类型是否被阻止

event模块的get_blocked函数，可用于判断指定的事件类型是否已经被阻止。

get_blocked(type)

type 参数

如果type参数是一个整数，则判断该整数所对应的事件类型是否被阻止，如果eventtype参数一个 Python 整数序列对象，则判断这些整数所对应的事件类型中的任意一个是否被阻止。

返回值

如果get_blocked函数的返回值为True，那么表示指定的事件类型（或其中的一个）已经被阻止。

取消阻止某种事件类型

如果某种事件类型被阻止，那么你可以使用event模块的set_allowed函数，来取消阻止该事件类型。

set_allowed(type)

type 参数

type参数用于指定取消阻止的事件类型，他可以是某个事件类型对应的整数，或一个包含事件类型对应整数的 Python 序列对象。如果该参数为空值None，则表示取消阻止所有的事件类型。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 导入表示退出，窗口关闭，鼠标进入的变量
from pygame import QUIT, WINDOWCLOSE, WINDOWENTER
running = True


# 阻止退出和窗口关闭事件
event.set_blocked([QUIT, WINDOWCLOSE])


while running:
	for e in event.get():
		# 当鼠标进入窗口并且退出事件被阻止时，解除对退出和窗口关闭事件的阻止
		if e.type == WINDOWENTER and event.get_blocked(QUIT):
			event.set_allowed((QUIT, WINDOWCLOSE))


		# 根据事件的类型进行不同的处理
		if e.type == WINDOWCLOSE:
			print('窗口关闭')
		elif e.type == QUIT:
			print('退出')
			running = False

获取和设置是否共享输入设备

event模块的set_grab函数，可用于在 Windows 中设置 Pygame 是否与其他程序共享输入设备。

set_grab(grab)

grab 参数

如果grab参数为False，那么 Pygame 共享输入设备，否则不共享输入设备。

event模块的get_grab函数，可用于获取 Pygame 是否与其他程序共享输入设备。

get_grab()

返回值

如果get_grab函数的返回值为False，则表示 Pygame 共享输入设备，否则表示不共享输入设备。

event模块的set_keyboard_grab函数，可用于在 Windows 中设置 Pygame 是否与其他程序共享键盘输入。

set_keyboard_grab(grab)

grab 参数

如果grab参数为False，那么 Pygame 共享键盘输入，否则不共享键盘输入。

event模块的get_keyboard_grab函数，可用于获取 Pygame 是否与其他程序共享输入设备。

get_grab()

返回值

如果get_grab函数的返回值为False，则 Pygame 共享键盘输入，否则表示不共享键盘输入。

# 导入模块 display 和 event，并创建游戏窗口
from pygame import display, event
w = display.set_mode([800, 600])


# 独占输入设备
event.set_grab(True)
# 独占键盘输入，但 Alt+F4 快捷键依然有效
event.set_keyboard_grab(True)
print(f'独占输入设备？{event.get_grab()}')
print(f'独占键盘输入？{event.get_keyboard_grab()}')


# 在游戏循环中等待结束请求
from pygame import QUIT
running = True
while running:
	for e in event.get():
		if e.type == QUIT:
			running = False

获取事件的名称

event模块的event_name函数，可用于获取事件类型对应的事件名称。

event_name(type)

type 参数

type参数是一个表示事件类型的整数。

返回值

event_name函数返回表示事件名称的字符串（请注意字母的大小写问题）。如果是自定义事件，则统一返回'UserEvent'，如果是事件的类型未知，则统一返回'Unknown'。

# 导入模块 event 和一些与事件相关的变量
from pygame import event, NOEVENT, USEREVENT


# 获取与系统相关的事件的名称
for i in range(NOEVENT + 1, USEREVENT):
	name = event.event_name(i)


	# 不显示未知事件
	if name != 'Unknown':
		print(name)

创建自定义事件

如果你希望创建自定义事件，那么可以使用event模块的Event类（别名为EventType）。事实上，Event类即可表示由操作系统引发的事件，也可表示由开发人员引发的自定义事件。

Event(type, dict, **kwargs)

type 参数

type参数是表示事件类型的整数，对于自定义事件，可通过函数custom_type来产生新的自定义事件类型，具体请查看生成自定义事件类型一段。

dict 参数

dict参数是一个包含事件特性的 Python 字典，其键值对的键是表示特性名称的字符串，键值对的值是特性的值。

kwargs 参数

可变参数kwargs所包含的关键字参数，同样用于设置事件的特性，参数的名称为特性的名称，参数的值为特性的值。

如果kwargs参数与dict参数设置了相同的特性，则以kwargs为准。

Event对象的只读变量type，是表示事件类型的整数，其值与构造器的type参数相同。

event.type

与其他 Python 对象类似，你可以通过.运算符来访问Event对象的特性，这些特性通常是通过Event对象构造器的dict与kwargs参数创建的。而Event对象的只读变量dict，是一个包含了事件特性的字典，他提供了另外一种访问事件特性的方式，其键值对的键是表示特性名称的字符串，键值对的值是特性的值。

event.dict

# 导入模块 event 和一些与事件相关的变量
from pygame import event, QUIT, USEREVENT


# 创建系统事件对象
e1 = event.Event(QUIT)
print(e1)


# 创建自定义事件对象，其 id 为 2
e2 = event.Event(USEREVENT + 100, {'id': 1, 'message': '这是自定义事件！'}, id=2)
print(e2)

<Event(256-Quit {})>
<Event(32966-UserEvent {'id': 2, 'message': '这是自定义事件！'})>

生成自定义事件类型

event模块的custom_type函数，可用于生成一个新的整数，用于表示自定义事件的类型，而每一次调用custom_type所得到整数均不同。

custom_type()

返回值

custom_type函数返回一个新的整数，用于表示自定义事件的类型。

# 导入模块 event
from pygame import event


# 创建两个自定义事件
e1 = event.Event(event.custom_type())
print(e1.type)
e2 = event.Event(event.custom_type())
print(e2.type)

32867
32868

判断两个事件是否相等

对于两个Event对象，你可以通过==或!=来判断他们是否相等或不相等，当他们的事件类型以及dict变量对应的字典相等时，则认为两个事件对象相等，否则认为不相等。

# 导入模块 event，USEREVENT
from pygame import event, USEREVENT


# 创建一些事件对象
e1 = event.Event(USEREVENT + 1)
e2 = event.Event(USEREVENT + 1, message='一个自定义事件')
e3 = event.Event(USEREVENT + 1, {'message': '一个自定义事件'})
e4 = event.Event(USEREVENT + 2, {'message': '一个自定义事件'})
e5 = event.Event(USEREVENT + 2, {'message': '一个自定义事件'}, id=1)


# 判断他们是否相等
print(f'e1 == e2？{e1 == e2}')
print(f'e2 == e3？{e2 == e3}')
print(f'e3 == e4？{e3 == e4}')
print(f'e4 == e5？{e4 == e5}')

e1 == e2？False
e2 == e3？True
e3 == e4？False
e4 == e5？False

引发事件

event模块的post函数可将一个事件添加至事件队列，这类似于引发了新的事件，你可以通过get之类的函数来获取被添加的事件。通常情况下，调用post是为了添加自定义事件。

post(event)

event 参数

event参数是被添加的Event事件对象。

返回值

如果post函数返回True，表示事件被成功添加至事件队列末尾，否则表示未能成功添加。

# 导入相关内容，并创建游戏窗口
from pygame import display, event, QUIT, WINDOWLEAVE, MOUSEBUTTONDOWN
w = display.set_mode([800, 600])


# 阻止退出事件
event.set_blocked(QUIT)


running = True
while running:
	for e in event.get():
		if e.type == WINDOWLEAVE:
			# 当鼠标离开窗口时，取消阻止退出事件
			event.set_allowed(QUIT)
		elif e.type == MOUSEBUTTONDOWN:
			# 按下鼠标时，引发退出事件
			event.post(event.Event(QUIT))
		elif e.type == QUIT:
			# 结束游戏循环
			running = False

内容分类

源码

src/zh/event·codebeatme/pygame·GitHub

讲解视频

如何在 Pygame 中捕获、过滤、处理事件·YouTube如何在 Pygame 中捕获、过滤、处理事件·Bilibili