2 .\" $Id: dialog.3,v 1.128 2020/03/24 00:26:28 tom Exp $
3 .\" Copyright 2005-2019,2020 Thomas E. Dickey
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU Lesser General Public License, version 2.1
7 .\" as published by the Free Software Foundation.
9 .\" This program is distributed in the hope that it will be useful, but
10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 .\" Lesser General Public License for more details.
14 .\" You should have received a copy of the GNU Lesser General Public
15 .\" License along with this program; if not, write to
16 .\" Free Software Foundation, Inc.
17 .\" 51 Franklin St., Fifth Floor
18 .\" Boston, MA 02110, USA.
20 .\" definitions for renaming
41 .\" Bulleted paragraph
50 .TH \*D 3 "" "$Date: 2020/03/24 00:26:28 $"
52 dialog \- widgets and utilities for the \*p program
54 .B cc [ flag ... ] file ... -l\*l [ library ... ]
58 .B cc $(\*p-config --cflags) file ... $(\*p-config --libs) ]
63 is a program that will let you present a variety of questions or
64 display messages using dialog boxes from a shell script.
65 It is built from the \fB\*l\fP library,
66 which consists of several widgets
67 as well as utility functions that are used by the widgets
71 This manpage documents the features from \fI<\*l.h>\fP which
72 are likely to be important to developers using the widgets directly.
73 Some hints are also given for developing new widgets.
75 Here is a \fB\*l\fP version of \fIHello World\/\fP:
81 init_dialog(stdin, stdout);
82 status = dialog_yesno(
83 "Hello, in dialog-format",
92 .\" ************************************************************************
94 Exit codes (passed back to the main program for its use)
95 are defined with a "\fIDLG_EXIT_\fP prefix.
96 The efined constants can be mapped using environment variables
97 as described in \fB\*p\fP(1),
98 e.g., \fIDLG_EXIT_OK\fP corresponds to \fI$DIALOG_OK\fP.
100 Useful character constants which correspond to user input
101 are named with the "\fICHR_\fP" prefix, e.g.,
104 Colors and video attributes are categorized and associated with
105 settings in the configuration file
106 (see the discussion of \fI$DIALOGRC\fP in \fB\*p\/\fP(1)).
107 The \fIDIALOG_ATR(n)\fP macro is used for defining the references
108 to the combined color and attribute table \fBdlg_color_table[]\fP.
110 The \fB\*p\fP application passes its command-line parameters
111 to the widget functions.
112 Some of those parameters are single values,
113 but some of the widgets accept data as an array of values.
114 Those include checklist/radiobox, menubox and formbox.
115 When the \fB--item-help\fP option is given, an extra column
117 The USE_ITEM_HELP(), CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS
118 macros are used to hide this difference from the calling application.
120 Most of the other definitions found in \fI<\*l.h>\fP
121 are used for convenience in building the library or main program.
122 These include definitions based on the generated \fI<dlg_config.h>\fP header.
124 .\" ************************************************************************
126 All of the global data for the \fB\*l\fP library is stored in
128 \fIDIALOG_STATE\fP, \fIDIALOG_VARS\fP and \fIDIALOG_COLORS\fP.
130 \fBdialog_state\fP, \fBdialog_vars\fP and \fBdlg_color_table\fP
131 global variables should be initialized to zeros,
132 and then populated with the data to use.
133 A few of these must be nonzero for the corresponding widgets to function.
134 As as the case with function names,
135 variables beginning with "\fIdialog_\fP"
136 are designed for use by the calling application
137 while variables beginning with "\fIdlg_\fP"
138 are intended for lower levels, e.g., by the \fB\*l\fP library.
139 .\" ---------------------------------------------------------------------------
141 The \fIstate\fP variables are \fB\*l\fP's working variables.
142 It initializes those, uses them to manage the widgets.
143 .\" ---------------------------------------------------------------------------
145 This is a linked list of all subwindows created by the library.
146 The \fBdlg_del_window\fP function uses this
147 to free storage for subwindows when deleting a window.
148 .\" ---------------------------------------------------------------------------
150 This is a linked list of all windows created by the library.
151 The \fBdlg_del_window\fP function uses this to locate windows which
152 may be redrawn after deleting a window.
153 .\" ---------------------------------------------------------------------------
155 This corresponds to the command-line option "\fB--aspect-ratio\fP".
156 The value gives the application
157 some control over the box dimensions when using auto
158 sizing (specifying 0 for height and width).
159 It represents width / height.
160 The default is 9, which means 9 characters wide to every 1 line high.
161 .\" ---------------------------------------------------------------------------
163 When set to true, this allows calls to \fBdlg_finish_string\fP to discard the
164 corresponding data which is created to speed up layout computations for the
165 given string parameter.
166 The \fBgauge\fP widget uses this feature.
167 .\" ---------------------------------------------------------------------------
169 This is set up in \fIui_getc.c\fP to record windows which must be polled
170 for input, e.g., to handle the background tailbox widget.
171 One window is designated as the foreground or control window.
172 .\" ---------------------------------------------------------------------------
174 If the control window for \fIDIALOG_STATE.getc_callbacks\fP is
175 closed, the list is transferred to this variable.
176 Closing all windows causes the application to exit.
177 .\" ---------------------------------------------------------------------------
180 in \fBdlg_will_resize\fP or \fBdlg_result_key\fP
181 when \fBKEY_RESIZE\fP is read,
182 to tell \fB\*p\fP to ignore subsequent \fBERR\fPs.
183 .\" ---------------------------------------------------------------------------
185 This corresponds to the command-line option "\fB--no-mouse\fP".
186 If true, \fB\*p\fP will not initialize (and enable) the mouse in
188 .\" ---------------------------------------------------------------------------
190 This is set in the \fB\*p\fP application to the stream on
191 which the application and library functions may write text results.
192 Normally that is the standard error,
193 since the curses library prefers to write its data to the standard output.
194 Some scripts, trading portability for convenience,
195 prefer to write results to the standard output,
196 e.g., by using the "\fB--stdout\fP" option.
197 .\" ---------------------------------------------------------------------------
199 This is incremented by \fBdlg_does_output\fP,
200 which is called by each widget that writes text to the output.
201 The \fB\*p\fP application uses that to decide if it should
202 also write a separator, i.e.,
203 \fIDIALOG_STATE.separate_str\fP,
204 between calls to each widget.
205 .\" ---------------------------------------------------------------------------
207 This is set in \fIinit_dialog\fP to a stream which can be used by the
208 \fBgauge\fP widget, which must be the application's standard input.
209 The \fB\*p\fP application calls \fIinit_dialog\fP normally with
210 \fIinput\fP set to the standard input, but optionally based on the
211 "\fB--input-fd\fP" option.
212 Since the application cannot read from
213 a pipe (standard input) and at the same time read
214 the curses input from the standard input,
215 it must allow for reopening the latter from either
216 a specific file descriptor,
217 or directly from the terminal.
218 The adjusted pipe stream value is stored in this variable.
219 .\" ---------------------------------------------------------------------------
221 The text-formatting functions use this for the number of rows used for
224 It is used by \fB\*l\fP for the command-line options
225 "\fB--print-text-size\fP" and
226 "\fB--print-text-only\fP".
227 .\" ---------------------------------------------------------------------------
228 .SS .screen_initialized
229 This is set in \fIinit_dialog\fP and
230 reset in \fIend_dialog\fP.
231 It is used to check if curses has been initialized,
232 and if the \fIendwin\fP function must be called on exit.
233 .\" ---------------------------------------------------------------------------
235 This is set in \fIinit_dialog\fP to the output stream used
236 by the curses library.
237 Normally that is the standard output,
238 unless that happens to not be a terminal (and if \fIinit_dialog\fP can
239 successfully open the terminal directly).
240 .\" ---------------------------------------------------------------------------
242 The text-formatting functions use this for the number of columns used for
245 It is used by \fB\*l\fP for the command-line options
246 "\fB--print-text-size\fP" and
247 "\fB--print-text-only\fP".
248 .\" ---------------------------------------------------------------------------
250 This corresponds to the command-line option "\fB--separate-widget\fP".
252 specifies a string that will separate the output on \fB\*p\fP's output from
254 This is used to simplify parsing the result of a dialog with several widgets.
255 If this option is not given,
256 the default separator string is a tab character.
257 .\" ---------------------------------------------------------------------------
259 This corresponds to the command-line option "\fB--tab-len\fP \fInumber\/\fP".
260 Specify the number of spaces that a tab character occupies if the
261 "\fB--tab-correct\fP"
264 .\" ---------------------------------------------------------------------------
266 The text-formatting functions set this to the number of lines used for
269 It is used by \fB\*l\fP for the command-line options
270 "\fB--print-text-size\fP" and
271 "\fB--print-text-only\fP".
272 .\" ---------------------------------------------------------------------------
274 \fB\*L\fP uses this in the command-line option "\fB--print-text-only\fP".
276 The text-formatting functions
277 (\fBdlg_print_text\fP,
278 \fBdlg_print_line\fP, and
279 \fBdlg_print_autowrap\fP)
280 check this to decide whether to print the formatted text to
281 \fB\*p\fP's output or to the curses-display.
284 \fBdlg_auto_size\fP checks the flag, allowing it to be used before
285 \fBinit_dialog\fP is called.
286 .\" ---------------------------------------------------------------------------
288 The text-formatting functions set this to the number of columns used for
291 It is used by \fB\*l\fP for the command-line options
292 "\fB--print-text-size\fP" and
293 "\fB--print-text-only\fP".
294 .\" ---------------------------------------------------------------------------
296 This corresponds to the command-line option "\fB--trace\fP \fIfile\fP".
297 It is the file pointer to which trace messages are written.
298 .\" ---------------------------------------------------------------------------
300 This is set in \fIinit_dialog\fP if the curses implementation supports color.
301 .\" ---------------------------------------------------------------------------
303 This corresponds to the command-line option "\fB--scrollbar\fP".
305 draw a scrollbar to make windows holding scrolled data more readable.
306 .\" ---------------------------------------------------------------------------
308 This corresponds to the command-line option "\fB--no-shadow\fP".
309 This is set in \fIinit_dialog\fP if the curses implementation supports color.
311 suppress shadows that would be drawn to the right and bottom of each dialog box.
312 .\" ---------------------------------------------------------------------------
314 This corresponds to the command-line option "\fB--visit-items\fP".
315 Modify the tab-traversal of the list-oriented widgets
316 (buildlist, checklist, radiobox, menubox, inputmenu, and treeview)
317 to include the list of items as one of the states.
318 This is useful as a visual aid,
319 i.e., the cursor position helps some users.
320 .\" ---------------------------------------------------------------------------
322 The \fB\*p\fP application resets the \fBdialog_vars\fP data before
323 accepting options to invoke each widget.
324 Most of the \fIDIALOG_VARS\fP members are set directly from \fB\*p\fP's
325 command-line options:
326 .\" ---------------------------------------------------------------------------
330 In contrast to \fBDIALOG_STATE\fP, the members of \fBDIALOG_VARS\fP
331 are set by command-line options in \fB\*p\fP.
332 .\" ---------------------------------------------------------------------------
334 This corresponds to the command-line option "\fB--ascii-lines\fP.
335 It causes line-drawing to be done with ASCII characters, e.g., "+" and "-".
336 See \fIDIALOG_VARS.no_lines\fP.
337 .\" ---------------------------------------------------------------------------
339 This corresponds to the command-line option
340 "\fB--backtitle\fP \fIbacktitle\/\fP".
343 string to be displayed on the backdrop, at the top of the screen.
344 .\" ---------------------------------------------------------------------------
345 .SS .beep_after_signal
346 This corresponds to the command-line option "\fB--beep-after\fP".
347 If true, beep after a user has completed a widget
348 by pressing one of the buttons.
349 .\" ---------------------------------------------------------------------------
351 This corresponds to the command-line option "\fB--beep\fP".
353 .\" ---------------------------------------------------------------------------
355 This is true if the command-line option "\fB--begin\fP \fIy x\/\fP" was used.
356 It specifies the position of the upper left corner
357 of a dialog box on the screen.
358 .\" ---------------------------------------------------------------------------
360 This corresponds to the \fIx\fP value from
361 the command-line option "\fB--begin\fP \fIy x\/\fP" (second value).
362 .\" ---------------------------------------------------------------------------
364 This corresponds to the \fIy\fP value from
365 the command-line option "\fB--begin\fP \fIy x\/\fP" (first value).
366 .\" ---------------------------------------------------------------------------
368 This corresponds to the command-line option
369 "\fB--cancel-label\fP \fIstring\/\fP".
370 The given \fIstring\fP overrides the label used for \*(``Cancel\*('' buttons.
371 .\" ---------------------------------------------------------------------------
373 This corresponds to the command-line option "\fB--no-kill\fP".
378 box in the background,
379 printing its process id to \fB\*p\fP's output.
380 SIGHUP is disabled for the background process.
381 .\" ---------------------------------------------------------------------------
383 This corresponds to the command-line option "\fB--colors\fP".
384 If true, interpret embedded "\eZ" sequences in the dialog text
385 by the following character,
386 which tells \fB\*p\fP to set colors or video attributes:
387 0 through 7 are the ANSI codes used in curses:
396 Bold is set by 'b', reset by 'B'.
397 Reverse is set by 'r', reset by 'R'.
398 Underline is set by 'u', reset by 'U'.
399 The settings are cumulative, e.g., "\eZb\eZ1" makes the following text
401 Restore normal settings with "\eZn".
402 .\" ---------------------------------------------------------------------------
403 .SS .column_separator
404 This corresponds to the command-line option "\fB--column-separator\fP".
405 \fB\*L\fP splits data for radio/checkboxes and menus on the
406 occurrences of the given string, and aligns the split data into columns.
407 .\" ---------------------------------------------------------------------------
409 This corresponds to the command-line option "\fB--cr-wrap\fP".
411 interpret embedded newlines in the dialog text as a newline on the screen.
412 Otherwise, \fB\*p\fR will only wrap lines where needed
413 to fit inside the text box.
414 Even though you can control line breaks with this,
415 \fB\*p\fR will still wrap any lines that are too long for the width of the box.
416 Without cr-wrap, the layout of your text may be formatted to look nice
417 in the source code of your script without affecting the way it will
419 .\" ---------------------------------------------------------------------------
421 This corresponds to the command-line option
422 "\fB--date-format\fP \fIstring\/\fP".
423 If the host provides \fBstrftime\fP, and the value is nonnull,
424 the calendar widget uses this to format its output.
425 .\" ---------------------------------------------------------------------------
427 This is set by the command-line option "\fB--default-button\fP.
428 It is used by \fBdlg_default_button\fP.
429 .\" ---------------------------------------------------------------------------
431 This corresponds to the command-line option
432 "\fB--default-item\fP \fIstring\/\fP".
433 The given string is used as
434 the default item in a checklist, form or menu box.
435 Normally the first item in the box is the default.
436 .\" ---------------------------------------------------------------------------
438 This corresponds to the command-line option "\fB--defaultno\fP".
440 make the default value of the
444 Likewise, treat the default button of widgets that provide
445 \*(``OK\*('' and \*(``Cancel\*(''
447 If \fB--nocancel\fP was given that option overrides this,
448 making the default button always \*(``Yes\*(''
449 (internally the same as \*(``OK\*('').
450 .\" ---------------------------------------------------------------------------
451 .SS .dlg_clear_screen
452 This corresponds to the command-line option "\fB--clear\fP".
453 This option is implemented in the main program, not the library.
455 the screen will be cleared on exit.
456 This may be used alone, without other options.
457 .\" ---------------------------------------------------------------------------
459 This corresponds to the command-line option "\fB--exit-label string\fP".
460 The given string overrides the label used for \*(``EXIT\*('' buttons.
461 .\" ---------------------------------------------------------------------------
463 This corresponds to the command-line option "\fB--extra-button\fP".
464 If true, some widgets show an extra button,
465 between \*(``OK\*('' and \*(``Cancel\*('' buttons.
466 .\" ---------------------------------------------------------------------------
468 This corresponds to the command-line option
469 "\fB--extra-label\fP \fIstring\/\fP".
470 The given string overrides the label used for \*(``Extra\*('' buttons.
471 Note: for inputmenu widgets, this defaults to \*(``Rename\*(''.
472 .\" ---------------------------------------------------------------------------
474 This is set by the command-line option "\fB--passwordform\fP"
475 to tell the form widget that its text fields should be treated like
477 .\" ---------------------------------------------------------------------------
479 This corresponds to the command-line option "\fB--help-button\fP".
480 If true, some widgets show a help-button after
481 \*(``OK\*('' and \*(``Cancel\*('' buttons,
482 i.e., in checklist, radiolist and menu boxes.
483 If \fB--item-help\fR is also given, on exit
484 the return status will be the same as for the \*(``OK\*('' button,
485 and the item-help text will be written to \fB\*p\fP's output
486 after the token \*(``HELP\*(''.
487 Otherwise, the return status will indicate that the Help button was pressed,
488 and no message printed.
489 .\" ---------------------------------------------------------------------------
491 This corresponds to the command-line option "\fB--hfile\fP \fIstring\/\fP".
492 The given filename is passed to \fBdialog_helpfile\fP when the user
494 .\" ---------------------------------------------------------------------------
496 This corresponds to the command-line option "\fB--help-label\fP \fIstring\/\fP".
497 The given string overrides the label used for \*(``Help\*('' buttons.
498 .\" ---------------------------------------------------------------------------
500 This corresponds to the command-line option "\fB--hline\fP \fIstring\/\fP".
501 The given string is displayed in the bottom of dialog windows,
503 .\" ---------------------------------------------------------------------------
505 This corresponds to the command-line option "\fB--help-status\fP".
506 If true, and the the help-button is selected,
507 writes the checklist or radiolist information
508 after the item-help \*(``HELP\*('' information.
509 This can be used to reconstruct the state of a checklist after processing
511 .\" ---------------------------------------------------------------------------
513 This corresponds to the command-line option "\fB--help-tags\fP".
515 \fBdlg_add_help_formitem\fP and
516 \fBdlg_add_help_listitem\fP use the item's tag value consistently
517 rather than using the tag's help-text value
518 when \fIDIALOG_VARS.item_help\fP is set.
519 .\" ---------------------------------------------------------------------------
521 This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated,
522 versus being a pointer to the user's local variables.
523 .\" ---------------------------------------------------------------------------
525 This flag is set to denote whether the menubox widget
526 implements a menu versus a inputmenu widget.
527 .\" ---------------------------------------------------------------------------
529 This may be either a user-supplied buffer,
530 or a buffer dynamically allocated by the library,
531 depending on \fIDIALOG_VARS.input_length\fP:
533 If \fIDIALOG_VARS.input_length\fP is zero,
534 this is a pointer to user buffer (on the stack, or static).
535 The buffer size is assumed to be \fBMAX_LEN\fP,
536 which is defined in \fI<\*l.h>\fP.
538 When \fIDIALOG_VARS.input_length\fP is nonzero,
539 this is a dynamically-allocated buffer used by the widgets to return
540 printable results to the calling application.
542 Certain widgets copy a result to this buffer.
543 If the pointer is NULL, or if the length is insufficient for
544 the result, then the \fB\*l\fP library allocates a buffer which is large enough,
545 and sets \fIDIALOG_VARS.input_length\fP.
546 Callers should check for this case if they have supplied their own buffer.
547 .\" ---------------------------------------------------------------------------
549 This corresponds to the command-line option "\fB--insecure\fP".
550 If true, make the password widget friendlier but less secure,
551 by echoing asterisks for each character.
552 .\" ---------------------------------------------------------------------------
554 This variable is used to prevent \fBdialog_helpfile\fP from showing
555 anything, e.g., if F1 were pressed within a help-file display.
556 .\" ---------------------------------------------------------------------------
558 This corresponds to the command-line option "\fB--iso-week\fP".
559 It is used in the calendar widget to tell how
560 to compute the starting week for the year:
562 by default, the calendar treats January 1 as the first week of the year.
564 If this variable is true, the calendar uses ISO 8601's convention.
565 ISO 8601 numbers weeks starting with the first week in January with
566 a Thursday in the current year.
567 January 1 may be in the \fIprevious\fP year.
568 .\" ---------------------------------------------------------------------------
570 This corresponds to the command-line option "\fB--item-help\fP".
572 interpret the tags data for checklist, radiolist and menu boxes
573 adding a column whose text is displayed in the bottom line of the
574 screen, for the currently selected item.
575 .\" ---------------------------------------------------------------------------
577 This is set by the command-line option "\fB--keep-tite\fP"
578 to tell \fB\*p\fP to not attempt to cancel the terminal initialization
579 (termcap \fIti\/\fP/\,\fIte\/\fP) sequences
580 which correspond to xterm's alternate-screen switching.
581 Normally \fB\*p\fP does this to avoid flickering when run several times
583 .\" ---------------------------------------------------------------------------
585 This corresponds to the command-line option "\fB--keep-window\fP".
586 If true, do not remove/repaint the window on exit.
587 This is useful for keeping the window contents visible when several
588 widgets are run in the same process.
589 Note that curses will clear the screen when starting a new process.
590 .\" ---------------------------------------------------------------------------
592 This corresponds to the command-line option "\fB--last-key\fP".
593 .\" ---------------------------------------------------------------------------
595 This corresponds to the command-line option "\fB--max-input\fP \fIsize\/\fP".
596 Limit input strings to the given size.
597 If not specified, the limit is 2048.
598 .\" ---------------------------------------------------------------------------
600 This corresponds to the command-line option "\fB--no-items\fP".
601 Some widgets (checklist, inputmenu, radiolist, menu) display a list
602 with two columns (a \*(``tag\*('' and \*(``item\*('',
603 i.e., \*(``description\*('').
604 This tells \fB\*p\fP to read shorter rows from data,
605 omitting the \*(``list\*(''.
606 .\" ---------------------------------------------------------------------------
608 This corresponds to the command-line option "\fB--no-label\fP \fIstring\/\fP".
609 The given string overrides the label used for \*(``No\*('' buttons.
610 .\" ---------------------------------------------------------------------------
612 This corresponds to the command-line option "\fB--no-lines\fP.
613 It suppresses line-drawing.
614 See \fIDIALOG_VARS.ascii_lines\fP.
615 .\" ---------------------------------------------------------------------------
617 This corresponds to the command-line option "\fB--no-nl-expand\fP".
618 If false, \fBdlg_trim_string\fP converts literal "\en" substrings
619 in a message into newlines.
620 .\" ---------------------------------------------------------------------------
622 This corresponds to the command-line option "\fB--no-tags\fP".
623 Some widgets (checklist, inputmenu, radiolist, menu) display a list
624 with two columns (a \*(``tag\*('' and \*(``item\*('',
625 also known as \*(``description\*('').
626 The tag is useful for scripting, but may not help the user.
627 The \fB--no-tags\fP option (from Xdialog) may be used to suppress the
628 column of tags from the display.
630 Normally \fB\*p\fP allows you to quickly move to entries on the displayed list,
631 by matching a single character to the first character of the tag.
632 When the \fB--no-tags\fP option is given, \fB\*p\fP matches against
633 the first character of the description.
634 In either case, the matchable character is highlighted.
636 Here is a table showing how the no_tags and no_items values interact:
641 Widget/Fields Shown/Fields Read/.no_items/.no_tags
643 buildlist/item/tag,item/0/0*
644 buildlist/item/tag,item/0/1
645 buildlist/tag/tag/1/0*
646 buildlist/tag/tag/1/1
647 checklist/tag,item/tag,item/0/0
648 checklist/item/tag,item/0/1
649 checklist/tag/tag/1/0
650 checklist/tag/tag/1/1
651 inputmenu/tag,item/tag,item/0/0
652 inputmenu/item/tag,item/0/1
653 inputmenu/tag/tag/1/0
654 inputmenu/tag/tag/1/1
655 menu/tag,item/tag,item/0/0
656 menu/item/tag,item/0/1
659 radiolist/tag,item/tag,item/0/0
660 radiolist/item/tag,item/0/1
661 radiolist/tag/tag/1/0
662 radiolist/tag/tag/1/1
663 treeview/item/tag,item/0/0*
664 treeview/item/tag,item/0/1
665 treeview/tag/tag/1/0*
671 Xdialog does not display the tag column for the analogous buildlist
672 and treeview widgets.
673 \fB\*L\fP does the same on the command-line.
674 However the library interface defaults to displaying the tag column.
675 Your application can enable or disable the tag column as needed for each widget.
676 .\" ---------------------------------------------------------------------------
678 This corresponds to the command-line option "\fB--no-cancel\fP".
680 suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes.
681 A script can still test if the user pressed the ESC key to cancel to quit.
682 .\" ---------------------------------------------------------------------------
684 This corresponds to the command-line option "\fB--no-collapse\fP".
685 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
686 spaces to a single space for text which is displayed in a message boxes, etc.
687 It true, that feature is disabled.
688 Note that \fB\*p\fR will still wrap text, subject to the \fB--cr-wrap\fR
690 .\" ---------------------------------------------------------------------------
692 This corresponds to the command-line option "\fB--nook\fP.
693 \fB\*L\fP will suppress the \*(``ok\*('' (or \*(``yes\*('') button
695 .\" ---------------------------------------------------------------------------
697 This corresponds to the command-line option "\fB--ok-label\fP \fIstring\/\fP".
698 The given string overrides the label used for \*(``OK\*('' buttons.
699 .\" ---------------------------------------------------------------------------
701 This corresponds to the command-line option "\fB--print-size\fP".
703 each widget prints its size to \fB\*p\fP's output when it is invoked.
704 .\" ---------------------------------------------------------------------------
706 This corresponds to the command-line option "\fB--quoted\fP.
707 Normally \fB\*p\fP quotes the strings returned by checklist's
708 as well as the item-help text.
709 If true, \fB\*p\fP will quote all string results.
710 .\" ---------------------------------------------------------------------------
712 This corresponds to the command-line option "\fB--reorder\fP.
713 By default, the buildlist widget uses the same order for the output (right)
714 list as for the input (left).
715 If true, \fB\*p\fP will use the order in which a user adds selections
717 .\" ---------------------------------------------------------------------------
719 This corresponds to the command-line option "\fB--separate-output\fP".
721 checklist widgets output result one line at a time, with no quoting.
722 This facilitates parsing by another program.
723 .\" ---------------------------------------------------------------------------
725 This corresponds to the command-line option "\fB--single-quoted\fP".
727 use single-quoting as needed (and no quotes if unneeded) for the
728 output of checklist's as well as the item-help text.
729 If this option is not set, \fB\*p\fP uses double quotes around each item.
730 The latter requires occasional use of backslashes to make the output useful in
732 .\" ---------------------------------------------------------------------------
734 This corresponds to the command-line option "\fB--size-err\fP".
736 check the resulting size of a dialog box before trying to use it,
737 printing the resulting size if it is larger than the screen.
738 (This option is obsolete, since all new-window calls are checked).
739 .\" ---------------------------------------------------------------------------
741 This corresponds to the command-line option "\fB--sleep\fP \fIsecs\/\fP".
742 This option is implemented in the main program, not the library.
743 If nonzero, this is the number of seconds after to delay
744 after processing a dialog box.
745 .\" ---------------------------------------------------------------------------
747 This corresponds to the command-line option "\fB--tab-correct\fP".
748 If true, convert each tab character of the text to one or more spaces.
749 Otherwise, tabs are rendered according to the curses library's interpretation.
750 .\" ---------------------------------------------------------------------------
752 This corresponds to the command-line option
753 "\fB--time-format\fP \fIstring\/\fP".
754 If the host provides \fBstrftime\fP, and the value is nonnull,
755 the timebox widget uses this to format its output.
756 .\" ---------------------------------------------------------------------------
758 This corresponds to the command-line option "\fB--timeout\fP \fIsecs\/\fP".
759 If nonzero, timeout input requests (exit with error code)
760 if no user response within the given number of seconds.
761 .\" ---------------------------------------------------------------------------
763 This corresponds to the command-line option "\fB--title\fP \fItitle\/\fP".
766 string to be displayed at the top of the dialog box.
767 .\" ---------------------------------------------------------------------------
769 This corresponds to the command-line option "\fB--trim\fP".
770 If true, eliminate leading blanks,
771 trim literal newlines and repeated blanks from message text.
772 .\" ---------------------------------------------------------------------------
774 This corresponds to the command-line option "\fB--week-start\fP".
775 It is used in the calendar widget to set the starting day for the week.
776 The string value can be
778 a number (0 to 6, Sunday through Saturday using POSIX) or
780 the special value \*(``locale\*('' (this works with systems using glibc,
781 providing an extension to the \fBlocale\fP command,
782 the \fBfirst_weekday\fP value).
784 a string matching one of the abbreviations for the day of the week
785 shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''.
786 .\" ---------------------------------------------------------------------------
788 This corresponds to the command-line option "\fB--yes-label\fP \fIstring\/\fP".
789 The given string overrides the label used for \*(``Yes\*('' buttons.
791 .\" ************************************************************************
792 .\" ************************************************************************
794 Functions that implement major functionality for the command-line \fB\*p\fP
795 program, e.g., widgets, have names beginning "\fIdialog_\fP".
797 All dialog boxes have at least three parameters:
801 the caption for the box, shown on its top border.
804 the height of the dialog box.
807 the width of the dialog box.
810 Other parameters depend on the box type.
812 .\" ************************************************************************
814 implements the "\fB--buildlist\fP" option.
816 .B const char * \fItitle
817 is the title on the top of the widget.
819 .B const char * \fIcprompt
820 is the prompt text shown within the widget.
823 is the desired height of the box.
824 If zero, the height is adjusted to use the available screen size.
827 is the desired width of the box.
828 If zero, the height is adjusted to use the available screen size.
830 .B int \fIlist_height
831 is the minimum height to reserve for displaying the list.
832 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
835 is the number of rows in \fIitems\fP.
838 is an array of strings which is viewed either as a list of rows
840 \fItag item status\fR
845 \fItag item status help\fR
848 depending on whether \fBdialog_vars.item_help\fP is set.
851 is reserved for future enhancements
853 .\" ************************************************************************
855 implements the "\fB--calendar\fP" option.
857 .B const char * \fItitle
858 is the title on the top of the widget.
860 .B const char * \fIsubtitle
861 is the prompt text shown within the widget.
864 is the height excluding the fixed-height calendar grid.
867 is the overall width of the box,
868 which is adjusted up to the calendar grid's minimum width if needed.
871 is the initial day of the week shown,
872 counting zero as Sunday.
873 If the value is negative, the current day of the week is used.
876 is the initial month of the year shown,
877 counting one as January.
878 If the value is negative, the current month of the year is used.
881 is the initial year shown.
882 If the value is negative, the current year is used.
883 .\" ************************************************************************
885 implements the "\fB--checklist\fP" and "\fB--radiolist\fP" options
886 depending on the \fIflag\fP parameter.
888 .B const char * \fItitle
889 is the title on the top of the widget.
891 .B const char * \fIcprompt
892 is the prompt text shown within the widget.
895 is the desired height of the box.
896 If zero, the height is adjusted to use the available screen size.
899 is the desired width of the box.
900 If zero, the height is adjusted to use the available screen size.
902 .B int \fIlist_height
903 is the minimum height to reserve for displaying the list.
904 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
907 is the number of rows in \fIitems\fP.
910 is an array of strings which is viewed either as a list of rows
912 \fItag item status\fR
917 \fItag item status help\fR
920 depending on whether \fBdialog_vars.item_help\fP is set.
922 is either \fIFLAG_CHECK\fP, for checklists,
923 or \fIFLAG_RADIO\fP for radiolists.
924 .\" ************************************************************************
926 implements the "\fB--dselect\fP" option.
928 .B const char * \fItitle
929 is the title on the top of the widget.
931 .B const char * \fIpath
932 is the preselected value to show in the input-box,
933 which is used also to set the directory- and file-windows.
936 is the height excluding the minimum needed to show the dialog box framework.
937 If zero, the height is based on the screen size.
940 is the desired width of the box.
941 If zero, the height is based on the screen size.
942 .\" ************************************************************************
944 implements the "\fB--editbox\fP" option.
946 .B const char * \fItitle
947 is the title on the top of the widget.
949 .B const char * \fIfile
950 is the name of the file from which to read.
953 is the desired height of the box.
954 If zero, the height is adjusted to use the available screen size.
957 is the desired width of the box.
958 If zero, the height is adjusted to use the available screen size.
959 .\" ************************************************************************
961 implements the "\fB--form\fP" option.
963 .B const char * \fItitle
964 is the title on the top of the widget.
966 .B const char * \fIcprompt
967 is the prompt text shown within the widget.
970 is the desired height of the box.
971 If zero, the height is adjusted to use the available screen size.
974 is the desired width of the box.
975 If zero, the height is adjusted to use the available screen size.
977 .B int \fIform_height
978 is the minimum height to reserve for displaying the list.
979 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
982 is the number of rows in \fIitems\fP.
985 is an array of strings which is viewed either as a list of rows
987 \fIName NameY NameX Text TextY TextX FLen ILen\fR
992 \fIName NameY NameX Text TextY TextX FLen ILen Help\fR
995 depending on whether \fBdialog_vars.item_help\fP is set.
996 .\" ************************************************************************
998 implements the "\fB--fselect\fP" option.
1000 .B const char * \fItitle
1001 is the title on the top of the widget.
1003 .B const char * \fIpath
1004 is the preselected value to show in the input-box,
1005 which is used also to set the directory- and file-windows.
1008 is the height excluding the minimum needed to show the dialog box framework.
1009 If zero, the height is based on the screen size.
1012 is the desired width of the box.
1013 If zero, the height is based on the screen size.
1014 .\" ************************************************************************
1016 implements the "\fB--gauge\fP" option.
1017 Alternatively, a simpler or customized gauge widget can be
1019 \fBdlg_allocate_gauge\fP,
1020 \fBdlg_reallocate_gauge\fP,
1021 \fBdlg_update_gauge\fP and
1022 \fBdlg_free_gauge\fP.
1024 .B const char * \fItitle
1025 is the title on the top of the widget.
1027 .B const char * \fIcprompt
1028 is the prompt text shown within the widget.
1031 is the desired height of the box.
1032 If zero, the height is based on the screen size.
1035 is the desired width of the box.
1036 If zero, the height is based on the screen size.
1039 is the percentage to show in the progress bar.
1040 .\" ************************************************************************
1042 implements the "\fB--inputbox\fP" or
1043 "\fB--password\fP" option, depending on the value of \fIpassword\fP.
1045 .B const char * \fItitle
1046 is the title on the top of the widget.
1048 .B const char * \fIcprompt
1049 is the prompt text shown within the widget.
1052 is the desired height of the box.
1053 If zero, the height is based on the screen size.
1056 is the desired width of the box.
1057 If zero, the height is based on the screen size.
1059 .B const char * \fIinit
1060 is the initial value of the input box, whose length is taken into account
1061 when auto-sizing the width of the dialog box.
1064 if true, causes typed input to be echoed as asterisks.
1065 .\" ************************************************************************
1067 implements the "\fB--hfile\fP" option.
1069 .B const char * \fItitle
1070 is the title on the top of the widget.
1072 .B const char * \fIfile
1073 is the name of a file containing the text to display.
1074 This function is internally bound to F1 (function key \*(``1\*(''),
1075 passing \fBdialog_vars.help_file\fP as a parameter.
1076 The \fB\*p\fP program sets that variable when the \fB--hfile\fP option
1080 is the desired height of the box.
1081 If zero, the height is based on the screen size.
1084 is the desired width of the box.
1085 If zero, the height is based on the screen size.
1086 .\" ************************************************************************
1088 implements the "\fB--menu\fP" or "\fB--inputmenu\fP" option
1089 depending on whether \fBdialog_vars.input_menu\fP is set.
1091 .B const char * \fItitle
1092 is the title on the top of the widget.
1094 .B const char * \fIcprompt
1095 is the prompt text shown within the widget.
1098 is the desired height of the box.
1099 If zero, the height is based on the screen size.
1102 is the desired width of the box.
1103 If zero, the height is based on the screen size.
1105 .B int \fImenu_height
1106 is the minimum height to reserve for displaying the list.
1107 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1110 is the number of rows in \fIitems\fP.
1113 is an array of strings which is viewed either as a list of rows
1123 depending on whether \fBdialog_vars.item_help\fP is set.
1124 .\" ************************************************************************
1125 .SS dialog_mixedform
1126 implements the "\fB--mixedform\fP" option.
1128 .B const char * \fItitle
1129 is the title on the top of the widget.
1131 .B const char * \fIcprompt
1132 is the prompt text shown within the widget.
1135 is the desired height of the box.
1136 If zero, the height is adjusted to use the available screen size.
1139 is the desired width of the box.
1140 If zero, the height is adjusted to use the available screen size.
1142 .B int \fIform_height
1143 is the minimum height to reserve for displaying the list.
1144 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1147 is the number of rows in \fIitems\fP.
1150 is an array of strings which is viewed either as a list of rows
1152 \fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR
1157 \fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR
1160 depending on whether \fBdialog_vars.item_help\fP is set.
1161 .\" ************************************************************************
1162 .SS dialog_mixedgauge
1163 implements the "\fB--mixedgauge\fP" option
1165 .B const char * \fItitle
1166 is the title on the top of the widget.
1168 .B const char * \fIcprompt
1169 is the caption text shown within the widget.
1172 is the desired height of the box.
1173 If zero, the height is based on the screen size.
1176 is the desired width of the box.
1177 If zero, the height is based on the screen size.
1180 is the percentage to show in the progress bar.
1183 is the number of rows in \fIitems\fP.
1186 is an array of strings which is viewed as a list
1187 of \fItag\fP and \fIitem\fP values.
1188 The \fItag\fP values are listed,
1189 one per row, in the list at the top of the widget.
1191 The \fIitem\fP values are decoded:
1192 digits 0 through 9 are the following strings
1216 A string with a leading "-" character is centered, marked with "%".
1217 For example, "-75" is displayed as "75%".
1218 Other strings are displayed as is.
1219 .\" ************************************************************************
1221 implements the "\fB--msgbox\fP" or "\fB--infobox\fP" option
1222 depending on whether \fIpauseopt\fP is set.
1224 .B const char * \fItitle
1225 is the title on the top of the widget.
1227 .B const char * \fIcprompt
1228 is the prompt text shown within the widget.
1231 is the desired height of the box.
1232 If zero, the height is based on the screen size.
1235 is the desired width of the box.
1236 If zero, the height is based on the screen size.
1239 if true, an \*(``OK\*('' button will be shown,
1240 and the dialog will wait for it to complete.
1241 With an \*(``OK\*('' button, it is denoted a \*(``msgbox\*('',
1242 without an \*(``OK\*('' button, it is denoted an \*(``infobox\*(''.
1243 .\" ************************************************************************
1245 implements the "\fB--pause\fP" option.
1247 .B const char * \fItitle
1248 is the title on the top of the widget.
1251 is the desired height of the box.
1252 If zero, the height is based on the screen size.
1255 is the desired width of the box.
1256 If zero, the height is based on the screen size.
1259 is the timeout to use for the progress bar.
1260 .\" ************************************************************************
1262 implements the "\fB--prgbox\fP" option.
1264 .B const char * \fItitle
1265 is the title on the top of the widget.
1267 .B const char * \fIcprompt
1268 is the prompt text shown within the widget.
1269 If empty or null, no prompt is shown.
1271 .B const char * \fIcommand
1272 is the name of the command to execute.
1275 is the desired height of the box.
1276 If zero, the height is based on the screen size.
1279 is the desired width of the box.
1280 If zero, the height is based on the screen size.
1283 if true, an \*(``OK\*('' button will be shown,
1284 and the dialog will wait for it to complete.
1285 .\" ************************************************************************
1286 .SS dialog_progressbox
1287 implements the "\fB--progressbox\fP" option.
1289 .B const char * \fItitle
1290 is the title on the top of the widget.
1292 .B const char * \fIcprompt
1293 is the prompt text shown within the widget.
1294 If empty or null, no prompt is shown.
1297 is the desired height of the box.
1298 If zero, the height is based on the screen size.
1301 is the desired width of the box.
1302 If zero, the height is based on the screen size.
1303 .\" ************************************************************************
1305 implements the "\fB--rangebox\fP" option.
1307 .B const char * \fItitle
1308 is the title on the top of the widget.
1310 .B const char * \fIcprompt
1311 is the prompt text shown within the widget.
1312 If empty or null, no prompt is shown.
1315 is the desired height of the widget.
1316 If zero, the height is based on the screen size.
1319 is the desired width of the widget.
1320 If zero, the height is based on the screen size.
1323 is the minimum value to allow.
1326 is the maximum value to allow.
1328 .B int \fIdefault_value
1329 is the default value, if no change is made.
1330 .\" ************************************************************************
1332 implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option
1333 depending on whether \fIbg_task\fP is set.
1335 .B const char * \fItitle
1336 is the title on the top of the widget.
1338 .B const char * \fIfile
1339 is the name of the file to display in the dialog.
1342 is the desired height of the box.
1343 If zero, the height is based on the screen size.
1346 is the desired width of the box.
1347 If zero, the height is based on the screen size.
1351 the window is added to the callback list in \fBdialog_state\fP,
1352 and the application will poll for the window to be updated.
1353 Otherwise an \*(``OK\*('' button is added to the window,
1354 and it will be closed when the button is activated.
1355 .\" ************************************************************************
1357 implements the "\fB--textbox\fP" option.
1359 .B const char * \fItitle
1360 is the title on the top of the widget.
1362 .B const char * \fIfile
1363 is the name of the file to display in the dialog.
1366 is the desired height of the box.
1367 If zero, the height is based on the screen size.
1370 is the desired width of the box.
1371 If zero, the height is based on the screen size.
1372 .\" ************************************************************************
1374 implements the "\fB--timebox\fP" option.
1376 .B const char * \fItitle
1377 is the title on the top of the widget.
1379 .B const char * \fIsubtitle
1380 is the prompt text shown within the widget.
1383 is the desired height of the box.
1384 If zero, the height is based on the screen size.
1387 is the desired width of the box.
1388 If zero, the height is based on the screen size.
1391 is the initial hour shown.
1392 If the value is negative, the current hour is used.
1393 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24.
1396 is the initial minute shown.
1397 If the value is negative, the current minute is used.
1398 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1401 is the initial second shown.
1402 If the value is negative, the current second is used.
1403 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1404 .\" ************************************************************************
1406 implements the "\fB--treeview\fP" option.
1408 .B const char * \fItitle
1409 is the title on the top of the widget.
1411 .B const char * \fIcprompt
1412 is the prompt text shown within the widget.
1415 is the desired height of the box.
1416 If zero, the height is based on the screen size.
1419 is the desired width of the box.
1420 If zero, the height is based on the screen size.
1422 .B int \fIlist_height
1423 is the minimum height to reserve for displaying the list.
1424 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1427 is the number of rows in \fIitems\fP.
1430 is the list of items, contain tag, name, and optionally help strings
1431 (if \fBdialog_vars.item_help\fP is set).
1432 The initial selection state for each item is also in this list.
1436 is either \fIFLAG_CHECK\fP, for checklists (multiple selections),
1437 or \fIFLAG_RADIO\fP for radiolists (a single selection).
1438 .\" ************************************************************************
1440 implements the "\fB--yesno\fP" option.
1442 .B const char * \fItitle
1443 is the title on the top of the widget.
1445 .B const char * \fIcprompt
1446 is the prompt text shown within the widget.
1449 is the desired height of the box.
1450 If zero, the height is based on the screen size.
1453 is the desired width of the box.
1454 If zero, the height is based on the screen size.
1456 .\" ************************************************************************
1457 .SH UTILITY FUNCTIONS
1458 Most functions that implement lower-level
1459 functionality for the command-line \fB\*p\fP
1460 program or widgets, have names beginning "\fIdlg_\fP".
1461 Bowing to longstanding usage, the functions that initialize the
1462 display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP.
1464 The only non-widget function whose name begins with "\fIdialog_\fP"
1465 is \fBdialog_version\fP, which returns the version number of the
1466 library as a string.
1469 Here is a brief summary of the utility functions and their parameters:
1470 .\" ---------------------------------------------------------------------------
1471 .SS dlg_add_callback
1472 Add a callback, used to allow polling input from multiple tailbox
1475 .B DIALOG_CALLBACK *\fIp\fP
1476 contains the callback information.
1477 .\" ---------------------------------------------------------------------------
1478 .SS dlg_add_callback_ref
1479 Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP
1480 as well as a pointer to a cleanup function which will be called when the
1481 associated input ends.
1483 .B DIALOG_CALLBACK **\fIp\fP
1484 points to the callback information.
1485 This is a reference to the pointer so that the caller's pointer can be
1486 zeroed when input ends.
1488 .B DIALOG_FREEBACK \fIfunc\fP
1489 function to call when input ends, e.g., to free caller's additional data.
1490 .\" ---------------------------------------------------------------------------
1491 .SS dlg_add_help_formitem
1492 This is a utility function used enforce consistent behavior for
1493 the \fIDIALOG_VARS.help_tags\fP and \fIDIALOG_VARS.item_help\fP variables.
1495 .B int *\fIresult\fP
1496 this is updated to DLG_EXIT_ITEM_HELP if \fIDIALOG_VARS.item_help\fP is set.
1499 the tag- or help-text is stored here.
1501 .B DIALOG_FORMITEM *\fIitem\fP
1502 contains the list item to use for tag- or help-text.
1503 .\" ---------------------------------------------------------------------------
1504 .SS dlg_add_help_listitem
1505 This is a utility function used enforce consistent behavior for
1506 the \fIDIALOG_VARS.help_tags\fP and \fIDIALOG_VARS.item_help\fP variables.
1508 .B int *\fIresult\fP
1509 this is updated to DLG_EXIT_ITEM_HELP if \fIDIALOG_VARS.item_help\fP is set.
1512 the tag- or help-text is stored here.
1514 .B DIALOG_LISTITEM *\fIitem\fP
1515 contains the list item to use for tag- or help-text.
1516 .\" ---------------------------------------------------------------------------
1517 .SS dlg_add_last_key
1518 Report the last key entered by the user.
1519 This implements the \fB--last-key\fP command-line option,
1520 using \fBdialog_vars.last_key\fP.
1523 controls the way the last key report is separated from other results:
1530 (separator after the key name)
1533 (separator is optionally before the key name)
1538 .\" ---------------------------------------------------------------------------
1540 Add a quoted string to the result buffer (see \fBdlg_add_result\fP).
1541 If no quotes are necessary, none are used.
1542 If \fBdialog_vars.single_quoted\fR is set, single-quotes are used.
1543 Otherwise, double-quotes are used.
1546 is the string to add.
1547 .\" ---------------------------------------------------------------------------
1549 Add a string to the result buffer \fBdialog_vars.input_result\fP.
1552 is the string to add.
1553 .\" ---------------------------------------------------------------------------
1554 .SS dlg_add_separator
1555 Add an output-separator to the result buffer \fBdialog_vars.input_result\fP.
1556 If \fBdialog_vars.output_separator\fP is set, use that.
1557 Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline.
1558 If neither is set, use a space.
1559 .\" ---------------------------------------------------------------------------
1561 Add a quoted or unquoted string to the result buffer
1562 (see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP),
1563 according to whether \fBdialog_vars.quoted\fP is true.
1566 is the string to add.
1567 .\" ---------------------------------------------------------------------------
1568 .SS dlg_align_columns
1569 Copy and reformat an array of pointers to strings, aligning according to
1570 the column separator \fBdialog_vars.column_separator\fP.
1571 If no column separator is set, the array will be unmodified;
1572 otherwise it is copied and reformatted.
1574 Caveat: This function is only implemented for 8-bit characters.
1577 This is the array to reformat.
1578 It points to the first string to modify.
1581 This is the size of the struct for each row of the array.
1584 This is the number of rows in the array.
1585 .\" ---------------------------------------------------------------------------
1586 .SS dlg_allocate_gauge
1587 Allocates a gauge widget.
1588 Use \fBdlg_update_gauge\fP to display the result.
1590 .B const char * \fItitle
1591 is the title string to display at the top of the widget.
1593 .B const char * \fIcprompt
1594 is the prompt text shown within the widget.
1597 is the desired height of the box.
1598 If zero, the height is adjusted to use the available screen size.
1601 is the desired width of the box.
1602 If zero, the height is adjusted to use the available screen size.
1605 is the percentage to show in the progress bar.
1606 .\" ---------------------------------------------------------------------------
1608 returns its parameter transformed to the
1609 corresponding "+" or "-", etc.,
1610 for the line-drawing characters used in \fB\*p\fP.
1611 If the parameter is not a line-drawing or other special character
1612 such as ACS_DARROW, it returns 0.
1615 is the parameter, usually one of the \fBACS_\fP\fIxxx\fP constants.
1616 .\" ---------------------------------------------------------------------------
1618 Set window to the given attribute.
1621 is the window to update.
1624 is the number of rows to update.
1627 is the number of columns to update.
1630 is the attribute, e.g., \fBA_BOLD\fP.
1631 .\" ---------------------------------------------------------------------------
1633 Compute window size based on the size of the formatted \fIprompt\fP and
1634 minimum dimensions for a given widget.
1637 \fBdialog_state.text_height\fP and
1638 \fBdialog_state.text_width\fP for
1639 the formatted \fIprompt\fP
1642 Normally \fB\*l\fP writes the formatted \fIprompt\fP to the curses
1644 but it will write the formatted \fIprompt\fP to the output stream
1645 if \fBdialog_state.text_only\fP is set.
1647 .B const char * \fItitle
1648 is the title string to display at the top of the widget.
1650 .B const char * \fIprompt
1651 is the message text which will be displayed in the widget,
1652 used here to determine how large the widget should be.
1654 If the value is \fINULL\fP,
1655 \fB\*l\fP allows the widget to use the whole screen,
1656 i.e., if the values referenced by \fIheight\fP and/or \fIwidth\fP are zero.
1659 is the nominal height.
1660 \fB\*L\fP checks the referenced value and may update it:
1663 if the value is negative,
1664 \fB\*l\fP updates it to the available height of the screen,
1665 after reserving rows for the window border and shadow,
1666 as well as taking into account
1667 \fBdialog_vars.begin_y\fP and
1668 \fBdialog_vars.begin_set\fP.
1670 if the value is zero,
1671 \fB\*l\fP updates it to the required height of the window,
1672 taking into account a (possibly) multi-line \fIprompt\fP.
1674 if the value is greater than zero,
1675 \fB\*l\fP uses it internally, but restores the value on return.
1679 is the nominal width.
1680 \fB\*L\fP checks the referenced value and may update it:
1683 if the value is negative,
1684 \fB\*l\fP updates it to the available width of the screen,
1685 after reserving rows for the window border and shadow,
1686 as well as taking into account
1687 \fBdialog_vars.begin_x\fP and
1688 \fBdialog_vars.begin_set\fP.
1690 if the value is zero,
1691 \fB\*l\fP updates it to the required width of the window,
1692 taking into account a (possibly) multi-line \fIprompt\fP.
1694 if the value is greater than zero,
1695 \fB\*l\fP uses it internally, but restores the value on return.
1699 is the number of lines to reserve in the vertical direction.
1702 is the minimum number of columns to use.
1703 .\" ---------------------------------------------------------------------------
1704 .SS dlg_auto_sizefile
1705 Like \fBdlg_auto_size\fP, but use a file contents to decide how large
1706 the widget should be.
1708 .B const char * \fItitle
1709 is the title string to display at the top of the widget.
1711 .B const char * \fIfile
1712 is the name of the file.
1715 is the nominal height.
1717 If it is -1, use the screen's height
1718 (after subtracting \fBdialog_vars.begin_y\fP
1719 if \fBdialog_vars.begin_set\fP is true).
1721 If it is greater than zero,
1722 limit the referenced value to the screen-height
1723 after verifying that the file exists.
1726 is the nominal width.
1728 If it is -1, use the screen's width (after subtracting \fBdialog_vars.begin_x\fP
1729 if \fBdialog_vars.begin_set\fP is true).
1731 If it is greater than zero,
1732 limit the referenced value to the screen-width
1733 after verifying that the file exists.
1736 is the number of lines to reserve on the screen for drawing boxes.
1739 is the number of columns to reserve on the screen for drawing boxes.
1740 .\" ---------------------------------------------------------------------------
1742 If \fBdialog_vars.beep_signal\fP is nonzero,
1743 this calls \fBbeep\fP once and sets
1744 \fBdialog_vars.beep_signal\fP to zero.
1745 .\" ---------------------------------------------------------------------------
1747 returns its \fBchtype\fP parameter transformed as follows:
1749 if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set.
1751 if \fBdialog_vars.ascii_lines\fP is set,
1752 returns the corresponding "+" or "-", etc.,
1753 for the line-drawing characters used in \fB\*p\fP.
1755 otherwise, if \fBdialog_vars.no_lines\fP is set,
1756 returns a space for the line-drawing characters.
1758 if the parameter is not a line-drawing or other special character
1760 it returns the parameter unchanged.
1761 .\" ---------------------------------------------------------------------------
1762 .SS dlg_box_x_ordinate
1763 returns a suitable x-ordinate (column) for a new widget.
1764 If \fBdialog_vars.begin_set\fP is 1,
1765 use \fBdialog_vars.begin_x\fP;
1766 otherwise center the widget on the screen (using the \fIwidth\fP parameter).
1769 is the width of the widget.
1770 .\" ---------------------------------------------------------------------------
1771 .SS dlg_box_y_ordinate
1772 returns a suitable y-ordinate (row) for a new widget.
1773 If \fBdialog_vars.begin_set\fP is 1,
1774 use \fBdialog_vars.begin_y\fP;
1775 otherwise center the widget on the screen (using the \fIheight\fP parameter).
1778 is the height of the widget.
1779 .\" ---------------------------------------------------------------------------
1781 This is an alternate interface to the \fBbuildlist\fP widget
1782 which allows the application to read the list item states back
1783 directly without putting them in the output buffer.
1785 .B const char * \fItitle
1786 is the title string to display at the top of the widget.
1788 .B const char * \fIcprompt
1789 is the prompt text shown within the widget.
1792 is the desired height of the box.
1793 If zero, the height is adjusted to use the available screen size.
1796 is the desired width of the box.
1797 If zero, the height is adjusted to use the available screen size.
1799 .B int \fIlist_height
1800 is the minimum height to reserve for displaying the list.
1801 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1804 is the number of rows in \fIitems\fP.
1806 .B DIALOG_LISTITEM * \fIitems
1807 is the list of items, contain tag, name, and optionally help strings
1808 (if \fBdialog_vars.item_help\fP is set).
1809 The initial selection state for each item is also in this list.
1811 .B const char * \fIstates
1812 This is a list of characters to display for the given states.
1813 Normally a buildlist provides true (1) and false (0) values,
1814 which the widget displays as "*" and space, respectively.
1815 An application may set this parameter to an arbitrary null-terminated string.
1816 The widget determines the number of states from the length of this string,
1817 and will cycle through the corresponding display characters as the user
1818 presses the space-bar.
1820 .B int \fIorder_mode
1821 is reserved for future enhancements
1823 .B int * \fIcurrent_item
1824 The widget sets the referenced location to the index of the current display
1825 item (cursor) when it returns.
1826 .\" ---------------------------------------------------------------------------
1827 .SS dlg_button_count
1828 Count the buttons in the list.
1830 .B const char ** \fIlabels
1831 is a list of (pointers to) button labels terminated by a null pointer.
1832 .\" ---------------------------------------------------------------------------
1834 If a key was bound to one of the button-codes in \fBdlg_result_key\fP, fake
1835 a button-value and an \*(``Cancel\*('' key
1836 to cause the calling widget to return the corresponding status.
1838 See \fBdlg_ok_buttoncode\fP, which maps settings for ok/extra/help and button
1839 number into exit-code.
1840 .\" ---------------------------------------------------------------------------
1841 .SS dlg_button_layout
1842 Make sure there is enough space for the buttons by
1843 computing the width required for their labels,
1844 adding margins and limiting based on the screen size.
1846 .B const char ** \fIlabels
1847 is a list of (pointers to) button labels terminated by a null pointer.
1850 the function sets the referenced \fIlimit\fP to the width required for
1851 the buttons (limited by the screen size)
1852 if that is wider than the passed-in limit.
1853 .\" ---------------------------------------------------------------------------
1854 .SS dlg_button_sizes
1855 Compute the size of the button array in columns.
1857 .B const char ** \fIlabels
1858 is a list of (pointers to) button labels terminated by a null pointer.
1861 is true if the buttons are arranged in a column rather than a row.
1864 Return the total number of columns in the referenced location.
1867 Return the longest button's columns in the referenced location.
1868 .\" ---------------------------------------------------------------------------
1869 .SS dlg_button_to_char
1870 Find the first uppercase character in the label, which we may use for an
1872 If the label is empty, return -1.
1873 If no uppercase character is found, return 0.
1874 Otherwise return the uppercase character.
1879 .B dlg_char_to_button
1880 use the first uppercase character.
1881 However, they keep track of all of the labels and
1882 if the first has already been used in another label,
1883 they will continue looking for another uppercase character.
1884 This function does not have enough information to make that check.
1886 .B const char * \fIlabel
1887 is the label to test.
1888 .\" ---------------------------------------------------------------------------
1889 .SS dlg_button_x_step
1890 Compute the step-size needed between elements of the button array.
1892 .B const char ** \fIlabels
1893 is a list of (pointers to) button labels terminated by a null pointer.
1896 is the maximum number of columns to allow for the buttons.
1899 store the nominal gap between buttons in the referenced location.
1900 This is constrained to be at least one.
1903 store the left+right total margins (for the list of buttons) in the referenced
1907 store the step-size in the referenced location.
1908 .\" ---------------------------------------------------------------------------
1909 .SS dlg_calc_list_width
1910 Calculate the minimum width for the list,
1911 assuming none of the items are truncated.
1914 is the number of \fIitems\fP.
1916 .B DIALOG_LISTITEM * \fIitems
1917 contains a \fIname\fP and \fItext\fP field,
1918 e.g., for checklists or radiobox lists.
1919 The function returns the sum of the widest columns
1920 needed for of each of these fields.
1922 If \fBdialog_vars.no_items\fP is set,
1923 the \fItext\fP fields in the list are ignored.
1924 .\" ---------------------------------------------------------------------------
1926 Calculate new height and list_height values.
1929 on input, is the height without adding the list-height.
1930 On return, this contains the total list-height and is the
1931 actual widget's height.
1933 .B int * \fIlist_height
1934 on input, is the requested list-height.
1935 On return, this contains the number of rows available for displaying
1936 the list after taking into account the screen size and
1937 the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables.
1940 is the number of \fIitems\fP in the list.
1941 .\" ---------------------------------------------------------------------------
1943 This function is obsolete, provided for library-compatibility.
1944 It is replaced by \fBdlg_calc_list_width\fP.
1947 is the number of \fIitems\fP.
1950 is a list of character pointers.
1953 is the number of items in each group, e.g., the second array index.
1954 .\" ---------------------------------------------------------------------------
1955 .SS dlg_char_to_button
1956 Given a list of button labels,
1957 and a character which may be the abbreviation for one, find it, if it exists.
1958 An abbreviation will be the first character
1959 which happens to be capitalized in the label.
1960 If the character is found, return its index within the list of \fIlabels\fP.
1961 Otherwise, return \fBDLG_EXIT_UNKNOWN\fP.
1964 is the character to find.
1966 .B const char ** \fIlabels
1967 is a list of (pointers to) button labels terminated by a null pointer.
1968 .\" ---------------------------------------------------------------------------
1970 This entrypoint provides the \fB--checklist\fP or \fB--radiolist\fP
1971 functionality without the limitations of \fB\*p\fP's command-line syntax
1972 (compare to \fBdialog_checklist\fP).
1974 .B const char * \fItitle
1975 is the title string to display at the top of the widget.
1977 .B const char * \fIcprompt
1978 is the prompt text shown within the widget.
1981 is the desired height of the box.
1982 If zero, the height is adjusted to use the available screen size.
1985 is the desired width of the box.
1986 If zero, the height is adjusted to use the available screen size.
1988 .B int \fIlist_height
1989 is the minimum height to reserve for displaying the list.
1990 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1993 is the number of \fIitems\fP.
1995 .B DIALOG_LISTITEM * \fIitems
1996 This is a list of the items to display in the checklist.
1998 .B const char * \fIstates
1999 This is a list of characters to display for the given states.
2000 Normally a checklist provides true (1) and false (0) values,
2001 which the widget displays as "*" and space, respectively.
2002 An application may set this parameter to an arbitrary null-terminated string.
2003 The widget determines the number of states from the length of this string,
2004 and will cycle through the corresponding display characters as the user
2005 presses the space-bar.
2008 This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP,
2009 depending on whether the widget should act as a checklist or radiobox.
2011 .B int * \fIcurrent_item
2012 The widget sets the referenced location to the index of the current display
2013 item (cursor) when it returns.
2014 .\" ---------------------------------------------------------------------------
2015 .SS dlg_check_scrolled
2016 given a function key (or other key that was mapped to a function key),
2017 check if it is one of the up/down scrolling functions:
2034 Some widgets use these key bindings for scrolling the prompt-text up and
2035 down, to allow for display in very small windows.
2037 The function returns 0 (zero) if it finds one of these keys,
2041 is the function-key to check
2044 is the number of lines
2045 which would be used to display the scrolled prompt in
2046 an arbitrarily tall window.
2047 It is used here to check limits for the \fIoffset\fP value.
2050 this is the available height for writing scrolled text,
2051 which is smaller than the window if it contains buttons.
2054 on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay
2058 on entry, holds the starting line number (counting from zero)
2059 last used for \fBdlg_print_scrolled\fP.
2060 On return, holds the updated starting line number.
2061 .\" ---------------------------------------------------------------------------
2063 Set window to the default \fB\*p\fP screen attribute.
2064 This is set in the rc-file with \fBscreen_color\fP.
2065 .\" ---------------------------------------------------------------------------
2067 Free storage used for the result buffer (\fBdialog_vars.input_result\fP).
2068 The corresponding pointer is set to NULL.
2069 .\" ---------------------------------------------------------------------------
2071 Return the number of colors that can be configured in \fB\*p\fP.
2072 .\" ---------------------------------------------------------------------------
2074 Initialize the color pairs used in \fB\*p\fP.
2075 .\" ---------------------------------------------------------------------------
2077 Count the entries in an argument vector.
2080 Points to the argument vector.
2081 .\" ---------------------------------------------------------------------------
2082 .SS dlg_count_columns
2083 Returns the number of columns used for a string.
2084 This is not necessarily the number of bytes in a string.
2086 .B const char * \fIstring
2087 is the string to measure.
2088 .\" ---------------------------------------------------------------------------
2089 .SS dlg_count_real_columns
2090 Returns the number of columns used for a string,
2091 accounting for "\eZ" sequences which can be used for
2092 coloring the text if \fBdialog_vars.colors\fP is set.
2093 This is not necessarily the number of bytes in a string.
2095 .B const char * \fIstring
2096 is the string to measure.
2097 .\" ---------------------------------------------------------------------------
2098 .SS dlg_count_wchars
2099 Returns the number of wide-characters in the string.
2101 .B const char * \fIstring
2102 is the string to measure.
2103 .\" ---------------------------------------------------------------------------
2105 Create a configuration file,
2106 i.e., write internal tables to a file which can be read back by \fB\*p\fP
2109 .B const char * \fIfilename
2110 is the name of the file to write to.
2111 .\" ---------------------------------------------------------------------------
2113 If \fBdialog_vars.size_err\fP is true,
2114 check if the given window size is too large to fit on the screen.
2115 If so, exit with an error reporting the size of the window.
2118 is the window's height
2121 is the window's width
2122 .\" ---------------------------------------------------------------------------
2123 .SS dlg_default_button
2124 If \fBdialog_vars.default_button\fP is positive,
2125 return the button-index for that button code,
2126 using \fBdlg_ok_buttoncode\fP to test indices starting with zero.
2127 Otherwise (or if no match was found for the button code), return zero.
2128 .\" ---------------------------------------------------------------------------
2129 .SS dlg_default_formitem
2130 If \fBdialog_vars.default_item\fP is not null,
2131 find that name by matching the \fIname\fP field in the list of form \fIitems\fP.
2132 If found, return the index of that item in the list.
2133 Otherwise, return zero.
2135 .B DIALOG_FORMITEM * \fIitems
2136 is the list of items to search.
2137 It is terminated by an entry with a null \fIname\fP field.
2138 .\" ---------------------------------------------------------------------------
2139 .SS dlg_default_item
2140 This function is obsolete, provided for library-compatibility.
2141 It is replaced by \fBdlg_default_formitem\fP and \fBdlg_default_listitem\fP.
2144 is the list of items to search.
2147 is the number of items in each group, e.g., the second array index.
2148 .\" ---------------------------------------------------------------------------
2149 .SS dlg_defaultno_button
2150 If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not,
2151 find the button-index for the \*(``Cancel\*('' button.
2152 Otherwise, return the index for \*(``OK\*('' (always zero).
2153 .\" ---------------------------------------------------------------------------
2155 Remove a window, repainting everything else.
2158 is the window to remove.
2159 .\" ---------------------------------------------------------------------------
2161 This is called each time a widget is invoked which may do output.
2162 It increments \fBdialog_state.output_count\fP,
2163 so the output function in \fB\*p\fP can test this and add a separator.
2164 .\" ---------------------------------------------------------------------------
2166 Draw up/down arrows on a window, e.g., for scrollable lists.
2167 It calls \fBdlg_draw_arrows2\fP using the
2168 \fImenubox_color\fP and \fImenubox_border_color\fP attributes.
2170 .B WINDOW * \fIdialog
2171 is the window on which to draw an arrow.
2174 is true if an up-arrow should be drawn at the top of the window.
2176 .B int \fIbottom_arrow
2177 is true if an down-arrow should be drawn at the bottom of the window.
2180 is the zero-based column within the window on which to draw arrows.
2183 is the zero-based row within the window on which to draw up-arrows
2184 as well as a horizontal line to show the window's top.
2187 is the zero-based row within the window on which to draw down-arrows
2188 as well as a horizontal line to show the window's bottom.
2189 .\" ---------------------------------------------------------------------------
2190 .SS dlg_draw_arrows2
2191 Draw up/down arrows on a window, e.g., for scrollable lists.
2193 .B WINDOW * \fIdialog
2194 is the window on which to draw an arrow.
2197 is true if an up-arrow should be drawn at the top of the window.
2199 .B int \fIbottom_arrow
2200 is true if an down-arrow should be drawn at the bottom of the window.
2203 is the zero-based column within the window on which to draw arrows.
2206 is the zero-based row within the window on which to draw up-arrows
2207 as well as a horizontal line to show the window's top.
2210 is the zero-based row within the window on which to draw down-arrows
2211 as well as a horizontal line to show the window's bottom.
2214 is the window's background attribute.
2216 .B chtype \fIborderattr
2217 is the window's border attribute.
2218 .\" ---------------------------------------------------------------------------
2219 .SS dlg_draw_bottom_box
2220 Draw a partial box at the bottom of a window,
2221 e.g., to surround a row of buttons.
2222 It is designed to merge with an existing box around
2223 the whole window (see \fBdlg_draw_box\fP),
2224 so it uses tee-elements rather than corner-elements
2225 on the top corners of this box.
2228 is the window to update.
2229 .\" ---------------------------------------------------------------------------
2230 .SS dlg_draw_bottom_box2
2231 Draw a partial box at the bottom of a window,
2232 e.g., to surround a row of buttons.
2233 It is designed to merge with an existing box around
2234 the whole window (see \fBdlg_draw_box2\fP),
2235 so it uses tee-elements rather than corner-elements
2236 on the top corners of this box.
2239 is the window to update.
2241 .B chtype \fIon_left
2242 is used to color the upper/left edges of the box, i.e., the tee-element and
2245 .B chtype \fIon_right
2246 is used to color the right edge of the box, i.e., the tee-element
2248 .B chtype \fIon_inside
2249 is used to fill-color the inside of the box
2250 .\" ---------------------------------------------------------------------------
2252 Draw a rectangular box with line drawing characters.
2255 is the window to update.
2258 is the top row of the box.
2261 is the left column of the box.
2264 is the height of the box.
2267 is the width of the box.
2269 .B chtype \fIboxchar
2270 is used to color the right/lower edges.
2271 It also is fill-color used for the box contents.
2273 .B chtype \fIborderchar
2274 is used to color the upper/left edges.
2275 .\" ---------------------------------------------------------------------------
2277 Draw a rectangular box with line drawing characters.
2280 is the window to update.
2283 is the top row of the box.
2286 is the left column of the box.
2289 is the height of the box.
2292 is the width of the box.
2294 .B chtype \fIboxchar
2295 is used to fill-color for the box contents.
2297 .B chtype \fIborderchar
2298 is used to color the upper/left edges.
2300 .B chtype \fIborderchar2
2301 is used to color the right/lower edges.
2302 .\" ---------------------------------------------------------------------------
2303 .SS dlg_draw_buttons
2304 Print a list of buttons at the given position.
2307 is the window to update.
2310 is the starting row.
2313 is the starting column.
2315 .B const char ** \fIlabels
2316 is a list of (pointers to) button labels terminated by a null pointer.
2319 is the index within the list of the selected button.
2322 is true if the buttons are arranged in a column rather than a row.
2325 is the number of columns (or rows if \fIvertical\/\fP) allowed for the display.
2326 .\" ---------------------------------------------------------------------------
2327 .SS dlg_draw_helpline
2328 draw the text in \fBdialog_vars.help_line\fP at the bottom of the given window.
2330 .B WINDOW * \fIdialog
2331 is the window to modify.
2333 .B bool \fIdecorations
2334 if true, allow room for the scrolling arrows.
2335 .\" ---------------------------------------------------------------------------
2336 .SS dlg_draw_scrollbar
2337 If \fBdialog_state.use_scrollbar\fP is set,
2338 draw a scrollbar on the right margin of windows holding scrollable data.
2339 Also (whether or not the scrollbar is drawn),
2340 annotate the bottom margin of the window with the percentage of data
2341 by the bottom of that window,
2342 and call \fBdlg_draw_arrows2\fP to put markers on the window showing
2343 when more data is available.
2346 is the window in which the data is scrolled.
2347 Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP
2348 are passed as parameters, this window can contain additional data.
2350 .B long \fIfirst_data
2351 is the zero-based index to the first row of data in the current window.
2353 .B long \fIthis_data
2354 is the zero-based index to the current row of data.
2356 .B long \fInext_data
2357 is the zero-based index to the next data after the current row.
2359 .B long \fItotal_data
2360 is the total number of rows of data.
2363 is the zero-based left margin/column of the window.
2364 The up/down arrows are draw inset by 5 columns from this point.
2367 is the zero-based right margin/column of the window.
2368 The scrollbar is drawn flush against this column.
2371 is the zero-based row within the window on which to draw up-arrows
2372 as well as a horizontal line to show the window's top.
2375 is the zero-based row within the window on which to draw down-arrows
2376 as well as a horizontal line to show the window's bottom.
2379 is the window's background attribute.
2381 .B chtype \fIborderattr
2382 is the window's border attribute.
2383 .\" ---------------------------------------------------------------------------
2385 Draw shadows along the right and bottom edge of a window to give it
2386 a 3-dimensional look.
2387 (The height, etc., may not be the same as the window's actual values).
2390 is the window to update.
2393 is the height of the window.
2396 is the width of the window.
2399 is the top row of the window.
2402 is the left column of the window.
2403 .\" ---------------------------------------------------------------------------
2405 Draw a title centered at the top of the window.
2408 is the window to update.
2410 .B const char * \fItitle
2411 is the title string to display at the top of the widget.
2412 .\" ---------------------------------------------------------------------------
2413 .SS dlg_dummy_menutext
2414 This is a utility function which supports the \fB--inputmenu\fP option of
2415 the \fB\*p\fP program.
2416 If \fBdialog_vars.input_menu\fP is set, \fBdialog_menu\fP passes this
2417 pointer to \fBdlg_menu\fP as the \fIrename_menutext\fP parameter.
2418 Otherwise, it passes \fBdlg_dummy_menutext\fP.
2420 The function should only return \fBDLG_EXIT_ERROR\fP.
2422 .B DIALOG_LISTITEM * \fIitems
2423 is the list of menu items
2426 is the index of the currently-selected item
2428 .B char * \fInewtext
2429 is the updated text for the menu item
2430 .\" ---------------------------------------------------------------------------
2432 Write all user-defined key-bindings to the given stream,
2433 e.g., as part of \fBdlg_create_rc\fP.
2436 is the stream on which to write the bindings.
2437 .\" ---------------------------------------------------------------------------
2438 .SS dlg_dump_window_keys
2439 Write all user-defined key-bindings to the given stream,
2440 e.g., as part of \fBdlg_create_rc\fP.
2443 is the stream on which to write the bindings.
2446 is the window for which bindings should be dumped.
2447 If it is null, then only built-in bindings are dumped.
2448 .\" ---------------------------------------------------------------------------
2450 Remove one or more items from an argument vector.
2453 in/out parameter giving the length of the argument vector.
2454 .B char *** \fIargvp
2455 in/out parameter pointing to the argument vector.
2459 number of arguments to remove.
2460 .\" ---------------------------------------------------------------------------
2462 Given the character-offset in the string,
2463 returns the display-offset where
2464 \fB\*p\fP should position the cursor.
2465 In this context, \*(``characters\*('' may be multicolumn,
2466 since the string can be a multibyte character string.
2469 is the string to analyze
2472 is the character-offset
2475 is a limit on the column positions that can be used,
2476 e.g., the window's size.
2477 .\" ---------------------------------------------------------------------------
2479 Updates the string and character-offset, given various editing characters
2480 or literal characters which are inserted at the character-offset.
2481 Returns true if an editing change was made (and the display should
2482 be updated), and false if the key was something like \fBKEY_ENTER\fP,
2483 which is a non-editing action outside this function.
2486 is the (multibyte) string to update
2489 is the character-offset
2495 is true if the editing key is a function-key
2498 is used in a special loop case by calling code to force the return
2499 value of this function when a function-key code 0 is passed in.
2500 .\" ---------------------------------------------------------------------------
2502 Given an internal exit code,
2503 check if the corresponding environment variable is set.
2504 If so, remap the exit code to match the environment variable.
2505 Finally call \fBexit\fP with the resulting exit code.
2508 is the internal exit code, e.g., \fBDLG_EXIT_OK\fP,
2509 which may be remapped.
2511 The \fB\*p\fP program uses this function
2512 to allow shell scripts to remap the exit codes so they can distinguish ESC
2514 .\" ---------------------------------------------------------------------------
2516 Returns the name of an exit-code, e.g.,
2517 \*(``OK\*('' for \fBDLG_EXIT_OK\fP.
2520 is an exit-code for \fB\*p\fP as defined in \fB<\*p.h>\fP.
2521 .\" ---------------------------------------------------------------------------
2523 Returns an exit-code as the reverse of \fBdlg_exitcode2n\fP, e.g.,
2524 0 (\fBDLG_EXIT_OK\fP) for the \*(``OK\*('' string.
2526 .B const char * \fIname
2527 is the name of an exit-code for \fB\*p\fP as defined in \fB<\*p.h>\fP
2528 but omitting the \*(``DLG_EXIT_\*('' prefix.
2529 .\" ---------------------------------------------------------------------------
2530 .SS dlg_exit_buttoncode
2531 Map the given button index for \fBdlg_exit_label\fP into \fB\*p\fP's exit-code.
2535 .\" ---------------------------------------------------------------------------
2537 Return a list of button labels.
2538 If \fBdialog_vars.extra_button\fP is true,
2539 return the result of \fBdlg_ok_labels\fP.
2540 Otherwise, return a list with the \*(``Exit\*('' label
2541 and (if \fBdialog_vars.help_button\fP is set)
2542 the \*(``Help\*('' button as well.
2543 .\" ---------------------------------------------------------------------------
2545 Quit program killing all \fBtailboxbg\fP widgets.
2547 .B const char * \fIfmt
2548 is the format of the \fBprintf\fP-like message to write.
2552 are the variables to apply to the \fIfmt\fP format.
2553 .\" ---------------------------------------------------------------------------
2555 Given the character-offset to find in the list, return the corresponding
2558 .B const int *\fIlist
2559 contains a list of character-offsets,
2560 i.e., indices into a string that denote the beginning of multibyte characters.
2563 is the last index into \fBlist\fP to search.
2566 is the character-offset to find.
2567 .\" ---------------------------------------------------------------------------
2568 .SS dlg_finish_string
2569 If \fIDIALOG_STATE.finish_string\fP is true,
2570 this function discards data used to speed up layout computations.
2572 .B const char * \fIstring
2573 is the address of the string whose data should be discarded.
2574 The address rather than contents is used as the unique identifier because
2575 some of the caching is used for editable input-fields.
2576 .\" ---------------------------------------------------------------------------
2578 Cancel the local data saved by \fBdlg_last_getc\fP.
2579 .\" ---------------------------------------------------------------------------
2581 This entrypoint provides the \fB--editbox\fP
2582 functionality without the limitations of \fB\*p\fP's command-line syntax
2583 (compare to \fBdialog_editbox\fP).
2585 .B const char * \fItitle
2586 is the title string to display at the top of the widget.
2589 is a pointer to an array of \fBchar\ *\fP pointers.
2590 The array is allocated by the caller,
2591 and so are the strings to which it points.
2592 The \fBdlg_editbox\fP function may reallocate the
2593 array and the strings.
2596 points to the nominal length of \fIlist\fP.
2597 The referenced value is updated if\fIlist\fP is reallocated.
2600 is the desired height of the box.
2601 If zero, the height is adjusted to use the available screen size.
2604 is the desired width of the box.
2605 If zero, the height is adjusted to use the available screen size.
2606 .\" ---------------------------------------------------------------------------
2608 This entrypoint provides the \fB--form\fP
2609 functionality without the limitations of \fB\*p\fP's command-line syntax
2610 (compare to \fBdialog_form\fP).
2612 .B const char * \fItitle
2613 is the title string to display at the top of the widget.
2615 .B const char * \fIcprompt
2616 is the prompt text shown within the widget.
2619 is the desired height of the box.
2620 If zero, the height is adjusted to use the available screen size.
2623 is the desired width of the box.
2624 If zero, the height is adjusted to use the available screen size.
2626 .B int \fIform_height
2627 is the minimum height to reserve for displaying the list.
2628 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2631 is the number of \fIitems\fP.
2633 .B DIALOG_FORMITEM * \fIitems
2634 This is a list of the items to display in the form.
2636 .B int * \fIcurrent_item
2637 The widget sets the referenced location to the index of the current display
2638 item (cursor) when it returns.
2639 .\" ---------------------------------------------------------------------------
2640 .SS dlg_free_columns
2641 Free data allocated by \fBdlg_align_columns\fP.
2644 This is the array which was reformatted.
2645 It points to the first string to free.
2648 This is the size of the struct for each row of the array.
2651 This is the number of rows in the array.
2652 .\" ---------------------------------------------------------------------------
2653 .SS dlg_free_formitems
2654 Free memory owned by a list of DIALOG_FORMITEM's.
2656 .B DIALOG_FORMITEM * \fIitems
2657 is the list to free.
2658 .\" ---------------------------------------------------------------------------
2660 Remove the gauge widget from the screen and free its associated memory.
2663 points to the gauge widget.
2664 .\" ---------------------------------------------------------------------------
2666 Read a character from the given window.
2667 Handle repainting here (to simplify
2668 things in the calling application).
2669 Also, if input-callback(s) are set up,
2670 poll the corresponding files and handle the updates,
2671 e.g., for displaying a tailbox.
2672 Returns the key-code.
2675 is the window within which to read.
2678 as a side-effect, set this to true if the key-code is really a function-key.
2679 .\" ---------------------------------------------------------------------------
2681 extract the video attributes from the given window.
2684 is the window from which to get attributes.
2685 .\" ---------------------------------------------------------------------------
2686 .SS dlg_getc_callbacks
2687 passes the given key-code \fIch\fP to the current window that
2688 has established a callback.
2689 If the callback returns zero, remove it and try the next window.
2690 If no more callbacks remain, return.
2691 If any callbacks were found, return true, otherwise false.
2697 is true if the key is a function-key
2700 is used to pass an exit-code to the caller,
2701 which should pass that via \fBdlg_exit\fP.
2702 .\" ---------------------------------------------------------------------------
2703 .SS dlg_index_columns
2704 Build a list of the display-columns for the given multibyte string's characters.
2706 .B const char * \fIstring
2707 is the string to analyze
2708 .\" ---------------------------------------------------------------------------
2709 .SS dlg_index_wchars
2710 Build an index of the wide-characters in the string,
2711 so the caller can easily tell
2712 which byte-offset begins a given wide-character.
2714 .B const char * \fIstring
2715 is the string to analyze
2716 .\" ---------------------------------------------------------------------------
2718 Draw the string for the \fBdialog_vars.item_help\fP feature.
2720 .B const char * \fItxt
2722 .\" ---------------------------------------------------------------------------
2724 If \fB\*p\fP has callbacks active,
2725 purge the list of all that are not marked
2726 to keep in the background.
2727 If any remain, run those in a background process.
2730 stores the exit-code to pass back to the caller.
2731 .\" ---------------------------------------------------------------------------
2733 returns the most recent character that was read via \fBdlg_getc\fP.
2734 .\" ---------------------------------------------------------------------------
2735 .SS dlg_limit_columns
2736 Given a column limit,
2737 count the number of wide characters that can fit into that limit.
2738 The offset is used to skip over a leading character
2739 that was already written.
2741 .B const char * \fIstring
2742 is the string to analyze
2748 is the starting offset from which analysis should continue
2749 .\" ---------------------------------------------------------------------------
2751 Check for a key-binding.
2752 If there is no binding associated with the widget, it simply returns
2753 the given curses-key.
2754 Otherwise, it returns the result of the binding
2757 is the window on which the binding is checked
2759 .B int \fIcurses_key
2760 is the curses key-code
2762 .B int * \fIdialog_key
2763 is the corresponding \fB\*p\fP internal code
2764 (see \fBDLG_KEYS_ENUM\fP in dlg_key.h).
2765 .\" ---------------------------------------------------------------------------
2767 Limit the parameter according to \fBdialog_vars.max_input\fP
2770 is the value to limit
2771 .\" ---------------------------------------------------------------------------
2773 Match a given character against the beginning of the string,
2774 ignoring case of the given character.
2775 The matching string must begin with an uppercase character.
2778 is the character to check
2780 .B const char * \fIstring
2781 is the string to search
2782 .\" ---------------------------------------------------------------------------
2784 This entrypoint provides the \fB--menu\fP
2785 functionality without the limitations of \fB\*p\fP's command-line syntax
2786 (compare to \fBdialog_menu\fP).
2788 .B const char * \fItitle
2789 is the title string to display at the top of the widget.
2791 .B const char * \fIcprompt
2792 is the prompt text shown within the widget.
2795 is the desired height of the box.
2796 If zero, the height is adjusted to use the available screen size.
2799 is the desired width of the box.
2800 If zero, the height is adjusted to use the available screen size.
2802 .B int \fImenu_height
2803 is the minimum height to reserve for displaying the list.
2804 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2807 is the number of \fIitems\fP.
2809 .B DIALOG_LISTITEM * \fIitems
2810 This is a list of the items to display in the form.
2812 .B int * \fIcurrent_item
2813 The widget sets the referenced location to the index of the current display
2814 item (cursor) when it returns.
2816 .B DIALOG_INPUTMENU \fIrename_menutext
2817 If this is not \fBdlg_dummy_menutext\fP,
2818 the widget acts like an \fIinputmenu\fP widget,
2819 providing an extra \*(``Rename\*('' button,
2820 which activates an edit feature on the selected menu item.
2821 .\" ---------------------------------------------------------------------------
2823 Moves/resizes the given window to the given position and size.
2826 is the window to move/resize.
2828 .B WINDOW *\fIheight
2829 is the height of the resized window.
2832 is the width of the resized window.
2835 y-ordinate to use for the repositioned window.
2838 x-ordinate to use for the repositioned window.
2839 .\" ---------------------------------------------------------------------------
2840 .SS dlg_mouse_bigregion
2841 Retrieve the big-region under the pointer.
2844 is the row on which the mouse click occurred
2847 is the column on which the mouse click occurred
2848 .\" ---------------------------------------------------------------------------
2849 .SS dlg_mouse_free_regions
2850 Free the memory associated with mouse regions.
2851 .\" ---------------------------------------------------------------------------
2852 .SS dlg_mouse_mkbigregion
2853 Creates a region on which the mouse-clicks will return a specified code.
2856 is the top-row of the region.
2859 is the left-column of the region.
2862 is the height of the region.
2865 is the width of the region.
2868 is a code used to make the region unique within a widget
2871 is used in modes 2 (columns) and 3 (cells) to determine the width
2878 is used to determine how the mouse position is translated into
2879 a code (like a function-key):
2891 .\" ---------------------------------------------------------------------------
2892 .SS dlg_mouse_mkregion
2895 is the top-row of the region.
2898 is the left-column of the region.
2901 is the height of the region.
2904 is the width of the region.
2907 is a code used to make the region unique within a widget
2908 .\" ---------------------------------------------------------------------------
2909 .SS dlg_mouse_region
2910 Retrieve the frame under the mouse pointer
2913 is the row of the mouse-click
2916 is the column of the mouse-click
2917 .\" ---------------------------------------------------------------------------
2918 .SS dlg_mouse_setbase
2919 Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP,
2920 so they can make regions relative to the start of a given window.
2923 is the left-column for the base
2926 is the top-row for the base
2927 .\" ---------------------------------------------------------------------------
2928 .SS dlg_mouse_setcode
2929 Sets a value used internally by \fBdlg_mouse_mkregion\fP
2930 which is added to the \fIcode\fP parameter.
2931 By providing different values,
2932 e.g., multiples of \fBKEY_MAX\fP,
2933 it is possible to support multiple \*(``big\*('' regions in a widget.
2934 The \fIbuildlist\fP widget uses this feature to recognize mouse-clicks
2935 in the left/right panes.
2938 is the value to add to \fBdlg_mouse_mkregion\fP's \fIcode\fP parameter.
2939 .\" ---------------------------------------------------------------------------
2940 .SS dlg_mouse_wgetch
2941 is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks
2942 (if the curses library supports those) into extended function-keys
2943 which encode the position according to the \fImode\fP in
2944 \fBdlg_mouse_mkbigregion\fP.
2945 Returns the corresponding key-code.
2948 is the window on which to perform the input
2951 the referenced location is set to true if the key-code is an actual
2952 or extended (mouse) function-key.
2953 .\" ---------------------------------------------------------------------------
2954 .SS dlg_mouse_wgetch_nowait
2955 This is a non-blocking variant of \fBdlg_mouse_wgetch\fP.
2958 is the window on which to perform the input
2961 the referenced location is set to true if the key-code is an actual
2962 or extended (mouse) function-key.
2963 .\" ---------------------------------------------------------------------------
2964 .SS dlg_need_separator
2965 Check if an output-separator is needed.
2966 If \fBdialog_vars.output_separator\fP is set, return true.
2967 Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true.
2968 If neither, return false.
2969 .\" ---------------------------------------------------------------------------
2970 .SS dlg_new_modal_window
2971 Create a modal window, optionally with a shadow.
2972 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2974 .B WINDOW * \fIparent
2975 is the parent window (usually the top-level window of a widget)
2978 is the window's height
2981 is the window's width
2984 is the window's top-row
2987 is the window's left-column
2988 .\" ---------------------------------------------------------------------------
2990 Create a window, optionally with a shadow.
2991 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2994 is the window's height
2997 is the window's width
3000 is the window's top-row
3003 is the window's left-column
3004 .\" ---------------------------------------------------------------------------
3006 Return the next index in the list of labels.
3008 .B const char ** \fIlabels
3009 is a list of (pointers to) button labels terminated by a null pointer.
3012 is the current button-index.
3013 .\" ---------------------------------------------------------------------------
3014 .SS dlg_next_ok_buttonindex
3015 Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons,
3016 find the next index in the list of buttons.
3019 is the current index in the list of buttons
3022 if negative, provides a way to enumerate extra active areas on the widget.
3023 .\" ---------------------------------------------------------------------------
3024 .SS dlg_ok_buttoncode
3025 Map the given button index for \fBdlg_ok_labels\fP
3026 into \fB\*p\fP's exit-code.
3029 is the button-index (which is not necessarily the same as the index
3030 in the list of labels).
3031 .\" ---------------------------------------------------------------------------
3032 .SS dlg_ok_button_key
3033 Calls \fBdlg_button_key\fP with the \*(``Cancel\*('' button disabled,
3034 e.g., for the textbox widget.
3035 .\" ---------------------------------------------------------------------------
3037 Returns a list with the \*(``Ok\*('' label,
3038 and if \fBdialog_vars.help_button\fP is true, the \*(``Help\*('' label as well.
3039 .\" ---------------------------------------------------------------------------
3041 Return a list of button labels for the OK/Cancel group of widgets.
3042 .\" ---------------------------------------------------------------------------
3044 Decode the string as an integer, decrement if greater than zero to make
3045 a curses-ordinate from a dialog-ordinate.
3046 .\" ---------------------------------------------------------------------------
3047 .SS dlg_parse_bindkey
3048 Parse the parameters of the \*(``bindkeys\*('' configuration-file entry.
3049 This expects widget name which may be "*", followed by curses key definition and
3050 then \fB\*p\fP key definition.
3053 is the parameter string to parse.
3054 .\" ---------------------------------------------------------------------------
3056 Parse the configuration file and set up variables.
3057 .\" ---------------------------------------------------------------------------
3059 Open a pipe which ties the standard error and output together.
3060 The \fBpopen\fP function captures only the standard output of a command.
3062 .B const char *\fIcommand
3063 The shell command to run.
3065 .B const char *\fItype
3066 Like \fBpopen\fP, "r" is used to read, and "w" is used to write.
3067 .\" ---------------------------------------------------------------------------
3069 Return the previous index in the list of labels.
3071 .B const char ** \fIlabels
3072 is a list of (pointers to) button labels terminated by a null pointer.
3075 is the current button index
3076 .\" ---------------------------------------------------------------------------
3077 .SS dlg_print_listitem
3078 This is a helper function used for the various \*(``list\*('' widgets,
3079 e.g., checklist, menu, buildlist, treeview.
3080 Each list-widget has \*(``tag\*('' and \*(``description\*('' values
3081 for each item which can be displayed.
3082 If \fBdialog_vars.no_tags\fP is true,
3083 the \*(``tag\*('' value is not shown.
3084 The first character of the first value shown (tag or description)
3085 is highlighted to indicate that the widget will match it for quick navigation.
3088 the window in which to display the text
3090 .B const char *\fItext
3091 the value to display
3094 the number of columns available for printing the text
3097 true if this is the first call (for \*(``tag\*('' and \*(``description\*(''),
3098 and the first character of the value should be highlighted.
3101 nonzero if the text should be displayed using the \*(``selected\*('' colors
3102 .\" ---------------------------------------------------------------------------
3103 .SS dlg_print_scrolled
3104 This is a wrapper for \fBdlg_print_autowrap\fP which allows the user
3105 to scroll too-long prompt text up/down.
3107 See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP
3108 variable used as a parameter here.
3109 It complements this function; you need both.
3110 If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP
3111 parameter, needed for \fBdlg_check_scrolled\fP calls.
3114 is the window to update.
3116 .B const char * \fIprompt
3117 is the string to print
3120 is the starting line-number to write wrapped text.
3123 is the available height for writing the wrapped text
3126 is the width that the wrapping should occur in
3129 is true if the extra functionality for scrolling should be enabled.
3130 If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling.
3131 .\" ---------------------------------------------------------------------------
3133 Print one line of the prompt in the window within the limits of the
3134 specified right margin.
3135 The line will end on a word boundary and a pointer
3136 to the start of the next line is returned, or a NULL pointer if the end of
3140 is the window to update.
3143 holds the starting attributes, and is updated to reflect the final attributes
3144 applied to the string.
3146 .B const char *\fIprompt
3147 is the string to print
3156 returns the ending x-ordinate.
3157 .\" ---------------------------------------------------------------------------
3158 .SS dlg_prev_ok_buttonindex
3159 Find the previous button index in the list from \fBdlg_ok_labels\fP.
3162 is the current index
3165 if negative provides a way to enumerate extra active areas on the widget.
3166 .\" ---------------------------------------------------------------------------
3167 .SS dlg_print_autowrap
3168 Print a string of text in a window, automatically wrap around to the next
3169 line if the string is too long to fit on one line.
3170 Note that the string may contain embedded newlines.
3171 The text is written starting at the top of the window.
3174 is the window to update.
3176 .B const char * \fIprompt
3177 is the string to print
3180 is the nominal height the wrapped string is limited to
3183 is the width that the wrapping should occur in
3184 .\" ---------------------------------------------------------------------------
3186 If \fBdialog_vars.print_siz\fP is true,
3187 print the given height/width (from a widget)
3188 to \fBdialog_state.output\fP, e.g.,
3189 \fBSize: height, width\fP.
3192 is the window's height
3195 is the window's width
3196 .\" ---------------------------------------------------------------------------
3198 Print up to \fIcols\fP columns from \fBtext\fP,
3199 optionally rendering \fB\*p\fP's escape sequences for attributes and color.
3202 is the window to update.
3204 .B const char * \fItxt
3205 is the string to print
3211 holds the starting attributes, and is updated to reflect the final attributes
3212 applied to the string.
3213 .\" ---------------------------------------------------------------------------
3215 implements the "\fB--prgbox\fP" and "\fB--progressbox\fP" options.
3217 .B const char * \fItitle
3218 is the title on the top of the widget.
3220 .B const char * \fIcprompt
3221 is the prompt text shown within the widget.
3222 If empty or null, no prompt is shown.
3225 is the desired height of the box.
3226 If zero, the height is based on the screen size.
3229 is the desired width of the box.
3230 If zero, the height is based on the screen size.
3233 if true, an \*(``OK\*('' button will be shown,
3234 and the dialog will wait for it to complete.
3235 With an \*(``OK\*('' button, it is denoted a \*(``programbox\*('',
3236 without an \*(``OK\*('' button, it is denoted a \*(``progressbox\*(''.
3239 is the file pointer, which may be a pipe or a regular file.
3240 .\" ---------------------------------------------------------------------------
3241 .SS dlg_put_backtitle
3242 Display the background title if \fBdialog_vars.backtitle\fP is non-null.
3243 The background title is shown at the top of the screen.
3244 .\" ---------------------------------------------------------------------------
3245 .SS dlg_reallocate_gauge
3246 Allocates or reallocates a gauge widget (see \fBdlg_allocate_gauge\fP).
3247 Use \fBdlg_update_gauge\fP to display the result.
3249 .B void ** \fIobjptr
3250 If the pointer referenced by this parameter is null, the function creates
3251 a new gauge widget using \fBdlg_allocate_gauge\fP.
3252 Otherwise, it updates the title and cprompt values, reusing the window
3253 from the previous call on this function.
3254 As a side-effect, the function stores the updated object-pointer via
3255 the \fIobjptr\fP parameter.
3257 .B const char * \fItitle
3258 is the title string to display at the top of the widget.
3260 .B const char * \fIcprompt
3261 is the prompt text shown within the widget.
3264 is the desired height of the box.
3265 If zero, the height is adjusted to use the available screen size.
3268 is the desired width of the box.
3269 If zero, the height is adjusted to use the available screen size.
3272 is the percentage to show in the progress bar.
3273 .\" ---------------------------------------------------------------------------
3274 .SS dlg_register_buttons
3275 The widget developer should call this function after \fBdlg_register_window\fP,
3276 for the list of button labels associated with the widget.
3277 One may bind a key to a button, e.g., \*(``OK\*('' for \fBDLGK_OK\fP,
3280 is the window with which to associate the buttons
3282 .B const char * \fIname
3283 is the widget's binding name (usually the name of the widget).
3285 .B const char ** \fIbuttons
3286 is the list of buttons
3287 .\" ---------------------------------------------------------------------------
3288 .SS dlg_register_window
3289 For a given named widget's window, associate a binding table.
3292 is the window with which to associate the buttons
3294 .B const char * \fIname
3295 is the widget's binding name (usually the name of the widget).
3297 .B DLG_KEYS_BINDING * \fIbinding
3298 is the binding table
3299 .\" ---------------------------------------------------------------------------
3300 .SS dlg_remove_callback
3303 .B DIALOG_CALLBACK * \fIp
3304 contains the callback information.
3305 .\" ---------------------------------------------------------------------------
3306 .SS dlg_renamed_menutext
3307 This is a utility function which supports the \fB--inputmenu\fP option of
3308 the \fB\*p\fP program.
3309 If \fBdialog_vars.input_menu\fP is set, \fBdialog_menu\fP passes this
3310 pointer to \fBdlg_menu\fP as the \fIrename_menutext\fP parameter.
3311 Otherwise, it passes \fBdlg_dummy_menutext\fP.
3313 The function should add \*(``RENAMED\*('' to \fBdialog_vars.input_result\fP ,
3314 followed by the menu item's name and the \fInewtext\fP value
3315 (with a space separating the three items),
3316 and return \fBDLG_EXIT_EXTRA\fP.
3318 .B DIALOG_LISTITEM * \fIitems
3319 is the list of menu items
3322 is the index of the currently-selected item
3324 .B char * \fInewtext
3325 is the updated text for the menu item
3326 .\" ---------------------------------------------------------------------------
3327 .SS dlg_reset_timeout
3328 Calls \fBwtimeout\fP with the value saved for a window in the
3329 last call to \fBdlg_set_timeout\fP.
3330 .\" ---------------------------------------------------------------------------
3331 .SS dlg_restore_vars
3332 Restore \fB\*p\fP's variables from the given variable
3333 (see \fBdialog_save_vars\fP).
3335 .B DIALOG_VARS * \fIsave
3336 is the variable from which to restore.
3339 \fIDIALOG_VARS.input_length\fP and
3340 \fIDIALOG_VARS.input_result\fP members are treated specially,
3341 since these are used by a widget to pass data to the caller.
3342 They are not modified by this function.
3343 .\" ---------------------------------------------------------------------------
3345 Test a \fB\*p\fP internal keycode to see if it corresponds to one of the push
3346 buttons on the widget such as \*(``OK\*(''.
3347 This is only useful if there are user-defined key bindings, since there are
3348 no built-in bindings that map directly to \fBDLGK_OK\fP, etc.
3349 Return true if a mapping was done.
3351 .B int \fIdialog_key
3352 is the \fB\*p\fP key to test
3355 is true if this is a function key
3358 store the result of the mapping in the referenced location.
3359 .\" ---------------------------------------------------------------------------
3361 Save \fB\*p\fP's variables into the given variable (see \fBdlg_restore_vars\fP).
3363 .B DIALOG_VARS * \fIsave
3364 is the variable into which to save.
3365 .\" ---------------------------------------------------------------------------
3367 Set focus on the given window,
3368 making it display above other windows on the screen.
3370 .B WINDOW * \fIparent
3371 is the parent window (usually the top-level window of a widget)
3374 is the window on which to place focus (usually a subwindow of a widget)
3375 .\" ---------------------------------------------------------------------------
3377 Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP
3379 .B const char * \fIstring
3380 is the new contents for the result
3381 .\" ---------------------------------------------------------------------------
3383 Calls \fBwtimeout\fP to establish a preferred timeout for nonblocking
3384 reads, e.g., to allow the gauge widget to handle window-resizing events.
3385 The \fBdlg_may_resize\fP function temporarily overrides this value,
3386 to allow it to skip over the error codes returned while the ncurses
3387 library processes window-resizing events.
3388 It restores the value established in this call
3389 by calling \fBdlg_restore_timeout\fP.
3392 is the window whose input-timeout should be set
3394 .B bool \fIwill_getc
3395 is true if the widget is expected to read keyboard characters.
3396 Some (such as the gauge widget) do not.
3397 .\" ---------------------------------------------------------------------------
3399 Displays the string, shifted as necessary, to fit within the box and show
3400 the current character-offset.
3403 is the window within which to display
3405 .B const char * \fIstring
3406 is the string to display
3409 is the starting (character, not bytes) offset
3412 is the window attribute to use for the string
3415 beginning row on screen
3418 beginning column on screen
3421 number of columns on screen
3424 if true, do not echo input
3427 if true, force repaint
3428 .\" ---------------------------------------------------------------------------
3430 duplicate the string, like \fBstrdup\fP.
3432 .B const char * \fIcprompt
3433 is the string to duplicate
3434 .\" ---------------------------------------------------------------------------
3436 compare two strings, ignoring case.
3438 .B const char * \fIa
3441 .B const char * \fIb
3443 .\" ---------------------------------------------------------------------------
3444 .SS dlg_string_to_argv
3445 Convert a string to an argument vector
3446 returning an index (which must be freed by the caller).
3447 The string is modified:
3449 Blanks between arguments are replaced by nulls.
3451 Normally arguments are separated by blanks;
3452 however you can double-quote an argument to enclose blanks.
3453 The surrounding double-quotes are removed from the string.
3455 A backslash preceding a double-quote within double-quotes is removed.
3457 A backslash preceding a newline outside double-quotes is removed.
3459 Except for special cases, backslashes are preserved in the strings,
3460 since other \fB\*l\fP functions interpret backslashes, e.g., for colors.
3463 is the string to convert.
3464 .\" ---------------------------------------------------------------------------
3466 create a subwindow, e.g., for an input area of a widget
3469 is the parent window
3472 is the subwindow's height
3475 is the subwindow's width
3478 is the subwindow's top-row
3481 is the subwindow's left-column
3482 .\" ---------------------------------------------------------------------------
3483 .SS dlg_tab_correct_str
3484 If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces.
3485 Return the converted result.
3486 The caller is responsible for freeing the string.
3489 is the string to convert
3490 .\" ---------------------------------------------------------------------------
3492 If the parameter is non-null, opens a trace file with that
3493 name and stores the file pointer in \fBdialog_state.trace\fP.
3494 .\" ---------------------------------------------------------------------------
3496 logs a numeric value as a comment.
3499 is the name to log in the comment.
3502 is the value to log in the comment.
3503 .\" ---------------------------------------------------------------------------
3505 logs a string value as a comment.
3506 If the value contains embedded newlines,
3507 the comment is continued with \*(``#+\*('' markers.
3510 is the name to log in the comment.
3513 is the value to log in the comment.
3514 .\" ---------------------------------------------------------------------------
3516 If \fBdialog_state.trace\fP is set,
3517 translate the parameters into a printable representation,
3518 log it on a \*(``chr\*('' line.
3521 is the nominal keycode value.
3524 is nonzero if the value is really a function key.
3525 Some of these may be values declared in the DLG_KEYS_ENUM.
3526 .\" ---------------------------------------------------------------------------
3528 Write a formatted message to the trace file.
3530 .B const char * \fIfmt
3531 is the format of the \fBprintf\fP-like message to write.
3535 are the variables to apply to the \fIfmt\fP format.
3537 Use the DLG_TRACE macro for portability, in case the trace
3538 feature is not compiled into the library.
3539 It uses an extra level of parentheses to work with a variable number of
3542 DLG_TRACE(("this is dialog version %s\en", dialog_version()));
3544 .\" ---------------------------------------------------------------------------
3545 .SS dlg_trace_va_msg
3546 Write a formatted message to the trace file.
3548 .B const char *\fIfmt
3549 is the format of the \fBprintf\fP-like message to write.
3552 are the variables to apply to the \fIfmt\fP format.
3554 This is used in \fBdlg_exiterr\fP to capture error messages in the trace file:
3557 dlg_trace_msg("## Error: ");
3558 dlg_trace_va_msg(fmt, ap);
3562 Unlike \fBdlg_trace_msg\fP, an extra macro is not needed.
3563 .\" ---------------------------------------------------------------------------
3565 Returns the screensize without using curses.
3566 That allows the function to be used before initializing the screen.
3567 .\" ---------------------------------------------------------------------------
3569 If \fBdialog_state.trace\fP is set,
3570 log a printable picture of the given window.
3571 .\" ---------------------------------------------------------------------------
3573 This is an alternate interface to 'treeview' which allows the application
3574 to read the list item states back directly without putting them in the
3577 .B const char * \fItitle
3578 is the title on the top of the widget.
3580 .B const char * \fIcprompt
3581 is the prompt text shown within the widget.
3584 is the desired height of the box.
3585 If zero, the height is based on the screen size.
3588 is the desired width of the box.
3589 If zero, the height is based on the screen size.
3591 .B int \fIlist_height
3592 is the minimum height to reserve for displaying the list.
3593 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
3596 is the number of rows in \fIitems\fP.
3598 .B DIALOG_LISTITEM * \fIitems
3599 is the list of items, contain tag, name, and optionally help strings
3600 (if \fBdialog_vars.item_help\fP is set).
3601 The initial selection state for each item is also in this list.
3603 .B const char * \fIstates
3604 This is a list of characters to display for the given states.
3605 Normally a buildlist provides true (1) and false (0) values,
3606 which the widget displays as "*" and space, respectively.
3607 An application may set this parameter to an arbitrary null-terminated string.
3608 The widget determines the number of states from the length of this string,
3609 and will cycle through the corresponding display characters as the user
3610 presses the space-bar.
3613 This is a list of depths of each item in the tree.
3614 It is a separate parameter from \fIitems\fP to allow reuse of
3615 the existing functions.
3618 is either \fIFLAG_CHECK\fP, for checklists (multiple selections),
3619 or \fIFLAG_RADIO\fP for radiolists (a single selection).
3621 .B int * \fIcurrent_item
3622 The widget sets the referenced location to the index of the current display
3623 item (cursor) when it returns.
3624 .\" ---------------------------------------------------------------------------
3626 The \fB\*p\fP program uses this in each widget to adjust the
3628 which may contain the newline character (referred to as '\en')
3629 and/or the special substring "\en"
3630 (which can be translated into a newline character).
3632 There are several optional features:
3634 Unless \fBdialog_vars.nocollapse\fP is set,
3635 each tab is converted to a space before other processing.
3637 If \fBdialog_vars.no_nl_expand\fP is not set,
3638 and the string has "\en" substrings:
3641 The function changes embedded "\en" substrings to '\en' characters.
3643 The function preserves extra spaces after these substitutions.
3644 For instance, spaces following a newline (substring or character)
3645 are preserved to use as an indentation.
3647 If \fBdialog_vars.cr_wrap\fP is set,
3648 the function preserves '\en' newline characters.
3649 Otherwise, each '\en' newline character is converted to a space.
3652 Otherwise, if \fBdialog_vars.trim_whitespace\fP is set:
3655 This function strips all extra spaces to simplify justification.
3657 If \fBdialog_vars.cr_wrap\fP is set,
3658 the function preserves '\en' newline characters.
3659 Otherwise, each '\en' newline character is converted to a space.
3663 (if \fBdialog_vars.no_nl_expand\fP is set,
3664 or the string does not contain "\en" substrings,
3665 and \fBdialog_vars.trim_whitespace\fP is not set):
3668 Unless \fBdialog_vars.nocollapse\fP is set,
3669 sequences of spaces are reduced to a single space.
3673 is the string to trim
3674 .\" ---------------------------------------------------------------------------
3675 .SS dlg_unregister_window
3676 Remove the bindings for a given window.
3679 is the window from which to remove bindings
3680 .\" ---------------------------------------------------------------------------
3681 .SS dlg_update_gauge
3682 Update a gauge widget to show a different percentage value.
3685 points to the gauge object to update.
3688 is the new percentage value to display.
3689 .\" ---------------------------------------------------------------------------
3691 This filters out bursts of \fBKEY_RESIZE\fP values.
3692 Call this after \fBdlg_getc\fP returns \fBKEY_RESIZE\fP,
3693 to improve performance.
3694 .\" ---------------------------------------------------------------------------
3695 .SS dlg_yes_buttoncode
3696 Map the given button index for \fBdlg_yes_labels\fP into \fB\*p\fP's exit-code.
3700 .\" ---------------------------------------------------------------------------
3702 Return a list of buttons for Yes/No labels.
3703 .\" ---------------------------------------------------------------------------
3705 End use of \fB\*p\fP functions.
3706 .\" ---------------------------------------------------------------------------
3708 Do some initialization for \fB\*p\fP.
3711 is the real tty input of \fB\*p\fP.
3712 Usually it is the standard input, but if
3713 \fB--input-fd\fP option is used, it may be anything.
3716 is where \fB\*p\fP will send its result.
3717 Usually it is the standard error, but
3718 if \fB--stdout\fP or \fB--output-fd\fP is used, it may be anything.
3720 .\" ************************************************************************
3724 .\" ************************************************************************