1DIALOG(3) Library Functions Manual DIALOG(3)
2
3
4
6 dialog - widgets and utilities for the dialog program
7
9 cc [ flag ... ] file ... -ldialog [ library ... ]
10 or
11 cc $(dialog-config --cflags) file ... $(dialog-config --libs) ]
12
13 #include <dialog.h>
14
15 Dialog is a program that will let you present a variety of questions or
16 display messages using dialog boxes from a shell script. It is built
17 from the dialog library, which consists of several widgets as well as
18 utility functions that are used by the widgets or the main program.
19
21 This manpage documents the features from <dialog.h> which are likely to
22 be important to developers using the widgets directly. Some hints are
23 also given for developing new widgets.
24
25 Here is a dialog version of Hello World:
26 int main(void)
27 {
28 int status;
29 init_dialog(stdin, stdout);
30 status = dialog_yesno(
31 "Hello, in dialog-format",
32 "Hello World!",
33 0, 0);
34 end_dialog();
35 return status;
36 }
37
39 Exit codes (passed back to the main program for its use) are defined
40 with a "DLG_EXIT_ prefix. The efined constants can be mapped using
41 environment variables as described in dialog(1), e.g., DLG_EXIT_OK cor‐
42 responds to $DIALOG_OK.
43
44 Useful character constants which correspond to user input are named
45 with the "CHR_" prefix, e.g., CHR_BACKSPACE.
46
47 Colors and video attributes are categorized and associated with set‐
48 tings in the configuration file (see the discussion of $DIALOGRC in
49 dialog(1)). The DIALOG_ATR(n) macro is used for defining the refer‐
50 ences to the combined color and attribute table dlg_color_table[].
51
52 The dialog application passes its command-line parameters to the widget
53 functions. Some of those parameters are single values, but some of the
54 widgets accept data as an array of values. Those include check‐
55 list/radiobox, menubox and formbox. When the --item-help option is
56 given, an extra column of data is expected. The USE_ITEM_HELP(),
57 CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS macros are used to hide
58 this difference from the calling application.
59
60 Most of the other definitions found in <dialog.h> are used for conve‐
61 nience in building the library or main program. These include defini‐
62 tions based on the generated <dlg_config.h> header.
63
65 All of the global data for the dialog library is stored in a few struc‐
66 tures: DIALOG_STATE, DIALOG_VARS and DIALOG_COLORS. The corresponding
67 dialog_state, dialog_vars and dlg_color_table global variables should
68 be initialized to zeros, and then populated with the data to use. A
69 few of these must be nonzero for the corresponding widgets to function.
70 As as the case with function names, variables beginning with "dialog_"
71 are designed for use by the calling application while variables begin‐
72 ning with "dlg_" are intended for lower levels, e.g., by the dialog
73 library.
74
76 The state variables are dialog's working variables. It initializes
77 those, uses them to manage the widgets.
78
79 .all_subwindows
80 This is a linked list of all subwindows created by the library. The
81 dlg_del_window function uses this to free storage for subwindows when
82 deleting a window.
83
84 .all_windows
85 This is a linked list of all windows created by the library. The
86 dlg_del_window function uses this to locate windows which may be
87 redrawn after deleting a window.
88
89 .aspect_ratio
90 This corresponds to the command-line option "--aspect-ratio". The
91 value gives the application some control over the box dimensions when
92 using auto sizing (specifying 0 for height and width). It represents
93 width / height. The default is 9, which means 9 characters wide to
94 every 1 line high.
95
96 .finish_string
97 When set to true, this allows calls to dlg_finish_string to discard the
98 corresponding data which is created to speed up layout computations for
99 the given string parameter. The gauge widget uses this feature.
100
101 .getc_callbacks
102 This is set up in ui_getc.c to record windows which must be polled for
103 input, e.g., to handle the background tailbox widget. One window is
104 designated as the foreground or control window.
105
106 .getc_redirect
107 If the control window for DIALOG_STATE.getc_callbacks is closed, the
108 list is transferred to this variable. Closing all windows causes the
109 application to exit.
110
111 .had_resize
112 This is set to TRUE in dlg_will_resize or dlg_result_key when
113 KEY_RESIZE is read, to tell dialog to ignore subsequent ERRs.
114
115 .no_mouse
116 This corresponds to the command-line option "--no-mouse". If true,
117 dialog will not initialize (and enable) the mouse in init_dialog.
118
119 .output
120 This is set in the dialog application to the stream on which the appli‐
121 cation and library functions may write text results. Normally that is
122 the standard error, since the curses library prefers to write its data
123 to the standard output. Some scripts, trading portability for conve‐
124 nience, prefer to write results to the standard output, e.g., by using
125 the "--stdout" option.
126
127 .output_count
128 This is incremented by dlg_does_output, which is called by each widget
129 that writes text to the output. The dialog application uses that to
130 decide if it should also write a separator, i.e., DIALOG_STATE.sepa‐
131 rate_str, between calls to each widget.
132
133 .pipe_input
134 This is set in init_dialog to a stream which can be used by the gauge
135 widget, which must be the application's standard input. The dialog
136 application calls init_dialog normally with input set to the standard
137 input, but optionally based on the "--input-fd" option. Since the
138 application cannot read from a pipe (standard input) and at the same
139 time read the curses input from the standard input, it must allow for
140 reopening the latter from either a specific file descriptor, or
141 directly from the terminal. The adjusted pipe stream value is stored
142 in this variable.
143
144 .screen_height
145 The text-formatting functions use this for the number of rows used for
146 formatting a string.
147
148 It is used by dialog for the command-line options "--print-text-size"
149 and "--print-text-only".
150
151 .screen_initialized
152 This is set in init_dialog and reset in end_dialog. It is used to
153 check if curses has been initialized, and if the endwin function must
154 be called on exit.
155
156 .screen_output
157 This is set in init_dialog to the output stream used by the curses
158 library. Normally that is the standard output, unless that happens to
159 not be a terminal (and if init_dialog can successfully open the termi‐
160 nal directly).
161
162 .screen_width
163 The text-formatting functions use this for the number of columns used
164 for formatting a string.
165
166 It is used by dialog for the command-line options "--print-text-size"
167 and "--print-text-only".
168
169 .separate_str
170 This corresponds to the command-line option "--separate-widget". The
171 given string specifies a string that will separate the output on dia‐
172 log's output from each widget. This is used to simplify parsing the
173 result of a dialog with several widgets. If this option is not given,
174 the default separator string is a tab character.
175
176 .tab_len
177 This corresponds to the command-line option "--tab-len number". Spec‐
178 ify the number of spaces that a tab character occupies if the "--tab-
179 correct" option is given. The default is 8.
180
181 .text_height
182 The text-formatting functions set this to the number of lines used for
183 formatting a string.
184
185 It is used by dialog for the command-line options "--print-text-size"
186 and "--print-text-only".
187
188 .text_only
189 Dialog uses this in the command-line option "--print-text-only".
190
191 The text-formatting functions (dlg_print_text, dlg_print_line, and
192 dlg_print_autowrap) check this to decide whether to print the formatted
193 text to dialog's output or to the curses-display.
194
195 Also, dlg_auto_size checks the flag, allowing it to be used before
196 init_dialog is called.
197
198 .text_width
199 The text-formatting functions set this to the number of columns used
200 for formatting a string.
201
202 It is used by dialog for the command-line options "--print-text-size"
203 and "--print-text-only".
204
205 .trace_output
206 This corresponds to the command-line option "--trace file". It is the
207 file pointer to which trace messages are written.
208
209 .use_colors
210 This is set in init_dialog if the curses implementation supports color.
211
212 .use_scrollbar
213 This corresponds to the command-line option "--scrollbar". If true,
214 draw a scrollbar to make windows holding scrolled data more readable.
215
216 .use_shadow
217 This corresponds to the command-line option "--no-shadow". This is set
218 in init_dialog if the curses implementation supports color. If true,
219 suppress shadows that would be drawn to the right and bottom of each
220 dialog box.
221
222 .visit_items
223 This corresponds to the command-line option "--visit-items". Modify
224 the tab-traversal of the list-oriented widgets (buildlist, checklist,
225 radiobox, menubox, inputmenu, and treeview) to include the list of
226 items as one of the states. This is useful as a visual aid, i.e., the
227 cursor position helps some users.
228
229 The dialog application resets the dialog_vars data before accepting
230 options to invoke each widget. Most of the DIALOG_VARS members are set
231 directly from dialog's command-line options:
232
234 In contrast to DIALOG_STATE, the members of DIALOG_VARS are set by com‐
235 mand-line options in dialog.
236
237 .ascii_lines
238 This corresponds to the command-line option "--ascii-lines. It causes
239 line-drawing to be done with ASCII characters, e.g., "+" and "-". See
240 DIALOG_VARS.no_lines.
241
242 .backtitle
243 This corresponds to the command-line option "--backtitle backtitle".
244 It specifies a backtitle string to be displayed on the backdrop, at the
245 top of the screen.
246
247 .beep_after_signal
248 This corresponds to the command-line option "--beep-after". If true,
249 beep after a user has completed a widget by pressing one of the but‐
250 tons.
251
252 .beep_signal
253 This corresponds to the command-line option "--beep". It is obsolete.
254
255 .begin_set
256 This is true if the command-line option "--begin y x" was used. It
257 specifies the position of the upper left corner of a dialog box on the
258 screen.
259
260 .begin_x
261 This corresponds to the x value from the command-line option "--begin y
262 x" (second value).
263
264 .begin_y
265 This corresponds to the y value from the command-line option "--begin y
266 x" (first value).
267
268 .cancel_label
269 This corresponds to the command-line option "--cancel-label string".
270 The given string overrides the label used for “Cancel” buttons.
271
272 .cant_kill
273 This corresponds to the command-line option "--no-kill". If true, this
274 tells dialog to put the tailboxbg box in the background, printing its
275 process id to dialog's output. SIGHUP is disabled for the background
276 process.
277
278 .colors
279 This corresponds to the command-line option "--colors". If true,
280 interpret embedded "\Z" sequences in the dialog text by the following
281 character, which tells dialog to set colors or video attributes: 0
282 through 7 are the ANSI codes used in curses: black, red, green, yellow,
283 blue, magenta, cyan and white respectively. Bold is set by 'b', reset
284 by 'B'. Reverse is set by 'r', reset by 'R'. Underline is set by 'u',
285 reset by 'U'. The settings are cumulative, e.g., "\Zb\Z1" makes the
286 following text bright red. Restore normal settings with "\Zn".
287
288 .column_separator
289 This corresponds to the command-line option "--column-separator". Dia‐
290 log splits data for radio/checkboxes and menus on the occurrences of
291 the given string, and aligns the split data into columns.
292
293 .cr_wrap
294 This corresponds to the command-line option "--cr-wrap". If true,
295 interpret embedded newlines in the dialog text as a newline on the
296 screen. Otherwise, dialog will only wrap lines where needed to fit
297 inside the text box. Even though you can control line breaks with
298 this, dialog will still wrap any lines that are too long for the width
299 of the box. Without cr-wrap, the layout of your text may be formatted
300 to look nice in the source code of your script without affecting the
301 way it will look in the dialog.
302
303 .date_format
304 This corresponds to the command-line option "--date-format string". If
305 the host provides strftime, and the value is nonnull, the calendar wid‐
306 get uses this to format its output.
307
308 .default_button
309 This is set by the command-line option "--default-button. It is used
310 by dlg_default_button.
311
312 .default_item
313 This corresponds to the command-line option "--default-item string".
314 The given string is used as the default item in a checklist, form or
315 menu box. Normally the first item in the box is the default.
316
317 .defaultno
318 This corresponds to the command-line option "--defaultno". If true,
319 make the default value of the yes/no box a No. Likewise, treat the
320 default button of widgets that provide “OK” and “Cancel” as a Cancel.
321 If --nocancel was given that option overrides this, making the default
322 button always “Yes” (internally the same as “OK”).
323
324 .dlg_clear_screen
325 This corresponds to the command-line option "--clear". This option is
326 implemented in the main program, not the library. If true, the screen
327 will be cleared on exit. This may be used alone, without other
328 options.
329
330 .exit_label
331 This corresponds to the command-line option "--exit-label string". The
332 given string overrides the label used for “EXIT” buttons.
333
334 .extra_button
335 This corresponds to the command-line option "--extra-button". If true,
336 some widgets show an extra button, between “OK” and “Cancel” buttons.
337
338 .extra_label
339 This corresponds to the command-line option "--extra-label string".
340 The given string overrides the label used for “Extra” buttons. Note:
341 for inputmenu widgets, this defaults to “Rename”.
342
343 .formitem_type
344 This is set by the command-line option "--passwordform" to tell the
345 form widget that its text fields should be treated like password wid‐
346 gets.
347
348 .help_button
349 This corresponds to the command-line option "--help-button". If true,
350 some widgets show a help-button after “OK” and “Cancel” buttons, i.e.,
351 in checklist, radiolist and menu boxes. If --item-help is also given,
352 on exit the return status will be the same as for the “OK” button, and
353 the item-help text will be written to dialog's output after the token
354 “HELP”. Otherwise, the return status will indicate that the Help but‐
355 ton was pressed, and no message printed.
356
357 .help_file
358 This corresponds to the command-line option "--hfile string". The
359 given filename is passed to dialog_helpfile when the user presses F1.
360
361 .help_label
362 This corresponds to the command-line option "--help-label string". The
363 given string overrides the label used for “Help” buttons.
364
365 .help_line
366 This corresponds to the command-line option "--hline string". The
367 given string is displayed in the bottom of dialog windows, like a sub‐
368 title.
369
370 .help_status
371 This corresponds to the command-line option "--help-status". If true,
372 and the the help-button is selected, writes the checklist or radiolist
373 information after the item-help “HELP” information. This can be used
374 to reconstruct the state of a checklist after processing the help
375 request.
376
377 .help_tags
378 This corresponds to the command-line option "--help-tags". If true,
379 dlg_add_help_formitem and dlg_add_help_listitem use the item's tag
380 value consistently rather than using the tag's help-text value when
381 DIALOG_VARS.item_help is set.
382
383 .input_length
384 This is nonzero if DIALOG_VARS.input_result is allocated, versus being
385 a pointer to the user's local variables.
386
387 .input_menu
388 This flag is set to denote whether the menubox widget implements a menu
389 versus a inputmenu widget.
390
391 .input_result
392 This may be either a user-supplied buffer, or a buffer dynamically
393 allocated by the library, depending on DIALOG_VARS.input_length:
394
395 · If DIALOG_VARS.input_length is zero, this is a pointer to user buf‐
396 fer (on the stack, or static). The buffer size is assumed to be
397 MAX_LEN, which is defined in <dialog.h>.
398
399 · When DIALOG_VARS.input_length is nonzero, this is a dynamically-
400 allocated buffer used by the widgets to return printable results to
401 the calling application.
402
403 Certain widgets copy a result to this buffer. If the pointer is NULL,
404 or if the length is insufficient for the result, then the dialog
405 library allocates a buffer which is large enough, and sets DIA‐
406 LOG_VARS.input_length. Callers should check for this case if they have
407 supplied their own buffer.
408
409 .insecure
410 This corresponds to the command-line option "--insecure". If true,
411 make the password widget friendlier but less secure, by echoing aster‐
412 isks for each character.
413
414 .in_helpfile
415 This variable is used to prevent dialog_helpfile from showing anything,
416 e.g., if F1 were pressed within a help-file display.
417
418 .iso_week
419 This corresponds to the command-line option "--iso-week". It is used
420 in the calendar widget to tell how to compute the starting week for the
421 year:
422
423 · by default, the calendar treats January 1 as the first week of the
424 year.
425
426 · If this variable is true, the calendar uses ISO 8601's convention.
427 ISO 8601 numbers weeks starting with the first week in January with
428 a Thursday in the current year. January 1 may be in the previous
429 year.
430
431 .item_help
432 This corresponds to the command-line option "--item-help". If true,
433 interpret the tags data for checklist, radiolist and menu boxes adding
434 a column whose text is displayed in the bottom line of the screen, for
435 the currently selected item.
436
437 .keep_tite
438 This is set by the command-line option "--keep-tite" to tell dialog to
439 not attempt to cancel the terminal initialization (termcap ti/te)
440 sequences which correspond to xterm's alternate-screen switching. Nor‐
441 mally dialog does this to avoid flickering when run several times in a
442 script.
443
444 .keep_window
445 This corresponds to the command-line option "--keep-window". If true,
446 do not remove/repaint the window on exit. This is useful for keeping
447 the window contents visible when several widgets are run in the same
448 process. Note that curses will clear the screen when starting a new
449 process.
450
451 .last_key
452 This corresponds to the command-line option "--last-key".
453
454 .max_input
455 This corresponds to the command-line option "--max-input size". Limit
456 input strings to the given size. If not specified, the limit is 2048.
457
458 .no_items
459 This corresponds to the command-line option "--no-items". Some widgets
460 (checklist, inputmenu, radiolist, menu) display a list with two columns
461 (a “tag” and “item”, i.e., “description”). This tells dialog to read
462 shorter rows from data, omitting the “list”.
463
464 .no_label
465 This corresponds to the command-line option "--no-label string". The
466 given string overrides the label used for “No” buttons.
467
468 .no_lines
469 This corresponds to the command-line option "--no-lines. It suppresses
470 line-drawing. See DIALOG_VARS.ascii_lines.
471
472 .no_nl_expand
473 This corresponds to the command-line option "--no-nl-expand". If
474 false, dlg_trim_string converts literal "\n" substrings in a message
475 into newlines.
476
477 .no_tags
478 This corresponds to the command-line option "--no-tags". Some widgets
479 (checklist, inputmenu, radiolist, menu) display a list with two columns
480 (a “tag” and “item”, also known as “description”). The tag is useful
481 for scripting, but may not help the user. The --no-tags option (from
482 Xdialog) may be used to suppress the column of tags from the display.
483
484 Normally dialog allows you to quickly move to entries on the displayed
485 list, by matching a single character to the first character of the tag.
486 When the --no-tags option is given, dialog matches against the first
487 character of the description. In either case, the matchable character
488 is highlighted.
489
490 Here is a table showing how the no_tags and no_items values interact:
491
492 Widget Fields Shown Fields Read .no_items .no_tags
493 ──────────────────────────────────────────────────────────────
494 buildlist item tag,item 0 0*
495 buildlist item tag,item 0 1
496 buildlist tag tag 1 0*
497 buildlist tag tag 1 1
498 checklist tag,item tag,item 0 0
499 checklist item tag,item 0 1
500 checklist tag tag 1 0
501 checklist tag tag 1 1
502 inputmenu tag,item tag,item 0 0
503 inputmenu item tag,item 0 1
504 inputmenu tag tag 1 0
505 inputmenu tag tag 1 1
506 menu tag,item tag,item 0 0
507 menu item tag,item 0 1
508 menu tag tag 1 0
509 menu tag tag 1 1
510 radiolist tag,item tag,item 0 0
511 radiolist item tag,item 0 1
512 radiolist tag tag 1 0
513 radiolist tag tag 1 1
514 treeview item tag,item 0 0*
515 treeview item tag,item 0 1
516 treeview tag tag 1 0*
517 treeview tag tag 1 1
518 ──────────────────────────────────────────────────────────────
519
520 * Xdialog does not display the tag column for the analogous buildlist
521 and treeview widgets. Dialog does the same on the command-line.
522 However the library interface defaults to displaying the tag column.
523 Your application can enable or disable the tag column as needed for
524 each widget.
525
526 .nocancel
527 This corresponds to the command-line option "--no-cancel". If true,
528 suppress the “Cancel” button in checklist, inputbox and menu box modes.
529 A script can still test if the user pressed the ESC key to cancel to
530 quit.
531
532 .nocollapse
533 This corresponds to the command-line option "--no-collapse". Normally
534 dialog converts tabs to spaces and reduces multiple spaces to a single
535 space for text which is displayed in a message boxes, etc. It true,
536 that feature is disabled. Note that dialog will still wrap text, sub‐
537 ject to the --cr-wrap option.
538
539 .nook
540 This corresponds to the command-line option "--nook. Dialog will sup‐
541 press the “ok” (or “yes”) button from the widget.
542
543 .ok_label
544 This corresponds to the command-line option "--ok-label string". The
545 given string overrides the label used for “OK” buttons.
546
547 .print_siz
548 This corresponds to the command-line option "--print-size". If true,
549 each widget prints its size to dialog's output when it is invoked.
550
551 .quoted
552 This corresponds to the command-line option "--quoted. Normally dialog
553 quotes the strings returned by checklist's as well as the item-help
554 text. If true, dialog will quote all string results.
555
556 .reorder
557 This corresponds to the command-line option "--reorder. By default,
558 the buildlist widget uses the same order for the output (right) list as
559 for the input (left). If true, dialog will use the order in which a
560 user adds selections to the output list.
561
562 .separate_output
563 This corresponds to the command-line option "--separate-output". If
564 true, checklist widgets output result one line at a time, with no quot‐
565 ing. This facilitates parsing by another program.
566
567 .single_quoted
568 This corresponds to the command-line option "--single-quoted". If
569 true, use single-quoting as needed (and no quotes if unneeded) for the
570 output of checklist's as well as the item-help text. If this option is
571 not set, dialog uses double quotes around each item. The latter
572 requires occasional use of backslashes to make the output useful in
573 shell scripts.
574
575 .size_err
576 This corresponds to the command-line option "--size-err". If true,
577 check the resulting size of a dialog box before trying to use it,
578 printing the resulting size if it is larger than the screen. (This
579 option is obsolete, since all new-window calls are checked).
580
581 .sleep_secs
582 This corresponds to the command-line option "--sleep secs". This
583 option is implemented in the main program, not the library. If
584 nonzero, this is the number of seconds after to delay after processing
585 a dialog box.
586
587 .tab_correct
588 This corresponds to the command-line option "--tab-correct". If true,
589 convert each tab character of the text to one or more spaces. Other‐
590 wise, tabs are rendered according to the curses library's interpreta‐
591 tion.
592
593 .time_format
594 This corresponds to the command-line option "--time-format string". If
595 the host provides strftime, and the value is nonnull, the timebox wid‐
596 get uses this to format its output.
597
598 .timeout_secs
599 This corresponds to the command-line option "--timeout secs". If
600 nonzero, timeout input requests (exit with error code) if no user
601 response within the given number of seconds.
602
603 .title
604 This corresponds to the command-line option "--title title". Specifies
605 a title string to be displayed at the top of the dialog box.
606
607 .trim_whitespace
608 This corresponds to the command-line option "--trim". If true, elimi‐
609 nate leading blanks, trim literal newlines and repeated blanks from
610 message text.
611
612 .week_start
613 This corresponds to the command-line option "--week-start". It is used
614 in the calendar widget to set the starting day for the week. The
615 string value can be
616
617 · a number (0 to 6, Sunday through Saturday using POSIX) or
618
619 · the special value “locale” (this works with systems using glibc,
620 providing an extension to the locale command, the first_weekday
621 value).
622
623 · a string matching one of the abbreviations for the day of the week
624 shown in the calendar widget, e.g., “Mo” for “Monday”.
625
626 .yes_label
627 This corresponds to the command-line option "--yes-label string". The
628 given string overrides the label used for “Yes” buttons.
629
631 Functions that implement major functionality for the command-line dia‐
632 log program, e.g., widgets, have names beginning "dialog_".
633
634 All dialog boxes have at least three parameters:
635
636 title
637 the caption for the box, shown on its top border.
638
639 height
640 the height of the dialog box.
641
642 width
643 the width of the dialog box.
644
645 Other parameters depend on the box type.
646
647 dialog_buildlist
648 implements the "--buildlist" option.
649
650 const char * title
651 is the title on the top of the widget.
652
653 const char * cprompt
654 is the prompt text shown within the widget.
655
656 int height
657 is the desired height of the box. If zero, the height is adjusted
658 to use the available screen size.
659
660 int width
661 is the desired width of the box. If zero, the height is adjusted
662 to use the available screen size.
663
664 int list_height
665 is the minimum height to reserve for displaying the list. If
666 zero, it is computed based on the given height and width.
667
668 int item_no
669 is the number of rows in items.
670
671 char ** items
672 is an array of strings which is viewed either as a list of rows
673 tag item status
674
675 or
676 tag item status help
677
678 depending on whether dialog_vars.item_help is set.
679
680 int order_mode
681 is reserved for future enhancements
682
683 dialog_calendar
684 implements the "--calendar" option.
685
686 const char * title
687 is the title on the top of the widget.
688
689 const char * subtitle
690 is the prompt text shown within the widget.
691
692 int height
693 is the height excluding the fixed-height calendar grid.
694
695 int width
696 is the overall width of the box, which is adjusted up to the cal‐
697 endar grid's minimum width if needed.
698
699 int day
700 is the initial day of the week shown, counting zero as Sunday. If
701 the value is negative, the current day of the week is used.
702
703 int month
704 is the initial month of the year shown, counting one as January.
705 If the value is negative, the current month of the year is used.
706
707 int year
708 is the initial year shown. If the value is negative, the current
709 year is used.
710
711 dialog_checklist
712 implements the "--checklist" and "--radiolist" options depending on the
713 flag parameter.
714
715 const char * title
716 is the title on the top of the widget.
717
718 const char * cprompt
719 is the prompt text shown within the widget.
720
721 int height
722 is the desired height of the box. If zero, the height is adjusted
723 to use the available screen size.
724
725 int width
726 is the desired width of the box. If zero, the height is adjusted
727 to use the available screen size.
728
729 int list_height
730 is the minimum height to reserve for displaying the list. If
731 zero, it is computed based on the given height and width.
732
733 int item_no
734 is the number of rows in items.
735
736 int items
737 is an array of strings which is viewed either as a list of rows
738 tag item status
739
740 or
741 tag item status help
742
743 depending on whether dialog_vars.item_help is set.
744
745 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for radi‐
746 olists.
747
748 dialog_dselect
749 implements the "--dselect" option.
750
751 const char * title
752 is the title on the top of the widget.
753
754 const char * path
755 is the preselected value to show in the input-box, which is used
756 also to set the directory- and file-windows.
757
758 int height
759 is the height excluding the minimum needed to show the dialog box
760 framework. If zero, the height is based on the screen size.
761
762 int width
763 is the desired width of the box. If zero, the height is based on
764 the screen size.
765
766 dialog_editbox
767 implements the "--editbox" option.
768
769 const char * title
770 is the title on the top of the widget.
771
772 const char * file
773 is the name of the file from which to read.
774
775 int height
776 is the desired height of the box. If zero, the height is adjusted
777 to use the available screen size.
778
779 int width
780 is the desired width of the box. If zero, the height is adjusted
781 to use the available screen size.
782
783 dialog_form
784 implements the "--form" option.
785
786 const char * title
787 is the title on the top of the widget.
788
789 const char * cprompt
790 is the prompt text shown within the widget.
791
792 int height
793 is the desired height of the box. If zero, the height is adjusted
794 to use the available screen size.
795
796 int width
797 is the desired width of the box. If zero, the height is adjusted
798 to use the available screen size.
799
800 int form_height
801 is the minimum height to reserve for displaying the list. If
802 zero, it is computed based on the given height and width.
803
804 int item_no
805 is the number of rows in items.
806
807 int items
808 is an array of strings which is viewed either as a list of rows
809 Name NameY NameX Text TextY TextX FLen ILen
810
811 or
812 Name NameY NameX Text TextY TextX FLen ILen Help
813
814 depending on whether dialog_vars.item_help is set.
815
816 dialog_fselect
817 implements the "--fselect" option.
818
819 const char * title
820 is the title on the top of the widget.
821
822 const char * path
823 is the preselected value to show in the input-box, which is used
824 also to set the directory- and file-windows.
825
826 int height
827 is the height excluding the minimum needed to show the dialog box
828 framework. If zero, the height is based on the screen size.
829
830 int width
831 is the desired width of the box. If zero, the height is based on
832 the screen size.
833
834 dialog_gauge
835 implements the "--gauge" option. Alternatively, a simpler or custom‐
836 ized gauge widget can be set up using dlg_allocate_gauge, dlg_reallo‐
837 cate_gauge, dlg_update_gauge and dlg_free_gauge.
838
839 const char * title
840 is the title on the top of the widget.
841
842 const char * cprompt
843 is the prompt text shown within the widget.
844
845 int height
846 is the desired height of the box. If zero, the height is based on
847 the screen size.
848
849 int width
850 is the desired width of the box. If zero, the height is based on
851 the screen size.
852
853 int percent
854 is the percentage to show in the progress bar.
855
856 dialog_inputbox
857 implements the "--inputbox" or "--password" option, depending on the
858 value of password.
859
860 const char * title
861 is the title on the top of the widget.
862
863 const char * cprompt
864 is the prompt text shown within the widget.
865
866 int height
867 is the desired height of the box. If zero, the height is based on
868 the screen size.
869
870 int width
871 is the desired width of the box. If zero, the height is based on
872 the screen size.
873
874 const char * init
875 is the initial value of the input box, whose length is taken into
876 account when auto-sizing the width of the dialog box.
877
878 int password
879 if true, causes typed input to be echoed as asterisks.
880
881 dialog_helpfile
882 implements the "--hfile" option.
883
884 const char * title
885 is the title on the top of the widget.
886
887 const char * file
888 is the name of a file containing the text to display. This func‐
889 tion is internally bound to F1 (function key “1”), passing dia‐
890 log_vars.help_file as a parameter. The dialog program sets that
891 variable when the --hfile option is given.
892
893 int height
894 is the desired height of the box. If zero, the height is based on
895 the screen size.
896
897 int width
898 is the desired width of the box. If zero, the height is based on
899 the screen size.
900
901 dialog_menu
902 implements the "--menu" or "--inputmenu" option depending on whether
903 dialog_vars.input_menu is set.
904
905 const char * title
906 is the title on the top of the widget.
907
908 const char * cprompt
909 is the prompt text shown within the widget.
910
911 int height
912 is the desired height of the box. If zero, the height is based on
913 the screen size.
914
915 int width
916 is the desired width of the box. If zero, the height is based on
917 the screen size.
918
919 int menu_height
920 is the minimum height to reserve for displaying the list. If
921 zero, it is computed based on the given height and width.
922
923 int item_no
924 is the number of rows in items.
925
926 int items
927 is an array of strings which is viewed either as a list of rows
928 tag item
929
930 or
931 tag item help
932
933 depending on whether dialog_vars.item_help is set.
934
935 dialog_mixedform
936 implements the "--mixedform" option.
937
938 const char * title
939 is the title on the top of the widget.
940
941 const char * cprompt
942 is the prompt text shown within the widget.
943
944 int height
945 is the desired height of the box. If zero, the height is adjusted
946 to use the available screen size.
947
948 int width
949 is the desired width of the box. If zero, the height is adjusted
950 to use the available screen size.
951
952 int form_height
953 is the minimum height to reserve for displaying the list. If
954 zero, it is computed based on the given height and width.
955
956 int item_no
957 is the number of rows in items.
958
959 int items
960 is an array of strings which is viewed either as a list of rows
961 Name NameY NameX Text TextY TextX FLen ILen Ityp
962
963 or
964 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
965
966 depending on whether dialog_vars.item_help is set.
967
968 dialog_mixedgauge
969 implements the "--mixedgauge" option
970
971 const char * title
972 is the title on the top of the widget.
973
974 const char * cprompt
975 is the caption text shown within the widget.
976
977 int height
978 is the desired height of the box. If zero, the height is based on
979 the screen size.
980
981 int width
982 is the desired width of the box. If zero, the height is based on
983 the screen size.
984
985 int percent
986 is the percentage to show in the progress bar.
987
988 int item_no
989 is the number of rows in items.
990
991 int items
992 is an array of strings which is viewed as a list of tag and item
993 values. The tag values are listed, one per row, in the list at
994 the top of the widget.
995
996 The item values are decoded: digits 0 through 9 are the following
997 strings
998
999 0 Succeeded
1000
1001 1 Failed
1002
1003 2 Passed
1004
1005 3 Completed
1006
1007 4 Checked
1008
1009 5 Done
1010
1011 6 Skipped
1012
1013 7 In Progress
1014
1015 8 (blank)
1016
1017 9 N/A
1018
1019 A string with a leading "-" character is centered, marked with
1020 "%". For example, "-75" is displayed as "75%". Other strings are
1021 displayed as is.
1022
1023 dialog_msgbox
1024 implements the "--msgbox" or "--infobox" option depending on whether
1025 pauseopt is set.
1026
1027 const char * title
1028 is the title on the top of the widget.
1029
1030 const char * cprompt
1031 is the prompt text shown within the widget.
1032
1033 int height
1034 is the desired height of the box. If zero, the height is based on
1035 the screen size.
1036
1037 int width
1038 is the desired width of the box. If zero, the height is based on
1039 the screen size.
1040
1041 int pauseopt
1042 if true, an “OK” button will be shown, and the dialog will wait
1043 for it to complete. With an “OK” button, it is denoted a “msg‐
1044 box”, without an “OK” button, it is denoted an “infobox”.
1045
1046 dialog_pause
1047 implements the "--pause" option.
1048
1049 const char * title
1050 is the title on the top of the widget.
1051
1052 int height
1053 is the desired height of the box. If zero, the height is based on
1054 the screen size.
1055
1056 int width
1057 is the desired width of the box. If zero, the height is based on
1058 the screen size.
1059
1060 int seconds
1061 is the timeout to use for the progress bar.
1062
1063 dialog_prgbox
1064 implements the "--prgbox" option.
1065
1066 const char * title
1067 is the title on the top of the widget.
1068
1069 const char * cprompt
1070 is the prompt text shown within the widget. If empty or null, no
1071 prompt is shown.
1072
1073 const char * command
1074 is the name of the command to execute.
1075
1076 int height
1077 is the desired height of the box. If zero, the height is based on
1078 the screen size.
1079
1080 int width
1081 is the desired width of the box. If zero, the height is based on
1082 the screen size.
1083
1084 int pauseopt
1085 if true, an “OK” button will be shown, and the dialog will wait
1086 for it to complete.
1087
1088 dialog_progressbox
1089 implements the "--progressbox" option.
1090
1091 const char * title
1092 is the title on the top of the widget.
1093
1094 const char * cprompt
1095 is the prompt text shown within the widget. If empty or null, no
1096 prompt is shown.
1097
1098 int height
1099 is the desired height of the box. If zero, the height is based on
1100 the screen size.
1101
1102 int width
1103 is the desired width of the box. If zero, the height is based on
1104 the screen size.
1105
1106 dialog_rangebox
1107 implements the "--rangebox" option.
1108
1109 const char * title
1110 is the title on the top of the widget.
1111
1112 const char * cprompt
1113 is the prompt text shown within the widget. If empty or null, no
1114 prompt is shown.
1115
1116 int height
1117 is the desired height of the widget. If zero, the height is based
1118 on the screen size.
1119
1120 int width
1121 is the desired width of the widget. If zero, the height is based
1122 on the screen size.
1123
1124 int min_value
1125 is the minimum value to allow.
1126
1127 int max_value
1128 is the maximum value to allow.
1129
1130 int default_value
1131 is the default value, if no change is made.
1132
1133 dialog_tailbox
1134 implements the "--tailbox" or "--tailboxbg" option depending on whether
1135 bg_task is set.
1136
1137 const char * title
1138 is the title on the top of the widget.
1139
1140 const char * file
1141 is the name of the file to display in the dialog.
1142
1143 int height
1144 is the desired height of the box. If zero, the height is based on
1145 the screen size.
1146
1147 int width
1148 is the desired width of the box. If zero, the height is based on
1149 the screen size.
1150
1151 int bg_task
1152 if true, the window is added to the callback list in dialog_state,
1153 and the application will poll for the window to be updated. Oth‐
1154 erwise an “OK” button is added to the window, and it will be
1155 closed when the button is activated.
1156
1157 dialog_textbox
1158 implements the "--textbox" option.
1159
1160 const char * title
1161 is the title on the top of the widget.
1162
1163 const char * file
1164 is the name of the file to display in the dialog.
1165
1166 int height
1167 is the desired height of the box. If zero, the height is based on
1168 the screen size.
1169
1170 int width
1171 is the desired width of the box. If zero, the height is based on
1172 the screen size.
1173
1174 dialog_timebox
1175 implements the "--timebox" option.
1176
1177 const char * title
1178 is the title on the top of the widget.
1179
1180 const char * subtitle
1181 is the prompt text shown within the widget.
1182
1183 int height
1184 is the desired height of the box. If zero, the height is based on
1185 the screen size.
1186
1187 int width
1188 is the desired width of the box. If zero, the height is based on
1189 the screen size.
1190
1191 int hour
1192 is the initial hour shown. If the value is negative, the current
1193 hour is used. Returns DLG_EXIT_ERROR if the value specified is
1194 greater than or equal to 24.
1195
1196 int minute
1197 is the initial minute shown. If the value is negative, the cur‐
1198 rent minute is used. Returns DLG_EXIT_ERROR if the value speci‐
1199 fied is greater than or equal to 60.
1200
1201 int second
1202 is the initial second shown. If the value is negative, the cur‐
1203 rent second is used. Returns DLG_EXIT_ERROR if the value speci‐
1204 fied is greater than or equal to 60.
1205
1206 dialog_treeview
1207 implements the "--treeview" option.
1208
1209 const char * title
1210 is the title on the top of the widget.
1211
1212 const char * cprompt
1213 is the prompt text shown within the widget.
1214
1215 int height
1216 is the desired height of the box. If zero, the height is based on
1217 the screen size.
1218
1219 int width
1220 is the desired width of the box. If zero, the height is based on
1221 the screen size.
1222
1223 int list_height
1224 is the minimum height to reserve for displaying the list. If
1225 zero, it is computed based on the given height and width.
1226
1227 int item_no
1228 is the number of rows in items.
1229
1230 char ** items
1231 is the list of items, contain tag, name, and optionally help
1232 strings (if dialog_vars.item_help is set). The initial selection
1233 state for each item is also in this list.
1234
1235 int flag
1236
1237 flag is either FLAG_CHECK, for checklists (multiple selections), or
1238 FLAG_RADIO for radiolists (a single selection).
1239
1240 dialog_yesno
1241 implements the "--yesno" option.
1242
1243 const char * title
1244 is the title on the top of the widget.
1245
1246 const char * cprompt
1247 is the prompt text shown within the widget.
1248
1249 int height
1250 is the desired height of the box. If zero, the height is based on
1251 the screen size.
1252
1253 int width
1254 is the desired width of the box. If zero, the height is based on
1255 the screen size.
1256
1258 Most functions that implement lower-level functionality for the com‐
1259 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
1260 ing to longstanding usage, the functions that initialize the display
1261 and end it are named init_dialog and end_dialog.
1262
1263 The only non-widget function whose name begins with "dialog_" is dia‐
1264 log_version, which returns the version number of the library as a
1265 string.
1266
1267 Here is a brief summary of the utility functions and their parameters:
1268
1269 dlg_add_callback
1270 Add a callback, used to allow polling input from multiple tailbox wid‐
1271 gets.
1272
1273 DIALOG_CALLBACK *p
1274 contains the callback information.
1275
1276 dlg_add_callback_ref
1277 Like dlg_add_callback, but passes a reference to the DIALOG_CALLBACK as
1278 well as a pointer to a cleanup function which will be called when the
1279 associated input ends.
1280
1281 DIALOG_CALLBACK **p
1282 points to the callback information. This is a reference to the
1283 pointer so that the caller's pointer can be zeroed when input
1284 ends.
1285
1286 DIALOG_FREEBACK func
1287 function to call when input ends, e.g., to free caller's addi‐
1288 tional data.
1289
1290 dlg_add_help_formitem
1291 This is a utility function used enforce consistent behavior for the
1292 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1293
1294 int *result
1295 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1296 set.
1297
1298 char **tag
1299 the tag- or help-text is stored here.
1300
1301 DIALOG_FORMITEM *item
1302 contains the list item to use for tag- or help-text.
1303
1304 dlg_add_help_listitem
1305 This is a utility function used enforce consistent behavior for the
1306 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1307
1308 int *result
1309 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1310 set.
1311
1312 char **tag
1313 the tag- or help-text is stored here.
1314
1315 DIALOG_LISTITEM *item
1316 contains the list item to use for tag- or help-text.
1317
1318 dlg_add_last_key
1319 Report the last key entered by the user. This implements the --last-
1320 key command-line option, using dialog_vars.last_key.
1321
1322 int mode
1323 controls the way the last key report is separated from other
1324 results:
1325
1326 -2 (no separator)
1327
1328 -1 (separator after the key name)
1329
1330 0 (separator is optionally before the key name)
1331
1332 1 (same as -1)
1333
1334 dlg_add_quoted
1335 Add a quoted string to the result buffer (see dlg_add_result). If no
1336 quotes are necessary, none are used. If dialog_vars.single_quoted is
1337 set, single-quotes are used. Otherwise, double-quotes are used.
1338
1339 char * string
1340 is the string to add.
1341
1342 dlg_add_result
1343 Add a string to the result buffer dialog_vars.input_result.
1344
1345 char * string
1346 is the string to add.
1347
1348 dlg_add_separator
1349 Add an output-separator to the result buffer dialog_vars.input_result.
1350 If dialog_vars.output_separator is set, use that. Otherwise, if dia‐
1351 log_vars.separate_output is set, use newline. If neither is set, use a
1352 space.
1353
1354 dlg_add_string
1355 Add a quoted or unquoted string to the result buffer (see
1356 dlg_add_quoted) and dlg_add_result), according to whether dia‐
1357 log_vars.quoted is true.
1358
1359 char * string
1360 is the string to add.
1361
1362 dlg_align_columns
1363 Copy and reformat an array of pointers to strings, aligning according
1364 to the column separator dialog_vars.column_separator. If no column
1365 separator is set, the array will be unmodified; otherwise it is copied
1366 and reformatted.
1367
1368 Caveat: This function is only implemented for 8-bit characters.
1369
1370 char **target
1371 This is the array to reformat. It points to the first string to
1372 modify.
1373
1374 int per_row
1375 This is the size of the struct for each row of the array.
1376
1377 int num_rows
1378 This is the number of rows in the array.
1379
1380 dlg_allocate_gauge
1381 Allocates a gauge widget. Use dlg_update_gauge to display the result.
1382
1383 const char * title
1384 is the title string to display at the top of the widget.
1385
1386 const char * cprompt
1387 is the prompt text shown within the widget.
1388
1389 int height
1390 is the desired height of the box. If zero, the height is adjusted
1391 to use the available screen size.
1392
1393 int width
1394 is the desired width of the box. If zero, the height is adjusted
1395 to use the available screen size.
1396
1397 int percent
1398 is the percentage to show in the progress bar.
1399
1400 dlg_asciibox
1401 returns its parameter transformed to the corresponding "+" or "-",
1402 etc., for the line-drawing characters used in dialog. If the parameter
1403 is not a line-drawing or other special character such as ACS_DARROW, it
1404 returns 0.
1405
1406 chtype ch
1407 is the parameter, usually one of the ACS_xxx constants.
1408
1409 dlg_attr_clear
1410 Set window to the given attribute.
1411
1412 WINDOW * win
1413 is the window to update.
1414
1415 int height
1416 is the number of rows to update.
1417
1418 int width
1419 is the number of columns to update.
1420
1421 chtype attr
1422 is the attribute, e.g., A_BOLD.
1423
1424 dlg_auto_size
1425 Compute window size based on the size of the formatted prompt and mini‐
1426 mum dimensions for a given widget.
1427
1428 Dialog sets dialog_state.text_height and dialog_state.text_width for
1429 the formatted prompt as a side-effect.
1430
1431 Normally dialog writes the formatted prompt to the curses window, but
1432 it will write the formatted prompt to the output stream if dia‐
1433 log_state.text_only is set.
1434
1435 const char * title
1436 is the title string to display at the top of the widget.
1437
1438 const char * prompt
1439 is the message text which will be displayed in the widget, used
1440 here to determine how large the widget should be.
1441
1442 If the value is NULL, dialog allows the widget to use the whole
1443 screen, i.e., if the values referenced by height and/or width are
1444 zero.
1445
1446 int * height
1447 is the nominal height. Dialog checks the referenced value and may
1448 update it:
1449
1450 · if the value is negative, dialog updates it to the available
1451 height of the screen, after reserving rows for the window bor‐
1452 der and shadow, as well as taking into account dia‐
1453 log_vars.begin_y and dialog_vars.begin_set.
1454
1455 · if the value is zero, dialog updates it to the required height
1456 of the window, taking into account a (possibly) multi-line
1457 prompt.
1458
1459 · if the value is greater than zero, dialog uses it internally,
1460 but restores the value on return.
1461
1462 int * width
1463 is the nominal width. Dialog checks the referenced value and may
1464 update it:
1465
1466 · if the value is negative, dialog updates it to the available
1467 width of the screen, after reserving rows for the window bor‐
1468 der and shadow, as well as taking into account dia‐
1469 log_vars.begin_x and dialog_vars.begin_set.
1470
1471 · if the value is zero, dialog updates it to the required width
1472 of the window, taking into account a (possibly) multi-line
1473 prompt.
1474
1475 · if the value is greater than zero, dialog uses it internally,
1476 but restores the value on return.
1477
1478 int boxlines
1479 is the number of lines to reserve in the vertical direction.
1480
1481 int mincols
1482 is the minimum number of columns to use.
1483
1484 dlg_auto_sizefile
1485 Like dlg_auto_size, but use a file contents to decide how large the
1486 widget should be.
1487
1488 const char * title
1489 is the title string to display at the top of the widget.
1490
1491 const char * file
1492 is the name of the file.
1493
1494 int * height
1495 is the nominal height.
1496
1497 If it is -1, use the screen's height (after subtracting dia‐
1498 log_vars.begin_y if dialog_vars.begin_set is true).
1499
1500 If it is greater than zero, limit the referenced value to the
1501 screen-height after verifying that the file exists.
1502
1503 int * width
1504 is the nominal width.
1505
1506 If it is -1, use the screen's width (after subtracting dia‐
1507 log_vars.begin_x if dialog_vars.begin_set is true).
1508
1509 If it is greater than zero, limit the referenced value to the
1510 screen-width after verifying that the file exists.
1511
1512 int boxlines
1513 is the number of lines to reserve on the screen for drawing boxes.
1514
1515 int mincols
1516 is the number of columns to reserve on the screen for drawing
1517 boxes.
1518
1519 dlg_beeping
1520 If dialog_vars.beep_signal is nonzero, this calls beep once and sets
1521 dialog_vars.beep_signal to zero.
1522
1523 dlg_boxchar
1524 returns its chtype parameter transformed as follows:
1525
1526 · if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is set.
1527
1528 · if dialog_vars.ascii_lines is set, returns the corresponding "+" or
1529 "-", etc., for the line-drawing characters used in dialog.
1530
1531 · otherwise, if dialog_vars.no_lines is set, returns a space for the
1532 line-drawing characters.
1533
1534 · if the parameter is not a line-drawing or other special character
1535 such as ACS_DARROW, it returns the parameter unchanged.
1536
1537 dlg_box_x_ordinate
1538 returns a suitable x-ordinate (column) for a new widget. If dia‐
1539 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center the
1540 widget on the screen (using the width parameter).
1541
1542 int width
1543 is the width of the widget.
1544
1545 dlg_box_y_ordinate
1546 returns a suitable y-ordinate (row) for a new widget. If dia‐
1547 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center the
1548 widget on the screen (using the height parameter).
1549
1550 int height
1551 is the height of the widget.
1552
1553 dlg_buildlist
1554 This is an alternate interface to the buildlist widget which allows the
1555 application to read the list item states back directly without putting
1556 them in the output buffer.
1557
1558 const char * title
1559 is the title string to display at the top of the widget.
1560
1561 const char * cprompt
1562 is the prompt text shown within the widget.
1563
1564 int height
1565 is the desired height of the box. If zero, the height is adjusted
1566 to use the available screen size.
1567
1568 int width
1569 is the desired width of the box. If zero, the height is adjusted
1570 to use the available screen size.
1571
1572 int list_height
1573 is the minimum height to reserve for displaying the list. If
1574 zero, it is computed based on the given height and width.
1575
1576 int item_no
1577 is the number of rows in items.
1578
1579 DIALOG_LISTITEM * items
1580 is the list of items, contain tag, name, and optionally help
1581 strings (if dialog_vars.item_help is set). The initial selection
1582 state for each item is also in this list.
1583
1584 const char * states
1585 This is a list of characters to display for the given states.
1586 Normally a buildlist provides true (1) and false (0) values, which
1587 the widget displays as "*" and space, respectively. An applica‐
1588 tion may set this parameter to an arbitrary null-terminated
1589 string. The widget determines the number of states from the
1590 length of this string, and will cycle through the corresponding
1591 display characters as the user presses the space-bar.
1592
1593 int order_mode
1594 is reserved for future enhancements
1595
1596 int * current_item
1597 The widget sets the referenced location to the index of the cur‐
1598 rent display item (cursor) when it returns.
1599
1600 dlg_button_count
1601 Count the buttons in the list.
1602
1603 const char ** labels
1604 is a list of (pointers to) button labels terminated by a null
1605 pointer.
1606
1607 dlg_button_key
1608 If a key was bound to one of the button-codes in dlg_result_key, fake a
1609 button-value and an “Cancel” key to cause the calling widget to return
1610 the corresponding status.
1611
1612 See dlg_ok_buttoncode, which maps settings for ok/extra/help and button
1613 number into exit-code.
1614
1615 dlg_button_layout
1616 Make sure there is enough space for the buttons by computing the width
1617 required for their labels, adding margins and limiting based on the
1618 screen size.
1619
1620 const char ** labels
1621 is a list of (pointers to) button labels terminated by a null
1622 pointer.
1623
1624 int * limit
1625 the function sets the referenced limit to the width required for
1626 the buttons (limited by the screen size) if that is wider than the
1627 passed-in limit.
1628
1629 dlg_button_sizes
1630 Compute the size of the button array in columns.
1631
1632 const char ** labels
1633 is a list of (pointers to) button labels terminated by a null
1634 pointer.
1635
1636 int vertical
1637 is true if the buttons are arranged in a column rather than a row.
1638
1639 int * longest
1640 Return the total number of columns in the referenced location.
1641
1642 int * length
1643 Return the longest button's columns in the referenced location.
1644
1645 dlg_button_to_char
1646 Find the first uppercase character in the label, which we may use for
1647 an abbreviation. If the label is empty, return -1. If no uppercase
1648 character is found, return 0. Otherwise return the uppercase charac‐
1649 ter.
1650
1651 Normally dlg_draw_buttons and dlg_char_to_button use the first upper‐
1652 case character. However, they keep track of all of the labels and if
1653 the first has already been used in another label, they will continue
1654 looking for another uppercase character. This function does not have
1655 enough information to make that check.
1656
1657 const char * label
1658 is the label to test.
1659
1660 dlg_button_x_step
1661 Compute the step-size needed between elements of the button array.
1662
1663 const char ** labels
1664 is a list of (pointers to) button labels terminated by a null
1665 pointer.
1666
1667 int limit
1668 is the maximum number of columns to allow for the buttons.
1669
1670 int * gap
1671 store the nominal gap between buttons in the referenced location.
1672 This is constrained to be at least one.
1673
1674 int * margin
1675 store the left+right total margins (for the list of buttons) in
1676 the referenced location.
1677
1678 int * step
1679 store the step-size in the referenced location.
1680
1681 dlg_calc_list_width
1682 Calculate the minimum width for the list, assuming none of the items
1683 are truncated.
1684
1685 int item_no
1686 is the number of items.
1687
1688 DIALOG_LISTITEM * items
1689 contains a name and text field, e.g., for checklists or radiobox
1690 lists. The function returns the sum of the widest columns needed
1691 for of each of these fields.
1692
1693 If dialog_vars.no_items is set, the text fields in the list are
1694 ignored.
1695
1696 dlg_calc_listh
1697 Calculate new height and list_height values.
1698
1699 int * height
1700 on input, is the height without adding the list-height. On
1701 return, this contains the total list-height and is the actual wid‐
1702 get's height.
1703
1704 int * list_height
1705 on input, is the requested list-height. On return, this contains
1706 the number of rows available for displaying the list after taking
1707 into account the screen size and the dialog_vars.begin_set and
1708 dialog_vars.begin_y variables.
1709
1710 int item_no
1711 is the number of items in the list.
1712
1713 dlg_calc_listw
1714 This function is obsolete, provided for library-compatibility. It is
1715 replaced by dlg_calc_list_width.
1716
1717 int item_no
1718 is the number of items.
1719
1720 char ** items
1721 is a list of character pointers.
1722
1723 int group
1724 is the number of items in each group, e.g., the second array
1725 index.
1726
1727 dlg_char_to_button
1728 Given a list of button labels, and a character which may be the abbre‐
1729 viation for one, find it, if it exists. An abbreviation will be the
1730 first character which happens to be capitalized in the label. If the
1731 character is found, return its index within the list of labels. Other‐
1732 wise, return DLG_EXIT_UNKNOWN.
1733
1734 int ch
1735 is the character to find.
1736
1737 const char ** labels
1738 is a list of (pointers to) button labels terminated by a null
1739 pointer.
1740
1741 dlg_checklist
1742 This entrypoint provides the --checklist or --radiolist functionality
1743 without the limitations of dialog's command-line syntax (compare to
1744 dialog_checklist).
1745
1746 const char * title
1747 is the title string to display at the top of the widget.
1748
1749 const char * cprompt
1750 is the prompt text shown within the widget.
1751
1752 int height
1753 is the desired height of the box. If zero, the height is adjusted
1754 to use the available screen size.
1755
1756 int width
1757 is the desired width of the box. If zero, the height is adjusted
1758 to use the available screen size.
1759
1760 int list_height
1761 is the minimum height to reserve for displaying the list. If
1762 zero, it is computed based on the given height and width.
1763
1764 int item_no
1765 is the number of items.
1766
1767 DIALOG_LISTITEM * items
1768 This is a list of the items to display in the checklist.
1769
1770 const char * states
1771 This is a list of characters to display for the given states.
1772 Normally a checklist provides true (1) and false (0) values, which
1773 the widget displays as "*" and space, respectively. An applica‐
1774 tion may set this parameter to an arbitrary null-terminated
1775 string. The widget determines the number of states from the
1776 length of this string, and will cycle through the corresponding
1777 display characters as the user presses the space-bar.
1778
1779 int flag
1780 This is should be one of FLAG_CHECK or FLAG_RADIO, depending on
1781 whether the widget should act as a checklist or radiobox.
1782
1783 int * current_item
1784 The widget sets the referenced location to the index of the cur‐
1785 rent display item (cursor) when it returns.
1786
1787 dlg_check_scrolled
1788 given a function key (or other key that was mapped to a function key),
1789 check if it is one of the up/down scrolling functions:
1790
1791 DLGK_PAGE_FIRST,
1792 DLGK_PAGE_LAST,
1793 DLGK_GRID_UP,
1794 DLGK_GRID_DOWN,
1795 DLGK_PAGE_PREV or
1796 DLGK_PAGE_NEXT.
1797
1798 Some widgets use these key bindings for scrolling the prompt-text up
1799 and down, to allow for display in very small windows.
1800
1801 The function returns 0 (zero) if it finds one of these keys, and -1 if
1802 not.
1803
1804 int key
1805 is the function-key to check
1806
1807 int last
1808 is the number of lines which would be used to display the scrolled
1809 prompt in an arbitrarily tall window. It is used here to check
1810 limits for the offset value.
1811
1812 int page
1813 this is the available height for writing scrolled text, which is
1814 smaller than the window if it contains buttons.
1815
1816 bool * show
1817 on return, holds TRUE if dlg_print_scrolled should be used to
1818 redisplay the prompt text.
1819
1820 int * offset
1821 on entry, holds the starting line number (counting from zero) last
1822 used for dlg_print_scrolled. On return, holds the updated start‐
1823 ing line number.
1824
1825 dlg_clear
1826 Set window to the default dialog screen attribute. This is set in the
1827 rc-file with screen_color.
1828
1829 dlg_clr_result
1830 Free storage used for the result buffer (dialog_vars.input_result).
1831 The corresponding pointer is set to NULL.
1832
1833 dlg_color_count
1834 Return the number of colors that can be configured in dialog.
1835
1836 dlg_color_setup
1837 Initialize the color pairs used in dialog.
1838
1839 dlg_count_argv
1840 Count the entries in an argument vector.
1841
1842 argv Points to the argument vector.
1843
1844 dlg_count_columns
1845 Returns the number of columns used for a string. This is not necessar‐
1846 ily the number of bytes in a string.
1847
1848 const char * string
1849 is the string to measure.
1850
1851 dlg_count_real_columns
1852 Returns the number of columns used for a string, accounting for "\Z"
1853 sequences which can be used for coloring the text if dialog_vars.colors
1854 is set. This is not necessarily the number of bytes in a string.
1855
1856 const char * string
1857 is the string to measure.
1858
1859 dlg_count_wchars
1860 Returns the number of wide-characters in the string.
1861
1862 const char * string
1863 is the string to measure.
1864
1865 dlg_create_rc
1866 Create a configuration file, i.e., write internal tables to a file
1867 which can be read back by dialog as an rc-file.
1868
1869 const char * filename
1870 is the name of the file to write to.
1871
1872 dlg_ctl_size
1873 If dialog_vars.size_err is true, check if the given window size is too
1874 large to fit on the screen. If so, exit with an error reporting the
1875 size of the window.
1876
1877 int height
1878 is the window's height
1879
1880 int width
1881 is the window's width
1882
1883 dlg_default_button
1884 If dialog_vars.default_button is positive, return the button-index for
1885 that button code, using dlg_ok_buttoncode to test indices starting with
1886 zero. Otherwise (or if no match was found for the button code), return
1887 zero.
1888
1889 dlg_default_formitem
1890 If dialog_vars.default_item is not null, find that name by matching the
1891 name field in the list of form items. If found, return the index of
1892 that item in the list. Otherwise, return zero.
1893
1894 DIALOG_FORMITEM * items
1895 is the list of items to search. It is terminated by an entry with
1896 a null name field.
1897
1898 dlg_default_item
1899 This function is obsolete, provided for library-compatibility. It is
1900 replaced by dlg_default_formitem and dlg_default_listitem.
1901
1902 char ** items
1903 is the list of items to search.
1904
1905 int llen
1906 is the number of items in each group, e.g., the second array
1907 index.
1908
1909 dlg_defaultno_button
1910 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not, find
1911 the button-index for the “Cancel” button. Otherwise, return the index
1912 for “OK” (always zero).
1913
1914 dlg_del_window
1915 Remove a window, repainting everything else.
1916
1917 WINDOW * win
1918 is the window to remove.
1919
1920 dlg_does_output
1921 This is called each time a widget is invoked which may do output. It
1922 increments dialog_state.output_count, so the output function in dialog
1923 can test this and add a separator.
1924
1925 dlg_draw_arrows
1926 Draw up/down arrows on a window, e.g., for scrollable lists. It calls
1927 dlg_draw_arrows2 using the menubox_color and menubox_border_color
1928 attributes.
1929
1930 WINDOW * dialog
1931 is the window on which to draw an arrow.
1932
1933 int top_arrow
1934 is true if an up-arrow should be drawn at the top of the window.
1935
1936 int bottom_arrow
1937 is true if an down-arrow should be drawn at the bottom of the win‐
1938 dow.
1939
1940 int x
1941 is the zero-based column within the window on which to draw
1942 arrows.
1943
1944 int top
1945 is the zero-based row within the window on which to draw up-arrows
1946 as well as a horizontal line to show the window's top.
1947
1948 int bottom
1949 is the zero-based row within the window on which to draw down-
1950 arrows as well as a horizontal line to show the window's bottom.
1951
1952 dlg_draw_arrows2
1953 Draw up/down arrows on a window, e.g., for scrollable lists.
1954
1955 WINDOW * dialog
1956 is the window on which to draw an arrow.
1957
1958 int top_arrow
1959 is true if an up-arrow should be drawn at the top of the window.
1960
1961 int bottom_arrow
1962 is true if an down-arrow should be drawn at the bottom of the win‐
1963 dow.
1964
1965 int x
1966 is the zero-based column within the window on which to draw
1967 arrows.
1968
1969 int top
1970 is the zero-based row within the window on which to draw up-arrows
1971 as well as a horizontal line to show the window's top.
1972
1973 int bottom
1974 is the zero-based row within the window on which to draw down-
1975 arrows as well as a horizontal line to show the window's bottom.
1976
1977 chtype attr
1978 is the window's background attribute.
1979
1980 chtype borderattr
1981 is the window's border attribute.
1982
1983 dlg_draw_bottom_box
1984 Draw a partial box at the bottom of a window, e.g., to surround a row
1985 of buttons. It is designed to merge with an existing box around the
1986 whole window (see dlg_draw_box), so it uses tee-elements rather than
1987 corner-elements on the top corners of this box.
1988
1989 WINDOW * win
1990 is the window to update.
1991
1992 dlg_draw_bottom_box2
1993 Draw a partial box at the bottom of a window, e.g., to surround a row
1994 of buttons. It is designed to merge with an existing box around the
1995 whole window (see dlg_draw_box2), so it uses tee-elements rather than
1996 corner-elements on the top corners of this box.
1997
1998 WINDOW * win
1999 is the window to update.
2000
2001 chtype on_left
2002 is used to color the upper/left edges of the box, i.e., the tee-
2003 element and horizontal line
2004
2005 chtype on_right
2006 is used to color the right edge of the box, i.e., the tee-element
2007
2008 chtype on_inside
2009 is used to fill-color the inside of the box
2010
2011 dlg_draw_box
2012 Draw a rectangular box with line drawing characters.
2013
2014 WINDOW * win
2015 is the window to update.
2016
2017 int y
2018 is the top row of the box.
2019
2020 int x
2021 is the left column of the box.
2022
2023 int height
2024 is the height of the box.
2025
2026 int width
2027 is the width of the box.
2028
2029 chtype boxchar
2030 is used to color the right/lower edges. It also is fill-color
2031 used for the box contents.
2032
2033 chtype borderchar
2034 is used to color the upper/left edges.
2035
2036 dlg_draw_box2
2037 Draw a rectangular box with line drawing characters.
2038
2039 WINDOW * win
2040 is the window to update.
2041
2042 int y
2043 is the top row of the box.
2044
2045 int x
2046 is the left column of the box.
2047
2048 int height
2049 is the height of the box.
2050
2051 int width
2052 is the width of the box.
2053
2054 chtype boxchar
2055 is used to fill-color for the box contents.
2056
2057 chtype borderchar
2058 is used to color the upper/left edges.
2059
2060 chtype borderchar2
2061 is used to color the right/lower edges.
2062
2063 dlg_draw_buttons
2064 Print a list of buttons at the given position.
2065
2066 WINDOW * win
2067 is the window to update.
2068
2069 int y
2070 is the starting row.
2071
2072 int x
2073 is the starting column.
2074
2075 const char ** labels
2076 is a list of (pointers to) button labels terminated by a null
2077 pointer.
2078
2079 int selected
2080 is the index within the list of the selected button.
2081
2082 int vertical
2083 is true if the buttons are arranged in a column rather than a row.
2084
2085 int limit
2086 is the number of columns (or rows if vertical) allowed for the
2087 display.
2088
2089 dlg_draw_helpline
2090 draw the text in dialog_vars.help_line at the bottom of the given win‐
2091 dow.
2092
2093 WINDOW * dialog
2094 is the window to modify.
2095
2096 bool decorations
2097 if true, allow room for the scrolling arrows.
2098
2099 dlg_draw_scrollbar
2100 If dialog_state.use_scrollbar is set, draw a scrollbar on the right
2101 margin of windows holding scrollable data. Also (whether or not the
2102 scrollbar is drawn), annotate the bottom margin of the window with the
2103 percentage of data by the bottom of that window, and call
2104 dlg_draw_arrows2 to put markers on the window showing when more data is
2105 available.
2106
2107 WINDOW * win
2108 is the window in which the data is scrolled. Because left, right,
2109 top, bottom are passed as parameters, this window can contain
2110 additional data.
2111
2112 long first_data
2113 is the zero-based index to the first row of data in the current
2114 window.
2115
2116 long this_data
2117 is the zero-based index to the current row of data.
2118
2119 long next_data
2120 is the zero-based index to the next data after the current row.
2121
2122 long total_data
2123 is the total number of rows of data.
2124
2125 int left
2126 is the zero-based left margin/column of the window. The up/down
2127 arrows are draw inset by 5 columns from this point.
2128
2129 int right
2130 is the zero-based right margin/column of the window. The scroll‐
2131 bar is drawn flush against this column.
2132
2133 int top
2134 is the zero-based row within the window on which to draw up-arrows
2135 as well as a horizontal line to show the window's top.
2136
2137 int bottom
2138 is the zero-based row within the window on which to draw down-
2139 arrows as well as a horizontal line to show the window's bottom.
2140
2141 chtype attr
2142 is the window's background attribute.
2143
2144 chtype borderattr
2145 is the window's border attribute.
2146
2147 dlg_draw_shadow
2148 Draw shadows along the right and bottom edge of a window to give it a
2149 3-dimensional look. (The height, etc., may not be the same as the win‐
2150 dow's actual values).
2151
2152 WINDOW * win
2153 is the window to update.
2154
2155 int height
2156 is the height of the window.
2157
2158 int width
2159 is the width of the window.
2160
2161 int y
2162 is the top row of the window.
2163
2164 int x
2165 is the left column of the window.
2166
2167 dlg_draw_title
2168 Draw a title centered at the top of the window.
2169
2170 WINDOW * win
2171 is the window to update.
2172
2173 const char * title
2174 is the title string to display at the top of the widget.
2175
2176 dlg_dummy_menutext
2177 This is a utility function which supports the --inputmenu option of the
2178 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
2179 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
2180 it passes dlg_dummy_menutext.
2181
2182 The function should only return DLG_EXIT_ERROR.
2183
2184 DIALOG_LISTITEM * items
2185 is the list of menu items
2186
2187 int current
2188 is the index of the currently-selected item
2189
2190 char * newtext
2191 is the updated text for the menu item
2192
2193 dlg_dump_keys
2194 Write all user-defined key-bindings to the given stream, e.g., as part
2195 of dlg_create_rc.
2196
2197 FILE * fp
2198 is the stream on which to write the bindings.
2199
2200 dlg_dump_window_keys
2201 Write all user-defined key-bindings to the given stream, e.g., as part
2202 of dlg_create_rc.
2203
2204 FILE * fp
2205 is the stream on which to write the bindings.
2206
2207 WINDOW * win
2208 is the window for which bindings should be dumped. If it is null,
2209 then only built-in bindings are dumped.
2210
2211 dlg_eat_argv
2212 Remove one or more items from an argument vector.
2213
2214 int * argcp
2215 in/out parameter giving the length of the argument vector. char
2216 *** argvp in/out parameter pointing to the argument vector. int
2217 start starting index. int count number of arguments to remove.
2218
2219 dlg_edit_offset
2220 Given the character-offset in the string, returns the display-offset
2221 where dialog should position the cursor. In this context, “characters”
2222 may be multicolumn, since the string can be a multibyte character
2223 string.
2224
2225 char * string
2226 is the string to analyze
2227
2228 int offset
2229 is the character-offset
2230
2231 int x_last
2232 is a limit on the column positions that can be used, e.g., the
2233 window's size.
2234
2235 dlg_edit_string
2236 Updates the string and character-offset, given various editing charac‐
2237 ters or literal characters which are inserted at the character-offset.
2238 Returns true if an editing change was made (and the display should be
2239 updated), and false if the key was something like KEY_ENTER, which is a
2240 non-editing action outside this function.
2241
2242 char * string
2243 is the (multibyte) string to update
2244
2245 int * offset
2246 is the character-offset
2247
2248 int key
2249 is the editing key
2250
2251 int fkey
2252 is true if the editing key is a function-key
2253
2254 bool force
2255 is used in a special loop case by calling code to force the return
2256 value of this function when a function-key code 0 is passed in.
2257
2258 dlg_exit
2259 Given an internal exit code, check if the corresponding environment
2260 variable is set. If so, remap the exit code to match the environment
2261 variable. Finally call exit with the resulting exit code.
2262
2263 int code
2264 is the internal exit code, e.g., DLG_EXIT_OK, which may be
2265 remapped.
2266
2267 The dialog program uses this function to allow shell scripts to remap
2268 the exit codes so they can distinguish ESC from ERROR.
2269
2270 dlg_exitcode2s
2271 Returns the name of an exit-code, e.g., “OK” for DLG_EXIT_OK.
2272
2273 int code
2274 is an exit-code for dialog as defined in <dialog.h>.
2275
2276 dlg_exitname2n
2277 Returns an exit-code as the reverse of dlg_exitcode2n, e.g., 0
2278 (DLG_EXIT_OK) for the “OK” string.
2279
2280 const char * name
2281 is the name of an exit-code for dialog as defined in <dialog.h>
2282 but omitting the “DLG_EXIT_” prefix.
2283
2284 dlg_exit_buttoncode
2285 Map the given button index for dlg_exit_label into dialog's exit-code.
2286
2287 int button
2288 is the button index
2289
2290 dlg_exit_label
2291 Return a list of button labels. If dialog_vars.extra_button is true,
2292 return the result of dlg_ok_labels. Otherwise, return a list with the
2293 “Exit” label and (if dialog_vars.help_button is set) the “Help” button
2294 as well.
2295
2296 dlg_exiterr
2297 Quit program killing all tailboxbg widgets.
2298
2299 const char * fmt
2300 is the format of the printf-like message to write.
2301
2302 ...
2303 are the variables to apply to the fmt format.
2304
2305 dlg_find_index
2306 Given the character-offset to find in the list, return the correspond‐
2307 ing array index.
2308
2309 const int *list
2310 contains a list of character-offsets, i.e., indices into a string
2311 that denote the beginning of multibyte characters.
2312
2313 int limit
2314 is the last index into list to search.
2315
2316 int to_find
2317 is the character-offset to find.
2318
2319 dlg_finish_string
2320 If DIALOG_STATE.finish_string is true, this function discards data used
2321 to speed up layout computations.
2322
2323 const char * string
2324 is the address of the string whose data should be discarded. The
2325 address rather than contents is used as the unique identifier
2326 because some of the caching is used for editable input-fields.
2327
2328 dlg_flush_getc
2329 Cancel the local data saved by dlg_last_getc.
2330
2331 dlg_editbox
2332 This entrypoint provides the --editbox functionality without the limi‐
2333 tations of dialog's command-line syntax (compare to dialog_editbox).
2334
2335 const char * title
2336 is the title string to display at the top of the widget.
2337
2338 char *** list
2339 is a pointer to an array of char * pointers. The array is allo‐
2340 cated by the caller, and so are the strings to which it points.
2341 The dlg_editbox function may reallocate the array and the strings.
2342
2343 int * rows
2344 points to the nominal length of list. The referenced value is
2345 updated iflist is reallocated.
2346
2347 int height
2348 is the desired height of the box. If zero, the height is adjusted
2349 to use the available screen size.
2350
2351 int width
2352 is the desired width of the box. If zero, the height is adjusted
2353 to use the available screen size.
2354
2355 dlg_form
2356 This entrypoint provides the --form functionality without the limita‐
2357 tions of dialog's command-line syntax (compare to dialog_form).
2358
2359 const char * title
2360 is the title string to display at the top of the widget.
2361
2362 const char * cprompt
2363 is the prompt text shown within the widget.
2364
2365 int height
2366 is the desired height of the box. If zero, the height is adjusted
2367 to use the available screen size.
2368
2369 int width
2370 is the desired width of the box. If zero, the height is adjusted
2371 to use the available screen size.
2372
2373 int form_height
2374 is the minimum height to reserve for displaying the list. If
2375 zero, it is computed based on the given height and width.
2376
2377 int item_no
2378 is the number of items.
2379
2380 DIALOG_FORMITEM * items
2381 This is a list of the items to display in the form.
2382
2383 int * current_item
2384 The widget sets the referenced location to the index of the cur‐
2385 rent display item (cursor) when it returns.
2386
2387 dlg_free_columns
2388 Free data allocated by dlg_align_columns.
2389
2390 char **target
2391 This is the array which was reformatted. It points to the first
2392 string to free.
2393
2394 int per_row
2395 This is the size of the struct for each row of the array.
2396
2397 int num_rows
2398 This is the number of rows in the array.
2399
2400 dlg_free_formitems
2401 Free memory owned by a list of DIALOG_FORMITEM's.
2402
2403 DIALOG_FORMITEM * items
2404 is the list to free.
2405
2406 dlg_free_gauge
2407 Remove the gauge widget from the screen and free its associated memory.
2408
2409 void *objptr
2410 points to the gauge widget.
2411
2412 dlg_getc
2413 Read a character from the given window. Handle repainting here (to
2414 simplify things in the calling application). Also, if input-call‐
2415 back(s) are set up, poll the corresponding files and handle the
2416 updates, e.g., for displaying a tailbox. Returns the key-code.
2417
2418 WINDOW * win
2419 is the window within which to read.
2420
2421 int * fkey
2422 as a side-effect, set this to true if the key-code is really a
2423 function-key.
2424
2425 dlg_get_attrs
2426 extract the video attributes from the given window.
2427
2428 WINDOW * win
2429 is the window from which to get attributes.
2430
2431 dlg_getc_callbacks
2432 passes the given key-code ch to the current window that has established
2433 a callback. If the callback returns zero, remove it and try the next
2434 window. If no more callbacks remain, return. If any callbacks were
2435 found, return true, otherwise false.
2436
2437 int ch
2438 is the key-code
2439
2440 int fkey
2441 is true if the key is a function-key
2442
2443 int * result
2444 is used to pass an exit-code to the caller, which should pass that
2445 via dlg_exit.
2446
2447 dlg_index_columns
2448 Build a list of the display-columns for the given multibyte string's
2449 characters.
2450
2451 const char * string
2452 is the string to analyze
2453
2454 dlg_index_wchars
2455 Build an index of the wide-characters in the string, so the caller can
2456 easily tell which byte-offset begins a given wide-character.
2457
2458 const char * string
2459 is the string to analyze
2460
2461 dlg_item_help
2462 Draw the string for the dialog_vars.item_help feature.
2463
2464 const char * txt
2465 is the help-message
2466
2467 dlg_killall_bg
2468 If dialog has callbacks active, purge the list of all that are not
2469 marked to keep in the background. If any remain, run those in a back‐
2470 ground process.
2471
2472 int * retval
2473 stores the exit-code to pass back to the caller.
2474
2475 dlg_last_getc
2476 returns the most recent character that was read via dlg_getc.
2477
2478 dlg_limit_columns
2479 Given a column limit, count the number of wide characters that can fit
2480 into that limit. The offset is used to skip over a leading character
2481 that was already written.
2482
2483 const char * string
2484 is the string to analyze
2485
2486 int limit
2487 is the column limit
2488
2489 int offset
2490 is the starting offset from which analysis should continue
2491
2492 dlg_lookup_key
2493 Check for a key-binding. If there is no binding associated with the
2494 widget, it simply returns the given curses-key. Otherwise, it returns
2495 the result of the binding
2496
2497 WINDOW * win
2498 is the window on which the binding is checked
2499
2500 int curses_key
2501 is the curses key-code
2502
2503 int * dialog_key
2504 is the corresponding dialog internal code (see DLG_KEYS_ENUM in
2505 dlg_key.h).
2506
2507 dlg_max_input
2508 Limit the parameter according to dialog_vars.max_input
2509
2510 int max_len
2511 is the value to limit
2512
2513 dlg_match_char
2514 Match a given character against the beginning of the string, ignoring
2515 case of the given character. The matching string must begin with an
2516 uppercase character.
2517
2518 int ch
2519 is the character to check
2520
2521 const char * string
2522 is the string to search
2523
2524 dlg_menu
2525 This entrypoint provides the --menu functionality without the limita‐
2526 tions of dialog's command-line syntax (compare to dialog_menu).
2527
2528 const char * title
2529 is the title string to display at the top of the widget.
2530
2531 const char * cprompt
2532 is the prompt text shown within the widget.
2533
2534 int height
2535 is the desired height of the box. If zero, the height is adjusted
2536 to use the available screen size.
2537
2538 int width
2539 is the desired width of the box. If zero, the height is adjusted
2540 to use the available screen size.
2541
2542 int menu_height
2543 is the minimum height to reserve for displaying the list. If
2544 zero, it is computed based on the given height and width.
2545
2546 int item_no
2547 is the number of items.
2548
2549 DIALOG_LISTITEM * items
2550 This is a list of the items to display in the form.
2551
2552 int * current_item
2553 The widget sets the referenced location to the index of the cur‐
2554 rent display item (cursor) when it returns.
2555
2556 DIALOG_INPUTMENU rename_menutext
2557 If this is not dlg_dummy_menutext, the widget acts like an input‐
2558 menu widget, providing an extra “Rename” button, which activates
2559 an edit feature on the selected menu item.
2560
2561 dlg_move_window
2562 Moves/resizes the given window to the given position and size.
2563
2564 WINDOW *win
2565 is the window to move/resize.
2566
2567 WINDOW *height
2568 is the height of the resized window.
2569
2570 WINDOW *width
2571 is the width of the resized window.
2572
2573 WINDOW *y
2574 y-ordinate to use for the repositioned window.
2575
2576 WINDOW *x
2577 x-ordinate to use for the repositioned window.
2578
2579 dlg_mouse_bigregion
2580 Retrieve the big-region under the pointer.
2581
2582 int y
2583 is the row on which the mouse click occurred
2584
2585 int x
2586 is the column on which the mouse click occurred
2587
2588 dlg_mouse_free_regions
2589 Free the memory associated with mouse regions.
2590
2591 dlg_mouse_mkbigregion
2592 Creates a region on which the mouse-clicks will return a specified
2593 code.
2594
2595 int y
2596 is the top-row of the region.
2597
2598 int x
2599 is the left-column of the region.
2600
2601 int height
2602 is the height of the region.
2603
2604 int width
2605 is the width of the region.
2606
2607 int code
2608 is a code used to make the region unique within a widget
2609
2610 int step_x
2611 is used in modes 2 (columns) and 3 (cells) to determine the width
2612 of a column/cell.
2613
2614 int step_y
2615 is currently unused
2616
2617 int mode
2618 is used to determine how the mouse position is translated into a
2619 code (like a function-key):
2620
2621 1 index by lines
2622
2623 2 index by columns
2624
2625 3 index by cells
2626
2627 dlg_mouse_mkregion
2628 int y
2629 is the top-row of the region.
2630
2631 int x
2632 is the left-column of the region.
2633
2634 int height
2635 is the height of the region.
2636
2637 int width
2638 is the width of the region.
2639
2640 int code
2641 is a code used to make the region unique within a widget
2642
2643 dlg_mouse_region
2644 Retrieve the frame under the mouse pointer
2645
2646 int y
2647 is the row of the mouse-click
2648
2649 int x
2650 is the column of the mouse-click
2651
2652 dlg_mouse_setbase
2653 Sets a base for subsequent calls to dlg_mouse_mkregion, so they can
2654 make regions relative to the start of a given window.
2655
2656 int x
2657 is the left-column for the base
2658
2659 int y
2660 is the top-row for the base
2661
2662 dlg_mouse_setcode
2663 Sets a value used internally by dlg_mouse_mkregion which is added to
2664 the code parameter. By providing different values, e.g., multiples of
2665 KEY_MAX, it is possible to support multiple “big” regions in a widget.
2666 The buildlist widget uses this feature to recognize mouse-clicks in the
2667 left/right panes.
2668
2669 int code
2670 is the value to add to dlg_mouse_mkregion's code parameter.
2671
2672 dlg_mouse_wgetch
2673 is a wrapper for dlg_getc which additionally maps mouse-clicks (if the
2674 curses library supports those) into extended function-keys which encode
2675 the position according to the mode in dlg_mouse_mkbigregion. Returns
2676 the corresponding key-code.
2677
2678 WINDOW * win
2679 is the window on which to perform the input
2680
2681 int * fkey
2682 the referenced location is set to true if the key-code is an
2683 actual or extended (mouse) function-key.
2684
2685 dlg_mouse_wgetch_nowait
2686 This is a non-blocking variant of dlg_mouse_wgetch.
2687
2688 WINDOW * win
2689 is the window on which to perform the input
2690
2691 int * fkey
2692 the referenced location is set to true if the key-code is an
2693 actual or extended (mouse) function-key.
2694
2695 dlg_need_separator
2696 Check if an output-separator is needed. If dialog_vars.output_separa‐
2697 tor is set, return true. Otherwise, if dialog_vars.input_result is
2698 nonempty, return true. If neither, return false.
2699
2700 dlg_new_modal_window
2701 Create a modal window, optionally with a shadow. The shadow is created
2702 if dialog_state.use_shadow is true.
2703
2704 WINDOW * parent
2705 is the parent window (usually the top-level window of a widget)
2706
2707 int height
2708 is the window's height
2709
2710 int width
2711 is the window's width
2712
2713 int y
2714 is the window's top-row
2715
2716 int x
2717 is the window's left-column
2718
2719 dlg_new_window
2720 Create a window, optionally with a shadow. The shadow is created if
2721 dialog_state.use_shadow is true.
2722
2723 int height
2724 is the window's height
2725
2726 int width
2727 is the window's width
2728
2729 int y
2730 is the window's top-row
2731
2732 int x
2733 is the window's left-column
2734
2735 dlg_next_button
2736 Return the next index in the list of labels.
2737
2738 const char ** labels
2739 is a list of (pointers to) button labels terminated by a null
2740 pointer.
2741
2742 int button
2743 is the current button-index.
2744
2745 dlg_next_ok_buttonindex
2746 Assuming that the caller is using dlg_ok_labels to list buttons, find
2747 the next index in the list of buttons.
2748
2749 int current
2750 is the current index in the list of buttons
2751
2752 int extra
2753 if negative, provides a way to enumerate extra active areas on the
2754 widget.
2755
2756 dlg_ok_buttoncode
2757 Map the given button index for dlg_ok_labels into dialog's exit-code.
2758
2759 int button
2760 is the button-index (which is not necessarily the same as the
2761 index in the list of labels).
2762
2763 dlg_ok_button_key
2764 Calls dlg_button_key with the “Cancel” button disabled, e.g., for the
2765 textbox widget.
2766
2767 dlg_ok_label
2768 Returns a list with the “Ok” label, and if dialog_vars.help_button is
2769 true, the “Help” label as well.
2770
2771 dlg_ok_labels
2772 Return a list of button labels for the OK/Cancel group of widgets.
2773
2774 dlg_ordinate
2775 Decode the string as an integer, decrement if greater than zero to make
2776 a curses-ordinate from a dialog-ordinate.
2777
2778 dlg_parse_bindkey
2779 Parse the parameters of the “bindkeys” configuration-file entry. This
2780 expects widget name which may be "*", followed by curses key definition
2781 and then dialog key definition.
2782
2783 char * params
2784 is the parameter string to parse.
2785
2786 dlg_parse_rc
2787 Parse the configuration file and set up variables.
2788
2789 dlg_popen
2790 Open a pipe which ties the standard error and output together. The
2791 popen function captures only the standard output of a command.
2792
2793 const char *command
2794 The shell command to run.
2795
2796 const char *type
2797 Like popen, "r" is used to read, and "w" is used to write.
2798
2799 dlg_prev_button
2800 Return the previous index in the list of labels.
2801
2802 const char ** labels
2803 is a list of (pointers to) button labels terminated by a null
2804 pointer.
2805
2806 int button
2807 is the current button index
2808
2809 dlg_print_listitem
2810 This is a helper function used for the various “list” widgets, e.g.,
2811 checklist, menu, buildlist, treeview. Each list-widget has “tag” and
2812 “description” values for each item which can be displayed. If dia‐
2813 log_vars.no_tags is true, the “tag” value is not shown. The first
2814 character of the first value shown (tag or description) is highlighted
2815 to indicate that the widget will match it for quick navigation.
2816
2817 WINDOW *win
2818 the window in which to display the text
2819
2820 const char *text
2821 the value to display
2822
2823 int climit
2824 the number of columns available for printing the text
2825
2826 bool first
2827 true if this is the first call (for “tag” and “description”), and
2828 the first character of the value should be highlighted.
2829
2830 int selected
2831 nonzero if the text should be displayed using the “selected” col‐
2832 ors
2833
2834 dlg_print_scrolled
2835 This is a wrapper for dlg_print_autowrap which allows the user to
2836 scroll too-long prompt text up/down.
2837
2838 See dlg_check_scrolled for a function which updates the offset variable
2839 used as a parameter here. It complements this function; you need both.
2840 If pauseopt is set, this function returns an updated last parameter,
2841 needed for dlg_check_scrolled calls.
2842
2843 WINDOW * win
2844 is the window to update.
2845
2846 const char * prompt
2847 is the string to print
2848
2849 int offset
2850 is the starting line-number to write wrapped text.
2851
2852 int height
2853 is the available height for writing the wrapped text
2854
2855 int width
2856 is the width that the wrapping should occur in
2857
2858 int pauseopt
2859 is true if the extra functionality for scrolling should be
2860 enabled. If false, this calls dlg_print_autowrap without doing
2861 any scrolling.
2862
2863 dlg_print_line
2864 Print one line of the prompt in the window within the limits of the
2865 specified right margin. The line will end on a word boundary and a
2866 pointer to the start of the next line is returned, or a NULL pointer if
2867 the end of *prompt is reached.
2868
2869 WINDOW *win
2870 is the window to update.
2871
2872 chtype *attr
2873 holds the starting attributes, and is updated to reflect the final
2874 attributes applied to the string.
2875
2876 const char *prompt
2877 is the string to print
2878
2879 int lm
2880 is the left margin.
2881
2882 int rm
2883 is the right margin
2884
2885 int *x
2886 returns the ending x-ordinate.
2887
2888 dlg_prev_ok_buttonindex
2889 Find the previous button index in the list from dlg_ok_labels.
2890
2891 int current
2892 is the current index
2893
2894 int extra
2895 if negative provides a way to enumerate extra active areas on the
2896 widget.
2897
2898 dlg_print_autowrap
2899 Print a string of text in a window, automatically wrap around to the
2900 next line if the string is too long to fit on one line. Note that the
2901 string may contain embedded newlines. The text is written starting at
2902 the top of the window.
2903
2904 WINDOW * win
2905 is the window to update.
2906
2907 const char * prompt
2908 is the string to print
2909
2910 int height
2911 is the nominal height the wrapped string is limited to
2912
2913 int width
2914 is the width that the wrapping should occur in
2915
2916 dlg_print_size
2917 If dialog_vars.print_siz is true, print the given height/width (from a
2918 widget) to dialog_state.output, e.g., Size: height, width.
2919
2920 int height
2921 is the window's height
2922
2923 int width
2924 is the window's width
2925
2926 dlg_print_text
2927 Print up to cols columns from text, optionally rendering dialog's
2928 escape sequences for attributes and color.
2929
2930 WINDOW * win
2931 is the window to update.
2932
2933 const char * txt
2934 is the string to print
2935
2936 int col
2937 is the column limit
2938
2939 chtype * attr
2940 holds the starting attributes, and is updated to reflect the final
2941 attributes applied to the string.
2942
2943 dlg_progressbox
2944 implements the "--prgbox" and "--progressbox" options.
2945
2946 const char * title
2947 is the title on the top of the widget.
2948
2949 const char * cprompt
2950 is the prompt text shown within the widget. If empty or null, no
2951 prompt is shown.
2952
2953 int height
2954 is the desired height of the box. If zero, the height is based on
2955 the screen size.
2956
2957 int width
2958 is the desired width of the box. If zero, the height is based on
2959 the screen size.
2960
2961 int pauseopt
2962 if true, an “OK” button will be shown, and the dialog will wait
2963 for it to complete. With an “OK” button, it is denoted a “pro‐
2964 grambox”, without an “OK” button, it is denoted a “progressbox”.
2965
2966 FILE * fp
2967 is the file pointer, which may be a pipe or a regular file.
2968
2969 dlg_put_backtitle
2970 Display the background title if dialog_vars.backtitle is non-null. The
2971 background title is shown at the top of the screen.
2972
2973 dlg_reallocate_gauge
2974 Allocates or reallocates a gauge widget (see dlg_allocate_gauge). Use
2975 dlg_update_gauge to display the result.
2976
2977 void ** objptr
2978 If the pointer referenced by this parameter is null, the function
2979 creates a new gauge widget using dlg_allocate_gauge. Otherwise,
2980 it updates the title and cprompt values, reusing the window from
2981 the previous call on this function. As a side-effect, the func‐
2982 tion stores the updated object-pointer via the objptr parameter.
2983
2984 const char * title
2985 is the title string to display at the top of the widget.
2986
2987 const char * cprompt
2988 is the prompt text shown within the widget.
2989
2990 int height
2991 is the desired height of the box. If zero, the height is adjusted
2992 to use the available screen size.
2993
2994 int width
2995 is the desired width of the box. If zero, the height is adjusted
2996 to use the available screen size.
2997
2998 int percent
2999 is the percentage to show in the progress bar.
3000
3001 dlg_register_buttons
3002 The widget developer should call this function after dlg_register_win‐
3003 dow, for the list of button labels associated with the widget. One may
3004 bind a key to a button, e.g., “OK” for DLGK_OK,
3005
3006 WINDOW * win
3007 is the window with which to associate the buttons
3008
3009 const char * name
3010 is the widget's binding name (usually the name of the widget).
3011
3012 const char ** buttons
3013 is the list of buttons
3014
3015 dlg_register_window
3016 For a given named widget's window, associate a binding table.
3017
3018 WINDOW * win
3019 is the window with which to associate the buttons
3020
3021 const char * name
3022 is the widget's binding name (usually the name of the widget).
3023
3024 DLG_KEYS_BINDING * binding
3025 is the binding table
3026
3027 dlg_remove_callback
3028 Remove a callback.
3029
3030 DIALOG_CALLBACK * p
3031 contains the callback information.
3032
3033 dlg_renamed_menutext
3034 This is a utility function which supports the --inputmenu option of the
3035 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
3036 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
3037 it passes dlg_dummy_menutext.
3038
3039 The function should add “RENAMED” to dialog_vars.input_result , fol‐
3040 lowed by the menu item's name and the newtext value (with a space sepa‐
3041 rating the three items), and return DLG_EXIT_EXTRA.
3042
3043 DIALOG_LISTITEM * items
3044 is the list of menu items
3045
3046 int current
3047 is the index of the currently-selected item
3048
3049 char * newtext
3050 is the updated text for the menu item
3051
3052 dlg_restore_vars
3053 Restore dialog's variables from the given variable (see dia‐
3054 log_save_vars).
3055
3056 DIALOG_VARS * save
3057 is the variable from which to restore.
3058
3059 The DIALOG_VARS.input_length and DIALOG_VARS.input_result members are
3060 treated specially, since these are used by a widget to pass data to the
3061 caller. They are not modified by this function.
3062
3063 dlg_result_key
3064 Test a dialog internal keycode to see if it corresponds to one of the
3065 push buttons on the widget such as “OK”. This is only useful if there
3066 are user-defined key bindings, since there are no built-in bindings
3067 that map directly to DLGK_OK, etc. Return true if a mapping was done.
3068
3069 int dialog_key
3070 is the dialog key to test
3071
3072 int fkey
3073 is true if this is a function key
3074
3075 int * resultp
3076 store the result of the mapping in the referenced location.
3077
3078 dlg_save_vars
3079 Save dialog's variables into the given variable (see dlg_restore_vars).
3080
3081 DIALOG_VARS * save
3082 is the variable into which to save.
3083
3084 dlg_set_focus
3085 Set focus on the given window, making it display above other windows on
3086 the screen.
3087
3088 WINDOW * parent
3089 is the parent window (usually the top-level window of a widget)
3090
3091 WINDOW * win
3092 is the window on which to place focus (usually a subwindow of a
3093 widget)
3094
3095 dlg_set_result
3096 Setup a fixed-buffer for the result in dialog_vars.input_result
3097
3098 const char * string
3099 is the new contents for the result
3100
3101 dlg_show_string
3102 Displays the string, shifted as necessary, to fit within the box and
3103 show the current character-offset.
3104
3105 WINDOW * win
3106 is the window within which to display
3107
3108 const char * string
3109 is the string to display
3110
3111 int offset
3112 is the starting (character, not bytes) offset
3113
3114 chtype attr
3115 is the window attribute to use for the string
3116
3117 int y_base
3118 beginning row on screen
3119
3120 int x_base
3121 beginning column on screen
3122
3123 int x_last
3124 number of columns on screen
3125
3126 bool hidden
3127 if true, do not echo input
3128
3129 bool force
3130 if true, force repaint
3131
3132 dlg_strclone
3133 duplicate the string, like strdup.
3134
3135 const char * cprompt
3136 is the string to duplicate
3137
3138 dlg_strcmp
3139 compare two strings, ignoring case.
3140
3141 const char * a
3142 is one string
3143
3144 const char * b
3145 is the other string
3146
3147 dlg_string_to_argv
3148 Convert a string to an argument vector returning an index (which must
3149 be freed by the caller). The string is modified:
3150
3151 · Blanks between arguments are replaced by nulls.
3152
3153 · Normally arguments are separated by blanks; however you can double-
3154 quote an argument to enclose blanks. The surrounding double-quotes
3155 are removed from the string.
3156
3157 · A backslash preceding a double-quote within double-quotes is
3158 removed.
3159
3160 · A backslash preceding a newline outside double-quotes is removed.
3161
3162 · Except for special cases, backslashes are preserved in the strings,
3163 since other dialog functions interpret backslashes, e.g., for col‐
3164 ors.
3165
3166 char *blob
3167 is the string to convert.
3168
3169 dlg_sub_window
3170 create a subwindow, e.g., for an input area of a widget
3171
3172 WINDOW * win
3173 is the parent window
3174
3175 int height
3176 is the subwindow's height
3177
3178 int width
3179 is the subwindow's width
3180
3181 int y
3182 is the subwindow's top-row
3183
3184 int x
3185 is the subwindow's left-column
3186
3187 dlg_tab_correct_str
3188 If the dialog_vars.tab_correct is true, convert tabs to single spaces.
3189 Return the converted result. The caller is responsible for freeing the
3190 string.
3191
3192 char * prompt
3193 is the string to convert
3194
3195 dlg_trace
3196 If the parameter is non-null, opens a trace file with that name and
3197 stores the file pointer in dialog_state.trace.
3198
3199 dlg_trace_2n
3200 logs a numeric value as a comment.
3201
3202 char * name
3203 is the name to log in the comment.
3204
3205 int value
3206 is the value to log in the comment.
3207
3208 dlg_trace_2s
3209 logs a string value as a comment. If the value contains embedded new‐
3210 lines, the comment is continued with “#+” markers.
3211
3212 char * name
3213 is the name to log in the comment.
3214
3215 int value
3216 is the value to log in the comment.
3217
3218 dlg_trace_chr
3219 If dialog_state.trace is set, translate the parameters into a printable
3220 representation, log it on a “chr” line.
3221
3222 int ch
3223 is the nominal keycode value.
3224
3225 int fkey
3226 is nonzero if the value is really a function key. Some of these
3227 may be values declared in the DLG_KEYS_ENUM.
3228
3229 dlg_trace_msg
3230 Write a formatted message to the trace file.
3231
3232 const char * fmt
3233 is the format of the printf-like message to write.
3234
3235 ...
3236 are the variables to apply to the fmt format.
3237
3238 Use the DLG_TRACE macro for portability, in case the trace feature is
3239 not compiled into the library. It uses an extra level of parentheses
3240 to work with a variable number of parameters, e.g.,
3241
3242 DLG_TRACE(("this is dialog version %s\n", dialog_version()));
3243
3244 dlg_trace_va_msg
3245 Write a formatted message to the trace file.
3246
3247 const char *fmt
3248 is the format of the printf-like message to write.
3249
3250 va_list ap
3251 are the variables to apply to the fmt format.
3252
3253 This is used in dlg_exiterr to capture error messages in the trace
3254 file:
3255
3256 va_start(ap, fmt);
3257 dlg_trace_msg("## Error: ");
3258 dlg_trace_va_msg(fmt, ap);
3259 va_end(ap);
3260
3261 Unlike dlg_trace_msg, an extra macro is not needed.
3262
3263 dlg_ttysize
3264 Returns the screensize without using curses. That allows the function
3265 to be used before initializing the screen.
3266
3267 dlg_trace_win
3268 If dialog_state.trace is set, log a printable picture of the given win‐
3269 dow.
3270
3271 dlg_treeview
3272 This is an alternate interface to 'treeview' which allows the applica‐
3273 tion to read the list item states back directly without putting them in
3274 the output buffer.
3275
3276 const char * title
3277 is the title on the top of the widget.
3278
3279 const char * cprompt
3280 is the prompt text shown within the widget.
3281
3282 int height
3283 is the desired height of the box. If zero, the height is based on
3284 the screen size.
3285
3286 int width
3287 is the desired width of the box. If zero, the height is based on
3288 the screen size.
3289
3290 int list_height
3291 is the minimum height to reserve for displaying the list. If
3292 zero, it is computed based on the given height and width.
3293
3294 int item_no
3295 is the number of rows in items.
3296
3297 DIALOG_LISTITEM * items
3298 is the list of items, contain tag, name, and optionally help
3299 strings (if dialog_vars.item_help is set). The initial selection
3300 state for each item is also in this list.
3301
3302 const char * states
3303 This is a list of characters to display for the given states.
3304 Normally a buildlist provides true (1) and false (0) values, which
3305 the widget displays as "*" and space, respectively. An applica‐
3306 tion may set this parameter to an arbitrary null-terminated
3307 string. The widget determines the number of states from the
3308 length of this string, and will cycle through the corresponding
3309 display characters as the user presses the space-bar.
3310
3311 int * depths
3312 This is a list of depths of each item in the tree. It is a sepa‐
3313 rate parameter from items to allow reuse of the existing func‐
3314 tions.
3315
3316 int flag
3317 is either FLAG_CHECK, for checklists (multiple selections), or
3318 FLAG_RADIO for radiolists (a single selection).
3319
3320 int * current_item
3321 The widget sets the referenced location to the index of the cur‐
3322 rent display item (cursor) when it returns.
3323
3324 dlg_trim_string
3325 The dialog program uses this in each widget to adjust the message
3326 string, which may contain the newline character (referred to as '\n')
3327 and/or the special substring "\n" (which can be translated into a new‐
3328 line character).
3329
3330 There are several optional features:
3331
3332 · Unless dialog_vars.nocollapse is set, each tab is converted to a
3333 space before other processing.
3334
3335 · If dialog_vars.no_nl_expand is not set, and the string has "\n"
3336 substrings:
3337
3338 · The function changes embedded "\n" substrings to '\n' charac‐
3339 ters.
3340
3341 The function preserves extra spaces after these substitutions.
3342 For instance, spaces following a newline (substring or charac‐
3343 ter) are preserved to use as an indentation.
3344
3345 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3346 line characters. Otherwise, each '\n' newline character is
3347 converted to a space.
3348
3349 · Otherwise, if dialog_vars.trim_whitespace is set:
3350
3351 · This function strips all extra spaces to simplify justifica‐
3352 tion.
3353
3354 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3355 line characters. Otherwise, each '\n' newline character is
3356 converted to a space.
3357
3358 · Finally (if dialog_vars.no_nl_expand is set, or the string does not
3359 contain "\n" substrings, and dialog_vars.trim_whitespace is not
3360 set):
3361
3362 · Unless dialog_vars.nocollapse is set, sequences of spaces are
3363 reduced to a single space.
3364
3365 char * src
3366 is the string to trim
3367
3368 dlg_unregister_window
3369 Remove the bindings for a given window.
3370
3371 WINDOW * win
3372 is the window from which to remove bindings
3373
3374 dlg_update_gauge
3375 Update a gauge widget to show a different percentage value.
3376
3377 void *objptr
3378 points to the gauge object to update.
3379
3380 int percent
3381 is the new percentage value to display.
3382
3383 dlg_will_resize
3384 This filters out bursts of KEY_RESIZE values. Call this after dlg_getc
3385 returns KEY_RESIZE, to improve performance.
3386
3387 dlg_yes_buttoncode
3388 Map the given button index for dlg_yes_labels into dialog's exit-code.
3389
3390 int button
3391 is the button index
3392
3393 dlg_yes_labels
3394 Return a list of buttons for Yes/No labels.
3395
3396 end_dialog
3397 End use of dialog functions.
3398
3399 init_dialog
3400 Do some initialization for dialog.
3401
3402 FILE *input
3403 is the real tty input of dialog. Usually it is the standard
3404 input, but if --input-fd option is used, it may be anything.
3405
3406 FILE *output
3407 is where dialog will send its result. Usually it is the standard
3408 error, but if --stdout or --output-fd is used, it may be anything.
3409
3411 dialog (1).
3412
3414 Thomas E. Dickey
3415
3416
3417
3418$Date: 2019/12/09 10:04:31 $ DIALOG(3)