KIVY Widget class

Widget class¶

Added in 1.0.0

The Widget class is the base class required for creating Widgets. This widget class was designed with a couple of principles in mind:

组件类是基础类，被需要来创造组件们。这组件类是掺和着一些智慧里的原则被设计的。

Event Driven 事件动
Widget interaction is built on top of events that occur. If a property changes, the widget can respond to the change in the ‘on_<propname>’ callback. If nothing changes, nothing will be done. That’s the main goal of the Property class.
组件相互作用是建立在呈现的事件们之上。如果一个属性改变，这组件可以对 on_<propname>返回结果里的改变做出回应。如果没啥改变，没啥可干的。那是Property类的主要的目标。
Separation Of Concerns (the widget and its graphical representation)
涉及的间隔（这组件和它的图像的表现物）

Widgets don’t have a draw() method. This is done on purpose: The idea is to allow you to create your own graphical representation outside the widget class. Obviously you can still use all the available properties to do that, so that your representation properly reflects the widget’s current state. Every widget has its own Canvas that you can use to draw. This separation allows Kivy to run your application in a very efficient manner.
组件们没有一个 draw()方法。这样干是有目的的: 这主意是来允许你来在组件类之外创造你自己个的图像表现。更显然的, 你仍然可以是用所有适合的属性来这么干，以至于你的图像表现物完全地影响着组件当前的状态。每个组件有它自己个的Canvas 你可以用来画画。这间隔允许Kivy来运行你的应用程序在一个非常有效率的方式。
Bounding Box / Collision 绑定的Box / 抵触

Often you want to know if a certain point is within the bounds of your widget. An example would be a button widget where you only want to trigger an action when the button itself is actually touched. For this, you can use the collide_point() method, which will return True if the point you pass to it is inside the axis-aligned bounding box defined by the widget’s position and size. If a simple AABB is not sufficient, you can override the method to perform the collision checks with more complex shapes, e.g. a polygon. You can also check if a widget collides with another widget with collide_widget().
经常，你想来知道是不是有一个明显的一点来判断里外组件的边界。一个例子可以是一个按钮组件在你只想来引发一个行为当这按钮它自己个是真正被触摸的。关于这点，你可以用collide_point()方法，这方法将返回True如果这点你传给它是在以组件的位置和大小被定义的轴对称关系盒子的条件内。如果一个简单地AABB 是不充足的，你可以这方法上伸展来演示这抵触检查同更多复杂的姓张，例如：一个多边形。你也可以使用 collide_widget() 检查是否一个组件与另一个组件抵触

We also have some default values and behaviors that you should be aware of:|
我们也有许多默认的值和行为你应该了解的：

A Widget is not a Layout: it will not change the position or the size of its children. If you want control over positioning or sizing, use a Layout.
一个组件不是一个布局: 它将不会改变它子类的位置或者大小。如果你想在位置和大小上有所控制，使用一个布局Layout。
The default size of a widget is (100, 100). This is only changed if the parent is a Layout. For example, if you add a Label inside a Button, the label will not inherit the button’s size or position because the button is not a Layout: it’s just another Widget.
一个组件默认的大小是（100， 100). 这只有当父类是一个布局才会改变。例如，如果你增加了一个标签Label 在一个按钮里，这个标签Label 将不会继承这个按钮的大小或者位置因为这按钮不是一个布局。它只是另外一个已组建。
The default size_hint is (1, 1). If the parent is a Layout, then the widget size will be the parent layout’s size.
默认的size_hint 是（1，1），如果父类是一个布局，然后这组件大小将是父类布局的大小。
on_touch_down(), on_touch_move(), on_touch_up() don’t do any sort of collisions. If you want to know if the touch is inside your widget, use collide_point().
on_touch_down(), on_touch_move(), on_touch_up() 不做任何种类的抵触。如果你想知道如果触摸是是不是在你的组件内，用collide_point()。

Using Properties 使用属性

When you read the documentation, all properties are described in the format:
当你阅读当前的文件，所有的属性都被总体安排地设计好了。

<name> is a <property class> and defaults to <default value>.
<name> 是一个 <property class> 属性类 并且默认是 <default value>

e.g.

text is a StringProperty and defaults to ‘’.
text 是一个StringProperty 字符属性并且默认是 ' '

If you want to be notified when the pos attribute changes, i.e. when the widget moves, you can bind your own callback function like this:
如果你想被注意当位置属性改变的时候，当这组件移动时，你可以关联你自己个地返回功能像这样:

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

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

Basic drawing 基础绘画

Widgets support a range of drawing instructions that you can use to customize the look of your widgets and layouts. For example, to draw a background image for your widget, you can do the following:
组件支持一个范围的画画指令，你可以用来定制你组件和布局们的外貌。例如：画一个背景图片给你的组件，你可以如下这样做：

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)

To draw a background in kv:

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

These examples only scratch the surface. Please see the kivy.graphics documentation for more information.
这些案例仅仅是仓促写了点皮毛。请看kivy.graphic 文档的更多的知识。

Widget touch event bubbling¶ 组件触摸事件冒泡

When you catch touch events between multiple widgets, you often need to be aware of the order in which these events are propagated. In Kivy, events bubble up from the first child upwards through the other children. If a widget has children, the event is passed through its children before being passed on to the widget after it.
当你在多个组件之间抓取触摸事件，你经常需要意识到这些事件被传播的顺序。在kivy里，事件从第一个子类向上到其他的子类冒泡。如果一个组件有子类，这事件被它的子类们已经穿过了，然后再被传给这组件。

在多个控件之间捕获触摸事件时，你通常需要了解这些事件传播的顺序。在Kivy中，事件是从第一个子控件开始，向上冒泡至其他子控件的。如果一个控件有子控件，那么事件会先在其子控件中传递，然后再传递给其后的控件。

简单地说，这意味着当你触摸一个包含多个子控件的控件时，首先会触发子控件的触摸事件处理函数（如果它们有定义的话），然后这些事件会“冒泡”到父控件，如果父控件也定义了相应的事件处理函数，那么这些函数也会被触发。这种机制使得开发者能够更精细地控制事件在不同层级控件中的处理逻辑

文心扩展:

会传递给最顶层的部件（在这个例子中是 MyLayout），但由于 MyLayout 没有重写 on_touch_down 方法，它会将事件传递给它的子部件。然而，由于你试图将 yourlabel 和 herlabel 添加到 label（一个 Label 部件），这些事件实际上并没有到达它们，因为 label 不是一个容器，不能包含子部件。

关于 on_touch_down 方法的返回值：

如果 on_touch_down 方法返回 True，则表示该事件已被该组件消耗，并且不会继续向下（到子组件）或向上（到父组件）传播。
如果 on_touch_down 方法返回 False，则表示该事件没有被该组件消耗，并且会继续传播。

注意： Label 不是容器部件，它不支持子部件

As the add_widget() method inserts widgets at index 0 by default, this means the event goes from the most recently added widget back to the first one added. Consider the following:

当 add_widget() 方法插入组件在索引默认为0 时，这意味着这事件从最新添加的组件到第一个添加的。看下面的代码思考:

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

The label with text “c” gets the event first, “b” second and “a” last. You can reverse this order by manually specifying the index:
有”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)

Now the order would be “a”, “b” then “c”. One thing to keep in mind when using kv is that declaring a widget uses the add_widget() method for insertion. Hence, using
现在顺序将是"a" "b" 然后是“c”。一个事得牢记在脑海是当使用kv文件时，声明一个组件使用add_widget()方法来插入。因此，使用：

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

would result in the event order “c”, “b” then “a” as “c” was actually the last added widget. It thus has index 0, “b” index 1 and “a” index 2. Effectively, the child order is the reverse of its listed order.
会导致事件顺序 "c" "b" 然后是 "a" 当 'c'真的是最后被添加的组件。因为它有索引是 0， “b” 索引1，以及 “a” 索引 2. 实际上，子类的顺序是和它陈列的顺序是相反的。

This ordering is the same for the on_touch_move() and on_touch_up() events.
这顺序是相同的对于 on_touch_move() 和 on_touch_up() 事件。

In order to stop this event bubbling, a method can return True. This tells Kivy the event has been handled and the event propagation stops. For example:
为了停止这事件冒泡，一个方法可以返回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)

This approach gives you good control over exactly how events are dispatched and managed. Sometimes, however, you may wish to let the event be completely propagated before taking action. You can use the Clock to help you here:
这方法给你好的控制基于真正的如何事件们被派遣和被管理。又是，然而，你可能希望让事件被完整地派遣在获取行动之前。你可以使用 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)

Usage of Widget.center, Widget.right, and Widget.top ¶

A common mistake when using one of the computed properties such as Widget.right is to use it to make a widget follow its parent with a KV rule such as right: self.parent.right. Consider, for example:
一个常见的错误当使用一个被计算的属性例如： Widget.right 被用来使用它来让一个组件跟随它的父类按着KV规则例如：右边： self.parent.right。值得考虑的是，例如：

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

The (mistaken) expectation is that this rule ensures that wid’s right will always be whatever layout’s right is - that is wid.right and layout.right will always be identical. In actual fact, this rule only says that “whenever layout’s right changes, wid’s right will be set to that value”. The difference being that as long as layout.right doesn’t change, wid.right could be anything, even a value that will make them different.
这（错误）期望是这规则确保组件的右边总是无论如何在布局的右边，那就是wid.right 和layout.right 将总是完全相同的。事实是，这规则总是说：无论何时布局的右边改变，组件的右边将被设置为其改变的值。不同时：只要布局的右边没改变，组件的右边可能会是任何事儿，甚至一个让他们不一样的值

Specifically, for the KV code above, consider the following example:
尤其是, 对以上的KV代码，看看下面的例子:

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

As can be seen, initially they are in sync, however, when we change wid.x they go out of sync because layout.right is not changed and the rule is not triggered.
显而易见的，初始它们是不一样的，然而，当我们改变wid.x，它们会同步因为 layout.right 是不变的并且是不犯规的。

The proper way to make the widget follow its parent’s right is to use Widget.pos_hint. If instead of right: layout.right we did pos_hint: {‘right’: 1}, then the widgets right will always be set to be at the parent’s right at each layout update.
真正的方式让组件跟随它的父母的右边是使用Widget.pos_hint 如果右边被替代， layout.right，我们设置 pos_hint:{'right':1}, 然后组件右边将持续被设置为父类的右边每当布局改变。

APIHide Description ⇑

class kivy.uix.widget.Widget(**kwargs)¶

Bases: kivy.uix.widget.WidgetBase

Widget class. See module documentation for more information.

Events:

on_touch_down: (touch, )

Fired when a new touch event occurs. touch is the touch object.
当一个新的触摸事件呈现时， touch是被触摸的对象

on_touch_move: (touch, )

Fired when an existing touch moves. touch is the touch object.
当一个存在的触摸滑动时，touch 是移动的触摸对象

on_touch_up: (touch, )

Fired when an existing touch disappears. touch is the touch object.
当一个存在的触摸消失时， touch 是触摸对象

on_kv_post: (base_widget, )

Fired after all the kv rules associated with the widget and all other widgets that are in any of those rules have had all their kv rules applied. base_widget is the base-most widget whose instantiation triggered the kv rules (i.e. the widget instantiated from Python, e.g. MyWidget()).
在所有的kv规则同在这些规则被组件和所有其他的组件应用联系时， base_widget 是最基础的组件，它的实例被引用了kv的规则（组件从python实例化）

on_kv_post 事件是在所有与特定组件（widget）相关的 KV 规则（即在 .kv 文件中定义的规则）以及这些规则中引用的所有其他组件的 KV 规则都被应用之后触发的。base_widget 参数是指触发这些 KV 规则的最顶层组件（即从 Python 代码中实例化的那个组件，如 MyWidget()）。

这个事件在 Kivy 1.11.0 版本中引入，它允许开发者在 KV 规则完全应用后执行一些额外的操作或初始化。

Changed in version 1.11.0.

`del` 方法与垃圾收集 Warning

Adding a __del__ method to a class derived from Widget with Python prior to 3.4 will disable automatic garbage collection for instances of that class. This is because the Widget class creates reference cycles, thereby preventing garbage collection.
增加了一个 __del__方法到一个类被组件同Python先前的版本到3.4将自动关闭垃圾收集驱使的，为了那些个本本。这是因为组件类创建额介绍循环，因此 preventing garbage collection
【赘述: 就说python3.4之前的版本无法正常使用垃圾收集，所以增加了一个 __del__方法。这是因为和组件类的循环周期相关，因此阻止了垃圾的收集。】

事件属性与 `EventDispatcher`

Changed in version 1.0.9: Everything related to event properties has been moved to the EventDispatcher. Event properties can now be used when constructing a simple class without subclassing Widget.
在1.0.9 被改变了：每个事儿和事件属性相关的都被已到了EventDispatcher. 事件属性现在可以被使用当不Widget子类化构造一个简单地类

在 Kivy 1.0.9 版本中，与事件属性相关的所有内容都被移动到了 EventDispatcher 类中。这意味着，你现在可以在不继承 Widget 类的情况下，通过简单地构造一个类并使用 EventDispatcher 的功能来使用事件属性。这为开发者提供了更大的灵活性，允许他们在不构建完整 UI 组件的情况下处理事件。

构造器与 `on_*` 回调

Changed in version 1.5.0: The constructor now accepts on_* arguments to automatically bind callbacks to properties or events, as in the Kv language.
在1.5.0的改变，构造器接收 on_*自变数来自动地关联返回到属性或事件的，同Kv语言里一样

在 Kivy 1.5.0 版本中，组件的构造器（即 __init__ 方法）开始支持 on_* 参数的自动绑定。这意味着，你可以在创建组件实例时直接指定某些属性或事件的回调函数，这与在 KV 语言中定义这些回调的方式类似。这种机制为 Python 代码中的组件初始化提供了更大的便利性和可读性。

add_widget(widget, index=0, canvas=None)¶

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

New in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

New in version 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)¶

Method that is called by kivy to apply the kv rules of this widget’s class.

Parameters:

root: Widget

The root widget that instantiated this widget in kv, if the widget was instantiated in kv, otherwise None.

ignored_consts: set

(internal) See apply().

rule_children: list

(internal) See apply().

This is useful to be able to execute code before/after the class kv rules are applied to the widget. E.g. if the kv code requires some properties to be initialized before it is used in a binding rule. If overwriting remember to call super, otherwise the kv rules will not be applied.
这是有用的来执行代码在之前/之后类kv规则被引用到这组件。如果 kv 代码需要一些属性来初始化在它被绑定到一个规则之前。如果覆盖记得召唤 super，如不则kv规则将不被应用。

In the following example,

class MyWidget(Widget):
    pass

class OtherWidget(MyWidget):
    pass

<MyWidget>:

my_prop: some_value

<OtherWidget>:

other_prop: some_value

When OtherWidget is instantiated with OtherWidget(), the widget’s apply_class_lang_rules() is called and it applies the kv rules of this class - <MyWidget> and <OtherWidget>.
当 OtherWidget 是同OtherWidget（）实例化，组件的apply_class_lang_rules()是被召唤的并且它应用kv中该类的规则 - <MyWidget> 和<OtherWidget>

Similarly, when the widget is instantiated from kv, e.g.

相同的，当这组件在kv中实例化

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

OtherWidget’s apply_class_lang_rules() is called and it applies the kv rules of this class
- <MyWidget> and <OtherWidget>.
OtherWidget的 apply_class_lang_rules() 是被召唤并且它运用kv的这俩类的规则

Note

It applies only the class rules not the instance rules. I.e. in the above kv example in the MyBox rule when OtherWidget is instantiated, its apply_class_lang_rules() applies the <MyWidget> and <OtherWidget> rules to it - it does not apply the width: 124 rule. The width: 124 rule is part of the MyBox rule and is applied by the MyBox’s instance’s apply_class_lang_rules().
它提供应用只有当类规则不是实例规则。在以上的在MyBox的kv案例规则中，当OtherWidget 被实例化时，它的 apply_class_lang_rules()适用 <MyWidget>和<OtherWidget>规则，它不适用宽度 124规则。

宽度 width ： 124规则是MyBox规则一部分，并且它以MyBox的实例apply_class_lang_rules()应用

Changed in version 1.11.0.

canvas = None¶

Canvas of the widget.

The canvas is a graphics object that contains all the drawing instructions for the graphical representation of the widget.
画布是一个可以容纳所有用来图像画画指令绘画物的构造图像对象

There are no general properties for the Widget class, such as background color, to keep the design simple and lean. Some derived classes, such as Button, do add such convenience properties but generally the developer is responsible for implementing the graphics representation for a custom widget from the ground up. See the derived widget classes for patterns to follow and extend.
对于组件类来说，这是不常见的属性，例如背景颜色，保持设计简单和精简。一些衍生类，例如 Button，添加方便的属性是负责的，但通常开发者是对执行图像绘画物定做的成组组件。看衍生组件类的模型来使用和扩展：

See Canvas for more information about the usage.

center¶

Center position of the widget. 组件的中心

center is a ReferenceListProperty of (center_x, center_y) properties.
中心是一个列表相关(center_x, center_y)的属性

center_x¶

X center position of the widget.

center_x is an AliasProperty of (x + width / 2.).

alias 美/ˈeɪliəs/ 别名

center_y¶

Y center position of the widget.

center_y is an AliasProperty of (y + height / 2.).

children¶

List of children of this widget.

children is a ListProperty and defaults to an empty list.

Use add_widget() and remove_widget() for manipulating the children list. Don’t manipulate the children list directly unless you know what you are doing.
使用 add_widget() 和 remove_widget() 来操控子类列表。不要直接操控子类列表除非你知道你在干啥。

clear_widgets(children=None)¶

Remove all (or the specified) children of this widget. If the ‘children’ argument is specified, it should be a list (or filtered list) of children of the current widget.
在组件中消除所有(或者特指的)子类。如果子类自变量是特指的，它应该是当前组件子类的一个列表（或者被过滤过的列表) 。

Changed in version 1.8.0: The children argument can be used to specify the children you want to remove.
1.8.0的改变：子类自变量可以被用来特指你想移除的子类。

Changed in version 2.1.0: Specifying an empty children list leaves the widgets unchanged. Previously it was treated like None and all children were removed.
2.1.0改变：特指一个空子类列表留给没被改变的组件部分。以前它被当作None对待，并且所有的子类都被消除。

cls¶

Class of the widget, used for styling.

collide_point(x, y)¶

Check if a point (x, y) is inside the widget’s axis aligned bounding box.

Parameters:

x: numeric

x position of the point (in parent coordinates)

y: numeric

y position of the point (in parent coordinates)

Returns:

A bool. True if the point is inside the bounding box, False otherwise.

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

collide_widget(wid)¶

Check if another widget collides with this widget. This function performs an axis-aligned bounding box intersection test by default.
检查是不是其他组件同这个组件抵触。这个功能执行一个轴对称绑定盒子默认相交测试。

Parameters:

wid: Widget class

Widget to test collision with.

Returns:

bool. True if the other widget collides with this widget, False otherwise.

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¶

Indicates whether this widget can interact with input or not.
表明这个组件是否可以与 input 相互作用。

disabled is an AliasProperty and defaults to False.

Note

Child Widgets, when added to a disabled widget, will be disabled automatically.
1。子类组件，当被添加到一个丧失能力的组件，将被自动地丧失能力。
Disabling/enabling a parent disables/enables all of its children.
2. 使丧失能力/使能动一个父类 disables/enables 它所有的子类。

New in version 1.8.0.

Changed in version 1.10.1: disabled was changed from a BooleanProperty to an AliasProperty to allow access to its previous state when a parent’s disabled state is changed.
1.10.1改变： disabled 被从一个波尔数值属性改变到了一个别名属性来允许进入它的先前状态当一个父类的 disabled状态被改变时。

export_as_image(*args, **kwargs)¶

Return an core Image of the actual widget. 返回一个真实组件的代码图片

New in version 1.11.0.

export_to_png(filename, *args, **kwargs)¶

Saves an image of the widget and its children in png format at the specified filename. Works by removing the widget canvas from its parent, rendering to an Fbo, and calling save().
以png格式在特定文件名内保存一个组件和它子类照片。以从其父类移除组件画布为职责，呈现给一个Fbo，并且召唤save()

Note

The image includes only this widget and its children. If you want to include widgets elsewhere in the tree, you must call export_to_png() from their common parent, or use screenshot() to capture the whole window.
图片仅包括这个组件和它的子类。如果你想在树内包含组件的其他地方。你必须从它们常见的父类召唤export_to_png() ，或者使用screenshot()方法来捕获整个窗口。

Note

The image will be saved in png format, you should include the extension in your filename.
图像将被以png格式保存，在你的文件夹内你应该包括扩展名

New in version 1.9.0.

Parameters:

filename: str

The filename with which to save the png.
用来保存png图片的文件夹名字

scale: float

The amount by which to scale the saved image, defaults to 1.
以默认到1的比例数量保存图片

New in version 1.11.0.

get_parent_window()¶

Return the parent window. 返回父类窗口

Returns:

Instance of the parent window. Can be a WindowBase or Widget.
父类窗口的实例。可以是一个基础窗口或者组件

get_root_window()¶

Return the root window. 返回根类窗口

Returns:

Instance of the root window. Can be a WindowBase or Widget.
根类窗口的实例。可以是一个根类窗口或者组件

get_window_matrix(x=0, y=0)¶

Calculate the transformation matrix to convert between window and widget coordinates.
计算转变模型来窗口和组件坐标之间转变

Parameters:

x: float, defaults to 0

Translates the matrix on the x axis.
转变matrix 在x轴

y: float, defaults to 0

Translates the matrix on the y axis.
转变matrix 在y 轴

matrix 在kivy 是什么

在Kivy中，Matrix 通常与图形变换和渲染相关。根据参考文章，特别是参考文章4中提到的kivy.graphics.transformation.Matrix()示例，可以总结出以下几点关于Kivy中的Matrix：

定义与用途：

Matrix 是Kivy中用于图形变换的一个类，它允许开发者对图形元素（如图像、形状等）进行各种变换，如平移、旋转、缩放等。

使用场景：

当你需要在Kivy应用程序中动态地调整图形元素的位置、大小或方向时，Matrix 类就会非常有用。

例如，你可以使用Matrix来实现一个动态的UI元素，或者创建一个可以响应用户交互（如拖拽、旋转等）的图形界面。

与Kivy的集成：

Kivy的图形渲染系统内部使用Matrix类来处理各种图形变换。这意味着，当你在Kivy中编写代码来创建或修改图形元素时，你可能会间接或直接地使用到Matrix。

相关操作：

Matrix类提供了许多方法，用于执行各种图形变换操作。例如，identity()方法用于将矩阵重置为单位矩阵（即没有变换的状态），translate()方法用于平移变换，rotate()方法用于旋转变换，scale()方法用于缩放变换等。

示例代码：

在参考文章4中，有一个使用Matrix的示例代码片段，它展示了如何重置一个图形元素的变换（通过设置矩阵为单位矩阵）和可能的后续操作（尽管这部分代码在给出的片段中并未完整展示）。

与其他Kivy功能的配合：

Matrix通常与Kivy的图形绘制和渲染功能一起使用，例如Canvas和Graphics模块。这些模块提供了在Kivy应用程序中创建和显示图形元素所需的工具和API。

总结：

简而言之，Matrix在Kivy中是一个用于图形变换的类，它允许开发者通过编程方式动态地调整图形元素的位置、大小和方向。它是Kivy图形渲染系统的重要组成部分，并与其他图形绘制和渲染功能紧密配合。

height¶

Height of the widget. 组件的高度

height is a NumericProperty and defaults to 100.
高度是一个数量属性，并且默认是100

Warning 警告

Keep in mind that the height property is subject to layout logic and that this has not yet happened at the time of the widget’s __init__ method.
记住，高度属性受布局逻辑支配，并且这还没发生当组件的 __init__方法运行的时候

Warning 警告

A negative height is not supported.
一个负数的高度是不被支持的

ids¶ 获取kv文件里的 id值

This is a dictionary of ids defined in your kv language. This will only be populated if you use ids in your kv language code.
这是一个字典，被你的kv语言定义。这将只是出现如果你使用ids在你的kv语言代码里。

New in version 1.7.0.

ids is a DictProperty and defaults to an empty dict {}.
ids 是一个字典属性并且默认值是一个空的字典{}

The ids are populated for each root level widget definition. For example:
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

Then, in 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¶

motion 美/ˈmoʊʃ(ə)n/ 位移
Holds a dict of type_id to list of child widgets registered to receive motion events of type_id.
包含一个字典的 type_id 到子类组件列表，被设计来位移事件的type_id

Don’t change the property directly but use register_for_motion_event() and unregister_for_motion_event() to register and unregister for motion events. If self is registered it will always be the first element in the list.
不要直接改变属性而是使用register_for_motion_event()方法和unregister_for_motion_event()方法来对请求事件注册和未注册。如果自己个是被注册它将总是列表的第一个元素。

New in version 2.1.0.

Warning

This is an experimental property and it remains so while this warning is present.
这是一个实验性的属性并且它包含因此这份警告是当下暂时的。

on_motion(etype, me)¶

Called when a motion event is received. 当一个位移事件被接受时被使唤

Parameters:

etype: str

Event type, one of “begin”, “update” or “end”

me: MotionEvent

Received motion event 接收位移事件

Returns:

New in version 2.1.0.

Warning

This is an experimental method and it remains so while this warning is present.

on_touch_down(touch)¶

Receive a touch down event. 接受一个触摸按下事件

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.
触摸被接收。触摸是在父类的坐标。看relativelayout 为了讨论在坐标系里。

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.
布尔值
如果为True，按下事件将被停止派遣。
如果为False，事件将被继续派件到剩下的组件树。

on_touch_move(touch)¶

Receive a touch move event. The touch is in parent coordinates.
接收一个触摸滑动事件。触摸是在父类的坐标系内。

See on_touch_down() for more information.
看 on_touch_down() 获取更多知识。

on_touch_up(touch)¶

Receive a touch up event. The touch is in parent coordinates.
获取一个触摸松开事件，这个触摸是在父类的坐标系内。

See on_touch_down() for more information.
看on_touch_down() 来获取更多知识。

opacity¶ 透明度

Opacity of the widget and all its children. 组件和它所有子类的透明度

New in version 1.4.1.

The opacity attribute controls the opacity of the widget and its children. Be careful, it’s a cumulative attribute: the value is multiplied by the current global opacity and the result is applied to the current context color.
透明度属性控制着组件和它子类的透明度。值得注意的是，它是一个渐增的属性：值是一个以当前全局透明度成倍数增长的，并且结果被应用到当前的内容颜色。

For example, if the parent has an opacity of 0.5 and a child has an opacity of 0.2, the real opacity of the child will be 0.5 * 0.2 = 0.1.
举个例子，如果父类有一个透明度是0.5，并且一个子类有一个透明度是0.2，那么真正的该子类的透明度将是0.5 * 0.2 = 0.1

Then, the opacity is applied by the shader as:
接下来，透明度被着色程序应用

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

opacity is a NumericProperty and defaults to 1.0.
透明度是一个数量属性，并且默认是 1.0

parent¶

Parent of this widget. The parent of a widget is set when the widget is added to another widget and unset when the widget is removed from its parent.

parent is an ObjectProperty and defaults to None.

pos¶

Position of the widget.

pos is a ReferenceListProperty of (x, y) properties.

pos_hint¶

Position hint. This property allows you to set the position of the widget inside its parent layout (similar to size_hint).

For example, if you want to set the top of the widget to be at 90% height of its parent layout, you can write:

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

The keys ‘x’, ‘right’ and ‘center_x’ will use the parent width. The keys ‘y’, ‘top’ and ‘center_y’ will use the parent height.

See Float Layout for further reference.

Note

pos_hint is not used by all layouts. Check the documentation of the layout in question to see if it supports pos_hint.

pos_hint is an ObjectProperty containing a dict.

property proxy_ref¶

Return a proxy reference to the widget, i.e. without creating a reference to the widget. See weakref.proxy for more information.

New in version 1.7.2.

register_for_motion_event(type_id, widget=None)¶

Override on_motion() or bind to on_motion event to handle the incoming motion events.

Parameters:

type_id: str

Motion event type id (eg. “touch”, “hover”, etc.)

widget: Widget

Child widget or self if omitted

New in version 2.1.0.

Note

Method can be called multiple times with the same arguments.

Warning

This is an experimental method and it remains so while this warning is present.

remove_widget(widget)¶

Remove a widget from the children of this widget.

Parameters:

widget: Widget

Widget to remove from our children list.

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

right¶

Right position of the widget.

right is an AliasProperty of (x + width).

size¶

Size of the widget.

size is a ReferenceListProperty of (width, height) properties.

size_hint¶

Size hint.

size_hint is a ReferenceListProperty of (size_hint_x, size_hint_y) properties.

See size_hint_x for more information.

size_hint_max¶

Maximum size when using size_hint.

size_hint_max is a ReferenceListProperty of (size_hint_max_x, size_hint_max_y) properties.

New in version 1.10.0.

size_hint_max_x¶

When not None, the x-direction maximum size (in pixels, like width) when size_hint_x is also not None.

Similar to size_hint_min_x, except that it sets the maximum width.

size_hint_max_x is a NumericProperty and defaults to None.

New in version 1.10.0.

size_hint_max_y¶

When not None, the y-direction maximum size (in pixels, like height) when size_hint_y is also not None.

Similar to size_hint_min_y, except that it sets the maximum height.

size_hint_max_y is a NumericProperty and defaults to None.

New in version 1.10.0.

size_hint_min¶

Minimum size when using size_hint.

size_hint_min is a ReferenceListProperty of (size_hint_min_x, size_hint_min_y) properties.

New in version 1.10.0.

size_hint_min_x¶

When not None, the x-direction minimum size (in pixels, like width) when size_hint_x is also not None.

When size_hint_x is not None, it is the minimum width that the widget will be set due to the size_hint_x. I.e. when a smaller size would be set, size_hint_min_x is the value used instead for the widget width. When None, or when size_hint_x is None, size_hint_min_x doesn’t do anything.

Only the Layout and Window classes make use of the hint.

size_hint_min_x is a NumericProperty and defaults to None.

New in version 1.10.0.

size_hint_min_y¶

When not None, the y-direction minimum size (in pixels, like height) when size_hint_y is also not None.

When size_hint_y is not None, it is the minimum height that the widget will be set due to the size_hint_y. I.e. when a smaller size would be set, size_hint_min_y is the value used instead for the widget height. When None, or when size_hint_y is None, size_hint_min_y doesn’t do anything.

Only the Layout and Window classes make use of the hint.

size_hint_min_y is a NumericProperty and defaults to None.

New in version 1.10.0.

size_hint_x¶

x size hint. Represents how much space the widget should use in the direction of the x axis relative to its parent’s width. Only the Layout and Window classes make use of the hint.

The size_hint is used by layouts for two purposes:

When the layout considers widgets on their own rather than in relation to its other children, the size_hint_x is a direct proportion of the parent width, normally between 0.0 and 1.0. For instance, a widget with size_hint_x=0.5 in a vertical BoxLayout will take up half the BoxLayout’s width, or a widget in a FloatLayout with size_hint_x=0.2 will take up 20% of the FloatLayout width. If the size_hint is greater than 1, the widget will be wider than the parent.
When multiple widgets can share a row of a layout, such as in a horizontal BoxLayout, their widths will be their size_hint_x as a fraction of the sum of widget size_hints. For instance, if the size_hint_xs are (0.5, 1.0, 0.5), the first widget will have a width of 25% of the parent width.

size_hint_x is a NumericProperty and defaults to 1.

size_hint_y¶

y size hint.

size_hint_y is a NumericProperty and defaults to 1.

See size_hint_x for more information, but with widths and heights swapped.

to_local(x, y, relative=False)¶

Transform parent coordinates to local (current widget) coordinates.

See relativelayout for details on the coordinate systems.

Parameters:

relative: bool, defaults to False

Change to True if you want to translate coordinates to relative widget coordinates.

to_parent(x, y, relative=False)¶

Transform local (current widget) coordinates to parent coordinates.

See relativelayout for details on the coordinate systems.

Parameters:

relative: bool, defaults to False

Change to True if you want to translate relative positions from a widget to its parent coordinates.

to_widget(x, y, relative=False)¶

Convert the coordinate from window to local (current widget) coordinates.

See relativelayout for details on the coordinate systems.

to_window(x, y, initial=True, relative=False)¶

If initial is True, the default, it transforms parent coordinates to window coordinates. Otherwise, it transforms local (current widget) coordinates to window coordinates.

See relativelayout for details on the coordinate systems.

top¶

Top position of the widget.

top is an AliasProperty of (y + height).

unregister_for_motion_event(type_id, widget=None)¶

Unregister to receive motion events of type_id.

Parameters:

type_id: str

Motion event type id (eg. “touch”, “hover”, etc.)

widget: Widget

Child widget or self if omitted

New in version 2.1.0.

Note

Method can be called multiple times with the same arguments.

Warning

This is an experimental method and it remains so while this warning is present.

walk(restrict=False, loopback=False)¶

Iterator that walks the widget tree starting with this widget and goes forward returning widgets in the order in which layouts display them.

Parameters:

restrict: bool, defaults to False

If True, it will only iterate through the widget and its children (or children of its children etc.). Defaults to False.

loopback: bool, defaults to False

If True, when the last widget in the tree is reached, it’ll loop back to the uppermost root and start walking until we hit this widget again. Naturally, it can only loop back when restrict is False. Defaults to False.

Returns:

A generator that walks the tree, returning widgets in the forward layout order.

For example, given a tree with the following structure:

GridLayout:
    Button
    BoxLayout:
        id: box
        Widget
        Button
    Widget

walking this tree:

# 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'>]

New in version 1.9.0.

walk_reverse(loopback=False)¶

Iterator that walks the widget tree backwards starting with the widget before this, and going backwards returning widgets in the reverse order in which layouts display them.

This walks in the opposite direction of walk(), so a list of the tree generated with walk() will be in reverse order compared to the list generated with this, provided loopback is True.

Parameters:

loopback: bool, defaults to False

If True, when the uppermost root in the tree is reached, it’ll loop back to the last widget and start walking back until after we hit widget again. Defaults to False.

Returns:

A generator that walks the tree, returning widgets in the reverse layout order.

For example, given a tree with the following structure:

GridLayout:
    Button
    BoxLayout:
        id: box
        Widget
        Button
    Widget

walking this tree:

# 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

New in version 1.9.0.