JustUI/doc/changelogs.md

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.

//=== 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 626da6f378):

//=== 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.

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. 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: 57a460894f (diff-94b157d9507dee40d44c23076d92c5ceb0b427d4))

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: 57a460894f (diff-492b1daa1b4361eb231c82b4b1fca013601eb54c)).

Breaking features and major features

• Rework widget focus model 57a460894f 7a5101360a
  • 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 23294b77ac
• Replace widget definition process 216918123f 683e89d725 626da6f378
  • This removes the inheritance property
  • This modifies the convention for event handling functions, which should now default to jwidget_poly_event() 683e89d725 93eb0df38a
  • Results in much less boilerplate
• fx-CP 400 build and basic compatibility (no touch input yet) 5b092a5a4e with correctly-sizes (but barely usable) F-keys e12a58c1f0s
• WIP: Denotational UIs still a work-in-progress.

Minor improvemements

• jfileselect: Now displays "(No entries)" for empty folders 4c44b3e413 and error values when a filesystem error occurs bea113f09e
• jscene: Now turns off with SHIFT+AC/ON, with option to disable ef71bc11c0 0c8371edce
• jscene: Autopaint option 7f2131d6a0
• jscene: Defaults to vbox layout instead of no layout a2129f1ed2
• jinput: Add function to customize keymap 0e5ccf4cc3
• jlabel: Now recognizes the font_t property line_distance for inter-line spacing 33e9962209
• jlabel: Defaults to top alignment 4728c6ecbe
• jlabel: No longer gobbles spaces after line breaks if the break is caused by an explicit \n 4728c6ecbe
• jlist: More fluid user code with default selection 3488c6515a, info values 12b29f8223, and a user data pointer for rendering 7587dfa17c
• jevent: Provide functions for identifying key events (still looking for a good design there) 7b8070f02c
• 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). f28d7a9cb8
• Optimization: turn on LTO 5a885b541f
• Optimization: full-screen widget with background (usually jscene) now renders with dclear() f32dcc69ce

Fixes

• Compatibility: less FX vs. CG hardcoding e324f9a3a2
• jframe: Fix crash with NULL child 5e2488cdf4
• jscene: Interrupt-safe access to event queue 550c08e200
• jlist, jscrolledlist: Fix parent not being last parameter ba7b0a02d0
• Add checks to avoid the compiler inserting certain abort() calls 4d6b760b1a