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

FreeBSD Manual Pages


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

       dialog -	display	dialog boxes from shell	scripts

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

       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.

	      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

       --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 [ yes | no ]
	      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.	A Yes button is	 selected  by  default
	      unless no	is specified.

       --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.

       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.

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

       $HOME/.dialogrc	   default configuration file

       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.


       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.

       Savio Lam (

       Changes by Anatoly A. Orehovsky ( (ftree and  tree

				2 October 1998			     DIALOG(1)


Want to link to this manual page? Use this URL:

home | help