And documented all the other functions we need to start writing common/control.c.

doc/controls.md

@@ -68,9 +68,9 @@ This function is intended to be used to implement a macro that converts an arbit
 uiControl *uiNewControl(uint32_t type, void *initData);
 ```
 
-`uiNewControl()` creates a new `uiControl` of the given type with the given data.
+`uiNewControl()` creates a new `uiControl` of the given type.
 
-This function is meant for control implementations to use in the implementation of dedicated creation functions; for instance, `uiNewButton()` calls `uiNewControl()`, passing in the appropriate values for `initData`. Normal users should not call this function.
+This function is meant for control implementations to use in the implementation of dedicated creation functions; for instance, `uiNewButton()` calls `uiNewControl()`, passing in the appropriate values for `initData`. `initData` is, in turn, passed to the control's `Init()` method, and its format is generally internal to the control. Normal users should not call this function.
 
 It is a programmer error to pass an invalid value for either `type` or `initData`.
 
@@ -90,4 +90,24 @@ If `c` has any registered events, those event handlers will be set to be no long
 
 It is a programmer error to specify `NULL` for `c`.
 
-**For control implementations**: This function calls your vtable's `Free()` method. Parameter validity checks are already performed, `uiControlEventOnFree()` handlers have been called, and `uiControl`-specific events have been invalidated. Your `Free()` should invalidate any events that are specific to your controls, call `uiControlFree()` on all the children of this control, and free dynamically allocated memory that is part of your implementation data. Once your `Free()` method returns, libui will take care of freeing the implementation data memory block itself.
+**For control implementations**: This function calls your vtable's `Free()` method. Parameter validity checks are already performed, `uiControlOnFree()` handlers have been called, and `uiControl`-specific events have been invalidated. Your `Free()` should invalidate any events that are specific to your controls, call `uiControlFree()` on all the children of this control, and free dynamically allocated memory that is part of your implementation data. Once your `Free()` method returns, libui will take care of freeing the implementation data memory block itself.
+
+## `uiControlImplData()`
+
+```c
+void *uiControlImplData(uiControl *c);
+```
+
+`uiControlImplData()` returns the pointer to the implementation data for `c`. The returned pointer is valid for the lifetime of `c`.
+
+This function is meant to be used by control implementations only. There is in general no guarantee as to the size or format of this pointer. Normal users should not call `uiControlImplData()`.
+
+It is a programmer error to pass `NULL` or a non-`uiControl` for `c`.
+
+## `uiControlOnFree()`
+
+```c
+uiEvent *uiControlOnFree(void);
+```
+
+`uiControlOnFree()` returns a `uiEvent` that is fired by `uiControlFree()` to indicate that a control is about to be freed. In your handler, `sender` is the control in question and `args` is `NULL`.

doc/events.md

@@ -121,3 +121,15 @@ void uiEventSetHandlerBlocked(uiEvent *e, int id, bool blocked);
 `uiEventSetHandlerBlocked()` changes whether or not the given registered event handler is bocked. `id` should be the identifier of a previously registered event handler as returned by `uiEventAddHandler()`.
 
 It is a programmer error to specify `NULL` for `e` or a currently unregistered event identifier for `id`. It is also a programmer error to call `uiEventSetHandlerBlocked()` on an event while that event is being fired.
+
+## `xxxxx()`
+
+```c
+void uiEventInvalidateSender(uiEvent *e, void *sender);
+```
+
+`uiEventInvalidateSender()` instructs any registered handlers of `e` with sender `sender` that they should no longer fire. The handlers are not deleted (since the handler IDs may be reused, which may lead to bugs in client code), nor are they blocked with `uiEventHandlerSetBlocked()` (so the value of the blocked flag will be unaffected), but they will no longer actually run when the event is fired with the given sender pointer. Any future handlers registered with the same sender pointer will NOT be deactivated thus; only the existing ones are. The affected handlers can safely be deleted or blocked (the blocked flag merely no longer has any effect).
+
+The idea behind this function is that it is to be called when `sender` is destroyed, so `sender` does not need to worry about whether it has an event handler registered against it or not. Since it is possible for two objects whose lifetimes never overlap to have the same pointer value, simply blacklisting the sender pointer is insufficient.
+
+It is a programmer error to specify `NULL` or a global event for `e`, or to specify `NULL` for `sender`.

ui.h

@@ -60,6 +60,7 @@ uiprivExtern void uiEventDeleteHandler(uiEvent *e, int id);
 uiprivExtern void uiEventFire(uiEvent *e, void *sender, void *args);
 uiprivExtern bool uiEventHandlerBlocked(const uiEvent *e, int id);
 uiprivExtern void uiEventSetHandlerBlocked(uiEvent *e, int id, bool blocked);
+uiprivExtern void uiEventInvalidateSender(uiEvent *e, void *sender);
 
 typedef struct uiControl uiControl;
 typedef struct uiControlVtable uiControlVtable;
@@ -78,6 +79,8 @@ uiprivExtern void *uiCheckControlType(void *c, uint32_t type);
 
 uiprivExtern uiControl *uiNewControl(uint32_t type, void *initData);
 uiprivExtern void uiControlFree(uiControl *c);
+uiprivExtern void *uiControlImplData(uiControl *c);
+uiprivExtern uiEvent *uiControlOnFree(void);
 
 #ifdef __cplusplus
 }