dialog


SYNOPSIS
       cc [ flag ... ] file ... -ldialog [ library ... ]

       #include <dialog.h>

       Dialog is a program that will let you to present a variety of questions
       or display messages using dialog boxes from  a  shell  script.   It  is
       built  from  the  dialog  library, which consists of several widgets as
       well as utility functions that are used by the widgets or the main pro-
       gram.

DESCRIPTION
       This manpage documents the features from <dialog.h> which are likely to
       be important to developers using the widgets directly.  Some hints  are
       also given for developing new widgets.

   DEFINITIONS
       Exit  codes  (passed  back to the main program for its use) are defined
       with a "DLG_EXIT_ prefix.  The defined constants can  be  mapped  using
       environment variables as described in dialog(1), e.g., DLG_EXIT_OK cor-
       responds to $DIALOG_OK.

       Useful character constants which correspond to  user  input  are  named
       with the "CHR_" prefix, e.g., CHR_BACKSPACE.

       Colors  and  video  attributes are categorized and associated with set-
       tings in the configuration file (see the  discussion  of  $DIALOGRC  in
       dialog(1)).   The  DIALOG_ATR(n)  macro is used for defining the refer-
       ences to the combined color and attribute table dlg_color_table[].

       The dialog application passes its command-line parameters to the widget
       functions.  Some of those parameters are single values, but some of the
       widgets accept data as  an  array  of  values.   Those  include  check-
       list/radiobox,  menubox  and  formbox.   When the --item-help option is
       given, an extra column  of  data  is  expected.   The  USE_ITEM_HELP(),
       CHECKBOX_TAGS,  MENUBOX_TAGS  and  FORMBOX_TAGS macros are used to hide
       this difference from the calling application.

       Most of the other definitions found in <dialog.h> are used  for  conve-
       nience  in building the library or main program.  These include defini-
       tions based on the generated <dlg_config.h> header.


   DATA STRUCTURES
       All of the global data for the dialog library is stored in a few struc-
       tures:  DIALOG_STATE, DIALOG_VARS and DIALOG_COLORS.  The corresponding
       dialog_state, dialog_vars and dlg_color_table global  variables  should
       be  initialized  to  zeros, and then populated with the data to use.  A
       few of these must be nonzero for the corresponding widgets to function.
       As  as the case with function names, variables beginning with "dialog_"
       are designed for use by the calling application while variables  begin-
       ning  with  "dlg_"  are  intended for lower levels, e.g., by the dialog
       library.

       DIALOG_STATE.getc_callbacks
              This is setup in ui_getc.c  to  record  windows  which  must  be
              polled for input, e.g,. to handle the background tailbox widget.
              One window is designated as the foreground or control window.

       DIALOG_STATE.getc_redirect
              If the control window for DIALOG_STATE.getc_callbacks is closed,
              the  list  is transferred to this variable.  Closing all windows
              causes the application to exit.

       DIALOG_STATE.output
              This is set in the dialog application to the stream on which the
              application  and library functions may write text results.  Nor-
              mally that is the  standard  error,  since  the  curses  library
              prefers to write its data to the standard output.  Some scripts,
              trading portability for convenience, prefer to write results  to
              the standard output, e.g., by using the "--stdout" option.

       DIALOG_STATE.output_count
              This  is incremented by dlg_does_output, which is called by each
              widget that writes text to the output.  The  dialog  application
              uses  that  to decide if it should also write a separator, i.e.,
              DIALOG_STATE.separate_str, between calls to each widget.

       DIALOG_STATE.pipe_input
              This is set in init_dialog to a stream which can be used by  the
              gauge  widget,  which  must be the application's standard input.
              The dialog application calls init_dialog normally with input set
              to  the standard input, but optionally based on the "--input-fd"
              option.  Since the application cannot read from a pipe (standard
              input) and at the same time read the curses input from the stan-
              dard input, it must allow for reopening the latter from either a
              specific  file  descriptor,  or directly from the terminal.  The
              adjusted pipe stream value is stored in this variable.

       DIALOG_STATE.screen_initialized
              This is set in init_dialog and reset in end_dialog.  It is  used
              to check if curses has been initialized, and if the endwin func-
              tion must be called on exit.

       DIALOG_STATE.screen_output
              This is set in init_dialog to the  output  stream  used  by  the
              curses  library.   Normally  that is the standard output, unless
              that happens to not be a terminal (and if init_dialog  can  suc-
              cessfully open the terminal directly).

       DIALOG_STATE.separate_str
              This corresponds to the command-line option "--separate-widget".
              The given string specifies a string that will separate the  out-
              put  on  dialog's output from each widget.  This is used to sim-
              plify parsing the result of a dialog with several  widgets.   If
              this  option is not given, the default separator string is a tab
              character.
              is set in init_dialog  if  the  curses  implementation  supports
              color.   If  true,  suppress  shadows that would be drawn to the
              right and bottom of each dialog box.

       DIALOG_STATE.visit_items
              This corresponds to the command-line option "--visit-items".

       The dialog application resets the  dialog_vars  data  before  accepting
       options to invoke each widget.  Most of the DIALOG_VARS members are set
       directly from dialog's command-line options:

       DIALOG_VARS.ascii_lines

       DIALOG_VARS.backtitle
              This corresponds to the command-line option "--backtitle backti-
              tle".   It  specifies  a backtitle string to be displayed on the
              backdrop, at the top of the screen.

       DIALOG_VARS.beep_after_signal
              This corresponds to the command-line option "--beep-after".   If
              true,  beep  after a user has completed a widget by pressing one
              of the buttons.

       DIALOG_VARS.beep_signal
              This corresponds to the command-line  option  "--beep".   It  is
              obsolete.

       DIALOG_VARS.begin_set
              This  is true if the command-line option "--begin y x" was used.
              It specifies the position of the upper left corner of  a  dialog
              box on the screen.

       DIALOG_VARS.begin_x
              This  corresponds  to  the  x value from the command-line option
              "--begin y x" (second value).

       DIALOG_VARS.begin_y
              This corresponds to the y value  from  the  command-line  option
              "--begin y x" (first value).

       DIALOG_VARS.cancel_label
              This  corresponds  to  the  command-line  option "--cancel-label
              string".  The given string overrides the label used for "Cancel"
              buttons.

       DIALOG_VARS.cant_kill
              This  corresponds  to  the  command-line option "--no-kill".  If
              true, this tells dialog to put the tailboxbg box  in  the  back-
              ground,  printing  its process id to dialog's output.  SIGHUP is
              disabled for the background process.

       DIALOG_VARS.colors
              This corresponds to  the  command-line  option  "--colors".   If
              true,  interpret  embedded  "\Z" sequences in the dialog text by
              true,  interpret  embedded newlines in the dialog text as a new-
              line 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.

       DIALOG_VARS.default_item
              This corresponds  to  the  command-line  option  "--default-item
              string".   The  given  string  is  used as the default item in a
              checklist, form or menu box.  Normally the first item in the box
              is the default.

       DIALOG_VARS.defaultno
              This  corresponds  to the command-line option "--defaultno".  If
              true, make the default value of the yes/no box a No.   Likewise,
              make  the  default button of widgets that provide "OK" and "Can-
              cel" a Cancel.  If --nocancel was given  that  option  overrides
              this,  making  the  default  button always "Yes" (internally the
              same as "OK").

       DIALOG_VARS.dlg_clear_screen
              This corresponds to the  command-line  option  "--clear".   This
              option  is implemented in the main program, not the library.  If
              true, the screen will be cleared on  exit.   This  may  be  used
              alone, without other options.

       DIALOG_VARS.exit_label
              This   corresponds  to  the  command-line  option  "--exit-label
              string".  The given string overrides the label used  for  "EXIT"
              buttons.

       DIALOG_VARS.extra_button
              This  corresponds  to  the command-line option "--extra-button".
              If true, some widgets show an extra  button,  between  "OK"  and
              "Cancel" buttons.

       DIALOG_VARS.extra_label
              This  corresponds  to  the  command-line  option  "--extra-label
              string".  The given string overrides the label used for  "Extra"
              buttons.    Note:   for  inputmenu  widgets,  this  defaults  to
              "Rename".

       DIALOG_VARS.formitem_type
              This is set by the command-line option "--passwordform" to  tell
              the  form  widget  that  its  text fields should be treated like
              password widgets.

       DIALOG_VARS.help_button
              This corresponds to the command-line option "--help-button".  If
              true,  some  widgets  show a help-button after "OK" and "Cancel"
              buttons, i.e., in  checklist,  radiolist  and  menu  boxes.   If
              This corresponds to the command-line option "--help-status".  If
              true, and the the help-button is selected, writes the  checklist
              or radiolist information after the item-help "HELP" information.
              This can be used to reconstruct the state of a  checklist  after
              processing the help request.

       DIALOG_VARS.input_length
              This is nonzero if DIALOG_VARS.input_result is allocated, versus
              being a pointer to the user's local variables.

       DIALOG_VARS.input_menu
              This flag is set to denote whether the menubox widget implements
              a menu versus a inputmenu widget.

       DIALOG_VARS.input_result
              If  DIALOG_VARS.input_length  is zero, this is a pointer to user
              buffer (on the stack, or static).  When DIALOG_VARS.input_length
              is  nonzero,  this is a dynamically-allocated buffer used by the
              widgets to return printable results to the calling application.

       DIALOG_VARS.insecure
              This corresponds to the command-line  option  "--insecure".   If
              true,  make  the  password widget friendlier but less secure, by
              echoing asterisks for each character.

       DIALOG_VARS.item_help
              This corresponds to the command-line option  "--item-help".   If
              true,  interpret the tags data for checklist, radiolist and menu
              boxes adding a column whose text is displayed in the bottom line
              of the screen, for the currently selected item.

       DIALOG_VARS.keep_tite
              This  is  set  by  the command-line option "--keep-tite" to tell
              dialog to not attempt  to  cancel  the  terminal  initialization
              (termcap ti/te) sequences which correspond to xterm's alternate-
              screen switching.  Normally dialog does this to avoid flickering
              when run several times in a script.

       DIALOG_VARS.keep_window
              This corresponds to the command-line option "--keep-window".  If
              true, do not remove/repaint the window on exit.  This is  useful
              for keeping the window contents visible when several widgets are
              run in the same process.  Note that curses will clear the screen
              when starting a new process.

       DIALOG_VARS.max_input
              This  corresponds to the command-line option "--max-input size".
              Limit input strings to the given size.  If  not  specified,  the
              limit is 2048.

       DIALOG_VARS.no_label
              This corresponds to the command-line option "--no-label string".
              The given string overrides the label used for "No" buttons.

              sage boxes, etc.  It true, that feature is disabled.  Note  that
              dialog will still wrap text, subject to the --cr-wrap option.

       DIALOG_VARS.nook

       DIALOG_VARS.ok_label
              This corresponds to the command-line option "--ok-label string".
              The given string overrides the label used for "OK" buttons.

       DIALOG_VARS.print_siz
              This corresponds to the command-line option "--print-size".   If
              true,  each widget prints its size to dialog's output when it is
              invoked.

       DIALOG_VARS.quoted

       DIALOG_VARS.separate_output
              This corresponds to the command-line option "--separate-output".
              If  true,  checklist  widgets  output result one line at a time,
              with no quoting.  This facilitates parsing by another program.

       DIALOG_VARS.single_quoted
              This corresponds to the command-line  option  "--single-quoted".
              If  true,  Use  single-quoting  as  needed  (and  no  quotes  if
              unneeded) for the output of checklist's as well as the item-help
              text.   If  this  option  is  not set, dialog uses double quotes
              around each item.  That requires occasional use  of  backslashes
              to make the output useful in shell scripts.

       DIALOG_VARS.size_err
              This  corresponds  to  the command-line option "--size-err".  If
              true, 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).

       DIALOG_VARS.sleep_secs
              This  corresponds  to  the  command-line  option "--sleep secs".
              This option is implemented in the main program, not the library.
              If  nonzero,  this is the number of seconds after to delay after
              processing a dialog box.

       DIALOG_VARS.tab_correct
              This corresponds to the command-line option "--tab-correct".  If
              true, convert each tab character of the text to one or more spa-
              ces.  Otherwise, tabs  are  rendered  according  to  the  curses
              library's interpretation.

       DIALOG_VARS.timeout_secs
              This  corresponds  to  the command-line option "--timeout secs".
              If nonzero, timeout input requests (exit with error code) if  no
              user response within the given number of seconds.

       DIALOG_VARS.title
              inputmenu  to  include  the  list of items as one of the states.
              This is useful as a visual aid, i.e., the cursor position  helps
              some users.

       DIALOG_VARS.yes_label
              This   corresponds   to  the  command-line  option  "--yes-label
              string".  The given string overrides the label  used  for  "Yes"
              buttons.

   WIDGETS
       Functions  that implement major functionality for the command-line dia-
       log program, e.g., widgets, have names beginning "dialog_".

       All dialog boxes have at least three parameters:

       title
            the caption for the box, shown on its top border.

       height
            the height of the dialog box.

       width
            the width of the dialog box.

       Other parameters depend on the box type.

       dialog_calendar
              implements the "--calendar" option.

              title  is the title on the top of the widget.

              subtitle
                     is the prompt text shown within the widget.

              height is the height excluding the fixed-height calendar grid.

              width  is the overall width of the box, which is adjusted up  to
                     the calendar grid's minimum width if needed.

              day    is  the  initial  day of the week shown, counting zero as
                     Sunday.  If the value is negative, the current day of the
                     week is used.

              month  is  the  initial month of the year shown, counting one as
                     January.  If the value is negative, the current month  of
                     the year is used.

              year   is the initial year shown.  If the value is negative, the
                     current year is used.

       dialog_checklist
              implements the "--checklist" and "--radiolist" options depending
              on the flag parameter.

                     is the minimum height to reserve for displaying the list.
                     If zero, it is computed based on  the  given  height  and
                     width.

              item_no
                     is the number of rows in items.

              items  is  an  array of strings which is viewed either as a list
                     of rows
                     tag item status

                     or
                     tag item status help

                     depending on whether dialog_vars.item_help is set.

              flag   is either FLAG_CHECK, for checklists, or  FLAG_RADIO  for
                     radiolists.

       dialog_dselect
              implements the "--dselect" option.

              title  is the title on the top of the widget.

              path   is  the preselected value to show in the input-box, which
                     is used also to set the directory- and file-windows.

              height is the height excluding the minimum needed  to  show  the
                     dialog  box  framework.   If zero, the height is based on
                     the screen size.

              width  is the desired width of the box.  If zero, the height  is
                     based on the screen size.

       dialog_editbox
              implements the "--editbox" option.

              title  is the title on the top of the widget.

              file   is the name of the file from which to read.

              height is the desired height of the box.  If zero, the height is
                     adjusted to use the available screen size.

              width  is the desired width of the box.  If zero, the height  is
                     adjusted to use the available screen size.

       dialog_form
              implements the "--form" option.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              item_no
                     is the number of rows in items.

              items  is  an  array of strings which is viewed either as a list
                     of rows
                     Name NameY NameX Text TextY TextX FLen ILen

                     or
                     Name NameY NameX Text TextY TextX FLen ILen Help

                     depending on whether dialog_vars.item_help is set.

       dialog_fselect
              implements the "--fselect" option.

              title  is the title on the top of the widget.

              path   is the preselected value to show in the input-box,  which
                     is used also to set the directory- and file-windows.

              height is  the  height  excluding the minimum needed to show the
                     dialog box framework.  If zero, the height  is  based  on
                     the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

       dialog_gauge
              implements the "--gauge" option.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

              percent
                     is the percentage to show in the progress bar.

       dialog_inputbox
              implements the "--inputbox" or "--password" option, depending on
              the value of password.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is

       dialog_menu
              implements  the  "--menu"  or  "--inputmenu" option depending on
              whether dialog_vars.input_menu is set.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

              menu_height
                     is the minimum height to reserve for displaying the list.
                     If  zero,  it  is  computed based on the given height and
                     width.

              item_no
                     is the number of rows in items.

              items  is an array of strings which is viewed either as  a  list
                     of rows
                     tag item

                     or
                     tag item help

                     depending on whether dialog_vars.item_help is set.

       dialog_mixedform
              implements the "--mixedform" option.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     adjusted to use the available screen size.

              width  is the desired width of the box.  If zero, the height  is
                     adjusted to use the available screen size.

              form_height
                     is the minimum height to reserve for displaying the list.
                     If zero, it is computed based on  the  given  height  and
                     width.

              item_no
                     is the number of rows in items.

              title  is the title on the top of the widget.

              cprompt
                     is the caption text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

              percent
                     is the percentage to show in the progress bar.

              item_no
                     is the number of rows in items.

              items  is an array of strings which is viewed as a list  of  tag
                     and item values.  The tag values are listed, one per row,
                     in the list at the top of the widget.

                     The item values are decoded: digits 0-9 are the following
                     strings

                     0      Succeeded

                     1      Failed

                     2      Passed

                     3      Completed

                     4      Checked

                     5      Done

                     6      Skipped

                     7      In Progress

                     8      (blank)

                     9      N/A

                     A string with a leading "-" character is centered, marked
                     with "%".  For example,  "-75"  is  displayed  as  "75%".
                     Other strings are displayed as is.

       dialog_msgbox
              implements  the  "--msgbox"  or  "--infobox" option depending on
              whether pauseopt is set.

              title  is the title on the top of the widget.

                     denoted a "msgbox", without an "OK" button, it is denoted
                     an "infobox".

       dialog_pause
              implements the "--pause" option.

              title  is the title on the top of the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is the desired width of the box.  If zero, the height  is
                     based on the screen size.

              seconds
                     is the timeout to use for the progress bar.

       dialog_progressbox
              implements the "--progressbox" option.

              title  is the title on the top of the widget.

              cprompt
                     is  the prompt text shown within the widget.  If empty or
                     null, no prompt is shown.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

       dialog_tailbox
              implements the "--tailbox" or "--tailboxbg" option depending  on
              whether bg_task is set.

              title  is the title on the top of the widget.

              file   is the name of the file to display in the dialog.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is the desired width of the box.  If zero, the height  is
                     based on the screen size.

              bg_task
                     if true, the window is added to the callback list in dia-
                     log_state, and the application will poll for  the  window
                     to  be updated.  Otherwise an "OK" button is added to the
                     window, and it will be closed when the  button  is  acti-
                     vated.

       dialog_textbox
       dialog_timebox
              implements the "--timebox" option.

              title  is the title on the top of the widget.

              subtitle
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is the desired width of the box.  If zero, the height  is
                     based on the screen size.

              hour   is the initial hour shown.  If the value is negative, the
                     current hour is used.

              minute is the initial minute shown.  If the value  is  negative,
                     the current minute is used.

              second is  the  initial second shown.  If the value is negative,
                     the current second is used.

       dialog_yesno
              implements the "--yesno" option.

              title  is the title on the top of the widget.

              cprompt
                     is the prompt text shown within the widget.

              height is the desired height of the box.  If zero, the height is
                     based on the screen size.

              width  is  the desired width of the box.  If zero, the height is
                     based on the screen size.

   UTILITY FUNCTIONS
       Most functions that implement lower-level functionality  for  the  com-
       mand-line dialog program or widgets, have names beginning "dlg_".  Bow-
       ing to longstanding usage, the functions that  initialize  the  display
       and end it are named init_dialog and end_dialog.

       The  only  non-widget function whose name begins with "dialog_" is dia-
       log_version, which returns the version  number  of  the  library  as  a
       string.

       Here is a brief summary of the utility functions and their parameters:

       dlg_add_callback
            Add  a callback, used to allow polling input from multiple tailbox
            widgets.

            DIALOG_CALLBACK *p
                 is the string to add.

       dlg_add_separator
            Add   an   output-separator   to   the    result    buffer    dia-
            log_vars.input_result.   If  dialog_vars.output_separator  is set,
            use that.  Otherwise, if dialog_vars.separate_output is  set,  use
            newline.  If neither is set, use a space.

       dlg_add_string
            Add  a  quoted  or  unquoted  string  to  the  result  buffer (see
            dlg_add_quoted) and dlg_add_result),  according  to  whether  dia-
            log_vars.quoted is true.

            char * string
                 is the string to add.

       dlg_align_columns
            Copy  and  reformat  an  array  of  pointers  to strings, aligning
            according to the  column  separator  dialog_vars.column_separator.
            If  no column separator is set, the array will be unmodified; oth-
            erwise it is copied and reformatted.

            Caveat: This function is only implemented for 8-bit characters.

            char **target
                 This is the array to reformat.  It points to the first string
                 to modify.

            int per_row
                 This is the size of the struct for each row of the array.

            int num_rows
                 This is the number of rows in the array.

       dlg_asciibox
            returns its parameter transformed to the corresponding "+" or "-",
            etc. for the line-drawing  characters  used  in  dialog.   If  the
            parameter is not a line-drawing or other special character such as
            ACS_DARROW, it returns 0.

       dlg_attr_clear
            Set window to the given attribute.

            WINDOW * win
                 is the window to update.

            int height
                 is the number of rows to update.

            int width
                 is the number of columns to update.

            chtype attr
                 is the attribute, e.g., A_BOLD.

            int * height
                 is the nominal height.

            int * width
                 is the nominal width.

            int boxlines
                 is the number of lines to reserve in the vertical direction.

            int mincols
                 is the minimum number of columns to use.

       dlg_auto_sizefile
            Like  dlg_auto_size,  but  use a file contents to decide how large
            the widget should be.

            const char * title
                 is the title string to display at the top of the widget.

            const char * file
                 is the name of the file.

            int * height
                 is the nominal height.  If it is -1, use the screen's  height
                 after     subtracting     dialog_vars.begin_y     if     dia-
                 log_vars.begin_set is true.

            int *width
                 is the nominal width.  If it is -1, use  the  screen's  width
                 after     subtracting     dialog_vars.begin_x     if     dia-
                 log_vars.begin_set is true.

            int boxlines
                 is the number of lines to reserve on the screen  for  drawing
                 boxes.

            int mincols
                 is the number of columns to reserve on the screen for drawing
                 boxes.

       dlg_beeping
            If dialog_vars.beep_signal is nonzero, this calls  beep  once  and
            sets dialog_vars.beep_signal to zero.

       dlg_boxchar
            returns its parameter transformed as follows:

            -  if  neither dialog_vars.ascii_lines nor dialog_vars.no_lines is
               set.

            -  if dialog_vars.ascii_lines is set,  returns  the  corresponding
               "+"  or  "-", etc. for the line-drawing characters used in dia-
               log.

            int width
                 is the width of the widget.

       dlg_box_y_ordinate
            returns a suitable y-ordinate (row) for a  new  widget.   If  dia-
            log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center
            the widget on the screen (using the height parameter).

            int height
                 is the height of the widget.

       dlg_button_count
            Count the buttons in the list.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

       dlg_button_layout
            Make  sure  there is enough space for the buttons by computing the
            width required for their labels, adding margins and limiting based
            on the screen size.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

            int * limit
                 the function sets the referenced limit to the width  required
                 for  the widest label (limited by the screen size) if that is
                 wider than the passed-in limit.

       dlg_button_sizes
            Compute the size of the button array in columns.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

            int vertical
                 is true if the buttons are arranged in a column rather than a
                 row.

            int * longest
                 Return the total number of columns in  the  referenced  loca-
                 tion.

            int * length
                 Return  the  longest button's columns in the referenced loca-
                 tion.

       dlg_button_x_step
            Compute the step-size needed between elements of the button array.

                 store the left+right total margins (for the list of  buttons)
                 in the referenced location.

            int * step
                 store the step-size in the referenced location.

       dlg_button_to_char
            Find  the first uppercase character in the label, which we may use
            for an abbreviation.  If the label is empty,  return  -1.   If  no
            uppercase  character  is  found,  return  0.  Otherwise return the
            uppercase character.

            const char * label
                 is the label to test.

       dlg_calc_list_width
            Calculate the minimum width for the list,  assuming  none  of  the
            items are truncated.

            int item_no
                 is the number of items.

            DIALOG_LISTITEM * items
                 contains  a  name  and  text  field,  e.g., for checklists or
                 radiobox lists.  The function returns the sum of  the  widest
                 columns needed for of each of these fields.

       dlg_calc_listh
            Calculate new height and list_height values.

            int * height
                 on  input,  is the height without adding the list-height.  On
                 return, this contains the total list-height and is the actual
                 widget's height.

            int * list_height
                 on input, is the requested list-height.  On return, this con-
                 tains the number of rows available for  displaying  the  list
                 after  taking  into  account  the  screen  size  and the dia-
                 log_vars.begin_set and dialog_vars.begin_y variables.

            int item_no
                 is the number of items in the list.

       dlg_calc_listw
            This function is obsolete, provided for library-compatibility.  It
            is replaced by dlg_calc_list_width.

            int item_no
                 is the number of items.

            char ** items
                 is a list of character pointers.

                 is the character to find.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

       dlg_checklist
            This  entrypoint provides the --checklist or --radiolist function-
            ality without the  limitations  of  dialog's  command-line  syntax
            (compare to dialog_checklist).

            const char * title
                 is the title string to display at the top of the widget.

            const char * cprompt
                 is the prompt text shown within the widget.

            int height
                 is  the  desired  height  of the box.  If zero, the height is
                 adjusted to use the available screen size.

            int width
                 is the desired width of the box.   If  zero,  the  height  is
                 adjusted to use the available screen size.

            int list_height
                 is the minimum height to reserve for displaying the list.  If
                 zero, it is computed based on the given height and width.

            int item_no
                 is the number of items.

            DIALOG_LISTITEM * items
                 This is a list of the items to display in the checklist.

            const char * states
                 This is a list of characters to display for the given states.
                 Normally  a checklist provides true (1) and false (0) values,
                 which the widget displays as "*" and space, respectively.  An
                 application  may set this parameter to an arbitrary null-ter-
                 minated string.  The widget determines the number  of  states
                 from  the  length  of this string, and will cycle through the
                 corresponding display characters  as  the  user  presses  the
                 space-bar.

            int flag
                 This  is should be one of FLAG_CHECK or FLAG_RADIO, depending
                 on whether the widget should act as a checklist or radiobox.

            int * current_item
                 The widget sets the referenced location to the index  of  the
                 current display item (cursor) when it returns.

       dlg_clear

       dlg_count_columns
            Returns the number of columns used for a string.  This is not nec-
            essarily the number of bytes in a string.

            const char * string
                 is the string to measure.

       dlg_count_wchars
            Returns the number of wide-characters in the string.

            const char * string
                 is the string to measure.

       dlg_create_rc
            Create a configuration file, i.e., write internal tables to a file
            which can be read back by dialog as an rc-file.

            const char * filename
                 is the name of the file to write to.

       dlg_ctl_size
            If dialog_vars.size_err is true, check if the given window size is
            too large to fit on the screen.  If so, exit with an error report-
            ing the size of the window.

            int height
                 is the window's height

            int width
                 is the window's width

       dlg_default_formitem
            If  dialog_vars.default_item is not null, find that name by match-
            ing the name field in the list of form items.   If  found,  return
            the index of that item in the list.  Otherwise, return zero.

            DIALOG_FORMITEM * items
                 is the list of items to search.  It is terminated by an entry
                 with a null name field.

       dlg_default_item
            This function is obsolete, provided for library-compatibility.  It
            is replaced by dlg_default_formitem and dlg_default_listitem.

            char ** items
                 is the list of items to search.

            int llen
                 is  the number of items in each group, e.g., the second array
                 index.

       dlg_defaultno_button
            If dialog_vars.defaultno is true, and dialog_vars.nocancel is not,
            dialog can test this and add a separator.

       dlg_draw_arrows
            Draw up/down arrows on a window, e.g., for scrollable  lists.   It
            calls  dlg_draw_arrows2  using  the menubox_color and menubox_bor-
            der_color attributes.

            WINDOW * dialog
                 is the window on which to draw an arrow.

            int top_arrow
                 is true if an up-arrow should be drawn at the top of the win-
                 dow.

            int bottom_arrow
                 is true if an down-arrow should be drawn at the bottom of the
                 window.

            int x
                 is the zero-based column within the window on which  to  draw
                 arrows.

            int top
                 is  the zero-based row within the window on which to draw up-
                 arrows as well as a horizontal line to show the window's top.

            int bottom
                 is the zero-based row within the  window  on  which  to  draw
                 down-arrows as well as a horizontal line to show the window's
                 bottom.

       dlg_draw_arrows2
            Draw up/down arrows on a window, e.g., for scrollable lists.

            WINDOW * dialog
                 is the window on which to draw an arrow.

            int top_arrow
                 is true if an up-arrow should be drawn at the top of the win-
                 dow.

            int bottom_arrow
                 is true if an down-arrow should be drawn at the bottom of the
                 window.

            int x
                 is the zero-based column within the window on which  to  draw
                 arrows.

            int top
                 is  the zero-based row within the window on which to draw up-
                 arrows as well as a horizontal line to show the window's top.

            int bottom
            row  of  buttons.   It  is  designed to merge with an existing box
            around the whole window, so it uses tee-elements rather than  cor-
            ner-elements on the top corners of this box.

            WINDOW * win
                 is the window to update.

       dlg_draw_box
            Draw a rectangular box with line drawing characters.

            WINDOW * win
                 is the window to update.

            int y
                 is the top row of the box.

            int x
                 is the left column of the box.

            int height
                 is the height of the box.

            int width
                 is the width of the box.

            chtype boxchar
                 is  used  to  color  the right/lower edges.  It also is fill-
                 color used for the box contents.

            chtype borderchar
                 is used to color the upper/left edges.

       dlg_draw_buttons
            Print a list of buttons at the given position.

            WINDOW * win
                 is the window to update.

            int y
                 is the starting row.

            int x
                 is the starting column.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

            int selected
                 is the index within the list of the selected button.

            int vertical
                 is true if the buttons are arranged in a column rather than a
                 row.

            int height
                 is the height of the window.

            int width
                 is the width of the window.

            int y
                 is the top row of the window.

            int x
                 is the left column of the window.

       dlg_draw_title
            Draw a title centered at the top of the window.

            WINDOW * win
                 is the window to update.

            const char * title
                 is the title string to display at the top of the widget.

       dlg_dump_keys
            Write  all user-defined key-bindings to the given stream, e.g., as
            part of dlg_create_rc.

            FILE * fp
                 is the stream on which to write the bindings.

       dlg_edit_offset
            Given the character-offset in the string, returns the display-off-
            set  where  dialog  should  position the cursor.  In this context,
            "characters" may be multicolumn, since the string can be a  multi-
            byte character string.

            char * string
                 is the string to analyze

            int offset
                 is the character-offset

            int x_last
                 is  a  limit  on the column positions that can be used, e.g.,
                 the window's size.

       dlg_edit_string
            Updates the string and  character-offset,  given  various  editing
            characters or literal characters which are inserted at the charac-
            ter-offset.  Returns true if an editing change was made  (and  the
            display  should  be  updated),  and false if the key was something
            like KEY_ENTER, which is a non-editing action outside  this  func-
            tion.

            char * string
                 is  used  in a special loop case by calling code to force the
                 return value of this function when a function-key code  0  is
                 passed in.

       dlg_exit
            Given  an  internal exit code, check if the corresponding environ-
            ment variable is set.  If so, remap the exit  code  to  match  the
            environment  variable.   Finally call exit with the resulting exit
            code.

            int code
                 is the internal exit code, e.g., DLG_EXIT_OK,  which  may  be
                 remapped.

            The  dialog  program  uses this function to allow shell scripts to
            remap the exit codes so they can distinguish ESC from ERROR.

       dlg_exit_buttoncode
            Map the given button index for dlg_exit_label into dialog's  exit-
            code.

            int button
                 is the button index

       dlg_exit_label
            Return  a  list  of  button labels.  If dialog_var.extra_button is
            true, return the result of  dlg_ok_labels.   Otherwise,  return  a
            list with the "Exit" label and (if dialog_vars.help_button is set)
            the "Help" button as well.

       dlg_exiterr
            Quit program killing all tailboxbg widgets.

            const char * fmt
                 is the format of the printf-like message to write.

            are the variables to apply to the fmt format.

       dlg_find_index
            Given the character-offset to find in the list, return the  corre-
            sponding array index.

            const int *list
                 contains  a  list  of character-offsets, i.e., indices into a
                 string that denote the beginning of multibyte characters.

            int limit
                 is the last index into list to search.

            int to_find
                 is the character-offset to find.

       dlg_flush_getc
            Cancel the local data saved by dlg_last_getc.
                 points.  The dlg_editbox function may  reallocate  the  array
                 and the strings.

            int * rows
                 points  to  the nominal length of list.  The referenced value
                 is updated iflist is reallocated.

            int height
                 is the desired height of the box.  If  zero,  the  height  is
                 adjusted to use the available screen size.

            int width
                 is  the  desired  width  of  the box.  If zero, the height is
                 adjusted to use the available screen size.

       dlg_form
            This entrypoint provides the --form functionality without the lim-
            itations of dialog's command-line syntax (compare to dialog_form).

            const char * title
                 is the title string to display at the top of the widget.

            const char * cprompt
                 is the prompt text shown within the widget.

            int height
                 is  the  desired  height  of the box.  If zero, the height is
                 adjusted to use the available screen size.

            int width
                 is the desired width of the box.   If  zero,  the  height  is
                 adjusted to use the available screen size.

            int form_height
                 is the minimum height to reserve for displaying the list.  If
                 zero, it is computed based on the given height and width.

            int item_no
                 is the number of items.

            DIALOG_FORMITEM * items
                 This is a list of the items to display in the form.

            int * current_item
                 The widget sets the referenced location to the index  of  the
                 current display item (cursor) when it returns.

       dlg_free_columns
            Free data allocated by dlg_align_columns.

            char **target
                 This  is  the  array which was reformatted.  It points to the
                 first string to free.

       dlg_getc
            Read a character from the given window.   Handle  repainting  here
            (to  simplify things in the calling application).  Also, if input-
            callback(s) are set up, poll the corresponding  files  and  handle
            the  updates,  e.g.,  for  displaying a tailbox.  Returns the key-
            code.

            WINDOW * win
                 is the window within which to read.

            int * fkey
                 as a side-effect, set this to true if the key-code is  really
                 a function-key.

       dlg_getc_callbacks
            passes the given key-code ch to the current window that has estab-
            lished a callback.  If the callback returns zero,  remove  it  and
            try the next window.  If no more callbacks remain, return.  If any
            callbacks were found, return true, otherwise false.

            int ch
                 is the key-code

            int fkey
                 is true if the key is a function-key

            int * result
                 is used to pass an exit-code to the caller, which should pass
                 that via dlg_exit.

       dlg_index_columns
            Build  a  list  of  the  display-columns  for  the given multibyte
            string's characters.

            const char * string
                 is the string to analyze

       dlg_index_wchars
            Build an index of the wide-characters in the string, so the caller
            can easily tell which byte-offset begins a given wide-character.

            const char * string
                 is the string to analyze

       dlg_item_help
            Draw the string for the dialog_vars.item_help feature.

            char * txt
                 is the help-message

       dlg_killall_bg
            If dialog has callbacks active, purge the list of all that are not
            marked to keep in the background.  If any remain, run those  in  a
            background process.
            const char * string
                 is the string to analyze

            int limit
                 is the column limit

            int offset
                 is the starting offset from which analysis should continue

       dlg_lookup_key
            Check  for  a key-binding.  If there is no binding associated with
            the widget, it simply returns the given curses-key.  Otherwise, it
            returns the result of the binding

            WINDOW * win
                 is the window on which the binding is checked

            int curses_key
                 is the curses key-code

            int * dialog_key
                 is  the corresponding dialog internal code (see DLG_KEYS_ENUM
                 in dlg_key.h).

       dlg_max_input
            Limit the parameter according to dialog_vars.max_input

            int max_len
                 is the value to limit

       dlg_match_char
            Match a given character  against  the  beginning  of  the  string,
            ignoring  case  of  the given character.  The matching string must
            begin with an uppercase character.

            int ch
                 is the character to check

            const char * string
                 is the string to search

       dlg_menu
            This entrypoint provides the --menu functionality without the lim-
            itations of dialog's command-line syntax (compare to dialog_menu).

            const char * title
                 is the title string to display at the top of the widget.

            const char * cprompt
                 is the prompt text shown within the widget.

            int height
                 is  the  desired  height  of the box.  If zero, the height is
                 adjusted to use the available screen size.

            DIALOG_LISTITEM * items
                 This is a list of the items to display in the form.

            int * current_item
                 The widget sets the referenced location to the index  of  the
                 current display item (cursor) when it returns.

            DIALOG_INPUTMENU rename_menutext

       dlg_move_window
            Moves/resizes the given window to the given position and size.

            WINDOW *win
                 is the window to move/resize.

            WINDOW *height
                 is the height of the resized window.

            WINDOW *width
                 is the width of the resized window.

            WINDOW *y
                 y-ordinate to use for the repositioned window.

            WINDOW *x
                 x-ordinate to use for the repositioned window.

       dlg_mouse_bigregion
            Retrieve the big-region under the pointer.

            int y
                 is the row on which the mouse click occurred

            int x
                 is the column on which the mouse click occurred

       dlg_mouse_free_regions
            Free the memory associated with mouse regions.

       dlg_mouse_mkbigregion
            Creates  a region on which the mouse-clicks will return a specifed
            code.

            int y
                 is the top-row of the region.

            int x
                 is the left-column of the region.

            int height
                 is the height of the region.

            int width
                 is the width of the region.
                 is  used  to  determine  how the mouse position is translated
                 into a code (like a function-key):

                 1      index by lines

                 2      index by columns

                 3      index by cells

       dlg_mouse_mkregion

            int y
                 is the top-row of the region.

            int x
                 is the left-column of the region.

            int height
                 is the height of the region.

            int width
                 is the width of the region.

            int code
                 is a code used to make the region unique within a widget

       dlg_mouse_region
            Retrieve the frame under the mouse pointer

            int y
                 is the row of the mouse-click

            int x
                 is the column of the mouse-click

       dlg_mouse_setbase
            Sets a base for subsequent calls to  dlg_mouse_mkregion,  so  they
            can make regions relative to the start of a given window.

            int x
                 is the left-column for the base

            int y
                 is the top-row for the base

       dlg_mouse_wgetch
            is a wrapper for dlg_getc which additionally maps mouse-clicks (if
            the curses library supports  those)  into  extended  function-keys
            which encode the position according to the mode in dlg_mouse_mkbi-
            gregion.  Returns the corresponding key-code.

            WINDOW * win
                 is the window on which to perform the input

                 actual or extended (mouse) function-key.

       dlg_need_separator
            Check if  an  output-separator  is  needed.   If  dialog_vars.out-
            put_separator   is   set,   return   true.    Otherwise,  if  dia-
            log_vars.input_result  is  nonempty,  return  true.   If  neither,
            return false.

       dlg_new_modal_window
            Create  a  modal  window, optionally with a shadow.  The shadow is
            created if dialog_state.use_shadow is true.

            WINDOW * parent
                 is the parent window (usually the top-level window of a  wid-
                 get)

            int height
                 is the window's height

            int width
                 is the window's width

            int y
                 is the window's top-row

            int x
                 is the window's left-column

       dlg_new_window
            Create  a window, optionally with a shadow.  The shadow is created
            if dialog_state.use_shadow is true.

            int height
                 is the window's height

            int width
                 is the window's width

            int y
                 is the window's top-row

            int x
                 is the window's left-column

       dlg_next_button
            Return the next index in the list of labels.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

            int button
                 is the current button-index.

            Map  the  given button index for dlg_ok_labels into dialog's exit-
            code.

            int button
                 is the button-index (which is not necessarily the same as the
                 index in the list of labels).

       dlg_ok_label
            Returns a list with the "Ok" label, and if dialog_vars.help_button
            is true, the "Help" label as well.

       dlg_ok_labels
            Return a list of button labels for the OK/Cancel group of widgets.

       dlg_ordinate
            Decode the string as an integer, decrement if greater than zero to
            make a curses-ordinate from a dialog-ordinate.

       dlg_parse_bindkey
            Parse  the  parameters of the "bindkeys" configuration-file entry.
            This expects widget name which may be "*", followed by curses  key
            definition and then dialog key definition.

            char * params
                 is the parameter string to parse.

       dlg_parse_rc
            Parse the configuration file and set up variables.

       dlg_prev_button
            Return the previous index in the list of labels.

            const char ** labels
                 is a list of (pointers to) button labels terminated by a null
                 pointer.

            int button
                 is the current button index

       dlg_print_line
            Print one line of the prompt in the window within  the  limits  of
            the  specified right margin.  The line will end on a word boundary
            and a pointer to the start of the next line is returned, or a NULL
            pointer if the end of *prompt is reached.

            WINDOW *win
                 is the window to update.

            chtype *attr
                 holds  the starting attributes, and is updated to reflect the
                 final attributes applied to the string.

            const char *prompt
                 is the string to print

            int current
                 is the current index

            int extra
                 if negative provides a way to enumerate extra active areas on
                 the widget.

       dlg_print_autowrap
            Print  a  string of text in a window, automatically wrap around to
            the next line if the string is too long to fit on one line.   Note
            that the string may contain embedded newlines.

            WINDOW * win
                 is the window to update.

            const char * prompt
                 is the string to print

            int height
                 is the nominal height the wrapped string is limited to

            int width
                 is the width that the wrapping should occur in

       dlg_print_size
            If  dialog_vars.print_siz  is  true,  print the given height/width
            (from a widget) to dialog_state.output, e.g., Size: height, width.

            int height
                 is the window's height

            int width
                 is the window's width

       dlg_print_text
            Print up to cols columns from text, optionally rendering  dialog's
            escape sequences for attributes and color.

            WINDOW * win
                 is the window to update.

            const char * txt
                 is the string to print

            int col
                 is the column limit

            chtype * attr
                 holds  the starting attributes, and is updated to reflect the
                 final attributes applied to the string.

       dlg_put_backtitle
            Display the background title if dialog_vars.backtitle is non-null.
                 get).

            const char ** buttons
                 is the list of buttons

       dlg_register_window
            For a given named widget's window, associate a binding table.

            WINDOW * win
                 is the window with which to associate the buttons

            const char * name
                 is the widget's binding name (usually the name  of  the  wid-
                 get).

            DLG_KEYS_BINDING * binding
                 is the binding table

       dlg_remove_callback
            Remove a callback.

            DIALOG_CALLBACK * p
                 contains the callback information.

       dlg_restore_vars
            Restore  dialog's  variables  from  the  given  variable (see dia-
            log_save_vars).

            DIALOG_VARS * save
                 is the variable from which to restore.

       dlg_result_key
            Test a dialog internal keycode to see if it corresponds to one  of
            the  push buttons on the widget such as "OK".  This is only useful
            if there are user-defined key bindings, since there are no  built-
            in  bindings  that map directly to DLGK_OK, etc.  Return true if a
            mapping was done.

            int dialog_key
                 is the dialog key to test

            int fkey
                 is true if this is a function key

            int * resultp
                 store the result of the mapping in the referenced location.

       dlg_save_vars
            Save  dialog's  variables  into  the  given  variable  (see   dia-
            log_restore_vars).

            DIALOG_VARS * save
                 is the variable into which to save.

       dlg_set_result
            Setup a fixed-buffer for the result in dialog_vars.input_result

            const char * string
                 is the new contents for the result

       dlg_show_string
            Displays the string, shifted as necessary, to fit within  the  box
            and show the current character-offset.

            WINDOW * win
                 is the window within which to display

            const char * string
                 is the string to display

            int offset
                 is the starting (character, not bytes) offset

            chtype attr
                 is the window attribute to use for the string

            int y_base
                 beginning row on screen

            int x_base
                 beginning column on screen

            int x_last
                 number of columns on screen

            bool hidden
                 if true, do not echo input

            bool force
                 if true, force repaint

       dlg_strclone
            duplicate the string, like strdup.

            const char * cprompt
                 is the string to duplicate

       dlg_strcmp
            compare two strings, ignoring case.

            const char * a
                 is one string

            const char * b
                 is the other string

       dlg_sub_window
            create a subwindow, e.g., for an input area of a widget

            int x
                 is the subwindow's left-column

       dlg_tab_correct_str
            If  the  dialog_vars.tab_correct  is  true, convert tabs to single
            spaces.  Return the converted result.  The caller  is  responsible
            for freeing the string.

            char * prompt
                 is the string to convert

       dlg_trace
            If  the  parameter  is non-null, opens a trace file with that name
            and stores the file pointer in dialog_state.trace.

       dlg_trace_chr
            If dialog_state.trace is set,  translate  the  parameters  into  a
            printable representation, log it on a "chr" line.

            int ch
                 is the nominal keycode value.

            int fkey
                 is  nonzero  if  the value is really a function key.  Some of
                 these may be values declared in the DLG_KEYS_ENUM.

       dlg_trace_win
            If dialog_state.trace is set, log a printable picture of the given
            window.

       dlg_trim_string
            Change  embedded  "\n"  substrings  to '\n' characters and tabs to
            single spaces.  If there are no "\n"s,  the  function  strips  all
            extra  spaces,  for justification.  If it has "\n"'s, the function
            preserves extra spaces.  If dialog_vars.cr_wrap is set, the  func-
            tion preserves '\n's.

            char * src
                 is the string to trim

       dlg_unregister_window
            Remove the bindings for a given window.

            WINDOW * win
                 is the window from which to remove bindings

       dlg_yes_buttoncode
            Map  the given button index for dlg_yes_labels into dialog's exit-
            code.

            int button
                 is the button index
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2014 Hurricane Electric. All Rights Reserved.