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:

1. [caller] allocates the user data
2. [caller] calls [dad] to allocate the dad ctx: PCB_DAD_NEW()
3. [dad] calls [HID] to allocate the hid ctx
4. [HID] calls the [toolkit] to allocate widgets
5. the [caller] calls PCB_DAD_RUN() or PCB_DAD_AUTORUN()

• non-blocking dialog, GUI close, free'd from the close callback
  1. the [toolkit] calls [HID] in a widget destroy callback; the [HID] free's the wigets and initiates the user callback to the [caller]
  2. from the close callback: the [caller] reads out the results
  3. from the close callback: the [caller] calls PCB_DAD_FREE(table), which frees the dad ctx and the hid ctx
  4. from the close callback: the [caller] frees user data
• non-blocking dialog, code close, free'd from the close callback
  1. the [caller] reads out the results
  2. the [caller] calls PCB_DAD_FREE(table), which frees widgets, the dad ctx and the hid ctx
  3. the [caller] frees user data
• modal (blocking) dialog, GUI close, free'd from where PCB_DAD_RUN() is called
  1. the [toolkit] calls [HID] in a widget destroy callback; the [HID] free's the wigets and initiates the user callback to the [caller]
  2. PCB_DAD_RUN() returns at the caller
  3. the [caller] reads out the results
  4. the [caller] calls PCB_DAD_FREE(table), which frees the dad ctx and the hid ctx
  5. 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().