Kivy - Settings

The "kivy.uix.settings" module includes a very useful feature that lets you to handle the setting parameters of your Kivy installation environment. You can open the Settings panel on the application window and modify any of the configuration tokens.

When Kivy software is installed, it creates a configuration file that contains various parameter tokens with their default values. The file, named as "config.ini", is stored in a directory identified by KIVY_HOME environment variable.

  • On a Windows machine − The file is stored at C:\Users\user\.kivy\config.ini.

  • On Linux − /home/user/.kivy/config.ini.

  • On macOS − /Users/user/.kivy/config.ini.

  • On Android − /data/data/org.kivy.launcher/files/.kivy/config.ini.

  • On iOS − <HOME_DIRECTORY>/Documents/.kivy/config.ini.

To open the settings panel, call the open_settings() method of the App class, usually in response to an on_press event (or any other event) on the GUI.

def onpress(self, instance):
   app.open_settings()

We start with a simple Kivy app with a Button mounted on the window. When the button is presses, it calls the onpress() method to display the Kivy settings panel.

class HelloApp(App):
   def onpress(self, instance):
      app.open_settings()
   def build(self):
      b1=Button(
         text='Click Here', font_size=50,
         on_press=self.onpress
      )
      return b1

app = HelloApp()
app.run()

After the application is run, click the button to enter into the settings panel.

Kivy Settings

The settings shown here are the same that you see in the config.ini file. Try changing value of any of the config tokens, and you will see the changes done to the config file.

There are several setting panel layouts available.

  • Settings − Displays settings with a sidebar at the left to switch between json panels.

  • SettingsWithSidebar − A trivial subclass of Settings.

  • SettingsWithSpinner − Displays settings with a spinner at the top, which can be used to switch between json panels. This is the default.

  • SettingsWithTabbedPanel − Displays json panels as individual tabs in a TabbedPanel.

  • SettingsWithNoMenu − Displays a single json panel, with no way to switch to other panels and no close button.

To use the SeetingsWithSidebar layout, import it from the kivy.uix.settings module and assign it as the value for settings_cls parameter of the App class.

from kivy.uix.settings import SettingsWithSidebar
class HelloApp(App):
   def onpress(self, instance):
      app.open_settings()
   def build(self):
      self.settings_cls = SettingsWithSidebar
      b1=Button(text='Click Here', font_size=50, on_press=self.onpress)
      return b1

The window now provides a sidebar to switch between settings panels.

Kivy Settings Panels

Create a New Panel

Right now, you have only a panel titled Kivy that diaplays the default settings of Kivy's configuration. You can add a new panel to define the settings for your app. You need two things −

  • a ConfigParser instance with default values.

  • a JSON object.

You must create and handle the ConfigParser object to tell kivy's configparser what settings to store in a config file.. SettingsPanel will read the values from it. The default values of these settings are specified with setdefaults for all the sections/keys in your JSON object.

Let us add build_config method that gives the default values for button' text and font_size properties.

def build_config(self, config):
   config.setdefaults('My Button', {'text': 'Hello Kivy, 'font_size': 20})

The build_settings() method builds a new panel in the configuration from the JSON object in the code.

The JSON object used in this example is −

json = '''
[
   {
      "type": "string",
      "title": "Button text",
      "desc": "text on the button",
      "section": "My Button",
      "key": "text"
   },
   {
      "type": "numeric",
      "title": "Button font size",
      "desc": "font size",
      "section": "My Button",
      "key": "font_size"
   }
]

To add a new panel based on the definition of this JSON object define build_settings() method −

def build_settings(self, settings):
   settings.add_json_panel('My Button', self.config, data=json)

And that's all. When you open the settings, you should see a new My Button panel added.

Example

The complete code is given below −

from kivy.app import App
from kivy.uix.button import Button
from kivy.core.window import Window
from kivy.uix.settings import SettingsWithSidebar

Window.size = (720,350)
json = '''
[
   {
      "type": "string",
      "title": "Button text",
      "desc": "text on the button",
      "section": "My Button",
      "key": "text"
   },
   {
      "type": "numeric",
      "title": "Button font size",
      "desc": "font size",
      "section": "My Button",
      "key": "font_size"
   }
]
'''
class MyApp(App):
   def onpress(self, instance):
      app.open_settings()
      
   def build(self):
      self.settings_cls = SettingsWithSidebar
      self.btn = Button(on_press=self.onpress)
      self.btn.text = self.config.get('My Button', 'text')
      self.btn.font_size = float(self.config.get('My Button', 'font_size'))
      return self.btn
   
   def build_config(self, config):
      config.setdefaults(
         'My Button', {'text': 'Hello Python', 'font_size': 20}
      )
   
   def build_settings(self, settings):
      settings.add_json_panel('My Button', self.config, data=json)
      
   def on_config_change(self, config, section, key, value):
      if section == "My Button":
         if key == "text":
            self.btn.text = value
         elif key == 'font_size':
            self.btn.font_size = float(value)
app=MyApp()
app.run()

Output

When you open the settings panel, you now see the My Button Panel with two settings. Modify the values as required. Finally, close the settings dialog and go back to see the changes.

Kivy Settings Hello
Advertisements