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.