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.

How user attached data and memory allocation is managed is described in the DAD closing sequence document.

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.

example code template

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).

example code template

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: