1DIALOG(3)                  Library Functions Manual                  DIALOG(3)
2
3
4

NAME

6       dialog - widgets and utilities for the dialog program
7

SYNOPSIS

9       cc [ flag ... ] file ... -ldialog [ library ... ]
10          or
11       cc $(dialog-config --cflags) file ... $(dialog-config --libs) ]
12
13       #include <dialog.h>
14
15       Dialog is a program that will let you present a variety of questions or
16       display messages using dialog boxes from a shell script.  It  is  built
17       from  the  dialog library, which consists of several widgets as well as
18       utility functions that are used by the widgets or the main program.
19

DESCRIPTION

21       This manpage documents the features from <dialog.h> which are likely to
22       be  important to developers using the widgets directly.  Some hints are
23       also given for developing new widgets.
24
25       Here is a dialog version of Hello World:
26              int main(void)
27              {
28                   int status;
29                   init_dialog(stdin, stdout);
30                   status = dialog_yesno(
31                             "Hello, in dialog-format",
32                             "Hello World!",
33                             0, 0);
34                   end_dialog();
35                   return status;
36              }
37

DEFINITIONS

39       Exit codes (passed back to the main program for its  use)  are  defined
40       with  a  "DLG_EXIT_  prefix.   The efined constants can be mapped using
41       environment variables as described in dialog(1), e.g., DLG_EXIT_OK cor‐
42       responds to $DIALOG_OK.
43
44       Useful  character  constants  which  correspond to user input are named
45       with the "CHR_" prefix, e.g., CHR_BACKSPACE.
46
47       Colors and video attributes are categorized and  associated  with  set‐
48       tings  in  the  configuration  file (see the discussion of $DIALOGRC in
49       dialog(1)).  The DIALOG_ATR(n) macro is used for  defining  the  refer‐
50       ences to the combined color and attribute table dlg_color_table[].
51
52       The dialog application passes its command-line parameters to the widget
53       functions.  Some of those parameters are single values, but some of the
54       widgets  accept  data  as  an  array  of  values.  Those include check‐
55       list/radiobox, menubox and formbox.  When  the  --item-help  option  is
56       given,  an  extra  column  of  data  is expected.  The USE_ITEM_HELP(),
57       CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS macros are  used  to  hide
58       this difference from the calling application.
59
60       Most  of  the other definitions found in <dialog.h> are used for conve‐
61       nience in building the library or main program.  These include  defini‐
62       tions based on the generated <dlg_config.h> header.
63

DATA STRUCTURES

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

DIALOG_STATE

76       The  state  variables  are  dialog's working variables.  It initializes
77       those, uses them to manage the widgets.
78
79   .all_subwindows
80       This is a linked list of all subwindows created by  the  library.   The
81       dlg_del_window  function  uses this to free storage for subwindows when
82       deleting a window.
83
84   .all_windows
85       This is a linked list of all  windows  created  by  the  library.   The
86       dlg_del_window  function  uses  this  to  locate  windows  which may be
87       redrawn after deleting a window.
88
89   .aspect_ratio
90       This corresponds to  the  command-line  option  "--aspect-ratio".   The
91       value  gives  the application some control over the box dimensions when
92       using auto sizing (specifying 0 for height and width).   It  represents
93       width  /  height.   The  default is 9, which means 9 characters wide to
94       every 1 line high.
95
96   .finish_string
97       When set to true, this allows calls to dlg_finish_string to discard the
98       corresponding data which is created to speed up layout computations for
99       the given string parameter.  The gauge widget uses this feature.
100
101   .getc_callbacks
102       This is set up in ui_getc.c to record windows which must be polled  for
103       input,  e.g.,  to  handle the background tailbox widget.  One window is
104       designated as the foreground or control window.
105
106   .getc_redirect
107       If the control window for DIALOG_STATE.getc_callbacks  is  closed,  the
108       list  is  transferred to this variable.  Closing all windows causes the
109       application to exit.
110
111   .had_resize
112       This  is  set  to  TRUE  in  dlg_will_resize  or  dlg_result_key   when
113       KEY_RESIZE is read, to tell dialog to ignore subsequent ERRs.
114
115   .no_mouse
116       This  corresponds  to  the  command-line option "--no-mouse".  If true,
117       dialog will not initialize (and enable) the mouse in init_dialog.
118
119   .output
120       This is set in the dialog application to the stream on which the appli‐
121       cation  and library functions may write text results.  Normally that is
122       the standard error, since the curses library prefers to write its  data
123       to  the  standard output.  Some scripts, trading portability for conve‐
124       nience, prefer to write results to the standard output, e.g., by  using
125       the "--stdout" option.
126
127   .output_count
128       This  is incremented by dlg_does_output, which is called by each widget
129       that writes text to the output.  The dialog application  uses  that  to
130       decide  if  it  should also write a separator, i.e., DIALOG_STATE.sepa‐
131       rate_str, between calls to each widget.
132
133   .pipe_input
134       This is set in init_dialog to a stream which can be used by  the  gauge
135       widget,  which  must  be  the application's standard input.  The dialog
136       application calls init_dialog normally with input set to  the  standard
137       input,  but  optionally  based  on  the "--input-fd" option.  Since the
138       application cannot read from a pipe (standard input) and  at  the  same
139       time  read  the curses input from the standard input, it must allow for
140       reopening the  latter  from  either  a  specific  file  descriptor,  or
141       directly  from  the terminal.  The adjusted pipe stream value is stored
142       in this variable.
143
144   .screen_height
145       The text-formatting functions use this for the number of rows used  for
146       formatting a string.
147
148       It  is  used by dialog for the command-line options "--print-text-size"
149       and "--print-text-only".
150
151   .screen_initialized
152       This is set in init_dialog and reset in  end_dialog.   It  is  used  to
153       check  if  curses has been initialized, and if the endwin function must
154       be called on exit.
155
156   .screen_output
157       This is set in init_dialog to the output  stream  used  by  the  curses
158       library.   Normally that is the standard output, unless that happens to
159       not be a terminal (and if init_dialog can successfully open the  termi‐
160       nal directly).
161
162   .screen_width
163       The  text-formatting  functions use this for the number of columns used
164       for formatting a string.
165
166       It is used by dialog for the command-line  options  "--print-text-size"
167       and "--print-text-only".
168
169   .separate_str
170       This  corresponds  to the command-line option "--separate-widget".  The
171       given string specifies a string that will separate the output  on  dia‐
172       log's  output  from  each widget.  This is used to simplify parsing the
173       result of a dialog with several widgets.  If this option is not  given,
174       the default separator string is a tab character.
175
176   .tab_len
177       This  corresponds to the command-line option "--tab-len number".  Spec‐
178       ify the number of spaces that a tab character occupies if  the  "--tab-
179       correct" option is given.  The default is 8.
180
181   .text_height
182       The  text-formatting functions set this to the number of lines used for
183       formatting a string.
184
185       It is used by dialog for the command-line  options  "--print-text-size"
186       and "--print-text-only".
187
188   .text_only
189       Dialog uses this in the command-line option "--print-text-only".
190
191       The  text-formatting  functions  (dlg_print_text,  dlg_print_line,  and
192       dlg_print_autowrap) check this to decide whether to print the formatted
193       text to dialog's output or to the curses-display.
194
195       Also,  dlg_auto_size  checks  the  flag,  allowing it to be used before
196       init_dialog is called.
197
198   .text_width
199       The text-formatting functions set this to the number  of  columns  used
200       for formatting a string.
201
202       It  is  used by dialog for the command-line options "--print-text-size"
203       and "--print-text-only".
204
205   .trace_output
206       This corresponds to the command-line option "--trace file".  It is  the
207       file pointer to which trace messages are written.
208
209   .use_colors
210       This is set in init_dialog if the curses implementation supports color.
211
212   .use_scrollbar
213       This  corresponds  to  the command-line option "--scrollbar".  If true,
214       draw a scrollbar to make windows holding scrolled data more readable.
215
216   .use_shadow
217       This corresponds to the command-line option "--no-shadow".  This is set
218       in  init_dialog  if the curses implementation supports color.  If true,
219       suppress shadows that would be drawn to the right and  bottom  of  each
220       dialog box.
221
222   .visit_items
223       This  corresponds  to  the command-line option "--visit-items".  Modify
224       the tab-traversal of the list-oriented widgets  (buildlist,  checklist,
225       radiobox,  menubox,  inputmenu,  and  treeview)  to include the list of
226       items as one of the states.  This is useful as a visual aid, i.e.,  the
227       cursor position helps some users.
228
229       The  dialog  application  resets  the dialog_vars data before accepting
230       options to invoke each widget.  Most of the DIALOG_VARS members are set
231       directly from dialog's command-line options:
232

DIALOG_VARS

234       In contrast to DIALOG_STATE, the members of DIALOG_VARS are set by com‐
235       mand-line options in dialog.
236
237   .ascii_lines
238       This corresponds to the command-line option "--ascii-lines.  It  causes
239       line-drawing  to be done with ASCII characters, e.g., "+" and "-".  See
240       DIALOG_VARS.no_lines.
241
242   .backtitle
243       This corresponds to the command-line  option  "--backtitle  backtitle".
244       It specifies a backtitle string to be displayed on the backdrop, at the
245       top of the screen.
246
247   .beep_after_signal
248       This corresponds to the command-line option "--beep-after".   If  true,
249       beep  after  a  user has completed a widget by pressing one of the but‐
250       tons.
251
252   .beep_signal
253       This corresponds to the command-line option "--beep".  It is obsolete.
254
255   .begin_set
256       This is true if the command-line option "--begin y  x"  was  used.   It
257       specifies  the position of the upper left corner of a dialog box on the
258       screen.
259
260   .begin_x
261       This corresponds to the x value from the command-line option "--begin y
262       x" (second value).
263
264   .begin_y
265       This corresponds to the y value from the command-line option "--begin y
266       x" (first value).
267
268   .cancel_label
269       This corresponds to the command-line  option  "--cancel-label  string".
270       The given string overrides the label used for “Cancel” buttons.
271
272   .cant_kill
273       This corresponds to the command-line option "--no-kill".  If true, this
274       tells dialog to put the tailboxbg box in the background,  printing  its
275       process  id  to dialog's output.  SIGHUP is disabled for the background
276       process.
277
278   .colors
279       This corresponds to  the  command-line  option  "--colors".   If  true,
280       interpret  embedded  "\Z" sequences in the dialog text by the following
281       character, which tells dialog to set  colors  or  video  attributes:  0
282       through 7 are the ANSI codes used in curses: black, red, green, yellow,
283       blue, magenta, cyan and white respectively.  Bold is set by 'b',  reset
284       by 'B'.  Reverse is set by 'r', reset by 'R'.  Underline is set by 'u',
285       reset by 'U'.  The settings are cumulative, e.g.,  "\Zb\Z1"  makes  the
286       following text bright red.  Restore normal settings with "\Zn".
287
288   .column_separator
289       This corresponds to the command-line option "--column-separator".  Dia‐
290       log splits data for radio/checkboxes and menus on  the  occurrences  of
291       the given string, and aligns the split data into columns.
292
293   .cr_wrap
294       This  corresponds  to  the  command-line  option "--cr-wrap".  If true,
295       interpret embedded newlines in the dialog text  as  a  newline  on  the
296       screen.   Otherwise,  dialog  will  only wrap lines where needed to fit
297       inside the text box.  Even though you  can  control  line  breaks  with
298       this,  dialog will still wrap any lines that are too long for the width
299       of the box.  Without cr-wrap, the layout of your text may be  formatted
300       to  look  nice  in the source code of your script without affecting the
301       way it will look in the dialog.
302
303   .date_format
304       This corresponds to the command-line option "--date-format string".  If
305       the host provides strftime, and the value is nonnull, the calendar wid‐
306       get uses this to format its output.
307
308   .default_button
309       This is set by the command-line option "--default-button.  It  is  used
310       by dlg_default_button.
311
312   .default_item
313       This  corresponds  to  the command-line option "--default-item string".
314       The given string is used as the default item in a  checklist,  form  or
315       menu box.  Normally the first item in the box is the default.
316
317   .defaultno
318       This  corresponds  to  the command-line option "--defaultno".  If true,
319       make the default value of the yes/no box a  No.   Likewise,  treat  the
320       default  button  of widgets that provide “OK” and “Cancel” as a Cancel.
321       If --nocancel was given that option overrides this, making the  default
322       button always “Yes” (internally the same as “OK”).
323
324   .dlg_clear_screen
325       This  corresponds to the command-line option "--clear".  This option is
326       implemented in the main program, not the library.  If true, the  screen
327       will  be  cleared  on  exit.   This  may  be  used alone, without other
328       options.
329
330   .exit_label
331       This corresponds to the command-line option "--exit-label string".  The
332       given string overrides the label used for “EXIT” buttons.
333
334   .extra_button
335       This corresponds to the command-line option "--extra-button".  If true,
336       some widgets show an extra button, between “OK” and “Cancel” buttons.
337
338   .extra_label
339       This corresponds to the  command-line  option  "--extra-label  string".
340       The  given  string overrides the label used for “Extra” buttons.  Note:
341       for inputmenu widgets, this defaults to “Rename”.
342
343   .formitem_type
344       This is set by the command-line option  "--passwordform"  to  tell  the
345       form  widget  that its text fields should be treated like password wid‐
346       gets.
347
348   .help_button
349       This corresponds to the command-line option "--help-button".  If  true,
350       some  widgets show a help-button after “OK” and “Cancel” buttons, i.e.,
351       in checklist, radiolist and menu boxes.  If --item-help is also  given,
352       on  exit the return status will be the same as for the “OK” button, and
353       the item-help text will be written to dialog's output after  the  token
354       “HELP”.   Otherwise, the return status will indicate that the Help but‐
355       ton was pressed, and no message printed.
356
357   .help_file
358       This corresponds to the  command-line  option  "--hfile  string".   The
359       given filename is passed to dialog_helpfile when the user presses F1.
360
361   .help_label
362       This corresponds to the command-line option "--help-label string".  The
363       given string overrides the label used for “Help” buttons.
364
365   .help_line
366       This corresponds to the  command-line  option  "--hline  string".   The
367       given  string is displayed in the bottom of dialog windows, like a sub‐
368       title.
369
370   .help_status
371       This corresponds to the command-line option "--help-status".  If  true,
372       and  the the help-button is selected, writes the checklist or radiolist
373       information after the item-help “HELP” information.  This can  be  used
374       to  reconstruct  the  state  of  a  checklist after processing the help
375       request.
376
377   .help_tags
378       This corresponds to the command-line option  "--help-tags".   If  true,
379       dlg_add_help_formitem  and  dlg_add_help_listitem  use  the  item's tag
380       value consistently rather than using the  tag's  help-text  value  when
381       DIALOG_VARS.item_help is set.
382
383   .input_length
384       This  is nonzero if DIALOG_VARS.input_result is allocated, versus being
385       a pointer to the user's local variables.
386
387   .input_menu
388       This flag is set to denote whether the menubox widget implements a menu
389       versus a inputmenu widget.
390
391   .input_result
392       This  may  be  either  a  user-supplied buffer, or a buffer dynamically
393       allocated by the library, depending on DIALOG_VARS.input_length:
394
395       ·   If DIALOG_VARS.input_length is zero, this is a pointer to user buf‐
396           fer  (on  the  stack, or static).  The buffer size is assumed to be
397           MAX_LEN, which is defined in <dialog.h>.
398
399       ·   When DIALOG_VARS.input_length is nonzero, this  is  a  dynamically-
400           allocated buffer used by the widgets to return printable results to
401           the calling application.
402
403       Certain widgets copy a result to this buffer.  If the pointer is  NULL,
404       or  if  the  length  is  insufficient  for  the result, then the dialog
405       library allocates a  buffer  which  is  large  enough,  and  sets  DIA‐
406       LOG_VARS.input_length.  Callers should check for this case if they have
407       supplied their own buffer.
408
409   .insecure
410       This corresponds to the command-line  option  "--insecure".   If  true,
411       make  the password widget friendlier but less secure, by echoing aster‐
412       isks for each character.
413
414   .in_helpfile
415       This variable is used to prevent dialog_helpfile from showing anything,
416       e.g., if F1 were pressed within a help-file display.
417
418   .iso_week
419       This  corresponds  to the command-line option "--iso-week".  It is used
420       in the calendar widget to tell how to compute the starting week for the
421       year:
422
423       ·   by  default, the calendar treats January 1 as the first week of the
424           year.
425
426       ·   If this variable is true, the calendar uses ISO 8601's  convention.
427           ISO 8601 numbers weeks starting with the first week in January with
428           a Thursday in the current year.  January 1 may be in  the  previous
429           year.
430
431   .item_help
432       This  corresponds  to  the command-line option "--item-help".  If true,
433       interpret the tags data for checklist, radiolist and menu boxes  adding
434       a  column whose text is displayed in the bottom line of the screen, for
435       the currently selected item.
436
437   .keep_tite
438       This is set by the command-line option "--keep-tite" to tell dialog  to
439       not  attempt  to  cancel  the  terminal  initialization (termcap ti/te)
440       sequences which correspond to xterm's alternate-screen switching.  Nor‐
441       mally  dialog does this to avoid flickering when run several times in a
442       script.
443
444   .keep_window
445       This corresponds to the command-line option "--keep-window".  If  true,
446       do  not  remove/repaint the window on exit.  This is useful for keeping
447       the window contents visible when several widgets are run  in  the  same
448       process.   Note  that  curses will clear the screen when starting a new
449       process.
450
451   .last_key
452       This corresponds to the command-line option "--last-key".
453
454   .max_input
455       This corresponds to the command-line option "--max-input size".   Limit
456       input strings to the given size.  If not specified, the limit is 2048.
457
458   .no_items
459       This corresponds to the command-line option "--no-items".  Some widgets
460       (checklist, inputmenu, radiolist, menu) display a list with two columns
461       (a  “tag”  and “item”, i.e., “description”).  This tells dialog to read
462       shorter rows from data, omitting the “list”.
463
464   .no_label
465       This corresponds to the command-line option "--no-label  string".   The
466       given string overrides the label used for “No” buttons.
467
468   .no_lines
469       This corresponds to the command-line option "--no-lines.  It suppresses
470       line-drawing.  See DIALOG_VARS.ascii_lines.
471
472   .no_nl_expand
473       This corresponds  to  the  command-line  option  "--no-nl-expand".   If
474       false,  dlg_trim_string  converts  literal "\n" substrings in a message
475       into newlines.
476
477   .no_tags
478       This corresponds to the command-line option "--no-tags".  Some  widgets
479       (checklist, inputmenu, radiolist, menu) display a list with two columns
480       (a “tag” and “item”, also known as “description”).  The tag  is  useful
481       for  scripting,  but may not help the user.  The --no-tags option (from
482       Xdialog) may be used to suppress the column of tags from the display.
483
484       Normally dialog allows you to quickly move to entries on the  displayed
485       list, by matching a single character to the first character of the tag.
486       When the --no-tags option is given, dialog matches  against  the  first
487       character  of the description.  In either case, the matchable character
488       is highlighted.
489
490       Here is a table showing how the no_tags and no_items values interact:
491
492       Widget      Fields Shown   Fields Read   .no_items   .no_tags
493       ──────────────────────────────────────────────────────────────
494       buildlist   item           tag,item          0          0*
495       buildlist   item           tag,item          0          1
496       buildlist   tag            tag               1          0*
497       buildlist   tag            tag               1          1
498       checklist   tag,item       tag,item          0          0
499       checklist   item           tag,item          0          1
500       checklist   tag            tag               1          0
501       checklist   tag            tag               1          1
502       inputmenu   tag,item       tag,item          0          0
503       inputmenu   item           tag,item          0          1
504       inputmenu   tag            tag               1          0
505       inputmenu   tag            tag               1          1
506       menu        tag,item       tag,item          0          0
507       menu        item           tag,item          0          1
508       menu        tag            tag               1          0
509       menu        tag            tag               1          1
510       radiolist   tag,item       tag,item          0          0
511       radiolist   item           tag,item          0          1
512       radiolist   tag            tag               1          0
513       radiolist   tag            tag               1          1
514       treeview    item           tag,item          0          0*
515       treeview    item           tag,item          0          1
516       treeview    tag            tag               1          0*
517       treeview    tag            tag               1          1
518       ──────────────────────────────────────────────────────────────
519
520       * Xdialog does not display the tag column for the  analogous  buildlist
521         and  treeview  widgets.   Dialog  does  the same on the command-line.
522         However the library interface defaults to displaying the tag  column.
523         Your  application  can enable or disable the tag column as needed for
524         each widget.
525
526   .nocancel
527       This corresponds to the command-line option  "--no-cancel".   If  true,
528       suppress the “Cancel” button in checklist, inputbox and menu box modes.
529       A script can still test if the user pressed the ESC key  to  cancel  to
530       quit.
531
532   .nocollapse
533       This  corresponds to the command-line option "--no-collapse".  Normally
534       dialog converts tabs to spaces and reduces multiple spaces to a  single
535       space  for  text  which is displayed in a message boxes, etc.  It true,
536       that feature is disabled.  Note that dialog will still wrap text,  sub‐
537       ject to the --cr-wrap option.
538
539   .nook
540       This  corresponds to the command-line option "--nook.  Dialog will sup‐
541       press the “ok” (or “yes”) button from the widget.
542
543   .ok_label
544       This corresponds to the command-line option "--ok-label  string".   The
545       given string overrides the label used for “OK” buttons.
546
547   .print_siz
548       This  corresponds  to the command-line option "--print-size".  If true,
549       each widget prints its size to dialog's output when it is invoked.
550
551   .quoted
552       This corresponds to the command-line option "--quoted.  Normally dialog
553       quotes  the  strings  returned  by checklist's as well as the item-help
554       text.  If true, dialog will quote all string results.
555
556   .reorder
557       This corresponds to the command-line option  "--reorder.   By  default,
558       the buildlist widget uses the same order for the output (right) list as
559       for the input (left).  If true, dialog will use the order  in  which  a
560       user adds selections to the output list.
561
562   .separate_output
563       This  corresponds  to  the command-line option "--separate-output".  If
564       true, checklist widgets output result one line at a time, with no quot‐
565       ing.  This facilitates parsing by another program.
566
567   .single_quoted
568       This  corresponds  to  the  command-line  option "--single-quoted".  If
569       true, use single-quoting as needed (and no quotes if unneeded) for  the
570       output of checklist's as well as the item-help text.  If this option is
571       not set, dialog uses  double  quotes  around  each  item.   The  latter
572       requires  occasional  use  of  backslashes to make the output useful in
573       shell scripts.
574
575   .size_err
576       This corresponds to the command-line  option  "--size-err".   If  true,
577       check  the  resulting  size  of  a  dialog box before trying to use it,
578       printing the resulting size if it is larger  than  the  screen.   (This
579       option is obsolete, since all new-window calls are checked).
580
581   .sleep_secs
582       This  corresponds  to  the  command-line  option  "--sleep secs".  This
583       option is implemented  in  the  main  program,  not  the  library.   If
584       nonzero,  this is the number of seconds after to delay after processing
585       a dialog box.
586
587   .tab_correct
588       This corresponds to the command-line option "--tab-correct".  If  true,
589       convert  each  tab character of the text to one or more spaces.  Other‐
590       wise, tabs are rendered according to the curses  library's  interpreta‐
591       tion.
592
593   .time_format
594       This corresponds to the command-line option "--time-format string".  If
595       the host provides strftime, and the value is nonnull, the timebox  wid‐
596       get uses this to format its output.
597
598   .timeout_secs
599       This  corresponds  to  the  command-line  option  "--timeout secs".  If
600       nonzero, timeout input requests (exit  with  error  code)  if  no  user
601       response within the given number of seconds.
602
603   .title
604       This corresponds to the command-line option "--title title".  Specifies
605       a title string to be displayed at the top of the dialog box.
606
607   .trim_whitespace
608       This corresponds to the command-line option "--trim".  If true,  elimi‐
609       nate  leading  blanks,  trim  literal newlines and repeated blanks from
610       message text.
611
612   .week_start
613       This corresponds to the command-line option "--week-start".  It is used
614       in  the  calendar  widget  to  set  the starting day for the week.  The
615       string value can be
616
617       ·   a number (0 to 6, Sunday through Saturday using POSIX) or
618
619       ·   the special value “locale” (this works with  systems  using  glibc,
620           providing  an  extension  to  the locale command, the first_weekday
621           value).
622
623       ·   a string matching one of the abbreviations for the day of the  week
624           shown in the calendar widget, e.g., “Mo” for “Monday”.
625
626   .yes_label
627       This  corresponds to the command-line option "--yes-label string".  The
628       given string overrides the label used for “Yes” buttons.
629

WIDGETS

631       Functions that implement major functionality for the command-line  dia‐
632       log program, e.g., widgets, have names beginning "dialog_".
633
634       All dialog boxes have at least three parameters:
635
636          title
637               the caption for the box, shown on its top border.
638
639          height
640               the height of the dialog box.
641
642          width
643               the width of the dialog box.
644
645       Other parameters depend on the box type.
646
647   dialog_buildlist
648       implements the "--buildlist" option.
649
650       const char * title
651            is the title on the top of the widget.
652
653       const char * cprompt
654            is the prompt text shown within the widget.
655
656       int height
657            is the desired height of the box.  If zero, the height is adjusted
658            to use the available screen size.
659
660       int width
661            is the desired width of the box.  If zero, the height is  adjusted
662            to use the available screen size.
663
664       int list_height
665            is  the  minimum  height  to  reserve for displaying the list.  If
666            zero, it is computed based on the given height and width.
667
668       int item_no
669            is the number of rows in items.
670
671       char ** items
672            is an array of strings which is viewed either as a list of rows
673            tag item status
674
675            or
676            tag item status help
677
678            depending on whether dialog_vars.item_help is set.
679
680       int order_mode
681            is reserved for future enhancements
682
683   dialog_calendar
684       implements the "--calendar" option.
685
686       const char * title
687            is the title on the top of the widget.
688
689       const char * subtitle
690            is the prompt text shown within the widget.
691
692       int height
693            is the height excluding the fixed-height calendar grid.
694
695       int width
696            is the overall width of the box, which is adjusted up to the  cal‐
697            endar grid's minimum width if needed.
698
699       int day
700            is the initial day of the week shown, counting zero as Sunday.  If
701            the value is negative, the current day of the week is used.
702
703       int month
704            is the initial month of the year shown, counting one  as  January.
705            If the value is negative, the current month of the year is used.
706
707       int year
708            is  the initial year shown.  If the value is negative, the current
709            year is used.
710
711   dialog_checklist
712       implements the "--checklist" and "--radiolist" options depending on the
713       flag parameter.
714
715       const char * title
716            is the title on the top of the widget.
717
718       const char * cprompt
719            is the prompt text shown within the widget.
720
721       int height
722            is the desired height of the box.  If zero, the height is adjusted
723            to use the available screen size.
724
725       int width
726            is the desired width of the box.  If zero, the height is  adjusted
727            to use the available screen size.
728
729       int list_height
730            is  the  minimum  height  to  reserve for displaying the list.  If
731            zero, it is computed based on the given height and width.
732
733       int item_no
734            is the number of rows in items.
735
736       int items
737            is an array of strings which is viewed either as a list of rows
738            tag item status
739
740            or
741            tag item status help
742
743            depending on whether dialog_vars.item_help is set.
744
745       flag is either FLAG_CHECK, for  checklists,  or  FLAG_RADIO  for  radi‐
746            olists.
747
748   dialog_dselect
749       implements the "--dselect" option.
750
751       const char * title
752            is the title on the top of the widget.
753
754       const char * path
755            is  the  preselected value to show in the input-box, which is used
756            also to set the directory- and file-windows.
757
758       int height
759            is the height excluding the minimum needed to show the dialog  box
760            framework.  If zero, the height is based on the screen size.
761
762       int width
763            is  the desired width of the box.  If zero, the height is based on
764            the screen size.
765
766   dialog_editbox
767       implements the "--editbox" option.
768
769       const char * title
770            is the title on the top of the widget.
771
772       const char * file
773            is the name of the file from which to read.
774
775       int height
776            is the desired height of the box.  If zero, the height is adjusted
777            to use the available screen size.
778
779       int width
780            is  the desired width of the box.  If zero, the height is adjusted
781            to use the available screen size.
782
783   dialog_form
784       implements the "--form" option.
785
786       const char * title
787            is the title on the top of the widget.
788
789       const char * cprompt
790            is the prompt text shown within the widget.
791
792       int height
793            is the desired height of the box.  If zero, the height is adjusted
794            to use the available screen size.
795
796       int width
797            is  the desired width of the box.  If zero, the height is adjusted
798            to use the available screen size.
799
800       int form_height
801            is the minimum height to reserve  for  displaying  the  list.   If
802            zero, it is computed based on the given height and width.
803
804       int item_no
805            is the number of rows in items.
806
807       int items
808            is an array of strings which is viewed either as a list of rows
809            Name NameY NameX Text TextY TextX FLen ILen
810
811            or
812            Name NameY NameX Text TextY TextX FLen ILen Help
813
814            depending on whether dialog_vars.item_help is set.
815
816   dialog_fselect
817       implements the "--fselect" option.
818
819       const char * title
820            is the title on the top of the widget.
821
822       const char * path
823            is  the  preselected value to show in the input-box, which is used
824            also to set the directory- and file-windows.
825
826       int height
827            is the height excluding the minimum needed to show the dialog  box
828            framework.  If zero, the height is based on the screen size.
829
830       int width
831            is  the desired width of the box.  If zero, the height is based on
832            the screen size.
833
834   dialog_gauge
835       implements the "--gauge" option.  Alternatively, a simpler  or  custom‐
836       ized  gauge  widget can be set up using dlg_allocate_gauge, dlg_reallo‐
837       cate_gauge, dlg_update_gauge and dlg_free_gauge.
838
839       const char * title
840            is the title on the top of the widget.
841
842       const char * cprompt
843            is the prompt text shown within the widget.
844
845       int height
846            is the desired height of the box.  If zero, the height is based on
847            the screen size.
848
849       int width
850            is  the desired width of the box.  If zero, the height is based on
851            the screen size.
852
853       int percent
854            is the percentage to show in the progress bar.
855
856   dialog_inputbox
857       implements the "--inputbox" or "--password" option,  depending  on  the
858       value of password.
859
860       const char * title
861            is the title on the top of the widget.
862
863       const char * cprompt
864            is the prompt text shown within the widget.
865
866       int height
867            is the desired height of the box.  If zero, the height is based on
868            the screen size.
869
870       int width
871            is the desired width of the box.  If zero, the height is based  on
872            the screen size.
873
874       const char * init
875            is  the initial value of the input box, whose length is taken into
876            account when auto-sizing the width of the dialog box.
877
878       int password
879            if true, causes typed input to be echoed as asterisks.
880
881   dialog_helpfile
882       implements the "--hfile" option.
883
884       const char * title
885            is the title on the top of the widget.
886
887       const char * file
888            is the name of a file containing the text to display.  This  func‐
889            tion  is  internally  bound to F1 (function key “1”), passing dia‐
890            log_vars.help_file as a parameter.  The dialog program  sets  that
891            variable when the --hfile option is given.
892
893       int height
894            is the desired height of the box.  If zero, the height is based on
895            the screen size.
896
897       int width
898            is the desired width of the box.  If zero, the height is based  on
899            the screen size.
900
901   dialog_menu
902       implements  the  "--menu"  or "--inputmenu" option depending on whether
903       dialog_vars.input_menu is set.
904
905       const char * title
906            is the title on the top of the widget.
907
908       const char * cprompt
909            is the prompt text shown within the widget.
910
911       int height
912            is the desired height of the box.  If zero, the height is based on
913            the screen size.
914
915       int width
916            is  the desired width of the box.  If zero, the height is based on
917            the screen size.
918
919       int menu_height
920            is the minimum height to reserve  for  displaying  the  list.   If
921            zero, it is computed based on the given height and width.
922
923       int item_no
924            is the number of rows in items.
925
926       int items
927            is an array of strings which is viewed either as a list of rows
928            tag item
929
930            or
931            tag item help
932
933            depending on whether dialog_vars.item_help is set.
934
935   dialog_mixedform
936       implements the "--mixedform" option.
937
938       const char * title
939            is the title on the top of the widget.
940
941       const char * cprompt
942            is the prompt text shown within the widget.
943
944       int height
945            is the desired height of the box.  If zero, the height is adjusted
946            to use the available screen size.
947
948       int width
949            is the desired width of the box.  If zero, the height is  adjusted
950            to use the available screen size.
951
952       int form_height
953            is  the  minimum  height  to  reserve for displaying the list.  If
954            zero, it is computed based on the given height and width.
955
956       int item_no
957            is the number of rows in items.
958
959       int items
960            is an array of strings which is viewed either as a list of rows
961            Name NameY NameX Text TextY TextX FLen ILen Ityp
962
963            or
964            Name NameY NameX Text TextY TextX FLen ILen Ityp Help
965
966            depending on whether dialog_vars.item_help is set.
967
968   dialog_mixedgauge
969       implements the "--mixedgauge" option
970
971       const char * title
972            is the title on the top of the widget.
973
974       const char * cprompt
975            is the caption text shown within the widget.
976
977       int height
978            is the desired height of the box.  If zero, the height is based on
979            the screen size.
980
981       int width
982            is  the desired width of the box.  If zero, the height is based on
983            the screen size.
984
985       int percent
986            is the percentage to show in the progress bar.
987
988       int item_no
989            is the number of rows in items.
990
991       int items
992            is an array of strings which is viewed as a list of tag  and  item
993            values.   The  tag  values are listed, one per row, in the list at
994            the top of the widget.
995
996            The item values are decoded: digits 0 through 9 are the  following
997            strings
998
999            0      Succeeded
1000
1001            1      Failed
1002
1003            2      Passed
1004
1005            3      Completed
1006
1007            4      Checked
1008
1009            5      Done
1010
1011            6      Skipped
1012
1013            7      In Progress
1014
1015            8      (blank)
1016
1017            9      N/A
1018
1019            A  string  with  a  leading "-" character is centered, marked with
1020            "%".  For example, "-75" is displayed as "75%".  Other strings are
1021            displayed as is.
1022
1023   dialog_msgbox
1024       implements  the  "--msgbox"  or "--infobox" option depending on whether
1025       pauseopt is set.
1026
1027       const char * title
1028            is the title on the top of the widget.
1029
1030       const char * cprompt
1031            is the prompt text shown within the widget.
1032
1033       int height
1034            is the desired height of the box.  If zero, the height is based on
1035            the screen size.
1036
1037       int width
1038            is  the desired width of the box.  If zero, the height is based on
1039            the screen size.
1040
1041       int pauseopt
1042            if true, an “OK” button will be shown, and the  dialog  will  wait
1043            for  it  to  complete.  With an “OK” button, it is denoted a “msg‐
1044            box”, without an “OK” button, it is denoted an “infobox”.
1045
1046   dialog_pause
1047       implements the "--pause" option.
1048
1049       const char * title
1050            is the title on the top of the widget.
1051
1052       int height
1053            is the desired height of the box.  If zero, the height is based on
1054            the screen size.
1055
1056       int width
1057            is  the desired width of the box.  If zero, the height is based on
1058            the screen size.
1059
1060       int seconds
1061            is the timeout to use for the progress bar.
1062
1063   dialog_prgbox
1064       implements the "--prgbox" option.
1065
1066       const char * title
1067            is the title on the top of the widget.
1068
1069       const char * cprompt
1070            is the prompt text shown within the widget.  If empty or null,  no
1071            prompt is shown.
1072
1073       const char * command
1074            is the name of the command to execute.
1075
1076       int height
1077            is the desired height of the box.  If zero, the height is based on
1078            the screen size.
1079
1080       int width
1081            is the desired width of the box.  If zero, the height is based  on
1082            the screen size.
1083
1084       int pauseopt
1085            if  true,  an  “OK” button will be shown, and the dialog will wait
1086            for it to complete.
1087
1088   dialog_progressbox
1089       implements the "--progressbox" option.
1090
1091       const char * title
1092            is the title on the top of the widget.
1093
1094       const char * cprompt
1095            is the prompt text shown within the widget.  If empty or null,  no
1096            prompt is shown.
1097
1098       int height
1099            is the desired height of the box.  If zero, the height is based on
1100            the screen size.
1101
1102       int width
1103            is the desired width of the box.  If zero, the height is based  on
1104            the screen size.
1105
1106   dialog_rangebox
1107       implements the "--rangebox" option.
1108
1109       const char * title
1110            is the title on the top of the widget.
1111
1112       const char * cprompt
1113            is  the prompt text shown within the widget.  If empty or null, no
1114            prompt is shown.
1115
1116       int height
1117            is the desired height of the widget.  If zero, the height is based
1118            on the screen size.
1119
1120       int width
1121            is  the desired width of the widget.  If zero, the height is based
1122            on the screen size.
1123
1124       int min_value
1125            is the minimum value to allow.
1126
1127       int max_value
1128            is the maximum value to allow.
1129
1130       int default_value
1131            is the default value, if no change is made.
1132
1133   dialog_tailbox
1134       implements the "--tailbox" or "--tailboxbg" option depending on whether
1135       bg_task is set.
1136
1137       const char * title
1138            is the title on the top of the widget.
1139
1140       const char * file
1141            is the name of the file to display in the dialog.
1142
1143       int height
1144            is the desired height of the box.  If zero, the height is based on
1145            the screen size.
1146
1147       int width
1148            is the desired width of the box.  If zero, the height is based  on
1149            the screen size.
1150
1151       int bg_task
1152            if true, the window is added to the callback list in dialog_state,
1153            and the application will poll for the window to be updated.   Oth‐
1154            erwise  an  “OK”  button  is  added  to the window, and it will be
1155            closed when the button is activated.
1156
1157   dialog_textbox
1158       implements the "--textbox" option.
1159
1160       const char * title
1161            is the title on the top of the widget.
1162
1163       const char * file
1164            is the name of the file to display in the dialog.
1165
1166       int height
1167            is the desired height of the box.  If zero, the height is based on
1168            the screen size.
1169
1170       int width
1171            is  the desired width of the box.  If zero, the height is based on
1172            the screen size.
1173
1174   dialog_timebox
1175       implements the "--timebox" option.
1176
1177       const char * title
1178            is the title on the top of the widget.
1179
1180       const char * subtitle
1181            is the prompt text shown within the widget.
1182
1183       int height
1184            is the desired height of the box.  If zero, the height is based on
1185            the screen size.
1186
1187       int width
1188            is  the desired width of the box.  If zero, the height is based on
1189            the screen size.
1190
1191       int hour
1192            is the initial hour shown.  If the value is negative, the  current
1193            hour  is  used.   Returns DLG_EXIT_ERROR if the value specified is
1194            greater than or equal to 24.
1195
1196       int minute
1197            is the initial minute shown.  If the value is negative,  the  cur‐
1198            rent  minute  is used.  Returns DLG_EXIT_ERROR if the value speci‐
1199            fied is greater than or equal to 60.
1200
1201       int second
1202            is the initial second shown.  If the value is negative,  the  cur‐
1203            rent  second  is used.  Returns DLG_EXIT_ERROR if the value speci‐
1204            fied is greater than or equal to 60.
1205
1206   dialog_treeview
1207       implements the "--treeview" option.
1208
1209       const char * title
1210            is the title on the top of the widget.
1211
1212       const char * cprompt
1213            is the prompt text shown within the widget.
1214
1215       int height
1216            is the desired height of the box.  If zero, the height is based on
1217            the screen size.
1218
1219       int width
1220            is  the desired width of the box.  If zero, the height is based on
1221            the screen size.
1222
1223       int list_height
1224            is the minimum height to reserve  for  displaying  the  list.   If
1225            zero, it is computed based on the given height and width.
1226
1227       int item_no
1228            is the number of rows in items.
1229
1230       char ** items
1231            is  the  list  of  items,  contain  tag, name, and optionally help
1232            strings (if dialog_vars.item_help is set).  The initial  selection
1233            state for each item is also in this list.
1234
1235       int flag
1236
1237       flag is  either  FLAG_CHECK,  for  checklists (multiple selections), or
1238            FLAG_RADIO for radiolists (a single selection).
1239
1240   dialog_yesno
1241       implements the "--yesno" option.
1242
1243       const char * title
1244            is the title on the top of the widget.
1245
1246       const char * cprompt
1247            is the prompt text shown within the widget.
1248
1249       int height
1250            is the desired height of the box.  If zero, the height is based on
1251            the screen size.
1252
1253       int width
1254            is  the desired width of the box.  If zero, the height is based on
1255            the screen size.
1256

UTILITY FUNCTIONS

1258       Most functions that implement lower-level functionality  for  the  com‐
1259       mand-line dialog program or widgets, have names beginning "dlg_".  Bow‐
1260       ing to longstanding usage, the functions that  initialize  the  display
1261       and end it are named init_dialog and end_dialog.
1262
1263       The  only  non-widget function whose name begins with "dialog_" is dia‐
1264       log_version, which returns the version  number  of  the  library  as  a
1265       string.
1266
1267       Here is a brief summary of the utility functions and their parameters:
1268
1269   dlg_add_callback
1270       Add  a callback, used to allow polling input from multiple tailbox wid‐
1271       gets.
1272
1273       DIALOG_CALLBACK *p
1274            contains the callback information.
1275
1276   dlg_add_callback_ref
1277       Like dlg_add_callback, but passes a reference to the DIALOG_CALLBACK as
1278       well  as  a pointer to a cleanup function which will be called when the
1279       associated input ends.
1280
1281       DIALOG_CALLBACK **p
1282            points to the callback information.  This is a  reference  to  the
1283            pointer  so  that  the  caller's  pointer can be zeroed when input
1284            ends.
1285
1286       DIALOG_FREEBACK func
1287            function to call when input ends, e.g.,  to  free  caller's  addi‐
1288            tional data.
1289
1290   dlg_add_help_formitem
1291       This  is  a  utility  function used enforce consistent behavior for the
1292       DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1293
1294       int *result
1295            this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help  is
1296            set.
1297
1298       char **tag
1299            the tag- or help-text is stored here.
1300
1301       DIALOG_FORMITEM *item
1302            contains the list item to use for tag- or help-text.
1303
1304   dlg_add_help_listitem
1305       This  is  a  utility  function used enforce consistent behavior for the
1306       DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1307
1308       int *result
1309            this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help  is
1310            set.
1311
1312       char **tag
1313            the tag- or help-text is stored here.
1314
1315       DIALOG_LISTITEM *item
1316            contains the list item to use for tag- or help-text.
1317
1318   dlg_add_last_key
1319       Report  the  last key entered by the user.  This implements the --last-
1320       key command-line option, using dialog_vars.last_key.
1321
1322       int mode
1323            controls the way the last  key  report  is  separated  from  other
1324            results:
1325
1326            -2   (no separator)
1327
1328            -1   (separator after the key name)
1329
1330            0    (separator is optionally before the key name)
1331
1332            1    (same as -1)
1333
1334   dlg_add_quoted
1335       Add  a  quoted string to the result buffer (see dlg_add_result).  If no
1336       quotes are necessary, none are used.  If  dialog_vars.single_quoted  is
1337       set, single-quotes are used.  Otherwise, double-quotes are used.
1338
1339       char * string
1340            is the string to add.
1341
1342   dlg_add_result
1343       Add a string to the result buffer dialog_vars.input_result.
1344
1345       char * string
1346            is the string to add.
1347
1348   dlg_add_separator
1349       Add  an output-separator to the result buffer dialog_vars.input_result.
1350       If dialog_vars.output_separator is set, use that.  Otherwise,  if  dia‐
1351       log_vars.separate_output is set, use newline.  If neither is set, use a
1352       space.
1353
1354   dlg_add_string
1355       Add  a  quoted  or  unquoted  string  to   the   result   buffer   (see
1356       dlg_add_quoted)   and   dlg_add_result),   according  to  whether  dia‐
1357       log_vars.quoted is true.
1358
1359       char * string
1360            is the string to add.
1361
1362   dlg_align_columns
1363       Copy and reformat an array of pointers to strings,  aligning  according
1364       to  the  column  separator  dialog_vars.column_separator.  If no column
1365       separator is set, the array will be unmodified; otherwise it is  copied
1366       and reformatted.
1367
1368              Caveat: This function is only implemented for 8-bit characters.
1369
1370       char **target
1371            This  is  the array to reformat.  It points to the first string to
1372            modify.
1373
1374       int per_row
1375            This is the size of the struct for each row of the array.
1376
1377       int num_rows
1378            This is the number of rows in the array.
1379
1380   dlg_allocate_gauge
1381       Allocates a gauge widget.  Use dlg_update_gauge to display the result.
1382
1383       const char * title
1384            is the title string to display at the top of the widget.
1385
1386       const char * cprompt
1387            is the prompt text shown within the widget.
1388
1389       int height
1390            is the desired height of the box.  If zero, the height is adjusted
1391            to use the available screen size.
1392
1393       int width
1394            is  the desired width of the box.  If zero, the height is adjusted
1395            to use the available screen size.
1396
1397       int percent
1398            is the percentage to show in the progress bar.
1399
1400   dlg_asciibox
1401       returns its parameter transformed to  the  corresponding  "+"  or  "-",
1402       etc., for the line-drawing characters used in dialog.  If the parameter
1403       is not a line-drawing or other special character such as ACS_DARROW, it
1404       returns 0.
1405
1406       chtype ch
1407            is the parameter, usually one of the ACS_xxx constants.
1408
1409   dlg_attr_clear
1410       Set window to the given attribute.
1411
1412       WINDOW * win
1413            is the window to update.
1414
1415       int height
1416            is the number of rows to update.
1417
1418       int width
1419            is the number of columns to update.
1420
1421       chtype attr
1422            is the attribute, e.g., A_BOLD.
1423
1424   dlg_auto_size
1425       Compute window size based on the size of the formatted prompt and mini‐
1426       mum dimensions for a given widget.
1427
1428       Dialog sets dialog_state.text_height  and  dialog_state.text_width  for
1429       the formatted prompt as a side-effect.
1430
1431       Normally  dialog  writes the formatted prompt to the curses window, but
1432       it will write the  formatted  prompt  to  the  output  stream  if  dia‐
1433       log_state.text_only is set.
1434
1435       const char * title
1436            is the title string to display at the top of the widget.
1437
1438       const char * prompt
1439            is  the  message  text which will be displayed in the widget, used
1440            here to determine how large the widget should be.
1441
1442            If the value is NULL, dialog allows the widget to  use  the  whole
1443            screen,  i.e., if the values referenced by height and/or width are
1444            zero.
1445
1446       int * height
1447            is the nominal height.  Dialog checks the referenced value and may
1448            update it:
1449
1450            ·   if  the  value is negative, dialog updates it to the available
1451                height of the screen, after reserving rows for the window bor‐
1452                der   and   shadow,  as  well  as  taking  into  account  dia‐
1453                log_vars.begin_y and dialog_vars.begin_set.
1454
1455            ·   if the value is zero, dialog updates it to the required height
1456                of  the  window,  taking  into account a (possibly) multi-line
1457                prompt.
1458
1459            ·   if the value is greater than zero, dialog uses it  internally,
1460                but restores the value on return.
1461
1462       int * width
1463            is  the nominal width.  Dialog checks the referenced value and may
1464            update it:
1465
1466            ·   if the value is negative, dialog updates it to  the  available
1467                width  of the screen, after reserving rows for the window bor‐
1468                der  and  shadow,  as  well  as  taking  into   account   dia‐
1469                log_vars.begin_x and dialog_vars.begin_set.
1470
1471            ·   if  the value is zero, dialog updates it to the required width
1472                of the window, taking into  account  a  (possibly)  multi-line
1473                prompt.
1474
1475            ·   if  the value is greater than zero, dialog uses it internally,
1476                but restores the value on return.
1477
1478       int boxlines
1479            is the number of lines to reserve in the vertical direction.
1480
1481       int mincols
1482            is the minimum number of columns to use.
1483
1484   dlg_auto_sizefile
1485       Like dlg_auto_size, but use a file contents to  decide  how  large  the
1486       widget should be.
1487
1488       const char * title
1489            is the title string to display at the top of the widget.
1490
1491       const char * file
1492            is the name of the file.
1493
1494       int * height
1495            is the nominal height.
1496
1497            If  it  is  -1,  use  the  screen's height (after subtracting dia‐
1498            log_vars.begin_y if dialog_vars.begin_set is true).
1499
1500            If it is greater than zero, limit  the  referenced  value  to  the
1501            screen-height after verifying that the file exists.
1502
1503       int * width
1504            is the nominal width.
1505
1506            If  it  is  -1,  use  the  screen's  width (after subtracting dia‐
1507            log_vars.begin_x if dialog_vars.begin_set is true).
1508
1509            If it is greater than zero, limit  the  referenced  value  to  the
1510            screen-width after verifying that the file exists.
1511
1512       int boxlines
1513            is the number of lines to reserve on the screen for drawing boxes.
1514
1515       int mincols
1516            is  the  number  of  columns  to reserve on the screen for drawing
1517            boxes.
1518
1519   dlg_beeping
1520       If dialog_vars.beep_signal is nonzero, this calls beep  once  and  sets
1521       dialog_vars.beep_signal to zero.
1522
1523   dlg_boxchar
1524       returns its chtype parameter transformed as follows:
1525
1526       ·   if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is set.
1527
1528       ·   if dialog_vars.ascii_lines is set, returns the corresponding "+" or
1529           "-", etc., for the line-drawing characters used in dialog.
1530
1531       ·   otherwise, if dialog_vars.no_lines is set, returns a space for  the
1532           line-drawing characters.
1533
1534       ·   if  the  parameter is not a line-drawing or other special character
1535           such as ACS_DARROW, it returns the parameter unchanged.
1536
1537   dlg_box_x_ordinate
1538       returns a suitable x-ordinate (column)  for  a  new  widget.   If  dia‐
1539       log_vars.begin_set  is 1, use dialog_vars.begin_x; otherwise center the
1540       widget on the screen (using the width parameter).
1541
1542       int width
1543            is the width of the widget.
1544
1545   dlg_box_y_ordinate
1546       returns a  suitable  y-ordinate  (row)  for  a  new  widget.   If  dia‐
1547       log_vars.begin_set  is 1, use dialog_vars.begin_y; otherwise center the
1548       widget on the screen (using the height parameter).
1549
1550       int height
1551            is the height of the widget.
1552
1553   dlg_buildlist
1554       This is an alternate interface to the buildlist widget which allows the
1555       application  to read the list item states back directly without putting
1556       them in the output buffer.
1557
1558       const char * title
1559            is the title string to display at the top of the widget.
1560
1561       const char * cprompt
1562            is the prompt text shown within the widget.
1563
1564       int height
1565            is the desired height of the box.  If zero, the height is adjusted
1566            to use the available screen size.
1567
1568       int width
1569            is  the desired width of the box.  If zero, the height is adjusted
1570            to use the available screen size.
1571
1572       int list_height
1573            is the minimum height to reserve  for  displaying  the  list.   If
1574            zero, it is computed based on the given height and width.
1575
1576       int item_no
1577            is the number of rows in items.
1578
1579       DIALOG_LISTITEM * items
1580            is  the  list  of  items,  contain  tag, name, and optionally help
1581            strings (if dialog_vars.item_help is set).  The initial  selection
1582            state for each item is also in this list.
1583
1584       const char * states
1585            This  is  a  list  of  characters to display for the given states.
1586            Normally a buildlist provides true (1) and false (0) values, which
1587            the  widget  displays as "*" and space, respectively.  An applica‐
1588            tion may  set  this  parameter  to  an  arbitrary  null-terminated
1589            string.   The  widget  determines  the  number  of states from the
1590            length of this string, and will cycle  through  the  corresponding
1591            display characters as the user presses the space-bar.
1592
1593       int order_mode
1594            is reserved for future enhancements
1595
1596       int * current_item
1597            The  widget  sets the referenced location to the index of the cur‐
1598            rent display item (cursor) when it returns.
1599
1600   dlg_button_count
1601       Count the buttons in the list.
1602
1603       const char ** labels
1604            is a list of (pointers to) button  labels  terminated  by  a  null
1605            pointer.
1606
1607   dlg_button_key
1608       If a key was bound to one of the button-codes in dlg_result_key, fake a
1609       button-value and an “Cancel”  key to cause the calling widget to return
1610       the corresponding status.
1611
1612       See dlg_ok_buttoncode, which maps settings for ok/extra/help and button
1613       number into exit-code.
1614
1615   dlg_button_layout
1616       Make sure there is enough space for the buttons by computing the  width
1617       required  for  their  labels,  adding margins and limiting based on the
1618       screen size.
1619
1620       const char ** labels
1621            is a list of (pointers to) button  labels  terminated  by  a  null
1622            pointer.
1623
1624       int * limit
1625            the  function  sets the referenced limit to the width required for
1626            the buttons (limited by the screen size) if that is wider than the
1627            passed-in limit.
1628
1629   dlg_button_sizes
1630       Compute the size of the button array in columns.
1631
1632       const char ** labels
1633            is  a  list  of  (pointers  to) button labels terminated by a null
1634            pointer.
1635
1636       int vertical
1637            is true if the buttons are arranged in a column rather than a row.
1638
1639       int * longest
1640            Return the total number of columns in the referenced location.
1641
1642       int * length
1643            Return the longest button's columns in the referenced location.
1644
1645   dlg_button_to_char
1646       Find the first uppercase character in the label, which we may  use  for
1647       an  abbreviation.   If  the label is empty, return -1.  If no uppercase
1648       character is found, return 0.  Otherwise return the  uppercase  charac‐
1649       ter.
1650
1651       Normally  dlg_draw_buttons  and dlg_char_to_button use the first upper‐
1652       case character.  However, they keep track of all of the labels  and  if
1653       the  first  has  already been used in another label, they will continue
1654       looking for another uppercase character.  This function does  not  have
1655       enough information to make that check.
1656
1657       const char * label
1658            is the label to test.
1659
1660   dlg_button_x_step
1661       Compute the step-size needed between elements of the button array.
1662
1663       const char ** labels
1664            is  a  list  of  (pointers  to) button labels terminated by a null
1665            pointer.
1666
1667       int limit
1668            is the maximum number of columns to allow for the buttons.
1669
1670       int * gap
1671            store the nominal gap between buttons in the referenced  location.
1672            This is constrained to be at least one.
1673
1674       int * margin
1675            store  the  left+right  total margins (for the list of buttons) in
1676            the referenced location.
1677
1678       int * step
1679            store the step-size in the referenced location.
1680
1681   dlg_calc_list_width
1682       Calculate the minimum width for the list, assuming none  of  the  items
1683       are truncated.
1684
1685       int item_no
1686            is the number of items.
1687
1688       DIALOG_LISTITEM * items
1689            contains  a  name and text field, e.g., for checklists or radiobox
1690            lists.  The function returns the sum of the widest columns  needed
1691            for of each of these fields.
1692
1693            If  dialog_vars.no_items  is  set, the text fields in the list are
1694            ignored.
1695
1696   dlg_calc_listh
1697       Calculate new height and list_height values.
1698
1699       int * height
1700            on input, is  the  height  without  adding  the  list-height.   On
1701            return, this contains the total list-height and is the actual wid‐
1702            get's height.
1703
1704       int * list_height
1705            on input, is the requested list-height.  On return, this  contains
1706            the  number of rows available for displaying the list after taking
1707            into account the screen size  and  the  dialog_vars.begin_set  and
1708            dialog_vars.begin_y variables.
1709
1710       int item_no
1711            is the number of items in the list.
1712
1713   dlg_calc_listw
1714       This  function  is obsolete, provided for library-compatibility.  It is
1715       replaced by dlg_calc_list_width.
1716
1717       int item_no
1718            is the number of items.
1719
1720       char ** items
1721            is a list of character pointers.
1722
1723       int group
1724            is the number of items in  each  group,  e.g.,  the  second  array
1725            index.
1726
1727   dlg_char_to_button
1728       Given  a list of button labels, and a character which may be the abbre‐
1729       viation for one, find it, if it exists.  An abbreviation  will  be  the
1730       first  character  which happens to be capitalized in the label.  If the
1731       character is found, return its index within the list of labels.  Other‐
1732       wise, return DLG_EXIT_UNKNOWN.
1733
1734       int ch
1735            is the character to find.
1736
1737       const char ** labels
1738            is  a  list  of  (pointers  to) button labels terminated by a null
1739            pointer.
1740
1741   dlg_checklist
1742       This entrypoint provides the --checklist or  --radiolist  functionality
1743       without  the  limitations  of  dialog's command-line syntax (compare to
1744       dialog_checklist).
1745
1746       const char * title
1747            is the title string to display at the top of the widget.
1748
1749       const char * cprompt
1750            is the prompt text shown within the widget.
1751
1752       int height
1753            is the desired height of the box.  If zero, the height is adjusted
1754            to use the available screen size.
1755
1756       int width
1757            is  the desired width of the box.  If zero, the height is adjusted
1758            to use the available screen size.
1759
1760       int list_height
1761            is the minimum height to reserve  for  displaying  the  list.   If
1762            zero, it is computed based on the given height and width.
1763
1764       int item_no
1765            is the number of items.
1766
1767       DIALOG_LISTITEM * items
1768            This is a list of the items to display in the checklist.
1769
1770       const char * states
1771            This  is  a  list  of  characters to display for the given states.
1772            Normally a checklist provides true (1) and false (0) values, which
1773            the  widget  displays as "*" and space, respectively.  An applica‐
1774            tion may  set  this  parameter  to  an  arbitrary  null-terminated
1775            string.   The  widget  determines  the  number  of states from the
1776            length of this string, and will cycle  through  the  corresponding
1777            display characters as the user presses the space-bar.
1778
1779       int flag
1780            This  is  should  be one of FLAG_CHECK or FLAG_RADIO, depending on
1781            whether the widget should act as a checklist or radiobox.
1782
1783       int * current_item
1784            The widget sets the referenced location to the index of  the  cur‐
1785            rent display item (cursor) when it returns.
1786
1787   dlg_check_scrolled
1788       given  a function key (or other key that was mapped to a function key),
1789       check if it is one of the up/down scrolling functions:
1790
1791              DLGK_PAGE_FIRST,
1792              DLGK_PAGE_LAST,
1793              DLGK_GRID_UP,
1794              DLGK_GRID_DOWN,
1795              DLGK_PAGE_PREV or
1796              DLGK_PAGE_NEXT.
1797
1798       Some widgets use these key bindings for scrolling  the  prompt-text  up
1799       and down, to allow for display in very small windows.
1800
1801       The  function returns 0 (zero) if it finds one of these keys, and -1 if
1802       not.
1803
1804       int key
1805            is the function-key to check
1806
1807       int last
1808            is the number of lines which would be used to display the scrolled
1809            prompt  in  an  arbitrarily tall window.  It is used here to check
1810            limits for the offset value.
1811
1812       int page
1813            this is the available height for writing scrolled text,  which  is
1814            smaller than the window if it contains buttons.
1815
1816       bool * show
1817            on  return,  holds  TRUE  if  dlg_print_scrolled should be used to
1818            redisplay the prompt text.
1819
1820       int * offset
1821            on entry, holds the starting line number (counting from zero) last
1822            used  for dlg_print_scrolled.  On return, holds the updated start‐
1823            ing line number.
1824
1825   dlg_clear
1826       Set window to the default dialog screen attribute.  This is set in  the
1827       rc-file with screen_color.
1828
1829   dlg_clr_result
1830       Free  storage  used  for  the result buffer (dialog_vars.input_result).
1831       The corresponding pointer is set to NULL.
1832
1833   dlg_color_count
1834       Return the number of colors that can be configured in dialog.
1835
1836   dlg_color_setup
1837       Initialize the color pairs used in dialog.
1838
1839   dlg_count_argv
1840       Count the entries in an argument vector.
1841
1842       argv Points to the argument vector.
1843
1844   dlg_count_columns
1845       Returns the number of columns used for a string.  This is not necessar‐
1846       ily the number of bytes in a string.
1847
1848       const char * string
1849            is the string to measure.
1850
1851   dlg_count_real_columns
1852       Returns  the  number  of columns used for a string, accounting for "\Z"
1853       sequences which can be used for coloring the text if dialog_vars.colors
1854       is set.  This is not necessarily the number of bytes in a string.
1855
1856       const char * string
1857            is the string to measure.
1858
1859   dlg_count_wchars
1860       Returns the number of wide-characters in the string.
1861
1862       const char * string
1863            is the string to measure.
1864
1865   dlg_create_rc
1866       Create  a  configuration  file,  i.e.,  write internal tables to a file
1867       which can be read back by dialog as an rc-file.
1868
1869       const char * filename
1870            is the name of the file to write to.
1871
1872   dlg_ctl_size
1873       If dialog_vars.size_err is true, check if the given window size is  too
1874       large  to  fit  on the screen.  If so, exit with an error reporting the
1875       size of the window.
1876
1877       int height
1878            is the window's height
1879
1880       int width
1881            is the window's width
1882
1883   dlg_default_button
1884       If dialog_vars.default_button is positive, return the button-index  for
1885       that button code, using dlg_ok_buttoncode to test indices starting with
1886       zero.  Otherwise (or if no match was found for the button code), return
1887       zero.
1888
1889   dlg_default_formitem
1890       If dialog_vars.default_item is not null, find that name by matching the
1891       name field in the list of form items.  If found, return  the  index  of
1892       that item in the list.  Otherwise, return zero.
1893
1894       DIALOG_FORMITEM * items
1895            is the list of items to search.  It is terminated by an entry with
1896            a null name field.
1897
1898   dlg_default_item
1899       This function is obsolete, provided for library-compatibility.   It  is
1900       replaced by dlg_default_formitem and dlg_default_listitem.
1901
1902       char ** items
1903            is the list of items to search.
1904
1905       int llen
1906            is  the  number  of  items  in  each group, e.g., the second array
1907            index.
1908
1909   dlg_defaultno_button
1910       If dialog_vars.defaultno is true, and dialog_vars.nocancel is not, find
1911       the  button-index for the “Cancel” button.  Otherwise, return the index
1912       for “OK” (always zero).
1913
1914   dlg_del_window
1915       Remove a window, repainting everything else.
1916
1917       WINDOW * win
1918            is the window to remove.
1919
1920   dlg_does_output
1921       This is called each time a widget is invoked which may do  output.   It
1922       increments  dialog_state.output_count, so the output function in dialog
1923       can test this and add a separator.
1924
1925   dlg_draw_arrows
1926       Draw up/down arrows on a window, e.g., for scrollable lists.  It  calls
1927       dlg_draw_arrows2   using  the  menubox_color  and  menubox_border_color
1928       attributes.
1929
1930       WINDOW * dialog
1931            is the window on which to draw an arrow.
1932
1933       int top_arrow
1934            is true if an up-arrow should be drawn at the top of the window.
1935
1936       int bottom_arrow
1937            is true if an down-arrow should be drawn at the bottom of the win‐
1938            dow.
1939
1940       int x
1941            is  the  zero-based  column  within  the  window  on which to draw
1942            arrows.
1943
1944       int top
1945            is the zero-based row within the window on which to draw up-arrows
1946            as well as a horizontal line to show the window's top.
1947
1948       int bottom
1949            is  the  zero-based  row  within the window on which to draw down-
1950            arrows as well as a horizontal line to show the window's bottom.
1951
1952   dlg_draw_arrows2
1953       Draw up/down arrows on a window, e.g., for scrollable lists.
1954
1955       WINDOW * dialog
1956            is the window on which to draw an arrow.
1957
1958       int top_arrow
1959            is true if an up-arrow should be drawn at the top of the window.
1960
1961       int bottom_arrow
1962            is true if an down-arrow should be drawn at the bottom of the win‐
1963            dow.
1964
1965       int x
1966            is  the  zero-based  column  within  the  window  on which to draw
1967            arrows.
1968
1969       int top
1970            is the zero-based row within the window on which to draw up-arrows
1971            as well as a horizontal line to show the window's top.
1972
1973       int bottom
1974            is  the  zero-based  row  within the window on which to draw down-
1975            arrows as well as a horizontal line to show the window's bottom.
1976
1977       chtype attr
1978            is the window's background attribute.
1979
1980       chtype borderattr
1981            is the window's border attribute.
1982
1983   dlg_draw_bottom_box
1984       Draw a partial box at the bottom of a window, e.g., to surround  a  row
1985       of  buttons.   It  is designed to merge with an existing box around the
1986       whole window (see dlg_draw_box), so it uses  tee-elements  rather  than
1987       corner-elements on the top corners of this box.
1988
1989       WINDOW * win
1990            is the window to update.
1991
1992   dlg_draw_bottom_box2
1993       Draw  a  partial box at the bottom of a window, e.g., to surround a row
1994       of buttons.  It is designed to merge with an existing  box  around  the
1995       whole  window  (see dlg_draw_box2), so it uses tee-elements rather than
1996       corner-elements on the top corners of this box.
1997
1998       WINDOW * win
1999            is the window to update.
2000
2001       chtype on_left
2002            is used to color the upper/left edges of the box, i.e.,  the  tee-
2003            element and horizontal line
2004
2005       chtype on_right
2006            is used to color the right edge of the box, i.e., the tee-element
2007
2008       chtype on_inside
2009            is used to fill-color the inside of the box
2010
2011   dlg_draw_box
2012       Draw a rectangular box with line drawing characters.
2013
2014       WINDOW * win
2015            is the window to update.
2016
2017       int y
2018            is the top row of the box.
2019
2020       int x
2021            is the left column of the box.
2022
2023       int height
2024            is the height of the box.
2025
2026       int width
2027            is the width of the box.
2028
2029       chtype boxchar
2030            is  used  to  color  the right/lower edges.  It also is fill-color
2031            used for the box contents.
2032
2033       chtype borderchar
2034            is used to color the upper/left edges.
2035
2036   dlg_draw_box2
2037       Draw a rectangular box with line drawing characters.
2038
2039       WINDOW * win
2040            is the window to update.
2041
2042       int y
2043            is the top row of the box.
2044
2045       int x
2046            is the left column of the box.
2047
2048       int height
2049            is the height of the box.
2050
2051       int width
2052            is the width of the box.
2053
2054       chtype boxchar
2055            is used to fill-color for the box contents.
2056
2057       chtype borderchar
2058            is used to color the upper/left edges.
2059
2060       chtype borderchar2
2061            is used to color the right/lower edges.
2062
2063   dlg_draw_buttons
2064       Print a list of buttons at the given position.
2065
2066       WINDOW * win
2067            is the window to update.
2068
2069       int y
2070            is the starting row.
2071
2072       int x
2073            is the starting column.
2074
2075       const char ** labels
2076            is a list of (pointers to) button  labels  terminated  by  a  null
2077            pointer.
2078
2079       int selected
2080            is the index within the list of the selected button.
2081
2082       int vertical
2083            is true if the buttons are arranged in a column rather than a row.
2084
2085       int limit
2086            is  the  number  of  columns (or rows if vertical) allowed for the
2087            display.
2088
2089   dlg_draw_helpline
2090       draw the text in dialog_vars.help_line at the bottom of the given  win‐
2091       dow.
2092
2093       WINDOW * dialog
2094            is the window to modify.
2095
2096       bool decorations
2097            if true, allow room for the scrolling arrows.
2098
2099   dlg_draw_scrollbar
2100       If  dialog_state.use_scrollbar  is  set,  draw a scrollbar on the right
2101       margin of windows holding scrollable data.  Also (whether  or  not  the
2102       scrollbar  is drawn), annotate the bottom margin of the window with the
2103       percentage  of  data  by  the  bottom  of   that   window,   and   call
2104       dlg_draw_arrows2 to put markers on the window showing when more data is
2105       available.
2106
2107       WINDOW * win
2108            is the window in which the data is scrolled.  Because left, right,
2109            top,  bottom  are  passed  as  parameters, this window can contain
2110            additional data.
2111
2112       long first_data
2113            is the zero-based index to the first row of data  in  the  current
2114            window.
2115
2116       long this_data
2117            is the zero-based index to the current row of data.
2118
2119       long next_data
2120            is the zero-based index to the next data after the current row.
2121
2122       long total_data
2123            is the total number of rows of data.
2124
2125       int left
2126            is  the  zero-based left margin/column of the window.  The up/down
2127            arrows are draw inset by 5 columns from this point.
2128
2129       int right
2130            is the zero-based right margin/column of the window.  The  scroll‐
2131            bar is drawn flush against this column.
2132
2133       int top
2134            is the zero-based row within the window on which to draw up-arrows
2135            as well as a horizontal line to show the window's top.
2136
2137       int bottom
2138            is the zero-based row within the window on  which  to  draw  down-
2139            arrows as well as a horizontal line to show the window's bottom.
2140
2141       chtype attr
2142            is the window's background attribute.
2143
2144       chtype borderattr
2145            is the window's border attribute.
2146
2147   dlg_draw_shadow
2148       Draw  shadows  along the right and bottom edge of a window to give it a
2149       3-dimensional look.  (The height, etc., may not be the same as the win‐
2150       dow's actual values).
2151
2152       WINDOW * win
2153            is the window to update.
2154
2155       int height
2156            is the height of the window.
2157
2158       int width
2159            is the width of the window.
2160
2161       int y
2162            is the top row of the window.
2163
2164       int x
2165            is the left column of the window.
2166
2167   dlg_draw_title
2168       Draw a title centered at the top of the window.
2169
2170       WINDOW * win
2171            is the window to update.
2172
2173       const char * title
2174            is the title string to display at the top of the widget.
2175
2176   dlg_dummy_menutext
2177       This is a utility function which supports the --inputmenu option of the
2178       dialog program.  If dialog_vars.input_menu is set,  dialog_menu  passes
2179       this  pointer to dlg_menu as the rename_menutext parameter.  Otherwise,
2180       it passes dlg_dummy_menutext.
2181
2182       The function should only return DLG_EXIT_ERROR.
2183
2184       DIALOG_LISTITEM * items
2185            is the list of menu items
2186
2187       int current
2188            is the index of the currently-selected item
2189
2190       char * newtext
2191            is the updated text for the menu item
2192
2193   dlg_dump_keys
2194       Write all user-defined key-bindings to the given stream, e.g., as  part
2195       of dlg_create_rc.
2196
2197       FILE * fp
2198            is the stream on which to write the bindings.
2199
2200   dlg_dump_window_keys
2201       Write  all user-defined key-bindings to the given stream, e.g., as part
2202       of dlg_create_rc.
2203
2204       FILE * fp
2205            is the stream on which to write the bindings.
2206
2207       WINDOW * win
2208            is the window for which bindings should be dumped.  If it is null,
2209            then only built-in bindings are dumped.
2210
2211   dlg_eat_argv
2212       Remove one or more items from an argument vector.
2213
2214       int * argcp
2215            in/out  parameter  giving the length of the argument vector.  char
2216            *** argvp in/out parameter pointing to the argument  vector.   int
2217            start starting index.  int count number of arguments to remove.
2218
2219   dlg_edit_offset
2220       Given  the  character-offset  in the string, returns the display-offset
2221       where dialog should position the cursor.  In this context, “characters”
2222       may  be  multicolumn,  since  the  string  can be a multibyte character
2223       string.
2224
2225       char * string
2226            is the string to analyze
2227
2228       int offset
2229            is the character-offset
2230
2231       int x_last
2232            is a limit on the column positions that can  be  used,  e.g.,  the
2233            window's size.
2234
2235   dlg_edit_string
2236       Updates  the string and character-offset, given various editing charac‐
2237       ters or literal characters which are inserted at the  character-offset.
2238       Returns  true  if an editing change was made (and the display should be
2239       updated), and false if the key was something like KEY_ENTER, which is a
2240       non-editing action outside this function.
2241
2242       char * string
2243            is the (multibyte) string to update
2244
2245       int * offset
2246            is the character-offset
2247
2248       int key
2249            is the editing key
2250
2251       int fkey
2252            is true if the editing key is a function-key
2253
2254       bool force
2255            is used in a special loop case by calling code to force the return
2256            value of this function when a function-key code 0 is passed in.
2257
2258   dlg_exit
2259       Given an internal exit code, check  if  the  corresponding  environment
2260       variable  is  set.  If so, remap the exit code to match the environment
2261       variable.  Finally call exit with the resulting exit code.
2262
2263       int code
2264            is the  internal  exit  code,  e.g.,  DLG_EXIT_OK,  which  may  be
2265            remapped.
2266
2267       The  dialog  program uses this function to allow shell scripts to remap
2268       the exit codes so they can distinguish ESC from ERROR.
2269
2270   dlg_exitcode2s
2271       Returns the name of an exit-code, e.g., “OK” for DLG_EXIT_OK.
2272
2273       int code
2274            is an exit-code for dialog as defined in <dialog.h>.
2275
2276   dlg_exitname2n
2277       Returns  an  exit-code  as  the  reverse  of  dlg_exitcode2n,  e.g.,  0
2278       (DLG_EXIT_OK) for the “OK” string.
2279
2280       const char * name
2281            is  the  name  of an exit-code for dialog as defined in <dialog.h>
2282            but omitting the “DLG_EXIT_” prefix.
2283
2284   dlg_exit_buttoncode
2285       Map the given button index for dlg_exit_label into dialog's exit-code.
2286
2287       int button
2288            is the button index
2289
2290   dlg_exit_label
2291       Return a list of button labels.  If dialog_vars.extra_button  is  true,
2292       return  the result of dlg_ok_labels.  Otherwise, return a list with the
2293       “Exit” label and (if dialog_vars.help_button is set) the “Help”  button
2294       as well.
2295
2296   dlg_exiterr
2297       Quit program killing all tailboxbg widgets.
2298
2299       const char * fmt
2300            is the format of the printf-like message to write.
2301
2302       ...
2303            are the variables to apply to the fmt format.
2304
2305   dlg_find_index
2306       Given  the character-offset to find in the list, return the correspond‐
2307       ing array index.
2308
2309       const int *list
2310            contains a list of character-offsets, i.e., indices into a  string
2311            that denote the beginning of multibyte characters.
2312
2313       int limit
2314            is the last index into list to search.
2315
2316       int to_find
2317            is the character-offset to find.
2318
2319   dlg_finish_string
2320       If DIALOG_STATE.finish_string is true, this function discards data used
2321       to speed up layout computations.
2322
2323       const char * string
2324            is the address of the string whose data should be discarded.   The
2325            address  rather  than  contents  is  used as the unique identifier
2326            because some of the caching is used for editable input-fields.
2327
2328   dlg_flush_getc
2329       Cancel the local data saved by dlg_last_getc.
2330
2331   dlg_editbox
2332       This entrypoint provides the --editbox functionality without the  limi‐
2333       tations of dialog's command-line syntax (compare to dialog_editbox).
2334
2335       const char * title
2336            is the title string to display at the top of the widget.
2337
2338       char *** list
2339            is  a  pointer to an array of char * pointers.  The array is allo‐
2340            cated by the caller, and so are the strings to  which  it  points.
2341            The dlg_editbox function may reallocate the array and the strings.
2342
2343       int * rows
2344            points  to  the  nominal  length of list.  The referenced value is
2345            updated iflist is reallocated.
2346
2347       int height
2348            is the desired height of the box.  If zero, the height is adjusted
2349            to use the available screen size.
2350
2351       int width
2352            is  the desired width of the box.  If zero, the height is adjusted
2353            to use the available screen size.
2354
2355   dlg_form
2356       This entrypoint provides the --form functionality without  the  limita‐
2357       tions of dialog's command-line syntax (compare to dialog_form).
2358
2359       const char * title
2360            is the title string to display at the top of the widget.
2361
2362       const char * cprompt
2363            is the prompt text shown within the widget.
2364
2365       int height
2366            is the desired height of the box.  If zero, the height is adjusted
2367            to use the available screen size.
2368
2369       int width
2370            is the desired width of the box.  If zero, the height is  adjusted
2371            to use the available screen size.
2372
2373       int form_height
2374            is  the  minimum  height  to  reserve for displaying the list.  If
2375            zero, it is computed based on the given height and width.
2376
2377       int item_no
2378            is the number of items.
2379
2380       DIALOG_FORMITEM * items
2381            This is a list of the items to display in the form.
2382
2383       int * current_item
2384            The widget sets the referenced location to the index of  the  cur‐
2385            rent display item (cursor) when it returns.
2386
2387   dlg_free_columns
2388       Free data allocated by dlg_align_columns.
2389
2390       char **target
2391            This  is  the array which was reformatted.  It points to the first
2392            string to free.
2393
2394       int per_row
2395            This is the size of the struct for each row of the array.
2396
2397       int num_rows
2398            This is the number of rows in the array.
2399
2400   dlg_free_formitems
2401       Free memory owned by a list of DIALOG_FORMITEM's.
2402
2403       DIALOG_FORMITEM * items
2404            is the list to free.
2405
2406   dlg_free_gauge
2407       Remove the gauge widget from the screen and free its associated memory.
2408
2409       void *objptr
2410            points to the gauge widget.
2411
2412   dlg_getc
2413       Read a character from the given window.   Handle  repainting  here  (to
2414       simplify  things  in  the  calling  application).  Also, if input-call‐
2415       back(s) are set  up,  poll  the  corresponding  files  and  handle  the
2416       updates, e.g., for displaying a tailbox.  Returns the key-code.
2417
2418       WINDOW * win
2419            is the window within which to read.
2420
2421       int * fkey
2422            as  a  side-effect,  set  this to true if the key-code is really a
2423            function-key.
2424
2425   dlg_get_attrs
2426       extract the video attributes from the given window.
2427
2428       WINDOW * win
2429            is the window from which to get attributes.
2430
2431   dlg_getc_callbacks
2432       passes the given key-code ch to the current window that has established
2433       a  callback.   If the callback returns zero, remove it and try the next
2434       window.  If no more callbacks remain, return.  If  any  callbacks  were
2435       found, return true, otherwise false.
2436
2437       int ch
2438            is the key-code
2439
2440       int fkey
2441            is true if the key is a function-key
2442
2443       int * result
2444            is used to pass an exit-code to the caller, which should pass that
2445            via dlg_exit.
2446
2447   dlg_index_columns
2448       Build a list of the display-columns for the  given  multibyte  string's
2449       characters.
2450
2451       const char * string
2452            is the string to analyze
2453
2454   dlg_index_wchars
2455       Build  an index of the wide-characters in the string, so the caller can
2456       easily tell which byte-offset begins a given wide-character.
2457
2458       const char * string
2459            is the string to analyze
2460
2461   dlg_item_help
2462       Draw the string for the dialog_vars.item_help feature.
2463
2464       const char * txt
2465            is the help-message
2466
2467   dlg_killall_bg
2468       If dialog has callbacks active, purge the list  of  all  that  are  not
2469       marked  to keep in the background.  If any remain, run those in a back‐
2470       ground process.
2471
2472       int * retval
2473            stores the exit-code to pass back to the caller.
2474
2475   dlg_last_getc
2476       returns the most recent character that was read via dlg_getc.
2477
2478   dlg_limit_columns
2479       Given a column limit, count the number of wide characters that can  fit
2480       into  that  limit.  The offset is used to skip over a leading character
2481       that was already written.
2482
2483       const char * string
2484            is the string to analyze
2485
2486       int limit
2487            is the column limit
2488
2489       int offset
2490            is the starting offset from which analysis should continue
2491
2492   dlg_lookup_key
2493       Check for a key-binding.  If there is no binding  associated  with  the
2494       widget,  it simply returns the given curses-key.  Otherwise, it returns
2495       the result of the binding
2496
2497       WINDOW * win
2498            is the window on which the binding is checked
2499
2500       int curses_key
2501            is the curses key-code
2502
2503       int * dialog_key
2504            is the corresponding dialog internal code  (see  DLG_KEYS_ENUM  in
2505            dlg_key.h).
2506
2507   dlg_max_input
2508       Limit the parameter according to dialog_vars.max_input
2509
2510       int max_len
2511            is the value to limit
2512
2513   dlg_match_char
2514       Match  a  given character against the beginning of the string, ignoring
2515       case of the given character.  The matching string must  begin  with  an
2516       uppercase character.
2517
2518       int ch
2519            is the character to check
2520
2521       const char * string
2522            is the string to search
2523
2524   dlg_menu
2525       This  entrypoint  provides the --menu functionality without the limita‐
2526       tions of dialog's command-line syntax (compare to dialog_menu).
2527
2528       const char * title
2529            is the title string to display at the top of the widget.
2530
2531       const char * cprompt
2532            is the prompt text shown within the widget.
2533
2534       int height
2535            is the desired height of the box.  If zero, the height is adjusted
2536            to use the available screen size.
2537
2538       int width
2539            is  the desired width of the box.  If zero, the height is adjusted
2540            to use the available screen size.
2541
2542       int menu_height
2543            is the minimum height to reserve  for  displaying  the  list.   If
2544            zero, it is computed based on the given height and width.
2545
2546       int item_no
2547            is the number of items.
2548
2549       DIALOG_LISTITEM * items
2550            This is a list of the items to display in the form.
2551
2552       int * current_item
2553            The  widget  sets the referenced location to the index of the cur‐
2554            rent display item (cursor) when it returns.
2555
2556       DIALOG_INPUTMENU rename_menutext
2557            If this is not dlg_dummy_menutext, the widget acts like an  input‐
2558            menu  widget,  providing an extra “Rename” button, which activates
2559            an edit feature on the selected menu item.
2560
2561   dlg_move_window
2562       Moves/resizes the given window to the given position and size.
2563
2564       WINDOW *win
2565            is the window to move/resize.
2566
2567       WINDOW *height
2568            is the height of the resized window.
2569
2570       WINDOW *width
2571            is the width of the resized window.
2572
2573       WINDOW *y
2574            y-ordinate to use for the repositioned window.
2575
2576       WINDOW *x
2577            x-ordinate to use for the repositioned window.
2578
2579   dlg_mouse_bigregion
2580       Retrieve the big-region under the pointer.
2581
2582       int y
2583            is the row on which the mouse click occurred
2584
2585       int x
2586            is the column on which the mouse click occurred
2587
2588   dlg_mouse_free_regions
2589       Free the memory associated with mouse regions.
2590
2591   dlg_mouse_mkbigregion
2592       Creates a region on which the  mouse-clicks  will  return  a  specified
2593       code.
2594
2595       int y
2596            is the top-row of the region.
2597
2598       int x
2599            is the left-column of the region.
2600
2601       int height
2602            is the height of the region.
2603
2604       int width
2605            is the width of the region.
2606
2607       int code
2608            is a code used to make the region unique within a widget
2609
2610       int step_x
2611            is  used in modes 2 (columns) and 3 (cells) to determine the width
2612            of a column/cell.
2613
2614       int step_y
2615            is currently unused
2616
2617       int mode
2618            is used to determine how the mouse position is translated  into  a
2619            code (like a function-key):
2620
2621            1  index by lines
2622
2623            2  index by columns
2624
2625            3  index by cells
2626
2627   dlg_mouse_mkregion
2628       int y
2629            is the top-row of the region.
2630
2631       int x
2632            is the left-column of the region.
2633
2634       int height
2635            is the height of the region.
2636
2637       int width
2638            is the width of the region.
2639
2640       int code
2641            is a code used to make the region unique within a widget
2642
2643   dlg_mouse_region
2644       Retrieve the frame under the mouse pointer
2645
2646       int y
2647            is the row of the mouse-click
2648
2649       int x
2650            is the column of the mouse-click
2651
2652   dlg_mouse_setbase
2653       Sets  a  base  for  subsequent calls to dlg_mouse_mkregion, so they can
2654       make regions relative to the start of a given window.
2655
2656       int x
2657            is the left-column for the base
2658
2659       int y
2660            is the top-row for the base
2661
2662   dlg_mouse_setcode
2663       Sets a value used internally by dlg_mouse_mkregion which  is  added  to
2664       the  code parameter.  By providing different values, e.g., multiples of
2665       KEY_MAX, it is possible to support multiple “big” regions in a  widget.
2666       The buildlist widget uses this feature to recognize mouse-clicks in the
2667       left/right panes.
2668
2669       int code
2670            is the value to add to dlg_mouse_mkregion's code parameter.
2671
2672   dlg_mouse_wgetch
2673       is a wrapper for dlg_getc which additionally maps mouse-clicks (if  the
2674       curses library supports those) into extended function-keys which encode
2675       the position according to the mode in  dlg_mouse_mkbigregion.   Returns
2676       the corresponding key-code.
2677
2678       WINDOW * win
2679            is the window on which to perform the input
2680
2681       int * fkey
2682            the  referenced  location  is  set  to  true if the key-code is an
2683            actual or extended (mouse) function-key.
2684
2685   dlg_mouse_wgetch_nowait
2686       This is a non-blocking variant of dlg_mouse_wgetch.
2687
2688       WINDOW * win
2689            is the window on which to perform the input
2690
2691       int * fkey
2692            the referenced location is set to  true  if  the  key-code  is  an
2693            actual or extended (mouse) function-key.
2694
2695   dlg_need_separator
2696       Check  if an output-separator is needed.  If dialog_vars.output_separa‐
2697       tor is set, return true.   Otherwise,  if  dialog_vars.input_result  is
2698       nonempty, return true.  If neither, return false.
2699
2700   dlg_new_modal_window
2701       Create a modal window, optionally with a shadow.  The shadow is created
2702       if dialog_state.use_shadow is true.
2703
2704       WINDOW * parent
2705            is the parent window (usually the top-level window of a widget)
2706
2707       int height
2708            is the window's height
2709
2710       int width
2711            is the window's width
2712
2713       int y
2714            is the window's top-row
2715
2716       int x
2717            is the window's left-column
2718
2719   dlg_new_window
2720       Create a window, optionally with a shadow.  The shadow  is  created  if
2721       dialog_state.use_shadow is true.
2722
2723       int height
2724            is the window's height
2725
2726       int width
2727            is the window's width
2728
2729       int y
2730            is the window's top-row
2731
2732       int x
2733            is the window's left-column
2734
2735   dlg_next_button
2736       Return the next index in the list of labels.
2737
2738       const char ** labels
2739            is  a  list  of  (pointers  to) button labels terminated by a null
2740            pointer.
2741
2742       int button
2743            is the current button-index.
2744
2745   dlg_next_ok_buttonindex
2746       Assuming that the caller is using dlg_ok_labels to list  buttons,  find
2747       the next index in the list of buttons.
2748
2749       int current
2750            is the current index in the list of buttons
2751
2752       int extra
2753            if negative, provides a way to enumerate extra active areas on the
2754            widget.
2755
2756   dlg_ok_buttoncode
2757       Map the given button index for dlg_ok_labels into dialog's exit-code.
2758
2759       int button
2760            is the button-index (which is not  necessarily  the  same  as  the
2761            index in the list of labels).
2762
2763   dlg_ok_button_key
2764       Calls  dlg_button_key  with the “Cancel” button disabled, e.g., for the
2765       textbox widget.
2766
2767   dlg_ok_label
2768       Returns a list with the “Ok” label, and if  dialog_vars.help_button  is
2769       true, the “Help” label as well.
2770
2771   dlg_ok_labels
2772       Return a list of button labels for the OK/Cancel group of widgets.
2773
2774   dlg_ordinate
2775       Decode the string as an integer, decrement if greater than zero to make
2776       a curses-ordinate from a dialog-ordinate.
2777
2778   dlg_parse_bindkey
2779       Parse the parameters of the “bindkeys” configuration-file entry.   This
2780       expects widget name which may be "*", followed by curses key definition
2781       and then dialog key definition.
2782
2783       char * params
2784            is the parameter string to parse.
2785
2786   dlg_parse_rc
2787       Parse the configuration file and set up variables.
2788
2789   dlg_popen
2790       Open a pipe which ties the standard error  and  output  together.   The
2791       popen function captures only the standard output of a command.
2792
2793       const char *command
2794            The shell command to run.
2795
2796       const char *type
2797            Like popen, "r" is used to read, and "w" is used to write.
2798
2799   dlg_prev_button
2800       Return the previous index in the list of labels.
2801
2802       const char ** labels
2803            is  a  list  of  (pointers  to) button labels terminated by a null
2804            pointer.
2805
2806       int button
2807            is the current button index
2808
2809   dlg_print_listitem
2810       This is a helper function used for the various  “list”  widgets,  e.g.,
2811       checklist,  menu,  buildlist, treeview.  Each list-widget has “tag” and
2812       “description” values for each item which can  be  displayed.   If  dia‐
2813       log_vars.no_tags  is  true,  the  “tag”  value is not shown.  The first
2814       character of the first value shown (tag or description) is  highlighted
2815       to indicate that the widget will match it for quick navigation.
2816
2817       WINDOW *win
2818            the window in which to display the text
2819
2820       const char *text
2821            the value to display
2822
2823       int climit
2824            the number of columns available for printing the text
2825
2826       bool first
2827            true  if this is the first call (for “tag” and “description”), and
2828            the first character of the value should be highlighted.
2829
2830       int selected
2831            nonzero if the text should be displayed using the “selected”  col‐
2832            ors
2833
2834   dlg_print_scrolled
2835       This  is  a  wrapper  for  dlg_print_autowrap  which allows the user to
2836       scroll too-long prompt text up/down.
2837
2838       See dlg_check_scrolled for a function which updates the offset variable
2839       used as a parameter here.  It complements this function; you need both.
2840       If pauseopt is set, this function returns an  updated  last  parameter,
2841       needed for dlg_check_scrolled calls.
2842
2843       WINDOW * win
2844            is the window to update.
2845
2846       const char * prompt
2847            is the string to print
2848
2849       int offset
2850            is the starting line-number to write wrapped text.
2851
2852       int height
2853            is the available height for writing the wrapped text
2854
2855       int width
2856            is the width that the wrapping should occur in
2857
2858       int pauseopt
2859            is  true  if  the  extra  functionality  for  scrolling  should be
2860            enabled.  If false, this calls  dlg_print_autowrap  without  doing
2861            any scrolling.
2862
2863   dlg_print_line
2864       Print  one  line  of  the prompt in the window within the limits of the
2865       specified right margin.  The line will end on a  word  boundary  and  a
2866       pointer to the start of the next line is returned, or a NULL pointer if
2867       the end of *prompt is reached.
2868
2869       WINDOW *win
2870            is the window to update.
2871
2872       chtype *attr
2873            holds the starting attributes, and is updated to reflect the final
2874            attributes applied to the string.
2875
2876       const char *prompt
2877            is the string to print
2878
2879       int lm
2880            is the left margin.
2881
2882       int rm
2883            is the right margin
2884
2885       int *x
2886            returns the ending x-ordinate.
2887
2888   dlg_prev_ok_buttonindex
2889       Find the previous button index in the list from dlg_ok_labels.
2890
2891       int current
2892            is the current index
2893
2894       int extra
2895            if  negative provides a way to enumerate extra active areas on the
2896            widget.
2897
2898   dlg_print_autowrap
2899       Print a string of text in a window, automatically wrap  around  to  the
2900       next  line if the string is too long to fit on one line.  Note that the
2901       string may contain embedded newlines.  The text is written starting  at
2902       the top of the window.
2903
2904       WINDOW * win
2905            is the window to update.
2906
2907       const char * prompt
2908            is the string to print
2909
2910       int height
2911            is the nominal height the wrapped string is limited to
2912
2913       int width
2914            is the width that the wrapping should occur in
2915
2916   dlg_print_size
2917       If  dialog_vars.print_siz is true, print the given height/width (from a
2918       widget) to dialog_state.output, e.g., Size: height, width.
2919
2920       int height
2921            is the window's height
2922
2923       int width
2924            is the window's width
2925
2926   dlg_print_text
2927       Print up to cols  columns  from  text,  optionally  rendering  dialog's
2928       escape sequences for attributes and color.
2929
2930       WINDOW * win
2931            is the window to update.
2932
2933       const char * txt
2934            is the string to print
2935
2936       int col
2937            is the column limit
2938
2939       chtype * attr
2940            holds the starting attributes, and is updated to reflect the final
2941            attributes applied to the string.
2942
2943   dlg_progressbox
2944       implements the "--prgbox" and "--progressbox" options.
2945
2946       const char * title
2947            is the title on the top of the widget.
2948
2949       const char * cprompt
2950            is the prompt text shown within the widget.  If empty or null,  no
2951            prompt is shown.
2952
2953       int height
2954            is the desired height of the box.  If zero, the height is based on
2955            the screen size.
2956
2957       int width
2958            is the desired width of the box.  If zero, the height is based  on
2959            the screen size.
2960
2961       int pauseopt
2962            if  true,  an  “OK” button will be shown, and the dialog will wait
2963            for it to complete.  With an “OK” button, it is  denoted  a  “pro‐
2964            grambox”, without an “OK” button, it is denoted a “progressbox”.
2965
2966       FILE * fp
2967            is the file pointer, which may be a pipe or a regular file.
2968
2969   dlg_put_backtitle
2970       Display the background title if dialog_vars.backtitle is non-null.  The
2971       background title is shown at the top of the screen.
2972
2973   dlg_reallocate_gauge
2974       Allocates or reallocates a gauge widget (see dlg_allocate_gauge).   Use
2975       dlg_update_gauge to display the result.
2976
2977       void ** objptr
2978            If  the pointer referenced by this parameter is null, the function
2979            creates a new gauge widget using  dlg_allocate_gauge.   Otherwise,
2980            it  updates  the title and cprompt values, reusing the window from
2981            the previous call on this function.  As a side-effect,  the  func‐
2982            tion stores the updated object-pointer via the objptr parameter.
2983
2984       const char * title
2985            is the title string to display at the top of the widget.
2986
2987       const char * cprompt
2988            is the prompt text shown within the widget.
2989
2990       int height
2991            is the desired height of the box.  If zero, the height is adjusted
2992            to use the available screen size.
2993
2994       int width
2995            is the desired width of the box.  If zero, the height is  adjusted
2996            to use the available screen size.
2997
2998       int percent
2999            is the percentage to show in the progress bar.
3000
3001   dlg_register_buttons
3002       The  widget developer should call this function after dlg_register_win‐
3003       dow, for the list of button labels associated with the widget.  One may
3004       bind a key to a button, e.g., “OK” for DLGK_OK,
3005
3006       WINDOW * win
3007            is the window with which to associate the buttons
3008
3009       const char * name
3010            is the widget's binding name (usually the name of the widget).
3011
3012       const char ** buttons
3013            is the list of buttons
3014
3015   dlg_register_window
3016       For a given named widget's window, associate a binding table.
3017
3018       WINDOW * win
3019            is the window with which to associate the buttons
3020
3021       const char * name
3022            is the widget's binding name (usually the name of the widget).
3023
3024       DLG_KEYS_BINDING * binding
3025            is the binding table
3026
3027   dlg_remove_callback
3028       Remove a callback.
3029
3030       DIALOG_CALLBACK * p
3031            contains the callback information.
3032
3033   dlg_renamed_menutext
3034       This is a utility function which supports the --inputmenu option of the
3035       dialog program.  If dialog_vars.input_menu is set,  dialog_menu  passes
3036       this  pointer to dlg_menu as the rename_menutext parameter.  Otherwise,
3037       it passes dlg_dummy_menutext.
3038
3039       The function should add “RENAMED” to  dialog_vars.input_result  ,  fol‐
3040       lowed by the menu item's name and the newtext value (with a space sepa‐
3041       rating the three items), and return DLG_EXIT_EXTRA.
3042
3043       DIALOG_LISTITEM * items
3044            is the list of menu items
3045
3046       int current
3047            is the index of the currently-selected item
3048
3049       char * newtext
3050            is the updated text for the menu item
3051
3052   dlg_restore_vars
3053       Restore  dialog's  variables  from  the  given   variable   (see   dia‐
3054       log_save_vars).
3055
3056       DIALOG_VARS * save
3057            is the variable from which to restore.
3058
3059       The  DIALOG_VARS.input_length  and DIALOG_VARS.input_result members are
3060       treated specially, since these are used by a widget to pass data to the
3061       caller.  They are not modified by this function.
3062
3063   dlg_result_key
3064       Test  a  dialog internal keycode to see if it corresponds to one of the
3065       push buttons on the widget such as “OK”.  This is only useful if  there
3066       are  user-defined  key  bindings,  since there are no built-in bindings
3067       that map directly to DLGK_OK, etc.  Return true if a mapping was done.
3068
3069       int dialog_key
3070            is the dialog key to test
3071
3072       int fkey
3073            is true if this is a function key
3074
3075       int * resultp
3076            store the result of the mapping in the referenced location.
3077
3078   dlg_save_vars
3079       Save dialog's variables into the given variable (see dlg_restore_vars).
3080
3081       DIALOG_VARS * save
3082            is the variable into which to save.
3083
3084   dlg_set_focus
3085       Set focus on the given window, making it display above other windows on
3086       the screen.
3087
3088       WINDOW * parent
3089            is the parent window (usually the top-level window of a widget)
3090
3091       WINDOW * win
3092            is  the  window  on which to place focus (usually a subwindow of a
3093            widget)
3094
3095   dlg_set_result
3096       Setup a fixed-buffer for the result in dialog_vars.input_result
3097
3098       const char * string
3099            is the new contents for the result
3100
3101   dlg_show_string
3102       Displays the string, shifted as necessary, to fit within  the  box  and
3103       show the current character-offset.
3104
3105       WINDOW * win
3106            is the window within which to display
3107
3108       const char * string
3109            is the string to display
3110
3111       int offset
3112            is the starting (character, not bytes) offset
3113
3114       chtype attr
3115            is the window attribute to use for the string
3116
3117       int y_base
3118            beginning row on screen
3119
3120       int x_base
3121            beginning column on screen
3122
3123       int x_last
3124            number of columns on screen
3125
3126       bool hidden
3127            if true, do not echo input
3128
3129       bool force
3130            if true, force repaint
3131
3132   dlg_strclone
3133       duplicate the string, like strdup.
3134
3135       const char * cprompt
3136            is the string to duplicate
3137
3138   dlg_strcmp
3139       compare two strings, ignoring case.
3140
3141       const char * a
3142            is one string
3143
3144       const char * b
3145            is the other string
3146
3147   dlg_string_to_argv
3148       Convert  a  string to an argument vector returning an index (which must
3149       be freed by the caller).  The string is modified:
3150
3151       ·   Blanks between arguments are replaced by nulls.
3152
3153       ·   Normally arguments are separated by blanks; however you can double-
3154           quote an argument to enclose blanks.  The surrounding double-quotes
3155           are removed from the string.
3156
3157       ·   A  backslash  preceding  a  double-quote  within  double-quotes  is
3158           removed.
3159
3160       ·   A backslash preceding a newline outside double-quotes is removed.
3161
3162       ·   Except for special cases, backslashes are preserved in the strings,
3163           since other dialog functions interpret backslashes, e.g., for  col‐
3164           ors.
3165
3166       char *blob
3167            is the string to convert.
3168
3169   dlg_sub_window
3170       create a subwindow, e.g., for an input area of a widget
3171
3172       WINDOW * win
3173            is the parent window
3174
3175       int height
3176            is the subwindow's height
3177
3178       int width
3179            is the subwindow's width
3180
3181       int y
3182            is the subwindow's top-row
3183
3184       int x
3185            is the subwindow's left-column
3186
3187   dlg_tab_correct_str
3188       If  the dialog_vars.tab_correct is true, convert tabs to single spaces.
3189       Return the converted result.  The caller is responsible for freeing the
3190       string.
3191
3192       char * prompt
3193            is the string to convert
3194
3195   dlg_trace
3196       If  the  parameter  is  non-null, opens a trace file with that name and
3197       stores the file pointer in dialog_state.trace.
3198
3199   dlg_trace_2n
3200       logs a numeric value as a comment.
3201
3202       char * name
3203            is the name to log in the comment.
3204
3205       int value
3206            is the value to log in the comment.
3207
3208   dlg_trace_2s
3209       logs a string value as a comment.  If the value contains embedded  new‐
3210       lines, the comment is continued with “#+” markers.
3211
3212       char * name
3213            is the name to log in the comment.
3214
3215       int value
3216            is the value to log in the comment.
3217
3218   dlg_trace_chr
3219       If dialog_state.trace is set, translate the parameters into a printable
3220       representation, log it on a “chr” line.
3221
3222       int ch
3223            is the nominal keycode value.
3224
3225       int fkey
3226            is nonzero if the value is really a function key.  Some  of  these
3227            may be values declared in the DLG_KEYS_ENUM.
3228
3229   dlg_trace_msg
3230       Write a formatted message to the trace file.
3231
3232       const char * fmt
3233            is the format of the printf-like message to write.
3234
3235       ...
3236            are the variables to apply to the fmt format.
3237
3238       Use  the  DLG_TRACE macro for portability, in case the trace feature is
3239       not compiled into the library.  It uses an extra level  of  parentheses
3240       to work with a variable number of parameters, e.g.,
3241
3242              DLG_TRACE(("this is dialog version %s\n", dialog_version()));
3243
3244   dlg_ttysize
3245       Returns  the screensize without using curses.  That allows the function
3246       to be used before initializing the screen.
3247
3248   dlg_trace_win
3249       If dialog_state.trace is set, log a printable picture of the given win‐
3250       dow.
3251
3252   dlg_treeview
3253       This  is an alternate interface to 'treeview' which allows the applica‐
3254       tion to read the list item states back directly without putting them in
3255       the output buffer.
3256
3257       const char * title
3258            is the title on the top of the widget.
3259
3260       const char * cprompt
3261            is the prompt text shown within the widget.
3262
3263       int height
3264            is the desired height of the box.  If zero, the height is based on
3265            the screen size.
3266
3267       int width
3268            is the desired width of the box.  If zero, the height is based  on
3269            the screen size.
3270
3271       int list_height
3272            is  the  minimum  height  to  reserve for displaying the list.  If
3273            zero, it is computed based on the given height and width.
3274
3275       int item_no
3276            is the number of rows in items.
3277
3278       DIALOG_LISTITEM * items
3279            is the list of items,  contain  tag,  name,  and  optionally  help
3280            strings  (if dialog_vars.item_help is set).  The initial selection
3281            state for each item is also in this list.
3282
3283       const char * states
3284            This is a list of characters to  display  for  the  given  states.
3285            Normally a buildlist provides true (1) and false (0) values, which
3286            the widget displays as "*" and space, respectively.   An  applica‐
3287            tion  may  set  this  parameter  to  an  arbitrary null-terminated
3288            string.  The widget determines  the  number  of  states  from  the
3289            length  of  this  string, and will cycle through the corresponding
3290            display characters as the user presses the space-bar.
3291
3292       int * depths
3293            This is a list of depths of each item in the tree.  It is a  sepa‐
3294            rate  parameter  from  items  to allow reuse of the existing func‐
3295            tions.
3296
3297       int flag
3298            is either FLAG_CHECK, for  checklists  (multiple  selections),  or
3299            FLAG_RADIO for radiolists (a single selection).
3300
3301       int * current_item
3302            The  widget  sets the referenced location to the index of the cur‐
3303            rent display item (cursor) when it returns.
3304
3305   dlg_trim_string
3306       The dialog program uses this in  each  widget  to  adjust  the  message
3307       string,  which  may contain the newline character (referred to as '\n')
3308       and/or the special substring "\n" (which can be translated into a  new‐
3309       line character).
3310
3311       There are several optional features:
3312
3313       ·   Unless  dialog_vars.nocollapse  is  set, each tab is converted to a
3314           space before other processing.
3315
3316       ·   If dialog_vars.no_nl_expand is not set, and  the  string  has  "\n"
3317           substrings:
3318
3319           ·   The  function  changes embedded "\n" substrings to '\n' charac‐
3320               ters.
3321
3322               The function preserves extra spaces after these  substitutions.
3323               For  instance, spaces following a newline (substring or charac‐
3324               ter) are preserved to use as an indentation.
3325
3326           ·   If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3327               line  characters.   Otherwise,  each  '\n' newline character is
3328               converted to a space.
3329
3330       ·   Otherwise, if dialog_vars.trim_whitespace is set:
3331
3332           ·   This function strips all extra spaces  to  simplify  justifica‐
3333               tion.
3334
3335           ·   If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3336               line characters.  Otherwise, each  '\n'  newline  character  is
3337               converted to a space.
3338
3339       ·   Finally (if dialog_vars.no_nl_expand is set, or the string does not
3340           contain "\n" substrings,  and  dialog_vars.trim_whitespace  is  not
3341           set):
3342
3343           ·   Unless  dialog_vars.nocollapse  is set, sequences of spaces are
3344               reduced to a single space.
3345
3346       char * src
3347            is the string to trim
3348
3349   dlg_unregister_window
3350       Remove the bindings for a given window.
3351
3352       WINDOW * win
3353            is the window from which to remove bindings
3354
3355   dlg_update_gauge
3356       Update a gauge widget to show a different percentage value.
3357
3358       void *objptr
3359            points to the gauge object to update.
3360
3361       int percent
3362            is the new percentage value to display.
3363
3364   dlg_will_resize
3365       This filters out bursts of KEY_RESIZE values.  Call this after dlg_getc
3366       returns KEY_RESIZE, to improve performance.
3367
3368   dlg_yes_buttoncode
3369       Map the given button index for dlg_yes_labels into dialog's exit-code.
3370
3371       int button
3372            is the button index
3373
3374   dlg_yes_labels
3375       Return a list of buttons for Yes/No labels.
3376
3377   end_dialog
3378       End use of dialog functions.
3379
3380   init_dialog
3381       Do some initialization for dialog.
3382
3383       FILE *input
3384            is  the  real  tty  input  of  dialog.  Usually it is the standard
3385            input, but if --input-fd option is used, it may be anything.
3386
3387       FILE *output
3388            is where dialog will send its result.  Usually it is the  standard
3389            error, but if --stdout or --output-fd is used, it may be anything.
3390

SEE ALSO

3392       dialog (1).
3393

AUTHOR

3395       Thomas E. Dickey
3396
3397
3398
3399$Date: 2019/08/07 00:33:05 $                                         DIALOG(3)
Impressum