kivy/kivy — pull request #1493 by inclement (2013-09-10 22:59:22+00:00)
Title: Improve Settings configurability (layout, display, and ease of modification)

(I'm not sure what is the right way to do this, but I'm submitting these changes for review and testing. There are still minor documentation changes and maybe bugs to fix up but only depending on how the changes are received.)

This set of commits has the general idea that the existing settings panel is too fixed and difficult to configure, which is particularly annoying when the sidebar layout doesn't suit the screen size (i.e. phones). The main perceived problems and associated changes are:

- Currently, users cannot change how the panel is drawn (it's just put on top of the window). Solution: add an App.display_settings method that can be overridden for different behaviour, such as adding it to a screenmanager.

- Only a single layout is currently available (i.e. with the sidebar), which doesn't even work very well on a small phone screen. Solution: Abstract the settings behaviour (add_json_panel etc.) from the interface (now constructed with Settings.add_interface). All the interface does is receive SettingsPanels via an add_panel method, and it is left to display and switch between them however it likes. Several interfaces are provided, with the default being identical to the old sidebar, but other choices including a spinner menu, a tabbed panel menu, and no menu at all.

- At the moment it's difficult to impossible to tell App what kind of settings panel to use, or to edit its properties (e.g. sidebar width). Solution: add a property settings_cls that is used to construct the panel, so (for instance) the user can do `App.settings_cls = kivy.uix.settings.SettingsWithSpinner` to easily use a different settings panel layout. In conjunction with this, there is an `App.destroy_settings` method to remove internal references to the panel and force it to be recreated when next opened, so the user can change the layout during runtime and easily remake the panel.

All the new changes are documented, including how to further extend or change Settings to create new panel layouts. The default behaviour should be totally unchanged (except internal methods), so existing apps should not be affected.

To quickly see some of the new possibilities there is also a new example at kivy/examples/widgets/settings.py , demonstrating the way settings panels can easily be displayed in different ways, use different layouts, and be swapped in and out on the fly.