listener
Installs a listener instance on the target component via the modifier mechanism - the by-identity listener seam, the one every builder taking a listener object is built on (the typed instance builders like mouseListener/actionListener and the model builders like changeListener).
The overload taking a callback and a CallbackRegistration instead registers a listener the library builds, which reads the callback when the event fires. That is the one to reach for when the handler is written at the call site.
The instance is added once through registration when the element enters the chain and removed when it leaves or the node is released/reused. Supplying a different instance (reference inequality) on a later recomposition detaches the old one and attaches the new; supplying the same instance is a no-op. Pass a stable instance (e.g. remember {}) to avoid that churn.
T is the component type the listener attaches to; registration receives it already typed, and a node that is not a T is rejected at apply with a clear error.
Reach for it last: it is the one place in the everyday API that names a component type, and a typed builder or a callback modifier covers the ordinary cases. Adding and removing a listener through the component it hands you is safe, which is what the seam exists for. Using that component to write a property the composition declares, or to add or remove children, makes a second manager of something the composition already owns. The widget then holds a value nothing declares until the next write or settlement overwrites it, or the two managers corrupt each other's bookkeeping.
Return
this chain with instance declared on it.
Parameters
the Swing/AWT listener (or model listener) object to install.
where instance is registered.
Installs one library-built listener that reads the caller's callback when an event fires - the seam every builder's lambda overload is built on.
This is the callback half of the listener seam, and what is registered is what separates it from the overload taking a listener instance. That one registers the caller's own object, whose identity is the contract: a different object detaches the old one and attaches the new, so a caller passing a fresh lambda has to remember it. Here the registered object is the one registration builds, and the caller's callback is read when the event fires - a fresh lambda each recomposition costs one write and re-registers nothing, and since it changes no registration the chain it sits in is applied as the one applied last, without being walked for it. Hand over a listener instance to reach the other overload; hand over a callback the library wraps to reach this one.
The built listener is added through registration when the element enters the chain and removed when it leaves or the node is released/reused. Each call is its own slot: two of them on one chain both install and both fire.
Return
this chain with the built listener declared on it.
Parameters
what the built listener reads when an event fires; refreshed on every pass.
where the built listener is registered, and how it is built.
Installs a listener instance, naming the target component type as a value.
The same by-identity contract as the reified overload above, with targetType - the thing that one reifies - spelled out. Reach for this when the component type is only known as a Class.
Return
this chain with instance declared on it.
Parameters
the component type registration receives; a node that is not one is rejected at apply with a clear error.
the Swing/AWT listener (or model listener) object to install.
where instance is registered.
Installs one library-built listener that reads the caller's callback, naming the target component type as a value.
The same live-callback contract as the reified overload above, with targetType - the thing that one reifies - spelled out. Reach for this when the component type is only known as a Class.
Return
this chain with the built listener declared on it.
Parameters
the component type registration receives.
what the built listener reads when an event fires; refreshed on every pass.
where the built listener is registered, and how it is built.