Widget 类¶

: Widget 类是创建 Widget 所需的基础类。这个 widget 类在设计时遵循了几个原则：

事件驱动

控件交互建立在发生的事件之上。如果某个属性发生变化，控件可以在 on_<propname> 回调中响应这一变化。如果没有变化，则不会执行任何操作。这正是 Property 类的主要目标。
关注点分离（控件及其图形表示）

Widget 没有 draw() 方法。这是有意为之：其目的是允许你在 Widget 类之外创建自己的图形表示。显然，你仍然可以使用所有可用的属性来实现这一点，从而使你的表示正确反映 Widget 的当前状态。每个 Widget 都有自己的 Canvas，你可以用它来绘制。这种分离使得 Kivy 能够以非常高效的方式运行你的应用程序。
边界框 / 碰撞

通常，您需要判断某个点是否位于控件的边界内。例如，对于一个按钮控件，您可能希望仅在按钮本身被实际触摸时触发操作。为此，您可以使用 collide_point() 方法，该方法会返回 True，如果传入的点位于由控件的位置和大小定义的轴对齐边界框内。如果简单的轴对齐边界框（AABB）不足以满足需求，您可以重写该方法，以使用更复杂的形状（如多边形）进行碰撞检测。此外，您还可以使用 collide_widget() 方法来检查一个控件是否与另一个控件发生碰撞。

我们还有一些默认值和行为，您应当了解：

一个 Widget 并不是一个 Layout：它不会改变其子组件的位置或大小。如果您需要控制定位或尺寸，请使用 Layout。
Widget 的默认尺寸是 (100, 100)。只有在父级是 Layout 时，这个尺寸才会被改变。例如，如果你将一个 Label 添加到 Button 内部，该标签不会继承按钮的尺寸或位置，因为按钮并不是一个布局：它只是另一个 Widget。
默认的 size_hint 为 (1, 1)。如果父级是 Layout，则控件的大小将等于父布局的大小。
on_touch_down()、on_touch_move()、on_touch_up() 不执行任何类型的碰撞检测。如果您想知道触摸是否位于您的控件内部，请使用 collide_point()。

使用属性¶

当你阅读文档时，所有属性都以以下格式描述：：

<name> is a <property class> and defaults to <default value>.

例如

text 是一个 StringProperty，默认值为 ''。

如果您希望在`pos`属性发生变化时（即控件移动时）收到通知，可以像这样绑定您自己的回调函数：

def callback_pos(instance, value):
    print('The widget', instance, 'moved to', value)

wid = Widget()
wid.bind(pos=callback_pos)

了解更多关于属性的信息。

基本绘图¶

控件支持一系列绘图指令，您可以使用这些指令来自定义控件和布局的外观。例如，要为您的控件绘制背景图像，您可以执行以下操作：

def redraw(self, args):
    self.bg_rect.size = self.size
    self.bg_rect.pos = self.pos

widget = Widget()
with widget.canvas:
    widget.bg_rect = Rectangle(source="cover.jpg", pos=self.pos, size=self.size)
widget.bind(pos=redraw, size=redraw)

要在kv中绘制背景：

Widget:
    canvas:
        Rectangle:
            source: "cover.jpg"
            size: self.size
            pos: self.pos

这些示例只是冰山一角。更多信息请参阅 kivy.graphics 文档。

控件触摸事件冒泡¶

当你在多个控件之间捕获触摸事件时，通常需要了解这些事件传播的顺序。在Kivy中，事件从第一个子控件向上冒泡，依次经过其他子控件。如果一个控件有子控件，事件会先传递给它的子控件，然后再传递给该控件之后的控件。

由于 add_widget() 方法默认在索引 0 处插入控件，这意味着事件从最近添加的控件回溯到第一个添加的控件。考虑以下情况：

box = BoxLayout()
box.add_widget(Label(text="a"))
box.add_widget(Label(text="b"))
box.add_widget(Label(text="c"))

文本为“c”的标签最先接收到事件，“b”其次，“a”最后。您可以通过手动指定索引来反转此顺序：

box = BoxLayout()
box.add_widget(Label(text="a"), index=0)
box.add_widget(Label(text="b"), index=1)
box.add_widget(Label(text="c"), index=2)

现在顺序将是“a”、“b”然后是“c”。在使用kv时，需要记住的一点是，声明一个widget会使用:meth:`~kivy.uix.widget.Widget.add_widget`方法进行插入。因此，使用

BoxLayout:
    MyLabel:
        text: "a"
    MyLabel:
        text: "b"
    MyLabel:
        text: "c"

将导致事件顺序为“c”、“b”然后“a”，因为“c”实际上是最后添加的部件。因此它的索引为0，“b”索引为1，“a”索引为2。实际上，子部件的顺序与其列出的顺序相反。

这个顺序同样适用于 on_touch_move() 和 on_touch_up() 事件。

为了阻止事件冒泡，方法可以返回`True`。这告诉Kivy事件已被处理，事件传播停止。例如：

class MyWidget(Widget):
    def on_touch_down(self, touch):
        If <some_condition>:
            # Do stuff here and kill the event
            return True
        else:
            return super(MyWidget, self).on_touch_down(touch)

这种方法让你能够精确控制事件的派发和管理方式。然而，有时你可能希望在采取行动之前让事件完全传播。你可以使用 Clock 来帮助你实现这一点：

class MyWidget(Label):
    def on_touch_down(self, touch, after=False):
        if after:
            print "Fired after the event has been dispatched!"
        else:
            Clock.schedule_once(lambda dt: self.on_touch_down(touch, True))
            return super(MyWidget, self).on_touch_down(touch)

使用 `Widget.center`、`Widget.right` 和 `Widget.top` 属性。¶

使用诸如 Widget.right 这样的计算属性时，一个常见的错误是使用它来让控件跟随其父级，例如通过 KV 规则 right: self.parent.right。例如，考虑以下情况：

FloatLayout:
    id: layout
    width: 100
    Widget:
        id: wid
        right: layout.right

（一个常见的误解是）这个规则确保了`wid`的`right`属性始终与`layout`的`right`属性保持一致——也就是说，`wid.right`和`layout.right`将始终相同。实际上，这个规则仅仅表明“每当`layout`的`right`发生变化时，`wid`的`right`会被设置为该值”。区别在于，只要`layout.right`没有改变，`wid.right`可以是任何值，甚至是一个使它们不同的值。

具体来说，对于上述KV代码，请考虑以下示例:

>>> print(layout.right, wid.right)
(100, 100)
>>> wid.x = 200
>>> print(layout.right, wid.right)
(100, 300)

可以看出，最初它们是同步的，然而，当我们更改 wid.x 时，它们就会失去同步，因为 layout.right 没有被更改，且规则未被触发。

让控件跟随其父级右侧的正确方式是使用 Widget.pos_hint。如果我们不用 right: layout.right，而是采用 pos_hint: {'right': 1}，那么在每次布局更新时，控件的右侧将始终被设置为父级的右侧。

class kivy.uix.widget.Widget(**kwargs)[源代码]¶

基类：WidgetBase

Widget 类。更多信息请参阅模块文档。

事件:

on_touch_down：(touch, ): 当新的触摸事件发生时触发。touch 是触摸对象。
on_touch_move：(touch, ): 当已有触摸移动时触发。touch 是触摸对象。
on_touch_up：(touch, ): 当现有的触摸消失时触发。touch 是触摸对象。
on_kv_post: (base_widget, ): 在所有与该控件关联的kv规则以及这些规则中涉及的所有其他控件的kv规则都应用完毕后触发。base_widget 是触发kv规则实例化的最基础控件（即从Python实例化的控件，例如 MyWidget()）。

在 1.11.0 版本发生变更.

警告

在Python 3.4之前的版本中，向从Widget派生的类添加`__del__`方法将禁用该类实例的自动垃圾回收。这是因为Widget类会创建引用循环，从而`阻止垃圾回收 <https://docs.python.org/2/library/gc.html#gc.garbage>`_。

在 1.0.9 版本发生变更: 与事件属性相关的内容已全部移至 EventDispatcher 中。现在，在构建一个简单的类时，无需继承 Widget 即可使用事件属性。

在 1.5.0 版本发生变更: 构造函数现在接受 on_* 参数，以便自动将回调绑定到属性或事件，就像在 Kv 语言中那样。

add_widget(widget, index=0, canvas=None)[源代码]¶

将此小部件添加为当前小部件的子级。

参数:

widget：Widget
要添加到我们子控件列表中的控件。

index：整数，默认值为0
在列表中插入小部件的索引。请注意，默认值为0意味着小部件被插入到列表的开头，因此会绘制在其他同级小部件之上。关于索引和小部件层次结构的完整讨论，请参阅小部件编程指南。

在 1.0.5 版本加入.

canvas：字符串，默认为 None
用于添加控件画布的Canvas。可以是'before'、'after'或None（默认画布）。

在 1.9.0 版本加入.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

apply_class_lang_rules(root=None, ignored_consts={}, rule_children=None)[源代码]¶

由kivy调用的方法，用于应用此widget类的kv规则。

参数:

root：Widget: 在kv中实例化此widget的根widget，如果该widget是在kv中实例化的，否则为``None``。
ignored_consts：集合: （内部）参见 apply()。
rule_children：列表: （内部）参见 apply()。

这在将类kv规则应用于控件之前/之后执行代码非常有用。例如，如果kv代码在绑定规则中使用某些属性之前需要先初始化这些属性。如果覆盖此方法，请记得调用``super``，否则kv规则将不会被应用。

在以下示例中，

class MyWidget(Widget):
    pass

class OtherWidget(MyWidget):
    pass

<MyWidget>:: my_prop: some_value
<OtherWidget>:: other_prop: some_value

当使用 OtherWidget() 实例化 OtherWidget 时，会调用该部件的 apply_class_lang_rules() 方法，并应用此类的 kv 规则——<MyWidget> 和 <OtherWidget>。

同样地，当从kv实例化该widget时，例如：

<MyBox@BoxLayout>:
    height: 55
    OtherWidget:
        width: 124

调用 OtherWidget 的 apply_class_lang_rules() 方法，该方法会应用此类的 kv 规则——<MyWidget> 和 <OtherWidget>。

备注

它仅应用类规则，而不应用实例规则。即，在上述kv示例的``MyBox``规则中，当``OtherWidget``被实例化时，其:meth:`apply_class_lang_rules`会将``<MyWidget>``和``<OtherWidget>``规则应用于它——但不会应用``width: 124``规则。``width: 124``规则属于``MyBox``规则的一部分，并由``MyBox``实例的:meth:`apply_class_lang_rules`应用。

在 1.11.0 版本发生变更.

canvas = None¶

控件的画布。

canvas 是一个图形对象，包含了用于控件图形表示的所有绘制指令。

Widget 类没有通用属性，如背景颜色，以保持设计简洁精炼。某些派生类，如 Button，确实添加了此类便捷属性，但通常开发者需从零开始为自定义控件实现图形表示。请参阅派生控件类以了解可遵循和扩展的模式。

关于用法，请参阅 Canvas 以获取更多信息。

center¶

控件的中心位置。

center 是 (center_x, center_y) 属性的 ReferenceListProperty。

center_x¶

控件的X中心位置。

center_x 是 (x + width / 2.) 的 AliasProperty。

center_y¶

控件的Y轴中心位置。

center_y 是 (y + height / 2.) 的 AliasProperty。

children¶

此控件的子控件列表。

children 是一个 ListProperty，默认值为空列表。

使用 add_widget() 和 remove_widget() 来操作子控件列表。除非你明确知道自己在做什么，否则不要直接操作子控件列表。

clear_widgets(children=None)[源代码]¶: 移除该部件的所有（或指定的）:attr:~Widget.children。如果指定了'children'参数，它应为当前部件子部件的一个列表（或过滤后的列表）。

在 1.8.0 版本发生变更: children 参数可用于指定你想要移除的子项。

在 2.1.0 版本发生变更: 指定一个空的 children 列表不会改变现有控件。此前，它会被视为 None，从而移除所有子控件。

cls¶: Widget 的类，用于样式设置。

collide_point(x, y)[源代码]¶

检查点 (x, y) 是否位于该控件的轴对齐边界框内。

参数:

x：数值: 点的x位置（在父坐标中）
y：数值: 点的y坐标（相对于父坐标）

返回:

一个布尔值。如果该点在边界框内，则为True，否则为False。

>>> Widget(pos=(10, 10), size=(50, 50)).collide_point(40, 40)
True

collide_widget(wid)[源代码]¶

检查另一个控件是否与此控件碰撞。此函数默认执行轴对齐边界框相交测试。

参数:

wid：Widget 类: 用于测试碰撞的部件。

返回:

bool。如果其他控件与此控件碰撞，则为True，否则为False。

>>> wid = Widget(size=(50, 50))
>>> wid2 = Widget(size=(50, 50), pos=(25, 25))
>>> wid.collide_widget(wid2)
True
>>> wid2.pos = (55, 55)
>>> wid.collide_widget(wid2)
False

disabled¶

指示此控件是否可以与输入进行交互。

disabled 是一个 AliasProperty，默认值为 False。

备注

子控件在添加到被禁用的控件后，将自动变为禁用状态。
禁用/启用父组件会同时禁用/启用其所有子组件。

在 1.8.0 版本加入.

在 1.10.1 版本发生变更: disabled 已从 BooleanProperty 更改为 AliasProperty，以便在父级禁用状态发生变化时，能够访问其先前的状态。

export_as_image(*args, **kwargs)[源代码]¶: 返回实际控件对应的核心 Image 对象。

在 1.11.0 版本加入.

export_to_png(filename, *args, **kwargs)[源代码]¶

以PNG格式将控件及其子控件的图像保存到指定文件名。实现方式是将控件画布从其父级中移除，渲染到一个 Fbo 中，并调用 save() 方法。

备注

图像仅包含此控件及其子控件。若需包含树中其他位置的控件，必须从其共同父控件调用 export_to_png()，或使用 screenshot() 捕获整个窗口。

备注

图片将以png格式保存，请在文件名中包含扩展名。

在 1.9.0 版本加入.

参数:

filename：字符串: 用于保存png的文件名。
scale：浮点数: 保存图像时缩放的比例，默认为1。

在 1.11.0 版本加入.

get_parent_window()[源代码]¶

返回父窗口。

返回:: 父窗口的实例。可以是 WindowBase 或 Widget。

get_root_window()[源代码]¶

返回根窗口。

返回:: 根窗口的实例。可以是 WindowBase 或 Widget。

get_window_matrix(x=0, y=0)[源代码]¶

计算窗口坐标与部件坐标之间转换的变换矩阵。

参数:

x：浮点数，默认值为 0: 在x轴上平移矩阵。
y：浮点数，默认值为0: 沿 y 轴平移矩阵。

height¶

控件的高度。

height 是一个 NumericProperty，默认值为 100。

警告

请注意，height 属性受布局逻辑影响，而在组件的 __init__ 方法执行时，布局尚未发生。

警告

不支持负高度。

ids¶

这是您在kv语言中定义的id字典。只有当您在kv语言代码中使用ids时，该字典才会被填充。

在 1.7.0 版本加入.

ids 是一个 DictProperty，默认值为空字典 {}。

:每个根级控件定义都会填充 ids 属性。例如：

# in kv
<MyWidget@Widget>:
    id: my_widget
    Label:
        id: label_widget
        Widget:
            id: inner_widget
            Label:
                id: inner_label
    TextInput:
        id: text_input
    OtherWidget:
        id: other_widget


<OtherWidget@Widget>
    id: other_widget
    Label:
        id: other_label
        TextInput:
            id: other_textinput

然后在 Python 中：

>>> widget = MyWidget()
>>> print(widget.ids)
{'other_widget': <weakproxy at 041CFED0 to OtherWidget at 041BEC38>,
'inner_widget': <weakproxy at 04137EA0 to Widget at 04138228>,
'inner_label': <weakproxy at 04143540 to Label at 04138260>,
'label_widget': <weakproxy at 04137B70 to Label at 040F97A0>,
'text_input': <weakproxy at 041BB5D0 to TextInput at 041BEC00>}
>>> print(widget.ids['other_widget'].ids)
{'other_textinput': <weakproxy at 041DBB40 to TextInput at 041BEF48>,
'other_label': <weakproxy at 041DB570 to Label at 041BEEA0>}
>>> print(widget.ids['label_widget'].ids)
{}

motion_filter¶

保存一个从 type_id 到已注册接收该类型运动事件的子控件列表的字典。

不要直接修改该属性，而应使用 register_for_motion_event() 和 unregister_for_motion_event() 方法来注册和注销运动事件。如果 self 已注册，它将始终是列表中的第一个元素。

在 2.1.0 版本加入.

警告

这是一个实验性属性，只要此警告存在，它就一直保持实验状态。

on_motion(etype, me)[源代码]¶

当接收到一个运动事件时调用。

参数:

etype：str: 事件类型，取值为"begin"、"update"或"end"之一。
me：MotionEvent: 收到运动事件

返回:

bool 类型，设为 True 可停止事件分发。

在 2.1.0 版本加入.

警告

这是一个实验性方法，只要此警告存在，它仍处于实验阶段。

on_touch_down(touch)[源代码]¶

接收触摸按下事件。

参数:

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

返回:

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

on_touch_move(touch)[源代码]¶

接收触摸移动事件。触摸位于父坐标中。

更多信息请参阅 on_touch_down()。

on_touch_up(touch)[源代码]¶

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

更多信息请参阅 on_touch_down()。

opacity¶

控件及其所有子控件的透明度。

在 1.4.1 版本加入.

opacity 属性控制控件及其子控件的透明度。请注意，这是一个累积属性：该值会与当前全局透明度相乘，并将结果应用于当前上下文颜色。

例如，如果父级的不透明度为0.5，而子级的不透明度为0.2，那么子级的实际不透明度将是0.5 * 0.2 = 0.1。

然后，着色器将不透明度应用为：

frag_color = color * vec4(1.0, 1.0, 1.0, opacity);

opacity 是一个 NumericProperty，默认值为 1.0。

parent¶

此控件的父级。当控件被添加到另一个控件时，其父级会被设置；当控件从其父级中移除时，父级会被取消设置。

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

pos¶

控件的位置。

pos 是 (x, y) 属性的 ReferenceListProperty。

pos_hint¶

位置提示。此属性允许您设置部件在其父布局内的位置（类似于size_hint）。

例如，若要将控件的顶部设置为其父布局高度的90%，可以这样写:

widget = Widget(pos_hint={'top': 0.9})

键 'x'、'right' 和 'center_x' 将使用父级宽度。键 'y'、'top' 和 'center_y' 将使用父级高度。

更多信息请参阅：浮动布局。

备注

pos_hint 并非所有布局都会使用。请查阅相关布局的文档，确认其是否支持 pos_hint。

pos_hint 是一个 ObjectProperty，包含一个字典。

property proxy_ref¶: 返回该控件的一个代理引用，即不创建对控件的直接引用。更多信息请参阅 weakref.proxy。

在 1.7.2 版本加入.

register_for_motion_event(type_id, widget=None)[源代码]¶

注册以接收 type_id 类型的运动事件。

重写 on_motion() 方法或绑定到 on_motion 事件，以处理传入的运动事件。

参数:

type_id：str: 运动事件类型ID（例如：“touch”、“hover”等）
widget：Widget: 子部件，若省略则为`self`

在 2.1.0 版本加入.

备注

方法可以使用相同的参数多次调用。

警告

这是一个实验性方法，只要此警告存在，它仍处于实验阶段。

remove_widget(widget)[源代码]¶

从该部件的子部件中移除一个部件。

参数:

widget：Widget
要从我们的子控件列表中移除的控件。

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

right¶

控件的右侧位置。

right 是 (x + width) 的 AliasProperty。

size¶

控件的大小。

size 是 (width, height) 属性的 ReferenceListProperty。

size_hint¶

尺寸提示。

size_hint 是 (size_hint_x, size_hint_y) 属性的 ReferenceListProperty。

更多信息请参阅 size_hint_x。

size_hint_max¶

使用 size_hint 时的最大尺寸。

size_hint_max 是 (size_hint_max_x, size_hint_max_y) 属性的 ReferenceListProperty。

在 1.10.0 版本加入.

size_hint_max_x¶

当该值不为None时，且 size_hint_x 同样不为None的情况下，x方向的最大尺寸（以像素为单位，类似于 width）。

类似于 size_hint_min_x，但此属性用于设置最大宽度。

size_hint_max_x 是一个 NumericProperty，默认值为 None。

在 1.10.0 版本加入.

size_hint_max_y¶

当该值不为None时，且 size_hint_y 也不为None的情况下，y方向的最大尺寸（以像素为单位，类似于 height）。

类似于 size_hint_min_y，但此属性用于设置最大高度。

size_hint_max_y 是一个 NumericProperty，默认值为 None。

在 1.10.0 版本加入.

size_hint_min¶

使用 size_hint 时的最小尺寸。

size_hint_min 是 (size_hint_min_x, size_hint_min_y) 属性的 ReferenceListProperty。

在 1.10.0 版本加入.

size_hint_min_x¶

当该值不为None时，且 size_hint_x 同样不为None的情况下，x方向的最小尺寸（以像素为单位，类似于 width）。

当 size_hint_x 不为 None 时，size_hint_min_x 是控件因 size_hint_x 而被设置的最小宽度。即，当计算出的尺寸更小时，将使用 size_hint_min_x 作为控件宽度的值。当 size_hint_min_x 为 None，或 size_hint_x 为 None 时，size_hint_min_x 不产生任何效果。

只有 Layout 和 Window 类会使用该提示。

size_hint_min_x 是一个 NumericProperty，默认值为 None。

在 1.10.0 版本加入.

size_hint_min_y¶

当该值不为None时，且 size_hint_y 也不为None的情况下，y方向的最小尺寸（以像素为单位，类似于 height）。

当 size_hint_y 不为 None 时，size_hint_min_y 是控件因 size_hint_y 而被设置的最小高度。即，当计算出的尺寸更小时，将使用 size_hint_min_y 作为控件的高度。当 size_hint_min_y 为 None，或 size_hint_y 为 None 时，size_hint_min_y 不产生任何效果。

只有 Layout 和 Window 类会使用该提示。

size_hint_min_y 是一个 NumericProperty，默认值为 None。

在 1.10.0 版本加入.

size_hint_x¶

x 尺寸提示。表示控件在 x 轴方向上相对于其父级宽度应使用的空间量。只有 Layout 和 Window 类会使用该提示。

size_hint 在布局中有两个用途：

当布局单独考虑子部件而非与其他子部件的关系时，size_hint_x 是父宽度的一个直接比例，通常在 0.0 到 1.0 之间。例如，在垂直 BoxLayout 中，一个具有 size_hint_x=0.5 的部件将占据 BoxLayout 宽度的一半；而在 FloatLayout 中，一个具有 size_hint_x=0.2 的部件将占据 FloatLayout 宽度的 20%。如果 size_hint 大于 1，则该部件将比父部件更宽。
当多个控件可以共享布局的一行时，例如在水平BoxLayout中，它们的宽度将根据其size_hint_x占所有控件size_hints总和的比例来确定。例如，如果size_hint_xs为(0.5, 1.0, 0.5)，则第一个控件的宽度将是父容器宽度的25%。

size_hint_x 是一个 NumericProperty，默认值为 1。

size_hint_y¶

y 尺寸提示。

size_hint_y 是一个 NumericProperty，默认值为 1。

更多信息请参阅 size_hint_x，但此处宽度与高度互换。

to_local(x, y, relative=False)[源代码]¶

将父级坐标转换为本地（当前控件）坐标。

关于坐标系统的详细信息，请参阅 relativelayout。

参数:

relative：布尔值，默认为 False: 如果你想要将坐标转换为相对于控件的坐标，请将其设置为True。

to_parent(x, y, relative=False)[源代码]¶

将局部（当前控件）坐标转换为父控件坐标。

关于坐标系统的详细信息，请参阅 relativelayout。

参数:

relative：布尔值，默认为 False: 如果你想要将小部件的相对位置转换为其父坐标，请将其设置为True。

to_widget(x, y, relative=False)[源代码]¶

将坐标从窗口转换为本地（当前控件）坐标。

关于坐标系统的详细信息，请参阅 relativelayout。

to_window(x, y, initial=True, relative=False)[源代码]¶

如果 initial 为 True（默认值），则会将 parent 坐标转换为窗口坐标。否则，会将 **local**（当前控件）坐标转换为窗口坐标。

关于坐标系统的详细信息，请参阅 relativelayout。

top¶

控件的顶部位置。

top 是 (y + height) 的 AliasProperty。

unregister_for_motion_event(type_id, widget=None)[源代码]¶

注销以停止接收 type_id 类型的运动事件。

参数:

type_id：str: 运动事件类型ID（例如：“touch”、“hover”等）
widget：Widget: 子部件，若省略则为`self`

在 2.1.0 版本加入.

备注

方法可以使用相同的参数多次调用。

警告

这是一个实验性方法，只要此警告存在，它仍处于实验阶段。

walk(restrict=False, loopback=False)[源代码]¶

从该控件开始遍历控件树的迭代器，按布局显示它们的顺序向前返回控件。

参数:

restrict：布尔值，默认为 False: 如果为True，则仅遍历该控件及其子控件（或子控件的子控件等）。默认为False。
loopback：布尔值，默认为 False: 如果为 True，当遍历到控件树中的最后一个控件时，它将循环回到最顶层的根控件，并继续遍历，直到再次遇到该控件。自然，只有在 restrict 为 False 时才能循环回去。默认值为 False。

返回:

一个生成器，遍历树结构，按正向布局顺序返回控件。

例如，给定一棵具有以下结构的树：

GridLayout:
    Button
    BoxLayout:
        id: box
        Widget
        Button
    Widget

遍历这棵树：

>>> # Call walk on box with loopback True, and restrict False
>>> [type(widget) for widget in box.walk(loopback=True)]
[<class 'BoxLayout'>, <class 'Widget'>, <class 'Button'>,
    <class 'Widget'>, <class 'GridLayout'>, <class 'Button'>]
>>> # Now with loopback False, and restrict False
>>> [type(widget) for widget in box.walk()]
[<class 'BoxLayout'>, <class 'Widget'>, <class 'Button'>,
    <class 'Widget'>]
>>> # Now with restrict True
>>> [type(widget) for widget in box.walk(restrict=True)]
[<class 'BoxLayout'>, <class 'Widget'>, <class 'Button'>]

在 1.9.0 版本加入.

walk_reverse(loopback=False)[源代码]¶

从当前控件之前的控件开始，反向遍历控件树的迭代器，按照布局显示顺序的逆序返回控件。

该方法与 walk() 的方向相反，因此，若 loopback 为 True，使用 walk() 生成的树列表将与此方法生成的列表顺序相反。

参数:

loopback：布尔值，默认为 False: 如果为 True，当遍历到达树中最顶层的根节点时，它将循环回到最后一个控件，并开始反向遍历，直到再次遇到该控件为止。默认值为 False。

返回:

一个生成器，遍历树结构，按反向布局顺序返回控件。

例如，给定一棵具有以下结构的树：

GridLayout:
    Button
    BoxLayout:
        id: box
        Widget
        Button
    Widget

遍历这棵树：

>>> # Call walk on box with loopback True
>>> [type(widget) for widget in box.walk_reverse(loopback=True)]
[<class 'Button'>, <class 'GridLayout'>, <class 'Widget'>,
    <class 'Button'>, <class 'Widget'>, <class 'BoxLayout'>]
>>> # Now with loopback False
>>> [type(widget) for widget in box.walk_reverse()]
[<class 'Button'>, <class 'GridLayout'>]
>>> forward = [w for w in box.walk(loopback=True)]
>>> backward = [w for w in box.walk_reverse(loopback=True)]
>>> forward == backward[::-1]
True

在 1.9.0 版本加入.

width¶

控件的宽度。

width 是一个 NumericProperty，默认值为 100。

警告

请注意，width 属性受布局逻辑影响，而在组件的 __init__ 方法执行时，该布局逻辑尚未发生。

警告

不支持负宽度。

x¶

控件的X坐标位置。

x 是一个 NumericProperty，默认值为 0。

y¶

Y 是 widget 的 Y 坐标位置。

y 是一个 NumericProperty，默认值为 0。

exception kivy.uix.widget.WidgetException[源代码]¶

基类：Exception

当控件遇到异常时触发。

« 虚拟键盘

从 Kivy 2.x.x 迁移至 Kivy 3.x.x »

Version

Quick search

目录

Widget 类¶

使用属性¶

基本绘图¶

控件触摸事件冒泡¶

使用 `Widget.center`、`Widget.right` 和 `Widget.top` 属性。¶

Version

Quick search

目录

Widget 类¶

使用属性¶

基本绘图¶

控件触摸事件冒泡¶

使用 Widget.center、Widget.right 和 Widget.top 属性。¶

使用 `Widget.center`、`Widget.right` 和 `Widget.top` 属性。¶