1 .\" $Id: dialog.3,v 1.49 2010/02/23 10:33:59 tom Exp $
2 .\" Copyright 2005-2009,2010 Thomas E. Dickey
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU Lesser General Public License, version 2.1
6 .\" as published by the Free Software Foundation.
8 .\" This program is distributed in the hope that it will be useful, but
9 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 .\" Lesser General Public License for more details.
13 .\" You should have received a copy of the GNU Lesser General Public
14 .\" License along with this program; if not, write to
15 .\" Free Software Foundation, Inc.
16 .\" 51 Franklin St., Fifth Floor
17 .\" Boston, MA 02110, USA.
18 .TH DIALOG 3 "" "$Date: 2010/02/23 10:33:59 $"
20 dialog \- widgets and utilities for the dialog program
22 .B cc [ flag ... ] file ... -ldialog [ library ... ]
24 .B #include <dialog.h>
27 is a program that will let you to present a variety of questions or
28 display messages using dialog boxes from a shell script.
29 It is built from the \fBdialog\fP library,
30 which consists of several widgets
31 as well as utility functions that are used by the widgets
35 This manpage documents the features from \fI<dialog.h>\fP which
36 are likely to be important to developers using the widgets directly.
37 Some hints are also given for developing new widgets.
39 .\" ************************************************************************
41 Exit codes (passed back to the main program for its use)
42 are defined with a "\fIDLG_EXIT_\fP prefix.
43 The defined constants can be mapped using environment variables
44 as described in \fBdialog\fP(1),
45 e.g., \fIDLG_EXIT_OK\fP corresponds to \fI$DIALOG_OK\fP.
47 Useful character constants which correspond to user input
48 are named with the "\fICHR_\fP" prefix, e.g.,
51 Colors and video attributes are categorized and associated with
52 settings in the configuration file
53 (see the discussion of \fI$DIALOGRC\fP in \fBdialog\fP(1)).
54 The \fIDIALOG_ATR(n)\fP macro is used for defining the references
55 to the combined color and attribute table \fIdlg_color_table[]\fP.
57 The \fBdialog\fP application passes its command-line parameters
58 to the widget functions. Some of those parameters are single values,
59 but some of the widgets accept data as an array of values.
60 Those include checklist/radiobox, menubox and formbox.
61 When the \fB--item-help\fP option is given, an extra column
63 The USE_ITEM_HELP(), CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS
64 macros are used to hide this difference from the calling application.
66 Most of the other definitions found in \fI<dialog.h>\fP
67 are used for convenience in building the library or main program.
68 These include definitions based on the generated \fI<dlg_config.h>\fP header.
70 .\" ************************************************************************
72 All of the global data for the \fBdialog\fP library is stored in
73 a few structures: \fIDIALOG_STATE\fP, \fIDIALOG_VARS\fP and \fIDIALOG_COLORS\fP.
74 The corresponding \fIdialog_state\fP, \fIdialog_vars\fP and \fIdlg_color_table\fP
75 global variables should be initialized to zeros,
76 and then populated with the data to use.
77 A few of these must be nonzero for the corresponding widgets to function.
78 As as the case with function names,
79 variables beginning with "\fIdialog_\fP"
80 are designed for use by the calling application
81 while variables beginning with "\fIdlg_\fP"
82 are intended for lower levels, e.g., by the \fBdialog\fP library.
83 .\" ---------------------------------------------------------------------------
84 .IP \fIDIALOG_STATE.all_windows
85 This is a linked list of all windows created by the library.
86 The \fBdlg_del_window\fP function uses this to locate windows which
87 may be redrawn after deleting a window.
88 .\" ---------------------------------------------------------------------------
89 .IP \fIDIALOG_STATE.aspect_ratio
90 This corresponds to the command-line option "\fB--aspect-ratio\fP".
91 The value gives the application
92 some control over the box dimensions when using auto
93 sizing (specifying 0 for height and width).
94 It represents width / height.
95 The default is 9, which means 9 characters wide to every 1 line high.
96 .\" ---------------------------------------------------------------------------
97 .IP \fIDIALOG_STATE.getc_callbacks
98 This is setup in \fIui_getc.c\fP to record windows which must be polled
99 for input, e.g,. to handle the background tailbox widget.
100 One window is designated as the foreground or control window.
101 .\" ---------------------------------------------------------------------------
102 .IP \fIDIALOG_STATE.getc_redirect
103 If the control window for \fIDIALOG_STATE.getc_callbacks\fP is
104 closed, the list is transferred to this variable.
105 Closing all windows causes the application to exit.
106 .\" ---------------------------------------------------------------------------
107 .IP \fIDIALOG_STATE.output
108 This is set in the \fBdialog\fP application to the stream on
109 which the application and library functions may write text results.
110 Normally that is the standard error,
111 since the curses library prefers to write its data to the standard output.
112 Some scripts, trading portability for convenience,
113 prefer to write results to the standard output,
114 e.g., by using the "\fB--stdout\fP" option.
115 .\" ---------------------------------------------------------------------------
116 .IP \fIDIALOG_STATE.output_count
117 This is incremented by \fIdlg_does_output\fP,
118 which is called by each widget that writes text to the output.
119 The \fBdialog\fP application uses that to decide if it should
120 also write a separator, i.e.,
121 \fIDIALOG_STATE.separate_str\fP,
122 between calls to each widget.
123 .\" ---------------------------------------------------------------------------
124 .IP \fIDIALOG_STATE.pipe_input
125 This is set in \fIinit_dialog\fP to a stream which can be used by the
126 \fBgauge\fP widget, which must be the application's standard input.
127 The \fBdialog\fP application calls \fIinit_dialog\fP normally with
128 \fIinput\fP set to the standard input, but optionally based on the
129 "\fB--input-fd\fP" option.
130 Since the application cannot read from
131 a pipe (standard input) and at the same time read
132 the curses input from the standard input,
133 it must allow for reopening the latter from either
134 a specific file descriptor,
135 or directly from the terminal.
136 The adjusted pipe stream value is stored in this variable.
137 .\" ---------------------------------------------------------------------------
138 .IP \fIDIALOG_STATE.screen_initialized
139 This is set in \fIinit_dialog\fP and
140 reset in \fIend_dialog\fP.
141 It is used to check if curses has been initialized,
142 and if the \fIendwin\fP function must be called on exit.
143 .\" ---------------------------------------------------------------------------
144 .IP \fIDIALOG_STATE.screen_output
145 This is set in \fIinit_dialog\fP to the output stream used
146 by the curses library.
147 Normally that is the standard output,
148 unless that happens to not be a terminal (and if \fIinit_dialog\fP can
149 successfully open the terminal directly).
150 .\" ---------------------------------------------------------------------------
151 .IP \fIDIALOG_STATE.separate_str
152 This corresponds to the command-line option "\fB--separate-widget\fP".
154 specifies a string that will separate the output on \fBdialog\fP's output from
156 This is used to simplify parsing the result of a dialog with several widgets.
157 If this option is not given,
158 the default separator string is a tab character.
159 .\" ---------------------------------------------------------------------------
160 .IP \fIDIALOG_STATE.tab_len
161 This corresponds to the command-line option "\fB--tab-len\fP \fInumber\fP".
162 Specify the number of spaces that a tab character occupies if the
163 "\fB--tab-correct\fP"
166 .\" ---------------------------------------------------------------------------
167 .IP \fIDIALOG_STATE.use_colors
168 This is set in \fIinit_dialog\fP if the curses implementation supports color.
169 .\" ---------------------------------------------------------------------------
170 .IP \fIDIALOG_STATE.use_scrollbar
171 This corresponds to the command-line option "\fB--scrollbar\fP".
173 draw a scrollbar to make windows holding scrolled data more readable.
174 .\" ---------------------------------------------------------------------------
175 .IP \fIDIALOG_STATE.use_shadow
176 This corresponds to the command-line option "\fB--no-shadow\fP".
177 This is set in \fIinit_dialog\fP if the curses implementation supports color.
179 suppress shadows that would be drawn to the right and bottom of each dialog box.
180 .\" ---------------------------------------------------------------------------
181 .IP \fIDIALOG_STATE.visit_items
182 This corresponds to the command-line option "\fB--visit-items\fP".
183 .\" ---------------------------------------------------------------------------
185 The \fBdialog\fP application resets the \fIdialog_vars\fP data before
186 accepting options to invoke each widget.
187 Most of the \fIDIALOG_VARS\fP members are set directly from \fBdialog\fP's
188 command-line options:
189 .\" ---------------------------------------------------------------------------
190 .IP \fIDIALOG_VARS.ascii_lines
191 .\" ---------------------------------------------------------------------------
192 .IP \fIDIALOG_VARS.backtitle
193 This corresponds to the command-line option "\fB--backtitle\fP \fIbacktitle\fP".
196 string to be displayed on the backdrop, at the top of the screen.
197 .\" ---------------------------------------------------------------------------
198 .IP \fIDIALOG_VARS.beep_after_signal
199 This corresponds to the command-line option "\fB--beep-after\fP".
200 If true, beep after a user has completed a widget by pressing one of the buttons.
201 .\" ---------------------------------------------------------------------------
202 .IP \fIDIALOG_VARS.beep_signal
203 This corresponds to the command-line option "\fB--beep\fP".
205 .\" ---------------------------------------------------------------------------
206 .IP \fIDIALOG_VARS.begin_set
207 This is true if the command-line option "\fB--begin y x\fP" was used.
208 It specifies the position of the upper left corner of a dialog box on the screen.
209 .\" ---------------------------------------------------------------------------
210 .IP \fIDIALOG_VARS.begin_x
211 This corresponds to the \fIx\fP value from
212 the command-line option "\fB--begin\fP \fIy x\fP" (second value).
213 .\" ---------------------------------------------------------------------------
214 .IP \fIDIALOG_VARS.begin_y
215 This corresponds to the \fIy\fP value from
216 the command-line option "\fB--begin\fP \fIy x\fP" (first value).
217 .\" ---------------------------------------------------------------------------
218 .IP \fIDIALOG_VARS.cancel_label
219 This corresponds to the command-line option "\fB--cancel-label\fP \fIstring\fP".
220 The given \fIstring\fP overrides the label used for "Cancel" buttons.
221 .\" ---------------------------------------------------------------------------
222 .IP \fIDIALOG_VARS.cant_kill
223 This corresponds to the command-line option "\fB--no-kill\fP".
228 box in the background,
229 printing its process id to \fBdialog\fP's output.
230 SIGHUP is disabled for the background process.
231 .\" ---------------------------------------------------------------------------
232 .IP \fIDIALOG_VARS.colors
233 This corresponds to the command-line option "\fB--colors\fP".
234 If true, interpret embedded "\\Z" sequences in the dialog text
235 by the following character,
236 which tells dialog to set colors or video attributes:
237 0 through 7 are the ANSI codes used in curses:
246 Bold is set by 'b', reset by 'B'.
247 Reverse is set by 'r', reset by 'R'.
248 Underline is set by 'u', reset by 'U'.
249 The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
251 Restore normal settings with "\\Zn".
252 .\" ---------------------------------------------------------------------------
253 .IP \fIDIALOG_VARS.column_separator
254 .\" ---------------------------------------------------------------------------
255 .IP \fIDIALOG_VARS.cr_wrap
256 This corresponds to the command-line option "\fB--cr-wrap\fP".
258 interpret embedded newlines in the dialog text as a newline on the screen.
259 Otherwise, \fBdialog\fR will only wrap lines where needed to fit inside the text box.
260 Even though you can control line breaks with this,
261 \fBdialog\fR will still wrap any lines that are too long for the width of the box.
262 Without cr-wrap, the layout of your text may be formatted to look nice
263 in the source code of your script without affecting the way it will
265 .\" ---------------------------------------------------------------------------
266 .IP \fIDIALOG_VARS.date_format
267 This corresponds to the command-line option "\fB--date-format\fP \fIstring\fP".
268 If the host provides \fBstrftime\fP, and the value is nonnull,
269 the calendar widget uses this to format its output.
270 .\" ---------------------------------------------------------------------------
271 .IP \fIDIALOG_VARS.default_item
272 This corresponds to the command-line option "\fB--default-item\fP \fIstring\fP".
273 The given string is used as
274 the default item in a checklist, form or menu box.
275 Normally the first item in the box is the default.
276 .IP \fIDIALOG_VARS.defaultno
277 This corresponds to the command-line option "\fB--defaultno\fP".
279 make the default value of the
283 Likewise, make the default button of widgets that provide "OK" and "Cancel"
285 If \fB--nocancel\fP was given that option overrides this,
286 making the default button always "Yes" (internally the same as "OK").
287 .\" ---------------------------------------------------------------------------
288 .IP \fIDIALOG_VARS.dlg_clear_screen
289 This corresponds to the command-line option "\fB--clear\fP".
290 This option is implemented in the main program, not the library.
292 the screen will be cleared on exit.
293 This may be used alone, without other options.
294 .\" ---------------------------------------------------------------------------
295 .IP \fIDIALOG_VARS.exit_label
296 This corresponds to the command-line option "\fB--exit-label string\fP".
297 The given string overrides the label used for "EXIT" buttons.
298 .\" ---------------------------------------------------------------------------
299 .IP \fIDIALOG_VARS.extra_button
300 This corresponds to the command-line option "\fB--extra-button\fP".
301 If true, some widgets show an extra button,
302 between "OK" and "Cancel" buttons.
303 .\" ---------------------------------------------------------------------------
304 .IP \fIDIALOG_VARS.extra_label
305 This corresponds to the command-line option "\fB--extra-label\fP \fIstring\fP".
306 The given string overrides the label used for "Extra" buttons.
307 Note: for inputmenu widgets, this defaults to "Rename".
308 .\" ---------------------------------------------------------------------------
309 .IP \fIDIALOG_VARS.formitem_type
310 This is set by the command-line option "\fB--passwordform\fP"
311 to tell the form widget that its text fields should be treated like
313 .\" ---------------------------------------------------------------------------
314 .IP \fIDIALOG_VARS.help_button
315 This corresponds to the command-line option "\fB--help-button\fP".
316 If true, some widgets show a help-button after "OK" and "Cancel" buttons,
317 i.e., in checklist, radiolist and menu boxes.
318 If \fB--item-help\fR is also given, on exit
319 the return status will be the same as for the "OK" button,
320 and the item-help text will be written to \fBdialog\fP's output after the token "HELP".
321 Otherwise, the return status will indicate that the Help button was pressed,
322 and no message printed.
323 .\" ---------------------------------------------------------------------------
324 .IP \fIDIALOG_VARS.help_label
325 This corresponds to the command-line option "\fB--help-label\fP \fIstring\fP".
326 The given string overrides the label used for "Help" buttons.
327 .\" ---------------------------------------------------------------------------
328 .IP \fIDIALOG_VARS.help_status
329 This corresponds to the command-line option "\fB--help-status\fP".
330 If true, and the the help-button is selected,
331 writes the checklist or radiolist information
332 after the item-help "HELP" information.
333 This can be used to reconstruct the state of a checklist after processing
335 .\" ---------------------------------------------------------------------------
336 .IP \fIDIALOG_VARS.input_length
337 This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated,
338 versus being a pointer to the user's local variables.
339 .\" ---------------------------------------------------------------------------
340 .IP \fIDIALOG_VARS.input_menu
341 This flag is set to denote whether the menubox widget
342 implements a menu versus a inputmenu widget.
343 .\" ---------------------------------------------------------------------------
344 .IP \fIDIALOG_VARS.input_result
345 If \fIDIALOG_VARS.input_length\fP is zero,
346 this is a pointer to user buffer (on the stack, or static).
347 When \fIDIALOG_VARS.input_length\fP is nonzero,
348 this is a dynamically-allocated buffer used by the widgets to return
349 printable results to the calling application.
350 .\" ---------------------------------------------------------------------------
351 .IP \fIDIALOG_VARS.insecure
352 This corresponds to the command-line option "\fB--insecure\fP".
353 If true, make the password widget friendlier but less secure,
354 by echoing asterisks for each character.
355 .\" ---------------------------------------------------------------------------
356 .IP \fIDIALOG_VARS.item_help
357 This corresponds to the command-line option "\fB--item-help\fP".
359 interpret the tags data for checklist, radiolist and menu boxes
360 adding a column whose text is displayed in the bottom line of the
361 screen, for the currently selected item.
362 .\" ---------------------------------------------------------------------------
363 .IP \fIDIALOG_VARS.keep_tite
364 This is set by the command-line option "\fB--keep-tite\fP"
365 to tell \fBdialog\fP to not attempt to cancel the terminal initialization
366 (termcap \fIti\fP/\fIte\fP) sequences which correspond to xterm's alternate-screen
368 Normally \fBdialog\fP does this to avoid flickering when run several times
370 .\" ---------------------------------------------------------------------------
371 .IP \fIDIALOG_VARS.keep_window
372 This corresponds to the command-line option "\fB--keep-window\fP".
373 If true, do not remove/repaint the window on exit.
374 This is useful for keeping the window contents visible when several
375 widgets are run in the same process.
376 Note that curses will clear the screen when starting a new process.
377 .\" ---------------------------------------------------------------------------
378 .IP \fIDIALOG_VARS.max_input
379 This corresponds to the command-line option "\fB--max-input\fP \fIsize\fP".
380 Limit input strings to the given size.
381 If not specified, the limit is 2048.
382 .\" ---------------------------------------------------------------------------
383 .IP \fIDIALOG_VARS.no_label
384 This corresponds to the command-line option "\fB--no-label\fP \fIstring\fP".
385 The given string overrides the label used for "No" buttons.
386 .\" ---------------------------------------------------------------------------
387 .IP \fIDIALOG_VARS.no_lines
388 .\" ---------------------------------------------------------------------------
389 .IP \fIDIALOG_VARS.nocancel
390 This corresponds to the command-line option "\fB--no-cancel\fP".
392 suppress the "Cancel" button in checklist, inputbox and menu box modes.
393 A script can still test if the user pressed the ESC key to cancel to quit.
394 .\" ---------------------------------------------------------------------------
395 .IP \fIDIALOG_VARS.nocollapse
396 This corresponds to the command-line option "\fB--no-collapse\fP".
397 Normally \fBdialog\fR converts tabs to spaces and reduces multiple
398 spaces to a single space for text which is displayed in a message boxes, etc.
399 It true, that feature is disabled.
400 Note that \fBdialog\fR will still wrap text, subject to the \fB--cr-wrap\fR
402 .\" ---------------------------------------------------------------------------
403 .IP \fIDIALOG_VARS.nook
404 .\" ---------------------------------------------------------------------------
405 .IP \fIDIALOG_VARS.ok_label
406 This corresponds to the command-line option "\fB--ok-label\fP \fIstring\fP".
407 The given string overrides the label used for "OK" buttons.
408 .\" ---------------------------------------------------------------------------
409 .IP \fIDIALOG_VARS.print_siz
410 This corresponds to the command-line option "\fB--print-size\fP".
412 each widget prints its size to \fBdialog\fP's output when it is invoked.
413 .\" ---------------------------------------------------------------------------
414 .IP \fIDIALOG_VARS.quoted
415 .\" ---------------------------------------------------------------------------
416 .IP \fIDIALOG_VARS.separate_output
417 This corresponds to the command-line option "\fB--separate-output\fP".
419 checklist widgets output result one line at a time, with no quoting.
420 This facilitates parsing by another program.
421 .\" ---------------------------------------------------------------------------
422 .IP \fIDIALOG_VARS.single_quoted
423 This corresponds to the command-line option "\fB--single-quoted\fP".
425 Use single-quoting as needed (and no quotes if unneeded) for the
426 output of checklist's as well as the item-help text.
427 If this option is not set, \fBdialog\fP uses double quotes around each item.
428 That requires occasional use of backslashes to make the output useful in
430 .IP \fIDIALOG_VARS.size_err
431 This corresponds to the command-line option "\fB--size-err\fP".
433 check the resulting size of a dialog box before trying to use it,
434 printing the resulting size if it is larger than the screen.
435 (This option is obsolete, since all new-window calls are checked).
436 .\" ---------------------------------------------------------------------------
437 .IP \fIDIALOG_VARS.sleep_secs
438 This corresponds to the command-line option "\fB--sleep\fP \fIsecs\fP".
439 This option is implemented in the main program, not the library.
440 If nonzero, this is the number of seconds after to delay after processing a dialog box.
441 .\" ---------------------------------------------------------------------------
442 .IP \fIDIALOG_VARS.tab_correct
443 This corresponds to the command-line option "\fB--tab-correct\fP".
444 If true, convert each tab character of the text to one or more spaces.
445 Otherwise, tabs are rendered according to the curses library's interpretation.
446 .\" ---------------------------------------------------------------------------
447 .IP \fIDIALOG_VARS.time_format
448 This corresponds to the command-line option "\fB--time-format\fP \fIstring\fP".
449 If the host provides \fBstrftime\fP, and the value is nonnull,
450 the timebox widget uses this to format its output.
451 .\" ---------------------------------------------------------------------------
452 .IP \fIDIALOG_VARS.timeout_secs
453 This corresponds to the command-line option "\fB--timeout\fP \fIsecs\fP".
454 If nonzero, timeout input requests (exit with error code)
455 if no user response within the given number of seconds.
456 .\" ---------------------------------------------------------------------------
457 .IP \fIDIALOG_VARS.title
458 This corresponds to the command-line option "\fB--title\fP \fItitle\fP".
461 string to be displayed at the top of the dialog box.
462 .\" ---------------------------------------------------------------------------
463 .IP \fIDIALOG_VARS.trim_whitespace
464 This corresponds to the command-line option "\fB--trim\fP".
465 If true, eliminate leading blanks,
466 trim literal newlines and repeated blanks from message text.
467 .\" ---------------------------------------------------------------------------
468 .IP \fIDIALOG_VARS.visit_items
469 This corresponds to the command-line option "\fB--visit-items\fP".
470 Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
471 to include the list of items as one of the states.
472 This is useful as a visual aid,
473 i.e., the cursor position helps some users.
474 .\" ---------------------------------------------------------------------------
475 .IP \fIDIALOG_VARS.yes_label
476 This corresponds to the command-line option "\fB--yes-label\fP \fIstring\fP".
477 The given string overrides the label used for "Yes" buttons.
479 .\" ************************************************************************
480 .\" ************************************************************************
482 Functions that implement major functionality for the command-line \fBdialog\fP
483 program, e.g., widgets, have names beginning "\fIdialog_\fP".
485 All dialog boxes have at least three parameters:
488 the caption for the box, shown on its top border.
491 the height of the dialog box.
494 the width of the dialog box.
496 Other parameters depend on the box type.
498 .\" ************************************************************************
499 .IP \fBdialog_calendar
500 implements the "\fB--calendar\fP" option.
503 is the title on the top of the widget.
505 is the prompt text shown within the widget.
507 is the height excluding the fixed-height calendar grid.
509 is the overall width of the box,
510 which is adjusted up to the calendar grid's minimum width if needed.
512 is the initial day of the week shown,
513 counting zero as Sunday.
514 If the value is negative,
515 the current day of the week is used.
517 is the initial month of the year shown,
518 counting one as January.
519 If the value is negative,
520 the current month of the year is used.
522 is the initial year shown.
523 If the value is negative,
524 the current year is used.
526 .\" ************************************************************************
527 .IP \fBdialog_checklist
528 implements the "\fB--checklist\fP" and "\fB--radiolist\fP" options
529 depending on the \fIflag\fP parameter.
532 is the title on the top of the widget.
534 is the prompt text shown within the widget.
536 is the desired height of the box.
537 If zero, the height is adjusted to use the available screen size.
539 is the desired width of the box.
540 If zero, the height is adjusted to use the available screen size.
542 is the minimum height to reserve for displaying the list.
543 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
545 is the number of rows in \fIitems\fP.
547 is an array of strings which is viewed either as a list of rows
549 \fItag item status \fR
554 \fItag item status help\fR
557 depending on whether \fIdialog_vars.item_help\fP is set.
559 is either \fIFLAG_CHECK\fP, for checklists,
560 or \fIFLAG_RADIO\fP for radiolists.
562 .\" ************************************************************************
563 .IP \fBdialog_dselect
564 implements the "\fB--dselect\fP" option.
567 is the title on the top of the widget.
569 is the preselected value to show in the input-box,
570 which is used also to set the directory- and file-windows.
572 is the height excluding the minimum needed to show the dialog box framework.
573 If zero, the height is based on the screen size.
575 is the desired width of the box.
576 If zero, the height is based on the screen size.
578 .\" ************************************************************************
579 .IP \fBdialog_editbox
580 implements the "\fB--editbox\fP" option.
583 is the title on the top of the widget.
585 is the name of the file from which to read.
587 is the desired height of the box.
588 If zero, the height is adjusted to use the available screen size.
590 is the desired width of the box.
591 If zero, the height is adjusted to use the available screen size.
593 .\" ************************************************************************
595 implements the "\fB--form\fP" option.
598 is the title on the top of the widget.
600 is the prompt text shown within the widget.
602 is the desired height of the box.
603 If zero, the height is adjusted to use the available screen size.
605 is the desired width of the box.
606 If zero, the height is adjusted to use the available screen size.
608 is the minimum height to reserve for displaying the list.
609 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
611 is the number of rows in \fIitems\fP.
613 is an array of strings which is viewed either as a list of rows
615 \fIName NameY NameX Text TextY TextX FLen ILen\fR
620 \fIName NameY NameX Text TextY TextX FLen ILen Help\fR
623 depending on whether \fIdialog_vars.item_help\fP is set.
625 .\" ************************************************************************
626 .IP \fBdialog_fselect
627 implements the "\fB--fselect\fP" option.
630 is the title on the top of the widget.
632 is the preselected value to show in the input-box,
633 which is used also to set the directory- and file-windows.
635 is the height excluding the minimum needed to show the dialog box framework.
636 If zero, the height is based on the screen size.
638 is the desired width of the box.
639 If zero, the height is based on the screen size.
641 .\" ************************************************************************
643 implements the "\fB--gauge\fP" option.
646 is the title on the top of the widget.
648 is the prompt text shown within the widget.
650 is the desired height of the box.
651 If zero, the height is based on the screen size.
653 is the desired width of the box.
654 If zero, the height is based on the screen size.
656 is the percentage to show in the progress bar.
658 .\" ************************************************************************
659 .IP \fBdialog_inputbox
660 implements the "\fB--inputbox\fP" or
661 "\fB--password\fP" option, depending on the value of \fIpassword\fP.
664 is the title on the top of the widget.
666 is the prompt text shown within the widget.
668 is the desired height of the box.
669 If zero, the height is based on the screen size.
671 is the desired width of the box.
672 If zero, the height is based on the screen size.
674 is the initial value of the input box, whose length is taken into account
675 when auto-sizing the width of the dialog box.
677 if true, causes typed input to be echoed as asterisks.
679 .\" ************************************************************************
681 implements the "\fB--menu\fP" or "\fB--inputmenu\fP" option
682 depending on whether \fIdialog_vars.input_menu\fP is set.
685 is the title on the top of the widget.
687 is the prompt text shown within the widget.
689 is the desired height of the box.
690 If zero, the height is based on the screen size.
692 is the desired width of the box.
693 If zero, the height is based on the screen size.
695 is the minimum height to reserve for displaying the list.
696 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
698 is the number of rows in \fIitems\fP.
700 is an array of strings which is viewed either as a list of rows
710 depending on whether \fIdialog_vars.item_help\fP is set.
712 .\" ************************************************************************
713 .IP \fBdialog_mixedform
714 implements the "\fB--mixedform\fP" option.
717 is the title on the top of the widget.
719 is the prompt text shown within the widget.
721 is the desired height of the box.
722 If zero, the height is adjusted to use the available screen size.
724 is the desired width of the box.
725 If zero, the height is adjusted to use the available screen size.
727 is the minimum height to reserve for displaying the list.
728 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
730 is the number of rows in \fIitems\fP.
732 is an array of strings which is viewed either as a list of rows
734 \fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR
739 \fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR
742 depending on whether \fIdialog_vars.item_help\fP is set.
744 .\" ************************************************************************
745 .IP \fBdialog_mixedgauge
746 implements the "\fB--mixedgauge\fP" option
749 is the title on the top of the widget.
751 is the caption text shown within the widget.
753 is the desired height of the box.
754 If zero, the height is based on the screen size.
756 is the desired width of the box.
757 If zero, the height is based on the screen size.
759 is the percentage to show in the progress bar.
761 is the number of rows in \fIitems\fP.
763 is an array of strings which is viewed as a list of \fItag\fP and \fIitem\fP values.
764 The \fItag\fP values are listed, one per row, in the list at the top of
767 The \fIitem\fP values are decoded: digits 0-9 are the following strings
791 A string with a leading "-" character is centered, marked with "%".
792 For example, "-75" is displayed as "75%".
793 Other strings are displayed as is.
795 .\" ************************************************************************
797 implements the "\fB--msgbox\fP" or "\fB--infobox\fP" option
798 depending on whether \fIpauseopt\fP is set.
801 is the title on the top of the widget.
803 is the prompt text shown within the widget.
805 is the desired height of the box.
806 If zero, the height is based on the screen size.
808 is the desired width of the box.
809 If zero, the height is based on the screen size.
811 if true, an "OK" button will be shown,
812 and the dialog will wait for it to complete.
813 With an "OK" button, it is denoted a "msgbox",
814 without an "OK" button, it is denoted an "infobox".
816 .\" ************************************************************************
818 implements the "\fB--pause\fP" option.
821 is the title on the top of the widget.
823 is the desired height of the box.
824 If zero, the height is based on the screen size.
826 is the desired width of the box.
827 If zero, the height is based on the screen size.
829 is the timeout to use for the progress bar.
831 .\" ************************************************************************
832 .IP \fBdialog_progressbox
833 implements the "\fB--progressbox\fP" option.
836 is the title on the top of the widget.
838 is the prompt text shown within the widget.
839 If empty or null, no prompt is shown.
841 is the desired height of the box.
842 If zero, the height is based on the screen size.
844 is the desired width of the box.
845 If zero, the height is based on the screen size.
847 .\" ************************************************************************
848 .IP \fBdialog_tailbox
849 implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option
850 depending on whether \fIbg_task\fP is set.
853 is the title on the top of the widget.
855 is the name of the file to display in the dialog.
857 is the desired height of the box.
858 If zero, the height is based on the screen size.
860 is the desired width of the box.
861 If zero, the height is based on the screen size.
864 the window is added to the callback list in \fIdialog_state\fP,
865 and the application will poll for the window to be updated.
866 Otherwise an "OK" button is added to the window,
867 and it will be closed when the button is activated.
869 .\" ************************************************************************
870 .IP \fBdialog_textbox
871 implements the "\fB--textbox\fP" option.
874 is the title on the top of the widget.
876 is the name of the file to display in the dialog.
878 is the desired height of the box.
879 If zero, the height is based on the screen size.
881 is the desired width of the box.
882 If zero, the height is based on the screen size.
884 .\" ************************************************************************
885 .IP \fBdialog_timebox
886 implements the "\fB--timebox\fP" option.
889 is the title on the top of the widget.
891 is the prompt text shown within the widget.
893 is the desired height of the box.
894 If zero, the height is based on the screen size.
896 is the desired width of the box.
897 If zero, the height is based on the screen size.
899 is the initial hour shown.
900 If the value is negative,
901 the current hour is used.
903 is the initial minute shown.
904 If the value is negative,
905 the current minute is used.
907 is the initial second shown.
908 If the value is negative,
909 the current second is used.
911 .\" ************************************************************************
913 implements the "\fB--yesno\fP" option.
916 is the title on the top of the widget.
918 is the prompt text shown within the widget.
920 is the desired height of the box.
921 If zero, the height is based on the screen size.
923 is the desired width of the box.
924 If zero, the height is based on the screen size.
927 .\" ************************************************************************
928 .SH UTILITY FUNCTIONS
929 Most functions that implement lower-level
930 functionality for the command-line \fBdialog\fP
931 program or widgets, have names beginning "\fIdlg_\fP".
932 Bowing to longstanding usage, the functions that initialize the
933 display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP.
935 The only non-widget function whose name begins with "\fIdialog_\fP"
936 is \fIdialog_version\fP, which returns the version number of the
940 Here is a brief summary of the utility functions and their parameters:
941 .\" ---------------------------------------------------------------------------
944 Add a callback, used to allow polling input from multiple tailbox
948 .B DIALOG_CALLBACK *\fIp\fP
949 contains the callback information.
951 .\" ---------------------------------------------------------------------------
953 .B dlg_add_callback_ref
954 Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP
955 as well as a pointer to a cleanup function which will be called when the
956 associated input ends.
959 .B DIALOG_CALLBACK **\fIp\fP
960 points to the callback information.
961 This is a reference to the pointer so that the caller's pointer can be
962 zeroed when input ends.
964 .B DIALOG_FREEBACK \fIfunc\fP
965 function to call when input ends, e.g., to free caller's additional data.
967 .\" ---------------------------------------------------------------------------
970 Add a quoted string to the result buffer (see \fBdlg_add_result\fP).
974 is the string to add.
976 .\" ---------------------------------------------------------------------------
979 Add a quoted string to the result buffer \fBdialog_vars.input_result\fP.
983 is the string to add.
985 .\" ---------------------------------------------------------------------------
988 Add an output-separator to the result buffer \fBdialog_vars.input_result\fP.
989 If \fBdialog_vars.output_separator\fP is set, use that.
990 Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline.
991 If neither is set, use a space.
992 .\" ---------------------------------------------------------------------------
995 Add a quoted or unquoted string to the result buffer
996 (see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP),
997 according to whether \fBdialog_vars.quoted\fP is true.
1001 is the string to add.
1003 .\" ---------------------------------------------------------------------------
1005 .B dlg_align_columns
1006 Copy and reformat an array of pointers to strings, aligning according to
1007 the column separator \fBdialog_vars.column_separator\fP.
1008 If no column separator is set, the array will be unmodified;
1009 otherwise it is copied and reformatted.
1011 Caveat: This function is only implemented for 8-bit characters.
1015 This is the array to reformat.
1016 It points to the first string to modify.
1019 This is the size of the struct for each row of the array.
1022 This is the number of rows in the array.
1024 .\" ---------------------------------------------------------------------------
1027 returns its parameter transformed to the
1028 corresponding "+" or "-", etc. for the line-drawing characters used in \fBdialog\fP.
1029 If the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns 0.
1031 .\" ---------------------------------------------------------------------------
1034 Set window to the given attribute.
1038 is the window to update.
1041 is the number of rows to update.
1044 is the number of columns to update.
1047 is the attribute, e.g., \fBA_BOLD\fP.
1049 .\" ---------------------------------------------------------------------------
1052 Automatically size the window used for a widget.
1053 If the given height or width are zero,
1054 justify the \fIprompt\fP text and return the actual limits.
1057 .B const char * \fItitle
1058 is the title string to display at the top of the widget.
1060 .B const char * \fIprompt
1061 is the message text which will be displayed in the widget,
1062 used here to determine how large the widget should be.
1065 is the nominal height.
1068 is the nominal width.
1071 is the number of lines to reserve in the vertical direction.
1074 is the minimum number of columns to use.
1076 .\" ---------------------------------------------------------------------------
1078 .B dlg_auto_sizefile
1079 Like \fBdlg_auto_size\fP, but use a file contents to decide how large
1080 the widget should be.
1083 .B const char * \fItitle
1084 is the title string to display at the top of the widget.
1086 .B const char * \fIfile
1087 is the name of the file.
1090 is the nominal height.
1091 If it is -1, use the screen's height after subtracting \fBdialog_vars.begin_y\fP
1092 if \fBdialog_vars.begin_set\fP is true.
1095 is the nominal width.
1096 If it is -1, use the screen's width after subtracting \fBdialog_vars.begin_x\fP
1097 if \fBdialog_vars.begin_set\fP is true.
1100 is the number of lines to reserve on the screen for drawing boxes.
1103 is the number of columns to reserve on the screen for drawing boxes.
1105 .\" ---------------------------------------------------------------------------
1108 If \fBdialog_vars.beep_signal\fP is nonzero,
1109 this calls \fBbeep\fP once and sets
1110 \fBdialog_vars.beep_signal\fP to zero.
1111 .\" ---------------------------------------------------------------------------
1114 returns its parameter transformed as follows:
1118 if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set.
1121 if \fBdialog_vars.ascii_lines\fP is set, returns the corresponding "+" or "-", etc. for the line-drawing characters used in \fBdialog\fP.
1124 otherwise, if \fBdialog_vars.no_lines\fP is set, returns a space for the line-drawing characters.
1127 if the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns the parameter unchanged.
1129 .\" ---------------------------------------------------------------------------
1131 .B dlg_box_x_ordinate
1132 returns a suitable x-ordinate (column) for a new widget.
1133 If \fBdialog_vars.begin_set\fP is 1,
1134 use \fBdialog_vars.begin_x\fP;
1135 otherwise center the widget on the screen (using the \fIwidth\fP parameter).
1139 is the width of the widget.
1141 .\" ---------------------------------------------------------------------------
1143 .B dlg_box_y_ordinate
1144 returns a suitable y-ordinate (row) for a new widget.
1145 If \fBdialog_vars.begin_set\fP is 1,
1146 use \fBdialog_vars.begin_y\fP;
1147 otherwise center the widget on the screen (using the \fIheight\fP parameter).
1151 is the height of the widget.
1153 .\" ---------------------------------------------------------------------------
1156 Count the buttons in the list.
1159 .B const char ** \fIlabels
1160 is a list of (pointers to) button labels terminated by a null pointer.
1162 .\" ---------------------------------------------------------------------------
1164 .B dlg_button_layout
1165 Make sure there is enough space for the buttons by
1166 computing the width required for their labels,
1167 adding margins and limiting based on the screen size.
1170 .B const char ** \fIlabels
1171 is a list of (pointers to) button labels terminated by a null pointer.
1174 the function sets the referenced \fIlimit\fP to the width required for
1175 the buttons (limited by the screen size)
1176 if that is wider than the passed-in limit.
1178 .\" ---------------------------------------------------------------------------
1181 Compute the size of the button array in columns.
1184 .B const char ** \fIlabels
1185 is a list of (pointers to) button labels terminated by a null pointer.
1188 is true if the buttons are arranged in a column rather than a row.
1191 Return the total number of columns in the referenced location.
1194 Return the longest button's columns in the referenced location.
1196 .\" ---------------------------------------------------------------------------
1198 .B dlg_button_x_step
1199 Compute the step-size needed between elements of the button array.
1202 .B const char ** \fIlabels
1203 is a list of (pointers to) button labels terminated by a null pointer.
1206 is the maximum number of columns to allow for the buttons.
1209 store the nominal gap between buttons in the referenced location.
1210 This is constrained to be at least one.
1213 store the left+right total margins (for the list of buttons) in the referenced
1217 store the step-size in the referenced location.
1219 .\" ---------------------------------------------------------------------------
1221 .B dlg_button_to_char
1222 Find the first uppercase character in the label, which we may use for an
1224 If the label is empty, return -1.
1225 If no uppercase character is found, return 0.
1226 Otherwise return the uppercase character.
1229 .B const char * \fIlabel
1230 is the label to test.
1232 .\" ---------------------------------------------------------------------------
1234 .B dlg_calc_list_width
1235 Calculate the minimum width for the list, assuming none of the items
1240 is the number of \fIitems\fP.
1242 .B DIALOG_LISTITEM * \fIitems
1243 contains a \fIname\fP and \fItext\fP field,
1244 e.g., for checklists or radiobox lists.
1245 The function returns the sum of the widest columns
1246 needed for of each of these fields.
1248 .\" ---------------------------------------------------------------------------
1251 Calculate new height and list_height values.
1255 on input, is the height without adding the list-height.
1256 On return, this contains the total list-height and is the
1257 actual widget's height.
1259 .B int * \fIlist_height
1260 on input, is the requested list-height.
1261 On return, this contains the number of rows available for displaying
1262 the list after taking into account the screen size and
1263 the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables.
1266 is the number of \fIitems\fP in the list.
1268 .\" ---------------------------------------------------------------------------
1271 This function is obsolete, provided for library-compatibility.
1272 It is replaced by \fIdlg_calc_list_width\fP.
1276 is the number of \fIitems\fP.
1279 is a list of character pointers.
1282 is the number of items in each group, e.g., the second array index.
1284 .\" ---------------------------------------------------------------------------
1286 .B dlg_char_to_button
1287 Given a list of button labels,
1288 and a character which may be the abbreviation for one, find it, if it exists.
1289 An abbreviation will be the first character
1290 which happens to be capitalized in the label.
1291 If the character is found, return its index within the list of \fIlabels\fP.
1292 Otherwise, return \fBDLG_EXIT_UNKNOWN\fP.
1296 is the character to find.
1298 .B const char ** \fIlabels
1299 is a list of (pointers to) button labels terminated by a null pointer.
1301 .\" ---------------------------------------------------------------------------
1304 This entrypoint provides the \fB--checklist\fP or \fP--radiolist\fP
1305 functionality without the limitations of \fBdialog\fP's command-line syntax
1306 (compare to \fBdialog_checklist\fP).
1309 .B const char * \fItitle
1310 is the title string to display at the top of the widget.
1312 .B const char * \fIcprompt
1313 is the prompt text shown within the widget.
1316 is the desired height of the box.
1317 If zero, the height is adjusted to use the available screen size.
1320 is the desired width of the box.
1321 If zero, the height is adjusted to use the available screen size.
1323 .B int \fIlist_height
1324 is the minimum height to reserve for displaying the list.
1325 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1328 is the number of \fIitems\fP.
1330 .B DIALOG_LISTITEM * \fIitems
1331 This is a list of the items to display in the checklist.
1333 .B const char * \fIstates
1334 This is a list of characters to display for the given states.
1335 Normally a checklist provides true (1) and false (0) values,
1336 which the widget displays as "*" and space, respectively.
1337 An application may set this parameter to an arbitrary null-terminated string.
1338 The widget determines the number of states from the length of this string,
1339 and will cycle through the corresponding display characters as the user
1340 presses the space-bar.
1343 This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP,
1344 depending on whether the widget should act as a checklist or radiobox.
1346 .B int * \fIcurrent_item
1347 The widget sets the referenced location to the index of the current display
1348 item (cursor) when it returns.
1350 .\" ---------------------------------------------------------------------------
1352 .B dlg_check_scrolled
1353 given a function key (or other key that was mapped to a function key),
1354 check if it is one of the up/down scrolling functions:
1371 Some widgets use these key bindings for scrolling the prompt-text up and
1372 down, to allow for display in very small windows.
1374 The function returns 0 (zero) if it finds one of these keys,
1379 is the function-key to check
1382 is the number of lines
1383 which would be used to display the scrolled prompt in
1384 an arbitrarily tall window.
1385 It is used here to check limits for the \fIoffset\fP value.
1388 this is the available height for writing scrolled text,
1389 which is smaller than the window if it contains buttons.
1392 on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay
1396 on entry, holds the starting line number (counting from zero)
1397 last used for \fBdlg_print_scrolled\fP.
1398 On return, holds the updated starting line number.
1400 .\" ---------------------------------------------------------------------------
1403 Set window to the default dialog screen attribute.
1404 This is set in the rc-file with \fBscreen_color\fP.
1405 .\" ---------------------------------------------------------------------------
1408 Free storage used for the result buffer (\fBdialog_vars.input_result\fP).
1409 .\" ---------------------------------------------------------------------------
1412 Return the number of colors that can be configured in \fBdialog\fP.
1413 .\" ---------------------------------------------------------------------------
1416 Initialize the color pairs used in \fBdialog\fP.
1417 .\" ---------------------------------------------------------------------------
1419 .B dlg_count_columns
1420 Returns the number of columns used for a string.
1421 This is not necessarily the number of bytes in a string.
1424 .B const char * \fIstring
1425 is the string to measure.
1427 .\" ---------------------------------------------------------------------------
1430 Returns the number of wide-characters in the string.
1433 .B const char * \fIstring
1434 is the string to measure.
1436 .\" ---------------------------------------------------------------------------
1439 Create a configuration file,
1440 i.e., write internal tables to a file which can be read back by \fBdialog\fP
1444 .B const char * \fIfilename
1445 is the name of the file to write to.
1447 .\" ---------------------------------------------------------------------------
1450 If \fBdialog_vars.size_err\fP is true,
1451 check if the given window size is too large to fit on the screen.
1452 If so, exit with an error reporting the size of the window.
1456 is the window's height
1459 is the window's width
1461 .\" ---------------------------------------------------------------------------
1463 .B dlg_default_formitem
1464 If \fBdialog_vars.default_item\fP is not null,
1465 find that name by matching the \fIname\fP field in the list of form \fIitems\fP.
1466 If found, return the index of that item in the list.
1467 Otherwise, return zero.
1470 .B DIALOG_FORMITEM * \fIitems
1471 is the list of items to search.
1472 It is terminated by an entry with a null \fIname\fP field.
1474 .\" ---------------------------------------------------------------------------
1477 This function is obsolete, provided for library-compatibility.
1478 It is replaced by \fIdlg_default_formitem\fP and \fIdlg_default_listitem\fP.
1482 is the list of items to search.
1485 is the number of items in each group, e.g., the second array index.
1487 .\" ---------------------------------------------------------------------------
1489 .B dlg_defaultno_button
1490 If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not,
1491 find the button-index for the "Cancel" button.
1492 Otherwise, return the index for "OK" (always zero).
1493 .\" ---------------------------------------------------------------------------
1496 Remove a window, repainting everything else.
1500 is the window to remove.
1502 .\" ---------------------------------------------------------------------------
1505 This is called each time a widget is invoked which may do output.
1506 It increments \fBdialog_state.output_count\fP,
1507 so the output function in \fBdialog\fP can test this and add a separator.
1508 .\" ---------------------------------------------------------------------------
1511 Draw up/down arrows on a window, e.g., for scrollable lists.
1512 It calls \fBdlg_draw_arrows2\fP using the
1513 \fImenubox_color\fP and \fImenubox_border_color\fP attributes.
1516 .B WINDOW * \fIdialog
1517 is the window on which to draw an arrow.
1520 is true if an up-arrow should be drawn at the top of the window.
1522 .B int \fIbottom_arrow
1523 is true if an down-arrow should be drawn at the bottom of the window.
1526 is the zero-based column within the window on which to draw arrows.
1529 is the zero-based row within the window on which to draw up-arrows
1530 as well as a horizontal line to show the window's top.
1533 is the zero-based row within the window on which to draw down-arrows
1534 as well as a horizontal line to show the window's bottom.
1536 .\" ---------------------------------------------------------------------------
1539 Draw up/down arrows on a window, e.g., for scrollable lists.
1542 .B WINDOW * \fIdialog
1543 is the window on which to draw an arrow.
1546 is true if an up-arrow should be drawn at the top of the window.
1548 .B int \fIbottom_arrow
1549 is true if an down-arrow should be drawn at the bottom of the window.
1552 is the zero-based column within the window on which to draw arrows.
1555 is the zero-based row within the window on which to draw up-arrows
1556 as well as a horizontal line to show the window's top.
1559 is the zero-based row within the window on which to draw down-arrows
1560 as well as a horizontal line to show the window's bottom.
1563 is the window's background attribute.
1565 .B chtype \fIborderattr
1566 is the window's border attribute.
1568 .\" ---------------------------------------------------------------------------
1570 .B dlg_draw_bottom_box
1571 Draw a partial box at the bottom of a window,
1572 e.g., to surround a row of buttons.
1573 It is designed to merge with an existing box around
1574 the whole window, so it uses tee-elements rather than corner-elements
1575 on the top corners of this box.
1579 is the window to update.
1581 .\" ---------------------------------------------------------------------------
1584 Draw a rectangular box with line drawing characters.
1588 is the window to update.
1591 is the top row of the box.
1594 is the left column of the box.
1597 is the height of the box.
1600 is the width of the box.
1602 .B chtype \fIboxchar
1603 is used to color the right/lower edges.
1604 It also is fill-color used for the box contents.
1606 .B chtype \fIborderchar
1607 is used to color the upper/left edges.
1609 .\" ---------------------------------------------------------------------------
1612 Print a list of buttons at the given position.
1616 is the window to update.
1619 is the starting row.
1622 is the starting column.
1624 .B const char ** \fIlabels
1625 is a list of (pointers to) button labels terminated by a null pointer.
1628 is the index within the list of the selected button.
1631 is true if the buttons are arranged in a column rather than a row.
1634 is the number of columns (or rows if \fIvertical\fP) allowed for the display.
1636 .\" ---------------------------------------------------------------------------
1638 .B dlg_draw_scrollbar
1639 If \fBdialog_state.use_scrollbar\fP is set,
1640 draw a scrollbar on the right margin of windows holding scrollable data.
1641 Also (whether or not the scrollbar is drawn),
1642 annotate the bottom margin of the window with the percentage of data
1643 by the bottom of that window,
1644 and call \fBdlg_draw_arrows2\fP to put markers on the window showing
1645 when more data is available.
1649 is the window in which the data is scrolled.
1650 Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP
1651 are passed as parameters, this window can contain additional data.
1653 .B long \fIfirst_data
1654 is the zero-based index to the first row of data in the current window.
1656 .B long \fIthis_data
1657 is the zero-based index to the current row of data.
1659 .B long \fInext_data
1660 is the zero-based index to the next data after the current row.
1662 .B long \fItotal_data
1663 is the total number of rows of data.
1666 is the zero-based left margin/column of the window.
1667 The up/down arrows are draw inset by 5 columns from this point.
1670 is the zero-based right margin/column of the window.
1671 The scrollbar is drawn flush against this column.
1674 is the zero-based row within the window on which to draw up-arrows
1675 as well as a horizontal line to show the window's top.
1678 is the zero-based row within the window on which to draw down-arrows
1679 as well as a horizontal line to show the window's bottom.
1682 is the window's background attribute.
1684 .B chtype \fIborderattr
1685 is the window's border attribute.
1687 .\" ---------------------------------------------------------------------------
1690 Draw shadows along the right and bottom edge of a window to give it
1691 a 3-dimensional look.
1692 (The height, etc., may not be the same as the window's actual values).
1696 is the window to update.
1699 is the height of the window.
1702 is the width of the window.
1705 is the top row of the window.
1708 is the left column of the window.
1710 .\" ---------------------------------------------------------------------------
1713 Draw a title centered at the top of the window.
1717 is the window to update.
1719 .B const char * \fItitle
1720 is the title string to display at the top of the widget.
1722 .\" ---------------------------------------------------------------------------
1725 Write all user-defined key-bindings to the given stream,
1726 e.g., as part of \fBdlg_create_rc\fP.
1730 is the stream on which to write the bindings.
1732 .\" ---------------------------------------------------------------------------
1735 Given the character-offset in the string,
1736 returns the display-offset where
1737 dialog should position the cursor.
1738 In this context, "characters" may be multicolumn,
1739 since the string can be a multibyte character string.
1743 is the string to analyze
1746 is the character-offset
1749 is a limit on the column positions that can be used,
1750 e.g., the window's size.
1752 .\" ---------------------------------------------------------------------------
1755 Updates the string and character-offset, given various editing characters
1756 or literal characters which are inserted at the character-offset.
1757 Returns true if an editing change was made (and the display should
1758 be updated), and false if the key was something like KEY_ENTER,
1759 which is a non-editing action outside this function.
1763 is the (multibyte) string to update
1766 is the character-offset
1772 is true if the editing key is a function-key
1775 is used in a special loop case by calling code to force the return
1776 value of this function when a function-key code 0 is passed in.
1778 .\" ---------------------------------------------------------------------------
1781 Given an internal exit code,
1782 check if the corresponding environment variable is set.
1783 If so, remap the exit code to match the environment variable.
1784 Finally call \fBexit\fP with the resulting exit code.
1788 is the internal exit code, e.g., \fBDLG_EXIT_OK\fP,
1789 which may be remapped.
1792 The \fBdialog\fP program uses this function
1793 to allow shell scripts to remap the exit codes so they can distinguish ESC
1795 .\" ---------------------------------------------------------------------------
1797 .B dlg_exit_buttoncode
1798 Map the given button index for \fBdlg_exit_label\fP into dialog's exit-code.
1804 .\" ---------------------------------------------------------------------------
1807 Return a list of button labels.
1808 If dialog_var.extra_button is true, return the result of \fBdlg_ok_labels\fP.
1809 Otherwise, return a list with the "Exit" label and (if \fBdialog_vars.help_button\fP
1810 is set) the "Help" button as well.
1811 .\" ---------------------------------------------------------------------------
1814 Quit program killing all \fBtailboxbg\fP widgets.
1817 .B const char * \fIfmt
1818 is the format of the \fBprintf\fP-like message to write.
1821 are the variables to apply to the \fIfmt\fP format.
1823 .\" ---------------------------------------------------------------------------
1826 Given the character-offset to find in the list, return the corresponding
1830 .B const int *\fIlist
1831 contains a list of character-offsets,
1832 i.e., indices into a string that denote the beginning of multibyte characters.
1835 is the last index into \fBlist\fP to search.
1838 is the character-offset to find.
1840 .\" ---------------------------------------------------------------------------
1843 Cancel the local data saved by \fBdlg_last_getc\fP.
1844 .\" ---------------------------------------------------------------------------
1846 This entrypoint provides the \fB--editbox\fP
1847 functionality without the limitations of \fBdialog\fP's command-line syntax
1848 (compare to \fBdialog_editbox\fP).
1851 .B const char * \fItitle
1852 is the title string to display at the top of the widget.
1855 is a pointer to an array of \fBchar\ *\fP pointers.
1856 The array is allocated by the caller,
1857 and so are the strings to which it points.
1858 The \fBdlg_editbox\fP function may reallocate the
1859 array and the strings.
1862 points to the nominal length of \fIlist\fP.
1863 The referenced value is updated if\fIlist\fP is reallocated.
1866 is the desired height of the box.
1867 If zero, the height is adjusted to use the available screen size.
1870 is the desired width of the box.
1871 If zero, the height is adjusted to use the available screen size.
1873 .\" ---------------------------------------------------------------------------
1876 This entrypoint provides the \fB--form\fP
1877 functionality without the limitations of \fBdialog\fP's command-line syntax
1878 (compare to \fBdialog_form\fP).
1881 .B const char * \fItitle
1882 is the title string to display at the top of the widget.
1884 .B const char * \fIcprompt
1885 is the prompt text shown within the widget.
1888 is the desired height of the box.
1889 If zero, the height is adjusted to use the available screen size.
1892 is the desired width of the box.
1893 If zero, the height is adjusted to use the available screen size.
1895 .B int \fIform_height
1896 is the minimum height to reserve for displaying the list.
1897 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1900 is the number of \fIitems\fP.
1902 .B DIALOG_FORMITEM * \fIitems
1903 This is a list of the items to display in the form.
1905 .B int * \fIcurrent_item
1906 The widget sets the referenced location to the index of the current display
1907 item (cursor) when it returns.
1909 .\" ---------------------------------------------------------------------------
1912 Free data allocated by \fBdlg_align_columns\fP.
1916 This is the array which was reformatted.
1917 It points to the first string to free.
1920 This is the size of the struct for each row of the array.
1923 This is the number of rows in the array.
1925 .\" ---------------------------------------------------------------------------
1927 .B dlg_free_formitems
1928 Free memory owned by a list of DIALOG_FORMITEM's.
1931 .B DIALOG_FORMITEM * \fIitems
1932 is the list to free.
1934 .\" ---------------------------------------------------------------------------
1937 Read a character from the given window.
1938 Handle repainting here (to simplify
1939 things in the calling application).
1940 Also, if input-callback(s) are set up,
1941 poll the corresponding files and handle the updates,
1942 e.g., for displaying a tailbox.
1943 Returns the key-code.
1947 is the window within which to read.
1950 as a side-effect, set this to true if the key-code is really a function-key.
1952 .\" ---------------------------------------------------------------------------
1954 .B dlg_getc_callbacks
1955 passes the given key-code \fIch\fP to the current window that
1956 has established a callback.
1957 If the callback returns zero, remove it and try the next window.
1958 If no more callbacks remain, return.
1959 If any callbacks were found, return true, otherwise false.
1966 is true if the key is a function-key
1969 is used to pass an exit-code to the caller,
1970 which should pass that via \fBdlg_exit\fP.
1972 .\" ---------------------------------------------------------------------------
1974 .B dlg_index_columns
1975 Build a list of the display-columns for the given multibyte string's characters.
1978 .B const char * \fIstring
1979 is the string to analyze
1981 .\" ---------------------------------------------------------------------------
1984 Build an index of the wide-characters in the string,
1985 so the caller can easily tell
1986 which byte-offset begins a given wide-character.
1989 .B const char * \fIstring
1990 is the string to analyze
1992 .\" ---------------------------------------------------------------------------
1995 Draw the string for the \fBdialog_vars.item_help\fP feature.
1998 .B const char * \fItxt
2001 .\" ---------------------------------------------------------------------------
2004 If \fBdialog\fP has callbacks active,
2005 purge the list of all that are not marked
2006 to keep in the background.
2007 If any remain, run those in a background process.
2011 stores the exit-code to pass back to the caller.
2013 .\" ---------------------------------------------------------------------------
2016 returns the most recent character that was read via \fBdlg_getc\fP.
2017 .\" ---------------------------------------------------------------------------
2019 .B dlg_limit_columns
2020 Given a column limit,
2021 count the number of wide characters that can fit into that limit.
2022 The offset is used to skip over a leading character
2023 that was already written.
2026 .B const char * \fIstring
2027 is the string to analyze
2033 is the starting offset from which analysis should continue
2035 .\" ---------------------------------------------------------------------------
2038 Check for a key-binding.
2039 If there is no binding associated with the widget, it simply returns
2040 the given curses-key.
2041 Otherwise, it returns the result of the binding
2045 is the window on which the binding is checked
2047 .B int \fIcurses_key
2048 is the curses key-code
2050 .B int * \fIdialog_key
2051 is the corresponding dialog internal code
2052 (see \fBDLG_KEYS_ENUM\fP in dlg_key.h).
2054 .\" ---------------------------------------------------------------------------
2057 Limit the parameter according to \fBdialog_vars.max_input\fP
2061 is the value to limit
2063 .\" ---------------------------------------------------------------------------
2066 Match a given character against the beginning of the string,
2067 ignoring case of the given character.
2068 The matching string must begin with an uppercase character.
2072 is the character to check
2074 .B const char * \fIstring
2075 is the string to search
2077 .\" ---------------------------------------------------------------------------
2080 This entrypoint provides the \fB--menu\fP
2081 functionality without the limitations of \fBdialog\fP's command-line syntax
2082 (compare to \fBdialog_menu\fP).
2085 .B const char * \fItitle
2086 is the title string to display at the top of the widget.
2088 .B const char * \fIcprompt
2089 is the prompt text shown within the widget.
2092 is the desired height of the box.
2093 If zero, the height is adjusted to use the available screen size.
2096 is the desired width of the box.
2097 If zero, the height is adjusted to use the available screen size.
2099 .B int \fImenu_height
2100 is the minimum height to reserve for displaying the list.
2101 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2104 is the number of \fIitems\fP.
2106 .B DIALOG_LISTITEM * \fIitems
2107 This is a list of the items to display in the form.
2109 .B int * \fIcurrent_item
2110 The widget sets the referenced location to the index of the current display
2111 item (cursor) when it returns.
2113 .B DIALOG_INPUTMENU \fIrename_menutext
2115 .\" ---------------------------------------------------------------------------
2118 Moves/resizes the given window to the given position and size.
2122 is the window to move/resize.
2124 .B WINDOW *\fIheight
2125 is the height of the resized window.
2128 is the width of the resized window.
2131 y-ordinate to use for the repositioned window.
2134 x-ordinate to use for the repositioned window.
2136 .\" ---------------------------------------------------------------------------
2138 .B dlg_mouse_bigregion
2139 Retrieve the big-region under the pointer.
2143 is the row on which the mouse click occurred
2146 is the column on which the mouse click occurred
2148 .\" ---------------------------------------------------------------------------
2150 .B dlg_mouse_free_regions
2151 Free the memory associated with mouse regions.
2152 .\" ---------------------------------------------------------------------------
2154 .B dlg_mouse_mkbigregion
2155 Creates a region on which the mouse-clicks will return a specifed code.
2159 is the top-row of the region.
2162 is the left-column of the region.
2165 is the height of the region.
2168 is the width of the region.
2171 is a code used to make the region unique within a widget
2174 is used in modes 2 (columns) and 3 (cells) to determine the width
2181 is used to determine how the mouse position is translated into
2182 a code (like a function-key):
2195 .\" ---------------------------------------------------------------------------
2197 .B dlg_mouse_mkregion
2201 is the top-row of the region.
2204 is the left-column of the region.
2207 is the height of the region.
2210 is the width of the region.
2213 is a code used to make the region unique within a widget
2215 .\" ---------------------------------------------------------------------------
2218 Retrieve the frame under the mouse pointer
2222 is the row of the mouse-click
2225 is the column of the mouse-click
2227 .\" ---------------------------------------------------------------------------
2229 .B dlg_mouse_setbase
2230 Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP,
2231 so they can make regions relative to the start of a given window.
2235 is the left-column for the base
2238 is the top-row for the base
2240 .\" ---------------------------------------------------------------------------
2243 is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks
2244 (if the curses library supports those) into extended function-keys
2245 which encode the position according to the \fImode\fP in
2246 \fBdlg_mouse_mkbigregion\fP.
2247 Returns the corresponding key-code.
2251 is the window on which to perform the input
2254 the referenced location is set to true if the key-code is an actual
2255 or extended (mouse) function-key.
2257 .\" ---------------------------------------------------------------------------
2259 .B dlg_mouse_wgetch_nowait
2260 This is a non-blocking variant of \fBdlg_mouse_wgetch\fP.
2264 is the window on which to perform the input
2267 the referenced location is set to true if the key-code is an actual
2268 or extended (mouse) function-key.
2270 .\" ---------------------------------------------------------------------------
2272 .B dlg_need_separator
2273 Check if an output-separator is needed.
2274 If \fBdialog_vars.output_separator\fP is set, return true.
2275 Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true.
2276 If neither, return false.
2277 .\" ---------------------------------------------------------------------------
2279 .B dlg_new_modal_window
2280 Create a modal window, optionally with a shadow.
2281 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2284 .B WINDOW * \fIparent
2285 is the parent window (usually the top-level window of a widget)
2288 is the window's height
2291 is the window's width
2294 is the window's top-row
2297 is the window's left-column
2299 .\" ---------------------------------------------------------------------------
2302 Create a window, optionally with a shadow.
2303 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2307 is the window's height
2310 is the window's width
2313 is the window's top-row
2316 is the window's left-column
2318 .\" ---------------------------------------------------------------------------
2321 Return the next index in the list of labels.
2324 .B const char ** \fIlabels
2325 is a list of (pointers to) button labels terminated by a null pointer.
2328 is the current button-index.
2330 .\" ---------------------------------------------------------------------------
2332 .B dlg_next_ok_buttonindex
2333 Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons,
2334 find the next index in the list of buttons.
2338 is the current index in the list of buttons
2341 if negative, provides a way to enumerate extra active areas on the widget.
2343 .\" ---------------------------------------------------------------------------
2345 .B dlg_ok_buttoncode
2346 Map the given button index for \fBdlg_ok_labels\fP
2347 into \fBdialog\fP's exit-code.
2351 is the button-index (which is not necessarily the same as the index
2352 in the list of labels).
2354 .\" ---------------------------------------------------------------------------
2357 Returns a list with the "Ok" label,
2358 and if \fBdialog_vars.help_button\fP is true, the "Help" label as well.
2359 .\" ---------------------------------------------------------------------------
2362 Return a list of button labels for the OK/Cancel group of widgets.
2363 .\" ---------------------------------------------------------------------------
2366 Decode the string as an integer, decrement if greater than zero to make
2367 a curses-ordinate from a dialog-ordinate.
2368 .\" ---------------------------------------------------------------------------
2370 .B dlg_parse_bindkey
2371 Parse the parameters of the "bindkeys" configuration-file entry. This
2372 expects widget name which may be "*", followed by curses key definition and
2373 then dialog key definition.
2377 is the parameter string to parse.
2379 .\" ---------------------------------------------------------------------------
2382 Parse the configuration file and set up variables.
2383 .\" ---------------------------------------------------------------------------
2386 Return the previous index in the list of labels.
2389 .B const char ** \fIlabels
2390 is a list of (pointers to) button labels terminated by a null pointer.
2393 is the current button index
2395 .\" ---------------------------------------------------------------------------
2398 This is a wrapper for \fBdlg_print_autowrap\fP which allows the user
2399 to scroll too-long prompt text up/down.
2401 See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP
2402 variable used as a parameter here.
2403 It complements this function; you need both.
2404 If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP
2405 parameter, needed for \fBdlg_check_scrolled\fP calls.
2409 is the window to update.
2411 .B const char * \fIprompt
2412 is the string to print
2415 is the starting line-number to write wrapped text.
2418 is the available height for writing the wrapped text
2421 is the width that the wrapping should occur in
2424 is true if the extra functionality for scrolling should be enabled.
2425 If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling.
2427 .\" ---------------------------------------------------------------------------
2430 Print one line of the prompt in the window within the limits of the
2431 specified right margin.
2432 The line will end on a word boundary and a pointer
2433 to the start of the next line is returned, or a NULL pointer if the end of
2438 is the window to update.
2441 holds the starting attributes, and is updated to reflect the final attributes
2442 applied to the string.
2444 .B const char *\fIprompt
2445 is the string to print
2454 returns the ending x-ordinate.
2456 .\" ---------------------------------------------------------------------------
2458 .B dlg_prev_ok_buttonindex
2459 Find the previous button index in the list from \fBdlg_ok_labels\fP.
2463 is the current index
2466 if negative provides a way to enumerate extra active areas on the widget.
2468 .\" ---------------------------------------------------------------------------
2470 .B dlg_print_autowrap
2471 Print a string of text in a window, automatically wrap around to the next
2472 line if the string is too long to fit on one line.
2473 Note that the string may contain embedded newlines.
2474 The text is written starting at the top of the window.
2478 is the window to update.
2480 .B const char * \fIprompt
2481 is the string to print
2484 is the nominal height the wrapped string is limited to
2487 is the width that the wrapping should occur in
2489 .\" ---------------------------------------------------------------------------
2492 If \fBdialog_vars.print_siz\fP is true,
2493 print the given height/width (from a widget)
2494 to \fBdialog_state.output\fP, e.g.,
2495 \fBSize: height, width\fP.
2499 is the window's height
2502 is the window's width
2504 .\" ---------------------------------------------------------------------------
2507 Print up to \fIcols\fP columns from \fBtext\fP,
2508 optionally rendering \fBdialog\fP's escape sequences for attributes and color.
2512 is the window to update.
2514 .B const char * \fItxt
2515 is the string to print
2521 holds the starting attributes, and is updated to reflect the final attributes
2522 applied to the string.
2524 .\" ---------------------------------------------------------------------------
2526 .B dlg_put_backtitle
2527 Display the background title if \fBdialog_vars.backtitle\fP is non-null.
2528 The background title is shown at the top of the screen.
2529 .\" ---------------------------------------------------------------------------
2531 .B dlg_register_buttons
2532 The widget developer should call this function after \fBdlg_register_window\fP,
2533 for the list of button labels associated with the widget.
2534 One may bind a key to a button, e.g., "OK" for \fBDLGK_OK\fP,
2538 is the window with which to associate the buttons
2540 .B const char * \fIname
2541 is the widget's binding name (usually the name of the widget).
2543 .B const char ** \fIbuttons
2544 is the list of buttons
2546 .\" ---------------------------------------------------------------------------
2548 .B dlg_register_window
2549 For a given named widget's window, associate a binding table.
2553 is the window with which to associate the buttons
2555 .B const char * \fIname
2556 is the widget's binding name (usually the name of the widget).
2558 .B DLG_KEYS_BINDING * \fIbinding
2559 is the binding table
2561 .\" ---------------------------------------------------------------------------
2563 .B dlg_remove_callback
2567 .B DIALOG_CALLBACK \fI* p
2568 contains the callback information.
2570 .\" ---------------------------------------------------------------------------
2573 Restore dialog's variables from the given variable (see \fBdialog_save_vars\fP).
2576 .B DIALOG_VARS * \fIsave
2577 is the variable from which to restore.
2579 .\" ---------------------------------------------------------------------------
2582 Test a dialog internal keycode to see if it corresponds to one of the push
2583 buttons on the widget such as "OK".
2584 This is only useful if there are user-defined key bindings, since there are
2585 no built-in bindings that map directly to \fBDLGK_OK\fP, etc.
2586 Return true if a mapping was done.
2589 .B int \fIdialog_key
2590 is the dialog key to test
2593 is true if this is a function key
2596 store the result of the mapping in the referenced location.
2598 .\" ---------------------------------------------------------------------------
2601 Save dialog's variables into the given variable (see \fBdialog_restore_vars\fP).
2604 .B DIALOG_VARS * \fIsave
2605 is the variable into which to save.
2607 .\" ---------------------------------------------------------------------------
2610 Set focus on the given window,
2611 making it display above other windows on the screen.
2614 .B WINDOW * \fIparent
2615 is the parent window (usually the top-level window of a widget)
2618 is the window on which to place focus (usually a subwindow of a widget)
2620 .\" ---------------------------------------------------------------------------
2623 Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP
2626 .B const char * \fIstring
2627 is the new contents for the result
2629 .\" ---------------------------------------------------------------------------
2632 Displays the string, shifted as necessary, to fit within the box and show
2633 the current character-offset.
2637 is the window within which to display
2639 .B const char * \fIstring
2640 is the string to display
2643 is the starting (character, not bytes) offset
2646 is the window attribute to use for the string
2649 beginning row on screen
2652 beginning column on screen
2655 number of columns on screen
2658 if true, do not echo input
2661 if true, force repaint
2663 .\" ---------------------------------------------------------------------------
2666 duplicate the string, like \fBstrdup\fP.
2669 .B const char * \fIcprompt
2670 is the string to duplicate
2672 .\" ---------------------------------------------------------------------------
2675 compare two strings, ignoring case.
2678 .B const char \fI* a
2681 .B const char \fI* b
2684 .\" ---------------------------------------------------------------------------
2687 create a subwindow, e.g., for an input area of a widget
2691 is the parent window
2694 is the subwindow's height
2697 is the subwindow's width
2700 is the subwindow's top-row
2703 is the subwindow's left-column
2705 .\" ---------------------------------------------------------------------------
2707 .B dlg_tab_correct_str
2708 If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces.
2709 Return the converted result.
2710 The caller is responsible for freeing the string.
2714 is the string to convert
2716 .\" ---------------------------------------------------------------------------
2719 If the parameter is non-null, opens a trace file with that
2720 name and stores the file pointer in \fBdialog_state.trace\fP.
2721 .\" ---------------------------------------------------------------------------
2724 If \fBdialog_state.trace\fP is set,
2725 translate the parameters into a printable representation,
2726 log it on a "chr" line.
2730 is the nominal keycode value.
2733 is nonzero if the value is really a function key.
2734 Some of these may be values declared in the DLG_KEYS_ENUM.
2736 .\" ---------------------------------------------------------------------------
2739 If \fBdialog_state.trace\fP is set,
2740 log a printable picture of the given window.
2741 .\" ---------------------------------------------------------------------------
2744 Change embedded "\\n" substrings to '\\n' characters and tabs to single spaces.
2745 If there are no "\\n"s, the function strips all extra spaces, for justification.
2746 If it has "\\n"'s, the function preserves extra spaces.
2747 If \fBdialog_vars.cr_wrap\fP is set, the function preserves '\\n's.
2751 is the string to trim
2753 .\" ---------------------------------------------------------------------------
2755 .B dlg_unregister_window
2756 Remove the bindings for a given window.
2760 is the window from which to remove bindings
2762 .\" ---------------------------------------------------------------------------
2764 .B dlg_yes_buttoncode
2765 Map the given button index for \fBdlg_yes_labels\fP into \fBdialog\fP's exit-code.
2771 .\" ---------------------------------------------------------------------------
2774 Return a list of buttons for Yes/No labels.
2776 .\" ************************************************************************
2780 .\" ************************************************************************