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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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.

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

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

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

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

       Most of the other definitions found in _dialog.h_ are used  for	conve-
       nience  in building the library or main program.	 These include defini-
       tions based on the generated _dlg_config.h_ header.

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

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

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

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

	      o	  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.max_input
	      This corresponds to the command-line option "--max-input	size".
	      Limit  input  strings  to	the given size.	 If not	specified, the
	      limit is 2048.

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

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

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

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

       DIALOG_VARS.quoted

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

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

       DIALOG_VARS.size_err
	      This  corresponds	 to  the command-line option "--size-err".  If
	      true, check the resulting	size of	a dialog box before trying  to
	      use  it,	printing  the  resulting size if it is larger than the
	      screen.  (This option is obsolete, since	all  new-window	 calls
	      are checked).

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

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

       DIALOG_VARS.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  checklist,  radiobox,  menubox  and
	      inputmenu	 to  include  the  list	of items as one	of the states.
	      This is useful as	a visual aid, i.e., the	cursor position	 helps
	      some users.

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

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

       All dialog boxes	have at	least three parameters:

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

       height
	    the	height of the dialog box.

       width
	    the	width of the dialog box.

       Other parameters	depend on the box type.

       dialog_calendar
	      implements the "--calendar" option.

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

	      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-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_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_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_quoted
	    Add	a quoted string	to the result buffer (see dlg_add_result).

	    char * string
		 is the	string to add.

       dlg_add_result
	    Add	a quoted 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.

       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	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 charac-
	       ter 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_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.

	    const char * label
		 is the	label to test.

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

	    int	item_no
		 is the	number of items.

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

       dlg_calc_listh
	    Calculate new height and list_height values.

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

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

	    int	item_no
		 is the	number of items	in the list.

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

	    int	item_no
		 is the	number of items.

	    char ** items
		 is a list of character	pointers.

	    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_wchars
	    Returns the	number of wide-characters in the string.

	    const char * string
		 is the	string to measure.

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

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

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

	    int	height
		 is the	window's height

	    int	width
		 is the	window's width

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

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

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

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

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

       dlg_defaultno_button
	    If dialog_vars.defaultno is	true, and dialog_vars.nocancel is not,
	    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, so	it uses	tee-elements rather than  cor-
	    ner-elements on the	top corners of this box.

	    WINDOW * win
		 is the	window to update.

       dlg_draw_box
	    Draw a rectangular box with	line drawing characters.

	    WINDOW * win
		 is the	window to update.

	    int	y
		 is the	top row	of the box.

	    int	x
		 is the	left column of the box.

	    int	height
		 is the	height of the box.

	    int	width
		 is the	width of the box.

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

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

       dlg_draw_buttons
	    Print a list of buttons at the given position.

	    WINDOW * win
		 is the	window to update.

	    int	y
		 is the	starting row.

	    int	x
		 is the	starting column.

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

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

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

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

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

	    WINDOW *win
		 is the	window to move/resize.

	    WINDOW *height
		 is the	height of the resized window.

	    WINDOW *width
		 is the	width of the resized window.

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

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

       dlg_mouse_bigregion
	    Retrieve the big-region under the pointer.

	    int	y
		 is the	row on which the mouse click occurred

	    int	x
		 is the	column on which	the mouse click	occurred

       dlg_mouse_free_regions
	    Free the memory associated with mouse regions.

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

	    int	y
		 is the	top-row	of the region.

	    int	x
		 is the	left-column of the region.

	    int	height
		 is the	height of the region.

	    int	width
		 is the	width of the region.

	    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_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_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_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_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	  dia-
	    log_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_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:

	    o	Unless dialog_vars.no_nl_expand	is set,

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

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

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

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

	    o	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: 2011/06/29 09:07:36 $					     DIALOG(3)

NAME | SYNOPSIS | DESCRIPTION | DEFINITIONS | DATA STRUCTURES | WIDGETS | UTILITY FUNCTIONS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dialog&sektion=3&manpath=FreeBSD+9.3-RELEASE>

home | help