Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DIALOG(1)		    General Commands Manual		     DIALOG(1)

NAME
       dialog -	display	dialog boxes from shell	scripts

SYNOPSIS
       dialog --clear
       dialog --create-rc file
       dialog  [ --title title ] [ --clear ] [ --hline line ] [	--hfile	file ]
       box-options

DESCRIPTION
       Dialog is a program which allows	you to present a variety of  questions
       or  display  messages in	dialog box form	from a shell script.  The fol-
       lowing types of dialog objects are currently supported:

       yes/no box, menu	box, input box,	 message  box,	text  box,  info  box,
       checklist box, program box, ftree and tree boxes.

OPTIONS
       --clear
	      The screen will be cleared to the	screen attribute on exit.

       --create-rc file
	      Since  dialog  supports run-time configuration, this can be used
	      to dump a	sample configuration file to  the  file	 specified  by
	      file.

       --title title
	      Specifies	 a title string	to be displayed	at the top of the dia-
	      log box.

       --hline line
	      Specifies	a line string to be displayed at the bottom of the di-
	      alog box.

       --hfile file
	      Specifies	a file to be displayed by pressing ? or	F1.

       Box Options

       --yesno text height width
	      A	yes/no dialog box of size height rows by width columns will be
	      displayed. The string specified by text is displayed inside  the
	      dialog  box.  If	this string is too long	to fit in one line, it
	      will be automatically divided into multiple lines	at the	appro-
	      priate  points.  The text	string may also	contain	the sub-string
	      "\n" or newline characters `\n' to control line breaking explic-
	      itly.   This  dialog box is useful for asking questions that re-
	      quire the	user to	answer either yes or no.  The dialog box has a
	      Yes button and a No button, in which the user can	switch between
	      by pressing the TAB key.

       --msgbox	text height width
	      A	message	box is very similar to a yes/no	box.  The only differ-
	      ence  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 dialog will	exit  and  the
	      calling shell script can continue	its operation.

       --infobox text height width
	      An  info box is basically	a message box.	However, in this case,
	      dialog will exit immediately after displaying the	message	to the
	      user.  The  screen is not	cleared	when dialog exits, so that the
	      message will remain on the screen	until the calling shell	script
	      clears it	later. This is useful when you want to inform the user
	      that some	operations are carrying	on that	may require some  time
	      to finish.

       --inputbox text height width
	      An  input	 box is	useful when you	want to	ask questions that re-
	      quire the	user to	input a	string as the  answer.	When  inputing
	      the  string, the BACKSPACE key can be used to correct typing er-
	      rors. If the input string	is longer than can be  fitted  in  the
	      dialog box, the input field will be scrolled. On exit, the input
	      string will be printed on	stderr.

       --textbox file height width
	      A	text box lets you display the contents of a text file in a di-
	      alog  box.  It  is  like a simple	text file viewer. The user can
	      move through the	file  by  using	 the  UP/DOWN,	PGUP/PGDN  and
	      HOME/END keys available on most keyboards.  If the lines are too
	      long to be displayed in the box, the LEFT/RIGHT keys can be used
	      to  scroll  the  text region horizontally. For more convenience,
	      forward and backward searching functions are also	provided.

       --menu text height width	menu-height [ tag item ] ...
	      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 descrip-
	      tion  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, or the	number keys 1-9. 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.
	      When dialog exits, the tag of the	 chosen	 menu  entry  will  be
	      printed on stderr.

       --prgbox	command	height width
	      A	program	box lets you display output of command in dialog box.

       --checklist text	height width list-height [ tag item status ] ...
	      A	 checklist box is similar to a menu box	in that	there are mul-
	      tiple entries presented in the form of a menu. Instead of	choos-
	      ing  one entry among the entries,	each entry can be turned on or
	      off by the user. The initial on/off state	of each	entry is spec-
	      ified  by	 status.   On exit, a list of the tag strings of those
	      entries that are turned on will be printed on stderr.

       --ftree file FS text height width menu-height
	      ftree box	is a dialog box	showing	the tree described by the data
	      from  the	 file  file.   The  data  in the file should look like
	      find(1)  output. For the find output,  the  field	 separator  FS
	      will  be '/'. If height and width	are positive numbers, they set
	      the absolute size	of the whole ftree box.	If  height  and	 width
	      are negative numbers, the	size of	the ftree box will be selected
	      automatically.  menu-height sets the height of the tree  subwin-
	      dow  inside the ftree box	and must be set.  text is shown	inside
	      the ftree	box above the tree subwindow and can  contain  newline
	      characters  '\n' to split	lines. One can navigate	in the tree by
	      pressing UP/DOWN or  '+'/'-',  PG_UP/PG_DOWN  or	'b'/SPACE  and
	      HOME/END or 'g'/'G'.  A leaf of the tree is selected by pressing
	      TAB or LEFT/RIGHT	the OK button and  pressing  ENTER.   The  se-
	      lected leaf (to be more exact, the full path to it from the root
	      of the tree) is printed to stderr.  If Cancel and	then ENTER  is
	      pressed,	nothing	 is  printed to	stderr.	 file may contain data
	      like find(1) output, as well as like the output of find(1)  with
	      -d option. Some of the transient paths to	the leaves of the tree
	      may be absent. Such data is corrected when fed from file.

       --tree FS text height width menu-height [ item ]	...
	      tree box is like ftree box with some exceptions. First, the data
	      is  not  entered	from a file, but from the command line as item
	      item ...	Second,	the data thus entered is not corrected in  any
	      way.   Thus,  the	data like the output of	find(1)	with -d	option
	      will look	incorrectly.

RUN-TIME CONFIGURATION
       1.  Create a sample configuration file by typing:

		 "dialog --create-rc <file>"

       2.  At start, dialog determines the settings to use as follows:

	   a)  if environment variable DIALOGRC	is set,	its  value  determines
	       the name	of the configuration file.

	   b)  if the file in (a) can't	be found, use the file $HOME/.dialogrc
	       as the configuration file.

	   c)  if the file in (b) can't	be found, use compiled in defaults.

       3.  Edit	the sample configuration file and copy it to some  place  that
	   dialog can find, as stated in step 2	above.

ENVIRONMENT
       DIALOGRC	      Define  this variable if you want	to specify the name of
		      the configuration	file to	use.

FILES
       $HOME/.dialogrc	   default configuration file

DIAGNOSTICS
       Exit status is 0	if dialog is exited by pressing	the Yes	or OK  button,
       and 1 if	the No or Cancel button	is pressed. Otherwise, if errors occur
       inside dialog or	dialog is exited by pressing the  ESC  key,  the  exit
       status is -1.

SEE ALSO
       dialog(3)

BUGS
       Text  files containing tab characters may cause problems	with text box.
       Tab characters in text files must first be expanded  to	spaces	before
       being displayed by text box.

       Screen update is	too slow.

       The  ftree and tree boxes do not	allow the tree to be moved to the left
       or to the right.	Thus, if there are many	levels of data,	 some  of  the
       leaves can be rendered invisible. A standard display with 80 characters
       allows for 17 levels to be visible. Deeper levels are  invisible.  How-
       ever, the navigation in the tree	and selection of leaves	do work.

AUTHOR
       Savio Lam (lam836@cs.cuhk.hk)

       Changes	by Anatoly A. Orehovsky	(tolik@mpeks.tomsk.su) (ftree and tree
       boxes)

				2 October 1998			     DIALOG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RUN-TIME CONFIGURATION | ENVIRONMENT | FILES | DIAGNOSTICS | SEE ALSO | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dialog&sektion=1&manpath=FreeBSD+5.4-RELEASE>

home | help