freebsd-nq/contrib/bsddialog/bsddialog.1

.\"
.\" Copyright (c) 2021-2022 Alfonso Sabato Siciliano
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 26, 2022
.Dt BSDDIALOG 1
.Os
.Sh NAME
.Nm bsddialog
.Nd TUI dialogs
.Sh SYNOPSIS
.Nm
.Fl Fl help
.Nm
.Fl Fl version
.Nm
.Op Fl Fl common-opts
.Fl Fl dialog
.Ar text
.Ar rows
.Ar cols
.Op Ar dialog-opts
.Sh DESCRIPTION
The
.Nm bsddialog
utility builds Text User Interface dialogs and widgets: to display messages,
to get input and to inform about a computation status.
.Pp
The options
.Fl Fl help
and
.Fl Fl version
print the list of options and the version, respectively, then exit.
.Pp
The following options are available for each dialog.
.Ar text
is a message printed inside the dialog, except for
.Fl Fl textbox
described later.
.Ar rows
and
.Ar cols
are the height and width, 0 for autosize and -1 for fullscreen.
The possible input got from the user interface is printed to standard error.
.Ss Common options
The following options can change the default behavior of the utility and are
common to some dialog.
.Bl -tag -width Ds
.It Fl Fl ascii-lines
Ascii characters to draw lines.
.It Fl Fl backtitle Ar backtitle
Title on the top side of the screen.
.It Fl Fl begin-x Ar x
Dialog horizontal position, 0 is the left screen side, -1 center.
.It Fl Fl begin-y Ar y
Dialog vertical position, 0 is the top screen side, -1 center.
.It Fl Fl cancel-label Ar label
Label for the
.Dq Cancel
button.
.It Fl Fl clear
Hide the dialog at exit.
.It Fl Fl colors
Enable highlights for text, the following sequences are considered escapes:
.Bl -column -compact
.It Dq \eZ0
black.
.It Dq \eZ1
red.
.It Dq \eZ2
green.
.It Dq \eZ3
yellow.
.It Dq \eZ4
blue.
.It Dq \eZ5
magenta.
.It Dq \eZ6
cyan.
.It Dq \eZ7
white.
.It Dq \eZr
reverse foreground and background colors.
.It Dq \eZR
disable reverse.
.It Dq \eZb
bold.
.It Dq \eZB
disable bold.
.It Dq \eZu
underline.
.It Dq \eZU
disable underline.
.It Dq \eZn
restore to normal text.
.El
.It Fl Fl cr-wrap
Replace new line with a space in
.Ar text .
.It Fl Fl date-format Ar format
String accepted by
.Xr strftime 3
to customize the output of
.Fl Fl datebox .
.It Fl Fl default-button Ar label
Focus on the button with
.Ar label
on startup.
.It Fl Fl default-item Ar name
Focus on the item with
.Ar name ,
for Checklist, Menu, Radiolist and Treeview.
.It Fl Fl default-no
Focus on
.Dq Cancel
or
.Dq \&No
button on startup.
.It Fl Fl defaultno
Equivalent to
.Fl Fl default-no .
.It Fl Fl disable-esc
Disable ESC key to quit.
.It Fl Fl esc-cancelvalue
Exits with the
.Dq Cancel
button value if the ESC key is pressed.
.It Fl Fl exit-label Ar label
Equivalent to
.Fl Fl ok-label .
.It Fl Fl extra-button
Add a button with
.Dq Extra
label.
.It Fl Fl extra-label Ar label
Set
.Ar label
for the
.Dq Extra
button.
.It Fl Fl generic-button1 Ar label
Add a button with
.Ar label .
.It Fl Fl generic-button2 Ar label
Add a button with
.Ar label .
.It Fl Fl help-button
Add a button with
.Dq Help
label.
.It Fl Fl help-label Ar label
Set
.Ar label
for
.Dq Help
button.
.It Fl Fl help-status
Print also the selected items if the
.Dq Help
button is pressed.
.It Fl Fl help-tags
Print the name of the focused item if the Help button is pressed also
with
.Fl Fl item-help .
.It Fl Fl hfile Ar filename
Open
.Ar filename
in a Textbox if F1 key is pressed,
.It Fl Fl hline Ar string
Dialog subtitle.
.It Fl Fl hmsg Ar string
Open a Msgbox with
.Ar string
if the F1 key is pressed.
.It Fl Fl ignore
Do not exit with unknown options.
.It Fl Fl insecure
Print
.Sq *
to hide passwords while typing, default space
.Sq " " .
.It Fl Fl item-depth
Specify a margin for items, available for Checklist, Menu and Radiolist.
.It Fl Fl item-help
Set a help string for each element of a Checklist, Form, Menu, Mixedform,
Passwordform, Radiolist and Treeview to display at the bottom screen side.
.It Fl Fl item-prefix
Set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview.
.It Fl Fl max-input Ar size
Maximum length of the input for
.Fl Fl input-box
ans
.Fl Fl passwordbox ,
default 2048.
.It Fl Fl no-cancel
Do not show
.Dq Cancel
button.
.It Fl Fl no-collapse
Do not replace a TAB character with a space in
.Ar text .
.It Fl Fl no-items
Do not display items desciption, for Checklist, Menu, Radiolist or Treeview.
.It Fl Fl no-label Ar label
Equivalent to
.Fl Fl cancel-label .
.It Fl Fl no-lines
Do not draw borders and lines.
.It Fl Fl no-nl-expand
do not consider the sequence
.Dq \en
like new line.
.It Fl Fl no-ok
Do not draw
.Dq OK
button.
.It Fl Fl no-shadow
No not draw the shadow of the dialog.
.It Fl Fl no-tags
Do not display items name, for Checklist, Menu and Radiolist.
.It Fl Fl nocancel
Equivalent to
.Fl Fl no-cancel .
.It Fl Fl nook
Equivalent to
.Fl Fl no-ok .
.It Fl Fl ok-label Ar label
Set
.Ar label
for
.Dq OK
button.
.It Fl Fl output-fd Ar fd
Print input from user interface to the specified file descriptor.
.It Fl Fl output-separator Ar sep
Set a sepator for the items in output, default whitespace.
.It Fl Fl print-maxsize
Screen size.
.It Fl Fl print-size
Print Dialog height and widget at exit.
.It Fl Fl print-version
Print version.
.It Fl Fl quoted
Quote items in output, default only when necessary.
.It Fl Fl separate-output
Separate selected items with a new line.
.It Fl Fl separator Ar sep
Equivalent to
.Fl Fl output-separator .
.It Fl Fl shadow
Show a pseudo shadow for the dialog, enabled by default.
.It Fl Fl single-quoted
Use single quote for items in output.
.It Fl Fl sleep Ar secs
Wait
.Ar secs
seconds to close the dialog.
.It Fl Fl stderr
Print input from user interface to standand error, default.
.It Fl Fl stdout
Print input from user interface to standard output.
.It Fl Fl tab-len Ar spaces
Number of spaces to print a TAB in
.Ar text .
.It Fl Fl theme Ar theme
Set a graphical style: blackwhite, bsddialog, default or dialog.
.It Fl Fl time-format Ar format
String accepted by
.Xr strftime 3
to customize the output of
.Fl Fl timebox .
.It Fl Fl title Ar title
Dialog title.
.It Fl Fl trim
remove consecutive spaces in
.Ar text .
.It Fl Fl yes-label Ar label
Equivalent to
.Fl Fl ok-label .
.El
.Ss Dialogs
The following dialogs are available:
.Bl -tag -width Ds
.It Fl Fl checklist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \
Ar status Oc ...
Checklist to select some item from a list via the SPACE key.
An item has a
.Ar name ,
.Ar desc
and a default
.Ar status
specified by
.Dq on
or
.Dq off .
The names of the selected items are printed to standard error.
.Ar menurows
is the graphical height of the list, 0 for autosize.
.It Fl Fl datebox Ar text Ar rows Ar cols Op Ar year Ar month Ar day
Dialog to select a date.
.It Fl Fl form Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \
Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxvaluelen Oc ...
Dialog to get a list of strings via forms.
A form has a
.Ar label
at the position
.Ar ylabel
and
.Ar xlabel ,
a field to get the input at the position
.Ar yfield
and
.Ar xfield
with graphical length
.Ar fieldlen ,
.Ar maxvaluelen
is the maximum input length.
The field can be customized, if
.Ar fieldlen
is 0 its length is the absolute value of
.Ar maxvaluelen ,
if
.Ar maxvaluelen
is negative the field is read only,
.Ar init
is a default value.
.Ar formrows
is the graphical height of the list, has to be at least the number of forms.
.It Fl Fl gauge Ar text Ar rows Ar cols Op Ar percentage
Dialog with a bar to shows
.Ar percentage ,
then it waits to read
.Dq XXX
from the standard input, then the first string replaces percentage and the
following strings replace
.Ar text
until the next
.Dq XXX ,
the loop ends reading
.Dv EOF .
.It Fl Fl infobox Ar text Ar rows Ar cols
Dialog without buttons to display a message and to exit immediately.
.It Fl Fl inputbox Ar text Ar rows Ar cols Op Ar init
Dialog to get a string in input,
.Ar init
is the default value.
.It Fl Fl menu Ar text Ar rows Ar cols Ar menurows Oo Ar name desc Oc ...
Builds a menu to select an item from a list.
An item has a
.Ar name
and a
.Ar desc .
The name of the selected item is printed to standard error.
.Ar menurows
is the graphical height of the list, 0 for autosize.
.It Fl Fl mixedform Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \
Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxvaluelen Ar flag Oc ...
Dialog to get a list of strings via forms.
A form has a
.Ar label
at the position
.Ar ylabel
and
.Ar xlabel ,
a field to get the input with graphical length
.Ar fieldlen
at the position
.Ar yfield
and
.Ar xfield ,
.Ar maxvaluelen
is the maximum input length,
.Ar init
is a default value,
.Ar flag
can be 0 for normal field, 1 to hide the typed characters and 2 to set the
field read only.
.Ar formrows
is the graphical height of the list, has to be at least the number of forms.
.It Fl Fl mixedgauge Ar text Ar rows Ar cols Ar mainperc Oo Ar minilabel \
Ar miniperc Oc ...
Dialog to show a main bar to represent
.Ar mainperc
from 0 to 100 and some mini bar with a
.Ar minilabel
string and a
.Ar miniperc
with value from 0 and 100 or negative to print a descriptive string: -1
.Dq Succeeded ,
-2
.Dq Failed ,
-3
.Dq Passed ,
-4
.Dq Completed ,
-5
.Dq Checked ,
-6
.Dq Done ,
-7
.Dq Skipped ,
-8
.Dq \&In Progress ,
-9
a blank line,
-10
.Dq N/A ,
-11
.Dq Pending .
.It Fl Fl msgbox Ar text Ar rows Ar cols
Dialog to diplay a message without the
.Dq Cancel
button.
.It Fl Fl passwordbox Ar text Ar rows Ar cols Op Ar init
Dialog to get a password,
.Ar init
is the default value.
.It Fl Fl passwordform Ar text Ar rows Ar cols Ar formrows Oo Ar label \
Ar ylabel Ar xlabel Ar init Ar yfield Ar xfield  Ar fieldlen Ar valuelen Oc ...
Dialog to get a list of passwords, equivalent to
.Fl Fl form
except typed characters are hidden.
.It Fl Fl pause Ar text Ar rows Ar cols Ar seconds
Dialog runs until the timeout in
.Ar seconds
expires or a button is pressed.
.It Fl Fl radiolist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \
Ar status Oc ...
Radiolist to select at most an item from a list via the SPACE key.
An item has a
.Ar name ,
.Ar desc
and a default
.Ar status
specified by
.Dq on
or
.Dq off .
The name of the selected item is printed to standard error.
.Ar menurows
is the graphical height of the list, 0 for autosize.
.It Fl Fl rangebox Ar text Ar rows Ar cols Ar min Ar max Op Ar init
Dialog to select a value between
.Ar min
and
.Ar max ,
.Ar init
is the default value, the keys UP, DOWN, HOME, END, PAGEUP and PAGEDOWN can
change it.
.It Fl Fl textbox Ar file Ar rows Ar cols
Opens and prints
.Ar file
the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate;
.Dq OK
button is renamed
.Dq EXIT .
.It Fl Fl timebox Ar text Ar rows Ar cols Op Ar hour Ar min Ar sec
Dialog to select a time.
.It Fl Fl treeview Ar text Ar rows Ar cols Ar menurows Oo Ar depth Ar name \
Ar desc Ar status Oc ...
Equivalent to Radiolist with
.Fl Fl  item-depth
and
.Fl Fl no-name .
.It Fl Fl yesno Ar text Ar rows Ar cols
.Dq Yes-No Question ,
.Dq OK
and
.Dq Cancel
buttons are renamed
.Dq Yes
and
.Dq \&No .
.El
.Sh EXIT STATUS
The
.Nm
utility exits 255 on unsuccessful, otherwise depending on the button or key
pressed the following values can be returned:
.Bl -column -compact
.It 0
.Dq OK ,
.Dq Yes
or
.Dq Exit
button.
.It 1
.Dq Cancel
or
.Dq \&No
button.
.It 2
.Dq Help
button.
.It 3
.Dq Extra
button.
.It 4
Timeout.
.It 5
ESC key.
.It 6
Generic 1 button.
.It 7
Generic 2 button.
.El
.Sh EXAMPLES
Backtitle, title and message:
.Dl bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0
.Pp
Yes-No Question and theme:
.Dl bsddialog --theme blackwhite --yesno Question 10 30
.Pp
Checklist:
.Dl bsddialog --checklist Checklist 0 0 3 N1 \&D1 off N2 D2 on N3 D3 off
.Pp
Mixedgauge:
.Dl bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 "\(dq" -1" L2 30
.Pp
Form:
.Dl bsddialog --form Form 0 0 2 L1: 1 1 X 1 5 20 25 L2: 2 1 X 2 5 20 25
.Pp
Gauge script:
.Bd -literal -offset indent -compact
i=1
for c in A B C D E F G H
do
	sleep 1
	echo XXX
	echo "$(expr $(expr $i "*" 100) "/" 8)"
	echo "[$i/8] Char: $c"
	echo XXX
	if [ $i -eq 8 ]
	then
		sleep 1
		echo EOF
	fi
	i=`expr $i + 1`
done | bsddialog --title Gauge --gauge "Starting..." 10 70
.Ed
.Pp
Mixedgauge script:
.Bd -literal -offset indent -compact
perc=0
while [ $perc -le 100 ]
do
	bsddialog --sleep 1 --title Mixedgauge          \e
		--mixedgauge "\enExample...\en" 0 0 $perc \e
		"Hidden"   " -9"                        \e
		"Label 1"  " -4"                        \e
		"Label 2"  " -4"                        \e
		"Label 3"  $perc

	perc=`expr $perc + 20`
done
.Ed
.Sh SEE ALSO
.Xr bsddialog 3
.Sh HISTORY
The
.Nm bsddialog
utility first appeared in
.Fx 14.0 .
.Sh AUTHORS
.Nm bsddialog
was written by
.An Alfonso Sabato Siciliano Aq Mt alf.siciliano@gmail.com .
.Sh BUGS
The forms do not resize the dialog after a terminal change and does not provides
scrolling for items.