DAD: Dynamic Attribute Dialogs: closing sequence
There are two ways a DAD can be closed:
- GUI close: the widget gets destroyed (e.g. the WM closes the dialog
after the user closes the window)
- code close: the code decides to close the dialog (e.g. from a
button callback or because of some non-gui async event happened)
There are four sets of structures/allocations associated with a DAD:
- user data: whatever data the [caller] (the code that created the DAD)
is keeping for the dialog; typically states or the content to be
displayed
- dad ctx: the widget table created using hid_dad.h, by the [dad] code
- hid ctx: the data behind hid_ctx maintained by the GUI [HID]
- widgets: the actual widgets maintained by the GUI [toolkit]
There is only one allocation sequence:
- [caller] allocates the user data
- [caller] calls [dad] to allocate the dad ctx: PCB_DAD_NEW()
- [dad] calls [HID] to allocate the hid ctx
- [HID] calls the [toolkit] to allocate widgets
- the [caller] calls PCB_DAD_RUN() or PCB_DAD_AUTORUN()
There are many different free sequences possible, the three most
typical ones are:
- non-blocking dialog, GUI close, free'd from the close callback
- the [toolkit] calls [HID] in a widget destroy callback; the
[HID] free's the wigets and initiates the user callback to the
[caller]
- from the close callback: the [caller] reads out the results
- from the close callback: the [caller] calls PCB_DAD_FREE(table),
which frees the dad ctx and the hid ctx
- from the close callback: the [caller] frees user data
- non-blocking dialog, code close, free'd from the close callback
- the [caller] reads out the results
- the [caller] calls PCB_DAD_FREE(table), which frees widgets,
the dad ctx and the hid ctx
- the [caller] frees user data
- modal (blocking) dialog, GUI close, free'd from where PCB_DAD_RUN() is called
- the [toolkit] calls [HID] in a widget destroy callback; the
[HID] free's the wigets and initiates the user callback to the
[caller]
- PCB_DAD_RUN() returns at the caller
- the [caller] reads out the results
- the [caller] calls PCB_DAD_FREE(table), which frees the dad ctx and
the hid ctx
- the [caller] frees user data
In other words, one PCB_DAD_NEW() needs to have exactly one PCB_DAD_FREE()
pair. If PCB_DAD_FREE() is called while the dialog is on (code close),
the dialog is closed and the callback function is called (unless it is
already running). The [caller] can access DAD widget states and values
only between PCB_DAD_NEW() and PCB_DAD_FREE().