beeware / beeware/toga

Settings API for Toga

Open
#90 9 comments 11 reactions 0 assignees View on GitHub
enhancement not quite right
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
9h 45m
Merged PRs (30d)
58

Description

# Settings API for Toga
I wrote this short text after a brief discussion with @freakboy3742. My intention is to kick off a conversation about a possible 'Settings API' for the toga project. This text is badly written and possibly full of bad ideas. But it is a start! :)

## Settings API
The settings API is the attempt to provide us programmers with a abstract interface to easily create settings/preferences panels that work on all platforms. A Mac user should feel just as 'at home' as a windows or linux user. On top of that, it should be possible to port a desktop settings window to mobile without the need of rewriting it.

## Native desktop settings in the wild
To get a better understanding about how native settings look like on different platforms I added this small overview.

### Desktop Examples:
![macos_settings](https://cloud.githubusercontent.com/assets/11357413/20884784/aa5cf7b6-baed-11e6-9316-93c92ecb2d0d.png)

![windows_settings](https://cloud.githubusercontent.com/assets/11357413/20884792/ae8695d6-baed-11e6-8bd7-3b19c8f6556a.jpg)

### Mobile Examples:
![ios_settings](https://cloud.githubusercontent.com/assets/11357413/20884807/bbe699f6-baed-11e6-9c80-32920008a046.png)

![android_settings](https://cloud.githubusercontent.com/assets/11357413/20884847/e67c6114-baed-11e6-954d-e0c359083946.png)

## Basic Structure
I think that all settings representations, no matter on what platform, have a common structure. They try to group settings which are related into some kind of settings group. On desktop platforms they use some sort of tab functionality, on mobile the use nested table views. These groups are then again grouped into a settings menu. On desktop often represented in form of a single settings window and on mobile in form of a settings view which holds a table view with navigation.

**Basic Hierarchy:**

* Settings Window/View
* Settings Group
* Settings Item

## Write once, use everywhere
I see the future of the toga settings API as write one, use everywhere! The translation from a desktop settings window to a mobile settings table view shouldn't be the problem as long as all settings items are implemented on all platforms.

## 'Translations'
In this section I describes possible 'translations' from desktop to mobile.

| | on Mobile | on Desktop |
|:------------- |:---------------|:-------------|
| root | view | independent settings window |
| root structure | TableView with subsections + Navigation | Tabs |
| Settings Group | TableView + Navigation | Area of the active tab |
| Settings Items | switch | checkbox |
| | slider | slider |
| | ... | ... |

## Settings Items
A list of possible settings items that one can use with the settings api.
I don't see a problem if we allow the user to use all input widgets defined in the [toga documentations](https://toga.readthedocs.io/en/latest/internals/roadmap.html#input). Again, as long as we make the settings items available on all platforms or find fitting 'translations' from desktop to mobile and vice versa.

## Under the Hood
I don't know a clever way of implementing a Settings API. But at least I can share how I would like to interact with a potential Settings API and what things I would expect from it.

~~~python
import toga

# Instantiating the settings class takes care of creating the settings window/view.
# All the platform specific bootstrapping should be taken care of and set to native defaults.
settings = toga.Settings()
# A the settings group should have a label and the possibility to add a icon to it.
group = toga.SettingsGroup('General'. icon='icon.png')

# creating setting item
switch = Switch(label='Show line numbers')

# adding setting item to the setting group
group.add(switch)

# adding group to settings
settings.add(group)

# you should be able to open the settings window/view by just calling the open() function.
settings.open()
~~~

## Notes
* I'm mostly focused on desktop and mobile. Other platforms should become a part of the equation.
* Sorry for the spelling :/
* After some feedback and discussion, I would like to get going with the OSX implementation followed by the iOS version.
* Basic functionality like callbacks on settings changes and getting the values of settings must be addressed as well.

Contributor guide

Open the contributing guide

Research direction

The issue names no implementation files or tests. Start by reading Toga's input widget documentation at the linked roadmap entry and reviewing the proposed toga.Settings, SettingsGroup, and settings.open() entry points; done would require an agreed cross-platform API covering callbacks, values, and desktop/mobile translations.

Written by the indexing model from the issue text.

Assessment

Tech stack
android, ios, macos, python
Domain
desktop-dev, frontend, mobile-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
18/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.