快捷实用按钮模块 xbutton 使用说明
阅读 17:05·字数 5127·发布
Youtube 频道
Bilibili 空间
关注 1800
关注 1800
快捷实用的 Pygame 按钮控件模块 xbutton，支持多状态/分配按键和手柄/导航选中操作视频演示 YouTube快捷实用的 Pygame 按钮控件模块 xbutton，支持多状态/分配按键和手柄/导航选中操作视频演示 Bilibili
引言
在使用 Pygame 开发游戏时，按钮是最常见的交互控件之一。xbutton是一个简单易用的按钮模块。通过他，你可以轻松实现按钮的多状态样式、事件绑定、键盘与手柄控制。
样式类 XStyle
XStyle对象用于定义一种外观，包括背景，字体等，可在创建XButton时使用。
XStyle(image=None, size=None, font=None, font_style=None, text_color=None, text_offset=None, scale=None)
- image 参数
image表示背景图像的Surface对象，或图像文件路径，或包含图像信息的IO对象。如果采用文件路径，那么不必担心会产生重复的Surface对象，XStyle会优先采用缓存。- size 参数
size表示控件的大小，如果忽略，则尝试根据背景图像的大小产生。- font 参数
font表示绘制文本所需的freetype.Font字体对象，或一个包含字体文件路径和字体大小的元组。如果忽略，则采用DEFAULT_FONT表示的字体对象。如果采用相同的字体文件路径和大小，那么不必担心会产生重复的Font对象，XStyle会优先采用缓存。- font_style 参数
font_style表示绘制文本时，所采用的字体样式，如果忽略，则采用freetype.STYLE_DEFAULT。- text_color 参数
text_color与Color类的构造器的rgbvalue参数相同，用于创建颜色对象，来绘制文本。如果忽略，则采用DEFAULT_COLOR表示的颜色对象。- text_offset 参数
text_offset表示文本的偏移距离，当背景图像展现偏移效果时，可设置该参数来调整文本的位置。- scale 参数
scale表示缩放大小（可能导致模糊），大于1为放大，小于1为缩小，将影响size属性。
XStyle会对字体与图片进行缓存，以提升性能。若需清除缓存，可调用该类的静态方法XStyle.clear_cache()。
创建控件组 XGroup
XGroup对象是一个控件组类，用处理多个控件的逻辑关系，使键盘或控制器可以切换控件的焦点，并实现对控件的某些操作。这里，你可以将控件理解为XButton。
XGroup(position, items, default_item=None, name=None, disabled=False, hidden=False, navigation_keys=None, navigation_hat=None, navigation_axes=None, joystick_id=None, onchange=None)
- position 参数
position表示组的左上角位置，将影响组中的所有控件，可传入一个包含 X 和 Y 坐标的元组或列表。- items 参数
items是一个嵌套序列，用于表示组中的控件布局。比如，[[b1,b2],[b3,b4]]，表示b1在b2的左边和b3的上边，b4在b3的右边和b2的下边，空位置可用None代替。- default_item 参数
default_item为组中的默认控件，默认控件在开始时拥有焦点。如果未指定，则第一个出现的控件为默认控件。- name 参数
name表示组的名称，可用于识别组。- disabled 参数
disabled表示组是否处于禁用状态。- hidden 参数
hidden表示组是否处于隐藏状态。- navigation_keys 参数
navigation_keys为包含用于切换控件焦点的键盘按键的元组（采用中文输入法时可能无效），形式为(up,down,left,right)。如果忽略，则采用(K_UP,K_DOWN,K_LEFT,K_RIGHT)。- navigation_hat 参数
navigation_hat为用于切换控件焦点的控制器方向键 ID。如果忽略，则为0。- navigation_axes 参数
navigation_axes为用于切换控件焦点的控制器轴装置信息。如果忽略，则为((1,0.3),(0,0.3))，其中0.3为触发操作的阈值，1为触发上下操作的轴装置 ID，0为触发左右操作的轴装置 ID。- joystick_id 参数
joystick_id为可以对组进行操作的控制器的 ID（控制器必须在模块定义的joysticks变量中）。如果忽略，则joysticks变量中的所有控制器均可操作组。- onchange 参数
onchange是一个函数，用于处理焦点控件发生变化的事件，形式为handle(**args)或handle(group, focused, blurred)，其中，group为控件组自身，focused为获得焦点的控件，blurred为失去焦点的控件。
在下面的示例中，我们创建了三个按钮b_start，b_enable，b_hide。在逻辑关系上，他们按照顺序从上至下排列，默认拥有焦点的按钮是b_enable。
# 定义样式并创建按钮
g_style = {
"default_style": XStyle(
image=r'g-normal.png',
font=(r'Bitty.ttf', 50),
text_color='#2c360c'
),
"hovered_style": XStyle(
image=r'g-hovered.png',
text_color='#4a5914',
scale=1.05
),
"pressed_style": XStyle(
image=r'g-clicked.png',
text_offset=(0, 1)
),
"disabled_style": XStyle(
image=r'g-disabled.png',
text_color='#505050',
scale=0.95,
font_style=freetype.STYLE_UNDERLINE
),
"focused_style": XStyle(
image=r'g-hovered.png',
font=(r'Bitty.ttf', 55),
text_color='#181c0b',
scale=1.05
)
}
b_start = XButton((0, 200), **g_style, text='Start', disabled=True)
b_enable = XButton((0, 300), **g_style, text='Enable', name='e')
b_hide = XButton((0, 400), **g_style, text='Hide', name='h')
g = XGroup(
(400, 0),
[
[b_start],
[b_enable],
[b_hide]
],
b_enable
)更新与绘制 XGroup 控件组
XGroup对象的update方法，用于更新控件组和组中所有控件的状态，需要在游戏循环中调用，最好放在draw方法之前。
update(pressed_keys)
- pressed_keys 参数
pressed_keys参数是键盘按键的按下状态（通常是key.get_pressed()的返回值）。如果忽略该参数，那么update方法将自行处理。
XGroup对象的draw方法，用于将控件组中的控件绘制到指定Surface对象，需要在游戏循环中调用，最好放在update方法之后。
draw(surface)
- surface 参数
surface参数是将被绘制控件的Surface对象。
js: list[joystick.JoystickType] = []
# NOTE 只有包含在 joysticks 中的控制器，才能操作按钮和控件组
xbutton.joysticks = js
running = True
while running:
# 在控制器连接和中断连接时，更新 js
for e in event.get():
if e.type == QUIT:
running = False
elif e.type == JOYDEVICEADDED:
j = joystick.Joystick(e.device_index)
js.append(j)
elif e.type == JOYDEVICEREMOVED:
for j in js:
if j.get_instance_id() == e.instance_id:
js.remove(j)
break
w.fill(0)
g.update(key.get_pressed())
g.draw(w)
# …绑定处理 XGroup 控件组事件
目前XGroup对象仅支持焦点控件发生变化的事件，可通过构造器的onchange参数设置处理事件的函数，具体可查看创建控件组一段。
在创建XGroup对象之后，你还可以通过该对象的onchange变量，来重新设置焦点控件发生变化的事件的处理函数。
在下面的示例中，将显示获得焦点以及失去焦点的按钮的文本。
# 焦点控件发生变化的事件的处理函数
def group_onchange(group, focused, blurred):
if focused:
print(f'Focus {focused.text}')
if blurred:
print(f'Blur {blurred.text}')
g = XGroup(
(400, 0),
[
[b_start],
[b_enable],
[b_hide]
],
b_enable,
onchange=group_onchange
)获取和设置 XGroup 控件组的其他特性
此外，XGroup还拥有以下的特性，可用于获取或设置控件组的某些状态。
- name 变量
name变量是组的名称，可用于识别组。- position 变量
position变量是组的左上角位置，可以是元组和列表（形式为(x, y)或[x, y]），或Vector2对象，该位置将影响组中的所有控件。- disabled 属性
disabled属性表示组是否处于禁用状态。- hidden 属性
hidden属性表示组是否处于隐藏状态。- joystick_id 属性
joystick_id属性用于指定可对组进行操作的控制器的 ID（控制器必须在模块定义的joysticks变量中）。如果为None，则joysticks变量中的所有控制器均可操作组。- current 属性
current属性表示当前具有焦点的控件。
源码
讲解视频
快捷实用的 Pygame 按钮控件模块 xbutton，支持多状态/分配按键和手柄/导航选中操作·YouTube快捷实用的 Pygame 按钮控件模块 xbutton，支持多状态/分配按键和手柄/导航选中操作·Bilibili