Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for dialog (redhat section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

DIALOG(1)										DIALOG(1)

       dialog - display dialog boxes from shell scripts

       dialog --clear
       dialog --create-rc file
       dialog --print-maxsize
       dialog common-options box-options

       Dialog  is  a  program that will let you to present a variety of questions or display mes-
       sages using dialog boxes from a shell script.  These types of dialog boxes are implemented
       (though not all are necessarily compiled into dialog):

	      calendar,  checklist,  fselect,  gauge,  infobox, inputbox, menu, msgbox (message),
	      password, radiolist, tailbox, tailboxbg, textbox, timebox, and yesno (yes/no).

       You can put more than one dialog box into a script:

       -    Use the --and-widget token to force Dialog to proceed to the next dialog  unless  you
	    have pressed ESC to cancel, or

       -    Simply add the tokens for the next dialog box, making a chain.  Dialog stops chaining
	    when the return code from a dialog is nonzero, e.g., Cancel or No.

       Common Options

       --aspect ratio
	      This gives you some control over the box dimensions when using auto sizing  (speci-
	      fying  0	for  height and width).  It represents width / height.	The default is 9,
	      which means 9 characters wide to every 1 line high.

       --backtitle backtitle
	      Specifies a backtitle string to be displayed on the backdrop, at	the  top  of  the

       --beep Sound the audible alarm each time the screen is refreshed.

	      Beep if input is interrupted, e.g., by a control/C.

       --begin y x
	      Specify the position of the upper left corner of a dialog box on the screen.

       --cancel-label string
	      Override the label used for "Cancel" buttons.

	      The  screen  will  be  cleared  to  the screen attribute on exit.  This may be used
	      alone, without other options.

	      Interpret embedded "\Z" sequences in the dialog text by the follow character, which
	      tells  dialog  to  set colors or video attributes: 0 through 7 are the ANSI used in
	      curses: black, red, green, yellow, blue,	magenta,  cyan	and  white  respectively.
	      Bold  is set by 'b', reset by 'B'.  Reverse is set by 'r', reset by 'R'.	Underline
	      is set by 'u', reset by 'U'.  The settings are cumulative, e.g., "\Zb\Z1" makes the
	      following text bright red.  Restore normal settings with "\Zn".

	      Interpret  embedded newlines in the dialog text as a newline on the screen.  Other-
	      wise, dialog will only wrap lines where needed to fit inside the	text  box.   Even
	      though you can control line breaks with this, dialog will still wrap any lines that
	      are too long for the width of the box.  Without cr-wrap, the layout  of  your  text
	      may  be  formatted to look nice in the source code of your script without affecting
	      the way it will look in the dialog.

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

	      Make the default value of the yes/no box a No.

       --default-item string
	      Set  the	default  item  in  a menu box.	Normally the first item in the box is the

       --exit-label string
	      Override the label used for "EXIT" buttons.

	      Show an extra button, between ok/cancel and help buttons.

       --extra-label string
	      Override the label used for "Extra" buttons.

       --help Prints the help message to standard error.  The  help  message  is  printed  if  no
	      options are given.

	      Show  a help-button after ok/cancel buttons, i.e., in checklist, radiolist and menu
	      boxes.  If --item-help is also given, on exit the return status will be the same as
	      for the "Ok" button, and the item-help text will be written to standard error after
	      the token "HELP".  Otherwise, the return status will indicate that the Help  button
	      was pressed, and no message printed.

       --help-label string
	      Override the label used for "Help" buttons.

	      Ignore  options  that  dialog  does  not	recognize.   Some well-known ones such as
	      "--icon" are ignored anyway, but this is a better  choice  for  compatibility  with
	      other implementations.

	      Interpret  the  tags  data  for checklist, radiolist and menu boxes adding a column
	      which is displayed in the bottom line of the screen,  for  the  currently  selected

       --max-input size
	      Limit input strings to the given size.  If not specified, the limit is 2000.


	      Suppress	the  "Cancel" button in checklist, inputbox and menu box modes.  A script
	      can still test if the user pressed the ESC key to cancel to quit.

	      Normally dialog converts tabs to spaces and reduces multiple  spaces  to	a  single
	      space for text which is displayed in a message boxes, etc.  Use this option to dis-
	      able that feature.  Note that dialog will still wrap text, subject to the --cr-wrap

	      Tells dialog to put the tailboxbg box in the background, printing its process id to
	      standard error.  SIGHUP is disabled for the background process.

	      Suppress shadows that would be drawn to the right and bottom of each dialog box.

       --ok-label string
	      Override the label used for "OK" buttons.

       --output-fd fd
	      Direct output to the given file descriptor.  Most dialog scripts write to the stan-
	      dard error, but error messages may also be written there, depending on your script.

	      Print  the  maximum  size  of  dialog boxes, i.e., the screen size, to the standard
	      error.  This may be used alone, without other options.

	      Prints the size of each dialog box to standard error.

	      Prints dialog's version to standard error.  This may be used alone,  without  other

	      For  checklist  widgets,	output	result one line at a time, with no quoting.  This
	      facilitates parsing by another program.

       --separate-widget string
	      Specify a string that will separate the output on standard error from each  widget.
	      This  is	used to simplify parsing the result of a dialog with several widgets.  If
	      this option is not given, the default separator string is a tab character.

	      Draw a shadow to the right and bottom of each dialog box.

	      Check the resulting size of a dialog box before trying  to  use  it,  printing  the
	      resulting  size  if  it is larger than the screen.  (This option is obsolete, since
	      all new-window calls are checked).

       --sleep secs
	      Sleep (delay) for the given number of seconds after processing a dialog box.

	      Direct output to the standard error.  This is the default,  since  curses  normally
	      writes screen updates to the standard output.

	      Direct output to the standard output.

	      Convert  each  tab  character  to one or more spaces.  Otherwise, tabs are rendered
	      according to the curses library's interpretation.

       --tab-len n
	      Specify the number of spaces that a tab character occupies if  the  "--tab-correct"
	      option is given.	The default is 8.

       --timeout secs
	      Timeout  (exit with error code) if no user response within the given number of sec-

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

       --trim eliminate leading blanks, trim literal newlines and repeated  blanks  from  message

	      Same as "--print-version".

       Box Options
	      All dialog boxes have at least three parameters:

	      text the caption or contents of the box.

		   the height of the dialog box.

		   the width of the dialog box.

	      Other parameters depend on the box type.

       --calendar text height width day month year
	      A  calendar  box displays month, day and year in separately adjustable windows.  If
	      the values for day, month or year are missing or negative, the current date's  cor-
	      responding  values are used.  You can increment or decrement any of those using the
	      left-, up-, right- and down-arrows.  Use vi-style h, j, k and l for  moving  around
	      the  array of days in a month.  Use tab or backtab to move between windows.  If the
	      year is given as zero, the current date is used as an initial value.  On exit,  the
	      date is printed in the form day/month/year.

       --checklist text height width list-height [ tag item status ] ...
	      A  checklist  box is similar to a menu box; there are multiple entries presented in
	      the form of a menu.  Instead of choosing 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
	      specified by status.  On exit, a list of the tag strings of those entries that  are
	      turned on will be printed on stderr.

       --fselect  filepath height width
	      The  file-selection  dialog  displays  a	text-entry window in which you can type a
	      filename (or directory), and above that two windows with directory names and  file-

	      Here  filepath  can be a filepath in which case the file and directory windows will
	      display the contents of the path and the text-entry window will contain the  prese-
	      lected filename.

	      Use  tab	or arrow keys to move between the windows.  Within the directory or file-
	      name windows, use the up/down arrow keys to scroll the current selection.  Use  the
	      space-bar to copy the current selection into the text-entry window.

	      Typing  any  printable characters switches focus to the text-entry window, entering
	      that character as well as scrolling the directory and filename windows to the clos-
	      est match.

	      Use  a  carriage return or the "OK" button to accept the current value in the text-
	      entry window, or the "Cancel" button to cancel.

       --gauge text height width [percent]
	      A gauge box displays a meter along the bottom of the box.  The meter indicates  the
	      percentage.   New  percentages  are read from standard input, one integer per line.
	      The meter is updated to reflect each new percentage.  If stdin is XXX, then  subse-
	      quent  lines up to another XXX are used for a new prompt.  The gauge exits when EOF
	      is reached on stdin.

	      The percent value denotes the initial percentage shown in the meter.  If not speci-
	      fied, it is zero.

       --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 [init]
	      An  input  box  is  useful  when you want to ask questions that require the user to
	      input a string as the answer.  If init is supplied it is	used  to  initialize  the
	      input  string.   When entering the string, the BACKSPACE key can be used to correct
	      typing errors.  If the input string is longer than can fit in the dialog	box,  the
	      input field will be scrolled.  On exit, the input string will be printed on stderr.

       --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.	Choices are displayed  in
	      the order given.	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, or the number keys 1-9. There are menu-height entries dis-
	      played 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.  If the --help-button option is given,  the  corresponding  help
	      text will be printed if the user selects the help button.

       --msgbox text height width
	      A  message box is very similar to a yes/no box.  The only difference between a mes-
	      sage 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 mes-
	      sage, the user can press the ENTER key so that dialog will  exit	and  the  calling
	      shell script can continue its operation.

       --passwordbox text height width [init]
	      A  password box is similar to an input box, except that 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.

       --radiolist text height width list-height  [ tag item status ] ...
	      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.

       --tailbox file height width
	      Display text from a file in a dialog box, as in a "tail -f" command.

       --tailboxbg file height width
	      Display  text from a file in a dialog box as a background task, as in a "tail -f &"

	      Dialog treats the background task specially if there are other widgets  (--and-wid-
	      get)  on	the screen concurrently.  Until those widgets are closed (e.g., an "OK"),
	      dialog will perform all of the tailboxbg widgets in the same process,  polling  for
	      updates.	 You  may  use	a  tab to traverse between the widgets on the screen, and
	      close them individually, e.g., by pressing ENTER.  Once the  non-tailboxbg  widgets
	      are  closed,  dialog  forks  a  copy  of itself into the background, and prints its
	      process id if the --no-kill option is given.

	      NOTE: Older versions of dialog forked  immediately  and  attempted  to  update  the
	      screen  individually.   Besides being bad for performance, it was unworkable.  Some
	      older scripts may not work properly with the polled scheme.

       --textbox file height width
	      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 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.  You may also use vi-style keys h, j, k, l  in	place  of
	      the  cursor keys, and B or N in place of the pageup/pagedown keys.  For more conve-
	      nience, vi-style forward and backward searching functions are also provided.

       --timebox text height [width hour minute second]
	      A dialog is displayed which allows you to select hour, minute and second.   If  the
	      values  for hour, minute or second are missing or negative, the current date's cor-
	      responding values are used.  You can increment or decrement any of those using  the
	      left-,  up-,  right-  and down-arrows.  Use tab or backtab to move between windows.
	      On exit, the result is printed in the form hour:minute:second.

       --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
	      appropriate  places.   The text string can also contain the sub-string "\n" or new-
	      line characters `\n' to control line breaking explicitly.  This dialog box is  use-
	      ful  for	asking	questions  that require 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.

       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 con-
	       figuration file.

	   b)  if the file in (a) is not found, use the file $HOME/.dialogrc as the configuration

	   c)  if  the	file  in (b) is not found, try using the GLOBALRC file determined at com-
	       pile-time, i.e., /etc/dialogrc.

	   d)  if the file in (c) is not 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.






       DIALOG_OK      Define any of these variables to change the exit code on Cancel (1),  error
		      (-1),  ESC  (255),  Extra (3), Help (2), or Ok (0).  Normally shell scripts
		      cannot distinguish between -1 and 255.

       $HOME/.dialogrc	   default configuration file

       Exit status is subject to being overridden by environment variables.  Normally they are:

       0    if dialog is exited by pressing the Yes or OK button.

       1    if the No or Cancel button is pressed.

       -1   if errors occur inside dialog or dialog is exited by pressing the ESC key.


       Savio Lam (lam836@cs.cuhk.hk) - version 0.3, "dialog"

       Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4

       Pako (demarco_p@abramo.it) - version 0.9a, "cdialog",

       Thomas Dickey (updates for 0.9b)

$Date: 2002/08/13 23:28:58 $								DIALOG(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 10:58 PM.