etform 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. etform-0.17.0/LICENSE +7 -0
  2. etform-0.17.0/MANIFEST.in +6 -0
  3. etform-0.17.0/PKG-INFO +573 -0
  4. etform-0.17.0/README.md +552 -0
  5. etform-0.17.0/VERSION +1 -0
  6. etform-0.17.0/assets/logo.png +0 -0
  7. etform-0.17.0/etform/__init__.py +3 -0
  8. etform-0.17.0/etform/__init__.pyi +21 -0
  9. etform-0.17.0/etform/_etform.pyi +356 -0
  10. etform-0.17.0/etform/py.typed +1 -0
  11. etform-0.17.0/etform.egg-info/PKG-INFO +573 -0
  12. etform-0.17.0/etform.egg-info/SOURCES.txt +46 -0
  13. etform-0.17.0/etform.egg-info/dependency_links.txt +1 -0
  14. etform-0.17.0/etform.egg-info/top_level.txt +1 -0
  15. etform-0.17.0/examples/doc_demo.py +99 -0
  16. etform-0.17.0/examples/form_demo.py +252 -0
  17. etform-0.17.0/pyproject.toml +3 -0
  18. etform-0.17.0/setup.cfg +4 -0
  19. etform-0.17.0/setup.py +64 -0
  20. etform-0.17.0/src/braille_canvas.c +404 -0
  21. etform-0.17.0/src/braille_canvas.h +37 -0
  22. etform-0.17.0/src/dialogs.c +1283 -0
  23. etform-0.17.0/src/dialogs.h +19 -0
  24. etform-0.17.0/src/doc_object.c +736 -0
  25. etform-0.17.0/src/doc_object.h +98 -0
  26. etform-0.17.0/src/doc_runtime.c +968 -0
  27. etform-0.17.0/src/doc_runtime.h +8 -0
  28. etform-0.17.0/src/editor_theme.h +156 -0
  29. etform-0.17.0/src/etformmodule.c +147 -0
  30. etform-0.17.0/src/form_helpers.c +135 -0
  31. etform-0.17.0/src/form_helpers.h +20 -0
  32. etform-0.17.0/src/form_object.c +2673 -0
  33. etform-0.17.0/src/form_object.h +166 -0
  34. etform-0.17.0/src/form_runtime.c +2923 -0
  35. etform-0.17.0/src/form_runtime.h +39 -0
  36. etform-0.17.0/src/panel_manager.c +181 -0
  37. etform-0.17.0/src/panel_manager.h +41 -0
  38. etform-0.17.0/src/syntax_highlighter.c +478 -0
  39. etform-0.17.0/src/syntax_highlighter.h +55 -0
  40. etform-0.17.0/src/terminal_control.c +15 -0
  41. etform-0.17.0/src/terminal_control.h +6 -0
  42. etform-0.17.0/src/third_party/stb_image.h +7988 -0
  43. etform-0.17.0/src/ui_footer.c +118 -0
  44. etform-0.17.0/src/ui_footer.h +12 -0
  45. etform-0.17.0/src/ui_list.c +161 -0
  46. etform-0.17.0/src/ui_list.h +41 -0
  47. etform-0.17.0/src/ui_text.c +95 -0
  48. etform-0.17.0/src/ui_text.h +13 -0
etform-0.17.0/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ Copyright (c) 2026 Luke Canada
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4
+
5
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
+
7
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,6 @@
1
+ include VERSION
2
+ include README.md
3
+ include examples/form_demo.py
4
+ include examples/doc_demo.py
5
+ include assets/logo.png
6
+ recursive-include src *.h
etform-0.17.0/PKG-INFO ADDED
@@ -0,0 +1,573 @@
1
+ Metadata-Version: 2.4
2
+ Name: etform
3
+ Version: 0.17.0
4
+ Summary: Native ncurses forms and read-only terminal documents
5
+ Home-page: https://github.com/canadaluke888/TForm
6
+ Classifier: Operating System :: POSIX :: Linux
7
+ Classifier: Programming Language :: C
8
+ Classifier: Programming Language :: Python :: 3 :: Only
9
+ Classifier: Programming Language :: Python :: Implementation :: CPython
10
+ Classifier: Topic :: Software Development :: User Interfaces
11
+ Requires-Python: >=3.11
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Dynamic: classifier
15
+ Dynamic: description
16
+ Dynamic: description-content-type
17
+ Dynamic: home-page
18
+ Dynamic: license-file
19
+ Dynamic: requires-python
20
+ Dynamic: summary
21
+
22
+ # ETForm
23
+
24
+ ETForm is a Python framework for building native terminal forms and read-only
25
+ documents with an ncurses interface. Forms collect structured input. Documents
26
+ render hierarchical manuals, project notes, and other ordered terminal content.
27
+
28
+ The public API is intentionally small: create a `Form` to collect values or a
29
+ `Doc` to render read-only content, add items in display order, then call `run()`.
30
+ ETForm handles terminal rendering, navigation, scrolling, and reusable styled
31
+ display objects.
32
+
33
+ ## Features
34
+
35
+ - Native ncurses UI implemented as a CPython extension.
36
+ - Text, boolean, choice, checkbox, integer, and list inputs.
37
+ - Static sections, text blocks, separators, and tables for grouping larger forms.
38
+ - Styled text with alignment, color, bold, italicized, dim, underline, blink,
39
+ strikethrough, and wrapping attributes.
40
+ - Inline text editing with cursor movement and clipboard paste.
41
+ - Scrollable integer fields with optional `min` and `max` bounds.
42
+ - File, calendar, and clock picker tools for text and list fields.
43
+ - Static Unicode Braille canvases for compact terminal graphics.
44
+ - Hierarchical read-only documents with headings, paragraphs, code blocks,
45
+ reusable display objects, margins, boxes, and scrolling.
46
+ - Typed package metadata through `py.typed` and `.pyi` stubs.
47
+
48
+ ## Install
49
+
50
+ The distribution and Python import are both named `etform`. Once published to
51
+ PyPI, install it with:
52
+
53
+ ```bash
54
+ python3 -m pip install etform
55
+ ```
56
+
57
+ The planned prebuilt wheels target CPython 3.11-3.14 on glibc-based Linux
58
+ x86-64 (manylinux_2_28, requiring glibc 2.28 or newer). Other Linux systems may
59
+ need to build from source. Windows is not
60
+ supported; macOS builds have not been tested. Python 3.11 or newer is required.
61
+
62
+ To build from source, ETForm needs a C compiler, Python development headers,
63
+ wide-character ncurses, and the panel library.
64
+
65
+ On Debian or Ubuntu:
66
+
67
+ ```bash
68
+ sudo apt update
69
+ sudo apt install python3-dev build-essential libncurses-dev
70
+ ```
71
+
72
+ From a source checkout:
73
+
74
+ ```bash
75
+ python3 -m pip install .
76
+ ```
77
+
78
+ For editable development:
79
+
80
+ ```bash
81
+ python3 -m pip install -e .
82
+ ```
83
+
84
+ Clipboard paste uses `xclip` when available. Running the interface requires an
85
+ interactive terminal with a suitable terminfo database.
86
+
87
+ ## Publishing
88
+
89
+ The package has not been published by this repository's workflow until a
90
+ maintainer configures PyPI and publishes a release. Create the `etform` project
91
+ or a pending trusted publisher on PyPI for repository `canadaluke888/TForm`,
92
+ workflow `package.yml`, and environment `pypi`. Review the project's licensing
93
+ and the licenses of bundled native dependencies before distributing it.
94
+
95
+ Update `VERSION`, then create and publish a GitHub release tagged with `v`
96
+ followed by that version (for example, `v0.17.0`). The packaging workflow builds
97
+ the source distribution and Linux wheels, tests the wheels, and publishes them
98
+ through PyPI Trusted Publishing. Each PyPI version can only be uploaded once.
99
+ The workflow also builds downloadable artifacts on pushes, pull requests, and
100
+ manual runs without publishing them. PyPI names are claimed on first upload.
101
+
102
+ ## Quick Start
103
+
104
+ ```python
105
+ from etform import BrailleCanvas, Calendar, Clock, FilePicker, Form, Image, Table, Text
106
+
107
+
108
+ form = Form(title="Project Setup")
109
+ commands = Table(
110
+ title=Text("Commands", align="center", bold=True, color="yellow"),
111
+ color="cyan",
112
+ )
113
+ commands.add_column("Command")
114
+ commands.add_column("Default")
115
+ commands.add_row("Build", "python3 setup.py build_ext --inplace")
116
+ commands.add_row("Demo", "python3 examples/form_demo.py")
117
+
118
+ form.add_section(
119
+ Text("Create a project configuration.", color="cyan", bold=True),
120
+ commands,
121
+ boxed=True,
122
+ )
123
+
124
+ form.add_text_input(
125
+ key="name",
126
+ label=Text("Project Name", color="cyan", bold=True),
127
+ description="The display name for this project.",
128
+ )
129
+
130
+ form.add_int_input(
131
+ key="workers",
132
+ label="Workers",
133
+ default=4,
134
+ min=1,
135
+ max=32,
136
+ scrollable=True,
137
+ description="Number of worker processes.",
138
+ )
139
+
140
+ form.add_choice_input(
141
+ key="environment",
142
+ label="Environment",
143
+ choices=["Development", "Staging", "Production"],
144
+ default="Development",
145
+ )
146
+
147
+ form.add_checkbox_input(
148
+ key="features",
149
+ label="Features",
150
+ options=["Logging", "Metrics", "Tracing"],
151
+ default=["Logging"],
152
+ )
153
+
154
+ form.add_text_input(
155
+ key="config_path",
156
+ label="Config File",
157
+ tools=FilePicker(mode="file", start_dir="."),
158
+ )
159
+
160
+ form.add_text_input(
161
+ key="release_date",
162
+ label="Release Date",
163
+ tools=Calendar(),
164
+ )
165
+
166
+ form.add_text_input(
167
+ key="release_time",
168
+ label="Release Time",
169
+ tools=Clock(format="12h", include_seconds=True),
170
+ )
171
+
172
+ values = form.run()
173
+ if values is None:
174
+ print("Canceled")
175
+ else:
176
+ print(values)
177
+ ```
178
+
179
+ Run the included demo from the repository root:
180
+
181
+ ```bash
182
+ python3 examples/form_demo.py
183
+ ```
184
+
185
+ Run the separate document demo with:
186
+
187
+ ```bash
188
+ python3 examples/doc_demo.py
189
+ ```
190
+
191
+ ## Core API
192
+
193
+ Import the framework objects from `etform`:
194
+
195
+ ```python
196
+ from etform import BrailleCanvas, Calendar, Clock, CodeBlock, Doc, FilePicker, Form, Group, Image, OrderedList, Paragraph, Table, Text, UnorderedList
197
+ ```
198
+
199
+ ### `Doc`
200
+
201
+ `Doc` is the read-only counterpart to `Form`. It renders static document items
202
+ vertically in the order passed to `Doc.add()` and supports line scrolling, page
203
+ scrolling, and Home/End navigation. Margins reduce the document viewport without
204
+ introducing coordinate placement.
205
+
206
+ ```python
207
+ from etform import CodeBlock, Doc, Group, OrderedList, Paragraph, Text, UnorderedList
208
+
209
+ doc = Doc(
210
+ title="Project Notes",
211
+ margin_x=4,
212
+ syntax_highlight=True,
213
+ show_border=True,
214
+ )
215
+
216
+ doc.add(
217
+ Text("Project Notes", align="center", bold=True, color="cyan"),
218
+ Paragraph(
219
+ "ETForm documents support ",
220
+ Text("inline styled text", color="yellow", bold=True),
221
+ " without a markup parser.",
222
+ ),
223
+ UnorderedList(
224
+ "Plain strings become paragraph-style list items",
225
+ Paragraph("Use ", Text("Text", color="cyan"), " for inline spans."),
226
+ OrderedList("Nested ordered item"),
227
+ ),
228
+ CodeBlock(
229
+ code="print('hello from ETForm docs')",
230
+ lang="python",
231
+ ),
232
+ )
233
+
234
+ controls = Group("Controls", boxed=True)
235
+ controls.add(
236
+ Paragraph("Use Up and Down to scroll one line at a time."),
237
+ Paragraph("Press Q or Escape to close the document."),
238
+ )
239
+ doc.add(controls)
240
+ doc.run()
241
+ ```
242
+
243
+ The page border uses the document margins as its outer boundaries and scrolls
244
+ with the document. Its bottom edge is rendered at the actual end of the
245
+ document rather than at the bottom of the viewport. Disable it with
246
+ `show_border=False`.
247
+
248
+ `Doc.add()` accepts `str`, `Text`, `Paragraph`, `Group`, `Table`,
249
+ `CodeBlock`, `BrailleCanvas`, `Image`, `OrderedList`, and `UnorderedList`, and
250
+ returns the document for chaining. Plain strings and standalone `Text` objects
251
+ are converted to paragraph-style blocks internally. `Paragraph` is the
252
+ block-level container for mixed inline runs; `Text` remains the styled inline
253
+ unit. `OrderedList` and `UnorderedList` are static document renderables and are
254
+ separate from `Form.add_list_input()`.
255
+
256
+ `Group(label, boxed=False, padding=1)` groups normal document items together.
257
+ It accepts the same renderables through `Group.add()` and can be added with
258
+ `Doc.add(group)`. Code blocks preserve indentation and clip safely at the right
259
+ margin. When `syntax_highlight=True`, recognized `CodeBlock.lang` values such
260
+ as `"python"`, `"c"`, `"javascript"`, `"json"`, and `"shell"` receive
261
+ token-based syntax colors. Set it to `False` to render code as plain text.
262
+ Press Q or Escape to exit.
263
+
264
+ ### `Form`
265
+
266
+ `Form(title: str)` creates a form screen. Add fields in the order they should
267
+ appear, then call `run()`.
268
+
269
+ `run()` returns a `dict[str, Any]` when the user saves the form, or `None` when
270
+ the user exits without saving. Static sections, tables, text sections, and
271
+ separators are visual only and are not included in the returned dictionary.
272
+ When static content is taller than the viewport, Up/Down scroll through it in
273
+ steps without selecting a field. Page Up/Page Down move by larger viewport
274
+ steps, and Home/End jump to the document boundaries. Field selection resumes
275
+ when the pending field reaches the visible viewport.
276
+
277
+ ### `Text`
278
+
279
+ `Text` styles labels, section text, separator labels, and checkbox/list option
280
+ labels.
281
+
282
+ ```python
283
+ Text(
284
+ "Workspace",
285
+ align="center",
286
+ bold=True,
287
+ italicized=True,
288
+ underline=True,
289
+ color="cyan",
290
+ wrap_text=True,
291
+ )
292
+ ```
293
+
294
+ Supported alignments are `left`, `center`, and `right`. Supported colors are
295
+ `default`, `white`, `cyan`, `yellow`, `green`, `blue`, `magenta`, and `red`.
296
+ Text styling is used by labels, section text, separator labels, table titles,
297
+ checkbox/list option labels, and text input placeholders. `dim`, `underline`,
298
+ and `blink` map to standard curses attributes. `strikethrough` is exposed as a
299
+ style flag and renders when the active curses implementation provides a
300
+ strikeout attribute.
301
+
302
+ ### `FilePicker`
303
+
304
+ `FilePicker(mode="file", start_dir=".")` attaches a file or directory browser to
305
+ a compatible field.
306
+
307
+ ```python
308
+ FilePicker(mode="directory", start_dir=".")
309
+ ```
310
+
311
+ Supported modes are `file` and `directory`.
312
+
313
+ ### `Calendar`
314
+
315
+ `Calendar()` attaches an interactive date picker to text and list fields. It
316
+ opens anywhere text input is needed, uses the current `YYYY-MM-DD` value when
317
+ available, and returns a valid `YYYY-MM-DD` date string.
318
+
319
+ ```python
320
+ form.add_text_input(
321
+ key="release_date",
322
+ label="Release Date",
323
+ tools=Calendar(),
324
+ )
325
+ ```
326
+
327
+ ### `Clock`
328
+
329
+ `Clock(format="24h", include_seconds=False)` attaches a live digital and Braille
330
+ analog time picker to text and list fields. It returns `HH:MM[:SS]` in 24-hour
331
+ mode or `hh:MM[:SS] AM/PM` in 12-hour mode.
332
+
333
+ ```python
334
+ form.add_text_input(
335
+ key="release_time",
336
+ label="Release Time",
337
+ tools=Clock(format="12h", include_seconds=True),
338
+ )
339
+ ```
340
+
341
+ ### `BrailleCanvas`
342
+
343
+ `BrailleCanvas(width, height, color="default", padding=1)` stores a 2x4-dot
344
+ Unicode Braille raster per terminal cell. Draw with dot coordinates, then pass
345
+ the canvas to `add_section()`; the form stores a static copy.
346
+
347
+ ```python
348
+ canvas = BrailleCanvas(24, 8, color="cyan")
349
+ canvas.draw_circle(canvas.dot_width // 2, canvas.dot_height // 2, 12)
350
+ canvas.draw_line(0, 0, canvas.dot_width - 1, canvas.dot_height - 1)
351
+ canvas.draw_image("logo.png")
352
+ form.add_section(canvas, boxed=True)
353
+ ```
354
+
355
+ `draw_image(path)` accepts image formats supported by `stb_image`, including
356
+ PNG, JPEG, BMP, GIF, TGA, PSD, HDR, PIC, and PNM. The image is aspect-fitted
357
+ and centered in the Braille dot grid. Transparent pixels are composited over
358
+ white. Luminance dithering varies Braille dot density to preserve shading,
359
+ highlights, and reflections instead of applying a single hard threshold. On
360
+ 256-color terminals each Braille cell uses the nearest xterm color from the
361
+ source image; 8-color and monochrome terminals use the canvas's configured
362
+ fallback color. Since one Braille character has one foreground color, all
363
+ raised dots within the same 2x4 cell share that color. Drawing overlays existing
364
+ canvas content; call `clear()` first when replacement is desired.
365
+
366
+ ### `Image`
367
+
368
+ `Image` is the portable, image-focused section API. It decodes once when the
369
+ object is created and renders through Unicode Braille, so it works without
370
+ Kitty, Sixel, or other terminal-specific graphics protocols.
371
+
372
+ ```python
373
+ image = Image(
374
+ "logo.png",
375
+ width=48,
376
+ color="cyan",
377
+ padding=1,
378
+ )
379
+ form.add_section(image, boxed=True)
380
+ ```
381
+
382
+ `width` controls the terminal-cell resolution. When `height=None`, the height
383
+ is derived from the source aspect ratio in Braille's 2x4 dot coordinate space.
384
+ Pass an explicit height to constrain the image to a fixed section area. Images
385
+ use 256-color cells when available and retain the configured `color` as the
386
+ 8-color or monochrome fallback.
387
+
388
+ ### `Table`
389
+
390
+ `Table` renders static tabular content inside `Doc.add()` or `Form.add_section()`.
391
+
392
+ ```python
393
+ table = Table(
394
+ title=Text("Command Defaults", align="center", bold=True, color="yellow"),
395
+ color="cyan",
396
+ )
397
+ table.add_column("Command")
398
+ table.add_column("Default")
399
+ table.add_row("Build", "python3 setup.py build_ext --inplace")
400
+ table.add_separator_row(Text("Validation", color="yellow", dim=True))
401
+ table.add_row("Demo", "python3 examples/form_demo.py")
402
+
403
+ form.add_section(Text("Developer Settings", color="cyan", bold=True), table, boxed=True)
404
+ ```
405
+
406
+ Rows must have the same number of cells as the table has columns. The table
407
+ title accepts `str` or `Text`, renders above the table, and is aligned within
408
+ the table bounds. Tables keep an outer border and a rule below the header by
409
+ default, while omitting body row and column grid lines. Set `show_lines=True`
410
+ to draw row and column grid lines for headers and normal rows. Separators are
411
+ always one full-width row without column dividers;
412
+ they are blank by default, accept a plain string for left-aligned unstyled text,
413
+ or accept `Text` for formatted and aligned separator text.
414
+
415
+ ## Field Types
416
+
417
+ ### Text Input
418
+
419
+ ```python
420
+ form.add_text_input(
421
+ key="project_name",
422
+ label="Project Name",
423
+ default="",
424
+ placeholder=Text("None", align="right", color="cyan", italicized=True),
425
+ description="Project display name.",
426
+ field_color="cyan",
427
+ )
428
+ ```
429
+
430
+ Text fields return strings. `placeholder` accepts `str` or `Text` and is
431
+ display-only ghost text shown when the field value is empty. `Text`
432
+ placeholders keep their alignment, color, bold, italicized, dim, underline,
433
+ blink, strikethrough, and wrapping attributes within the input box. `default` is
434
+ not rendered or inserted into the field; it is returned only when the user
435
+ leaves the field empty. When
436
+ `wrap_text=True`, the field can grow over multiple display lines and supports
437
+ vertical cursor movement while editing.
438
+
439
+ ### Boolean Input
440
+
441
+ ```python
442
+ form.add_bool_input(
443
+ key="enabled",
444
+ label="Enabled",
445
+ default=True,
446
+ )
447
+ ```
448
+
449
+ Boolean fields return `True` or `False`.
450
+
451
+ ### Choice Input
452
+
453
+ ```python
454
+ form.add_choice_input(
455
+ key="priority",
456
+ label="Priority",
457
+ choices=["Low", "Normal", "High"],
458
+ default="Normal",
459
+ )
460
+ ```
461
+
462
+ Choice fields return the selected string.
463
+
464
+ ### Checkbox Input
465
+
466
+ ```python
467
+ form.add_checkbox_input(
468
+ key="enabled_tools",
469
+ label="Enabled Tools",
470
+ options=["Formatter", "Linter", "Type Checker", "Test Runner"],
471
+ default=["Formatter", "Linter"],
472
+ tick="dot",
473
+ )
474
+ ```
475
+
476
+ Checkbox groups return a dictionary mapping each option label to `True` or
477
+ `False`. Supported tick styles are `x`, `block`, and `dot`.
478
+
479
+ ### Integer Input
480
+
481
+ ```python
482
+ form.add_int_input(
483
+ key="max_workers",
484
+ label="Max Workers",
485
+ default=8,
486
+ min=1,
487
+ max=64,
488
+ scrollable=True,
489
+ )
490
+ ```
491
+
492
+ Integer fields return Python integers. Scrollable integer fields can be adjusted
493
+ with the arrow keys and can enforce optional `min` and `max` bounds.
494
+
495
+ ### List Input
496
+
497
+ ```python
498
+ form.add_list_input(
499
+ key="environment_files",
500
+ label="Environment Files",
501
+ tools=FilePicker(mode="file", start_dir="."),
502
+ )
503
+ ```
504
+
505
+ List fields return `list[str]`. Without tools, users can add, edit, and delete
506
+ plain text entries. With a `FilePicker`, `Calendar`, or `Clock`, add and edit actions open
507
+ the attached tool.
508
+
509
+ ### Static Sections and Separators
510
+
511
+ ```python
512
+ form.add_section(
513
+ Text("Developer Settings", color="cyan", bold=True),
514
+ table,
515
+ boxed=True,
516
+ )
517
+ form.add_separator(Text("Build & Test", color="green"), color="yellow")
518
+ ```
519
+
520
+ Static sections accept `Text`, `Table`, and plain strings, then render them in
521
+ order. `add_text_section()` remains available for compatibility, but
522
+ `add_section()` is the preferred static-content API.
523
+
524
+ ## Controls
525
+
526
+ The footer shows context-sensitive controls while the form is running. The main
527
+ navigation controls are:
528
+
529
+ - `Up` / `Down`: move between fields.
530
+ - `Enter`: edit the selected field.
531
+ - `I`: show the selected field description.
532
+ - `Ctrl+S`: save and return the form values.
533
+ - `Q`: exit without saving and return `None`.
534
+
535
+ Text editing controls:
536
+
537
+ - `Left` / `Right`: move the cursor.
538
+ - `Home` / `End`: jump to the start or end of the text.
539
+ - `Delete` / `Backspace`: remove text.
540
+ - `Ctrl+V`: paste clipboard text.
541
+ - `Enter` or `Ctrl+E`: finish editing.
542
+ - `Esc`: clear the field and finish editing.
543
+
544
+ List editing controls:
545
+
546
+ - `A`: add an item.
547
+ - `E`: edit or replace the selected item.
548
+ - `D`: delete the selected item.
549
+ - `Ctrl+E` or `Esc`: leave list editing.
550
+
551
+ Checkbox controls:
552
+
553
+ - `Up` / `Down`: move between options.
554
+ - `Space` or `Enter`: toggle the selected option.
555
+ - `Ctrl+E` or `Esc`: leave checkbox editing.
556
+
557
+ File picker controls:
558
+
559
+ - `Up` / `Down`: move between entries.
560
+ - `Enter`: open a directory or choose a file.
561
+ - `B`: move back to the parent directory.
562
+ - `Ctrl+E`: choose the current directory in directory mode.
563
+ - `Esc`: close the picker.
564
+
565
+ ## Demo
566
+
567
+ The bundled developer settings demo exercises the major field types:
568
+
569
+ ```bash
570
+ python3 examples/form_demo.py
571
+ ```
572
+
573
+ When saved, it prints the returned form dictionary as JSON.