设置¶

在 1.0.7 版本加入.

该模块为您的应用程序添加设置界面提供了一个完整且可扩展的框架。默认情况下，该界面使用一个 SettingsWithSpinner，它由一个 Spinner`（顶部）组成，用于在各个设置面板（底部）之间切换。有关其他替代方案，请参阅 :ref:`differentlayouts。

:一个 SettingsPanel 代表一组可配置选项。当面板被添加时，Settings 会使用 SettingsPanel.title 属性：它决定了侧边栏按钮的名称。SettingsPanel 控制一个 ConfigParser 实例。

面板可以通过JSON定义文件自动构建：您只需描述所需的设置，以及ConfigParser实例中对应的部分/键……就完成了！

设置也已集成到 App 类中。使用 Settings.add_kivy_panel() 可在面板中配置 Kivy 核心设置。

从JSON创建一个面板¶

要从JSON文件创建面板，你需要两样东西：

一个带有默认值的 ConfigParser 实例

一个JSON文件

警告

必须使用 kivy.config.ConfigParser。你不能使用 Python 库中的默认 ConfigParser。

你必须创建并处理 ConfigParser 对象。SettingsPanel 将从关联的 ConfigParser 实例中读取值。请确保你已为 JSON 文件中的所有部分/键设置了默认值（使用 setdefaults）！

JSON 文件包含结构化信息，用于描述可用的设置。以下是一个示例：

[
    {
        "type": "title",
        "title": "Windows"
    },
    {
        "type": "bool",
        "title": "Fullscreen",
        "desc": "Set the window in windowed or fullscreen",
        "section": "graphics",
        "key": "fullscreen"
    }
]

根列表中的每个元素代表用户可配置的一项设置。只有“type”键是必需的：将创建关联类的实例并用于该设置——其他键则分配给该类的相应属性。

类型

关联类

标题

SettingTitle

布尔值

SettingBoolean

numeric

SettingNumeric

选项

SettingOptions

string

SettingString

路径

SettingPath

颜色

SettingColor

在 1.1.0 版本加入: 新增：SettingPath 类型

在 2.1.0 版本加入: 新增了 SettingColor 类型。

在上面的JSON示例中，第一个元素的类型为"title"。它将创建一个新的:class:`SettingTitle`实例，并将剩余的键值对应用于该类的属性，即"title": "Windows"将面板的:attr:`~SettingsPanel.title`属性设置为"Windows"。

要将JSON示例加载到:class:`Settings`实例中，请使用:meth:`Settings.add_json_panel`方法。它会自动实例化一个:class:`SettingsPanel`并将其添加到:class:`Settings`中:

from kivy.config import ConfigParser

config = ConfigParser()
config.read('myconfig.ini')

s = Settings()
s.add_json_panel('My custom panel', config, 'settings_custom.json')
s.add_json_panel('Another panel', config, 'settings_test2.json')

# then use the s as a widget...

不同的面板布局¶

一个kivy App 可以自动创建并显示一个 Settings 实例。关于如何选择要显示的设置类的详细信息，请参阅 settings_cls 的文档。

Kivy 提供了几个预构建的设置组件。除了 SettingsWithNoMenu 之外，所有组件都包含触发 on_close 事件的关闭按钮。

Settings：在左侧显示一个侧边栏，用于在多个 JSON 面板之间切换。
SettingsWithSidebar：Settings 的一个简单子类。
SettingsWithSpinner：在顶部显示一个带有下拉选择器的设置界面，可用于在不同 JSON 面板之间切换。使用 InterfaceWithSpinner 作为 interface_cls。这是 Kivy 1.8.0 以来的默认行为。
SettingsWithTabbedPanel：将 JSON 面板作为独立标签页显示在 TabbedPanel 中。使用 InterfaceWithTabbedPanel 作为 interface_cls。
SettingsWithNoMenu：显示单个 json 面板，无法切换到其他面板，也没有关闭按钮。这使得用户无法退出，除非通过其他关闭触发器重写 close_settings()！使用 InterfaceWithNoMenu 作为 interface_cls。

你可以通过设置 Settings.interface_cls 来构建自己的设置面板，使用你选择的任何布局。这应该是一个显示 JSON 设置面板的 Widget，并提供某种方式在面板之间切换。Settings 会自动创建该类的实例。

界面组件可以是任何你喜欢的形式，但*必须*有一个`add_panel`方法，用于接收新创建的JSON设置面板以供界面显示。更多信息请参阅`:class:InterfaceWithSidebar``的文档。它们可以选择性地分发一个`on_close`事件，例如当点击关闭按钮时。此事件被:class:`Settings``用来触发其自身的`on_close`事件。

完整的可运行示例，请参阅 kivy/examples/settings/main.py。

class kivy.uix.settings.ContentPanel(**kwargs)[源代码]¶

基类：ScrollView

用于显示设置面板的类。它一次只显示一个设置面板，占据ContentPanel的完整大小和形状。它被:class:`InterfaceWithSidebar`和:class:`InterfaceWithSpinner`用来显示设置。

add_panel(panel, name, uid)[源代码]¶

该方法由Settings用于添加可能显示的新面板。任何ContentPanel的替代实现*必须*实现此方法。

参数:

panel: SettingsPanel: 它应在需要时被存储并显示。
name：: 面板名称，以字符串形式表示。可用于标识该面板。
uid：: 一个用于标识面板的唯一整数。在切换面板时，应存储并使用它来识别面板。

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

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

参数:

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)

container¶

（内部）对包含设置面板的GridLayout的引用。

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

current_panel¶

（内部）对当前设置面板的引用。

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

current_uid¶

（内部）当前设置面板的 uid 引用。

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

on_current_uid(*args)[源代码]¶

当前显示面板的uid。更改此值将自动更改显示的面板。

参数:

uid：: 面板唯一标识符（uid）。它应用于检索并显示先前通过 add_panel() 方法添加的设置面板。

panels¶

（内部）存储一个字典，将设置面板映射到它们的唯一标识符（UID）。

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

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

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

参数:

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

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

class kivy.uix.settings.InterfaceWithSidebar(*args, **kwargs)[源代码]¶

基类：BoxLayout

默认的设置界面类。它显示一个侧边栏菜单，列出可用的设置面板名称，可用于切换当前显示的面板。

请参阅 add_panel() 以了解在创建自定义界面时必须实现的方法的相关信息。

该类还会分发一个 'on_close' 事件，该事件在侧边栏菜单的关闭按钮被释放时触发。如果您创建自己的界面组件，它也应分发此类事件，该事件将被 :class:`Settings` 自动捕获，并用于触发其自身的 'on_close' 事件。

add_panel(panel, name, uid)[源代码]¶

该方法由Settings用于添加可能显示的新面板。任何ContentPanel的替代实现*必须*实现此方法。

参数:

panel: SettingsPanel: 它应当被存储，并且界面应提供一种在面板之间切换的方式。
name：: 面板名称，以字符串形式表示。它可用于标识面板，但不一定唯一。
uid：: 一个用于标识面板的唯一整数。它应当用于识别面板并在面板之间进行切换。

content¶

（内部）面板显示部件（一个 ContentPanel）的引用。

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

menu¶

（内部）侧边栏菜单小部件的引用。

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

class kivy.uix.settings.MenuSidebar(**kwargs)[源代码]¶

基类：FloatLayout

:由 InterfaceWithSidebar 使用的菜单。它提供了一个侧边栏，其中包含每个设置面板的条目，用户可点击以进行选择。

add_item(name, uid)[源代码]¶

该方法用于向菜单中添加新的面板。

参数:

name：: 面板的名称（字符串）。它应用于在菜单中表示该面板。
uid：: 面板的名称（一个整数）。它应在内部用于表示面板，并在面板更改时用于设置 self.selected_uid。

buttons_layout¶

（内部）对包含各个设置面板菜单按钮的GridLayout的引用。

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

close_button¶

（内部）对部件关闭按钮的引用。

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

on_selected_uid(*args)[源代码]¶: （内部）取消选中当前选中的任何菜单按钮，除非它们代表当前面板。

selected_uid¶

当前选中面板的uid。这可用于切换显示的面板，例如通过将其绑定到 ContentPanel 的 current_uid 属性。

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

class kivy.uix.settings.SettingBoolean(**kwargs)[源代码]¶

基类：SettingItem

在 SettingItem 基础上实现的一个布尔设置项。它通过 Switch 控件进行可视化展示。默认情况下，使用 0 和 1 作为值：您可以通过设置 values 来更改它们。

values¶

用于表示设置状态的值。如果你希望在ConfigParser实例中使用“yes”和“no”:

SettingBoolean(..., values=['no', 'yes'])

警告

您至少需要两个值，索引0将用作False，索引1用作True。

values 是一个 ListProperty，默认值为 ['0', '1']。

class kivy.uix.settings.SettingItem(**kwargs)[源代码]¶

基类：FloatLayout

单个设置（在面板内）的基类。此类不能直接使用；它用于实现其他设置类。它构建了一行，包含标题/描述（左侧）和设置控件（右侧）。

请参考 SettingBoolean、SettingNumeric 和 SettingOptions 的使用示例。

事件:

on_release: 当项目被触摸然后释放时触发。

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

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

参数:

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)

content¶

（内部）对包含实际设置项的部件的引用。一旦设置了内容对象，任何后续对 add_widget 的调用都将调用 content.add_widget。此属性会自动设置。

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

desc¶

设置说明，显示在标题下方的一行。

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

disabled¶

指示此设置是否被禁用。如果为True，设置项上的所有触摸操作都将被忽略。

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

key¶

在 ConfigParser 实例的 section 中，令牌的键。

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

on_touch_down(touch)[源代码]¶

接收触摸按下事件。

参数:

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

返回:

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

on_touch_up(touch)[源代码]¶

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

更多信息请参阅 on_touch_down()。

panel¶

（内部）此设置对应的SettingsPanel引用。你无需使用它。

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

section¶

: ConfigParser 实例中令牌的部分。

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

selected_alpha¶

（内部）0到1之间的浮点值，用于在用户触摸项目时对背景进行动画处理。

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

title¶

设置标题，默认为“<未设置标题>”。

title 是一个 StringProperty，默认值为 '<No title set>'。

value¶

根据 ConfigParser 实例的令牌值。对此值的任何更改都将触发 Settings.on_config_change() 事件。

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

class kivy.uix.settings.SettingNumeric(**kwargs)[源代码]¶

基类：SettingString

在 SettingString 基础上实现的一个数值设置。它通过一个 Label 控件进行可视化展示，当点击该控件时，会打开一个包含 Textinput 的 Popup，以便用户输入自定义数值。

class kivy.uix.settings.SettingOptions(**kwargs)[源代码]¶

基类：SettingItem

在 SettingItem 之上实现一个选项列表。它通过一个 Label 控件进行可视化，当点击该控件时，会打开一个包含选项列表的 Popup，用户可从中进行选择。

options¶

所有可用选项的列表。这必须是一个包含“字符串”项的列表。否则，程序会崩溃。:)

options 是一个 ListProperty，默认值为 []。

popup¶

（内部）用于在弹出窗口显示时存储当前弹出窗口。

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

class kivy.uix.settings.SettingPath(**kwargs)[源代码]¶

基类：SettingItem

在 SettingItem 基础上实现路径设置。它通过一个 Label 控件进行可视化，当点击该控件时，会打开一个包含 FileChooserListView 的 Popup，以便用户输入自定义值。

在 1.1.0 版本加入.

dirselect¶

是否允许选择目录。

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

在 1.10.0 版本加入.

popup¶

（内部）用于在弹出窗口显示时存储当前弹出窗口。

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

show_hidden¶

是否显示“隐藏”文件名。其具体含义取决于操作系统。

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

在 1.10.0 版本加入.

textinput¶

（内部）用于存储弹出窗口中的当前文本输入，并监听其变化。

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

class kivy.uix.settings.SettingString(**kwargs)[源代码]¶

基类：SettingItem

在 SettingItem 基础上实现的字符串设置项。它通过一个 Label 控件进行可视化展示，点击该标签时会打开一个包含 Textinput 的 Popup，以便用户输入自定义值。

popup¶

（内部）用于在弹出窗口显示时存储当前弹出窗口。

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

textinput¶

（内部）用于存储弹出窗口中的当前文本输入，并监听其变化。

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

class kivy.uix.settings.SettingTitle(**kwargs)[源代码]¶

基类：Label

一个简单的标题标签，用于将设置按部分组织起来。

class kivy.uix.settings.Settings(*args, **kargs)[源代码]¶

基类：BoxLayout

设置界面。有关如何使用此类的更多信息，请参阅模块文档。

事件:

on_config_change：ConfigParser 实例，节，键，值: 当ConfigParser的某个section的键值对发生变化时触发。
on_close: 默认面板在按下“关闭”按钮时触发此事件。

add_interface()[源代码]¶: （内部）创建 Settings.interface_cls 的一个实例，并将其设置为 interface。当创建 JSON 面板时，它们将被添加到该界面中，该界面将向用户显示这些面板。

add_json_panel(title, config, filename=None, data=None)[源代码]¶

使用配置 config 和 JSON 定义 filename 创建并添加一个新的 SettingsPanel。如果未设置 filename，则改为从 data 参数读取 JSON 定义。

关于JSON格式及此函数用法的更多信息，请参阅文档中的从JSON创建一个面板部分。

add_kivy_panel()[源代码]¶

添加一个用于配置Kivy的面板。此面板直接作用于Kivy配置。您可以根据需要选择在配置中包含或排除它。

关于启用/禁用自动kivy面板的信息，请参阅 use_kivy_settings()。

create_json_panel(title, config, filename=None, data=None)[源代码]¶

创建新的 SettingsPanel。

在 1.5.0 版本加入.

请参阅 add_json_panel() 的文档以获取更多信息。

interface¶

（内部）指向将包含、组织并显示面板配置面板小部件的Widget的引用。

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

interface_cls¶

用于显示设置面板图形界面的widget类。默认情况下，它一次显示一个设置面板，并带有侧边栏以便在它们之间切换。

interface_cls 是一个 ObjectProperty，默认值为 InterfaceWithSidebar。

在 1.8.0 版本发生变更: 如果你设置了一个字符串，将使用 Factory 来解析该类。

on_touch_down(touch)[源代码]¶

接收触摸按下事件。

参数:

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

返回:

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

register_type(tp, cls)[源代码]¶: 注册一种可在JSON定义中使用的新类型。

class kivy.uix.settings.SettingsPanel(**kwargs)[源代码]¶

基类：GridLayout

该类用于构建面板设置，以便与 Settings 实例或其子类一起使用。

config¶: 一个 kivy.config.ConfigParser 实例。更多信息请参阅模块文档。

get_value(section, key)[源代码]¶

返回 config ConfigParser 实例中 section/key 的值。此函数由 SettingItem 用于获取指定 section/key 的值。

如果你不想使用ConfigParser实例，可能需要重写此函数。

settings¶: 一个 Settings 实例，将用于触发 on_config_change 事件。

title¶: 面板的标题。该标题将被侧边栏中的 Settings 复用。

class kivy.uix.settings.SettingsWithNoMenu(*args, **kwargs)[源代码]¶

基类：Settings

一个设置控件，用于显示单个设置面板，且*不*包含关闭按钮。它不会接受超过一个设置面板。此控件适用于设置项较少、无需完整面板切换器的程序。

警告

此设置面板*不*提供关闭按钮，因此除非您还添加其他行为或重写 display_settings() 和 close_settings()，否则无法离开设置界面。

class kivy.uix.settings.SettingsWithSidebar(*args, **kargs)[源代码]¶

基类：Settings

一个设置控件，用于显示设置面板，并带有侧边栏以便在它们之间切换。这是 Settings 的默认行为，而该控件是其一个简单的包装子类。

class kivy.uix.settings.SettingsWithSpinner(*args, **kwargs)[源代码]¶

基类：Settings

一个设置控件，每次显示一个设置面板，顶部有一个下拉选择器用于切换不同面板。

class kivy.uix.settings.SettingsWithTabbedPanel(*args, **kwargs)[源代码]¶

基类：Settings

一个设置控件，将设置面板作为页面显示在 TabbedPanel 中。

« 滚动视图

滑块 »

Version

Quick search

目录

设置¶

从JSON创建一个面板¶

不同的面板布局¶

类型	关联类
标题	`SettingTitle`
布尔值	`SettingBoolean`
numeric	`SettingNumeric`
选项	`SettingOptions`
string	`SettingString`
路径	`SettingPath`
颜色	`SettingColor`