2 .\" $Id: dialog.3,v 1.138 2021/01/17 18:02:44 tom Exp $
3 .\" Copyright 2005-2020,2021 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: 2021/01/17 18:02:44 $"
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 .\" ---------------------------------------------------------------------------
420 .SS .cursor_off_label
421 This corresponds to the command-line option "\fB\-\-cursor\-off\-label\fP".
422 If true, place the terminal cursor at the end of a button instead of
423 on the first character of the button label.
424 This is useful to reduce visual confusion when the cursor coloration
425 interacts poorly with the button-label text colors.
426 .\" ---------------------------------------------------------------------------
428 This corresponds to the command-line option
429 "\fB\-\-date\-format\fP \fIstring\/\fP".
430 If the host provides \fBstrftime\fP, and the value is nonnull,
431 the calendar widget uses this to format its output.
432 .\" ---------------------------------------------------------------------------
434 This is set by the command-line option "\fB\-\-default\-button\fP.
435 It is used by \fBdlg_default_button\fP.
436 .\" ---------------------------------------------------------------------------
438 This corresponds to the command-line option
439 "\fB\-\-default\-item\fP \fIstring\/\fP".
440 The given string is used as
441 the default item in a checklist, form or menu box.
442 Normally the first item in the box is the default.
443 .\" ---------------------------------------------------------------------------
445 This corresponds to the command-line option "\fB\-\-defaultno\fP".
447 make the default value of the
451 Likewise, treat the default button of widgets that provide
452 \*(``OK\*('' and \*(``Cancel\*(''
454 If \fB\-\-no\-cancel\fP was given that option overrides this,
455 making the default button always \*(``Yes\*(''
456 (internally the same as \*(``OK\*('').
457 .\" ---------------------------------------------------------------------------
458 .SS .dlg_clear_screen
459 This corresponds to the command-line option "\fB\-\-clear\fP".
460 This option is implemented in the main program, not the library.
462 the screen will be cleared on exit.
463 This may be used alone, without other options.
464 .\" ---------------------------------------------------------------------------
466 This corresponds to the command-line option "\fB\-\-erase\-on\-exit\fP".
467 If true, remove the dialog widget on program exit, erasing the entire
468 screen to its native background color, and place the terminal cursor
469 at the lower left corner of the screen.
470 This is useful for making the window contents invisible at the end of
471 a series of dialog boxes.
472 But it can also be used at earlier stages of a series of invocations
473 of \fB\*p\fP, if the series may be aborted before it is fully completed.
474 .\" ---------------------------------------------------------------------------
476 This corresponds to the command-line option "\fB\-\-exit\-label string\fP".
477 The given string overrides the label used for \*(``EXIT\*('' buttons.
478 .\" ---------------------------------------------------------------------------
480 This corresponds to the command-line option "\fB\-\-extra\-button\fP".
481 If true, some widgets show an extra button,
482 between \*(``OK\*('' and \*(``Cancel\*('' buttons.
483 .\" ---------------------------------------------------------------------------
485 This corresponds to the command-line option
486 "\fB\-\-extra\-label\fP \fIstring\/\fP".
487 The given string overrides the label used for \*(``Extra\*('' buttons.
488 Note: for inputmenu widgets, this defaults to \*(``Rename\*(''.
489 .\" ---------------------------------------------------------------------------
491 This is set by the command-line option "\fB\-\-passwordform\fP"
492 to tell the form widget that its text fields should be treated like
494 .\" ---------------------------------------------------------------------------
496 This corresponds to the command-line option "\fB\-\-help\-button\fP".
497 If true, some widgets show a help-button after
498 \*(``OK\*('' and \*(``Cancel\*('' buttons,
499 i.e., in checklist, radiolist and menu boxes.
500 If \fB\-\-item\-help\fR is also given, on exit
501 the return status will be the same as for the \*(``OK\*('' button,
502 and the item-help text will be written to \fB\*p\fP's output
503 after the token \*(``HELP\*(''.
504 Otherwise, the return status will indicate that the Help button was pressed,
505 and no message printed.
506 .\" ---------------------------------------------------------------------------
508 This corresponds to the command-line option "\fB\-\-hfile\fP \fIstring\/\fP".
509 The given filename is passed to \fBdialog_helpfile\fP when the user
511 .\" ---------------------------------------------------------------------------
513 This corresponds to the
514 command-line option "\fB\-\-help\-label\fP \fIstring\/\fP".
515 The given string overrides the label used for \*(``Help\*('' buttons.
516 .\" ---------------------------------------------------------------------------
518 This corresponds to the command-line option "\fB\-\-hline\fP \fIstring\/\fP".
519 The given string is displayed in the bottom of dialog windows,
521 .\" ---------------------------------------------------------------------------
523 This corresponds to the command-line option "\fB\-\-help\-status\fP".
524 If true, and the the help-button is selected,
525 writes the checklist or radiolist information
526 after the item-help \*(``HELP\*('' information.
527 This can be used to reconstruct the state of a checklist after processing
529 .\" ---------------------------------------------------------------------------
531 This corresponds to the command-line option "\fB\-\-help\-tags\fP".
533 \fBdlg_add_help_formitem\fP and
534 \fBdlg_add_help_listitem\fP use the item's tag value consistently
535 rather than using the tag's help-text value
536 when \fIDIALOG_VARS.item_help\fP is set.
537 .\" ---------------------------------------------------------------------------
539 This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated,
540 versus being a pointer to the user's local variables.
541 .\" ---------------------------------------------------------------------------
543 This flag is set to denote whether the menubox widget
544 implements a menu versus a inputmenu widget.
545 .\" ---------------------------------------------------------------------------
547 This may be either a user-supplied buffer,
548 or a buffer dynamically allocated by the library,
549 depending on \fIDIALOG_VARS.input_length\fP:
551 If \fIDIALOG_VARS.input_length\fP is zero,
552 this is a pointer to user buffer (on the stack, or static).
553 The buffer size is assumed to be \fBMAX_LEN\fP,
554 which is defined in \fI<\*l.h>\fP.
556 When \fIDIALOG_VARS.input_length\fP is nonzero,
557 this is a dynamically-allocated buffer used by the widgets to return
558 printable results to the calling application.
560 Certain widgets copy a result to this buffer.
561 If the pointer is NULL, or if the length is insufficient for
562 the result, then the \fB\*l\fP library allocates a buffer which is large enough,
563 and sets \fIDIALOG_VARS.input_length\fP.
564 Callers should check for this case if they have supplied their own buffer.
565 .\" ---------------------------------------------------------------------------
567 This corresponds to the command-line option "\fB\-\-insecure\fP".
568 If true, make the password widget friendlier but less secure,
569 by echoing asterisks for each character.
570 .\" ---------------------------------------------------------------------------
572 This variable is used to prevent \fBdialog_helpfile\fP from showing
573 anything, e.g., if F1 were pressed within a help-file display.
574 .\" ---------------------------------------------------------------------------
576 This corresponds to the command-line option "\fB\-\-iso\-week\fP".
577 It is used in the calendar widget to tell how
578 to compute the starting week for the year:
580 by default, the calendar treats January 1 as the first week of the year.
582 If this variable is true, the calendar uses ISO 8601's convention.
583 ISO 8601 numbers weeks starting with the first week in January with
584 a Thursday in the current year.
585 January 1 may be in the \fIprevious\fP year.
586 .\" ---------------------------------------------------------------------------
588 This corresponds to the command-line option "\fB\-\-item\-help\fP".
590 interpret the tags data for checklist, radiolist and menu boxes
591 adding a column whose text is displayed in the bottom line of the
592 screen, for the currently selected item.
593 .\" ---------------------------------------------------------------------------
595 This is set by the command-line option "\fB\-\-keep\-tite\fP"
596 to tell \fB\*p\fP to not attempt to cancel the terminal initialization
597 (termcap \fIti\/\fP/\,\fIte\/\fP) sequences
598 which correspond to xterm's alternate-screen switching.
599 Normally \fB\*p\fP does this to avoid flickering when run several times
601 .\" ---------------------------------------------------------------------------
603 This corresponds to the command-line option "\fB\-\-keep\-window\fP".
604 If true, do not remove/repaint the window on exit.
605 This is useful for keeping the window contents visible when several
606 widgets are run in the same process.
607 Note that curses will clear the screen when starting a new process.
608 .\" ---------------------------------------------------------------------------
610 This corresponds to the command-line option "\fB\-\-last\-key\fP".
611 .\" ---------------------------------------------------------------------------
613 This corresponds to the command-line option "\fB\-\-max\-input\fP \fIsize\/\fP".
614 Limit input strings to the given size.
615 If not specified, the limit is 2048.
616 .\" ---------------------------------------------------------------------------
618 This corresponds to the command-line option "\fB\-\-no\-hot\-list\fP".
628 for which the leading capital letter in each entry is accepted as a hot-key,
629 to quickly move the focus to that entry.
631 Setting this variable to TRUE disables the feature.
632 .\" ---------------------------------------------------------------------------
634 This corresponds to the command-line option "\fB\-\-no\-items\fP".
635 Some widgets (checklist, inputmenu, radiolist, menu) display a list
636 with two columns (a \*(``tag\*('' and \*(``item\*('',
637 i.e., \*(``description\*('').
638 This tells \fB\*p\fP to read shorter rows from data,
639 omitting the \*(``list\*(''.
640 .\" ---------------------------------------------------------------------------
642 This corresponds to the command-line
643 option "\fB\-\-no\-label\fP \fIstring\/\fP".
644 The given string overrides the label used for \*(``No\*('' buttons.
645 .\" ---------------------------------------------------------------------------
647 This corresponds to the command-line option "\fB\-\-no\-lines\fP.
648 It suppresses line-drawing.
649 See \fIDIALOG_VARS.ascii_lines\fP.
650 .\" ---------------------------------------------------------------------------
652 This corresponds to the command-line option "\fB\-\-no\-nl\-expand\fP".
653 If false, \fBdlg_trim_string\fP converts literal "\en" substrings
654 in a message into newlines.
655 .\" ---------------------------------------------------------------------------
657 This corresponds to the command-line option "\fB\-\-no\-tags\fP".
658 Some widgets (checklist, inputmenu, radiolist, menu) display a list
659 with two columns (a \*(``tag\*('' and \*(``item\*('',
660 also known as \*(``description\*('').
661 The tag is useful for scripting, but may not help the user.
662 The \fB\-\-no\-tags\fP option (from Xdialog) may be used to suppress the
663 column of tags from the display.
665 Normally \fB\*p\fP allows you to quickly move to entries on the displayed list,
666 by matching a single character to the first character of the tag.
667 When the \fB\-\-no\-tags\fP option is given, \fB\*p\fP matches against
668 the first character of the description.
669 In either case, the matchable character is highlighted.
671 Here is a table showing how the no_tags and no_items values interact:
676 Widget/Fields Shown/Fields Read/.no_items/.no_tags
678 buildlist/item/tag,item/0/0*
679 buildlist/item/tag,item/0/1
680 buildlist/tag/tag/1/0*
681 buildlist/tag/tag/1/1
682 checklist/tag,item/tag,item/0/0
683 checklist/item/tag,item/0/1
684 checklist/tag/tag/1/0
685 checklist/tag/tag/1/1
686 inputmenu/tag,item/tag,item/0/0
687 inputmenu/item/tag,item/0/1
688 inputmenu/tag/tag/1/0
689 inputmenu/tag/tag/1/1
690 menu/tag,item/tag,item/0/0
691 menu/item/tag,item/0/1
694 radiolist/tag,item/tag,item/0/0
695 radiolist/item/tag,item/0/1
696 radiolist/tag/tag/1/0
697 radiolist/tag/tag/1/1
698 treeview/item/tag,item/0/0*
699 treeview/item/tag,item/0/1
700 treeview/tag/tag/1/0*
706 Xdialog does not display the tag column for the analogous buildlist
707 and treeview widgets.
708 \fB\*L\fP does the same on the command-line.
709 However the library interface defaults to displaying the tag column.
710 Your application can enable or disable the tag column as needed for each widget.
711 .\" ---------------------------------------------------------------------------
713 This corresponds to the command-line option "\fB\-\-no\-cancel\fP".
715 suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes.
716 A script can still test if the user pressed the ESC key to cancel to quit.
717 .\" ---------------------------------------------------------------------------
719 This corresponds to the command-line option "\fB\-\-no\-collapse\fP".
720 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
721 spaces to a single space for text which is displayed in a message boxes, etc.
722 It true, that feature is disabled.
723 Note that \fB\*p\fR will still wrap text, subject to the \fB\-\-cr\-wrap\fR
725 .\" ---------------------------------------------------------------------------
727 This corresponds to the command-line option "\fB\-\-no\-ok\fP.
728 \fB\*L\fP will suppress the \*(``ok\*('' (or \*(``yes\*('') button
730 .\" ---------------------------------------------------------------------------
732 This corresponds to the command-line
733 option "\fB\-\-ok\-label\fP \fIstring\/\fP".
734 The given string overrides the label used for \*(``OK\*('' buttons.
735 .\" ---------------------------------------------------------------------------
737 When set, force \fBdlg_set_timeout\fP to use 10 milliseconds
738 rather than using the \fIDIALOG_VARS.timeout_secs\fP value.
739 .\" ---------------------------------------------------------------------------
741 This corresponds to the command-line option "\fB\-\-print\-size\fP".
743 each widget prints its size to \fB\*p\fP's output when it is invoked.
744 .\" ---------------------------------------------------------------------------
746 This corresponds to the command-line option "\fB\-\-quoted\fP.
747 Normally \fB\*p\fP quotes the strings returned by checklist's
748 as well as the item-help text.
749 If true, \fB\*p\fP will quote all string results.
750 .\" ---------------------------------------------------------------------------
752 This corresponds to the command-line option "\fB\-\-reorder\fP.
753 By default, the buildlist widget uses the same order for the output (right)
754 list as for the input (left).
755 If true, \fB\*p\fP will use the order in which a user adds selections
757 .\" ---------------------------------------------------------------------------
759 This corresponds to the command-line option "\fB\-\-separate\-output\fP".
761 checklist widgets output result one line at a time, with no quoting.
762 This facilitates parsing by another program.
763 .\" ---------------------------------------------------------------------------
765 This corresponds to the command-line option "\fB\-\-single\-quoted\fP".
767 use single-quoting as needed (and no quotes if unneeded) for the
768 output of checklist's as well as the item-help text.
769 If this option is not set, \fB\*p\fP uses double quotes around each item.
770 The latter requires occasional use of backslashes to make the output useful in
772 .\" ---------------------------------------------------------------------------
774 This corresponds to the command-line option "\fB\-\-size\-err\fP".
776 check the resulting size of a dialog box before trying to use it,
777 printing the resulting size if it is larger than the screen.
778 (This option is obsolete, since all new-window calls are checked).
779 .\" ---------------------------------------------------------------------------
781 This corresponds to the command-line option "\fB\-\-sleep\fP \fIsecs\/\fP".
782 This option is implemented in the main program, not the library.
783 If nonzero, this is the number of seconds after to delay
784 after processing a dialog box.
785 .\" ---------------------------------------------------------------------------
787 This corresponds to the command-line option "\fB\-\-tab-correct\fP".
788 If true, convert each tab character of the text to one or more spaces.
789 Otherwise, tabs are rendered according to the curses library's interpretation.
790 .\" ---------------------------------------------------------------------------
792 This corresponds to the command-line option
793 "\fB\-\-time\-format\fP \fIstring\/\fP".
794 If the host provides \fBstrftime\fP, and the value is nonnull,
795 the timebox widget uses this to format its output.
796 .\" ---------------------------------------------------------------------------
798 This corresponds to the command-line option "\fB\-\-timeout\fP \fIsecs\/\fP".
799 If nonzero, timeout input requests (exit with error code)
800 if no user response within the given number of seconds.
801 .\" ---------------------------------------------------------------------------
803 This corresponds to the command-line option "\fB\-\-title\fP \fItitle\/\fP".
806 string to be displayed at the top of the dialog box.
807 .\" ---------------------------------------------------------------------------
809 This corresponds to the command-line option "\fB\-\-trim\fP".
810 If true, eliminate leading blanks,
811 trim literal newlines and repeated blanks from message text.
812 .\" ---------------------------------------------------------------------------
814 This corresponds to the command-line option "\fB\-\-week\-start\fP".
815 It is used in the calendar widget to set the starting day for the week.
816 The string value can be
818 a number (0 to 6, Sunday through Saturday using POSIX) or
820 the special value \*(``locale\*('' (this works with systems using glibc,
821 providing an extension to the \fBlocale\fP command,
822 the \fBfirst_weekday\fP value).
824 a string matching one of the abbreviations for the day of the week
825 shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''.
826 .\" ---------------------------------------------------------------------------
828 This corresponds to the command-line
829 option "\fB\-\-yes\-label\fP \fIstring\/\fP".
830 The given string overrides the label used for \*(``Yes\*('' buttons.
832 .\" ************************************************************************
833 .\" ************************************************************************
835 Functions that implement major functionality for the command-line \fB\*p\fP
836 program, e.g., widgets, have names beginning "\fIdialog_\fP".
838 All dialog boxes have at least three parameters:
842 the caption for the box, shown on its top border.
845 the height of the dialog box.
848 the width of the dialog box.
851 Other parameters depend on the box type.
853 .\" ************************************************************************
855 implements the "\fB\-\-buildlist\fP" option.
857 .B const char * \fItitle
858 is the title on the top of the widget.
860 .B const char * \fIcprompt
861 is the prompt text shown within the widget.
864 is the desired height of the box.
865 If zero, the height is adjusted to use the available screen size.
868 is the desired width of the box.
869 If zero, the height is adjusted to use the available screen size.
871 .B int \fIlist_height
872 is the minimum height to reserve for displaying the list.
873 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
876 is the number of rows in \fIitems\fP.
879 is an array of strings which is viewed either as a list of rows
881 \fItag item status\fR
886 \fItag item status help\fR
889 depending on whether \fBdialog_vars.item_help\fP is set.
892 is reserved for future enhancements
894 .\" ************************************************************************
896 implements the "\fB\-\-calendar\fP" option.
898 .B const char * \fItitle
899 is the title on the top of the widget.
901 .B const char * \fIsubtitle
902 is the prompt text shown within the widget.
905 is the height excluding the fixed-height calendar grid.
908 is the overall width of the box,
909 which is adjusted up to the calendar grid's minimum width if needed.
912 is the initial day of the week shown,
913 counting zero as Sunday.
914 If the value is negative, the current day of the week is used.
917 is the initial month of the year shown,
918 counting one as January.
919 If the value is negative, the current month of the year is used.
922 is the initial year shown.
923 If the value is negative, the current year is used.
924 .\" ************************************************************************
926 implements the "\fB\-\-checklist\fP" and "\fB\-\-radiolist\fP" options
927 depending on the \fIflag\fP parameter.
929 .B const char * \fItitle
930 is the title on the top of the widget.
932 .B const char * \fIcprompt
933 is the prompt text shown within the widget.
936 is the desired height of the box.
937 If zero, the height is adjusted to use the available screen size.
940 is the desired width of the box.
941 If zero, the height is adjusted to use the available screen size.
943 .B int \fIlist_height
944 is the minimum height to reserve for displaying the list.
945 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
948 is the number of rows in \fIitems\fP.
951 is an array of strings which is viewed either as a list of rows
953 \fItag item status\fR
958 \fItag item status help\fR
961 depending on whether \fBdialog_vars.item_help\fP is set.
963 is either \fIFLAG_CHECK\fP, for checklists,
964 or \fIFLAG_RADIO\fP for radiolists.
965 .\" ************************************************************************
967 implements the "\fB\-\-dselect\fP" option.
969 .B const char * \fItitle
970 is the title on the top of the widget.
972 .B const char * \fIpath
973 is the preselected value to show in the input-box,
974 which is used also to set the directory- and file-windows.
977 is the height excluding the minimum needed to show the dialog box framework.
978 If zero, the height is based on the screen size.
981 is the desired width of the box.
982 If zero, the height is based on the screen size.
983 .\" ************************************************************************
985 implements the "\fB\-\-editbox\fP" option.
987 .B const char * \fItitle
988 is the title on the top of the widget.
990 .B const char * \fIfile
991 is the name of the file from which to read.
994 is the desired height of the box.
995 If zero, the height is adjusted to use the available screen size.
998 is the desired width of the box.
999 If zero, the height is adjusted to use the available screen size.
1000 .\" ************************************************************************
1002 implements the "\fB\-\-form\fP" option.
1004 .B const char * \fItitle
1005 is the title on the top of the widget.
1007 .B const char * \fIcprompt
1008 is the prompt text shown within the widget.
1011 is the desired height of the box.
1012 If zero, the height is adjusted to use the available screen size.
1015 is the desired width of the box.
1016 If zero, the height is adjusted to use the available screen size.
1018 .B int \fIform_height
1019 is the minimum height to reserve for displaying the list.
1020 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1023 is the number of rows in \fIitems\fP.
1026 is an array of strings which is viewed either as a list of rows
1028 \fIName NameY NameX Text TextY TextX FLen ILen\fR
1033 \fIName NameY NameX Text TextY TextX FLen ILen Help\fR
1036 depending on whether \fBdialog_vars.item_help\fP is set.
1037 .\" ************************************************************************
1039 implements the "\fB\-\-fselect\fP" option.
1041 .B const char * \fItitle
1042 is the title on the top of the widget.
1044 .B const char * \fIpath
1045 is the preselected value to show in the input-box,
1046 which is used also to set the directory- and file-windows.
1049 is the height excluding the minimum needed to show the dialog box framework.
1050 If zero, the height is based on the screen size.
1053 is the desired width of the box.
1054 If zero, the height is based on the screen size.
1055 .\" ************************************************************************
1057 implements the "\fB\-\-gauge\fP" option.
1058 Alternatively, a simpler or customized gauge widget can be
1060 \fBdlg_allocate_gauge\fP,
1061 \fBdlg_reallocate_gauge\fP,
1062 \fBdlg_update_gauge\fP and
1063 \fBdlg_free_gauge\fP.
1065 .B const char * \fItitle
1066 is the title on the top of the widget.
1068 .B const char * \fIcprompt
1069 is the prompt text shown within the widget.
1072 is the desired height of the box.
1073 If zero, the height is based on the screen size.
1076 is the desired width of the box.
1077 If zero, the height is based on the screen size.
1080 is the percentage to show in the progress bar.
1081 .\" ************************************************************************
1083 implements the "\fB\-\-inputbox\fP" or
1084 "\fB\-\-password\fP" option, depending on the value of \fIpassword\fP.
1086 .B const char * \fItitle
1087 is the title on the top of the widget.
1089 .B const char * \fIcprompt
1090 is the prompt text shown within the widget.
1093 is the desired height of the box.
1094 If zero, the height is based on the screen size.
1097 is the desired width of the box.
1098 If zero, the height is based on the screen size.
1100 .B const char * \fIinit
1101 is the initial value of the input box, whose length is taken into account
1102 when auto-sizing the width of the dialog box.
1105 if true, causes typed input to be echoed as asterisks.
1106 .\" ************************************************************************
1108 implements the "\fB\-\-hfile\fP" option.
1110 .B const char * \fItitle
1111 is the title on the top of the widget.
1113 .B const char * \fIfile
1114 is the name of a file containing the text to display.
1115 This function is internally bound to F1 (function key \*(``1\*(''),
1116 passing \fBdialog_vars.help_file\fP as a parameter.
1117 The \fB\*p\fP program sets that variable when the \fB\-\-hfile\fP option
1121 is the desired height of the box.
1122 If zero, the height is based on the screen size.
1125 is the desired width of the box.
1126 If zero, the height is based on the screen size.
1127 .\" ************************************************************************
1129 implements the "\fB\-\-menu\fP" or "\fB\-\-inputmenu\fP" option
1130 depending on whether \fBdialog_vars.input_menu\fP is set.
1132 .B const char * \fItitle
1133 is the title on the top of the widget.
1135 .B const char * \fIcprompt
1136 is the prompt text shown within the widget.
1139 is the desired height of the box.
1140 If zero, the height is based on the screen size.
1143 is the desired width of the box.
1144 If zero, the height is based on the screen size.
1146 .B int \fImenu_height
1147 is the minimum height to reserve for displaying the list.
1148 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1151 is the number of rows in \fIitems\fP.
1154 is an array of strings which is viewed either as a list of rows
1164 depending on whether \fBdialog_vars.item_help\fP is set.
1165 .\" ************************************************************************
1166 .SS dialog_mixedform
1167 implements the "\fB\-\-mixedform\fP" option.
1169 .B const char * \fItitle
1170 is the title on the top of the widget.
1172 .B const char * \fIcprompt
1173 is the prompt text shown within the widget.
1176 is the desired height of the box.
1177 If zero, the height is adjusted to use the available screen size.
1180 is the desired width of the box.
1181 If zero, the height is adjusted to use the available screen size.
1183 .B int \fIform_height
1184 is the minimum height to reserve for displaying the list.
1185 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1188 is the number of rows in \fIitems\fP.
1191 is an array of strings which is viewed either as a list of rows
1193 \fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR
1198 \fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR
1201 depending on whether \fBdialog_vars.item_help\fP is set.
1202 .\" ************************************************************************
1203 .SS dialog_mixedgauge
1204 implements the "\fB\-\-mixedgauge\fP" option
1206 .B const char * \fItitle
1207 is the title on the top of the widget.
1209 .B const char * \fIcprompt
1210 is the caption text shown within the widget.
1213 is the desired height of the box.
1214 If zero, the height is based on the screen size.
1217 is the desired width of the box.
1218 If zero, the height is based on the screen size.
1221 is the percentage to show in the progress bar.
1224 is the number of rows in \fIitems\fP.
1227 is an array of strings which is viewed as a list
1228 of \fItag\fP and \fIitem\fP values.
1229 The \fItag\fP values are listed,
1230 one per row, in the list at the top of the widget.
1232 The \fIitem\fP values are decoded:
1233 digits 0 through 9 are the following strings
1257 A string with a leading "-" character is centered, marked with "%".
1258 For example, "-75" is displayed as "75%".
1259 Other strings are displayed as is.
1260 .\" ************************************************************************
1262 implements the "\fB\-\-msgbox\fP" or "\fB\-\-infobox\fP" option
1263 depending on whether \fIpauseopt\fP is set.
1265 .B const char * \fItitle
1266 is the title on the top of the widget.
1268 .B const char * \fIcprompt
1269 is the prompt text shown within the widget.
1272 is the desired height of the box.
1273 If zero, the height is based on the screen size.
1276 is the desired width of the box.
1277 If zero, the height is based on the screen size.
1280 if true, an \*(``OK\*('' button will be shown,
1281 and the dialog will wait for it to complete.
1282 With an \*(``OK\*('' button, it is denoted a \*(``msgbox\*('',
1283 without an \*(``OK\*('' button, it is denoted an \*(``infobox\*(''.
1284 .\" ************************************************************************
1286 implements the "\fB\-\-pause\fP" option.
1288 .B const char * \fItitle
1289 is the title on the top of the widget.
1292 is the desired height of the box.
1293 If zero, the height is based on the screen size.
1296 is the desired width of the box.
1297 If zero, the height is based on the screen size.
1300 is the timeout to use for the progress bar.
1301 .\" ************************************************************************
1303 implements the "\fB\-\-prgbox\fP" option.
1305 .B const char * \fItitle
1306 is the title on the top of the widget.
1308 .B const char * \fIcprompt
1309 is the prompt text shown within the widget.
1310 If empty or null, no prompt is shown.
1312 .B const char * \fIcommand
1313 is the name of the command to execute.
1316 is the desired height of the box.
1317 If zero, the height is based on the screen size.
1320 is the desired width of the box.
1321 If zero, the height is based on the screen size.
1324 if true, an \*(``OK\*('' button will be shown,
1325 and the dialog will wait for it to complete.
1326 .\" ************************************************************************
1327 .SS dialog_progressbox
1328 implements the "\fB\-\-progressbox\fP" option.
1330 .B const char * \fItitle
1331 is the title on the top of the widget.
1333 .B const char * \fIcprompt
1334 is the prompt text shown within the widget.
1335 If empty or null, no prompt is shown.
1338 is the desired height of the box.
1339 If zero, the height is based on the screen size.
1342 is the desired width of the box.
1343 If zero, the height is based on the screen size.
1344 .\" ************************************************************************
1346 implements the "\fB\-\-rangebox\fP" option.
1348 .B const char * \fItitle
1349 is the title on the top of the widget.
1351 .B const char * \fIcprompt
1352 is the prompt text shown within the widget.
1353 If empty or null, no prompt is shown.
1356 is the desired height of the widget.
1357 If zero, the height is based on the screen size.
1360 is the desired width of the widget.
1361 If zero, the height is based on the screen size.
1364 is the minimum value to allow.
1367 is the maximum value to allow.
1369 .B int \fIdefault_value
1370 is the default value, if no change is made.
1371 .\" ************************************************************************
1373 implements the "\fB\-\-tailbox\fP" or "\fB\-\-tailboxbg\fP" option
1374 depending on whether \fIbg_task\fP is set.
1376 .B const char * \fItitle
1377 is the title on the top of the widget.
1379 .B const char * \fIfile
1380 is the name of the file to display in the dialog.
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.
1392 the window is added to the callback list in \fBdialog_state\fP,
1393 and the application will poll for the window to be updated.
1394 Otherwise an \*(``OK\*('' button is added to the window,
1395 and it will be closed when the button is activated.
1396 .\" ************************************************************************
1398 implements the "\fB\-\-textbox\fP" option.
1400 .B const char * \fItitle
1401 is the title on the top of the widget.
1403 .B const char * \fIfile
1404 is the name of the file to display in the dialog.
1407 is the desired height of the box.
1408 If zero, the height is based on the screen size.
1411 is the desired width of the box.
1412 If zero, the height is based on the screen size.
1413 .\" ************************************************************************
1415 implements the "\fB\-\-timebox\fP" option.
1417 .B const char * \fItitle
1418 is the title on the top of the widget.
1420 .B const char * \fIsubtitle
1421 is the prompt text shown within the widget.
1424 is the desired height of the box.
1425 If zero, the height is based on the screen size.
1428 is the desired width of the box.
1429 If zero, the height is based on the screen size.
1432 is the initial hour shown.
1433 If the value is negative, the current hour is used.
1434 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24.
1437 is the initial minute shown.
1438 If the value is negative, the current minute is used.
1439 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1442 is the initial second shown.
1443 If the value is negative, the current second is used.
1444 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1445 .\" ************************************************************************
1447 implements the "\fB\-\-treeview\fP" option.
1449 .B const char * \fItitle
1450 is the title on the top of the widget.
1452 .B const char * \fIcprompt
1453 is the prompt text shown within the widget.
1456 is the desired height of the box.
1457 If zero, the height is based on the screen size.
1460 is the desired width of the box.
1461 If zero, the height is based on the screen size.
1463 .B int \fIlist_height
1464 is the minimum height to reserve for displaying the list.
1465 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1468 is the number of rows in \fIitems\fP.
1471 is the list of items, contain tag, name, and optionally help strings
1472 (if \fBdialog_vars.item_help\fP is set).
1473 The initial selection state for each item is also in this list.
1477 is either \fIFLAG_CHECK\fP, for checklists (multiple selections),
1478 or \fIFLAG_RADIO\fP for radiolists (a single selection).
1479 .\" ************************************************************************
1481 implements the "\fB\-\-yesno\fP" option.
1483 .B const char * \fItitle
1484 is the title on the top of the widget.
1486 .B const char * \fIcprompt
1487 is the prompt text shown within the widget.
1490 is the desired height of the box.
1491 If zero, the height is based on the screen size.
1494 is the desired width of the box.
1495 If zero, the height is based on the screen size.
1497 .\" ************************************************************************
1498 .SH UTILITY FUNCTIONS
1499 Most functions that implement lower-level
1500 functionality for the command-line \fB\*p\fP
1501 program or widgets, have names beginning "\fIdlg_\fP".
1502 Bowing to longstanding usage, the functions that initialize the
1503 display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP.
1505 The only non-widget function whose name begins with "\fIdialog_\fP"
1506 is \fBdialog_version\fP, which returns the version number of the
1507 library as a string.
1509 A few functions are prefixed "\fI_dlg_\fP",
1510 because they are required for internal use,
1511 but not intended as part of the library application programming interface.
1514 Here is a brief summary of the utility functions and their parameters:
1515 .\" ---------------------------------------------------------------------------
1516 .SS dlg_add_callback
1517 Add a callback, used to allow polling input from multiple tailbox
1520 .B DIALOG_CALLBACK *\fIp\fP
1521 contains the callback information.
1522 .\" ---------------------------------------------------------------------------
1523 .SS dlg_add_callback_ref
1524 Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP
1525 as well as a pointer to a cleanup function which will be called when the
1526 associated input ends.
1528 .B DIALOG_CALLBACK **\fIp\fP
1529 points to the callback information.
1530 This is a reference to the pointer so that the caller's pointer can be
1531 zeroed when input ends.
1533 .B DIALOG_FREEBACK \fIfunc\fP
1534 function to call when input ends, e.g., to free caller's additional data.
1535 .\" ---------------------------------------------------------------------------
1536 .SS dlg_add_help_formitem
1537 This is a utility function used enforce consistent behavior for
1538 the \fIDIALOG_VARS.help_tags\fP and \fIDIALOG_VARS.item_help\fP variables.
1540 .B int *\fIresult\fP
1541 this is updated to DLG_EXIT_ITEM_HELP if \fIDIALOG_VARS.item_help\fP is set.
1544 the tag- or help-text is stored here.
1546 .B DIALOG_FORMITEM *\fIitem\fP
1547 contains the list item to use for tag- or help-text.
1548 .\" ---------------------------------------------------------------------------
1549 .SS dlg_add_help_listitem
1550 This is a utility function used enforce consistent behavior for
1551 the \fIDIALOG_VARS.help_tags\fP and \fIDIALOG_VARS.item_help\fP variables.
1553 .B int *\fIresult\fP
1554 this is updated to DLG_EXIT_ITEM_HELP if \fIDIALOG_VARS.item_help\fP is set.
1557 the tag- or help-text is stored here.
1559 .B DIALOG_LISTITEM *\fIitem\fP
1560 contains the list item to use for tag- or help-text.
1561 .\" ---------------------------------------------------------------------------
1562 .SS dlg_add_last_key
1563 Report the last key entered by the user.
1564 This implements the \fB\-\-last\-key\fP command-line option,
1565 using \fBdialog_vars.last_key\fP.
1568 controls the way the last key report is separated from other results:
1575 (separator after the key name)
1578 (separator is optionally before the key name)
1583 .\" ---------------------------------------------------------------------------
1585 Add a quoted string to the result buffer (see \fBdlg_add_result\fP).
1586 If no quotes are necessary, none are used.
1587 If \fBdialog_vars.single_quoted\fR is set, single-quotes are used.
1588 Otherwise, double-quotes are used.
1591 is the string to add.
1592 .\" ---------------------------------------------------------------------------
1594 Add a string to the result buffer \fBdialog_vars.input_result\fP.
1597 is the string to add.
1598 .\" ---------------------------------------------------------------------------
1599 .SS dlg_add_separator
1600 Add an output-separator to the result buffer \fBdialog_vars.input_result\fP.
1601 If \fBdialog_vars.output_separator\fP is set, use that.
1602 Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline.
1603 If neither is set, use a space.
1604 .\" ---------------------------------------------------------------------------
1606 Add a quoted or unquoted string to the result buffer
1607 (see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP),
1608 according to whether \fBdialog_vars.quoted\fP is true.
1611 is the string to add.
1612 .\" ---------------------------------------------------------------------------
1613 .SS dlg_align_columns
1614 Copy and reformat an array of pointers to strings, aligning according to
1615 the column separator \fBdialog_vars.column_separator\fP.
1616 If no column separator is set, the array will be unmodified;
1617 otherwise it is copied and reformatted.
1619 Caveat: This function is only implemented for 8-bit characters.
1622 This is the array to reformat.
1623 It points to the first string to modify.
1626 This is the size of the struct for each row of the array.
1629 This is the number of rows in the array.
1630 .\" ---------------------------------------------------------------------------
1631 .SS dlg_allocate_gauge
1632 Allocates a gauge widget.
1633 Use \fBdlg_update_gauge\fP to display the result.
1635 .B const char * \fItitle
1636 is the title string to display at the top of the widget.
1638 .B const char * \fIcprompt
1639 is the prompt text shown within the widget.
1642 is the desired height of the box.
1643 If zero, the height is adjusted to use the available screen size.
1646 is the desired width of the box.
1647 If zero, the height is adjusted to use the available screen size.
1650 is the percentage to show in the progress bar.
1651 .\" ---------------------------------------------------------------------------
1653 returns its parameter transformed to the
1654 corresponding "+" or "-", etc.,
1655 for the line-drawing characters used in \fB\*p\fP.
1656 If the parameter is not a line-drawing or other special character
1657 such as ACS_DARROW, it returns 0.
1660 is the parameter, usually one of the \fBACS_\fP\fIxxx\fP constants.
1661 .\" ---------------------------------------------------------------------------
1663 Set window to the given attribute.
1666 is the window to update.
1669 is the number of rows to update.
1672 is the number of columns to update.
1675 is the attribute, e.g., \fBA_BOLD\fP.
1676 .\" ---------------------------------------------------------------------------
1678 Compute window size based on the size of the formatted \fIprompt\fP and
1679 minimum dimensions for a given widget.
1682 \fBdialog_state.text_height\fP and
1683 \fBdialog_state.text_width\fP for
1684 the formatted \fIprompt\fP
1687 Normally \fB\*l\fP writes the formatted \fIprompt\fP to the curses
1689 but it will write the formatted \fIprompt\fP to the output stream
1690 if \fBdialog_state.text_only\fP is set.
1692 .B const char * \fItitle
1693 is the title string to display at the top of the widget.
1695 .B const char * \fIprompt
1696 is the message text which will be displayed in the widget,
1697 used here to determine how large the widget should be.
1699 If the value is \fINULL\fP,
1700 \fB\*l\fP allows the widget to use the whole screen,
1701 i.e., if the values referenced by \fIheight\fP and/or \fIwidth\fP are zero.
1704 is the nominal height.
1705 \fB\*L\fP checks the referenced value and may update it:
1708 if the value is negative,
1709 \fB\*l\fP updates it to the available height of the screen,
1710 after reserving rows for the window border and shadow,
1711 as well as taking into account
1712 \fBdialog_vars.begin_y\fP and
1713 \fBdialog_vars.begin_set\fP.
1715 if the value is zero,
1716 \fB\*l\fP updates it to the required height of the window,
1717 taking into account a (possibly) multi-line \fIprompt\fP.
1719 if the value is greater than zero,
1720 \fB\*l\fP uses it internally, but restores the value on return.
1724 is the nominal width.
1725 \fB\*L\fP checks the referenced value and may update it:
1728 if the value is negative,
1729 \fB\*l\fP updates it to the available width of the screen,
1730 after reserving rows for the window border and shadow,
1731 as well as taking into account
1732 \fBdialog_vars.begin_x\fP and
1733 \fBdialog_vars.begin_set\fP.
1735 if the value is zero,
1736 \fB\*l\fP updates it to the required width of the window,
1737 taking into account a (possibly) multi-line \fIprompt\fP.
1739 if the value is greater than zero,
1740 \fB\*l\fP uses it internally, but restores the value on return.
1744 is the number of lines to reserve in the vertical direction.
1747 is the minimum number of columns to use.
1748 .\" ---------------------------------------------------------------------------
1749 .SS dlg_auto_sizefile
1750 Like \fBdlg_auto_size\fP, but use a file contents to decide how large
1751 the widget should be.
1753 .B const char * \fItitle
1754 is the title string to display at the top of the widget.
1756 .B const char * \fIfile
1757 is the name of the file.
1760 is the nominal height.
1762 If it is -1, use the screen's height
1763 (after subtracting \fBdialog_vars.begin_y\fP
1764 if \fBdialog_vars.begin_set\fP is true).
1766 If it is greater than zero,
1767 limit the referenced value to the screen-height
1768 after verifying that the file exists.
1771 is the nominal width.
1773 If it is -1, use the screen's width (after subtracting \fBdialog_vars.begin_x\fP
1774 if \fBdialog_vars.begin_set\fP is true).
1776 If it is greater than zero,
1777 limit the referenced value to the screen-width
1778 after verifying that the file exists.
1781 is the number of lines to reserve on the screen for drawing boxes.
1784 is the number of columns to reserve on the screen for drawing boxes.
1785 .\" ---------------------------------------------------------------------------
1787 If \fBdialog_vars.beep_signal\fP is nonzero,
1788 this calls \fBbeep\fP once and sets
1789 \fBdialog_vars.beep_signal\fP to zero.
1790 .\" ---------------------------------------------------------------------------
1792 returns its \fBchtype\fP parameter transformed as follows:
1794 if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set.
1796 if \fBdialog_vars.ascii_lines\fP is set,
1797 returns the corresponding "+" or "-", etc.,
1798 for the line-drawing characters used in \fB\*p\fP.
1800 otherwise, if \fBdialog_vars.no_lines\fP is set,
1801 returns a space for the line-drawing characters.
1803 if the parameter is not a line-drawing or other special character
1805 it returns the parameter unchanged.
1806 .\" ---------------------------------------------------------------------------
1807 .SS dlg_box_x_ordinate
1808 returns a suitable x-ordinate (column) for a new widget.
1809 If \fBdialog_vars.begin_set\fP is 1,
1810 use \fBdialog_vars.begin_x\fP;
1811 otherwise center the widget on the screen (using the \fIwidth\fP parameter).
1814 is the width of the widget.
1815 .\" ---------------------------------------------------------------------------
1816 .SS dlg_box_y_ordinate
1817 returns a suitable y-ordinate (row) for a new widget.
1818 If \fBdialog_vars.begin_set\fP is 1,
1819 use \fBdialog_vars.begin_y\fP;
1820 otherwise center the widget on the screen (using the \fIheight\fP parameter).
1823 is the height of the widget.
1824 .\" ---------------------------------------------------------------------------
1826 This is an alternate interface to the \fBbuildlist\fP widget
1827 which allows the application to read the list item states back
1828 directly without putting them in the output buffer.
1830 .B const char * \fItitle
1831 is the title string to display at the top of the widget.
1833 .B const char * \fIcprompt
1834 is the prompt text shown within the widget.
1837 is the desired height of the box.
1838 If zero, the height is adjusted to use the available screen size.
1841 is the desired width of the box.
1842 If zero, the height is adjusted to use the available screen size.
1844 .B int \fIlist_height
1845 is the minimum height to reserve for displaying the list.
1846 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1849 is the number of rows in \fIitems\fP.
1851 .B DIALOG_LISTITEM * \fIitems
1852 is the list of items, contain tag, name, and optionally help strings
1853 (if \fBdialog_vars.item_help\fP is set).
1854 The initial selection state for each item is also in this list.
1856 .B const char * \fIstates
1857 This is a list of characters to display for the given states.
1858 Normally a buildlist provides true (1) and false (0) values,
1859 which the widget displays as "*" and space, respectively.
1860 An application may set this parameter to an arbitrary null-terminated string.
1861 The widget determines the number of states from the length of this string,
1862 and will cycle through the corresponding display characters as the user
1863 presses the space-bar.
1865 .B int \fIorder_mode
1866 is reserved for future enhancements
1868 .B int * \fIcurrent_item
1869 The widget sets the referenced location to the index of the current display
1870 item (cursor) when it returns.
1871 .\" ---------------------------------------------------------------------------
1872 .SS dlg_button_count
1873 Count the buttons in the list.
1875 .B const char ** \fIlabels
1876 is a list of (pointers to) button labels terminated by a null pointer.
1877 .\" ---------------------------------------------------------------------------
1879 If a key was bound to one of the button-codes in \fBdlg_result_key\fP, fake
1880 a button-value and an \*(``Cancel\*('' key
1881 to cause the calling widget to return the corresponding status.
1883 See \fBdlg_ok_buttoncode\fP, which maps settings for ok/extra/help and button
1884 number into exit-code.
1885 .\" ---------------------------------------------------------------------------
1886 .SS dlg_button_layout
1887 Make sure there is enough space for the buttons by
1888 computing the width required for their labels,
1889 adding margins and limiting based on the screen size.
1891 .B const char ** \fIlabels
1892 is a list of (pointers to) button labels terminated by a null pointer.
1895 the function sets the referenced \fIlimit\fP to the width required for
1896 the buttons (limited by the screen size)
1897 if that is wider than the passed-in limit.
1898 .\" ---------------------------------------------------------------------------
1899 .SS dlg_button_sizes
1900 Compute the size of the button array in columns.
1902 .B const char ** \fIlabels
1903 is a list of (pointers to) button labels terminated by a null pointer.
1906 is true if the buttons are arranged in a column rather than a row.
1909 Return the total number of columns in the referenced location.
1912 Return the longest button's columns in the referenced location.
1913 .\" ---------------------------------------------------------------------------
1914 .SS dlg_button_to_char
1915 Find the first uppercase character in the label, which we may use for an
1917 If the label is empty, return -1.
1918 If no uppercase character is found, return 0.
1919 Otherwise return the uppercase character.
1924 .B dlg_char_to_button
1925 use the first uppercase character.
1926 However, they keep track of all of the labels and
1927 if the first has already been used in another label,
1928 they will continue looking for another uppercase character.
1929 This function does not have enough information to make that check.
1931 .B const char * \fIlabel
1932 is the label to test.
1933 .\" ---------------------------------------------------------------------------
1934 .SS dlg_button_x_step
1935 Compute the step-size needed between elements of the button array.
1937 .B const char ** \fIlabels
1938 is a list of (pointers to) button labels terminated by a null pointer.
1941 is the maximum number of columns to allow for the buttons.
1944 store the nominal gap between buttons in the referenced location.
1945 This is constrained to be at least one.
1948 store the left+right total margins (for the list of buttons) in the referenced
1952 store the step-size in the referenced location.
1953 .\" ---------------------------------------------------------------------------
1954 .SS dlg_calc_list_width
1955 Calculate the minimum width for the list,
1956 assuming none of the items are truncated.
1959 is the number of \fIitems\fP.
1961 .B DIALOG_LISTITEM * \fIitems
1962 contains a \fIname\fP and \fItext\fP field,
1963 e.g., for checklists or radiobox lists.
1964 The function returns the sum of the widest columns
1965 needed for of each of these fields.
1967 If \fBdialog_vars.no_items\fP is set,
1968 the \fItext\fP fields in the list are ignored.
1969 .\" ---------------------------------------------------------------------------
1971 Calculate new height and list_height values.
1974 on input, is the height without adding the list-height.
1975 On return, this contains the total list-height and is the
1976 actual widget's height.
1978 .B int * \fIlist_height
1979 on input, is the requested list-height.
1980 On return, this contains the number of rows available for displaying
1981 the list after taking into account the screen size and
1982 the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables.
1985 is the number of \fIitems\fP in the list.
1986 .\" ---------------------------------------------------------------------------
1988 This function is obsolete, provided for library-compatibility.
1989 It is replaced by \fBdlg_calc_list_width\fP.
1992 is the number of \fIitems\fP.
1995 is a list of character pointers.
1998 is the number of items in each group, e.g., the second array index.
1999 .\" ---------------------------------------------------------------------------
2000 .SS dlg_char_to_button
2001 Given a list of button labels,
2002 and a character which may be the abbreviation for one, find it, if it exists.
2003 An abbreviation will be the first character
2004 which happens to be capitalized in the label.
2005 If the character is found, return its index within the list of \fIlabels\fP.
2006 Otherwise, return \fBDLG_EXIT_UNKNOWN\fP.
2009 is the character to find.
2011 .B const char ** \fIlabels
2012 is a list of (pointers to) button labels terminated by a null pointer.
2013 .\" ---------------------------------------------------------------------------
2015 This entrypoint provides the \fB\-\-checklist\fP or \fB\-\-radiolist\fP
2016 functionality without the limitations of \fB\*p\fP's command-line syntax
2017 (compare to \fBdialog_checklist\fP).
2019 .B const char * \fItitle
2020 is the title string to display at the top of the widget.
2022 .B const char * \fIcprompt
2023 is the prompt text shown within the widget.
2026 is the desired height of the box.
2027 If zero, the height is adjusted to use the available screen size.
2030 is the desired width of the box.
2031 If zero, the height is adjusted to use the available screen size.
2033 .B int \fIlist_height
2034 is the minimum height to reserve for displaying the list.
2035 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2038 is the number of \fIitems\fP.
2040 .B DIALOG_LISTITEM * \fIitems
2041 This is a list of the items to display in the checklist.
2043 .B const char * \fIstates
2044 This is a list of characters to display for the given states.
2045 Normally a checklist provides true (1) and false (0) values,
2046 which the widget displays as "*" and space, respectively.
2047 An application may set this parameter to an arbitrary null-terminated string.
2048 The widget determines the number of states from the length of this string,
2049 and will cycle through the corresponding display characters as the user
2050 presses the space-bar.
2053 This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP,
2054 depending on whether the widget should act as a checklist or radiobox.
2056 .B int * \fIcurrent_item
2057 The widget sets the referenced location to the index of the current display
2058 item (cursor) when it returns.
2059 .\" ---------------------------------------------------------------------------
2060 .SS dlg_check_scrolled
2061 given a function key (or other key that was mapped to a function key),
2062 check if it is one of the up/down scrolling functions:
2079 Some widgets use these key bindings for scrolling the prompt-text up and
2080 down, to allow for display in very small windows.
2082 The function returns 0 (zero) if it finds one of these keys,
2086 is the function-key to check
2089 is the number of lines
2090 which would be used to display the scrolled prompt in
2091 an arbitrarily tall window.
2092 It is used here to check limits for the \fIoffset\fP value.
2095 this is the available height for writing scrolled text,
2096 which is smaller than the window if it contains buttons.
2099 on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay
2103 on entry, holds the starting line number (counting from zero)
2104 last used for \fBdlg_print_scrolled\fP.
2105 On return, holds the updated starting line number.
2106 .\" ---------------------------------------------------------------------------
2108 Set window to the default \fB\*p\fP screen attribute.
2109 This is set in the rc-file with \fBscreen_color\fP.
2110 .\" ---------------------------------------------------------------------------
2112 Free storage used for the result buffer (\fBdialog_vars.input_result\fP).
2113 The corresponding pointer is set to NULL.
2114 .\" ---------------------------------------------------------------------------
2116 Return the number of colors that can be configured in \fB\*p\fP.
2117 .\" ---------------------------------------------------------------------------
2119 Initialize the color pairs used in \fB\*p\fP.
2120 .\" ---------------------------------------------------------------------------
2122 Count the entries in an argument vector.
2125 Points to the argument vector.
2126 .\" ---------------------------------------------------------------------------
2127 .SS dlg_count_columns
2128 Returns the number of columns used for a string.
2129 This is not necessarily the number of bytes in a string.
2131 .B const char * \fIstring
2132 is the string to measure.
2133 .\" ---------------------------------------------------------------------------
2134 .SS dlg_count_real_columns
2135 Returns the number of columns used for a string,
2136 accounting for "\eZ" sequences which can be used for
2137 coloring the text if \fBdialog_vars.colors\fP is set.
2138 This is not necessarily the number of bytes in a string.
2140 .B const char * \fIstring
2141 is the string to measure.
2142 .\" ---------------------------------------------------------------------------
2143 .SS dlg_count_wchars
2144 Returns the number of wide-characters in the string.
2146 .B const char * \fIstring
2147 is the string to measure.
2148 .\" ---------------------------------------------------------------------------
2150 Create a configuration file,
2151 i.e., write internal tables to a file which can be read back by \fB\*p\fP
2154 .B const char * \fIfilename
2155 is the name of the file to write to.
2156 .\" ---------------------------------------------------------------------------
2158 If \fBdialog_vars.size_err\fP is true,
2159 check if the given window size is too large to fit on the screen.
2160 If so, exit with an error reporting the size of the window.
2163 is the window's height
2166 is the window's width
2167 .\" ---------------------------------------------------------------------------
2168 .SS dlg_default_button
2169 If \fBdialog_vars.default_button\fP is positive,
2170 return the button-index for that button code,
2171 using \fBdlg_ok_buttoncode\fP to test indices starting with zero.
2172 Otherwise (or if no match was found for the button code), return zero.
2173 .\" ---------------------------------------------------------------------------
2174 .SS dlg_default_formitem
2175 If \fBdialog_vars.default_item\fP is not null,
2176 find that name by matching the \fIname\fP field in the list of form \fIitems\fP.
2177 If found, return the index of that item in the list.
2178 Otherwise, return zero.
2180 .B DIALOG_FORMITEM * \fIitems
2181 is the list of items to search.
2182 It is terminated by an entry with a null \fIname\fP field.
2183 .\" ---------------------------------------------------------------------------
2184 .SS dlg_default_item
2185 This function is obsolete, provided for library-compatibility.
2186 It is replaced by \fBdlg_default_formitem\fP and \fBdlg_default_listitem\fP.
2189 is the list of items to search.
2192 is the number of items in each group, e.g., the second array index.
2193 .\" ---------------------------------------------------------------------------
2194 .SS dlg_defaultno_button
2195 If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not,
2196 find the button-index for the \*(``Cancel\*('' button.
2197 Otherwise, return the index for \*(``OK\*('' (always zero).
2198 .\" ---------------------------------------------------------------------------
2200 Remove a window, repainting everything else.
2203 is the window to remove.
2204 .\" ---------------------------------------------------------------------------
2206 create a derived window, e.g., for an input area of a widget
2209 is the parent window
2212 is the subwindow's height
2215 is the subwindow's width
2218 is the subwindow's top-row
2221 is the subwindow's left-column
2222 .\" ---------------------------------------------------------------------------
2224 This is called each time a widget is invoked which may do output.
2225 It increments \fBdialog_state.output_count\fP,
2226 so the output function in \fB\*p\fP can test this and add a separator.
2227 .\" ---------------------------------------------------------------------------
2229 Draw up/down arrows on a window, e.g., for scrollable lists.
2230 It calls \fBdlg_draw_arrows2\fP using the
2231 \fImenubox_color\fP and \fImenubox_border_color\fP attributes.
2233 .B WINDOW * \fIdialog
2234 is the window on which to draw an arrow.
2237 is true if an up-arrow should be drawn at the top of the window.
2239 .B int \fIbottom_arrow
2240 is true if an down-arrow should be drawn at the bottom of the window.
2243 is the zero-based column within the window on which to draw arrows.
2246 is the zero-based row within the window on which to draw up-arrows
2247 as well as a horizontal line to show the window's top.
2250 is the zero-based row within the window on which to draw down-arrows
2251 as well as a horizontal line to show the window's bottom.
2252 .\" ---------------------------------------------------------------------------
2253 .SS dlg_draw_arrows2
2254 Draw up/down arrows on a window, e.g., for scrollable lists.
2256 .B WINDOW * \fIdialog
2257 is the window on which to draw an arrow.
2260 is true if an up-arrow should be drawn at the top of the window.
2262 .B int \fIbottom_arrow
2263 is true if an down-arrow should be drawn at the bottom of the window.
2266 is the zero-based column within the window on which to draw arrows.
2269 is the zero-based row within the window on which to draw up-arrows
2270 as well as a horizontal line to show the window's top.
2273 is the zero-based row within the window on which to draw down-arrows
2274 as well as a horizontal line to show the window's bottom.
2277 is the window's background attribute.
2279 .B chtype \fIborderattr
2280 is the window's border attribute.
2281 .\" ---------------------------------------------------------------------------
2282 .SS dlg_draw_bottom_box
2283 Draw a partial box at the bottom of a window,
2284 e.g., to surround a row of buttons.
2285 It is designed to merge with an existing box around
2286 the whole window (see \fBdlg_draw_box\fP),
2287 so it uses tee-elements rather than corner-elements
2288 on the top corners of this box.
2291 is the window to update.
2292 .\" ---------------------------------------------------------------------------
2293 .SS dlg_draw_bottom_box2
2294 Draw a partial box at the bottom of a window,
2295 e.g., to surround a row of buttons.
2296 It is designed to merge with an existing box around
2297 the whole window (see \fBdlg_draw_box2\fP),
2298 so it uses tee-elements rather than corner-elements
2299 on the top corners of this box.
2302 is the window to update.
2304 .B chtype \fIon_left
2305 is used to color the upper/left edges of the box, i.e., the tee-element and
2308 .B chtype \fIon_right
2309 is used to color the right edge of the box, i.e., the tee-element
2311 .B chtype \fIon_inside
2312 is used to fill-color the inside of the box
2313 .\" ---------------------------------------------------------------------------
2315 Draw a rectangular box with line drawing characters.
2318 is the window to update.
2321 is the top row of the box.
2324 is the left column of the box.
2327 is the height of the box.
2330 is the width of the box.
2332 .B chtype \fIboxchar
2333 is used to color the right/lower edges.
2334 It also is fill-color used for the box contents.
2336 .B chtype \fIborderchar
2337 is used to color the upper/left edges.
2338 .\" ---------------------------------------------------------------------------
2340 Draw a rectangular box with line drawing characters.
2343 is the window to update.
2346 is the top row of the box.
2349 is the left column of the box.
2352 is the height of the box.
2355 is the width of the box.
2357 .B chtype \fIboxchar
2358 is used to fill-color for the box contents.
2360 .B chtype \fIborderchar
2361 is used to color the upper/left edges.
2363 .B chtype \fIborderchar2
2364 is used to color the right/lower edges.
2365 .\" ---------------------------------------------------------------------------
2366 .SS dlg_draw_buttons
2367 Print a list of buttons at the given position.
2370 is the window to update.
2373 is the starting row.
2376 is the starting column.
2378 .B const char ** \fIlabels
2379 is a list of (pointers to) button labels terminated by a null pointer.
2382 is the index within the list of the selected button.
2385 is true if the buttons are arranged in a column rather than a row.
2388 is the number of columns (or rows if \fIvertical\/\fP) allowed for the display.
2389 .\" ---------------------------------------------------------------------------
2390 .SS dlg_draw_helpline
2391 draw the text in \fBdialog_vars.help_line\fP at the bottom of the given window.
2393 .B WINDOW * \fIdialog
2394 is the window to modify.
2396 .B bool \fIdecorations
2397 if true, allow room for the scrolling arrows.
2398 .\" ---------------------------------------------------------------------------
2399 .SS dlg_draw_scrollbar
2400 If \fBdialog_state.use_scrollbar\fP is set,
2401 draw a scrollbar on the right margin of windows holding scrollable data.
2402 Also (whether or not the scrollbar is drawn),
2403 annotate the bottom margin of the window with the percentage of data
2404 by the bottom of that window,
2405 and call \fBdlg_draw_arrows2\fP to put markers on the window showing
2406 when more data is available.
2409 is the window in which the data is scrolled.
2410 Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP
2411 are passed as parameters, this window can contain additional data.
2413 .B long \fIfirst_data
2414 is the zero-based index to the first row of data in the current window.
2416 .B long \fIthis_data
2417 is the zero-based index to the current row of data.
2419 .B long \fInext_data
2420 is the zero-based index to the next data after the current row.
2422 .B long \fItotal_data
2423 is the total number of rows of data.
2426 is the zero-based left margin/column of the window.
2427 The up/down arrows are draw inset by 5 columns from this point.
2430 is the zero-based right margin/column of the window.
2431 The scrollbar is drawn flush against this column.
2434 is the zero-based row within the window on which to draw up-arrows
2435 as well as a horizontal line to show the window's top.
2438 is the zero-based row within the window on which to draw down-arrows
2439 as well as a horizontal line to show the window's bottom.
2442 is the window's background attribute.
2444 .B chtype \fIborderattr
2445 is the window's border attribute.
2446 .\" ---------------------------------------------------------------------------
2448 Draw shadows along the right and bottom edge of a window to give it
2449 a 3-dimensional look.
2450 (The height, etc., may not be the same as the window's actual values).
2453 is the window to update.
2456 is the height of the window.
2459 is the width of the window.
2462 is the top row of the window.
2465 is the left column of the window.
2466 .\" ---------------------------------------------------------------------------
2468 Draw a title centered at the top of the window.
2471 is the window to update.
2473 .B const char * \fItitle
2474 is the title string to display at the top of the widget.
2475 .\" ---------------------------------------------------------------------------
2476 .SS dlg_dummy_menutext
2477 This is a utility function which supports the \fB\-\-inputmenu\fP option of
2478 the \fB\*p\fP program.
2479 If \fBdialog_vars.input_menu\fP is set, \fBdialog_menu\fP passes this
2480 pointer to \fBdlg_menu\fP as the \fIrename_menutext\fP parameter.
2481 Otherwise, it passes \fBdlg_dummy_menutext\fP.
2483 The function should only return \fBDLG_EXIT_ERROR\fP.
2485 .B DIALOG_LISTITEM * \fIitems
2486 is the list of menu items
2489 is the index of the currently-selected item
2491 .B char * \fInewtext
2492 is the updated text for the menu item
2493 .\" ---------------------------------------------------------------------------
2495 Write all user-defined key-bindings to the given stream,
2496 e.g., as part of \fBdlg_create_rc\fP.
2499 is the stream on which to write the bindings.
2500 .\" ---------------------------------------------------------------------------
2501 .SS dlg_dump_window_keys
2502 Write all user-defined key-bindings to the given stream,
2503 e.g., as part of \fBdlg_create_rc\fP.
2506 is the stream on which to write the bindings.
2509 is the window for which bindings should be dumped.
2510 If it is null, then only built-in bindings are dumped.
2511 .\" ---------------------------------------------------------------------------
2513 Remove one or more items from an argument vector.
2516 in/out parameter giving the length of the argument vector.
2517 .B char *** \fIargvp
2518 in/out parameter pointing to the argument vector.
2522 number of arguments to remove.
2523 .\" ---------------------------------------------------------------------------
2525 Given the character-offset in the string,
2526 returns the display-offset where
2527 \fB\*p\fP should position the cursor.
2528 In this context, \*(``characters\*('' may be multicolumn,
2529 since the string can be a multibyte character string.
2532 is the string to analyze
2535 is the character-offset
2538 is a limit on the column positions that can be used,
2539 e.g., the window's size.
2540 .\" ---------------------------------------------------------------------------
2542 Updates the string and character-offset, given various editing characters
2543 or literal characters which are inserted at the character-offset.
2544 Returns true if an editing change was made (and the display should
2545 be updated), and false if the key was something like \fBKEY_ENTER\fP,
2546 which is a non-editing action outside this function.
2549 is the (multibyte) string to update
2552 is the character-offset
2558 is true if the editing key is a function-key
2561 is used in a special loop case by calling code to force the return
2562 value of this function when a function-key code 0 is passed in.
2563 .\" ---------------------------------------------------------------------------
2565 Given an internal exit code,
2566 check if the corresponding environment variable is set.
2567 If so, remap the exit code to match the environment variable.
2568 Finally call \fBexit\fP with the resulting exit code.
2571 is the internal exit code, e.g., \fBDLG_EXIT_OK\fP,
2572 which may be remapped.
2574 The \fB\*p\fP program uses this function
2575 to allow shell scripts to remap the exit codes so they can distinguish ESC
2577 .\" ---------------------------------------------------------------------------
2579 Returns the name of an exit-code, e.g.,
2580 \*(``OK\*('' for \fBDLG_EXIT_OK\fP.
2583 is an exit-code for \fB\*p\fP as defined in \fB<\*p.h>\fP.
2584 .\" ---------------------------------------------------------------------------
2586 Returns an exit-code as the reverse of \fBdlg_exitcode2n\fP, e.g.,
2587 0 (\fBDLG_EXIT_OK\fP) for the \*(``OK\*('' string.
2589 .B const char * \fIname
2590 is the name of an exit-code for \fB\*p\fP as defined in \fB<\*p.h>\fP
2591 but omitting the \*(``DLG_EXIT_\*('' prefix.
2592 .\" ---------------------------------------------------------------------------
2593 .SS dlg_exit_buttoncode
2594 Map the given button index for \fBdlg_exit_label\fP into \fB\*p\fP's exit-code.
2598 .\" ---------------------------------------------------------------------------
2600 Return a list of button labels.
2601 If \fBdialog_vars.extra_button\fP is true,
2602 return the result of \fBdlg_ok_labels\fP.
2603 Otherwise, return a list with the \*(``Exit\*('' label
2604 and (if \fBdialog_vars.help_button\fP is set)
2605 the \*(``Help\*('' button as well.
2606 .\" ---------------------------------------------------------------------------
2608 Quit program killing all \fBtailboxbg\fP widgets.
2610 .B const char * \fIfmt
2611 is the format of the \fBprintf\fP-like message to write.
2615 are the variables to apply to the \fIfmt\fP format.
2616 .\" ---------------------------------------------------------------------------
2618 Given the character-offset to find in the list, return the corresponding
2621 .B const int *\fIlist
2622 contains a list of character-offsets,
2623 i.e., indices into a string that denote the beginning of multibyte characters.
2626 is the last index into \fBlist\fP to search.
2629 is the character-offset to find.
2630 .\" ---------------------------------------------------------------------------
2631 .SS dlg_finish_string
2632 If \fIDIALOG_STATE.finish_string\fP is true,
2633 this function discards data used to speed up layout computations.
2635 .B const char * \fIstring
2636 is the address of the string whose data should be discarded.
2637 The address rather than contents is used as the unique identifier because
2638 some of the caching is used for editable input-fields.
2639 .\" ---------------------------------------------------------------------------
2641 Cancel the local data saved by \fBdlg_last_getc\fP.
2642 .\" ---------------------------------------------------------------------------
2644 This entrypoint provides the \fB\-\-editbox\fP
2645 functionality without the limitations of \fB\*p\fP's command-line syntax
2646 (compare to \fBdialog_editbox\fP).
2648 .B const char * \fItitle
2649 is the title string to display at the top of the widget.
2652 is a pointer to an array of \fBchar\ *\fP pointers.
2653 The array is allocated by the caller,
2654 and so are the strings to which it points.
2655 The \fBdlg_editbox\fP function may reallocate the
2656 array and the strings.
2659 points to the nominal length of \fIlist\fP.
2660 The referenced value is updated if\fIlist\fP is reallocated.
2663 is the desired height of the box.
2664 If zero, the height is adjusted to use the available screen size.
2667 is the desired width of the box.
2668 If zero, the height is adjusted to use the available screen size.
2669 .\" ---------------------------------------------------------------------------
2671 This entrypoint provides the \fB\-\-form\fP
2672 functionality without the limitations of \fB\*p\fP's command-line syntax
2673 (compare to \fBdialog_form\fP).
2675 .B const char * \fItitle
2676 is the title string to display at the top of the widget.
2678 .B const char * \fIcprompt
2679 is the prompt text shown within the widget.
2682 is the desired height of the box.
2683 If zero, the height is adjusted to use the available screen size.
2686 is the desired width of the box.
2687 If zero, the height is adjusted to use the available screen size.
2689 .B int \fIform_height
2690 is the minimum height to reserve for displaying the list.
2691 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2694 is the number of \fIitems\fP.
2696 .B DIALOG_FORMITEM * \fIitems
2697 This is a list of the items to display in the form.
2699 .B int * \fIcurrent_item
2700 The widget sets the referenced location to the index of the current display
2701 item (cursor) when it returns.
2702 .\" ---------------------------------------------------------------------------
2703 .SS dlg_free_columns
2704 Free data allocated by \fBdlg_align_columns\fP.
2707 This is the array which was reformatted.
2708 It points to the first string to free.
2711 This is the size of the struct for each row of the array.
2714 This is the number of rows in the array.
2715 .\" ---------------------------------------------------------------------------
2716 .SS dlg_free_formitems
2717 Free memory owned by a list of DIALOG_FORMITEM's.
2719 .B DIALOG_FORMITEM * \fIitems
2720 is the list to free.
2721 .\" ---------------------------------------------------------------------------
2723 Remove the gauge widget from the screen and free its associated memory.
2726 points to the gauge widget.
2727 .\" ---------------------------------------------------------------------------
2729 Read a character from the given window.
2730 Handle repainting here (to simplify
2731 things in the calling application).
2732 Also, if input-callback(s) are set up,
2733 poll the corresponding files and handle the updates,
2734 e.g., for displaying a tailbox.
2735 Returns the key-code.
2738 is the window within which to read.
2741 as a side-effect, set this to true if the key-code is really a function-key.
2742 .\" ---------------------------------------------------------------------------
2744 Get a number from the environment:
2746 If the caller provides a pointer in the second parameter, return
2747 success/failure for the function return, and the actual value via the pointer.
2748 Use this for decoding arbitrary numbers, e.g., negative or zero.
2750 If the caller does not provide a pointer, return the decoded value for
2751 the function-return.
2752 Use this when only values greater than zero are useful.
2755 is the name of the environment-variable to retrieve.
2758 is the optional pointer to a return-value.
2759 .\" ---------------------------------------------------------------------------
2761 Get a string from the environment, rejecting those which are entirely blank.
2764 is the name of the environment-variable to retrieve.
2765 .\" ---------------------------------------------------------------------------
2767 extract the video attributes from the given window.
2770 is the window from which to get attributes.
2771 .\" ---------------------------------------------------------------------------
2772 .SS dlg_getc_callbacks
2773 passes the given key-code \fIch\fP to the current window that
2774 has established a callback.
2775 If the callback returns zero, remove it and try the next window.
2776 If no more callbacks remain, return.
2777 If any callbacks were found, return true, otherwise false.
2783 is true if the key is a function-key
2786 is used to pass an exit-code to the caller,
2787 which should pass that via \fBdlg_exit\fP.
2788 .\" ---------------------------------------------------------------------------
2789 .SS dlg_index_columns
2790 Build a list of the display-columns for the given multibyte string's characters.
2792 .B const char * \fIstring
2793 is the string to analyze
2794 .\" ---------------------------------------------------------------------------
2795 .SS dlg_index_wchars
2796 Build an index of the wide-characters in the string,
2797 so the caller can easily tell
2798 which byte-offset begins a given wide-character.
2800 .B const char * \fIstring
2801 is the string to analyze
2802 .\" ---------------------------------------------------------------------------
2804 Draw the string for the \fBdialog_vars.item_help\fP feature.
2806 .B const char * \fItxt
2808 .\" ---------------------------------------------------------------------------
2810 This performs the check and modifications
2811 for the command-line option "\fB\-\-keep\-tite\fP",
2812 used in \fBinit_dialog\fP as well as for
2813 the command-line option \fB\-\-erase\-on\-exit\fP.
2816 is the output stream used for displaying widgets.
2817 It is either \fIstdout\fP or \fIstderr\fP,
2818 depending on the \fB\-\-stdout\fP option.
2819 .\" ---------------------------------------------------------------------------
2821 If \fB\*p\fP has callbacks active,
2822 purge the list of all that are not marked
2823 to keep in the background.
2824 If any remain, run those in a background process.
2827 stores the exit-code to pass back to the caller.
2828 .\" ---------------------------------------------------------------------------
2830 returns the most recent character that was read via \fBdlg_getc\fP.
2831 .\" ---------------------------------------------------------------------------
2832 .SS dlg_limit_columns
2833 Given a column limit,
2834 count the number of wide characters that can fit into that limit.
2835 The offset is used to skip over a leading character
2836 that was already written.
2838 .B const char * \fIstring
2839 is the string to analyze
2845 is the starting offset from which analysis should continue
2846 .\" ---------------------------------------------------------------------------
2848 Check for a key-binding.
2849 If there is no binding associated with the widget, it simply returns
2850 the given curses-key.
2851 Otherwise, it returns the result of the binding
2854 is the window on which the binding is checked
2856 .B int \fIcurses_key
2857 is the curses key-code
2859 .B int * \fIdialog_key
2860 is the corresponding \fB\*p\fP internal code
2861 (see \fBDLG_KEYS_ENUM\fP in dlg_key.h).
2862 .\" ---------------------------------------------------------------------------
2864 Limit the parameter according to \fBdialog_vars.max_input\fP
2867 is the value to limit
2868 .\" ---------------------------------------------------------------------------
2870 Match a given character against the beginning of the string,
2871 ignoring case of the given character.
2872 The matching string must begin with an uppercase character.
2875 is the character to check
2877 .B const char * \fIstring
2878 is the string to search
2879 .\" ---------------------------------------------------------------------------
2881 This entrypoint provides the \fB\-\-menu\fP
2882 functionality without the limitations of \fB\*p\fP's command-line syntax
2883 (compare to \fBdialog_menu\fP).
2885 .B const char * \fItitle
2886 is the title string to display at the top of the widget.
2888 .B const char * \fIcprompt
2889 is the prompt text shown within the widget.
2892 is the desired height of the box.
2893 If zero, the height is adjusted to use the available screen size.
2896 is the desired width of the box.
2897 If zero, the height is adjusted to use the available screen size.
2899 .B int \fImenu_height
2900 is the minimum height to reserve for displaying the list.
2901 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2904 is the number of \fIitems\fP.
2906 .B DIALOG_LISTITEM * \fIitems
2907 This is a list of the items to display in the form.
2909 .B int * \fIcurrent_item
2910 The widget sets the referenced location to the index of the current display
2911 item (cursor) when it returns.
2913 .B DIALOG_INPUTMENU \fIrename_menutext
2914 If this is not \fBdlg_dummy_menutext\fP,
2915 the widget acts like an \fIinputmenu\fP widget,
2916 providing an extra \*(``Rename\*('' button,
2917 which activates an edit feature on the selected menu item.
2918 .\" ---------------------------------------------------------------------------
2920 Moves/resizes the given window to the given position and size.
2923 is the window to move/resize.
2925 .B WINDOW *\fIheight
2926 is the height of the resized window.
2929 is the width of the resized window.
2932 y-ordinate to use for the repositioned window.
2935 x-ordinate to use for the repositioned window.
2936 .\" ---------------------------------------------------------------------------
2937 .SS dlg_mouse_bigregion
2938 Retrieve the big-region under the pointer.
2941 is the row on which the mouse click occurred
2944 is the column on which the mouse click occurred
2945 .\" ---------------------------------------------------------------------------
2946 .SS dlg_mouse_free_regions
2947 Free the memory associated with mouse regions.
2948 .\" ---------------------------------------------------------------------------
2949 .SS dlg_mouse_mkbigregion
2950 Creates a region on which the mouse-clicks will return a specified code.
2953 is the top-row of the region.
2956 is the left-column of the region.
2959 is the height of the region.
2962 is the width of the region.
2965 is a code used to make the region unique within a widget
2968 is used in modes 2 (columns) and 3 (cells) to determine the width
2975 is used to determine how the mouse position is translated into
2976 a code (like a function-key):
2988 .\" ---------------------------------------------------------------------------
2989 .SS dlg_mouse_mkregion
2992 is the top-row of the region.
2995 is the left-column of the region.
2998 is the height of the region.
3001 is the width of the region.
3004 is a code used to make the region unique within a widget
3005 .\" ---------------------------------------------------------------------------
3006 .SS dlg_mouse_region
3007 Retrieve the frame under the mouse pointer
3010 is the row of the mouse-click
3013 is the column of the mouse-click
3014 .\" ---------------------------------------------------------------------------
3015 .SS dlg_mouse_setbase
3016 Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP,
3017 so they can make regions relative to the start of a given window.
3020 is the left-column for the base
3023 is the top-row for the base
3024 .\" ---------------------------------------------------------------------------
3025 .SS dlg_mouse_setcode
3026 Sets a value used internally by \fBdlg_mouse_mkregion\fP
3027 which is added to the \fIcode\fP parameter.
3028 By providing different values,
3029 e.g., multiples of \fBKEY_MAX\fP,
3030 it is possible to support multiple \*(``big\*('' regions in a widget.
3031 The \fIbuildlist\fP widget uses this feature to recognize mouse-clicks
3032 in the left/right panes.
3035 is the value to add to \fBdlg_mouse_mkregion\fP's \fIcode\fP parameter.
3036 .\" ---------------------------------------------------------------------------
3037 .SS dlg_mouse_wgetch
3038 is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks
3039 (if the curses library supports those) into extended function-keys
3040 which encode the position according to the \fImode\fP in
3041 \fBdlg_mouse_mkbigregion\fP.
3042 Returns the corresponding key-code.
3045 is the window on which to perform the input
3048 the referenced location is set to true if the key-code is an actual
3049 or extended (mouse) function-key.
3050 .\" ---------------------------------------------------------------------------
3051 .SS dlg_mouse_wgetch_nowait
3052 This is a non-blocking variant of \fBdlg_mouse_wgetch\fP.
3055 is the window on which to perform the input
3058 the referenced location is set to true if the key-code is an actual
3059 or extended (mouse) function-key.
3060 .\" ---------------------------------------------------------------------------
3061 .SS dlg_need_separator
3062 Check if an output-separator is needed.
3063 If \fBdialog_vars.output_separator\fP is set, return true.
3064 Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true.
3065 If neither, return false.
3066 .\" ---------------------------------------------------------------------------
3067 .SS dlg_new_modal_window
3068 Create a modal window, optionally with a shadow.
3069 The shadow is created if \fBdialog_state.use_shadow\fP is true.
3071 .B WINDOW * \fIparent
3072 is the parent window (usually the top-level window of a widget)
3075 is the window's height
3078 is the window's width
3081 is the window's top-row
3084 is the window's left-column
3085 .\" ---------------------------------------------------------------------------
3087 Create a window, optionally with a shadow.
3088 The shadow is created if \fBdialog_state.use_shadow\fP is true.
3091 is the window's height
3094 is the window's width
3097 is the window's top-row
3100 is the window's left-column
3101 .\" ---------------------------------------------------------------------------
3103 Return the next index in the list of labels.
3105 .B const char ** \fIlabels
3106 is a list of (pointers to) button labels terminated by a null pointer.
3109 is the current button-index.
3110 .\" ---------------------------------------------------------------------------
3111 .SS dlg_next_ok_buttonindex
3112 Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons,
3113 find the next index in the list of buttons.
3116 is the current index in the list of buttons
3119 if negative, provides a way to enumerate extra active areas on the widget.
3120 .\" ---------------------------------------------------------------------------
3121 .SS dlg_ok_buttoncode
3122 Map the given button index for \fBdlg_ok_labels\fP
3123 into \fB\*p\fP's exit-code.
3126 is the button-index (which is not necessarily the same as the index
3127 in the list of labels).
3128 .\" ---------------------------------------------------------------------------
3129 .SS dlg_ok_button_key
3130 Calls \fBdlg_button_key\fP with the \*(``Cancel\*('' button disabled,
3131 e.g., for the textbox widget.
3132 .\" ---------------------------------------------------------------------------
3134 Returns a list with the \*(``Ok\*('' label,
3135 and if \fBdialog_vars.help_button\fP is true, the \*(``Help\*('' label as well.
3136 .\" ---------------------------------------------------------------------------
3138 Return a list of button labels for the OK/Cancel group of widgets.
3139 .\" ---------------------------------------------------------------------------
3141 Decode the string as an integer, decrement if greater than zero to make
3142 a curses-ordinate from a dialog-ordinate.
3143 .\" ---------------------------------------------------------------------------
3144 .SS dlg_parse_bindkey
3145 Parse the parameters of the \*(``bindkeys\*('' configuration-file entry.
3146 This expects widget name which may be "*", followed by curses key definition and
3147 then \fB\*p\fP key definition.
3150 is the parameter string to parse.
3151 .\" ---------------------------------------------------------------------------
3153 Parse the configuration file and set up variables.
3154 .\" ---------------------------------------------------------------------------
3156 Open a pipe which ties the standard error and output together.
3157 The \fBpopen\fP function captures only the standard output of a command.
3159 .B const char *\fIcommand
3160 The shell command to run.
3162 .B const char *\fItype
3163 Like \fBpopen\fP, "r" is used to read, and "w" is used to write.
3164 .\" ---------------------------------------------------------------------------
3166 Return the previous index in the list of labels.
3168 .B const char ** \fIlabels
3169 is a list of (pointers to) button labels terminated by a null pointer.
3172 is the current button index
3173 .\" ---------------------------------------------------------------------------
3174 .SS dlg_print_listitem
3175 This is a helper function used for the various \*(``list\*('' widgets,
3176 e.g., checklist, menu, buildlist, treeview.
3177 Each list-widget has \*(``tag\*('' and \*(``description\*('' values
3178 for each item which can be displayed.
3179 If \fBdialog_vars.no_tags\fP is true,
3180 the \*(``tag\*('' value is not shown.
3181 The first character of the first value shown (tag or description)
3182 is highlighted to indicate that the widget will match it for quick navigation.
3185 the window in which to display the text
3187 .B const char *\fItext
3188 the value to display
3191 the number of columns available for printing the text
3194 true if this is the first call (for \*(``tag\*('' and \*(``description\*(''),
3195 and the first character of the value should be highlighted.
3198 nonzero if the text should be displayed using the \*(``selected\*('' colors
3199 .\" ---------------------------------------------------------------------------
3200 .SS dlg_print_scrolled
3201 This is a wrapper for \fBdlg_print_autowrap\fP which allows the user
3202 to scroll too-long prompt text up/down.
3204 See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP
3205 variable used as a parameter here.
3206 It complements this function; you need both.
3207 If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP
3208 parameter, needed for \fBdlg_check_scrolled\fP calls.
3211 is the window to update.
3213 .B const char * \fIprompt
3214 is the string to print
3217 is the starting line-number to write wrapped text.
3220 is the available height for writing the wrapped text
3223 is the width that the wrapping should occur in
3226 is true if the extra functionality for scrolling should be enabled.
3227 If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling.
3228 .\" ---------------------------------------------------------------------------
3230 Print one line of the prompt in the window within the limits of the
3231 specified right margin.
3232 The line will end on a word boundary and a pointer
3233 to the start of the next line is returned, or a NULL pointer if the end of
3237 is the window to update.
3240 holds the starting attributes, and is updated to reflect the final attributes
3241 applied to the string.
3243 .B const char *\fIprompt
3244 is the string to print
3253 returns the ending x-ordinate.
3254 .\" ---------------------------------------------------------------------------
3255 .SS dlg_prev_ok_buttonindex
3256 Find the previous button index in the list from \fBdlg_ok_labels\fP.
3259 is the current index
3262 if negative provides a way to enumerate extra active areas on the widget.
3263 .\" ---------------------------------------------------------------------------
3264 .SS dlg_print_autowrap
3265 Print a string of text in a window, automatically wrap around to the next
3266 line if the string is too long to fit on one line.
3267 Note that the string may contain embedded newlines.
3268 The text is written starting at the top of the window.
3271 is the window to update.
3273 .B const char * \fIprompt
3274 is the string to print
3277 is the nominal height the wrapped string is limited to
3280 is the width that the wrapping should occur in
3281 .\" ---------------------------------------------------------------------------
3283 If \fBdialog_vars.print_siz\fP is true,
3284 print the given height/width (from a widget)
3285 to \fBdialog_state.output\fP, e.g.,
3286 \fBSize: height, width\fP.
3289 is the window's height
3292 is the window's width
3293 .\" ---------------------------------------------------------------------------
3295 Print up to \fIcols\fP columns from \fBtext\fP,
3296 optionally rendering \fB\*p\fP's escape sequences for attributes and color.
3299 is the window to update.
3301 .B const char * \fItxt
3302 is the string to print
3308 holds the starting attributes, and is updated to reflect the final attributes
3309 applied to the string.
3310 .\" ---------------------------------------------------------------------------
3312 implements the "\fB\-\-prgbox\fP" and "\fB\-\-progressbox\fP" options.
3314 .B const char * \fItitle
3315 is the title on the top of the widget.
3317 .B const char * \fIcprompt
3318 is the prompt text shown within the widget.
3319 If empty or null, no prompt is shown.
3322 is the desired height of the box.
3323 If zero, the height is based on the screen size.
3326 is the desired width of the box.
3327 If zero, the height is based on the screen size.
3330 if true, an \*(``OK\*('' button will be shown,
3331 and the dialog will wait for it to complete.
3332 With an \*(``OK\*('' button, it is denoted a \*(``programbox\*('',
3333 without an \*(``OK\*('' button, it is denoted a \*(``progressbox\*(''.
3336 is the file pointer, which may be a pipe or a regular file.
3337 .\" ---------------------------------------------------------------------------
3338 .SS dlg_put_backtitle
3339 Display the background title if \fBdialog_vars.backtitle\fP is non-null.
3340 The background title is shown at the top of the screen.
3341 .\" ---------------------------------------------------------------------------
3342 .SS dlg_reallocate_gauge
3343 Allocates or reallocates a gauge widget (see \fBdlg_allocate_gauge\fP).
3344 Use \fBdlg_update_gauge\fP to display the result.
3346 .B void ** \fIobjptr
3347 If the pointer referenced by this parameter is null, the function creates
3348 a new gauge widget using \fBdlg_allocate_gauge\fP.
3349 Otherwise, it updates the title and cprompt values, reusing the window
3350 from the previous call on this function.
3351 As a side-effect, the function stores the updated object-pointer via
3352 the \fIobjptr\fP parameter.
3354 .B const char * \fItitle
3355 is the title string to display at the top of the widget.
3357 .B const char * \fIcprompt
3358 is the prompt text shown within the widget.
3361 is the desired height of the box.
3362 If zero, the height is adjusted to use the available screen size.
3365 is the desired width of the box.
3366 If zero, the height is adjusted to use the available screen size.
3369 is the percentage to show in the progress bar.
3370 .\" ---------------------------------------------------------------------------
3371 .SS dlg_register_buttons
3372 The widget developer should call this function after \fBdlg_register_window\fP,
3373 for the list of button labels associated with the widget.
3374 One may bind a key to a button, e.g., \*(``OK\*('' for \fBDLGK_OK\fP,
3377 is the window with which to associate the buttons
3379 .B const char * \fIname
3380 is the widget's binding name (usually the name of the widget).
3382 .B const char ** \fIbuttons
3383 is the list of buttons
3384 .\" ---------------------------------------------------------------------------
3385 .SS dlg_register_window
3386 For a given named widget's window, associate a binding table.
3389 is the window with which to associate the buttons
3391 .B const char * \fIname
3392 is the widget's binding name (usually the name of the widget).
3394 .B DLG_KEYS_BINDING * \fIbinding
3395 is the binding table
3396 .\" ---------------------------------------------------------------------------
3397 .SS dlg_remove_callback
3400 .B DIALOG_CALLBACK * \fIp
3401 contains the callback information.
3402 .\" ---------------------------------------------------------------------------
3403 .SS dlg_renamed_menutext
3404 This is a utility function which supports the \fB\-\-inputmenu\fP option of
3405 the \fB\*p\fP program.
3406 If \fBdialog_vars.input_menu\fP is set, \fBdialog_menu\fP passes this
3407 pointer to \fBdlg_menu\fP as the \fIrename_menutext\fP parameter.
3408 Otherwise, it passes \fBdlg_dummy_menutext\fP.
3410 The function should add \*(``RENAMED\*('' to \fBdialog_vars.input_result\fP ,
3411 followed by the menu item's name and the \fInewtext\fP value
3412 (with a space separating the three items),
3413 and return \fBDLG_EXIT_EXTRA\fP.
3415 .B DIALOG_LISTITEM * \fIitems
3416 is the list of menu items
3419 is the index of the currently-selected item
3421 .B char * \fInewtext
3422 is the updated text for the menu item
3423 .\" ---------------------------------------------------------------------------
3424 .SS dlg_reset_timeout
3425 Calls \fBwtimeout\fP with the value saved for a window in the
3426 last call to \fBdlg_set_timeout\fP.
3427 .\" ---------------------------------------------------------------------------
3428 .SS dlg_restore_vars
3429 Restore \fB\*p\fP's variables from the given variable
3430 (see \fBdialog_save_vars\fP).
3432 .B DIALOG_VARS * \fIsave
3433 is the variable from which to restore.
3436 \fIDIALOG_VARS.input_length\fP and
3437 \fIDIALOG_VARS.input_result\fP members are treated specially,
3438 since these are used by a widget to pass data to the caller.
3439 They are not modified by this function.
3440 .\" ---------------------------------------------------------------------------
3442 Test a \fB\*p\fP internal keycode to see if it corresponds to one of the push
3443 buttons on the widget such as \*(``OK\*(''.
3444 This is only useful if there are user-defined key bindings, since there are
3445 no built-in bindings that map directly to \fBDLGK_OK\fP, etc.
3446 Return true if a mapping was done.
3448 .B int \fIdialog_key
3449 is the \fB\*p\fP key to test
3452 is true if this is a function key
3455 store the result of the mapping in the referenced location.
3456 .\" ---------------------------------------------------------------------------
3458 Save \fB\*p\fP's variables into the given variable (see \fBdlg_restore_vars\fP).
3460 .B DIALOG_VARS * \fIsave
3461 is the variable into which to save.
3462 .\" ---------------------------------------------------------------------------
3464 Set focus on the given window,
3465 making it display above other windows on the screen.
3467 .B WINDOW * \fIparent
3468 is the parent window (usually the top-level window of a widget)
3471 is the window on which to place focus (usually a subwindow of a widget)
3472 .\" ---------------------------------------------------------------------------
3474 Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP
3476 .B const char * \fIstring
3477 is the new contents for the result
3478 .\" ---------------------------------------------------------------------------
3480 Calls \fBwtimeout\fP to establish a preferred timeout for nonblocking
3481 reads, e.g., to allow the gauge widget to handle window-resizing events.
3482 The \fBdlg_may_resize\fP function temporarily overrides this value,
3483 to allow it to skip over the error codes returned while the ncurses
3484 library processes window-resizing events.
3485 It restores the value established in this call
3486 by calling \fBdlg_restore_timeout\fP.
3489 is the window whose input-timeout should be set
3491 .B bool \fIwill_getc
3492 is true if the widget is expected to read keyboard characters.
3493 Some (such as the gauge widget) do not.
3494 .\" ---------------------------------------------------------------------------
3496 Displays the string, shifted as necessary, to fit within the box and show
3497 the current character-offset.
3500 is the window within which to display
3502 .B const char * \fIstring
3503 is the string to display
3506 is the starting (character, not bytes) offset
3509 is the window attribute to use for the string
3512 beginning row on screen
3515 beginning column on screen
3518 number of columns on screen
3521 if true, do not echo input
3524 if true, force repaint
3525 .\" ---------------------------------------------------------------------------
3527 duplicate the string, like \fBstrdup\fP.
3529 .B const char * \fIcprompt
3530 is the string to duplicate
3531 .\" ---------------------------------------------------------------------------
3533 compare two strings, ignoring case.
3535 .B const char * \fIa
3538 .B const char * \fIb
3540 .\" ---------------------------------------------------------------------------
3541 .SS dlg_string_to_argv
3542 Convert a string to an argument vector
3543 returning an index (which must be freed by the caller).
3544 The string is modified:
3546 Blanks between arguments are replaced by nulls.
3548 Normally arguments are separated by blanks;
3549 however you can double-quote an argument to enclose blanks.
3550 The surrounding double-quotes are removed from the string.
3552 A backslash preceding a double-quote within double-quotes is removed.
3554 A backslash preceding a newline outside double-quotes is removed.
3556 Except for special cases, backslashes are preserved in the strings,
3557 since other \fB\*l\fP functions interpret backslashes, e.g., for colors.
3560 is the string to convert.
3561 .\" ---------------------------------------------------------------------------
3563 create a subwindow, e.g., for an input area of a widget
3566 is the parent window
3569 is the subwindow's height
3572 is the subwindow's width
3575 is the subwindow's top-row
3578 is the subwindow's left-column
3579 .\" ---------------------------------------------------------------------------
3580 .SS dlg_tab_correct_str
3581 If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces.
3582 Return the converted result.
3583 The caller is responsible for freeing the string.
3586 is the string to convert
3587 .\" ---------------------------------------------------------------------------
3589 If the parameter is non-null, opens a trace file with that
3590 name and stores the file pointer in \fBdialog_state.trace\fP.
3591 .\" ---------------------------------------------------------------------------
3593 logs a numeric value as a comment.
3596 is the name to log in the comment.
3599 is the value to log in the comment.
3600 .\" ---------------------------------------------------------------------------
3602 logs a string value as a comment.
3603 If the value contains embedded newlines,
3604 the comment is continued with \*(``#+\*('' markers.
3607 is the name to log in the comment.
3610 is the value to log in the comment.
3611 .\" ---------------------------------------------------------------------------
3613 If \fBdialog_state.trace\fP is set,
3614 translate the parameters into a printable representation,
3615 log it on a \*(``chr\*('' line.
3618 is the nominal keycode value.
3621 is nonzero if the value is really a function key.
3622 Some of these may be values declared in the DLG_KEYS_ENUM.
3623 .\" ---------------------------------------------------------------------------
3625 Write a formatted message to the trace file.
3627 .B const char * \fIfmt
3628 is the format of the \fBprintf\fP-like message to write.
3632 are the variables to apply to the \fIfmt\fP format.
3634 Use the DLG_TRACE macro for portability, in case the trace
3635 feature is not compiled into the library.
3636 It uses an extra level of parentheses to work with a variable number of
3639 DLG_TRACE(("this is dialog version %s\en", dialog_version()));
3641 .\" ---------------------------------------------------------------------------
3642 .SS dlg_trace_va_msg
3643 Write a formatted message to the trace file.
3645 .B const char *\fIfmt
3646 is the format of the \fBprintf\fP-like message to write.
3649 are the variables to apply to the \fIfmt\fP format.
3651 This is used in \fBdlg_exiterr\fP to capture error messages in the trace file:
3654 dlg_trace_msg("## Error: ");
3655 dlg_trace_va_msg(fmt, ap);
3659 Unlike \fBdlg_trace_msg\fP, an extra macro is not needed.
3660 .\" ---------------------------------------------------------------------------
3662 Returns the screensize without using curses.
3663 That allows the function to be used before initializing the screen.
3664 .\" ---------------------------------------------------------------------------
3666 If \fBdialog_state.trace\fP is set,
3667 log a printable picture of the given window.
3668 .\" ---------------------------------------------------------------------------
3670 This is an alternate interface to 'treeview' which allows the application
3671 to read the list item states back directly without putting them in the
3674 .B const char * \fItitle
3675 is the title on the top of the widget.
3677 .B const char * \fIcprompt
3678 is the prompt text shown within the widget.
3681 is the desired height of the box.
3682 If zero, the height is based on the screen size.
3685 is the desired width of the box.
3686 If zero, the height is based on the screen size.
3688 .B int \fIlist_height
3689 is the minimum height to reserve for displaying the list.
3690 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
3693 is the number of rows in \fIitems\fP.
3695 .B DIALOG_LISTITEM * \fIitems
3696 is the list of items, contain tag, name, and optionally help strings
3697 (if \fBdialog_vars.item_help\fP is set).
3698 The initial selection state for each item is also in this list.
3700 .B const char * \fIstates
3701 This is a list of characters to display for the given states.
3702 Normally a buildlist provides true (1) and false (0) values,
3703 which the widget displays as "*" and space, respectively.
3704 An application may set this parameter to an arbitrary null-terminated string.
3705 The widget determines the number of states from the length of this string,
3706 and will cycle through the corresponding display characters as the user
3707 presses the space-bar.
3710 This is a list of depths of each item in the tree.
3711 It is a separate parameter from \fIitems\fP to allow reuse of
3712 the existing functions.
3715 is either \fIFLAG_CHECK\fP, for checklists (multiple selections),
3716 or \fIFLAG_RADIO\fP for radiolists (a single selection).
3718 .B int * \fIcurrent_item
3719 The widget sets the referenced location to the index of the current display
3720 item (cursor) when it returns.
3721 .\" ---------------------------------------------------------------------------
3723 The \fB\*p\fP program uses this in each widget to adjust the
3725 which may contain the newline character (referred to as '\en')
3726 and/or the special substring "\en"
3727 (which can be translated into a newline character).
3729 There are several optional features:
3731 Unless \fBdialog_vars.nocollapse\fP is set,
3732 each tab is converted to a space before other processing.
3734 If \fBdialog_vars.no_nl_expand\fP is not set,
3735 and the string has "\en" substrings:
3738 The function changes embedded "\en" substrings to '\en' characters.
3740 The function preserves extra spaces after these substitutions.
3741 For instance, spaces following a newline (substring or character)
3742 are preserved to use as an indentation.
3744 If \fBdialog_vars.cr_wrap\fP is set,
3745 the function preserves '\en' newline characters.
3746 Otherwise, each '\en' newline character is converted to a space.
3749 Otherwise, if \fBdialog_vars.trim_whitespace\fP is set:
3752 This function strips all extra spaces to simplify justification.
3754 If \fBdialog_vars.cr_wrap\fP is set,
3755 the function preserves '\en' newline characters.
3756 Otherwise, each '\en' newline character is converted to a space.
3760 (if \fBdialog_vars.no_nl_expand\fP is set,
3761 or the string does not contain "\en" substrings,
3762 and \fBdialog_vars.trim_whitespace\fP is not set):
3765 Unless \fBdialog_vars.nocollapse\fP is set,
3766 sequences of spaces are reduced to a single space.
3770 is the string to trim
3771 .\" ---------------------------------------------------------------------------
3772 .SS dlg_unregister_window
3773 Remove the bindings for a given window.
3776 is the window from which to remove bindings
3777 .\" ---------------------------------------------------------------------------
3778 .SS dlg_update_gauge
3779 Update a gauge widget to show a different percentage value.
3782 points to the gauge object to update.
3785 is the new percentage value to display.
3786 .\" ---------------------------------------------------------------------------
3788 This filters out bursts of \fBKEY_RESIZE\fP values.
3789 Call this after \fBdlg_getc\fP returns \fBKEY_RESIZE\fP,
3790 to improve performance.
3791 .\" ---------------------------------------------------------------------------
3792 .SS dlg_yes_buttoncode
3793 Map the given button index for \fBdlg_yes_labels\fP into \fB\*p\fP's exit-code.
3797 .\" ---------------------------------------------------------------------------
3799 Return a list of buttons for Yes/No labels.
3800 .\" ---------------------------------------------------------------------------
3802 End use of \fB\*p\fP functions.
3803 .\" ---------------------------------------------------------------------------
3805 Do some initialization for \fB\*p\fP.
3808 is the real tty input of \fB\*p\fP.
3809 Usually it is the standard input, but if
3810 \fB\-\-input\-fd\fP option is used, it may be anything.
3813 is where \fB\*p\fP will send its result.
3814 Usually it is the standard error, but
3815 if \fB\-\-stdout\fP or \fB\-\-output\-fd\fP is used, it may be anything.
3817 .\" ************************************************************************
3821 .\" ************************************************************************