Index: doc/developer/dad/run.html =================================================================== --- doc/developer/dad/run.html (nonexistent) +++ doc/developer/dad/run.html (revision 27868) @@ -0,0 +1,68 @@ + + + +

DAD: running the dialog box

+ +

From C

+

+Dialog box data is created in memory using either PCB_DAD_DECL(table) or +PCB_DAD_DECL_NOINIT(table). The first call declares and initializes all +variables and is suitable for when the dialog box is hosted directly in +(static) global variables or as local variables of a function. The _NOINIT +version omits the initialization and is suitable for declaring the dialog box +as part of a struct. In the latter case the caller needs to make sure all +dialog box fields are initialized to zero. + +

Running non-modal dialogs

+

+The typical sequence of running a non-modal dialog is: +

+(declaration)
+(filling in with widgets)
+PCB_DAD_NEW();
+
+

+The modal argument of PCB_DAD_NEW() is pcb_false. The dialog box +is created in the PCB_DAD_NEW() call, which returns immediately, leaving +the dialog box running in the background. + +

Running modal dialogs

+

+The typical sequence of running a modal dialog is: +

+(declaration)
+(filling in with widgets)
+PCB_DAD_NEW();
+PCB_DAD_RUN();
+(process the return value of PCB_DAD_RUN())
+PCB_DAD_FREE();
+
+

+The modal argument of PCB_DAD_NEW() is pcb_true. PCB_DAD_RUN() +will not return until the user gets the modal dialog box closed (either +by the VM or by the code). + +

Running modal dialogs - shorthand

+

+There is an alternative sequence using PCB_DAD_AUTORUN() but it saves +only one line compared to the above code and makes handling the return +value somewhat more complicated. Thus the above sequence should be +preferred. + + +

From user scripts

+

+After creating the dialog box widgets in memory, the actual GUI can be +started up by a call to action dad(dialog_name, run, title) or +dad(dlgname, run_modal, title). +

+The difference between run and run_modal is when the +call returns: +