Table Of Contents
Configuration object¶
The Config object is an instance of a modified Python ConfigParser.
See the ConfigParser documentation for more information.
Kivy has a configuration file which determines the default settings. In order to change these settings, you can alter this file manually or use the Config object. Please see the Configure Kivy section for more information.
Applying configurations¶
Configuration options control the initialization of the App.
In order to avoid situations where the config settings do not work or are not
applied before window creation (like setting an initial window size),
Config.set should be used before
importing any other Kivy modules. Ideally, this means setting them right at
the start of your main.py script.
Alternatively, you can save these settings permanently using
Config.set then
Config.write. In this case, you will need to
restart the app for the changes to take effect. Note that this approach will
effect all Kivy apps system wide.
Please note that no underscores (_) are allowed in the section name.
Usage of the Config object¶
To read a configuration token from a particular section:
>>> from kivy.config import Config
>>> Config.getint('kivy', 'show_fps')
0
Change the configuration and save it:
>>> Config.set('postproc', 'retain_time', '50')
>>> Config.write()
For information on configuring your App, please see the
Application configuration section.
Changed in version 1.7.1: The ConfigParser should work correctly with utf-8 now. The values are converted from ascii to unicode only when needed. The method get() returns utf-8 strings.
Changing configuration with environment variables¶
Since 1.11.0, it is now possible to change the configuration using environment variables. They take precedence on the loaded config.ini. The format is:
KCFG_<section>_<key> = <value>
For example:
KCFG_GRAPHICS_FULLSCREEN=auto … KCFG_KIVY_LOG_LEVEL=warning …
Or in your file before any kivy import:
import os os.environ[“KCFG_KIVY_LOG_LEVEL”] = “warning”
If you don’t want to map any environment variables, you can disable the behavior:
os.environ["KIVY_NO_ENV_CONFIG"] = "1"
Available configuration tokens¶
| kivy: |
|
|---|---|
| postproc: |
|
| graphics: |
|
| input: | You can create new input devices using this syntax: # example of input provider instance
yourid = providerid,parameters
# example for tuio provider
default = tuio,127.0.0.1:3333
mytable = tuio,192.168.0.1:3334
See also Check the providers in |
| widgets: |
|
| modules: | You can activate modules with this syntax: modulename =
Anything after the = will be passed to the module as arguments. Check the specific module’s documentation for a list of accepted arguments. |
Changed in version 1.10.0: min_state_time and allow_screensaver have been added to the graphics section. kivy_clock has been added to the kivy section. default_font has beed added to the kivy section.
Changed in version 1.9.0: borderless and window_state have been added to the graphics section. The fake setting of the fullscreen option has been deprecated, use the borderless option instead. pause_on_minimize has been added to the kivy section.
Changed in version 1.8.0: systemanddock and systemandmulti has been added as possible values for keyboard_mode in the kivy section. exit_on_escape has been added to the kivy section.
Changed in version 1.2.0: resizable has been added to graphics section.
Changed in version 1.1.0: tuio no longer listens by default. Window icons are not copied to
user directory anymore. You can still set a new window icon by using the
window_icon config setting.
Changed in version 1.0.8: scroll_timeout, scroll_distance and scroll_friction have been added. list_friction, list_trigger_distance and list_friction_bound have been removed. keyboard_type and keyboard_layout have been removed from the widget. keyboard_mode and keyboard_layout have been added to the kivy section.
-
kivy.config.Config= None¶ The default Kivy configuration object. This is a
ConfigParserinstance with thenameset to ‘kivy’.Config = ConfigParser(name='kivy')
-
class
kivy.config.ConfigParser(name='', **kwargs)[source]¶ Bases:
configparser.RawConfigParser,builtins.objectEnhanced ConfigParser class that supports the addition of default sections and default values.
By default, the kivy ConfigParser instance,
Config, is named ‘kivy’ and the ConfigParser instance used by theApp.build_settingsmethod is named ‘app’.Parameters: - name: string
The name of the instance. See
name. Defaults to ‘’.
Changed in version 1.9.0: Each ConfigParser can now be
named. You can get the ConfigParser associated with a name usingget_configparser(). In addition, you can now control the config values withConfigParserProperty.New in version 1.0.7.
-
add_callback(callback, section=None, key=None)[source]¶ Add a callback to be called when a specific section or key has changed. If you don’t specify a section or key, it will call the callback for all section/key changes.
Callbacks will receive 3 arguments: the section, key and value.
New in version 1.4.1.
-
get(section, option, **kwargs)[source]¶ Get an option value for a given section.
If `vars’ is provided, it must be a dictionary. The option is looked up in `vars’ (if provided), `section’, and in `DEFAULTSECT’ in that order. If the key is not found and `fallback’ is provided, it is used as a fallback value. `None’ can be provided as a `fallback’ value.
If interpolation is enabled and the optional argument `raw’ is False, all interpolations are expanded in the return values.
Arguments `raw’, `vars’, and `fallback’ are keyword only.
The section DEFAULT is special.
-
static
get_configparser(name)[source]¶ Returns the
ConfigParserinstance whose name is name, or None if not found.Parameters: - name: string
The name of the
ConfigParserinstance to return.
-
getdefault(section, option, defaultvalue)[source]¶ Get the value of an option in the specified section. If not found, it will return the default value.
-
getdefaultint(section, option, defaultvalue)[source]¶ Get the value of an option in the specified section. If not found, it will return the default value. The value will always be returned as an integer.
New in version 1.6.0.
-
name¶ The name associated with this ConfigParser instance, if not ‘’. Defaults to ‘’. It can be safely changed dynamically or set to ‘’.
When a ConfigParser is given a name, that config object can be retrieved using
get_configparser(). In addition, that config instance can also be used with aConfigParserPropertyinstance that set its config value to this name.Setting more than one ConfigParser with the same name will raise a ValueError.
-
read(filename)[source]¶ Read only one filename. In contrast to the original ConfigParser of Python, this one is able to read only one file at a time. The last read file will be used for the
write()method.Changed in version 1.9.0:
read()now calls the callbacks if read changed any values.
-
remove_callback(callback, section=None, key=None)[source]¶ Removes a callback added with
add_callback().remove_callback()must be called with the same parameters asadd_callback().Raises a ValueError if not found.
New in version 1.9.0.
-
set(section, option, value)[source]¶ Functions similarly to PythonConfigParser’s set method, except that the value is implicitly converted to a string.
-
setall(section, keyvalues)[source]¶ Sets multiple key-value pairs in a section. keyvalues should be a dictionary containing the key-value pairs to be set.
-
setdefault(section, option, value)[source]¶ Set the default value for an option in the specified section.
-
setdefaults(section, keyvalues)[source]¶ Set multiple key-value defaults in a section. keyvalues should be a dictionary containing the new key-value defaults.