API Reference¶
Use whiptail to display dialog boxes from Python scripts.
Classes:
|
Namedtuple to store the returncode and value returned by a whiptail dialog. |
|
Display dialog boxes in the terminal from Python scripts. |
-
namedtuple
Response
(returncode, value)[source]¶ Bases:
NamedTuple
Namedtuple to store the returncode and value returned by a whiptail dialog.
Return values are as follows:
0
: TheYes
orOK
button was pressed.1
: TheNo
orCancel
button was pressed.255
: The user pressed theESC
key, or an error occurred.
-
class
Whiptail
(title='', backtitle='', height=None, width=None, auto_exit=False)[source]¶ Bases:
object
Display dialog boxes in the terminal from Python scripts.
- Parameters
title (
str
) – The text to show at the top of the dialog. Default''
.backtitle (
str
) – The text to show on the top left of the background. Default''
.height (
Optional
[int
]) – The height of the dialog. Default is 2-5 characters shorter than the terminal windowwidth (
Optional
[int
]) – The height of the dialog. Default is approx. 10 characters narrower than the terminal windowauto_exit (
bool
) – Whether to callsys.exit()
if the user selects cancel in a dialog. DefaultFalse
.
Methods:
calc_height
(msg)Calculate the height of the dialog box based on the message.
checklist
([msg, items, prefix])A checklist box is similar to a menu box in that there are multiple entries presented in the form of a menu.
inputbox
(msg[, default, password])An input box is useful when you want to ask questions that require the user to input a string as the answer.
menu
([msg, items, prefix])As its name suggests, a menu box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose.
msgbox
(msg)A message box is very similar to a yes/no box.
radiolist
([msg, items, prefix])A radiolist box is similar to a menu box.
run
(control, msg[, extra_args, …])Display a control.
showlist
(control, msg, items, prefix)Helper function to display radio- and check-lists.
textbox
(path)A text box lets you display the contents of a text file in a dialog box.
yesno
(msg[, default])Display a yes/no dialog box.
-
checklist
(msg='', items=(), prefix=' - ')[source]¶ A checklist box is similar to a menu box in that there are multiple entries presented in the form of a menu.
You can select and deselect items using the SPACE key. The initial on/off state of each entry is specified by status.
- Parameters
- Return type
- Returns
A list of the tag strings of those entries that are turned on, and the return code
-
inputbox
(msg, default='', password=False)[source]¶ An input box is useful when you want to ask questions that require the user to input a string as the answer. If
default
is supplied it is used to initialize the input string. When inputting the string, theBACKSPACE
key can be used to correct typing errors. If the input string is longer than the width of the dialog box, the input field will be scrolled.If
password
isTrue
, the text the user enters is not displayed. This is useful when prompting for passwords or other sensitive information. Be aware that if anything is passed in “init”, it will be visible in the system’s process table to casual snoopers. Also, it is very confusing to the user to provide them with a default password they cannot see. For these reasons, using “init” is highly discouraged.- Parameters
- Return type
- Returns
The value entered by the user, and the return code
As its name suggests, a menu box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose.
Each menu entry consists of a tag string and an item string. The tag gives the entry a name to distinguish it from the other entries in the menu. The item is a short description of the option that the entry represents. The user can move between the menu entries by pressing the
UP
/DOWN
keys, the first letter of the tag as a hot-key. There are menu-height entries displayed in the menu at one time, but the menu will be scrolled if there are more entries than that.- Parameters
- Return type
- Returns
The tag of the selected menu item, and the return code.
-
msgbox
(msg)[source]¶ A message box is very similar to a yes/no box.
The only difference between a message box and a yes/no box is that a message box has only a single
OK
button.You can use this dialog box to display any message you like. After reading the message the user can press the ENTER key so that whiptail will exit and the calling script can continue its operation.
- Parameters
msg (
str
) – The message to display in the dialog box
-
radiolist
(msg='', items=(), prefix=' - ')[source]¶ A radiolist box is similar to a menu box.
The only difference is that you can indicate which entry is currently selected, by setting its status to on.
- Parameters
- Return type
- Returns
A list of the tags strings that were selected, and the return code.
-
run
(control, msg, extra_args=(), extra_values=(), exit_on=(1, 255))[source]¶ Display a control.
- Parameters
control (
str
) – The name of the control to run. One of'yesno'
,'msgbox'
,'infobox'
,'inputbox'
,'passwordbox'
,'textbox'
,'menu'
,'checklist'
,'radiolist'
or'gauge'
msg (
str
) – The message to display in the dialog boxextra_args (
Sequence
[str
]) – A sequence of extra arguments to pass to the control. Default()
.extra_values (
Sequence
[str
]) – A sequence of extra values to pass to the control. Default()
.exit_on (
Sequence
[int
]) – A sequence of return codes that will cause program execution to stop ifWhiptail.auto_exit
isTrue
. Default(1, 255)
.
- Return type
- Returns
The response returned by whiptail
-
showlist
(control, msg, items, prefix)[source]¶ Helper function to display radio- and check-lists.
- Parameters
- Return type
- Returns
A list of the tags strings that were selected, and the return code/
-
textbox
(path)[source]¶ A text box lets you display the contents of a text file in a dialog box. It is like a simple text file viewer. The user can move through the file by using the
UP
/DOWN
,PGUP
/PGDN
andHOME
/END
keys available on most keyboards. If the lines are too long to be displayed in the box, theLEFT
/RIGHT
keys can be used to scroll the text region horizontally. For more convenience, forward and backward searching functions are also provided.
-
yesno
(msg, default='yes')[source]¶ Display a yes/no dialog box.
The string specified by
msg
is displayed inside the dialog box. If this string is too long to be fit in one line, it will be automatically divided into multiple lines at appropriate places. The text string may also contain the newline character\n
to control line breaking explicitly.This dialog box is useful for asking questions that require the user to answer either yes or no. The dialog box has a
Yes
button and aNo
button, in which the user can switch between by pressing theTAB
key.