# dialogs package

The purpose of this package is to expose the dialog box handling interface of the active GUI hid. Using this package scripts can pop up dialog boxes to inform or ask the user. If there is no active GUI, call logs are dumped on stderr. Note: message arguments usually may contain newline (\n) characters to split the message.

## Common conventions

Dialog boxes are blocking calls to the GUI HID: when the script calls a dialog box, the script is suspended until the dialog box is closed by the user. In other words, dialog boxes behave as regular function calls from the scripts: when they return, the dialog is over and the result is known.

The only exception is dialog_progress(), which opens or updates or closes the already open progress dialog box, and returns immediately (even when the box is left open).

## Simple dialogs vs. custom dialogs

Most of the calls will pop up a static dialog box. Static means that widgets are predefined by the GUI HID. The script is free to fill in data, but can not change the basic structure of the dialog box. For example dialog_confirm(), dialog_prompt(), dialog_fileselect() are static.

When the script needs a custom, dynamic dialog box, it needs to create an attribute dialog. The script sets up a HID structure using the hid package, builds up all the input fields then calls dialog_attribute() with the hid.

## Progress dialogs

The script should call dialog_progress() periodically from a process that runs time consuming calculations and check the return value and break the loop on cancel. The process should have an idea of how long it will take. This is passed on in argument total. As long as argument so_far is less than total, the dialog is open.

After the process has finished, a call with so_far=total+1 should be made to make sure the window is closed. If the call returns non-zero, the process should be cancelled.