Glossary

dash escaping

In a dialog argument list, dash escaping consists in prepending an element composed of two ASCII hyphens, i.e., the string '--', before every element that starts with two ASCII hyphens (--).

Every dialog option starts with -- (e.g., --yesno), but there are valid cases where one needs to pass arguments to dialog that start with -- without having dialog interpret them as options. For instance, one may want to print a text or label that starts with --. In such a case, in order to avoid confusing the argument with a dialog option, one must prepend an argument consisting solely of two ASCII hyphens (--). This is what is called dash escaping here.

For instance, in order to display a message box containing the text --Not an option using POSIX shell syntax (the double quotes " are stripped by the shell, dialog does not see them):

dialog --msgbox -- "--Not an option" 0 0   # correct

dialog --msgbox    "--Not an option" 0 0   # incorrect

Note

In pythondialog, most Dialog public methods (msgbox(), yesno(), menu(), etc.) know that the arguments they receive are not to be used as dialog options, and therefore automatically perform dash escaping whenever needed to avoid having dialog treat them as options. At the time of this writing, the only public method that requires you to be careful about leading double-dashes is the low-level Dialog.add_persistent_args(), because it directly passes all its arguments to dialog and cannot reliably guess which of these the user wants to be treated as dialog options and which they want to be treated as arguments to a dialog option.

See these examples of dash escaping in pythondialog using Dialog.dash_escape() and Dialog.dash_escape_nf().

Dialog exit code

high-level exit code

A Dialog exit code, or high-level exit code, is a string indicating how/why a widget-producing method ended. Most widgets return one of the standard Dialog exit codes (e.g., "ok", available as Dialog.OK). However, some widgets may return additional, non-standard exit codes; for instance, the inputmenu() widget may return "accepted" or "renamed" in addition to the standard Dialog exit codes.

When returning from a widget call, the Dialog exit code is normally derived from the dialog exit status, also known as low-level exit code.

See “Dialog exit code” (high-level) for more details.

standard Dialog exit code

A standard Dialog exit code is a particular Dialog exit code. Namely, it is one of the following strings: "ok", "cancel", "esc", "help", "extra" and "timeout", respectively available as Dialog.OK, Dialog.CANCEL, Dialog.ESC, Dialog.HELP, Dialog.EXTRA and Dialog.TIMEOUT, i.e., attributes of the Dialog class.

dialog exit status

low-level exit code

The dialog exit status, or low-level exit code, is an integer returned by the dialog backend upon exit, whose different possible values are referred to as DIALOG_OK, DIALOG_CANCEL, DIALOG_ESC, DIALOG_ERROR, DIALOG_EXTRA, DIALOG_HELP, DIALOG_ITEM_HELP and DIALOG_TIMEOUT in the dialog(1) manual page.

See “dialog exit status” (low-level) for more details.

dialog common options

Options that may be passed to many widgets using keyword arguments, for instance defaultno, yes_label, extra_button or visit_items. These options roughly correspond to those listed in dialog(1) under the Common Options section.

See Passing dialog “common options” for more details.

item-help string

When using item_help=True in a widget-producing method call, every item must have an associated string, called its item-help string, that is normally displayed by dialog at the bottom of the screen whenever the item is highlighted.

See Providing inline per-item help for more details.