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

FreeBSD Manual Pages

  
 
  

home | help
DIALOG(3)		   Library Functions Manual		     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 di-
       alog(1)).   The DIALOG_ATR(n) macro is used for defining	the references
       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 checklist/ra-
       diobox,	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 li-
       brary.

       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  pre-
	      fers  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 op-
       tions 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 ob-
	      solete.

       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 op-
	      tion 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  "Re-
	      name".

       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 DIALOG_VARS.in-
	      put_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 di-
	      alog to not attempt to cancel the	terminal initialization	(term-
	      cap 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 un-
	      needed) 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  li-
	      brary'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 in-
	      putmenu 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 ra-
		   diolists.

       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 de-
		   noted 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  ad-
		 ditional 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 dialog_vars.input_re-
	    sult.  If dialog_vars.output_separator is set, use	that.	Other-
	    wise, if dialog_vars.separate_output is set, use newline.  If nei-
	    ther 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  ac-
	    cording  to	the column separator dialog_vars.column_separator.  If
	    no column separator	is set,	the array will be  unmodified;	other-
	    wise 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 re-
	    sult.

	    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 ad-
		 justed	to use the available screen size.

	    int	width
		 is the	desired	width of the box.  If zero, the	height is  ad-
		 justed	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  pa-
	    rameter  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  dialog_vars.be-
		 gin_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  dialog_vars.be-
		 gin_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 up-
	    percase character is found,	return 0.  Otherwise return the	upper-
	    case 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 ra-
		 diobox	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  la-
	    bel.   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 ad-
		 justed	to use the available screen size.

	    int	width
		 is the	desired	width of the box.  If zero, the	height is  ad-
		 justed	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 up-
		 dated 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	(dialog_vars.input_re-
	    sult).  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 en-
	    vironment 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 dialog_ed-
	    itbox).

	    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 ad-
		 justed	to use the available screen size.

	    int	width
		 is the	desired	width of the box.  If zero, the	height is  ad-
		 justed	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 ad-
		 justed	to use the available screen size.

	    int	width
		 is  the desired width of the box.  If zero, the height	is ad-
		 justed	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,  ig-
	    noring  case of the	given character.  The matching string must be-
	    gin	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 ad-
		 justed	to use the available screen size.

	    int	width
		 is the	desired	width of the box.  If zero, the	height is  ad-
		 justed	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 dialog_vars.in-
	    put_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  up-
	    dated 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 do-
		 ing 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  dialog_re-
	    store_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.2-RELEASE>

home | help