dialog man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

DIALOG(3)							     DIALOG(3)

NAME
       dialog - widgets and utilities for the dialog program

SYNOPSIS
       cc [ flag ... ] file ... -ldialog [ library ... ]
	  or
       cc $(dialog-config --cflags) file ... $(dialog-config --libs) ]

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

       Here is a dialog version of Hello World:
	      int main(void)
	      {
		   int status;
		   init_dialog(stdin, stdout);
		   status = dialog_yesno(
			     "Hello, in dialog-format",
			     "Hello World!",
			     0, 0);
		   end_dialog();
		   return status;
	      }

DEFINITIONS
       Exit  codes  (passed  back to the main program for its use) are defined
       with a "DLG_EXIT_ prefix.  The efined 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.all_subwindows
	      This is a linked list of all subwindows created by the  library.
	      The  dlg_del_window  function uses this to free storage for sub‐
	      windows when deleting a window.

       DIALOG_STATE.all_windows
	      This is a linked list of all windows  created  by	 the  library.
	      The  dlg_del_window  function  uses this to locate windows which
	      may be redrawn after deleting a window.

       DIALOG_STATE.aspect_ratio
	      This corresponds to the  command-line  option  "--aspect-ratio".
	      The value gives the application some control over the box dimen‐
	      sions 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 high.

       DIALOG_STATE.finish_string
	      When set to true, this allows calls to dlg_finish_string to dis‐
	      card  the corresponding data which is created to speed up layout
	      computations for the given string parameter.  The	 gauge	widget
	      uses this feature.

       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.no_mouse
	      This  corresponds	 to  the command-line option "--no-mouse".  If
	      true, dialog will not  initialize	 (and  enable)	the  mouse  in
	      init_dialog.

       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.

       DIALOG_STATE.tab_len
	      This  corresponds to the command-line option "--tab-len number".
	      Specify the number of spaces that a tab  character  occupies  if
	      the "--tab-correct" option is given.  The default is 8.

       DIALOG_STATE.trace_output
	      This  corresponds to the command-line option "--trace file".  It
	      is the file pointer to which trace messages are written.

       DIALOG_STATE.use_colors
	      This is set in init_dialog if the curses implementation supports
	      color.

       DIALOG_STATE.use_scrollbar
	      This  corresponds	 to the command-line option "--scrollbar".  If
	      true, draw a scrollbar to make  windows  holding	scrolled  data
	      more readable.

       DIALOG_STATE.use_shadow
	      This corresponds to the command-line option "--no-shadow".  This
	      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
	      This corresponds to the command-line option "--ascii-lines.   It
	      causes  line-drawing to be done with ASCII characters, e.g., "+"
	      and "-".	See DIALOG_VARS.no_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
	      the following character, which tells dialog  to  set  colors  or
	      video attributes: 0 through 7 are the ANSI codes used in curses:
	      black, red, green, yellow, blue, magenta, cyan and white respec‐
	      tively.	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".

       DIALOG_VARS.column_separator
	      This corresponds to the  command-line  option  "--column-separa‐
	      tor".   Dialog splits data for radio/checkboxes and menus on the
	      occurrences of the given string, and aligns the split data  into
	      columns.

       DIALOG_VARS.cr_wrap
	      This  corresponds	 to  the  command-line option "--cr-wrap".  If
	      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.date_format
	      This  corresponds	 to  the  command-line	option	"--date-format
	      string".	If the host provides strftime, and the value  is  non‐
	      null, the calendar widget uses this to format its output.

       DIALOG_VARS.default_button
	      This is set by the command-line option "--default-button.	 It is
	      used by dlg_default_button.

       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
	      --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  dialog's output after the token "HELP".  Otherwise,
	      the return  status  will	indicate  that	the  Help  button  was
	      pressed, and no message printed.

       DIALOG_VARS.help_file
	      This  corresponds	 to  the command-line option "--hfile string".
	      The given filename is passed to dialog_helpfile  when  the  user
	      presses F1.

       DIALOG_VARS.help_label
	      This   corresponds  to  the  command-line	 option	 "--help-label
	      string".	The given string overrides the label used  for	"Help"
	      buttons.

       DIALOG_VARS.help_line
	      This  corresponds	 to  the command-line option "--hline string".
	      The given string is displayed in the bottom of  dialog  windows,
	      like a subtitle.

       DIALOG_VARS.help_status
	      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.help_tags
	      This  corresponds	 to the command-line option "--help-tags".  If
	      true, dlg_add_help_formitem and  dlg_add_help_listitem  use  the
	      item's  tag value consistently rather than using the tag's help-
	      text value when DIALOG_VARS.item_help is set.

       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
	      This may be either a user-supplied buffer, or a  buffer  dynami‐
	      cally    allocated   by	the   library,	 depending   on	  DIA‐
	      LOG_VARS.input_length:

	      ·	  If DIALOG_VARS.input_length is zero, this is	a  pointer  to
		  user	buffer	(on the stack, or static).  The buffer size is
		  assumed to be MAX_LEN, which is defined in <dialog.h>.

	      ·	  When DIALOG_VARS.input_length is nonzero, this is a  dynami‐
		  cally-allocated  buffer used by the widgets to return print‐
		  able results to the calling application.

	      Certain widgets copy a result to this buffer.  If the pointer is
	      NULL,  or if the length is insufficient for the result, then the
	      dialog library allocates a buffer which  is  large  enough,  and
	      sets  DIALOG_VARS.input_length.	Callers	 should check for this
	      case if they have supplied their own buffer.

       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.in_helpfile
	      This variable is used to prevent	dialog_helpfile	 from  showing
	      anything, e.g., if F1 were pressed within a help-file display.

       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.last_key
	      This corresponds to the command-line option "--last-key".

       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_items
	      This corresponds to the command-line option "--no-items".	  Some
	      widgets  (checklist,  inputmenu, radiolist, menu) display a list
	      with two columns (a  "tag"  and  "item",	i.e.,  "description").
	      This  tells  dialog to read shorter rows from data, omitting the
	      "list".

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

       DIALOG_VARS.no_lines
	      This  corresponds	 to  the  command-line option "--no-lines.  It
	      suppresses line-drawing.	See DIALOG_VARS.ascii_lines.

       DIALOG_VARS.no_nl_expand
	      This corresponds to the  command-line  option  "--no-nl-expand".
	      If  false, dlg_trim_string converts literal "\n" substrings in a
	      message into newlines.

       DIALOG_VARS.no_tags
	      This corresponds to the command-line option  "--no-tags".	  Some
	      widgets  (checklist,  inputmenu, radiolist, menu) display a list
	      with two columns (a "tag" and "item", also  known	 as  "descrip‐
	      tion").	The  tag is useful for scripting, but may not help the
	      user.  The --no-tags option (from Xdialog) may be used  to  sup‐
	      press the column of tags from the display.

	      Normally	dialog	allows	you  to quickly move to entries on the
	      displayed list, by matching a  single  character	to  the	 first
	      character	 of the tag.  When the --no-tags option is given, dia‐
	      log matches against the first character of the description.   In
	      either case, the matchable character is highlighted.

	      Here  is	a  table  showing  how the no_tags and no_items values
	      interact:

	      Widget	  Fields Shown	 Fields Read   .no_items   .no_tags
	      ──────────────────────────────────────────────────────────────
	      buildlist	  item		 tag,item	   0	      0*
	      buildlist	  item		 tag,item	   0	      1
	      buildlist	  tag		 tag		   1	      0*
	      buildlist	  tag		 tag		   1	      1
	      checklist	  tag,item	 tag,item	   0	      0
	      checklist	  item		 tag,item	   0	      1
	      checklist	  tag		 tag		   1	      0
	      checklist	  tag		 tag		   1	      1
	      inputmenu	  tag,item	 tag,item	   0	      0
	      inputmenu	  item		 tag,item	   0	      1
	      inputmenu	  tag		 tag		   1	      0
	      inputmenu	  tag		 tag		   1	      1
	      menu	  tag,item	 tag,item	   0	      0
	      menu	  item		 tag,item	   0	      1
	      menu	  tag		 tag		   1	      0
	      menu	  tag		 tag		   1	      1
	      radiolist	  tag,item	 tag,item	   0	      0
	      radiolist	  item		 tag,item	   0	      1
	      radiolist	  tag		 tag		   1	      0
	      radiolist	  tag		 tag		   1	      1
	      treeview	  item		 tag,item	   0	      0*
	      treeview	  item		 tag,item	   0	      1
	      treeview	  tag		 tag		   1	      0*

	      treeview	  tag		 tag		   1	      1
	      ──────────────────────────────────────────────────────────────

	      * Xdialog does not display the  tag  column  for	the  analogous
		buildlist  and	treeview widgets.  Dialog does the same on the
		command-line.  However the library interface defaults to  dis‐
		playing	 the  tag column.  Your application can enable or dis‐
		able the tag column as needed for each widget.

       DIALOG_VARS.nocancel
	      This corresponds to the command-line option  "--no-cancel".   If
	      true,  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.

       DIALOG_VARS.nocollapse
	      This  corresponds	 to  the  command-line option "--no-collapse".
	      Normally dialog converts tabs to	spaces	and  reduces  multiple
	      spaces  to  a single space for text which is displayed in a mes‐
	      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
	      This  corresponds	 to  the  command-line option "--nook.	Dialog
	      will suppress the "ok" (or "yes") button from the widget.

       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
	      This corresponds to the command-line option "--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.  The latter requires occasional use of back‐
	      slashes 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.time_format
	      This  corresponds	 to  the  command-line	option	"--time-format
	      string".	 If  the host provides strftime, and the value is non‐
	      null, the timebox widget uses this to format its output.

       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
	      This corresponds to the  command-line  option  "--title  title".
	      Specifies	 a title string to be displayed at the top of the dia‐
	      log box.

       DIALOG_VARS.trim_whitespace
	      This corresponds to the command-line option "--trim".  If	 true,
	      eliminate	 leading  blanks,  trim	 literal newlines and repeated
	      blanks from message text.

       DIALOG_VARS.visit_items
	      This corresponds to  the	command-line  option  "--visit-items".
	      Modify   the   tab-traversal   of	  the	list-oriented  widgets
	      (buildlist, checklist, radiobox, menubox, inputmenu,  and	 tree‐
	      view)  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_buildlist
	      implements the "--buildlist" option.

	      const char * title
		   is the title on 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 rows in items.

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

	      int order_mode
		   is reserved for future enhancements

       dialog_calendar
	      implements the "--calendar" option.

	      const char * title
		   is the title on the top of the widget.

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

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

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

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

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

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

	      const char * title
		   is the title on 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 rows in items.

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

	      const char * title
		   is the title on the top of the widget.

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

	      int height
		   is the height excluding the minimum needed to show the dia‐
		   log box framework.  If zero, the height  is	based  on  the
		   screen size.

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

       dialog_editbox
	      implements the "--editbox" option.

	      const char * title
		   is the title on the top of the widget.

	      const char * file
		   is the name of the file from which to read.

	      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.

       dialog_form
	      implements the "--form" option.

	      const char * title
		   is the title on 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 rows in items.

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

	      const char * title
		   is the title on the top of the widget.

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

	      int height
		   is the height excluding the minimum needed to show the dia‐
		   log	box  framework.	  If  zero, the height is based on the
		   screen size.

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

       dialog_gauge
	      implements  the  "--gauge"  option.  Alternatively, a simpler or
	      customized gauge widget can be setup  using  dlg_allocate_gauge,
	      dlg_reallocate_gauge, dlg_update_gauge and dlg_free_gauge.

	      const char * title
		   is the title on 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
		   based on the screen size.

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

	      int percent
		   is the percentage to show in the progress bar.

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

	      const char * title
		   is the title on 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
		   based on the screen size.

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

	      const char * init
		   is the initial value of the	input  box,  whose  length  is
		   taken into account when auto-sizing the width of the dialog
		   box.

	      int password
		   if true, causes typed input to be echoed as asterisks.

       dialog_helpfile
	      implements the "--hfile" option.

	      const char * title
		   is the title on the top of the widget.

	      const char * file
		   is the name of a file containing the text to display.  This
		   function  is	 internally  bound  to	F1 (function key "1"),
		   passing dialog_vars.help_file as a parameter.   The	dialog
		   program  sets  that	variable  when	the  --hfile option is
		   given.

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

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

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

	      const char * title
		   is the title on 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
		   based on the screen size.

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

	      int menu_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 rows in items.

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

	      const char * title
		   is the title on 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 rows in items.

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

		   or
		   Name NameY NameX Text TextY TextX FLen ILen Ityp Help

		   depending on whether dialog_vars.item_help is set.

       dialog_mixedgauge
	      implements the "--mixedgauge" option

	      const char * title
		   is the title on the top of the widget.

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

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

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

	      int percent
		   is the percentage to show in the progress bar.

	      int item_no
		   is the number of rows in items.

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

	      const char * title
		   is the title on 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
		   based on the screen size.

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

	      int pauseopt
		   if  true, an "OK" button will be shown, and the dialog will
		   wait for it to  complete.   With  an	 "OK"  button,	it  is
		   denoted  a  "msgbox", without an "OK" button, it is denoted
		   an "infobox".

       dialog_pause
	      implements the "--pause" option.

	      const char * title
		   is the title on the top of the widget.

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

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

	      int seconds
		   is the timeout to use for the progress bar.

       dialog_prgbox
	      implements the "--prgbox" option.

	      const char * title
		   is the title on the top of the widget.

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

	      const char * command
		   is the name of the command to execute.

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

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

	      int pauseopt
		   if  true, an "OK" button will be shown, and the dialog will
		   wait for it to complete.

       dialog_progressbox
	      implements the "--progressbox" option.

	      const char * title
		   is the title on the top of the widget.

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

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

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

       dialog_rangebox
	      implements the "--rangebox" option.

	      const char * title
		   is the title on the top of the widget.

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

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

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

	      int min_value
		   is the minimum value to allow.

	      int max_value
		   is the maximum value to allow.

	      int default_value
		   is the default value, if no change is made.

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

	      const char * title
		   is the title on the top of the widget.

	      const char * file
		   is the name of the file to display in the dialog.

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

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

	      int 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 win‐
		   dow, and it will be closed when the button is activated.

       dialog_textbox
	      implements the "--textbox" option.

	      const char * title
		   is the title on the top of the widget.

	      const char * file
		   is the name of the file to display in the dialog.

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

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

       dialog_timebox
	      implements the "--timebox" option.

	      const char * title
		   is the title on the top of the widget.

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

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

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

	      int hour
		   is the initial hour shown.  If the value is	negative,  the
		   current  hour is used.  Returns DLG_EXIT_ERROR if the value
		   specified is greater than or equal to 24.

	      int minute
		   is the initial minute shown.	 If the value is negative, the
		   current  minute  is	used.	Returns	 DLG_EXIT_ERROR if the
		   value specified is greater than or equal to 60.

	      int second
		   is the initial second shown.	 If the value is negative, the
		   current  second  is	used.	Returns	 DLG_EXIT_ERROR if the
		   value specified is greater than or equal to 60.

       dialog_treeview
	      implements the "--treeview" option.

	      const char * title
		   is the title on 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
		   based on the screen size.

	      int width
		   is  the  desired  width of the box.	If zero, the height is
		   based on the 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 rows in items.

	      char ** items
		   is the list of items, contain  tag,	name,  and  optionally
		   help	 strings  (if dialog_vars.item_help is set).  The ini‐
		   tial selection state for each item is also in this list.

	      int flag

	      flag is either FLAG_CHECK, for checklists (multiple selections),
		   or FLAG_RADIO for radiolists (a single selection).

       dialog_yesno
	      implements the "--yesno" option.

	      const char * title
		   is the title on 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
		   based on the screen size.

	      int 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
		 contains the callback information.

       dlg_add_callback_ref
	    Like  dlg_add_callback, but passes a reference to the DIALOG_CALL‐
	    BACK as well as a pointer to a  cleanup  function  which  will  be
	    called when the associated input ends.

	    DIALOG_CALLBACK **p
		 points	 to  the callback information.	This is a reference to
		 the pointer so that the caller's pointer can be  zeroed  when
		 input ends.

	    DIALOG_FREEBACK func
		 function  to  call  when  input  ends, e.g., to free caller's
		 additional data.

       dlg_add_help_formitem
	    This is a utility function used enforce  consistent	 behavior  for
	    the DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.

	    int *result
		 this	 is    updated	  to	DLG_EXIT_ITEM_HELP   if	  DIA‐
		 LOG_VARS.item_help is set.

	    char **tag
		 the tag- or help-text is stored here.

	    DIALOG_FORMITEM *item
		 contains the list item to use for tag- or help-text.

       dlg_add_help_listitem
	    This is a utility function used enforce  consistent	 behavior  for
	    the DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.

	    int *result
		 this	 is    updated	  to	DLG_EXIT_ITEM_HELP   if	  DIA‐
		 LOG_VARS.item_help is set.

	    char **tag
		 the tag- or help-text is stored here.

	    DIALOG_LISTITEM *item
		 contains the list item to use for tag- or help-text.

       dlg_add_last_key
	    Report the last key entered by  the	 user.	 This  implements  the
	    --last-key command-line option, using dialog_vars.last_key.

	    int mode
		 controls  the way the last key report is separated from other
		 results:

		 -2   (no separator)

		 -1   (separator after the key name)

		 0    (separator is optionally before the key name)

		 1    (same as -1)

       dlg_add_quoted
	    Add a quoted string to the result buffer (see dlg_add_result).  If
	    no	quotes	are  necessary,	 none  are  used.  If dialog_vars.sin‐
	    gle_quoted is set, single-quotes  are  used.   Otherwise,  double-
	    quotes are used.

	    char * string
		 is the string to add.

       dlg_add_result
	    Add a string to the result buffer dialog_vars.input_result.

	    char * string
		 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_allocate_gauge
	    Allocates a gauge widget.  Use  dlg_update_gauge  to  display  the
	    result.

	    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 percent
		 is the percentage to show in the progress bar.

       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.

	    chtype ch
		 is the parameter, usually one of the ACS_xxx constants.

       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.

       dlg_auto_size
	    Automatically size the window used for a  widget.	If  the	 given
	    height  or	width are zero, justify the prompt text and return the
	    actual limits.

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

	    const char * prompt
		 is the message text which will be displayed  in  the  widget,
		 used here to determine how large the widget should be.

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

	    ·	otherwise, if dialog_vars.no_lines is set, returns a space for
		the line-drawing characters.

	    ·	if  the parameter is not a line-drawing or other special char‐
		acter such as ACS_DARROW, it returns the parameter unchanged.

       dlg_box_x_ordinate
	    returns a suitable x-ordinate (column) for a new widget.  If  dia‐
	    log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center
	    the widget on the screen (using the width parameter).

	    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_buildlist
	    This is an alternate  interface  to	 the  buildlist	 widget	 which
	    allows  the application to read the list item states back directly
	    without putting them in the output buffer.

	    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 rows in items.

	    DIALOG_LISTITEM * items
		 is  the list of items, contain tag, name, and optionally help
		 strings  (if  dialog_vars.item_help  is  set).	  The  initial
		 selection state for each item is also in this list.

	    const char * states
		 This is a list of characters to display for the given states.
		 Normally a buildlist 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 order_mode
		 is reserved for future enhancements

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

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

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

	    int limit
		 is the maximum number of columns to allow for the buttons.

	    int * gap
		 store the nominal gap between buttons in the referenced loca‐
		 tion.	This is constrained to be at least one.

	    int * margin
		 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.

	    Normally  dlg_draw_buttons	and  dlg_char_to_button	 use the first
	    uppercase character.  However, they	 keep  track  of  all  of  the
	    labels  and	 if  the first has already been used in another label,
	    they will continue looking for another uppercase character.	  This
	    function does not have enough information to make that check.

	    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.

		 If dialog_vars.no_items is set, the text fields in  the  list
		 are ignored.

       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.

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

       dlg_char_to_button
	    Given a list of button labels, and a character which  may  be  the
	    abbreviation for one, find it, if it exists.  An abbreviation will
	    be the first character which happens  to  be  capitalized  in  the
	    label.   If	 the  character	 is found, return its index within the
	    list of labels.  Otherwise, return DLG_EXIT_UNKNOWN.

	    int ch
		 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_check_scrolled
	    given  a  function key (or other key that was mapped to a function
	    key), check if it is one of the up/down scrolling functions:

		     DLGK_PAGE_FIRST,
		     DLGK_PAGE_LAST,
		     DLGK_GRID_UP,
		     DLGK_GRID_DOWN,
		     DLGK_PAGE_PREV or
		     DLGK_PAGE_NEXT.

	    Some widgets use these key bindings for scrolling the  prompt-text
	    up and down, to allow for display in very small windows.

	    The	 function  returns 0 (zero) if it finds one of these keys, and
	    -1 if not.

	    int key
		 is the function-key to check

	    int last
		 is the number of lines which would be	used  to  display  the
		 scrolled  prompt  in  an arbitrarily tall window.  It is used
		 here to check limits for the offset value.

	    int page
		 this is the available height for writing scrolled text, which
		 is smaller than the window if it contains buttons.

	    bool * show
		 on return, holds TRUE if dlg_print_scrolled should be used to
		 redisplay the prompt text.

	    int * offset
		 on entry, holds the starting line number (counting from zero)
		 last  used  for  dlg_print_scrolled.	On  return,  holds the
		 updated starting line number.

       dlg_clear
	    Set window to the default dialog screen attribute.	This is set in
	    the rc-file with screen_color.

       dlg_clr_result
	    Free    storage    used    for    the    result    buffer	 (dia‐
	    log_vars.input_result).  The corresponding pointer is set to NULL.

       dlg_color_count
	    Return the number of colors that can be configured in dialog.

       dlg_color_setup
	    Initialize the color pairs used in dialog.

       dlg_count_argv
	    Count the entries in an argument vector.

	    argv Points to the argument vector.

       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_real_columns
	    Returns  the  number  of columns used for a string, accounting for
	    "\Z" sequences which can be used for coloring  the	text  if  dia‐
	    log_vars.colors  is	 set.	This  is not necessarily 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_button
	    If dialog_vars.default_button is positive, return the button-index
	    for that button code,  using  dlg_ok_buttoncode  to	 test  indices
	    starting  with  zero.  Otherwise (or if no match was found for the
	    button code), return zero.

       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,
	    find the button-index for the "Cancel" button.  Otherwise,	return
	    the index for "OK" (always zero).

       dlg_del_window
	    Remove a window, repainting everything else.

	    WINDOW * win
		 is the window to remove.

       dlg_does_output
	    This  is called each time a widget is invoked which may do output.
	    It increments dialog_state.output_count, so the output function in
	    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
		 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.

	    chtype attr
		 is the window's background attribute.

	    chtype borderattr
		 is the window's border attribute.

       dlg_draw_bottom_box
	    Draw  a partial box at the bottom of a window, e.g., to surround a
	    row of buttons.  It is designed to	merge  with  an	 existing  box
	    around  the	 whole	window (see dlg_draw_box), so it uses tee-ele‐
	    ments rather than corner-elements on the top corners of this box.

	    WINDOW * win
		 is the window to update.

       dlg_draw_bottom_box2
	    Draw a partial box at the bottom of a window, e.g., to surround  a
	    row	 of  buttons.	It  is	designed to merge with an existing box
	    around the whole window (see dlg_draw_box2), so it	uses  tee-ele‐
	    ments rather than corner-elements on the top corners of this box.

	    WINDOW * win
		 is the window to update.

	    chtype on_left
		 is  used  to color the upper/left edges of the box, i.e., the
		 tee-element and horizontal line

	    chtype on_right
		 is used to color the right edge of the box,  i.e.,  the  tee-
		 element

	    chtype on_inside
		 is used to fill-color the inside of the box

       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_box2
	    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 fill-color for the box contents.

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

	    chtype borderchar2
		 is used to color the right/lower 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 limit
		 is the number of columns (or rows if  vertical)  allowed  for
		 the display.

       dlg_draw_helpline
	    draw  the text in dialog_vars.help_line at the bottom of the given
	    window.

	    WINDOW * dialog
		 is the window to modify.

	    bool decorations
		 if true, allow room for the scrolling arrows.

       dlg_draw_scrollbar
	    If dialog_state.use_scrollbar is set,  draw	 a  scrollbar  on  the
	    right margin of windows holding scrollable data.  Also (whether or
	    not the scrollbar is drawn), annotate the  bottom  margin  of  the
	    window  with  the percentage of data by the bottom of that window,
	    and call dlg_draw_arrows2 to put markers  on  the  window  showing
	    when more data is available.

	    WINDOW * win
		 is  the  window in which the data is scrolled.	 Because left,
		 right, top, bottom are passed as parameters, this window  can
		 contain additional data.

	    long first_data
		 is  the zero-based index to the first row of data in the cur‐
		 rent window.

	    long this_data
		 is the zero-based index to the current row of data.

	    long next_data
		 is the zero-based index to the next data  after  the  current
		 row.

	    long total_data
		 is the total number of rows of data.

	    int left
		 is  the  zero-based  left  margin/column  of the window.  The
		 up/down arrows are draw inset by 5 columns from this point.

	    int right
		 is the zero-based right margin/column	of  the	 window.   The
		 scrollbar is drawn flush against this column.

	    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.

	    chtype attr
		 is the window's background attribute.

	    chtype borderattr
		 is the window's border attribute.

       dlg_draw_shadow
	    Draw shadows along the right and bottom edge of a window  to  give
	    it	a  3-dimensional look.	(The height, etc., may not be the same
	    as the window's actual values).

	    WINDOW * win
		 is the window to update.

	    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_dummy_menutext
	    This is a utility function which supports the  --inputmenu	option
	    of	the  dialog  program.	If dialog_vars.input_menu is set, dia‐
	    log_menu passes this pointer to dlg_menu  as  the  rename_menutext
	    parameter.	Otherwise, it passes dlg_dummy_menutext.

	    The function should only return DLG_EXIT_ERROR.

	    DIALOG_LISTITEM * items
		 is the list of menu items

	    int current
		 is the index of the currently-selected item

	    char * newtext
		 is the updated text for the menu item

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

	    WINDOW * win
		 is  the window for which bindings should be dumped.  If it is
		 null, then only built-in bindings are dumped.

       dlg_eat_argv
	    Remove one or more items from an argument vector.

	    int * argcp
		 in/out parameter giving the length of	the  argument  vector.
		 char *** argvp in/out parameter pointing to the argument vec‐
		 tor.  int start starting index.  int count  number  of	 argu‐
		 ments to remove.

       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 the (multibyte) string to update

	    int * offset
		 is the character-offset

	    int key
		 is the editing key

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

	    bool force
		 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_finish_string
	    If DIALOG_STATE.finish_string is true, this function discards data
	    used to speed up layout computations.

	    const char * string
		 is the address of the string whose data should be  discarded.
		 The  address rather than contents is used as the unique iden‐
		 tifier because some of	 the  caching  is  used	 for  editable
		 input-fields.

       dlg_flush_getc
	    Cancel the local data saved by dlg_last_getc.

       dlg_editbox
	    This  entrypoint  provides the --editbox functionality without the
	    limitations of  dialog's  command-line  syntax  (compare  to  dia‐
	    log_editbox).

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

	    char *** list
		 is  a	pointer	 to an array of char * pointers.  The array is
		 allocated by the caller, and so are the strings to  which  it
		 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.

	    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_free_formitems
	    Free memory owned by a list of DIALOG_FORMITEM's.

	    DIALOG_FORMITEM * items
		 is the list to free.

       dlg_free_gauge
	    Remove  the	 gauge	widget from the screen and free its associated
	    memory.

	    void *objptr
		 points to the gauge widget.

       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_get_attrs
	    extract the video attributes from the given window.

	    WINDOW * win
		 is the window from which to get attributes.

       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.

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

	    int * retval
		 stores the exit-code to pass back to the caller.

       dlg_last_getc
	    returns the most recent character that was read via dlg_getc.

       dlg_limit_columns
	    Given a column limit, count the number of wide characters that can
	    fit into that limit.  The offset is used to skip  over  a  leading
	    character that was already written.

	    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.

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

	    int menu_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 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
		 If  this  is  not dlg_dummy_menutext, the widget acts like an
		 inputmenu widget, providing an extra "Rename"	button,	 which
		 activates an edit feature on the selected menu item.

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

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

	    int step_x
		 is used in modes 2 (columns) and 3 (cells) to	determine  the
		 width of a column/cell.

	    int step_y
		 is currently unused

	    int mode
		 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_setcode
	    Sets  a value used internally by dlg_mouse_mkregion which is added
	    to the code parameter.  By providing different values, e.g.,  mul‐
	    tiples  of	KEY_MAX,  it  is  possible  to	support multiple "big"
	    regions in a widget.  The buildlist widget uses  this  feature  to
	    recognize mouse-clicks in the left/right panes.

	    int code
		 is the value to add to dlg_mouse_mkregion's code parameter.

       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

	    int * fkey
		 the referenced location is set to true if the key-code is  an
		 actual or extended (mouse) function-key.

       dlg_mouse_wgetch_nowait
	    This is a non-blocking variant of dlg_mouse_wgetch.

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

	    int * fkey
		 the  referenced location is set to true if the key-code is an
		 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.

       dlg_next_ok_buttonindex
	    Assuming  that  the caller is using dlg_ok_labels to list buttons,
	    find the next index in the list of buttons.

	    int current
		 is the current index in the list of buttons

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

       dlg_ok_buttoncode
	    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_listitem
	    This is a helper function used for	the  various  "list"  widgets,
	    e.g.,  checklist, menu, buildlist, treeview.  Each list-widget has
	    "tag" and "description" values for each item  which	 can  be  dis‐
	    played.   If  dialog_vars.no_tags  is true, the "tag" value is not
	    shown.  The first character of  the	 first	value  shown  (tag  or
	    description) is highlighted to indicate that the widget will match
	    it for quick navigation.

	    WINDOW *win
		 the window in which to display the text

	    const char *text
		 the value to display

	    int climit
		 the number of columns available for printing the text

	    bool first
		 true if this is the first call (for "tag" and "description"),
		 and the first character of the value should be highlighted.

	    int selected
		 nonzero  if the text should be displayed using the "selected"
		 colors

       dlg_print_scrolled
	    This is a wrapper for dlg_print_autowrap which allows the user  to
	    scroll too-long prompt text up/down.

	    See	 dlg_check_scrolled  for  a  function which updates the offset
	    variable used as a parameter here.	It complements this  function;
	    you	 need  both.   If  pauseopt  is	 set, this function returns an
	    updated last parameter, needed for dlg_check_scrolled calls.

	    WINDOW * win
		 is the window to update.

	    const char * prompt
		 is the string to print

	    int offset
		 is the starting line-number to write wrapped text.

	    int height
		 is the available height for writing the wrapped text

	    int width
		 is the width that the wrapping should occur in

	    int pauseopt
		 is true if the extra functionality for	 scrolling  should  be
		 enabled.   If	false,	this  calls dlg_print_autowrap without
		 doing any scrolling.

       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 lm
		 is the left margin.

	    int rm
		 is the right margin

	    int *x
		 returns the ending x-ordinate.

       dlg_prev_ok_buttonindex
	    Find the previous button index in the list from dlg_ok_labels.

	    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.  The text is writ‐
	    ten starting at the top of the window.

	    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_progressbox implements the "--prgbox" and "--progressbox" options.

	    const char * title
		 is the title on the top of the widget.

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

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

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

	    int pauseopt
		 if true, an "OK" button will be shown, and  the  dialog  will
		 wait  for it to complete.  With an "OK" button, it is denoted
		 a "programbox", without an "OK" button, it is denoted a "pro‐
		 gressbox".

	    FILE * fp
		 is the file pointer, which may be a pipe or a regular file.

       dlg_put_backtitle
	    Display the background title if dialog_vars.backtitle is non-null.
	    The background title is shown at the top of the screen.

       dlg_reallocate_gauge
	    Allocates or reallocates a gauge widget (see  dlg_allocate_gauge).
	    Use dlg_update_gauge to display the result.

	    void ** objptr
		 If  the  pointer  referenced  by  this parameter is null, the
		 function creates a new gauge widget using dlg_allocate_gauge.
		 Otherwise,  it	 updates the title and cprompt values, reusing
		 the window from the previous call on  this  function.	 As  a
		 side-effect,  the  function stores the updated object-pointer
		 via the objptr parameter.

	    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 percent
		 is the percentage to show in the progress bar.

       dlg_register_buttons
	    The widget developer should call this  function  after  dlg_regis‐
	    ter_window, for the list of button labels associated with the wid‐
	    get.  One may bind a key to a button, e.g., "OK" for DLGK_OK,

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

	    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_renamed_menutext
	    This is a utility function which supports the  --inputmenu	option
	    of	the  dialog  program.	If dialog_vars.input_menu is set, dia‐
	    log_menu passes this pointer to dlg_menu  as  the  rename_menutext
	    parameter.	Otherwise, it passes dlg_dummy_menutext.

	    The	 function  should  add "RENAMED" to dialog_vars.input_result ,
	    followed by the menu item's name and the  newtext  value  (with  a
	    space separating the three items), and return DLG_EXIT_EXTRA.

	    DIALOG_LISTITEM * items
		 is the list of menu items

	    int current
		 is the index of the currently-selected item

	    char * newtext
		 is the updated text for the menu item

       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.

	    The DIALOG_VARS.input_length and DIALOG_VARS.input_result  members
	    are	 treated  specially,  since these are used by a widget to pass
	    data to the caller.	 They are not modified by this function.

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

	    DIALOG_VARS * save
		 is the variable into which to save.

       dlg_set_focus
	    Set	 focus on the given window, making it display above other win‐
	    dows on the screen.

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

	    WINDOW * win
		 is the window on which to place focus (usually a subwindow of
		 a widget)

       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_string_to_argv
	    Convert  a	string to an argument vector returning an index (which
	    must be freed by the caller).  The string is  modified  (replacing
	    gaps between tokens with nulls).

	    char *blob
		 is the string to convert.

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

	    WINDOW * win
		 is the parent window

	    int height
		 is the subwindow's height

	    int width
		 is the subwindow's width

	    int y
		 is the subwindow's top-row

	    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_msg
	    Write a formatted message to the trace file.

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

	    ...
		 are the variables to apply to the fmt format.

	    Use the DLG_TRACE macro for portability, in case the trace feature
	    is	not  compiled  into  the  library.   It uses an extra level of
	    parentheses to work with a variable number of parameters, e.g.,

	    DLG_TRACE(("this is dialog version %s\n", dialog_version()));

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

       dlg_treeview
	    This  is  an  alternate  interface	to 'treeview' which allows the
	    application to read the list item  states  back  directly  without
	    putting them in the output buffer.

	    const char * title
		 is the title on 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
		 based on the screen size.

	    int width
		 is the desired width of the box.   If	zero,  the  height  is
		 based on the 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 rows in items.

	    DIALOG_LISTITEM * items
		 is the list of items, contain tag, name, and optionally  help
		 strings  (if  dialog_vars.item_help  is  set).	  The  initial
		 selection state for each item is also in this list.

	    const char * states
		 This is a list of characters to display for the given states.
		 Normally  a buildlist 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 * depths
		 This  is  a list of depths of each item in the tree.  It is a
		 separate parameter from items to allow reuse of the  existing
		 functions.

	    int flag
		 is  either  FLAG_CHECK, for checklists (multiple selections),
		 or FLAG_RADIO for radiolists (a single selection).

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

       dlg_trim_string
	    The	 dialog program uses this in each widget to adjust the message
	    string, which may contain the newline character  (referred	to  as
	    '\n')  and/or  the special substring "\n" (which can be translated
	    into a newline character).

	    There are several optional features:

	    ·	Unless dialog_vars.no_nl_expand is set,

		·   If it has "\n" substrings, the  function  preserves	 extra
		    spaces.   For  instance,  spaces following a newline (sub‐
		    string or character) are preserved to use as  an  indenta‐
		    tion.

		·   The	 function  changes  embedded  "\n"  substrings to '\n'
		    characters.

	    ·	If dialog_vars.no_nl_expand is not set, or  if	there  are  no
		"\n" substrings, this function strips all extra spaces to sim‐
		plify justification.

	    ·	If dialog_vars.cr_wrap is set,	the  function  preserves  '\n'
		newline characters.  Otherwise, each '\n' newline character is
		converted to a space.

	    ·	Unless dialog_vars.nocollapse is set, each  tab	 character  is
		converted  to  a space, and sequences of blanks (space or tab)
		are reduced to a single space.

	    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_update_gauge
	    Update a gauge widget to show a different percentage value.

	    void *objptr
		 points to the gauge object to update.

	    int percent
		 is the new percentage value to display.

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

	    int button
		 is the button index

       dlg_yes_labels
	    Return a list of buttons for Yes/No labels.

SEE ALSO
       dialog (1).

AUTHOR
       Thomas E. Dickey

$Date: 2014/02/19 23:39:15 $					     DIALOG(3)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net