Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
No Starch Press

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 72 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here




       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 messages 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, radi­
              olist, 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 (specifying 0 for height and
              width).  It represents width / height.  The default
              is 9, which means 9 characters wide to every 1 line

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

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

              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
              '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.  Otherwise, 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 configuration 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 default.

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

              Show  an  extra  button, between ok/cancel and help

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

       --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 disable that feature.   Note  that  dialog  will
              still wrap text, subject to the --cr-wrap option.

              Tells  dialog to put the tailboxbg box in the back­
              ground, 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 standard 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

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

              For  checklist widgets, output result one line at a

              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  obso­
              lete, 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 seconds.

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

              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.

              date is printed in the form day/month/year.

       --checklist  text height width list-height [ tag item sta­
       tus ] ...
              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

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

              Here  filepath  can be a filepath in which case the
              file and directory windows will  display  the  con­
              tents  of  the  path and the text-entry window will
              contain the preselected filename.

              Use tab or arrow keys to move between the  windows.
              Within  the  directory or filename 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  win­
              dows to the closest 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 inte­
              ger per line.  The meter is updated to reflect each
              new  percentage.   If stdin is XXX, then subsequent
              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 specified, it is  zero.

              tialize   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 repre­
              sents.  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.   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 message box and a  yes/no
              box is that a message box has only a single OK but­
              ton.  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

       --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 any­
              thing 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 sta­
       tus ] ...
              A radiolist box is similar to a menu box.  The only
              difference is that you can indicate which entry  is
              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 individu­
              ally, e.g., by pressing ENTER.  Once the  non-tail­
              boxbg  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 unwork­
              able.  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 horizon­
              tally.  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  convenience,
              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  cur­
              rent date's corresponding 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 appro­
              priate places.  The text string  can  also  contain
              the  sub-string  "\n" or newline characters `\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 a No button, in which the user
              can switch between by pressing the TAB key.

           c)  if  the  file  in  (b) is not found, try using the
               GLOBALRC file determined  at  compile-time,  i.e.,

           d)  if  the  file in (c) is not found, use compiled in

       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



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
The Linux Tutorial welcomes your suggestions and ideas.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.09 Seconds