Skip to content

Commit 24adc8d

Browse files
ThomasFarstrikeThomasFarstrike
committed
document input_activity.py
1 parent 0a5c630 commit 24adc8d

4 files changed

Lines changed: 175 additions & 2 deletions

File tree

‎docs/frameworks/input-activity.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# InputActivity
2+
3+
`InputActivity` is a generic, reusable single-value input screen. It handles the UI and user input for one setting, then returns the value to the caller via `startActivityForResult`. It does **not** persist anything itself.
4+
5+
## Overview
6+
7+
`InputActivity` is useful any time you need to ask the user for a single value: a text string, a choice from radio buttons or a dropdown, or an integer from a slider. It supports the same input widgets as `SettingActivity`, but is independent of `SharedPreferences`.
8+
9+
`SettingActivity` is a thin wrapper around `InputActivity` that adds `SharedPreferences` persistence, row-label updates, and `changed_callback` handling. Apps that only need the input UI can use `InputActivity` directly.
10+
11+
## Basic Usage
12+
13+
```python
14+
from mpos import Activity, Intent, InputActivity
15+
16+
class MyApp(Activity):
17+
def ask_for_password(self):
18+
intent = Intent(activity_class=InputActivity)
19+
intent.putExtra("setting", {
20+
"title": "WiFi Password",
21+
"placeholder": "Enter password",
22+
"ui": "textarea"
23+
})
24+
intent.putExtra("value", "")
25+
self.startActivityForResult(intent, self.on_password_result)
26+
27+
def on_password_result(self, result):
28+
if result and result.get("result_code"):
29+
password = result["data"]["value"]
30+
print("Password entered:", password)
31+
```
32+
33+
## Intent Extras
34+
35+
### Required extras
36+
37+
- **`setting`** (dict): Metadata describing the input.
38+
39+
### Optional extras
40+
41+
- **`value`** (string): Initial value to display. If omitted, `setting["default_value"]` is used, falling back to `""`.
42+
43+
## Setting Dictionary Structure
44+
45+
The `setting` dict has the same shape as the one used by `SettingActivity` and `SettingsActivity`:
46+
47+
### Required properties
48+
49+
- **`title`** (string): Display name shown at the top of the input screen
50+
51+
### Optional properties
52+
53+
- **`key`** (string): Identifier returned in the result. Not used by `InputActivity` itself, but helpful for callers.
54+
- **`ui`** (string): UI type. Options: `"textarea"` (default), `"radiobuttons"`, `"dropdown"`, `"slider"`, `"activity"`
55+
- **`ui_options`** (list): List of `(label, value)` tuples for `radiobuttons` and `dropdown`
56+
- **`placeholder`** (string): Placeholder text for `textarea`
57+
- **`default_value`** (string): Default value if no `value` extra is provided
58+
- **`note`** (string): Short informational text shown below the input widget
59+
- **`min`** (int): Minimum value for `"slider"` (default: `0`)
60+
- **`max`** (int): Maximum value for `"slider"` (default: `100`)
61+
- **`allow_deselect`** (bool): For `radiobuttons`, allow the user to un-select the active option (default: `False`)
62+
63+
## Result Contract
64+
65+
`InputActivity` returns a result dict with the standard `Activity` result shape:
66+
67+
```python
68+
{
69+
"result_code": True, # True on Save, False on Cancel/back
70+
"data": {
71+
"value": "<new_value>",
72+
"key": "<setting key>",
73+
"ui": "<ui type>"
74+
}
75+
}
76+
```
77+
78+
The caller is responsible for persisting or acting on the returned `value`.
79+
80+
## UI Types
81+
82+
### Textarea (default)
83+
84+
Text input with an on-screen keyboard. If the device has a camera, a "Scan data from QR code" button is also shown.
85+
86+
```python
87+
{
88+
"title": "API Key",
89+
"key": "api_key",
90+
"placeholder": "Enter your API key"
91+
}
92+
```
93+
94+
### Radio Buttons
95+
96+
Mutually exclusive selection from a small list of options.
97+
98+
```python
99+
{
100+
"title": "Theme",
101+
"key": "theme",
102+
"ui": "radiobuttons",
103+
"ui_options": [
104+
("Light", "light"),
105+
("Dark", "dark"),
106+
("Auto", "auto")
107+
]
108+
}
109+
```
110+
111+
### Dropdown
112+
113+
Compact selection from a larger list of options.
114+
115+
```python
116+
{
117+
"title": "Language",
118+
"key": "language",
119+
"ui": "dropdown",
120+
"ui_options": [
121+
("English", "en"),
122+
("German", "de"),
123+
("French", "fr"),
124+
("Spanish", "es")
125+
]
126+
}
127+
```
128+
129+
### Slider
130+
131+
Integer selection within a range.
132+
133+
```python
134+
{
135+
"title": "Volume",
136+
"key": "volume",
137+
"ui": "slider",
138+
"default_value": "50",
139+
"min": 0,
140+
"max": 100
141+
}
142+
```
143+
144+
## Cancel and Back Handling
145+
146+
Pressing the **Cancel** button or swiping back returns:
147+
148+
```python
149+
{"result_code": False, "data": {"value": "...", "key": "...", "ui": "..."}}
150+
```
151+
152+
Callers should check `result.get("result_code")` before using the value.
153+
154+
## See Also
155+
156+
- [`SettingActivity`](setting-activity.md) - Wrapper that persists the input value to `SharedPreferences`
157+
- [`SettingsActivity`](settings-activity.md) - List of multiple settings, each edited through `SettingActivity`/`InputActivity`
158+
- [`SharedPreferences`](preferences.md) - For persisting values yourself

‎docs/frameworks/setting-activity.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44

55
## Overview
66

7-
`SettingActivity` displays a single setting that the user can modify. The setting is passed via Intent extras and can be configured with different UI types. When the user saves the setting, it's automatically persisted to SharedPreferences (unless `dont_persist` is set to true).
7+
`SettingActivity` is a thin wrapper around [`InputActivity`](input-activity.md). It passes the setting metadata and current value to `InputActivity`, waits for the user to save or cancel, then persists the returned value to `SharedPreferences` (unless `dont_persist` is set to true). It also updates the value label in `SettingsActivity` and fires `changed_callback` when the value changes.
8+
9+
If you only need the input UI without persistence (for example, a WiFi password prompt), use [`InputActivity`](input-activity.md) directly.
810

911
## Basic Usage
1012

@@ -393,3 +395,14 @@ class AppStore(Activity):
393395
5. **Provide meaningful placeholders**: Help users understand what format is expected with clear placeholder text.
394396

395397
6. **Consider conditional visibility**: Use `should_show` in SettingsActivity to hide settings that don't apply based on other settings.
398+
399+
## How it works
400+
401+
When `SettingActivity` is launched, it:
402+
403+
1. Reads the current value from `SharedPreferences`.
404+
2. Starts [`InputActivity`](input-activity.md) with the setting metadata and current value.
405+
3. Receives the new value when the user saves.
406+
4. Persists the value, updates the settings row label, and calls `changed_callback`.
407+
408+
The `SettingActivity` API visible to apps is unchanged; existing settings code continues to work exactly as before.

‎docs/frameworks/settings-activity.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## Overview
66

7-
`SettingsActivity` displays a list of settings that users can browse and edit. When a user taps on a setting, it opens a [`SettingActivity`](setting-activity.md) for editing that individual setting. After editing, the value is automatically saved to SharedPreferences and the list is updated.
7+
`SettingsActivity` displays a list of settings that users can browse and edit. When a user taps on a setting, it opens a [`SettingActivity`](setting-activity.md) for editing that individual setting. `SettingActivity` internally uses [`InputActivity`](input-activity.md) for the actual input UI, then persists the returned value to `SharedPreferences` and updates the list.
88

99
## Basic Usage
1010

@@ -396,4 +396,5 @@ SettingsActivity displays settings in a scrollable list with the following layou
396396
## See Also
397397

398398
- [`SettingActivity`](setting-activity.md) - For editing a single setting
399+
- [`InputActivity`](input-activity.md) - Generic input UI used by `SettingActivity`
399400
- [`SharedPreferences`](preferences.md) - For persisting settings

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ nav:
6262
- DownloadManager: frameworks/download-manager.md
6363
- FileExplorerActivity: frameworks/file-explorer-activity.md
6464
- Focus: frameworks/focus.md
65+
- InputActivity: frameworks/input-activity.md
6566
- InputManager: frameworks/input-manager.md
6667
- LightsManager: frameworks/lights-manager.md
6768
- NotificationManager: frameworks/notification-manager.md

0 commit comments

Comments
 (0)