Index: closing.html
===================================================================
--- closing.html (nonexistent)
+++ closing.html (revision 26962)
@@ -0,0 +1,72 @@
+
+
+
+ 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
+
+ - blocking dialog, GUI close, free'd from where PCB_DAD_AUTORUN() 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]
+
- 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().
+
Index: index.html
===================================================================
--- index.html (revision 26961)
+++ index.html (revision 26962)
@@ -9,4 +9,5 @@
History and intro
Building blocks (widgets)
Running the dialog box
+ Closing the dialog box