Settings¶
New in version 1.0.7.
This module is a complete and extensible framework for building a Settings interface in your application. The interface consists of a sidebar with a list of panels (on the left) and the selected panel (right).

SettingsPanel represents a group of configurable options. The SettingsPanel.title property is used by Settings when a panel is added - it determines the name of the sidebar button. SettingsPanel controls a ConfigParser instance.
The panel can be automatically constructed from a JSON definition file: you describe the settings you want and corresponding sections/keys in the ConfigParser instance... and you’re done!
Settings are also integrated with the App class. Use Settings.add_kivy_panel() to configure the Kivy core settings in a panel.
Create panel from JSON¶
To create a panel from a JSON-file, you need two things:
- a ConfigParser instance with default values
- a JSON file
Warning
The kivy.config.ConfigParser is required. You cannot use the default ConfigParser from Python libraries.
You must create and handle the ConfigParser object. SettingsPanel will read the values from the associated ConfigParser instance. Make sure you have default values for all sections/keys in your JSON file!
The JSON file contains structured information to describe the available settings. Here is an example:
[
{
"type": "title",
"title": "Windows"
},
{
"type": "bool",
"title": "Fullscreen",
"desc": "Set the window in windowed or fullscreen",
"section": "graphics",
"key": "fullscreen",
"true": "auto"
}
]
Each element in the root list represents a setting that the user can configure. Only the “type” key is mandatory: an instance of the associated class will be created and used for the setting - other keys are assigned to corresponding properties of that class.
Type Associated class title SettingTitle bool SettingBoolean numeric SettingNumeric options SettingOptions string SettingString path SettingPath (new from 1.1.0)
In the JSON example above, the first element is of type “title”. It will create a new instance of SettingTitle and apply the rest of the key/value pairs to the properties of that class, i.e., “title”: “Windows” sets the SettingTitle.title property to “Windows”.
To load the JSON example to a Settings instance, use the Settings.add_json_panel() method. It will automatically instantiate SettingsPanel and add it to 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...
- class kivy.uix.settings.Settings(**kwargs)¶
Bases: kivy.uix.boxlayout.BoxLayout
Settings UI. Check module documentation for more information on how to use this class.
Events : - on_config_change: ConfigParser instance, section, key, value
Fired when section/key/value of a ConfigParser changes
- on_close
Fired when the Close-button is pressed.
- add_json_panel(title, config, filename=None, data=None)¶
Create and add a new SettingsPanel using the configuration config, with the JSON definition filename.
Check the Create panel from JSON section in the documentation for more information about JSON format, and the usage of this function.
- add_kivy_panel()¶
Add a panel for configuring Kivy. This panel acts directly on the kivy configuration. Feel free to include or exclude it in your configuration.
- content¶
(internal) Reference to the widget that will contain the panel widget.
content is a ObjectProperty, default to None.
- create_json_panel(title, config, filename=None, data=None)¶
Create new SettingsPanel.
New in version 1.5.0.
Check the documentation of add_json_panel() for more information.
- get_panel_by_uid(uid)¶
Return the panel previously added from his UID. If it does not exist, return None.
(internal) Reference to the widget that will contain the sidebar menu.
menu is a ObjectProperty, default to None.
- register_type(tp, cls)¶
Register a new type that can be used in the JSON definition.
- select(panel)¶
Select a panel previously added on the widget.
- selection¶
(internal) Reference to the selected label in the sidebar.
selection is a ObjectProperty, default to None.
- unselect()¶
Unselect the current selection if it exists.
- class kivy.uix.settings.SettingsPanel(**kwargs)¶
Bases: kivy.uix.gridlayout.GridLayout
This class is used to contruct panel settings, for use with a Settings instance or subclass.
- config¶
A kivy.config.ConfigParser instance. See module documentation for more information.
- get_value(section, key)¶
Return the value of the section/key from the config ConfigParser instance. This function is used by SettingItem to get the value for a given section/key.
If you don’t want to use a ConfigParser instance, you might want to adapt this function.
- class kivy.uix.settings.SettingItem(**kwargs)¶
Bases: kivy.uix.floatlayout.FloatLayout
Base class for individual settings (within a panel). This class cannot be used directly; it is used for implementing the other setting classes. It builds a row with title/description (left) and setting control (right).
Look at SettingBoolean, SettingNumeric and SettingOptions for usage example.
Events : - on_release
Fired when the item is touched then released
- content¶
(internal) Reference to the widget that contains the real setting. As soon as the content object is set, any further call to add_widget will call the content.add_widget. This is automatically set.
content is a ObjectProperty, default to None.
- desc¶
Description of the setting, rendered on the line below title.
desc is a StringProperty, default to None.
- disabled¶
Indicate if this setting is disabled. If True, all touches on the setting item will be discarded.
disabled is a BooleanProperty, default to False.
- key¶
Key of the token inside the section in the ConfigParser instance.
key is a StringProperty, default to None.
- panel¶
(internal) Reference to the SettingsPanel with this setting. You don’t need to use it.
panel is a ObjectProperty, default to None
- section¶
Section of the token inside the ConfigParser instance.
section is a StringProperty, default to None.
- selected_alpha¶
(internal) Float value from 0 to 1, used to animate the background when the user touches the item.
selected_alpha is a NumericProperty, default to 0.
- title¶
Title of the setting, default to ‘<No title set>’.
title is a StringProperty, default to ‘<No title set>’.
- value¶
Value of the token, according to the ConfigParser instance. Any change to the value will trigger a Settings.on_config_change() event.
value is a ObjectProperty, default to None.
- class kivy.uix.settings.SettingString(**kwargs)¶
Bases: kivy.uix.settings.SettingItem
Implementation of a string setting on top of SettingItem. It is visualized with a Label widget that, when clicked, will open a Popup with a Textinput so the user can enter a custom value.
- popup¶
(internal) Used to store the current popup when it’s shown
popup is a ObjectProperty, default to None.
- textinput¶
(internal) Used to store the current textinput from the popup, and to listen for changes.
popup is a ObjectProperty, default to None.
- class kivy.uix.settings.SettingPath(**kwargs)¶
Bases: kivy.uix.settings.SettingItem
Implementation of a Path setting on top of SettingItem. It is visualized with a Label widget that, when clicked, will open a Popup with a FileChooserListView so the user can enter a custom value.
New in version 1.1.0.
- popup¶
(internal) Used to store the current popup when it is shown.
popup is a ObjectProperty, default to None.
- textinput¶
(internal) Used to store the current textinput from the popup, and to listen for changes.
popup is a ObjectProperty, default to None.
- class kivy.uix.settings.SettingBoolean(**kwargs)¶
Bases: kivy.uix.settings.SettingItem
Implementation of a boolean setting on top of SettingItem. It is visualized with a Switch widget. By default, 0 and 1 are used for values, you can change them by setting values.
- values¶
Values used to represent the state of the setting. If you use “yes” and “no” in your ConfigParser instance:
SettingBoolean(..., values=['no', 'yes'])
Warning
You need a minimum of two values, the index 0 will be used as False, and index 1 as True
values is a ListProperty, default to [‘0’, ‘1’]
- class kivy.uix.settings.SettingNumeric(**kwargs)¶
Bases: kivy.uix.settings.SettingString
Implementation of a numeric setting on top of SettingString. It is visualized with a Label widget that, when clicked, will open a Popup with a Textinput so the user can enter a custom value.
- class kivy.uix.settings.SettingOptions(**kwargs)¶
Bases: kivy.uix.settings.SettingItem
Implementation of an option list on top of SettingItem. It is visualized with a Label widget that, when clicked, will open a Popup with a list of options from which the user can select.
- options¶
List of all availables options. This must be a list of “string” items. Otherwise, it will crash. :)
options is a ListProperty, default to [].
- popup¶
(internal) Used to store the current popup when it is shown.
popup is a ObjectProperty, default to None.