虚拟键盘¶

在 1.0.8 版本加入.

VKeyboard 是 Kivy 的屏幕键盘。其操作旨在对用户透明。不建议直接使用该控件。请先阅读请求键盘部分。

模式¶

该虚拟键盘具有停靠和自由两种模式：

停靠模式（VKeyboard.docked = True）通常用于只有一个人使用计算机的情况，例如平板电脑或个人电脑等。
自由模式：（VKeyboard.docked = False）主要用于多点触控表面。此模式允许在屏幕上使用多个虚拟键盘。

如果停靠模式发生变化，您需要手动调用 VKeyboard.setup_mode()，否则该更改将不会生效。在此调用期间，基于 Scatter 实现的 VKeyboard 将改变散焦行为，并将键盘定位在目标附近（如果设置了目标和停靠模式）。

布局¶

虚拟键盘能够加载自定义布局。如果你创建了一个新布局，并将JSON文件放置在 <kivy_data_dir>/keyboards/<layoutid>.json 中，你可以通过将 VKeyboard.layout 设置为你的布局ID来加载它。

JSON 的结构必须如下所示：

{
    "title": "Title of your layout",
    "description": "Description of your layout",
    "cols": 15,
    "rows": 5,

    ...
}

然后，你需要描述每一行中的按键，无论是“普通”、“Shift”还是“特殊”（自1.9.0版本起新增）模式。这一行数据的按键必须命名为`normal_<row>`、shift_<row>`和`special_<row>。将`row`替换为行号。在每一行内部，你将描述按键。一个按键是一个包含4个元素的列表，格式如下:

[ <text displayed on the keyboard>, <text to put when the key is pressed>,
  <text that represents the keycode>, <size of cols> ]

以下是示例键：

# f key
["f", "f", "f", 1]
# capslock
["↹", "     ", "tab", 1.5]

最后，完成JSON:

{
    ...
    "normal_1": [
        ["`", "`", "`", 1],    ["1", "1", "1", 1],    ["2", "2", "2", 1],
        ["3", "3", "3", 1],    ["4", "4", "4", 1],    ["5", "5", "5", 1],
        ["6", "6", "6", 1],    ["7", "7", "7", 1],    ["8", "8", "8", 1],
        ["9", "9", "9", 1],    ["0", "0", "0", 1],    ["+", "+", "+", 1],
        ["=", "=", "=", 1],    ["⌫", null, "backspace", 2]
    ],

    "shift_1": [ ... ],
    "normal_2": [ ... ],
    "special_2": [ ... ],
    ...
}

请求键盘¶

虚拟键盘的实例化由配置控制。请参阅配置对象中的 keyboard_mode 和 keyboard_layout。

如果你打算创建一个需要键盘的控件，请不要直接使用虚拟键盘，而应优先采用平台上可用的最佳方法。请参阅窗口中的 request_keyboard() 方法。

如果你需要请求键盘时使用特定的布局，可以这样写（从1.8.0版本开始，numeric.json可以放在与你的main.py相同的目录下）:

keyboard = Window.request_keyboard(
    self._keyboard_close, self)
if keyboard.widget:
    vkeyboard = self._keyboard.widget
    vkeyboard.layout = 'numeric.json'

class kivy.uix.vkeyboard.VKeyboard(**kwargs)[源代码]¶

基类：Scatter

VKeyboard是一个支持多点触控的屏幕键盘。其布局完全可自定义，您可以通过控件右下角的按钮在可用布局之间切换。

事件:

on_key_down: keycode、internal、modifiers: 当键盘接收到按键按下事件（key press）时触发。
on_key_up: keycode, internal, modifiers: 当键盘接收到按键释放事件（key up event）时触发。

available_layouts¶

所有可用布局的字典。键为布局ID，值为JSON（已转换为Python对象）。

available_layouts 是一个 DictProperty，默认值为 {}。

background¶

背景图片的文件名。

background 是一个 StringProperty，默认值为 atlas://data/images/defaulttheme/vkeyboard_background。

background_border¶

背景图像边框。用于控制背景的 border 属性。

background_border 是一个 ListProperty，默认值为 [16, 16, 16, 16]。

background_color¶

背景颜色，格式为 (r, g, b, a)。如果设置了背景，该颜色将与背景纹理结合。

background_color 是一个 ColorProperty，默认值为 [1, 1, 1, 1]。

在 2.0.0 版本发生变更: 从 ListProperty 更改为 ColorProperty。

background_disabled¶

当虚拟键盘被禁用时背景图像的文件名。

在 1.8.0 版本加入.

background_disabled 是一个 StringProperty，默认值为 atlas://data/images/defaulttheme/vkeyboard__disabled_background。

callback¶

回调可以设置为一个函数，当用户关闭虚拟键盘（VKeyboard）时，该函数将被调用。

target 是一个 ObjectProperty 实例，默认值为 None。

collide_margin(x, y)[源代码]¶: 执行碰撞检测，如果坐标 (x, y) 位于虚拟键盘边距内，则返回 True。

docked¶

指示VKeyboard是否停靠在屏幕上。如果你更改此设置，必须手动调用:meth:setup_mode，否则不会产生任何影响。如果VKeyboard由Window创建，停靠模式将根据配置自动设置，使用`[kivy]`部分中的`keyboard_mode`标记。

docked 是一个 BooleanProperty，默认值为 False。

font_size¶

font_size，指定虚拟键盘按键上文本的大小。应将其保持在合理范围内，以确保文本不会超出按键边界，也不会因过小而难以阅读。

在 1.10.0 版本加入.

font_size 是一个 NumericProperty，默认值为 20。

key_background_color¶

按键背景颜色，格式为 (r, g, b, a)。如果设置了按键背景，该颜色将与按键背景纹理结合。

key_background_color 是一个 ColorProperty，默认值为 [1, 1, 1, 1]。

在 2.0.0 版本发生变更: 从 ListProperty 更改为 ColorProperty。

key_background_down¶

当小部件上有触摸活动时，用于背景图像的关键文件名。

key_background_down 是一个 StringProperty，默认值为 atlas://data/images/defaulttheme/vkeyboard_key_down。

key_background_normal¶

当小部件上没有触摸操作时，用于显示的关键背景图像文件名。

key_background_normal 是一个 StringProperty，默认值为 atlas://data/images/defaulttheme/vkeyboard_key_normal。

key_border¶

关键图像边框。用于控制键的 border 属性。

key_border 是一个 ListProperty，默认值为 [16, 16, 16, 16]。

key_disabled_background_normal¶

当部件上没有触摸操作且虚拟键盘被禁用时，用于显示的关键背景图像文件名。

在 1.8.0 版本加入.

key_disabled_background_normal 是一个 StringProperty，默认值为 atlas://data/images/defaulttheme/vkeyboard_disabled_key_normal。

key_margin¶

键边距，用于在按键之间创建空间。边距由四个值组成，单位为像素：

key_margin = [top, right, bottom, left]

key_margin 是一个 ListProperty，默认值为 [2, 2, 2, 2]。

layout¶

用于VKeyboard的布局。默认情况下，将使用配置中根据`[kivy]`部分的`keyboard_layout`设置的布局。

在 1.8.0 版本发生变更: 如果 layout 是一个 .json 文件名，它将被加载并添加到 available_layouts 中。

layout 是一个 StringProperty，默认值为 None。

layout_path¶

布局读取的路径。

layout 是一个 StringProperty，默认值为 <kivy_data_dir>/keyboards/。

margin_hint¶

边距提示，用作键盘背景与按键内容之间的间距。边距由四个介于0和1之间的值组成：

margin_hint = [top, right, bottom, left]

边距提示将根据其位置乘以宽度和高度。

margin_hint 是一个 ListProperty，默认值为 [.05, .06, .05, .06]。

on_touch_down(touch)[源代码]¶

接收触摸按下事件。

参数:

touch：MotionEvent 类: 收到触摸事件。该触摸位于父坐标中。关于坐标系统的讨论，请参阅 relativelayout。

返回:

bool 如果为 True，触摸事件的派发将停止。如果为 False，事件将继续派发给控件树中的其余部分。

on_touch_up(touch)[源代码]¶

接收触摸抬起事件。触摸坐标位于父级坐标系中。

更多信息请参阅 on_touch_down()。

refresh(force=False)[源代码]¶: （内部）根据所选布局重新创建整个控件及其图形。

setup_mode(*largs)[源代码]¶

当你需要根据选项重新调整键盘时，请调用此方法：是否停靠（docked），以及是否附加了目标（target）。

如果 docked 为 True，它将调用 setup_mode_dock()。
如果 docked 为 False，它将调用 setup_mode_free()。

请随意重载这些方法，以创建新的定位行为。

setup_mode_dock(*largs)[源代码]¶

将键盘设置为停靠模式。

停靠模式将重置旋转，禁用平移、旋转和缩放。缩放和位置将自动调整，以将键盘附着到屏幕底部。

备注

不要直接调用此方法，请改用 setup_mode()。

setup_mode_free()[源代码]¶

将键盘设置为自由模式。

自由模式旨在让用户控制键盘的位置和方向。其唯一实际用途是在多用户环境中，但您可能会发现其他使用方式。如果设置了 target，虚拟键盘将放置在目标下方。

备注

不要直接调用此方法，请改用 setup_mode()。

target¶

与VKeyboard关联的目标widget。如果设置了该属性，它将用于发送键盘事件。如果VKeyboard模式为“free”，它还将用于设置初始位置。

target 是一个 ObjectProperty 实例，默认值为 None。

« 视频播放器

Widget 类 »

Version

Quick search

目录

虚拟键盘¶

模式¶

布局¶

请求键盘¶