1 .\" $Id: dialog.3,v 1.60 2011/03/02 10:19:12 tom Exp $
2 .\" Copyright 2005-2010,2011 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.
19 .\" definitions for renaming
24 .\" Bulleted paragraph
28 .TH \*D 3 "" "$Date: 2011/03/02 10:19:12 $"
30 \*l \- widgets and utilities for the \*p program
32 .B cc [ flag ... ] file ... -l\*l [ library ... ]
36 .B cc `\*p-config --cflags` file ... `\*p-config --libs` ]
41 is a program that will let you to present a variety of questions or
42 display messages using dialog boxes from a shell script.
43 It is built from the \fB\*l\fP library,
44 which consists of several widgets
45 as well as utility functions that are used by the widgets
49 This manpage documents the features from \fI<\*l.h>\fP which
50 are likely to be important to developers using the widgets directly.
51 Some hints are also given for developing new widgets.
53 .\" ************************************************************************
55 Exit codes (passed back to the main program for its use)
56 are defined with a "\fIDLG_EXIT_\fP prefix.
57 The defined constants can be mapped using environment variables
58 as described in \fB\*p\fP(1),
59 e.g., \fIDLG_EXIT_OK\fP corresponds to \fI$DIALOG_OK\fP.
61 Useful character constants which correspond to user input
62 are named with the "\fICHR_\fP" prefix, e.g.,
65 Colors and video attributes are categorized and associated with
66 settings in the configuration file
67 (see the discussion of \fI$DIALOGRC\fP in \fB\*p\fP(1)).
68 The \fIDIALOG_ATR(n)\fP macro is used for defining the references
69 to the combined color and attribute table \fIdlg_color_table[]\fP.
71 The \fB\*p\fP application passes its command-line parameters
72 to the widget functions. Some of those parameters are single values,
73 but some of the widgets accept data as an array of values.
74 Those include checklist/radiobox, menubox and formbox.
75 When the \fB--item-help\fP option is given, an extra column
77 The USE_ITEM_HELP(), CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS
78 macros are used to hide this difference from the calling application.
80 Most of the other definitions found in \fI<\*l.h>\fP
81 are used for convenience in building the library or main program.
82 These include definitions based on the generated \fI<dlg_config.h>\fP header.
84 .\" ************************************************************************
86 All of the global data for the \fB\*l\fP library is stored in
87 a few structures: \fIDIALOG_STATE\fP, \fIDIALOG_VARS\fP and \fIDIALOG_COLORS\fP.
88 The corresponding \fIdialog_state\fP, \fIdialog_vars\fP and \fIdlg_color_table\fP
89 global variables should be initialized to zeros,
90 and then populated with the data to use.
91 A few of these must be nonzero for the corresponding widgets to function.
92 As as the case with function names,
93 variables beginning with "\fIdialog_\fP"
94 are designed for use by the calling application
95 while variables beginning with "\fIdlg_\fP"
96 are intended for lower levels, e.g., by the \fB\*l\fP library.
97 .\" ---------------------------------------------------------------------------
98 .IP \fIDIALOG_STATE.all_windows
99 This is a linked list of all windows created by the library.
100 The \fBdlg_del_window\fP function uses this to locate windows which
101 may be redrawn after deleting a window.
102 .\" ---------------------------------------------------------------------------
103 .IP \fIDIALOG_STATE.aspect_ratio
104 This corresponds to the command-line option "\fB--aspect-ratio\fP".
105 The value gives the application
106 some control over the box dimensions when using auto
107 sizing (specifying 0 for height and width).
108 It represents width / height.
109 The default is 9, which means 9 characters wide to every 1 line high.
110 .\" ---------------------------------------------------------------------------
111 .IP \fIDIALOG_STATE.getc_callbacks
112 This is setup in \fIui_getc.c\fP to record windows which must be polled
113 for input, e.g,. to handle the background tailbox widget.
114 One window is designated as the foreground or control window.
115 .\" ---------------------------------------------------------------------------
116 .IP \fIDIALOG_STATE.getc_redirect
117 If the control window for \fIDIALOG_STATE.getc_callbacks\fP is
118 closed, the list is transferred to this variable.
119 Closing all windows causes the application to exit.
120 .\" ---------------------------------------------------------------------------
121 .IP \fIDIALOG_STATE.no_mouse
122 This corresponds to the command-line option "\fB--no-mouse\fP".
123 If true, \fB\*p\fP will not initialize (and enable) the mouse in
125 .\" ---------------------------------------------------------------------------
126 .IP \fIDIALOG_STATE.output
127 This is set in the \fB\*p\fP application to the stream on
128 which the application and library functions may write text results.
129 Normally that is the standard error,
130 since the curses library prefers to write its data to the standard output.
131 Some scripts, trading portability for convenience,
132 prefer to write results to the standard output,
133 e.g., by using the "\fB--stdout\fP" option.
134 .\" ---------------------------------------------------------------------------
135 .IP \fIDIALOG_STATE.output_count
136 This is incremented by \fIdlg_does_output\fP,
137 which is called by each widget that writes text to the output.
138 The \fB\*p\fP application uses that to decide if it should
139 also write a separator, i.e.,
140 \fIDIALOG_STATE.separate_str\fP,
141 between calls to each widget.
142 .\" ---------------------------------------------------------------------------
143 .IP \fIDIALOG_STATE.pipe_input
144 This is set in \fIinit_dialog\fP to a stream which can be used by the
145 \fBgauge\fP widget, which must be the application's standard input.
146 The \fB\*p\fP application calls \fIinit_dialog\fP normally with
147 \fIinput\fP set to the standard input, but optionally based on the
148 "\fB--input-fd\fP" option.
149 Since the application cannot read from
150 a pipe (standard input) and at the same time read
151 the curses input from the standard input,
152 it must allow for reopening the latter from either
153 a specific file descriptor,
154 or directly from the terminal.
155 The adjusted pipe stream value is stored in this variable.
156 .\" ---------------------------------------------------------------------------
157 .IP \fIDIALOG_STATE.screen_initialized
158 This is set in \fIinit_dialog\fP and
159 reset in \fIend_dialog\fP.
160 It is used to check if curses has been initialized,
161 and if the \fIendwin\fP function must be called on exit.
162 .\" ---------------------------------------------------------------------------
163 .IP \fIDIALOG_STATE.screen_output
164 This is set in \fIinit_dialog\fP to the output stream used
165 by the curses library.
166 Normally that is the standard output,
167 unless that happens to not be a terminal (and if \fIinit_dialog\fP can
168 successfully open the terminal directly).
169 .\" ---------------------------------------------------------------------------
170 .IP \fIDIALOG_STATE.separate_str
171 This corresponds to the command-line option "\fB--separate-widget\fP".
173 specifies a string that will separate the output on \fB\*p\fP's output from
175 This is used to simplify parsing the result of a dialog with several widgets.
176 If this option is not given,
177 the default separator string is a tab character.
178 .\" ---------------------------------------------------------------------------
179 .IP \fIDIALOG_STATE.tab_len
180 This corresponds to the command-line option "\fB--tab-len\fP \fInumber\fP".
181 Specify the number of spaces that a tab character occupies if the
182 "\fB--tab-correct\fP"
185 .\" ---------------------------------------------------------------------------
186 .IP \fIDIALOG_STATE.trace_output
187 This corresponds to the command-line option "\fB--trace\fP \fIfile\fP".
188 It is the file pointer to which trace messages are written.
189 .\" ---------------------------------------------------------------------------
190 .IP \fIDIALOG_STATE.use_colors
191 This is set in \fIinit_dialog\fP if the curses implementation supports color.
192 .\" ---------------------------------------------------------------------------
193 .IP \fIDIALOG_STATE.use_scrollbar
194 This corresponds to the command-line option "\fB--scrollbar\fP".
196 draw a scrollbar to make windows holding scrolled data more readable.
197 .\" ---------------------------------------------------------------------------
198 .IP \fIDIALOG_STATE.use_shadow
199 This corresponds to the command-line option "\fB--no-shadow\fP".
200 This is set in \fIinit_dialog\fP if the curses implementation supports color.
202 suppress shadows that would be drawn to the right and bottom of each dialog box.
203 .\" ---------------------------------------------------------------------------
204 .IP \fIDIALOG_STATE.visit_items
205 This corresponds to the command-line option "\fB--visit-items\fP".
206 .\" ---------------------------------------------------------------------------
208 The \fB\*p\fP application resets the \fIdialog_vars\fP data before
209 accepting options to invoke each widget.
210 Most of the \fIDIALOG_VARS\fP members are set directly from \fB\*p\fP's
211 command-line options:
212 .\" ---------------------------------------------------------------------------
213 .IP \fIDIALOG_VARS.ascii_lines
214 .\" ---------------------------------------------------------------------------
215 .IP \fIDIALOG_VARS.backtitle
216 This corresponds to the command-line option "\fB--backtitle\fP \fIbacktitle\fP".
219 string to be displayed on the backdrop, at the top of the screen.
220 .\" ---------------------------------------------------------------------------
221 .IP \fIDIALOG_VARS.beep_after_signal
222 This corresponds to the command-line option "\fB--beep-after\fP".
223 If true, beep after a user has completed a widget by pressing one of the buttons.
224 .\" ---------------------------------------------------------------------------
225 .IP \fIDIALOG_VARS.beep_signal
226 This corresponds to the command-line option "\fB--beep\fP".
228 .\" ---------------------------------------------------------------------------
229 .IP \fIDIALOG_VARS.begin_set
230 This is true if the command-line option "\fB--begin y x\fP" was used.
231 It specifies the position of the upper left corner of a dialog box on the screen.
232 .\" ---------------------------------------------------------------------------
233 .IP \fIDIALOG_VARS.begin_x
234 This corresponds to the \fIx\fP value from
235 the command-line option "\fB--begin\fP \fIy x\fP" (second value).
236 .\" ---------------------------------------------------------------------------
237 .IP \fIDIALOG_VARS.begin_y
238 This corresponds to the \fIy\fP value from
239 the command-line option "\fB--begin\fP \fIy x\fP" (first value).
240 .\" ---------------------------------------------------------------------------
241 .IP \fIDIALOG_VARS.cancel_label
242 This corresponds to the command-line option "\fB--cancel-label\fP \fIstring\fP".
243 The given \fIstring\fP overrides the label used for "Cancel" buttons.
244 .\" ---------------------------------------------------------------------------
245 .IP \fIDIALOG_VARS.cant_kill
246 This corresponds to the command-line option "\fB--no-kill\fP".
251 box in the background,
252 printing its process id to \fB\*p\fP's output.
253 SIGHUP is disabled for the background process.
254 .\" ---------------------------------------------------------------------------
255 .IP \fIDIALOG_VARS.colors
256 This corresponds to the command-line option "\fB--colors\fP".
257 If true, interpret embedded "\\Z" sequences in the dialog text
258 by the following character,
259 which tells \fB\*p\fP to set colors or video attributes:
260 0 through 7 are the ANSI codes used in curses:
269 Bold is set by 'b', reset by 'B'.
270 Reverse is set by 'r', reset by 'R'.
271 Underline is set by 'u', reset by 'U'.
272 The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
274 Restore normal settings with "\\Zn".
275 .\" ---------------------------------------------------------------------------
276 .IP \fIDIALOG_VARS.column_separator
277 .\" ---------------------------------------------------------------------------
278 .IP \fIDIALOG_VARS.cr_wrap
279 This corresponds to the command-line option "\fB--cr-wrap\fP".
281 interpret embedded newlines in the dialog text as a newline on the screen.
282 Otherwise, \fB\*p\fR will only wrap lines where needed to fit inside the text box.
283 Even though you can control line breaks with this,
284 \fB\*p\fR will still wrap any lines that are too long for the width of the box.
285 Without cr-wrap, the layout of your text may be formatted to look nice
286 in the source code of your script without affecting the way it will
288 .\" ---------------------------------------------------------------------------
289 .IP \fIDIALOG_VARS.date_format
290 This corresponds to the command-line option "\fB--date-format\fP \fIstring\fP".
291 If the host provides \fBstrftime\fP, and the value is nonnull,
292 the calendar widget uses this to format its output.
293 .\" ---------------------------------------------------------------------------
294 .IP \fIDIALOG_VARS.default_item
295 This corresponds to the command-line option "\fB--default-item\fP \fIstring\fP".
296 The given string is used as
297 the default item in a checklist, form or menu box.
298 Normally the first item in the box is the default.
299 .IP \fIDIALOG_VARS.defaultno
300 This corresponds to the command-line option "\fB--defaultno\fP".
302 make the default value of the
306 Likewise, make the default button of widgets that provide "OK" and "Cancel"
308 If \fB--nocancel\fP was given that option overrides this,
309 making the default button always "Yes" (internally the same as "OK").
310 .\" ---------------------------------------------------------------------------
311 .IP \fIDIALOG_VARS.dlg_clear_screen
312 This corresponds to the command-line option "\fB--clear\fP".
313 This option is implemented in the main program, not the library.
315 the screen will be cleared on exit.
316 This may be used alone, without other options.
317 .\" ---------------------------------------------------------------------------
318 .IP \fIDIALOG_VARS.exit_label
319 This corresponds to the command-line option "\fB--exit-label string\fP".
320 The given string overrides the label used for "EXIT" buttons.
321 .\" ---------------------------------------------------------------------------
322 .IP \fIDIALOG_VARS.extra_button
323 This corresponds to the command-line option "\fB--extra-button\fP".
324 If true, some widgets show an extra button,
325 between "OK" and "Cancel" buttons.
326 .\" ---------------------------------------------------------------------------
327 .IP \fIDIALOG_VARS.extra_label
328 This corresponds to the command-line option "\fB--extra-label\fP \fIstring\fP".
329 The given string overrides the label used for "Extra" buttons.
330 Note: for inputmenu widgets, this defaults to "Rename".
331 .\" ---------------------------------------------------------------------------
332 .IP \fIDIALOG_VARS.formitem_type
333 This is set by the command-line option "\fB--passwordform\fP"
334 to tell the form widget that its text fields should be treated like
336 .\" ---------------------------------------------------------------------------
337 .IP \fIDIALOG_VARS.help_button
338 This corresponds to the command-line option "\fB--help-button\fP".
339 If true, some widgets show a help-button after "OK" and "Cancel" buttons,
340 i.e., in checklist, radiolist and menu boxes.
341 If \fB--item-help\fR is also given, on exit
342 the return status will be the same as for the "OK" button,
343 and the item-help text will be written to \fB\*p\fP's output after the token "HELP".
344 Otherwise, the return status will indicate that the Help button was pressed,
345 and no message printed.
346 .\" ---------------------------------------------------------------------------
347 .IP \fIDIALOG_VARS.help_label
348 This corresponds to the command-line option "\fB--help-label\fP \fIstring\fP".
349 The given string overrides the label used for "Help" buttons.
350 .\" ---------------------------------------------------------------------------
351 .IP \fIDIALOG_VARS.help_status
352 This corresponds to the command-line option "\fB--help-status\fP".
353 If true, and the the help-button is selected,
354 writes the checklist or radiolist information
355 after the item-help "HELP" information.
356 This can be used to reconstruct the state of a checklist after processing
358 .\" ---------------------------------------------------------------------------
359 .IP \fIDIALOG_VARS.input_length
360 This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated,
361 versus being a pointer to the user's local variables.
362 .\" ---------------------------------------------------------------------------
363 .IP \fIDIALOG_VARS.input_menu
364 This flag is set to denote whether the menubox widget
365 implements a menu versus a inputmenu widget.
366 .\" ---------------------------------------------------------------------------
367 .IP \fIDIALOG_VARS.input_result
368 This may be either a user-supplied buffer,
369 or a buffer dynamically allocated by the library,
370 depending on \fIDIALOG_VARS.input_length\fP:
373 If \fIDIALOG_VARS.input_length\fP is zero,
374 this is a pointer to user buffer (on the stack, or static).
375 The buffer size is assumed to be \fBMAX_LEN\fP,
376 which is defined in \fI<\*l.h>\fP.
378 When \fIDIALOG_VARS.input_length\fP is nonzero,
379 this is a dynamically-allocated buffer used by the widgets to return
380 printable results to the calling application.
383 Certain widgets copy a result to this buffer.
384 If the pointer is NULL, or if the length is insufficient for
385 the result, then the \fB\*l\fP library allocates a buffer which is large enough,
386 and sets \fIDIALOG_VARS.input_length\fP.
387 Callers should check for this case if they have supplied their own buffer.
388 .\" ---------------------------------------------------------------------------
389 .IP \fIDIALOG_VARS.insecure
390 This corresponds to the command-line option "\fB--insecure\fP".
391 If true, make the password widget friendlier but less secure,
392 by echoing asterisks for each character.
393 .\" ---------------------------------------------------------------------------
394 .IP \fIDIALOG_VARS.item_help
395 This corresponds to the command-line option "\fB--item-help\fP".
397 interpret the tags data for checklist, radiolist and menu boxes
398 adding a column whose text is displayed in the bottom line of the
399 screen, for the currently selected item.
400 .\" ---------------------------------------------------------------------------
401 .IP \fIDIALOG_VARS.keep_tite
402 This is set by the command-line option "\fB--keep-tite\fP"
403 to tell \fB\*p\fP to not attempt to cancel the terminal initialization
404 (termcap \fIti\fP/\fIte\fP) sequences which correspond to xterm's alternate-screen
406 Normally \fB\*p\fP does this to avoid flickering when run several times
408 .\" ---------------------------------------------------------------------------
409 .IP \fIDIALOG_VARS.keep_window
410 This corresponds to the command-line option "\fB--keep-window\fP".
411 If true, do not remove/repaint the window on exit.
412 This is useful for keeping the window contents visible when several
413 widgets are run in the same process.
414 Note that curses will clear the screen when starting a new process.
415 .\" ---------------------------------------------------------------------------
416 .IP \fIDIALOG_VARS.max_input
417 This corresponds to the command-line option "\fB--max-input\fP \fIsize\fP".
418 Limit input strings to the given size.
419 If not specified, the limit is 2048.
420 .\" ---------------------------------------------------------------------------
421 .IP \fIDIALOG_VARS.no_label
422 This corresponds to the command-line option "\fB--no-label\fP \fIstring\fP".
423 The given string overrides the label used for "No" buttons.
424 .\" ---------------------------------------------------------------------------
425 .IP \fIDIALOG_VARS.no_lines
426 .\" ---------------------------------------------------------------------------
427 .IP \fIDIALOG_VARS.nocancel
428 This corresponds to the command-line option "\fB--no-cancel\fP".
430 suppress the "Cancel" button in checklist, inputbox and menu box modes.
431 A script can still test if the user pressed the ESC key to cancel to quit.
432 .\" ---------------------------------------------------------------------------
433 .IP \fIDIALOG_VARS.nocollapse
434 This corresponds to the command-line option "\fB--no-collapse\fP".
435 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
436 spaces to a single space for text which is displayed in a message boxes, etc.
437 It true, that feature is disabled.
438 Note that \fB\*p\fR will still wrap text, subject to the \fB--cr-wrap\fR
440 .\" ---------------------------------------------------------------------------
441 .IP \fIDIALOG_VARS.nook
442 .\" ---------------------------------------------------------------------------
443 .IP \fIDIALOG_VARS.ok_label
444 This corresponds to the command-line option "\fB--ok-label\fP \fIstring\fP".
445 The given string overrides the label used for "OK" buttons.
446 .\" ---------------------------------------------------------------------------
447 .IP \fIDIALOG_VARS.print_siz
448 This corresponds to the command-line option "\fB--print-size\fP".
450 each widget prints its size to \fB\*p\fP's output when it is invoked.
451 .\" ---------------------------------------------------------------------------
452 .IP \fIDIALOG_VARS.quoted
453 .\" ---------------------------------------------------------------------------
454 .IP \fIDIALOG_VARS.separate_output
455 This corresponds to the command-line option "\fB--separate-output\fP".
457 checklist widgets output result one line at a time, with no quoting.
458 This facilitates parsing by another program.
459 .\" ---------------------------------------------------------------------------
460 .IP \fIDIALOG_VARS.single_quoted
461 This corresponds to the command-line option "\fB--single-quoted\fP".
463 Use single-quoting as needed (and no quotes if unneeded) for the
464 output of checklist's as well as the item-help text.
465 If this option is not set, \fB\*p\fP uses double quotes around each item.
466 That requires occasional use of backslashes to make the output useful in
468 .IP \fIDIALOG_VARS.size_err
469 This corresponds to the command-line option "\fB--size-err\fP".
471 check the resulting size of a dialog box before trying to use it,
472 printing the resulting size if it is larger than the screen.
473 (This option is obsolete, since all new-window calls are checked).
474 .\" ---------------------------------------------------------------------------
475 .IP \fIDIALOG_VARS.sleep_secs
476 This corresponds to the command-line option "\fB--sleep\fP \fIsecs\fP".
477 This option is implemented in the main program, not the library.
478 If nonzero, this is the number of seconds after to delay after processing a dialog box.
479 .\" ---------------------------------------------------------------------------
480 .IP \fIDIALOG_VARS.tab_correct
481 This corresponds to the command-line option "\fB--tab-correct\fP".
482 If true, convert each tab character of the text to one or more spaces.
483 Otherwise, tabs are rendered according to the curses library's interpretation.
484 .\" ---------------------------------------------------------------------------
485 .IP \fIDIALOG_VARS.time_format
486 This corresponds to the command-line option "\fB--time-format\fP \fIstring\fP".
487 If the host provides \fBstrftime\fP, and the value is nonnull,
488 the timebox widget uses this to format its output.
489 .\" ---------------------------------------------------------------------------
490 .IP \fIDIALOG_VARS.timeout_secs
491 This corresponds to the command-line option "\fB--timeout\fP \fIsecs\fP".
492 If nonzero, timeout input requests (exit with error code)
493 if no user response within the given number of seconds.
494 .\" ---------------------------------------------------------------------------
495 .IP \fIDIALOG_VARS.title
496 This corresponds to the command-line option "\fB--title\fP \fItitle\fP".
499 string to be displayed at the top of the dialog box.
500 .\" ---------------------------------------------------------------------------
501 .IP \fIDIALOG_VARS.trim_whitespace
502 This corresponds to the command-line option "\fB--trim\fP".
503 If true, eliminate leading blanks,
504 trim literal newlines and repeated blanks from message text.
505 .\" ---------------------------------------------------------------------------
506 .IP \fIDIALOG_VARS.visit_items
507 This corresponds to the command-line option "\fB--visit-items\fP".
508 Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
509 to include the list of items as one of the states.
510 This is useful as a visual aid,
511 i.e., the cursor position helps some users.
512 .\" ---------------------------------------------------------------------------
513 .IP \fIDIALOG_VARS.yes_label
514 This corresponds to the command-line option "\fB--yes-label\fP \fIstring\fP".
515 The given string overrides the label used for "Yes" buttons.
517 .\" ************************************************************************
518 .\" ************************************************************************
520 Functions that implement major functionality for the command-line \fB\*p\fP
521 program, e.g., widgets, have names beginning "\fIdialog_\fP".
523 All dialog boxes have at least three parameters:
526 the caption for the box, shown on its top border.
529 the height of the dialog box.
532 the width of the dialog box.
534 Other parameters depend on the box type.
536 .\" ************************************************************************
537 .IP \fBdialog_calendar
538 implements the "\fB--calendar\fP" option.
541 is the title on the top of the widget.
543 is the prompt text shown within the widget.
545 is the height excluding the fixed-height calendar grid.
547 is the overall width of the box,
548 which is adjusted up to the calendar grid's minimum width if needed.
550 is the initial day of the week shown,
551 counting zero as Sunday.
552 If the value is negative, the current day of the week is used.
554 is the initial month of the year shown,
555 counting one as January.
556 If the value is negative, the current month of the year is used.
558 is the initial year shown.
559 If the value is negative, the current year is used.
561 .\" ************************************************************************
562 .IP \fBdialog_checklist
563 implements the "\fB--checklist\fP" and "\fB--radiolist\fP" options
564 depending on the \fIflag\fP parameter.
567 is the title on the top of the widget.
569 is the prompt text shown within the widget.
571 is the desired height of the box.
572 If zero, the height is adjusted to use the available screen size.
574 is the desired width of the box.
575 If zero, the height is adjusted to use the available screen size.
577 is the minimum height to reserve for displaying the list.
578 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
580 is the number of rows in \fIitems\fP.
582 is an array of strings which is viewed either as a list of rows
584 \fItag item status \fR
589 \fItag item status help\fR
592 depending on whether \fIdialog_vars.item_help\fP is set.
594 is either \fIFLAG_CHECK\fP, for checklists,
595 or \fIFLAG_RADIO\fP for radiolists.
597 .\" ************************************************************************
598 .IP \fBdialog_dselect
599 implements the "\fB--dselect\fP" option.
602 is the title on the top of the widget.
604 is the preselected value to show in the input-box,
605 which is used also to set the directory- and file-windows.
607 is the height excluding the minimum needed to show the dialog box framework.
608 If zero, the height is based on the screen size.
610 is the desired width of the box.
611 If zero, the height is based on the screen size.
613 .\" ************************************************************************
614 .IP \fBdialog_editbox
615 implements the "\fB--editbox\fP" option.
618 is the title on the top of the widget.
620 is the name of the file from which to read.
622 is the desired height of the box.
623 If zero, the height is adjusted to use the available screen size.
625 is the desired width of the box.
626 If zero, the height is adjusted to use the available screen size.
628 .\" ************************************************************************
630 implements the "\fB--form\fP" option.
633 is the title on the top of the widget.
635 is the prompt text shown within the widget.
637 is the desired height of the box.
638 If zero, the height is adjusted to use the available screen size.
640 is the desired width of the box.
641 If zero, the height is adjusted to use the available screen size.
643 is the minimum height to reserve for displaying the list.
644 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
646 is the number of rows in \fIitems\fP.
648 is an array of strings which is viewed either as a list of rows
650 \fIName NameY NameX Text TextY TextX FLen ILen\fR
655 \fIName NameY NameX Text TextY TextX FLen ILen Help\fR
658 depending on whether \fIdialog_vars.item_help\fP is set.
660 .\" ************************************************************************
661 .IP \fBdialog_fselect
662 implements the "\fB--fselect\fP" option.
665 is the title on the top of the widget.
667 is the preselected value to show in the input-box,
668 which is used also to set the directory- and file-windows.
670 is the height excluding the minimum needed to show the dialog box framework.
671 If zero, the height is based on the screen size.
673 is the desired width of the box.
674 If zero, the height is based on the screen size.
676 .\" ************************************************************************
678 implements the "\fB--gauge\fP" option.
681 is the title on the top of the widget.
683 is the prompt text shown within the widget.
685 is the desired height of the box.
686 If zero, the height is based on the screen size.
688 is the desired width of the box.
689 If zero, the height is based on the screen size.
691 is the percentage to show in the progress bar.
693 .\" ************************************************************************
694 .IP \fBdialog_inputbox
695 implements the "\fB--inputbox\fP" or
696 "\fB--password\fP" option, depending on the value of \fIpassword\fP.
699 is the title on the top of the widget.
701 is the prompt text shown within the widget.
703 is the desired height of the box.
704 If zero, the height is based on the screen size.
706 is the desired width of the box.
707 If zero, the height is based on the screen size.
709 is the initial value of the input box, whose length is taken into account
710 when auto-sizing the width of the dialog box.
712 if true, causes typed input to be echoed as asterisks.
714 .\" ************************************************************************
716 implements the "\fB--menu\fP" or "\fB--inputmenu\fP" option
717 depending on whether \fIdialog_vars.input_menu\fP is set.
720 is the title on the top of the widget.
722 is the prompt text shown within the widget.
724 is the desired height of the box.
725 If zero, the height is based on the screen size.
727 is the desired width of the box.
728 If zero, the height is based on the screen size.
730 is the minimum height to reserve for displaying the list.
731 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
733 is the number of rows in \fIitems\fP.
735 is an array of strings which is viewed either as a list of rows
745 depending on whether \fIdialog_vars.item_help\fP is set.
747 .\" ************************************************************************
748 .IP \fBdialog_mixedform
749 implements the "\fB--mixedform\fP" option.
752 is the title on the top of the widget.
754 is the prompt text shown within the widget.
756 is the desired height of the box.
757 If zero, the height is adjusted to use the available screen size.
759 is the desired width of the box.
760 If zero, the height is adjusted to use the available screen size.
762 is the minimum height to reserve for displaying the list.
763 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
765 is the number of rows in \fIitems\fP.
767 is an array of strings which is viewed either as a list of rows
769 \fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR
774 \fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR
777 depending on whether \fIdialog_vars.item_help\fP is set.
779 .\" ************************************************************************
780 .IP \fBdialog_mixedgauge
781 implements the "\fB--mixedgauge\fP" option
784 is the title on the top of the widget.
786 is the caption text shown within the widget.
788 is the desired height of the box.
789 If zero, the height is based on the screen size.
791 is the desired width of the box.
792 If zero, the height is based on the screen size.
794 is the percentage to show in the progress bar.
796 is the number of rows in \fIitems\fP.
798 is an array of strings which is viewed as a list of \fItag\fP and \fIitem\fP values.
799 The \fItag\fP values are listed, one per row, in the list at the top of
802 The \fIitem\fP values are decoded: digits 0-9 are the following strings
826 A string with a leading "-" character is centered, marked with "%".
827 For example, "-75" is displayed as "75%".
828 Other strings are displayed as is.
830 .\" ************************************************************************
832 implements the "\fB--msgbox\fP" or "\fB--infobox\fP" option
833 depending on whether \fIpauseopt\fP is set.
836 is the title on the top of the widget.
838 is the prompt text shown within the widget.
840 is the desired height of the box.
841 If zero, the height is based on the screen size.
843 is the desired width of the box.
844 If zero, the height is based on the screen size.
846 if true, an "OK" button will be shown,
847 and the dialog will wait for it to complete.
848 With an "OK" button, it is denoted a "msgbox",
849 without an "OK" button, it is denoted an "infobox".
851 .\" ************************************************************************
853 implements the "\fB--pause\fP" option.
856 is the title on the top of the widget.
858 is the desired height of the box.
859 If zero, the height is based on the screen size.
861 is the desired width of the box.
862 If zero, the height is based on the screen size.
864 is the timeout to use for the progress bar.
866 .\" ************************************************************************
868 implements the "\fB--prgbox\fP" option.
871 is the title on the top of the widget.
873 is the prompt text shown within the widget.
874 If empty or null, no prompt is shown.
876 is the name of the command to execute.
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 if true, an "OK" button will be shown,
885 and the dialog will wait for it to complete.
887 .\" ************************************************************************
888 .IP \fBdialog_progressbox
889 implements the "\fB--progressbox\fP" option.
892 is the title on the top of the widget.
894 is the prompt text shown within the widget.
895 If empty or null, no prompt is shown.
897 is the desired height of the box.
898 If zero, the height is based on the screen size.
900 is the desired width of the box.
901 If zero, the height is based on the screen size.
903 .\" ************************************************************************
904 .IP \fBdialog_tailbox
905 implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option
906 depending on whether \fIbg_task\fP is set.
909 is the title on the top of the widget.
911 is the name of the file to display in the dialog.
913 is the desired height of the box.
914 If zero, the height is based on the screen size.
916 is the desired width of the box.
917 If zero, the height is based on the screen size.
920 the window is added to the callback list in \fIdialog_state\fP,
921 and the application will poll for the window to be updated.
922 Otherwise an "OK" button is added to the window,
923 and it will be closed when the button is activated.
925 .\" ************************************************************************
926 .IP \fBdialog_textbox
927 implements the "\fB--textbox\fP" option.
930 is the title on the top of the widget.
932 is the name of the file to display in the dialog.
934 is the desired height of the box.
935 If zero, the height is based on the screen size.
937 is the desired width of the box.
938 If zero, the height is based on the screen size.
940 .\" ************************************************************************
941 .IP \fBdialog_timebox
942 implements the "\fB--timebox\fP" option.
945 is the title on the top of the widget.
947 is the prompt text shown within the widget.
949 is the desired height of the box.
950 If zero, the height is based on the screen size.
952 is the desired width of the box.
953 If zero, the height is based on the screen size.
955 is the initial hour shown.
956 If the value is negative, the current hour is used.
957 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24.
959 is the initial minute shown.
960 If the value is negative, the current minute is used.
961 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
963 is the initial second shown.
964 If the value is negative, the current second is used.
965 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
967 .\" ************************************************************************
969 implements the "\fB--yesno\fP" option.
972 is the title on the top of the widget.
974 is the prompt text shown within the widget.
976 is the desired height of the box.
977 If zero, the height is based on the screen size.
979 is the desired width of the box.
980 If zero, the height is based on the screen size.
983 .\" ************************************************************************
984 .SH UTILITY FUNCTIONS
985 Most functions that implement lower-level
986 functionality for the command-line \fB\*p\fP
987 program or widgets, have names beginning "\fIdlg_\fP".
988 Bowing to longstanding usage, the functions that initialize the
989 display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP.
991 The only non-widget function whose name begins with "\fIdialog_\fP"
992 is \fIdialog_version\fP, which returns the version number of the
996 Here is a brief summary of the utility functions and their parameters:
997 .\" ---------------------------------------------------------------------------
1000 Add a callback, used to allow polling input from multiple tailbox
1004 .B DIALOG_CALLBACK *\fIp\fP
1005 contains the callback information.
1007 .\" ---------------------------------------------------------------------------
1009 .B dlg_add_callback_ref
1010 Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP
1011 as well as a pointer to a cleanup function which will be called when the
1012 associated input ends.
1015 .B DIALOG_CALLBACK **\fIp\fP
1016 points to the callback information.
1017 This is a reference to the pointer so that the caller's pointer can be
1018 zeroed when input ends.
1020 .B DIALOG_FREEBACK \fIfunc\fP
1021 function to call when input ends, e.g., to free caller's additional data.
1023 .\" ---------------------------------------------------------------------------
1026 Add a quoted string to the result buffer (see \fBdlg_add_result\fP).
1030 is the string to add.
1032 .\" ---------------------------------------------------------------------------
1035 Add a quoted string to the result buffer \fBdialog_vars.input_result\fP.
1039 is the string to add.
1041 .\" ---------------------------------------------------------------------------
1043 .B dlg_add_separator
1044 Add an output-separator to the result buffer \fBdialog_vars.input_result\fP.
1045 If \fBdialog_vars.output_separator\fP is set, use that.
1046 Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline.
1047 If neither is set, use a space.
1048 .\" ---------------------------------------------------------------------------
1051 Add a quoted or unquoted string to the result buffer
1052 (see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP),
1053 according to whether \fBdialog_vars.quoted\fP is true.
1057 is the string to add.
1059 .\" ---------------------------------------------------------------------------
1061 .B dlg_align_columns
1062 Copy and reformat an array of pointers to strings, aligning according to
1063 the column separator \fBdialog_vars.column_separator\fP.
1064 If no column separator is set, the array will be unmodified;
1065 otherwise it is copied and reformatted.
1067 Caveat: This function is only implemented for 8-bit characters.
1071 This is the array to reformat.
1072 It points to the first string to modify.
1075 This is the size of the struct for each row of the array.
1078 This is the number of rows in the array.
1080 .\" ---------------------------------------------------------------------------
1083 returns its parameter transformed to the
1084 corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP.
1085 If the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns 0.
1087 .\" ---------------------------------------------------------------------------
1090 Set window to the given attribute.
1094 is the window to update.
1097 is the number of rows to update.
1100 is the number of columns to update.
1103 is the attribute, e.g., \fBA_BOLD\fP.
1105 .\" ---------------------------------------------------------------------------
1108 Automatically size the window used for a widget.
1109 If the given height or width are zero,
1110 justify the \fIprompt\fP text and return the actual limits.
1113 .B const char * \fItitle
1114 is the title string to display at the top of the widget.
1116 .B const char * \fIprompt
1117 is the message text which will be displayed in the widget,
1118 used here to determine how large the widget should be.
1121 is the nominal height.
1124 is the nominal width.
1127 is the number of lines to reserve in the vertical direction.
1130 is the minimum number of columns to use.
1132 .\" ---------------------------------------------------------------------------
1134 .B dlg_auto_sizefile
1135 Like \fBdlg_auto_size\fP, but use a file contents to decide how large
1136 the widget should be.
1139 .B const char * \fItitle
1140 is the title string to display at the top of the widget.
1142 .B const char * \fIfile
1143 is the name of the file.
1146 is the nominal height.
1147 If it is -1, use the screen's height after subtracting \fBdialog_vars.begin_y\fP
1148 if \fBdialog_vars.begin_set\fP is true.
1151 is the nominal width.
1152 If it is -1, use the screen's width after subtracting \fBdialog_vars.begin_x\fP
1153 if \fBdialog_vars.begin_set\fP is true.
1156 is the number of lines to reserve on the screen for drawing boxes.
1159 is the number of columns to reserve on the screen for drawing boxes.
1161 .\" ---------------------------------------------------------------------------
1164 If \fBdialog_vars.beep_signal\fP is nonzero,
1165 this calls \fBbeep\fP once and sets
1166 \fBdialog_vars.beep_signal\fP to zero.
1167 .\" ---------------------------------------------------------------------------
1170 returns its parameter transformed as follows:
1174 if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set.
1177 if \fBdialog_vars.ascii_lines\fP is set, returns the corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP.
1180 otherwise, if \fBdialog_vars.no_lines\fP is set, returns a space for the line-drawing characters.
1183 if the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns the parameter unchanged.
1185 .\" ---------------------------------------------------------------------------
1187 .B dlg_box_x_ordinate
1188 returns a suitable x-ordinate (column) for a new widget.
1189 If \fBdialog_vars.begin_set\fP is 1,
1190 use \fBdialog_vars.begin_x\fP;
1191 otherwise center the widget on the screen (using the \fIwidth\fP parameter).
1195 is the width of the widget.
1197 .\" ---------------------------------------------------------------------------
1199 .B dlg_box_y_ordinate
1200 returns a suitable y-ordinate (row) for a new widget.
1201 If \fBdialog_vars.begin_set\fP is 1,
1202 use \fBdialog_vars.begin_y\fP;
1203 otherwise center the widget on the screen (using the \fIheight\fP parameter).
1207 is the height of the widget.
1209 .\" ---------------------------------------------------------------------------
1212 Count the buttons in the list.
1215 .B const char ** \fIlabels
1216 is a list of (pointers to) button labels terminated by a null pointer.
1218 .\" ---------------------------------------------------------------------------
1220 .B dlg_button_layout
1221 Make sure there is enough space for the buttons by
1222 computing the width required for their labels,
1223 adding margins and limiting based on the screen size.
1226 .B const char ** \fIlabels
1227 is a list of (pointers to) button labels terminated by a null pointer.
1230 the function sets the referenced \fIlimit\fP to the width required for
1231 the buttons (limited by the screen size)
1232 if that is wider than the passed-in limit.
1234 .\" ---------------------------------------------------------------------------
1237 Compute the size of the button array in columns.
1240 .B const char ** \fIlabels
1241 is a list of (pointers to) button labels terminated by a null pointer.
1244 is true if the buttons are arranged in a column rather than a row.
1247 Return the total number of columns in the referenced location.
1250 Return the longest button's columns in the referenced location.
1252 .\" ---------------------------------------------------------------------------
1254 .B dlg_button_x_step
1255 Compute the step-size needed between elements of the button array.
1258 .B const char ** \fIlabels
1259 is a list of (pointers to) button labels terminated by a null pointer.
1262 is the maximum number of columns to allow for the buttons.
1265 store the nominal gap between buttons in the referenced location.
1266 This is constrained to be at least one.
1269 store the left+right total margins (for the list of buttons) in the referenced
1273 store the step-size in the referenced location.
1275 .\" ---------------------------------------------------------------------------
1277 .B dlg_button_to_char
1278 Find the first uppercase character in the label, which we may use for an
1280 If the label is empty, return -1.
1281 If no uppercase character is found, return 0.
1282 Otherwise return the uppercase character.
1285 .B const char * \fIlabel
1286 is the label to test.
1288 .\" ---------------------------------------------------------------------------
1290 .B dlg_calc_list_width
1291 Calculate the minimum width for the list, assuming none of the items
1296 is the number of \fIitems\fP.
1298 .B DIALOG_LISTITEM * \fIitems
1299 contains a \fIname\fP and \fItext\fP field,
1300 e.g., for checklists or radiobox lists.
1301 The function returns the sum of the widest columns
1302 needed for of each of these fields.
1304 .\" ---------------------------------------------------------------------------
1307 Calculate new height and list_height values.
1311 on input, is the height without adding the list-height.
1312 On return, this contains the total list-height and is the
1313 actual widget's height.
1315 .B int * \fIlist_height
1316 on input, is the requested list-height.
1317 On return, this contains the number of rows available for displaying
1318 the list after taking into account the screen size and
1319 the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables.
1322 is the number of \fIitems\fP in the list.
1324 .\" ---------------------------------------------------------------------------
1327 This function is obsolete, provided for library-compatibility.
1328 It is replaced by \fIdlg_calc_list_width\fP.
1332 is the number of \fIitems\fP.
1335 is a list of character pointers.
1338 is the number of items in each group, e.g., the second array index.
1340 .\" ---------------------------------------------------------------------------
1342 .B dlg_char_to_button
1343 Given a list of button labels,
1344 and a character which may be the abbreviation for one, find it, if it exists.
1345 An abbreviation will be the first character
1346 which happens to be capitalized in the label.
1347 If the character is found, return its index within the list of \fIlabels\fP.
1348 Otherwise, return \fBDLG_EXIT_UNKNOWN\fP.
1352 is the character to find.
1354 .B const char ** \fIlabels
1355 is a list of (pointers to) button labels terminated by a null pointer.
1357 .\" ---------------------------------------------------------------------------
1360 This entrypoint provides the \fB--checklist\fP or \fP--radiolist\fP
1361 functionality without the limitations of \fB\*p\fP's command-line syntax
1362 (compare to \fBdialog_checklist\fP).
1365 .B const char * \fItitle
1366 is the title string to display at the top of the widget.
1368 .B const char * \fIcprompt
1369 is the prompt text shown within the widget.
1372 is the desired height of the box.
1373 If zero, the height is adjusted to use the available screen size.
1376 is the desired width of the box.
1377 If zero, the height is adjusted to use the available screen size.
1379 .B int \fIlist_height
1380 is the minimum height to reserve for displaying the list.
1381 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1384 is the number of \fIitems\fP.
1386 .B DIALOG_LISTITEM * \fIitems
1387 This is a list of the items to display in the checklist.
1389 .B const char * \fIstates
1390 This is a list of characters to display for the given states.
1391 Normally a checklist provides true (1) and false (0) values,
1392 which the widget displays as "*" and space, respectively.
1393 An application may set this parameter to an arbitrary null-terminated string.
1394 The widget determines the number of states from the length of this string,
1395 and will cycle through the corresponding display characters as the user
1396 presses the space-bar.
1399 This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP,
1400 depending on whether the widget should act as a checklist or radiobox.
1402 .B int * \fIcurrent_item
1403 The widget sets the referenced location to the index of the current display
1404 item (cursor) when it returns.
1406 .\" ---------------------------------------------------------------------------
1408 .B dlg_check_scrolled
1409 given a function key (or other key that was mapped to a function key),
1410 check if it is one of the up/down scrolling functions:
1427 Some widgets use these key bindings for scrolling the prompt-text up and
1428 down, to allow for display in very small windows.
1430 The function returns 0 (zero) if it finds one of these keys,
1435 is the function-key to check
1438 is the number of lines
1439 which would be used to display the scrolled prompt in
1440 an arbitrarily tall window.
1441 It is used here to check limits for the \fIoffset\fP value.
1444 this is the available height for writing scrolled text,
1445 which is smaller than the window if it contains buttons.
1448 on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay
1452 on entry, holds the starting line number (counting from zero)
1453 last used for \fBdlg_print_scrolled\fP.
1454 On return, holds the updated starting line number.
1456 .\" ---------------------------------------------------------------------------
1459 Set window to the default \fB\*p\fP screen attribute.
1460 This is set in the rc-file with \fBscreen_color\fP.
1461 .\" ---------------------------------------------------------------------------
1464 Free storage used for the result buffer (\fBdialog_vars.input_result\fP).
1465 The corresponding pointer is set to NULL.
1466 .\" ---------------------------------------------------------------------------
1469 Return the number of colors that can be configured in \fB\*p\fP.
1470 .\" ---------------------------------------------------------------------------
1473 Initialize the color pairs used in \fB\*p\fP.
1474 .\" ---------------------------------------------------------------------------
1477 Count the entries in an argument vector.
1481 Points to the argument vector.
1483 .\" ---------------------------------------------------------------------------
1485 .B dlg_count_columns
1486 Returns the number of columns used for a string.
1487 This is not necessarily the number of bytes in a string.
1490 .B const char * \fIstring
1491 is the string to measure.
1493 .\" ---------------------------------------------------------------------------
1496 Returns the number of wide-characters in the string.
1499 .B const char * \fIstring
1500 is the string to measure.
1502 .\" ---------------------------------------------------------------------------
1505 Create a configuration file,
1506 i.e., write internal tables to a file which can be read back by \fB\*p\fP
1510 .B const char * \fIfilename
1511 is the name of the file to write to.
1513 .\" ---------------------------------------------------------------------------
1516 If \fBdialog_vars.size_err\fP is true,
1517 check if the given window size is too large to fit on the screen.
1518 If so, exit with an error reporting the size of the window.
1522 is the window's height
1525 is the window's width
1527 .\" ---------------------------------------------------------------------------
1529 .B dlg_default_formitem
1530 If \fBdialog_vars.default_item\fP is not null,
1531 find that name by matching the \fIname\fP field in the list of form \fIitems\fP.
1532 If found, return the index of that item in the list.
1533 Otherwise, return zero.
1536 .B DIALOG_FORMITEM * \fIitems
1537 is the list of items to search.
1538 It is terminated by an entry with a null \fIname\fP field.
1540 .\" ---------------------------------------------------------------------------
1543 This function is obsolete, provided for library-compatibility.
1544 It is replaced by \fIdlg_default_formitem\fP and \fIdlg_default_listitem\fP.
1548 is the list of items to search.
1551 is the number of items in each group, e.g., the second array index.
1553 .\" ---------------------------------------------------------------------------
1555 .B dlg_defaultno_button
1556 If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not,
1557 find the button-index for the "Cancel" button.
1558 Otherwise, return the index for "OK" (always zero).
1559 .\" ---------------------------------------------------------------------------
1562 Remove a window, repainting everything else.
1566 is the window to remove.
1568 .\" ---------------------------------------------------------------------------
1571 This is called each time a widget is invoked which may do output.
1572 It increments \fBdialog_state.output_count\fP,
1573 so the output function in \fB\*p\fP can test this and add a separator.
1574 .\" ---------------------------------------------------------------------------
1577 Draw up/down arrows on a window, e.g., for scrollable lists.
1578 It calls \fBdlg_draw_arrows2\fP using the
1579 \fImenubox_color\fP and \fImenubox_border_color\fP attributes.
1582 .B WINDOW * \fIdialog
1583 is the window on which to draw an arrow.
1586 is true if an up-arrow should be drawn at the top of the window.
1588 .B int \fIbottom_arrow
1589 is true if an down-arrow should be drawn at the bottom of the window.
1592 is the zero-based column within the window on which to draw arrows.
1595 is the zero-based row within the window on which to draw up-arrows
1596 as well as a horizontal line to show the window's top.
1599 is the zero-based row within the window on which to draw down-arrows
1600 as well as a horizontal line to show the window's bottom.
1602 .\" ---------------------------------------------------------------------------
1605 Draw up/down arrows on a window, e.g., for scrollable lists.
1608 .B WINDOW * \fIdialog
1609 is the window on which to draw an arrow.
1612 is true if an up-arrow should be drawn at the top of the window.
1614 .B int \fIbottom_arrow
1615 is true if an down-arrow should be drawn at the bottom of the window.
1618 is the zero-based column within the window on which to draw arrows.
1621 is the zero-based row within the window on which to draw up-arrows
1622 as well as a horizontal line to show the window's top.
1625 is the zero-based row within the window on which to draw down-arrows
1626 as well as a horizontal line to show the window's bottom.
1629 is the window's background attribute.
1631 .B chtype \fIborderattr
1632 is the window's border attribute.
1634 .\" ---------------------------------------------------------------------------
1636 .B dlg_draw_bottom_box
1637 Draw a partial box at the bottom of a window,
1638 e.g., to surround a row of buttons.
1639 It is designed to merge with an existing box around
1640 the whole window, so it uses tee-elements rather than corner-elements
1641 on the top corners of this box.
1645 is the window to update.
1647 .\" ---------------------------------------------------------------------------
1650 Draw a rectangular box with line drawing characters.
1654 is the window to update.
1657 is the top row of the box.
1660 is the left column of the box.
1663 is the height of the box.
1666 is the width of the box.
1668 .B chtype \fIboxchar
1669 is used to color the right/lower edges.
1670 It also is fill-color used for the box contents.
1672 .B chtype \fIborderchar
1673 is used to color the upper/left edges.
1675 .\" ---------------------------------------------------------------------------
1678 Print a list of buttons at the given position.
1682 is the window to update.
1685 is the starting row.
1688 is the starting column.
1690 .B const char ** \fIlabels
1691 is a list of (pointers to) button labels terminated by a null pointer.
1694 is the index within the list of the selected button.
1697 is true if the buttons are arranged in a column rather than a row.
1700 is the number of columns (or rows if \fIvertical\fP) allowed for the display.
1702 .\" ---------------------------------------------------------------------------
1704 .B dlg_draw_scrollbar
1705 If \fBdialog_state.use_scrollbar\fP is set,
1706 draw a scrollbar on the right margin of windows holding scrollable data.
1707 Also (whether or not the scrollbar is drawn),
1708 annotate the bottom margin of the window with the percentage of data
1709 by the bottom of that window,
1710 and call \fBdlg_draw_arrows2\fP to put markers on the window showing
1711 when more data is available.
1715 is the window in which the data is scrolled.
1716 Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP
1717 are passed as parameters, this window can contain additional data.
1719 .B long \fIfirst_data
1720 is the zero-based index to the first row of data in the current window.
1722 .B long \fIthis_data
1723 is the zero-based index to the current row of data.
1725 .B long \fInext_data
1726 is the zero-based index to the next data after the current row.
1728 .B long \fItotal_data
1729 is the total number of rows of data.
1732 is the zero-based left margin/column of the window.
1733 The up/down arrows are draw inset by 5 columns from this point.
1736 is the zero-based right margin/column of the window.
1737 The scrollbar is drawn flush against this column.
1740 is the zero-based row within the window on which to draw up-arrows
1741 as well as a horizontal line to show the window's top.
1744 is the zero-based row within the window on which to draw down-arrows
1745 as well as a horizontal line to show the window's bottom.
1748 is the window's background attribute.
1750 .B chtype \fIborderattr
1751 is the window's border attribute.
1753 .\" ---------------------------------------------------------------------------
1756 Draw shadows along the right and bottom edge of a window to give it
1757 a 3-dimensional look.
1758 (The height, etc., may not be the same as the window's actual values).
1762 is the window to update.
1765 is the height of the window.
1768 is the width of the window.
1771 is the top row of the window.
1774 is the left column of the window.
1776 .\" ---------------------------------------------------------------------------
1779 Draw a title centered at the top of the window.
1783 is the window to update.
1785 .B const char * \fItitle
1786 is the title string to display at the top of the widget.
1788 .\" ---------------------------------------------------------------------------
1791 Write all user-defined key-bindings to the given stream,
1792 e.g., as part of \fBdlg_create_rc\fP.
1796 is the stream on which to write the bindings.
1798 .\" ---------------------------------------------------------------------------
1801 Remove one or more items from an argument vector.
1805 in/out parameter giving the length of the argument vector.
1807 in/out parameter pointing to the argument vector.
1811 number of arguments to remove.
1813 .\" ---------------------------------------------------------------------------
1816 Given the character-offset in the string,
1817 returns the display-offset where
1818 \fB\*p\fP should position the cursor.
1819 In this context, "characters" may be multicolumn,
1820 since the string can be a multibyte character string.
1824 is the string to analyze
1827 is the character-offset
1830 is a limit on the column positions that can be used,
1831 e.g., the window's size.
1833 .\" ---------------------------------------------------------------------------
1836 Updates the string and character-offset, given various editing characters
1837 or literal characters which are inserted at the character-offset.
1838 Returns true if an editing change was made (and the display should
1839 be updated), and false if the key was something like KEY_ENTER,
1840 which is a non-editing action outside this function.
1844 is the (multibyte) string to update
1847 is the character-offset
1853 is true if the editing key is a function-key
1856 is used in a special loop case by calling code to force the return
1857 value of this function when a function-key code 0 is passed in.
1859 .\" ---------------------------------------------------------------------------
1862 Given an internal exit code,
1863 check if the corresponding environment variable is set.
1864 If so, remap the exit code to match the environment variable.
1865 Finally call \fBexit\fP with the resulting exit code.
1869 is the internal exit code, e.g., \fBDLG_EXIT_OK\fP,
1870 which may be remapped.
1873 The \fB\*p\fP program uses this function
1874 to allow shell scripts to remap the exit codes so they can distinguish ESC
1876 .\" ---------------------------------------------------------------------------
1878 .B dlg_exit_buttoncode
1879 Map the given button index for \fBdlg_exit_label\fP into \fB\*p\fP's exit-code.
1885 .\" ---------------------------------------------------------------------------
1888 Return a list of button labels.
1889 If dialog_var.extra_button is true, return the result of \fBdlg_ok_labels\fP.
1890 Otherwise, return a list with the "Exit" label and (if \fBdialog_vars.help_button\fP
1891 is set) the "Help" button as well.
1892 .\" ---------------------------------------------------------------------------
1895 Quit program killing all \fBtailboxbg\fP widgets.
1898 .B const char * \fIfmt
1899 is the format of the \fBprintf\fP-like message to write.
1902 are the variables to apply to the \fIfmt\fP format.
1904 .\" ---------------------------------------------------------------------------
1907 Given the character-offset to find in the list, return the corresponding
1911 .B const int *\fIlist
1912 contains a list of character-offsets,
1913 i.e., indices into a string that denote the beginning of multibyte characters.
1916 is the last index into \fBlist\fP to search.
1919 is the character-offset to find.
1921 .\" ---------------------------------------------------------------------------
1924 Cancel the local data saved by \fBdlg_last_getc\fP.
1925 .\" ---------------------------------------------------------------------------
1927 This entrypoint provides the \fB--editbox\fP
1928 functionality without the limitations of \fB\*p\fP's command-line syntax
1929 (compare to \fBdialog_editbox\fP).
1932 .B const char * \fItitle
1933 is the title string to display at the top of the widget.
1936 is a pointer to an array of \fBchar\ *\fP pointers.
1937 The array is allocated by the caller,
1938 and so are the strings to which it points.
1939 The \fBdlg_editbox\fP function may reallocate the
1940 array and the strings.
1943 points to the nominal length of \fIlist\fP.
1944 The referenced value is updated if\fIlist\fP is reallocated.
1947 is the desired height of the box.
1948 If zero, the height is adjusted to use the available screen size.
1951 is the desired width of the box.
1952 If zero, the height is adjusted to use the available screen size.
1954 .\" ---------------------------------------------------------------------------
1957 This entrypoint provides the \fB--form\fP
1958 functionality without the limitations of \fB\*p\fP's command-line syntax
1959 (compare to \fBdialog_form\fP).
1962 .B const char * \fItitle
1963 is the title string to display at the top of the widget.
1965 .B const char * \fIcprompt
1966 is the prompt text shown within the widget.
1969 is the desired height of the box.
1970 If zero, the height is adjusted to use the available screen size.
1973 is the desired width of the box.
1974 If zero, the height is adjusted to use the available screen size.
1976 .B int \fIform_height
1977 is the minimum height to reserve for displaying the list.
1978 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1981 is the number of \fIitems\fP.
1983 .B DIALOG_FORMITEM * \fIitems
1984 This is a list of the items to display in the form.
1986 .B int * \fIcurrent_item
1987 The widget sets the referenced location to the index of the current display
1988 item (cursor) when it returns.
1990 .\" ---------------------------------------------------------------------------
1993 Free data allocated by \fBdlg_align_columns\fP.
1997 This is the array which was reformatted.
1998 It points to the first string to free.
2001 This is the size of the struct for each row of the array.
2004 This is the number of rows in the array.
2006 .\" ---------------------------------------------------------------------------
2008 .B dlg_free_formitems
2009 Free memory owned by a list of DIALOG_FORMITEM's.
2012 .B DIALOG_FORMITEM * \fIitems
2013 is the list to free.
2015 .\" ---------------------------------------------------------------------------
2018 Read a character from the given window.
2019 Handle repainting here (to simplify
2020 things in the calling application).
2021 Also, if input-callback(s) are set up,
2022 poll the corresponding files and handle the updates,
2023 e.g., for displaying a tailbox.
2024 Returns the key-code.
2028 is the window within which to read.
2031 as a side-effect, set this to true if the key-code is really a function-key.
2033 .\" ---------------------------------------------------------------------------
2036 extract the video attributes from the given window.
2040 is the window from which to get attributes.
2042 .\" ---------------------------------------------------------------------------
2044 .B dlg_getc_callbacks
2045 passes the given key-code \fIch\fP to the current window that
2046 has established a callback.
2047 If the callback returns zero, remove it and try the next window.
2048 If no more callbacks remain, return.
2049 If any callbacks were found, return true, otherwise false.
2056 is true if the key is a function-key
2059 is used to pass an exit-code to the caller,
2060 which should pass that via \fBdlg_exit\fP.
2062 .\" ---------------------------------------------------------------------------
2064 .B dlg_index_columns
2065 Build a list of the display-columns for the given multibyte string's characters.
2068 .B const char * \fIstring
2069 is the string to analyze
2071 .\" ---------------------------------------------------------------------------
2074 Build an index of the wide-characters in the string,
2075 so the caller can easily tell
2076 which byte-offset begins a given wide-character.
2079 .B const char * \fIstring
2080 is the string to analyze
2082 .\" ---------------------------------------------------------------------------
2085 Draw the string for the \fBdialog_vars.item_help\fP feature.
2088 .B const char * \fItxt
2091 .\" ---------------------------------------------------------------------------
2094 If \fB\*p\fP has callbacks active,
2095 purge the list of all that are not marked
2096 to keep in the background.
2097 If any remain, run those in a background process.
2101 stores the exit-code to pass back to the caller.
2103 .\" ---------------------------------------------------------------------------
2106 returns the most recent character that was read via \fBdlg_getc\fP.
2107 .\" ---------------------------------------------------------------------------
2109 .B dlg_limit_columns
2110 Given a column limit,
2111 count the number of wide characters that can fit into that limit.
2112 The offset is used to skip over a leading character
2113 that was already written.
2116 .B const char * \fIstring
2117 is the string to analyze
2123 is the starting offset from which analysis should continue
2125 .\" ---------------------------------------------------------------------------
2128 Check for a key-binding.
2129 If there is no binding associated with the widget, it simply returns
2130 the given curses-key.
2131 Otherwise, it returns the result of the binding
2135 is the window on which the binding is checked
2137 .B int \fIcurses_key
2138 is the curses key-code
2140 .B int * \fIdialog_key
2141 is the corresponding \fB\*p\fP internal code
2142 (see \fBDLG_KEYS_ENUM\fP in dlg_key.h).
2144 .\" ---------------------------------------------------------------------------
2147 Limit the parameter according to \fBdialog_vars.max_input\fP
2151 is the value to limit
2153 .\" ---------------------------------------------------------------------------
2156 Match a given character against the beginning of the string,
2157 ignoring case of the given character.
2158 The matching string must begin with an uppercase character.
2162 is the character to check
2164 .B const char * \fIstring
2165 is the string to search
2167 .\" ---------------------------------------------------------------------------
2170 This entrypoint provides the \fB--menu\fP
2171 functionality without the limitations of \fB\*p\fP's command-line syntax
2172 (compare to \fBdialog_menu\fP).
2175 .B const char * \fItitle
2176 is the title string to display at the top of the widget.
2178 .B const char * \fIcprompt
2179 is the prompt text shown within the widget.
2182 is the desired height of the box.
2183 If zero, the height is adjusted to use the available screen size.
2186 is the desired width of the box.
2187 If zero, the height is adjusted to use the available screen size.
2189 .B int \fImenu_height
2190 is the minimum height to reserve for displaying the list.
2191 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2194 is the number of \fIitems\fP.
2196 .B DIALOG_LISTITEM * \fIitems
2197 This is a list of the items to display in the form.
2199 .B int * \fIcurrent_item
2200 The widget sets the referenced location to the index of the current display
2201 item (cursor) when it returns.
2203 .B DIALOG_INPUTMENU \fIrename_menutext
2205 .\" ---------------------------------------------------------------------------
2208 Moves/resizes the given window to the given position and size.
2212 is the window to move/resize.
2214 .B WINDOW *\fIheight
2215 is the height of the resized window.
2218 is the width of the resized window.
2221 y-ordinate to use for the repositioned window.
2224 x-ordinate to use for the repositioned window.
2226 .\" ---------------------------------------------------------------------------
2228 .B dlg_mouse_bigregion
2229 Retrieve the big-region under the pointer.
2233 is the row on which the mouse click occurred
2236 is the column on which the mouse click occurred
2238 .\" ---------------------------------------------------------------------------
2240 .B dlg_mouse_free_regions
2241 Free the memory associated with mouse regions.
2242 .\" ---------------------------------------------------------------------------
2244 .B dlg_mouse_mkbigregion
2245 Creates a region on which the mouse-clicks will return a specifed code.
2249 is the top-row of the region.
2252 is the left-column of the region.
2255 is the height of the region.
2258 is the width of the region.
2261 is a code used to make the region unique within a widget
2264 is used in modes 2 (columns) and 3 (cells) to determine the width
2271 is used to determine how the mouse position is translated into
2272 a code (like a function-key):
2285 .\" ---------------------------------------------------------------------------
2287 .B dlg_mouse_mkregion
2291 is the top-row of the region.
2294 is the left-column of the region.
2297 is the height of the region.
2300 is the width of the region.
2303 is a code used to make the region unique within a widget
2305 .\" ---------------------------------------------------------------------------
2308 Retrieve the frame under the mouse pointer
2312 is the row of the mouse-click
2315 is the column of the mouse-click
2317 .\" ---------------------------------------------------------------------------
2319 .B dlg_mouse_setbase
2320 Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP,
2321 so they can make regions relative to the start of a given window.
2325 is the left-column for the base
2328 is the top-row for the base
2330 .\" ---------------------------------------------------------------------------
2333 is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks
2334 (if the curses library supports those) into extended function-keys
2335 which encode the position according to the \fImode\fP in
2336 \fBdlg_mouse_mkbigregion\fP.
2337 Returns the corresponding key-code.
2341 is the window on which to perform the input
2344 the referenced location is set to true if the key-code is an actual
2345 or extended (mouse) function-key.
2347 .\" ---------------------------------------------------------------------------
2349 .B dlg_mouse_wgetch_nowait
2350 This is a non-blocking variant of \fBdlg_mouse_wgetch\fP.
2354 is the window on which to perform the input
2357 the referenced location is set to true if the key-code is an actual
2358 or extended (mouse) function-key.
2360 .\" ---------------------------------------------------------------------------
2362 .B dlg_need_separator
2363 Check if an output-separator is needed.
2364 If \fBdialog_vars.output_separator\fP is set, return true.
2365 Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true.
2366 If neither, return false.
2367 .\" ---------------------------------------------------------------------------
2369 .B dlg_new_modal_window
2370 Create a modal window, optionally with a shadow.
2371 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2374 .B WINDOW * \fIparent
2375 is the parent window (usually the top-level window of a widget)
2378 is the window's height
2381 is the window's width
2384 is the window's top-row
2387 is the window's left-column
2389 .\" ---------------------------------------------------------------------------
2392 Create a window, optionally with a shadow.
2393 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2397 is the window's height
2400 is the window's width
2403 is the window's top-row
2406 is the window's left-column
2408 .\" ---------------------------------------------------------------------------
2411 Return the next index in the list of labels.
2414 .B const char ** \fIlabels
2415 is a list of (pointers to) button labels terminated by a null pointer.
2418 is the current button-index.
2420 .\" ---------------------------------------------------------------------------
2422 .B dlg_next_ok_buttonindex
2423 Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons,
2424 find the next index in the list of buttons.
2428 is the current index in the list of buttons
2431 if negative, provides a way to enumerate extra active areas on the widget.
2433 .\" ---------------------------------------------------------------------------
2435 .B dlg_ok_buttoncode
2436 Map the given button index for \fBdlg_ok_labels\fP
2437 into \fB\*p\fP's exit-code.
2441 is the button-index (which is not necessarily the same as the index
2442 in the list of labels).
2444 .\" ---------------------------------------------------------------------------
2447 Returns a list with the "Ok" label,
2448 and if \fBdialog_vars.help_button\fP is true, the "Help" label as well.
2449 .\" ---------------------------------------------------------------------------
2452 Return a list of button labels for the OK/Cancel group of widgets.
2453 .\" ---------------------------------------------------------------------------
2456 Decode the string as an integer, decrement if greater than zero to make
2457 a curses-ordinate from a dialog-ordinate.
2458 .\" ---------------------------------------------------------------------------
2460 .B dlg_parse_bindkey
2461 Parse the parameters of the "bindkeys" configuration-file entry. This
2462 expects widget name which may be "*", followed by curses key definition and
2463 then \fB\*p\fP key definition.
2467 is the parameter string to parse.
2469 .\" ---------------------------------------------------------------------------
2472 Parse the configuration file and set up variables.
2473 .\" ---------------------------------------------------------------------------
2476 Return the previous index in the list of labels.
2479 .B const char ** \fIlabels
2480 is a list of (pointers to) button labels terminated by a null pointer.
2483 is the current button index
2485 .\" ---------------------------------------------------------------------------
2487 .B dlg_print_scrolled
2488 This is a wrapper for \fBdlg_print_autowrap\fP which allows the user
2489 to scroll too-long prompt text up/down.
2491 See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP
2492 variable used as a parameter here.
2493 It complements this function; you need both.
2494 If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP
2495 parameter, needed for \fBdlg_check_scrolled\fP calls.
2499 is the window to update.
2501 .B const char * \fIprompt
2502 is the string to print
2505 is the starting line-number to write wrapped text.
2508 is the available height for writing the wrapped text
2511 is the width that the wrapping should occur in
2514 is true if the extra functionality for scrolling should be enabled.
2515 If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling.
2517 .\" ---------------------------------------------------------------------------
2520 Print one line of the prompt in the window within the limits of the
2521 specified right margin.
2522 The line will end on a word boundary and a pointer
2523 to the start of the next line is returned, or a NULL pointer if the end of
2528 is the window to update.
2531 holds the starting attributes, and is updated to reflect the final attributes
2532 applied to the string.
2534 .B const char *\fIprompt
2535 is the string to print
2544 returns the ending x-ordinate.
2546 .\" ---------------------------------------------------------------------------
2548 .B dlg_prev_ok_buttonindex
2549 Find the previous button index in the list from \fBdlg_ok_labels\fP.
2553 is the current index
2556 if negative provides a way to enumerate extra active areas on the widget.
2558 .\" ---------------------------------------------------------------------------
2560 .B dlg_print_autowrap
2561 Print a string of text in a window, automatically wrap around to the next
2562 line if the string is too long to fit on one line.
2563 Note that the string may contain embedded newlines.
2564 The text is written starting at the top of the window.
2568 is the window to update.
2570 .B const char * \fIprompt
2571 is the string to print
2574 is the nominal height the wrapped string is limited to
2577 is the width that the wrapping should occur in
2579 .\" ---------------------------------------------------------------------------
2582 If \fBdialog_vars.print_siz\fP is true,
2583 print the given height/width (from a widget)
2584 to \fBdialog_state.output\fP, e.g.,
2585 \fBSize: height, width\fP.
2589 is the window's height
2592 is the window's width
2594 .\" ---------------------------------------------------------------------------
2597 Print up to \fIcols\fP columns from \fBtext\fP,
2598 optionally rendering \fB\*p\fP's escape sequences for attributes and color.
2602 is the window to update.
2604 .B const char * \fItxt
2605 is the string to print
2611 holds the starting attributes, and is updated to reflect the final attributes
2612 applied to the string.
2614 .\" ---------------------------------------------------------------------------
2616 implements the "\fB--prgbox\fP" and "\fB--progressbox\fP" options.
2619 is the title on the top of the widget.
2621 is the prompt text shown within the widget.
2622 If empty or null, no prompt is shown.
2624 is the desired height of the box.
2625 If zero, the height is based on the screen size.
2627 is the desired width of the box.
2628 If zero, the height is based on the screen size.
2630 if true, an "OK" button will be shown,
2631 and the dialog will wait for it to complete.
2632 With an "OK" button, it is denoted a "programbox",
2633 without an "OK" button, it is denoted a "progressbox".
2635 is the file pointer, which may be a pipe or a regular file.
2637 .\" ---------------------------------------------------------------------------
2639 .B dlg_put_backtitle
2640 Display the background title if \fBdialog_vars.backtitle\fP is non-null.
2641 The background title is shown at the top of the screen.
2642 .\" ---------------------------------------------------------------------------
2644 .B dlg_register_buttons
2645 The widget developer should call this function after \fBdlg_register_window\fP,
2646 for the list of button labels associated with the widget.
2647 One may bind a key to a button, e.g., "OK" for \fBDLGK_OK\fP,
2651 is the window with which to associate the buttons
2653 .B const char * \fIname
2654 is the widget's binding name (usually the name of the widget).
2656 .B const char ** \fIbuttons
2657 is the list of buttons
2659 .\" ---------------------------------------------------------------------------
2661 .B dlg_register_window
2662 For a given named widget's window, associate a binding table.
2666 is the window with which to associate the buttons
2668 .B const char * \fIname
2669 is the widget's binding name (usually the name of the widget).
2671 .B DLG_KEYS_BINDING * \fIbinding
2672 is the binding table
2674 .\" ---------------------------------------------------------------------------
2676 .B dlg_remove_callback
2680 .B DIALOG_CALLBACK \fI* p
2681 contains the callback information.
2683 .\" ---------------------------------------------------------------------------
2686 Restore \fB\*p\fP's variables from the given variable (see \fBdialog_save_vars\fP).
2689 .B DIALOG_VARS * \fIsave
2690 is the variable from which to restore.
2694 \fIDIALOG_VARS.input_length\fP and
2695 \fIDIALOG_VARS.input_result\fP members are treated specially,
2696 since these are used by a widget to pass data to the caller.
2697 They are not modified by this function.
2698 .\" ---------------------------------------------------------------------------
2701 Test a \fB\*p\fP internal keycode to see if it corresponds to one of the push
2702 buttons on the widget such as "OK".
2703 This is only useful if there are user-defined key bindings, since there are
2704 no built-in bindings that map directly to \fBDLGK_OK\fP, etc.
2705 Return true if a mapping was done.
2708 .B int \fIdialog_key
2709 is the \fB\*p\fP key to test
2712 is true if this is a function key
2715 store the result of the mapping in the referenced location.
2717 .\" ---------------------------------------------------------------------------
2720 Save \fB\*p\fP's variables into the given variable (see \fBdialog_restore_vars\fP).
2723 .B DIALOG_VARS * \fIsave
2724 is the variable into which to save.
2726 .\" ---------------------------------------------------------------------------
2729 Set focus on the given window,
2730 making it display above other windows on the screen.
2733 .B WINDOW * \fIparent
2734 is the parent window (usually the top-level window of a widget)
2737 is the window on which to place focus (usually a subwindow of a widget)
2739 .\" ---------------------------------------------------------------------------
2742 Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP
2745 .B const char * \fIstring
2746 is the new contents for the result
2748 .\" ---------------------------------------------------------------------------
2751 Displays the string, shifted as necessary, to fit within the box and show
2752 the current character-offset.
2756 is the window within which to display
2758 .B const char * \fIstring
2759 is the string to display
2762 is the starting (character, not bytes) offset
2765 is the window attribute to use for the string
2768 beginning row on screen
2771 beginning column on screen
2774 number of columns on screen
2777 if true, do not echo input
2780 if true, force repaint
2782 .\" ---------------------------------------------------------------------------
2785 duplicate the string, like \fBstrdup\fP.
2788 .B const char * \fIcprompt
2789 is the string to duplicate
2791 .\" ---------------------------------------------------------------------------
2794 compare two strings, ignoring case.
2797 .B const char \fI* a
2800 .B const char \fI* b
2803 .\" ---------------------------------------------------------------------------
2805 .B dlg_string_to_argv
2806 Convert a string to an argument vector
2807 returning an index (which must be freed by the caller).
2808 The string is modified (replacing gaps between tokens with nulls).
2812 is the string to convert.
2814 .\" ---------------------------------------------------------------------------
2817 create a subwindow, e.g., for an input area of a widget
2821 is the parent window
2824 is the subwindow's height
2827 is the subwindow's width
2830 is the subwindow's top-row
2833 is the subwindow's left-column
2835 .\" ---------------------------------------------------------------------------
2837 .B dlg_tab_correct_str
2838 If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces.
2839 Return the converted result.
2840 The caller is responsible for freeing the string.
2844 is the string to convert
2846 .\" ---------------------------------------------------------------------------
2849 If the parameter is non-null, opens a trace file with that
2850 name and stores the file pointer in \fBdialog_state.trace\fP.
2851 .\" ---------------------------------------------------------------------------
2854 If \fBdialog_state.trace\fP is set,
2855 translate the parameters into a printable representation,
2856 log it on a "chr" line.
2860 is the nominal keycode value.
2863 is nonzero if the value is really a function key.
2864 Some of these may be values declared in the DLG_KEYS_ENUM.
2866 .\" ---------------------------------------------------------------------------
2869 If \fBdialog_state.trace\fP is set,
2870 log a printable picture of the given window.
2871 .\" ---------------------------------------------------------------------------
2874 Change embedded "\\n" substrings to '\\n' characters and tabs to single spaces.
2875 If there are no "\\n"s, the function strips all extra spaces, for justification.
2876 If it has "\\n"'s, the function preserves extra spaces.
2877 If \fBdialog_vars.cr_wrap\fP is set, the function preserves '\\n's.
2881 is the string to trim
2883 .\" ---------------------------------------------------------------------------
2885 .B dlg_unregister_window
2886 Remove the bindings for a given window.
2890 is the window from which to remove bindings
2892 .\" ---------------------------------------------------------------------------
2894 .B dlg_yes_buttoncode
2895 Map the given button index for \fBdlg_yes_labels\fP into \fB\*p\fP's exit-code.
2901 .\" ---------------------------------------------------------------------------
2904 Return a list of buttons for Yes/No labels.
2906 .\" ************************************************************************
2910 .\" ************************************************************************