bump version to 1.4.0

It was supposed to be equal to JWIDGET_KEY, but was no longer since
constructors were de-prioritized by the new widget declaration systems,
non-deterministically, causing a lot of confusion.

CMakeLists.txt

@@ -1,8 +1,8 @@
 # Just UI
 
 cmake_minimum_required(VERSION 3.16)
-project(JustUI VERSION 1.3.0 LANGUAGES C)
-find_package(Gint 2.8 REQUIRED)
+project(JustUI VERSION 1.4.0 LANGUAGES C)
+find_package(Gint 2.11 REQUIRED)
 include(Fxconv)
 
 set(CMAKE_INSTALL_MESSAGE LAZY)

doc/changelogs.md

@@ -0,0 +1,139 @@
+# Changelog and migration guides
+
+## 1.4.0
+
+**Migration: event functions**
+
+The convention for event functions has changed to allow the removall of the "inheritance" property, which was clumsy in C and only useful for event functions.
+Now, instead of returning `false` for events that a widget is not interested in, the event function should explicitly forward the event to the "inherited" function, i.e. usually the one from jwidget, and the inheritance parameter to `j_register_widget()` must be removed. The lack of inheritance also removes the need to order constructors.
+
+```c
+//=== Before =================================================================//
+static bool mywidget_poly_event(void *w, jevent e) {
+    if(event_is_interesting(e)) { /* ... */ }
+    return false;
+}
+__attribute__((constructor(1020)))
+static void j_register_mywidget(void) {
+	mywidget_type_id = j_register_widget(&type_mywidget, "jwidget");
+	/* ... */
+}
+
+//=== After ==================================================================//
+static bool mywidget_poly_event(void *w, jevent e) {
+    if(event_is_interesting(e)) { /* ... */ }
+    return jwidget_poly_event(w, e); //< Forward to jwidget
+}
+__attribute__((constructor)) //< No priority needed
+static void j_register_mywidget(void) {
+	mywidget_type_id = j_register_widget(&type_mywidget); //< No inheritance
+	/* ... */
+}
+```
+
+The event function should not forward events to focused sub-widgets; `jscene` handles that. Emitting an event at the scene level already leads to multiple event function calls, starting at the focused widget, and bubbling up to parents along the way.
+
+**Migration: widget definitions**
+
+The widget definition system has been improved with macros. This change is optional but removes a lot of boilerplate.
+
+The macro `J_DEFINE_WIDGET(<NAME>, <FUNCTIONS>...)` defines a widget with the given `NAME` that implements the given poly-`FUNCTIONS`. This macro:
+- Defines `int NAME_type_id`, which is assigned automatically at startup in a constructor;
+- Uses `NAME_poly_FUN` for each `FUN` in the list of `FUNCTIONS`.
+
+For instance (see https://git.planet-casio.com/Lephenixnoir/JustUI/commit/626da6f378fd3763fe51dd9478f85d9f9ea4874c):
+
+```c
+//=== Macro version ==========================================================//
+#include <justui/jwidget-api.h>
+J_DEFINE_WIDGET(jpainted, csize, render)
+
+void jpainted_poly_csize(void *p) { /* ... */ }
+void jpainted_poly_render(void *p, int x, int y) { /* ... */ }
+
+//=== Equivalent to ==========================================================//
+static int jpainted_type_id = -1;
+
+void jpainted_poly_csize(void *p) { /* ... */ }
+void jpainted_poly_render(void *p, int x, int y) { /* ... */ }
+
+static jwidget_poly type_jpainted = {
+    .name    = "jpainted",
+    .csize   = jpainted_poly_csize,
+    .render  = jpainted_poly_render,
+};
+
+__attribute__((constructor))
+static void j_register_jpainted(void) {
+    jpainted_type_id = j_register_widget(&type_jpainted);
+}
+```
+
+**Migration: event definitions**
+
+To allow the complete removal of explicit constructor functions from widgets, events can also be defined by a macro.
+
+```c
+J_DEFINE_EVENTS(<NAMES>...)
+```
+
+This simply defines new variables `uint16_t NAME` for every `NAME` in the list of `NAMES` and registers them as events at startup with a constructor.
+
+**Migration: focus system**
+
+The focus system changed; see the [appropriate documentation](scene.md). The main changes are as follow.
+
+Any widget that wants to receive keyboard input must set a focus policy, typically fixed at creation. This is either `J_FOCUS_POLICY_ACCEPT` if the widget has no children or `J_FOCUS_POLICY_SCOPE` if the widget contains children that may themselves want to receive keyboard focus. In most cases this is all that needs to be done (example with `jlist`: https://git.planet-casio.com/Lephenixnoir/JustUI/commit/57a460894f1395bd2b789f32c922fbc61e231a66#diff-94b157d9507dee40d44c23076d92c5ceb0b427d4)
+
+```c
+mywidget *mywidget_create(void *parent)
+{
+    if(mywidget_type_id < 0) return NULL;
+
+    mywidget *w = malloc(sizeof *w);
+    if(!w) return NULL;
+
+    jwidget_init(&w->widget, mywidget_type_id, parent);
+    jwidget_set_focus_policy(w, J_FOCUS_POLICY_ACCEPT); //< Set policy
+    /* ... */
+}
+```
+
+The events `JWIDGET_FOCUS_IN` and `JWIDGET_FOCUS_OUT` are replaced with a general `JWIDGET_FOCUS_CHANGED` event encompassing their meaning (among other things). The handler for such an event can call `jwidget_has_focus()` (example with `jinput`: https://git.planet-casio.com/Lephenixnoir/JustUI/commit/57a460894f1395bd2b789f32c922fbc61e231a66#diff-492b1daa1b4361eb231c82b4b1fca013601eb54c).
+
+**Breaking features and major features**
+
+* Rework widget focus model https://git.planet-casio.com/Lephenixnoir/JustUI/commit/57a460894f1395bd2b789f32c922fbc61e231a66 https://git.planet-casio.com/Lephenixnoir/JustUI/commit/7a5101360a86bc0d7d28e7a26f460fcea5f80dea
+  - Widgets that want keyboard input must now specify a focus policy at creation
+  - The events `JWIDGET_FOCUS_IN` and `JWIDGET_FOCUS_OUT` are replaced with a general `JWIDGET_FOCUS_CHANGED`
+  - This also removes `JSCENE_KEY` in favor of `JWIDGET_KEY`, which were supposed to be the same but weren't, leading to confusing bugs https://git.planet-casio.com/Lephenixnoir/JustUI/commit/23294b77ac945ac35a2b9571e778f8193fd6f4de
+* Replace widget definition process https://git.planet-casio.com/Lephenixnoir/JustUI/commit/216918123fc484793bef2e9d6072b13e129fa655 https://git.planet-casio.com/Lephenixnoir/JustUI/commit/683e89d7257d5d303071f9c63e238c8bb11400a9 https://git.planet-casio.com/Lephenixnoir/JustUI/commit/626da6f378fd3763fe51dd9478f85d9f9ea4874c
+  - This removes the inheritance property
+  - This modifies the convention for event handling functions, which should now default to `jwidget_poly_event()` https://git.planet-casio.com/Lephenixnoir/JustUI/commit/683e89d7257d5d303071f9c63e238c8bb11400a9 https://git.planet-casio.com/Lephenixnoir/JustUI/commit/93eb0df38aab9ebf1f71a4f27a53ba2039ed946d
+  - Results in much less boilerplate
+* fx-CP 400 build and basic compatibility (no touch input yet) https://git.planet-casio.com/Lephenixnoir/JustUI/commit/5b092a5a4ec2a74337ef6a98ccb4da3f658ab738 with correctly-sizes (but barely usable) F-keys https://git.planet-casio.com/Lephenixnoir/JustUI/commit/e12a58c1f0cd48cc1abd14630e4d44152e810948s
+* WIP: Denotational UIs still a work-in-progress.
+
+**Minor improvemements**
+
+* `jfileselect`: Now displays "(No entries)" for empty folders https://git.planet-casio.com/Lephenixnoir/JustUI/commit/4c44b3e413e81ad443e02d2d136efd3207ffcb54 and error values when a filesystem error occurs https://git.planet-casio.com/Lephenixnoir/JustUI/commit/bea113f09e33fea6e9cb91a78a15a93b8c4842aa
+* `jscene`: Now turns off with SHIFT+AC/ON, with option to disable https://git.planet-casio.com/Lephenixnoir/JustUI/commit/ef71bc11c0634fc575164e40bfe4afa6688c3fd9 https://git.planet-casio.com/Lephenixnoir/JustUI/commit/0c8371edceb768de6077f0fef2e2deaa912d2e8c
+* `jscene`: Autopaint option https://git.planet-casio.com/Lephenixnoir/JustUI/commit/7f2131d6a03af4930dc85a3900a537940d4689cc
+* `jscene`: Defaults to vbox layout instead of no layout https://git.planet-casio.com/Lephenixnoir/JustUI/commit/a2129f1ed208f5e982ae822e230e46a4b7406756
+* `jinput`: Add function to customize keymap https://git.planet-casio.com/Lephenixnoir/JustUI/commit/0e5ccf4cc3723f47d592cf0ba2375edd954c24ad
+* `jlabel`: Now recognizes the `font_t` property `line_distance` for inter-line spacing https://git.planet-casio.com/Lephenixnoir/JustUI/commit/33e99622096b892ae8406b160d19908e82f854cb
+* `jlabel`: Defaults to top alignment https://git.planet-casio.com/Lephenixnoir/JustUI/commit/4728c6ecbe4c1fcfcd11fbab15078bf51828f384
+* `jlabel`: No longer gobbles spaces after line breaks if the break is caused by an explicit `\n` https://git.planet-casio.com/Lephenixnoir/JustUI/commit/4728c6ecbe4c1fcfcd11fbab15078bf51828f384
+* `jlist`: More fluid user code with default selection https://git.planet-casio.com/Lephenixnoir/JustUI/commit/3488c6515ab1d4f4c664b353362a82aa328decc9, info values https://git.planet-casio.com/Lephenixnoir/JustUI/commit/12b29f8223e91753250ad5e64a730e8c7ff2db19, and a user data pointer for rendering https://git.planet-casio.com/Lephenixnoir/JustUI/commit/7587dfa17cdc643881a3048a0935abe2f31d2936
+* `jevent`: Provide functions for identifying key events (still looking for a good design there) https://git.planet-casio.com/Lephenixnoir/JustUI/commit/7b8070f02c01f8eb74487c4e61acf98f5b076cfc
+* `jfkeys`: Now returns events instead of leaving keys F1...F6 pass through. This requires jfkeys to get key events, which needs support from the scene (in gintctl, gscreen handles it). https://git.planet-casio.com/Lephenixnoir/JustUI/commit/f28d7a9cb8e9a1249e761a7b97e2e6f5e9faa6b5
+* Optimization: turn on LTO https://git.planet-casio.com/Lephenixnoir/JustUI/commit/5a885b541f7aad3dfcc76f522d4deec274cc91e4
+* Optimization: full-screen widget with background (usually `jscene`) now renders with `dclear()` https://git.planet-casio.com/Lephenixnoir/JustUI/commit/f32dcc69ce9055606d8efff97150fed291ceadb5
+
+**Fixes**
+
+* Compatibility: less FX vs. CG hardcoding https://git.planet-casio.com/Lephenixnoir/JustUI/commit/e324f9a3a281d9ce29bb6d4953ba39763b52dbed
+* `jframe`: Fix crash with NULL child https://git.planet-casio.com/Lephenixnoir/JustUI/commit/5e2488cdf4ac73761bc11612b10a37d0375e5ba9
+* `jscene`: Interrupt-safe access to event queue https://git.planet-casio.com/Lephenixnoir/JustUI/commit/550c08e200fd6479e51d1afc7f625657a659d9db
+* `jlist`, `jscrolledlist`: Fix parent not being last parameter https://git.planet-casio.com/Lephenixnoir/JustUI/commit/ba7b0a02d0701bd564294456452b897251bb2768
+* Add checks to avoid the compiler inserting certain `abort()` calls https://git.planet-casio.com/Lephenixnoir/JustUI/commit/4d6b760b1ae6744332ce929321c6b0d0ea2b8f30

doc/scene.md

@@ -4,105 +4,121 @@
 
 The _scene_ in JustUI is the component sitting at the root of the widget hierarchy. It handles all the dynamic aspects of the UI, including distributing/propagating events and managing keyboard focus among the widgets.
 
-Ideas...
+TODO...
 
-New keyboard focus system.
-1. Principle and conforming states
-   a. Widgets have a focus policy of FOCUS_ACCEPT, FOCUS_SCOPE or FOCUS_REJECT,
-      and two status flags FOCUSED and ACTIVE_FOCUSED whose valid combinations
-      describe 3 focus levels: *no focus* (F=0), *inactive focus* (F=1, AF=0),
-      and *active focus* (F=1, AF=1).
-   b. Each focus scope defines a region consisting of its subtree but excluding
-      itself and any children of other focus scopes. Up to one widget of policy
-      FOCUS_ACCEPT or FOCUS_SCOPE in the region may have its FOCUSED flag set,
-      called the *focus target* of the scope. The ACTIVE_FOCUSED flag of the
-      target is equal to the scope's.
-   c. Every focus scope fs induces a *focus chain* fc(fs), where
-        fc(w) = [] if w is FOCUS_ACCEPT or w is FOCUS_SCOPE with no target;
-        fc(w) = fc(target) + [target] if w is a scope with the named target.
-      Note that as a result of 1.b all elements of the chain have their FOCUSED
-      flag set and their ACTIVE_FOCUSED flags equal to that of fs.
-   d. jscene is a focus scope defined to have its ACTIVE_FOCUSED always set,
-      the only such widget that doesn't inherit this flag from a scope parent.
-      As such, the ACTIVE_FOCUSED flag identifies the focus chain of the scene.
-      jscene offers keyboard events to its focus chain, propagating rejected
-      events in list order.
-   X. The first (deepest) widget in the scene's focus chain is said to have
-      *strong focus*. Other widgets this chain are said to have *weak focus*.
-      -> TODO: Strong/weak focus is an informal substate of active focus and
-         may not be kept in the future.
-2. Operations
-   a. The core operation is a changing the target of a scope, which can be
-      initiated by any widget in the region through a widget-context call. The
-      consequences of this operation are as follow:
-      - The old target, if any, loses its FOCUSED and ACTIVE_FOCUSED flags. If
-        it's a scope and it had active focus, all widgets in its focus chain
-        also lose active focus.
-      - The new target, if any, gets its FOCUSED flag and the scope's value for
-        the ACTIVE_FOCUSED flag. If it's a focus scope and it gets active
-        focus, then its focus chain also gets active focus.
-      All widgets affected receive a FOCUS_CHANGED event and the scope itself
-      receives a FOCUS_TARGET_CHANGED event.
-   b. There is a widget-scene call to give a widget active focus. If the widget
-      has policy FOCUS_ACCEPT or FOCUS_SCOPE, this call walks up the scope
-      chain and assigns new targets until it reaches the scene. If the widget
-      has is NULL, this call just removes the surrounding scope's target.
-      TODO: If the widget is FOCUS_REJECT, clear scopes from that widget up
-            until reaching the scene.
-   X. There is a widget-context call to relinquish one's own focus within the
-      parent scope. This is intended to differ from 2.b in that scopes might
-      implement special logic for moving focus to a nearby widget.
-      -> TODO: Left unresolved for later
-3. Key-listener pattern
-   a. The operations described in 2.a and 2.b allow a "key-listener" pattern
-      where a widget "klw" (not the scene) receives keyboard events from its
-      potentially-focused descendants (i.e. inserts itself in the focus chain)
-      without impacting the focus mechanics of its surrounding scope "ssw".
-   b. The pattern consists of making klw a focus scope, and whenever it
-      receives a FOCUS_TARGET_CHANGED event that assigns a target, make klw
-      grab focus within ssw. This way, with regards to ssw, when focus moves:
-      - From within klw to within klw:
-          the grab is a no-op: OK.
-      - From within klw to outside it:
-          outside widget gets focus within ssw and klw does nothing: OK.
-      - From outside klw to within it:
-          inside widget gets focus in klw, klw gets focus in ssw: OK.
-      - From outside klw to outside it:
-          normal retargeting within ssw.
-   X. Should this be a built-in behavior?
+## Keyboard focus system
 
-4. Behavior of built-in widgets
-   a. `jfileselect`, `jinput`, `jlist` have policy FOCUS_ACCEPT
-   b. `jscene` has policy FOCUS_SCOPE
-   c. `jfkeys` has policy `FOCUS_REJECT` and must be given events manually
-   d. Widgets with a stack layout will try and give focus (within their
-      surrounding scope) to the current element. If the element is complex, it
-      should be a focus scope. Similarly, widgets with invisible children will
-      move focus around to their direct children as needed to make sure focus
-      remains on a visible child.
-      TODO: Implement stack layout logic
+### Principles: focus policies, focused widgets and active-focus widgets
 
-5. Implementation
-   a. Events are `FOCUS_CHANGED` when own FOCUSED and ACTIVE_FOCUSED flags have
-      changed, and `FOCUS_TARGET_CHANGED` for scopes when the target changes.
+Every widget has a focus policy, which can be:
+* `J_FOCUS_POLICY_REJECT`: The widget does not receive keyboard input and is ignored for the purposes of input handling (its children are not ignored though). This is the default and is usually overridden at creation by `jwidget_set_focus_policy()`.
+* `J_FOCUS_POLICY_ACCEPT`: The widget receives keyboard input and keeps it to itself, not allowing any children to get it. Children will not see any events unless the widget's event function decides to forward them.
+* `J_FOCUS_POLICY_SCOPE`: The widget can receive focus but also allows a child to get focus. In this case, events that the child is not interested in will be offered to the scope widget.
 
-NOTES:
-- Update focus flags when removing from parent
-- Focus events don't propagate but are replicated, which adds some complexity
-- Focus scopes could have background focus for jfkeys (left for later). Hard
-  part is this isn't specified by jfkeys.
-  Could tell users to add this to their main loop, or follow gscreen:
-    jevent e = jscene_run();
-    if(jwidget_event(fkeys, e)) continue;
-- Is there any sensible definition to "relinquishing" focus? In gintctl if e.g.
-  an jinput validates we want to take its focus away and put it back somewhere
-  sensible (i.e. the gscreen, not NULL, otherwise we don't have F-keys anymore)
-- Some functions from <jwidget-api.h> should go to <jwidget.h>
-- Functions from <jwidget.h> that require context or operate on the whole tree
-  should **really** be identified clearly. Everything by default should just
-  treat the widget as a box in a void.
-  -> Previously this was in jscene. Why not keep it that way?
+Additionally, widgets have three focus states defined by two status flags `FOCUSED` and `ACTIVE_FOCUSED`:
 
-## Keyboard focus and event propagation
+* No focus - `FOCUSED=0`
+* Inactive focus - `FOCUSED=1`, `ACTIVE_FOCUSED=0`
+* Active focus - `FOCUSED=1`, `ACTIVE_FOCUSED=1`
 
-TODO.
+Roughly speaking, active focus means the widget currently receives input, whereas inactive focus means the widget has focus within a parent that is inactive. For instance, an input field within a tab that is currently invisible would have inactive focus. If the tab becomes visible, the input field gets active focus. Inactive focus essentially remembers who had focus while certain parts of the interface are not being used.
+
+Each widget w with the `SCOPE` policy defines a region called a *focus scope*, which is essentially the widgets whose focus is managed by w. This region consists of w's subtree, excluding w itself and any children of other focus scopes.
+
+The fact that w can transmit its focus to a child is formalized as follows. Within the scope, up to one widget with policy `ACCEPT` or `SCOPE` can have its `FOCUSED` flag set and this widget is called the *focus target* of the scope. The focus target has the same value for the `ACTIVE_FOCUSED` flag as w.
+
+If the focus target is also a scope, it may itself have a target. Thus, each scope induces a *focus chain* FC, defined mathematically by
+
+* `FC(w) = []` if w is not a scope or has no target;
+* `FC(w) = FC(target) + [target]` if w is a scope with the given target.
+
+The elements of the chain are exactly the children of w that have their `FOCUSED` flag set, and they all have the same value for `ACTIVE_FOCUSED` as w.
+
+`jscene`, where focus originates, is a scope and is defined to have its `ACTIVE_FOCUSED` flag set at all times (the only widget that doesn't inherit this flag from a scope parent).  Thus, the `ACTIVE_FOCUSED` flag identifies the focus chain of the scene. When given an event, `jscene` offers it to all of the elements of its focus chain, starting from the deepest children and then to the parents, until one accepts the event.
+
+TODO: Diagram! It's not straightforward.
+
+Related functions:
+
+```c
+// Set the focus policy of a widget (usually when created, possible anytime)
+void jwidget_set_focus_policy(void *w, jwidget_focus_policy_t fp);
+// Check if a widget has any (inactive or active) focus
+bool jwidget_has_focus(void *w);
+// Check if a widget has active focus, i.e., receives keyboard events right now
+bool jwidget_has_active_focus(void *w);
+```
+
+### Operations
+
+**Changing the target of a scope**
+
+Focus can moved by changing the target of a scope. When this happens:
+
+- The old target, if any, loses its `FOCUSED` and `ACTIVE_FOCUSED` flags. If it's a scope and it had active focus, all widgets in its focus chain also lose active focus.
+- The new target, if any, gets its `FOCUSED` flag and the scope's value for the `ACTIVE_FOCUSED` flag. If it's a focus scope and it gets active focus, then its focus chain also gets active focus.
+
+All widgets affected receive a `JWIDGET_FOCUS_CHANGED` event and the scope itself receives a `JWIDGET_FOCUS_TARGET_CHANGED` event.
+
+```c
+// Set the target of a focus scope.
+void jwidget_scope_set_target(void *fs, void *target);
+// Get the current target of a focus scope (may be NULL).
+jwidget *jwidget_scope_get_target(void *fs);
+// Remove the current target (same as setting NULL).
+void jwidget_scope_clear_focus(void *fs);
+```
+
+**Giving a widget active focus**
+
+There is a scene function to give a widget active focus.
+- If the widget has policy `ACCEPT` or `SCOPE`, this function gives active focus to all of its sopce ancestors until it reaches the scene.
+- If the widget is `NULL`, this call just removes the surrounding scope's target.
+- [TODO] If the widget has policy `REJECT`, it clears scopes from that widget up until reaching the scene.
+
+**Relinquishing focus**
+
+[TODO] It is intended that there by a widget-context function to relinquish one's own focus within the parent scope. This is intended to allow scopes to implement special logic for moving focus to a nearby widget automatically.
+
+**Widget-context and global scene functions**
+
+Most functions on widgets ignore the widget's surroundings, such as its parents (or lack thereof). Widget-context functions are all the functions on widgets that *do* depend on the widget's surroundings.
+
+```c
+// Widget's enclosing scope (may be NULL, but not if there's a jscene).
+jwidget *jwidgetctx_enclosing_focus_scope(void *w);
+// Grab focus for w within enclosing scope.
+void jwidgetctx_grab_focus(void *w);
+// Drop focus from w (if it has it) within enclosing scope.
+void jwidgetctx_drop_focus(void *w);
+```
+
+Additionally, a few global functions are available at the scene level. If you're not sure how to proceed: `jscene_show_and_focus(w)` is the easy way to give focus to a widget `w` and it will do what you want most of the time.
+
+```c
+// Widget at the end of the focus chain of the scene.
+void *jscene_focused_widget(jscene *scene);
+// Active-focus the given widget and all its enclosing scopes.
+void jscene_set_focused_widget(jscene *scene, void *widget);
+// Active-focus the given widget and make sure it's visible.
+void jscene_show_and_focus(jscene *scene, void *widget);
+```
+
+### Key-listener pattern
+
+The operations described above allow a "key-listener" pattern where a widget KL (not the scene) receives keyboard events from its potentially-focused descendants (i.e. inserts itself in the focus chain) without impacting the focus mechanics of its surrounding scope SS.
+
+The pattern consists of making KL a focus scope, and whenever it receives a `FOCUS_TARGET_CHANGED` event that assigns a target, make KL grab focus within SS. This way, with regards to SS, when focus moves:
+* From within KL to within KL: the grab is a no-op: OK.
+* From within KL to outside it: outside widget gets focus within SS and KL does nothing: OK.
+* From outside KL to within it: inside widget gets focus in KL, KL gets focus in SS: OK.
+* From outside KL to outside it: KL is not involved: OK.
+
+[TODO] Should this be a built-in behavior?
+
+## Behavior of built-in widgets
+
+- `jfileselect`, `jinput`, `jlist` have policy `ACCEPT`
+- `jscene`, `jscrolledlist` have policy `SCOPE`
+- `jfkeys` has policy `REJECT` and must be given events manually (awkward)
+- [TODO] Widgets with a stack layout will try and give focus (within their surrounding scope) to the current element. If the element is complex, it should be a focus scope. Similarly, widgets with invisible children will move focus around to their direct children as needed to make sure focus remains on a visible child.

doc/widgets.md

@@ -21,15 +21,15 @@ compromise to work with polymorphic types in the C type system.
 and layout](layout.md)) and size constraints, geometry (margin, border,
 padding, background), and automatic repaint/relayout mechanisms.
 
-**`jlabel`** is a content widget that shows a single-line or multi-line piece
-of text. It supports various text alignment options (left/right/center), line
-wrapping (letter and word level), and a couple of graphical options.
-
 **`jscene`** is a special widget designed to be at the root of the widget tree.
 It provides event dispatching, automatic repaint and layout, keyboard input,
 and a generic input loop that is suitable for most GUI programs. See [Scenes
 and events](scene.md).
 
+**`jlabel`** is a content widget that shows a single-line or multi-line piece
+of text. It supports various text alignment options (left/right/center), line
+wrapping (letter and word level), and a couple of graphical options.
+
 **`jinput`** is a one-line input field. It supports direct key input, delayed
 and instant SHIFT and ALPHA modifiers, as well as modifier locking, with visual
 hints.
@@ -44,6 +44,20 @@ screen. On fx-9860G, it uses an image to show keys; on fx-CG 50, it supports a
 string specification that looks like `"@JUMP;;#ROM;#RAM;#ILRAM;#ADDIN"`. It can
 change options dynamically.
 
+**`jframe`** is a scrolling frame. It contains a single child widget that's
+larger than the frame, scrolls it around, renders scrollbars, and ensures that
+the child widget's rendering is clipped to the frame.
+
+**`jlist`** and **`jscrolledlist`** are browsable lists. The list model is not
+forced; the user provides an info function (indicating which elements can be
+selected and triggered) and a paint function for rendering them. Custom
+rendering is possible at any point and delegate widgets for edition can also be
+specified. `jscrolledlist` is a `jlist` in a `jframe`, which provides scrolling
+and is usually what one wants.
+
+**`jfilebrowser`** is a `jlist`-like file browser which is used to open and
+save files in applications.
+
 ## Custom widgets and polymorphic operations
 
 For custom widgets that just have custom rendering a no event management, one

include/justui/jscene.h

@@ -41,7 +41,6 @@ typedef struct {
 /* Events */
 extern uint16_t JSCENE_NONE;
 extern uint16_t JSCENE_PAINT;
-extern uint16_t JSCENE_KEY; /* Deprecated, merged with JWIDGET_KEY */
 
 /* jscene_create(): Create a new scene at that specified screen position */
 jscene *jscene_create(int x, int y, int w, int h, void *parent);

src/jscene.c

@@ -16,7 +16,6 @@ static int jscene_type_id = -1;
 /* Events */
 uint16_t JSCENE_NONE;
 uint16_t JSCENE_PAINT;
-uint16_t JSCENE_KEY;
 
 /* Keyboard transformation for inputs in a jscene */
 static int jscene_repeater(int key, GUNUSED int duration, int count)
@@ -318,5 +317,4 @@ static void j_register_jscene(void)
 	jscene_type_id = j_register_widget(&type_jscene);
 	JSCENE_NONE = j_register_event();
 	JSCENE_PAINT = j_register_event();
-	JSCENE_KEY = JWIDGET_KEY;
 }

src/jwidget.c

@@ -236,6 +236,8 @@ void jwidget_remove_child(void *w0, void *child0)
 	J_CAST(w, child)
 	if(child->parent != w) return;
 
+	// TODO[jwidget_remove_child]: Remove focus
+
 	int write = 0;
 	int index = -1;