焦点行为¶

FocusBehavior mixin 类提供了键盘焦点行为。当与其他 FocusBehavior 控件结合使用时，可以通过按 Tab 键在它们之间循环焦点。此外，在获得焦点时，该实例将自动接收键盘输入。

焦点与选择截然不同，它与键盘紧密相连；每个键盘可以聚焦于零个或一个控件，而每个控件也只能拥有一个键盘的焦点。然而，多个键盘可以同时聚焦于不同的控件。当按下退出键时，拥有该键盘焦点的控件将失去焦点。

管理焦点¶

本质上，焦点机制是通过双向链表实现的，其中每个节点持有对前一个和后一个实例的（弱）引用，这在使用tab（向前）或shift+tab（向后）循环遍历节点时可见。如果未指定前一个或后一个部件，则 focus_next 和 focus_previous 默认为 None。这意味着会遍历 children 列表和 parents 来寻找下一个可聚焦的部件，除非 focus_next 或 focus_previous 被设置为 StopIteration 类，在这种情况下，焦点在此处停止。

例如，要在 GridLayout 的 Button 元素之间循环焦点，可以这样做:

class FocusButton(FocusBehavior, Button):
  pass

grid = GridLayout(cols=4)
for i in range(40):
    grid.add_widget(FocusButton(text=str(i)))
# clicking on a widget will activate focus, and tab can now be used
# to cycle through

在使用软件键盘时（常见于移动设备和触摸设备），键盘的显示行为由 softinput_mode 属性决定。您可以使用此属性来确保焦点控件不会被键盘遮挡或覆盖。

初始化焦点¶

控件在可见之前无法接收焦点。这意味着在它们可见之前将其 focus 属性设置为 True 将不会产生任何效果。要初始化焦点，您可以使用 'on_parent' 事件:

from kivy.app import App
from kivy.uix.textinput import TextInput

class MyTextInput(TextInput):
    def on_parent(self, widget, parent):
        self.focus = True

class SampleApp(App):
    def build(self):
        return MyTextInput()

SampleApp().run()

如果你正在使用 popup，你可以使用 'on_open' 事件。

关于行为的概述，请参阅 behaviors 文档。

警告

此代码仍处于实验阶段，其API在未来的版本中可能会有所变动。

class kivy.uix.behaviors.focus.FocusBehavior(**kwargs)[源代码]¶

基类：object

提供键盘焦点行为。当与其他FocusBehavior控件结合使用时，它允许通过按Tab键在它们之间循环焦点。更多信息请参阅：mod:焦点行为模块文档 <kivy.uix.behaviors.focus>。

在 1.9.0 版本加入.

focus¶

实例当前是否具有焦点。

将其设为True将绑定和/或请求键盘，输入将被转发到该实例。设为False将解除绑定和/或释放键盘。对于给定的键盘，只有一个控件可以拥有焦点，因此聚焦一个控件将自动取消另一个持有焦点的实例的焦点。

使用软件键盘时，请参考 softinput_mode 属性来确定键盘显示的处理方式。

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

focus_next¶

当按下 Tab 键且此实例具有焦点时，要获取焦点的 FocusBehavior 实例；如果为 None 或 StopIteration，则不执行此操作。

当按下 Tab 键时，焦点会在所有通过 focus_next 链接且可聚焦的 FocusBehavior 控件之间循环。如果 focus_next 为 None，则会遍历子控件列表以查找下一个可聚焦的控件。最后，如果 focus_next 是 StopIteration 类，焦点将不会向前移动，而是在此处结束。

focus_next 是一个 ObjectProperty，默认值为 None。

focus_previous¶

当在此实例上按下shift+tab时，要获取焦点的:class:`FocusBehavior`实例，如果为None或`StopIteration`则忽略。

当按下shift+tab时，焦点会循环遍历所有通过:attr:focus_previous`链接且可聚焦的:class:`FocusBehavior`控件。如果:attr:`focus_previous`为`None，则改为遍历子控件树以查找上一个可聚焦的控件。最后，如果:attr:`focus_previous`是`StopIteration`类，焦点将不会向后移动，而是在此处结束。

focus_previous 是一个 ObjectProperty，默认值为 None。

focused¶

focus 的别名。

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

警告

focused 是 focus 的别名，将在 2.0.0 版本中移除。

get_focus_next()[源代码]¶: 使用 focus_next 或 children 返回下一个可聚焦的控件，其顺序与使用 tab 键向前切换焦点时的顺序相同。

get_focus_previous()[源代码]¶: 返回上一个可聚焦的控件，使用 focus_previous 或 children，其顺序与同时按下 tab + shift 键时一致。

hide_keyboard()[源代码]¶: 在管理模式下隐藏键盘的便捷函数。

ignored_touch = []¶

不应被用于取消焦点的触摸列表。在`on_touch_up`之后，如果配置的键盘模式不是多模式，那么不在:attr:`ignored_touch`中的每个触摸都将使所有聚焦的控件失去焦点。用于聚焦的可聚焦控件上的触摸会自动添加到此列表中。

示例用法:

class Unfocusable(Widget):

    def on_touch_down(self, touch):
        if self.collide_point(*touch.pos):
            FocusBehavior.ignored_touch.append(touch)

请注意，你需要将其作为类来访问，而不是作为实例变量。

input_type¶

请求的输入键盘类型。

在 1.8.0 版本加入.

在 2.1.0 版本发生变更: 将默认值从 text 改为 null。在选项中添加了 null。

警告

由于默认值已更改，您可能需要调整代码中的 input_type。

input_type 是一个 OptionsProperty，默认值为 'null'。可选值包括 'null'、'text'、'number'、'url'、'mail'、'datetime'、'tel' 或 'address'。

is_focusable¶

实例是否可以获得焦点。如果已获得焦点，当设置为False时，它将失去焦点。

is_focusable 是一个 BooleanProperty，在桌面平台上默认为 True（即 config 中的 desktop 为 True），否则为 False。

keyboard¶

聚焦时绑定到（或已绑定到小部件的）键盘。

当为None时，每当控件获得或失去焦点时，会请求并释放键盘。如果不为None，则必须是一个键盘，该键盘会在控件获得或失去焦点时与其绑定和解绑。这仅在存在多个键盘时才有用，因此当只有一个键盘可用时，建议将其设置为None。

如果存在多个键盘，每当一个实例获得焦点时，若当前没有键盘（None），则会请求一个新的键盘。除非其他实例失去焦点（例如使用了Tab键），否则会出现一个新的键盘。当不希望出现这种情况时，可以使用`keyboard`属性。例如，如果有两个用户各持有一个键盘，则可以将每个键盘分配给`FocusBehavior`的不同实例组，确保在每个组内，只有一个`FocusBehavior`会获得焦点，并从正确的键盘接收输入。关于键盘模式的更多信息，请参阅:mod:~kivy.config`中的`keyboard_mode。

键盘与焦点行为

使用键盘时，有几个重要的默认行为需要您牢记。

当Config的`keyboard_mode`设置为multi时，每个新的触摸事件被视为不同用户的触摸，并会（如果点击了可聚焦元素）以新键盘设置焦点。已聚焦的元素不会失去焦点（即使触摸了不可聚焦的控件）。
如果设置了 keyboard 属性，那么当实例获得焦点时，将使用该键盘。如果具有不同键盘的控件通过 focus_next 和 focus_previous 链接，则在它们之间切换标签时，不同的键盘会变为活动状态。因此，通常不希望链接分配了不同键盘的实例。
当控件获得焦点时，将其键盘设置为None会移除其键盘，但该控件随后会立即尝试获取另一个键盘。要移除其键盘，应将其 focus 属性设置为False。
在使用软件键盘时（常见于移动设备和触摸设备），键盘的显示行为由 softinput_mode 属性决定。您可以使用此属性来确保焦点控件不被遮挡或隐藏。

keyboard 是一个 AliasProperty，默认值为 None。

keyboard_mode¶

决定键盘可见性应如何管理。'auto' 将导致在焦点上显示/隐藏的标准行为。'managed' 需要手动设置键盘可见性，或调用辅助函数 show_keyboard() 和 hide_keyboard()。

keyboard_mode 是一个 OptionsProperty，默认值为 'auto'。可选值为 'auto' 或 'managed'。

keyboard_on_key_down(window, keycode, text, modifiers)[源代码]¶

当实例获得焦点时，绑定到键盘的方法。

当实例获得焦点时，此方法会绑定到键盘，并在每次按键输入时被调用。其参数与 kivy.core.window.WindowBase.on_key_down() 相同。

在派生控件中重写该方法时，应调用super以启用Tab键循环。如果派生控件希望将Tab键用于自身目的，则可以在处理字符后调用super（如果它不希望消耗Tab键）。

与其他键盘函数类似，如果按键已被消费，则应返回True。

keyboard_on_key_up(window, keycode)[源代码]¶

当实例获得焦点时，绑定到键盘的方法。

当实例获得焦点时，此方法会绑定到键盘，并在每次输入释放时被调用。其参数与 kivy.core.window.WindowBase.on_key_up() 相同。

在派生组件中重写该方法时，应调用super以支持按Escape键取消焦点。若派生组件希望将Escape用于自身用途，可在处理完该字符后调用super（若其不希望消耗Escape键）。

参见 keyboard_on_key_down()。

keyboard_suggestions¶

如果为 True，则在键盘上方提供自动建议。这仅在 input_type 设置为 text、url、mail 或 address 时有效。

警告

在Android上，keyboard_suggestions 依赖于 InputType.TYPE_TEXT_FLAG_NO_SUGGESTIONS 来生效，但有些键盘会忽略这个标志。如果你希望在Android上完全禁用建议，可以将 input_type 设置为 null，这将请求输入法以受限的“生成按键事件”模式运行。

在 2.1.0 版本加入.

keyboard_suggestions 是一个 BooleanProperty，默认值为 True。

show_keyboard()[源代码]¶: 便捷函数，用于在管理模式中显示键盘。

unfocus_on_touch¶

实例在被点击外部时是否应失去焦点。

当用户点击一个具有焦点感知能力且与本控件共享同一键盘（在只有一个键盘的情况下）的控件时，随着其他控件获得焦点，本控件将失去焦点。此外，如果此属性为 True，点击除本控件之外的任何控件，都会使本控件失去焦点。

unfocus_on_touch 是一个 BooleanProperty，如果 Config 中的 keyboard_mode 为 'multi' 或 'systemandmulti'，则默认为 False，否则默认为 True。

« Emacs 行为

Kivy 命名空间 »

Version

Quick search

目录

焦点行为¶

管理焦点¶

初始化焦点¶