1DIALOG(3) Library Functions Manual DIALOG(3)
2
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 #include <dialog.h>
14 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 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 Useful character constants which correspond to user input are named
45 with the "CHR_" prefix, e.g., CHR_BACKSPACE.
46 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 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 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 .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 .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 .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 .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 .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 .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 .no_mouse
112 This corresponds to the command-line option "--no-mouse". If true,
113 dialog will not initialize (and enable) the mouse in init_dialog.
114 .output
116 This is set in the dialog application to the stream on which the appli‐
117 cation and library functions may write text results. Normally that is
118 the standard error, since the curses library prefers to write its data
119 to the standard output. Some scripts, trading portability for conve‐
120 nience, prefer to write results to the standard output, e.g., by using
121 the "--stdout" option.
122 .output_count
124 This is incremented by dlg_does_output, which is called by each widget
125 that writes text to the output. The dialog application uses that to
126 decide if it should also write a separator, i.e., DIALOG_STATE.sepa‐
127 rate_str, between calls to each widget.
128 .pipe_input
130 This is set in init_dialog to a stream which can be used by the gauge
131 widget, which must be the application's standard input. The dialog
132 application calls init_dialog normally with input set to the standard
133 input, but optionally based on the "--input-fd" option. Since the
134 application cannot read from a pipe (standard input) and at the same
135 time read the curses input from the standard input, it must allow for
136 reopening the latter from either a specific file descriptor, or
137 directly from the terminal. The adjusted pipe stream value is stored
138 in this variable.
139 .screen_initialized
141 This is set in init_dialog and reset in end_dialog. It is used to
142 check if curses has been initialized, and if the endwin function must
143 be called on exit.
144 .screen_output
146 This is set in init_dialog to the output stream used by the curses
147 library. Normally that is the standard output, unless that happens to
148 not be a terminal (and if init_dialog can successfully open the termi‐
149 nal directly).
150 .separate_str
152 This corresponds to the command-line option "--separate-widget". The
153 given string specifies a string that will separate the output on dia‐
154 log's output from each widget. This is used to simplify parsing the
155 result of a dialog with several widgets. If this option is not given,
156 the default separator string is a tab character.
157 .tab_len
159 This corresponds to the command-line option "--tab-len number". Spec‐
160 ify the number of spaces that a tab character occupies if the "--tab-
161 correct" option is given. The default is 8.
162 .text_height
164 This text-formatting functions set this to the number of lines used for
165 formatting a string.
166 It is used by dialog for the command-line options "--print-text-size"
168 and "--print-text-only".
169 .text_only
171 Dialog uses this in the command-line option "--print-text-only".
172 The text-formatting functions (dlg_print_text, dlg_print_line, and
174 dlg_print_autowrap) check this to decide whether to print the formatted
175 text to dialog's output or to the curses-display.
176 Also, dlg_auto_size checks the flag, allowing it to be used before
178 init_dialog is called.
179 .text_width
181 This text-formatting functions set this to the number of columns used
182 for formatting a string.
183 It is used by dialog for the command-line options "--print-text-size"
185 and "--print-text-only".
186 .trace_output
188 This corresponds to the command-line option "--trace file". It is the
189 file pointer to which trace messages are written.
190 .use_colors
192 This is set in init_dialog if the curses implementation supports color.
193 .use_scrollbar
195 This corresponds to the command-line option "--scrollbar". If true,
196 draw a scrollbar to make windows holding scrolled data more readable.
197 .use_shadow
199 This corresponds to the command-line option "--no-shadow". This is set
200 in init_dialog if the curses implementation supports color. If true,
201 suppress shadows that would be drawn to the right and bottom of each
202 dialog box.
203 .visit_items
205 This corresponds to the command-line option "--visit-items". Modify
206 the tab-traversal of the list-oriented widgets (buildlist, checklist,
207 radiobox, menubox, inputmenu, and treeview) to include the list of
208 items as one of the states. This is useful as a visual aid, i.e., the
209 cursor position helps some users.
210 The dialog application resets the dialog_vars data before accepting
212 options to invoke each widget. Most of the DIALOG_VARS members are set
213 directly from dialog's command-line options:
214
216 In contrast to DIALOG_STATE, the members of DIALOG_VARS are set by com‐
217 mand-line options in dialog.
218 .ascii_lines
220 This corresponds to the command-line option "--ascii-lines. It causes
221 line-drawing to be done with ASCII characters, e.g., "+" and "-". See
222 DIALOG_VARS.no_lines.
223 .backtitle
225 This corresponds to the command-line option "--backtitle backtitle".
226 It specifies a backtitle string to be displayed on the backdrop, at the
227 top of the screen.
228 .beep_after_signal
230 This corresponds to the command-line option "--beep-after". If true,
231 beep after a user has completed a widget by pressing one of the but‐
232 tons.
233 .beep_signal
235 This corresponds to the command-line option "--beep". It is obsolete.
236 .begin_set
238 This is true if the command-line option "--begin y x" was used. It
239 specifies the position of the upper left corner of a dialog box on the
240 screen.
241 .begin_x
243 This corresponds to the x value from the command-line option "--begin y
244 x" (second value).
245 .begin_y
247 This corresponds to the y value from the command-line option "--begin y
248 x" (first value).
249 .cancel_label
251 This corresponds to the command-line option "--cancel-label string".
252 The given string overrides the label used for “Cancel” buttons.
253 .cant_kill
255 This corresponds to the command-line option "--no-kill". If true, this
256 tells dialog to put the tailboxbg box in the background, printing its
257 process id to dialog's output. SIGHUP is disabled for the background
258 process.
259 .colors
261 This corresponds to the command-line option "--colors". If true,
262 interpret embedded "\Z" sequences in the dialog text by the following
263 character, which tells dialog to set colors or video attributes: 0
264 through 7 are the ANSI codes used in curses: black, red, green, yellow,
265 blue, magenta, cyan and white respectively. Bold is set by 'b', reset
266 by 'B'. Reverse is set by 'r', reset by 'R'. Underline is set by 'u',
267 reset by 'U'. The settings are cumulative, e.g., "\Zb\Z1" makes the
268 following text bright red. Restore normal settings with "\Zn".
269 .column_separator
271 This corresponds to the command-line option "--column-separator". Dia‐
272 log splits data for radio/checkboxes and menus on the occurrences of
273 the given string, and aligns the split data into columns.
274 .cr_wrap
276 This corresponds to the command-line option "--cr-wrap". If true,
277 interpret embedded newlines in the dialog text as a newline on the
278 screen. Otherwise, dialog will only wrap lines where needed to fit
279 inside the text box. Even though you can control line breaks with
280 this, dialog will still wrap any lines that are too long for the width
281 of the box. Without cr-wrap, the layout of your text may be formatted
282 to look nice in the source code of your script without affecting the
283 way it will look in the dialog.
284 .date_format
286 This corresponds to the command-line option "--date-format string". If
287 the host provides strftime, and the value is nonnull, the calendar wid‐
288 get uses this to format its output.
289 .default_button
291 This is set by the command-line option "--default-button. It is used
292 by dlg_default_button.
293 .default_item
295 This corresponds to the command-line option "--default-item string".
296 The given string is used as the default item in a checklist, form or
297 menu box. Normally the first item in the box is the default.
298 .defaultno
300 This corresponds to the command-line option "--defaultno". If true,
301 make the default value of the yes/no box a No. Likewise, treat the
302 default button of widgets that provide “OK” and “Cancel” as a Cancel.
303 If --nocancel was given that option overrides this, making the default
304 button always “Yes” (internally the same as “OK”).
305 .dlg_clear_screen
307 This corresponds to the command-line option "--clear". This option is
308 implemented in the main program, not the library. If true, the screen
309 will be cleared on exit. This may be used alone, without other
310 options.
311 .exit_label
313 This corresponds to the command-line option "--exit-label string". The
314 given string overrides the label used for “EXIT” buttons.
315 .extra_button
317 This corresponds to the command-line option "--extra-button". If true,
318 some widgets show an extra button, between “OK” and “Cancel” buttons.
319 .extra_label
321 This corresponds to the command-line option "--extra-label string".
322 The given string overrides the label used for “Extra” buttons. Note:
323 for inputmenu widgets, this defaults to “Rename”.
324 .formitem_type
326 This is set by the command-line option "--passwordform" to tell the
327 form widget that its text fields should be treated like password wid‐
328 gets.
329 .help_button
331 This corresponds to the command-line option "--help-button". If true,
332 some widgets show a help-button after “OK” and “Cancel” buttons, i.e.,
333 in checklist, radiolist and menu boxes. If --item-help is also given,
334 on exit the return status will be the same as for the “OK” button, and
335 the item-help text will be written to dialog's output after the token
336 “HELP”. Otherwise, the return status will indicate that the Help but‐
337 ton was pressed, and no message printed.
338 .help_file
340 This corresponds to the command-line option "--hfile string". The
341 given filename is passed to dialog_helpfile when the user presses F1.
342 .help_label
344 This corresponds to the command-line option "--help-label string". The
345 given string overrides the label used for “Help” buttons.
346 .help_line
348 This corresponds to the command-line option "--hline string". The
349 given string is displayed in the bottom of dialog windows, like a sub‐
350 title.
351 .help_status
353 This corresponds to the command-line option "--help-status". If true,
354 and the the help-button is selected, writes the checklist or radiolist
355 information after the item-help “HELP” information. This can be used
356 to reconstruct the state of a checklist after processing the help
357 request.
358 .help_tags
360 This corresponds to the command-line option "--help-tags". If true,
361 dlg_add_help_formitem and dlg_add_help_listitem use the item's tag
362 value consistently rather than using the tag's help-text value when
363 DIALOG_VARS.item_help is set.
364 .input_length
366 This is nonzero if DIALOG_VARS.input_result is allocated, versus being
367 a pointer to the user's local variables.
368 .input_menu
370 This flag is set to denote whether the menubox widget implements a menu
371 versus a inputmenu widget.
372 .input_result
374 This may be either a user-supplied buffer, or a buffer dynamically
375 allocated by the library, depending on DIALOG_VARS.input_length:
376 · If DIALOG_VARS.input_length is zero, this is a pointer to user buf‐
378 fer (on the stack, or static). The buffer size is assumed to be
379 MAX_LEN, which is defined in <dialog.h>.
380 · When DIALOG_VARS.input_length is nonzero, this is a dynamically-
382 allocated buffer used by the widgets to return printable results to
383 the calling application.
384 Certain widgets copy a result to this buffer. If the pointer is NULL,
386 or if the length is insufficient for the result, then the dialog
387 library allocates a buffer which is large enough, and sets DIA‐
388 LOG_VARS.input_length. Callers should check for this case if they have
389 supplied their own buffer.
390 .insecure
392 This corresponds to the command-line option "--insecure". If true,
393 make the password widget friendlier but less secure, by echoing aster‐
394 isks for each character.
395 .in_helpfile
397 This variable is used to prevent dialog_helpfile from showing anything,
398 e.g., if F1 were pressed within a help-file display.
399 .iso_week
401 This corresponds to the command-line option "--iso-week". It is used
402 in the calendar widget to tell how to compute the starting week for the
403 year:
404 · by default, the calendar treats January 1 as the first week of the
406 year.
407 · If this variable is true, the calendar uses ISO 8601's convention.
409 ISO 8601 numbers weeks starting with the first week in January with
410 a Thursday in the current year. January 1 may be in the previous
411 year.
412 .item_help
414 This corresponds to the command-line option "--item-help". If true,
415 interpret the tags data for checklist, radiolist and menu boxes adding
416 a column whose text is displayed in the bottom line of the screen, for
417 the currently selected item.
418 .keep_tite
420 This is set by the command-line option "--keep-tite" to tell dialog to
421 not attempt to cancel the terminal initialization (termcap ti/te)
422 sequences which correspond to xterm's alternate-screen switching. Nor‐
423 mally dialog does this to avoid flickering when run several times in a
424 script.
425 .keep_window
427 This corresponds to the command-line option "--keep-window". If true,
428 do not remove/repaint the window on exit. This is useful for keeping
429 the window contents visible when several widgets are run in the same
430 process. Note that curses will clear the screen when starting a new
431 process.
432 .last_key
434 This corresponds to the command-line option "--last-key".
435 .max_input
437 This corresponds to the command-line option "--max-input size". Limit
438 input strings to the given size. If not specified, the limit is 2048.
439 .no_items
441 This corresponds to the command-line option "--no-items". Some widgets
442 (checklist, inputmenu, radiolist, menu) display a list with two columns
443 (a “tag” and “item”, i.e., “description”). This tells dialog to read
444 shorter rows from data, omitting the “list”.
445 .no_label
447 This corresponds to the command-line option "--no-label string". The
448 given string overrides the label used for “No” buttons.
449 .no_lines
451 This corresponds to the command-line option "--no-lines. It suppresses
452 line-drawing. See DIALOG_VARS.ascii_lines.
453 .no_nl_expand
455 This corresponds to the command-line option "--no-nl-expand". If
456 false, dlg_trim_string converts literal "\n" substrings in a message
457 into newlines.
458 .no_tags
460 This corresponds to the command-line option "--no-tags". Some widgets
461 (checklist, inputmenu, radiolist, menu) display a list with two columns
462 (a “tag” and “item”, also known as “description”). The tag is useful
463 for scripting, but may not help the user. The --no-tags option (from
464 Xdialog) may be used to suppress the column of tags from the display.
465 Normally dialog allows you to quickly move to entries on the displayed
467 list, by matching a single character to the first character of the tag.
468 When the --no-tags option is given, dialog matches against the first
469 character of the description. In either case, the matchable character
470 is highlighted.
471 Here is a table showing how the no_tags and no_items values interact:
473 Widget Fields Shown Fields Read .no_items .no_tags
475 ──────────────────────────────────────────────────────────────
476 buildlist item tag,item 0 0*
477 buildlist item tag,item 0 1
478 buildlist tag tag 1 0*
479 buildlist tag tag 1 1
480 checklist tag,item tag,item 0 0
481 checklist item tag,item 0 1
482 checklist tag tag 1 0
483 checklist tag tag 1 1
484 inputmenu tag,item tag,item 0 0
485 inputmenu item tag,item 0 1
486 inputmenu tag tag 1 0
487 inputmenu tag tag 1 1
488 menu tag,item tag,item 0 0
489 menu item tag,item 0 1
490 menu tag tag 1 0
491 menu tag tag 1 1
492 radiolist tag,item tag,item 0 0
493 radiolist item tag,item 0 1
494 radiolist tag tag 1 0
495 radiolist tag tag 1 1
496 treeview item tag,item 0 0*
497 treeview item tag,item 0 1
498 treeview tag tag 1 0*
499 treeview tag tag 1 1
500 ──────────────────────────────────────────────────────────────
501 * Xdialog does not display the tag column for the analogous buildlist
503 and treeview widgets. Dialog does the same on the command-line.
504 However the library interface defaults to displaying the tag column.
505 Your application can enable or disable the tag column as needed for
506 each widget.
507 .nocancel
509 This corresponds to the command-line option "--no-cancel". If true,
510 suppress the “Cancel” button in checklist, inputbox and menu box modes.
511 A script can still test if the user pressed the ESC key to cancel to
512 quit.
513 .nocollapse
515 This corresponds to the command-line option "--no-collapse". Normally
516 dialog converts tabs to spaces and reduces multiple spaces to a single
517 space for text which is displayed in a message boxes, etc. It true,
518 that feature is disabled. Note that dialog will still wrap text, sub‐
519 ject to the --cr-wrap option.
520 .nook
522 This corresponds to the command-line option "--nook. Dialog will sup‐
523 press the “ok” (or “yes”) button from the widget.
524 .ok_label
526 This corresponds to the command-line option "--ok-label string". The
527 given string overrides the label used for “OK” buttons.
528 .print_siz
530 This corresponds to the command-line option "--print-size". If true,
531 each widget prints its size to dialog's output when it is invoked.
532 .quoted
534 This corresponds to the command-line option "--quoted. Normally dialog
535 quotes the strings returned by checklist's as well as the item-help
536 text. If true, dialog will quote all string results.
537 .reorder
539 This corresponds to the command-line option "--reorder. By default,
540 the buildlist widget uses the same order for the output (right) list as
541 for the input (left). If true, dialog will use the order in which a
542 user adds selections to the output list.
543 .separate_output
545 This corresponds to the command-line option "--separate-output". If
546 true, checklist widgets output result one line at a time, with no quot‐
547 ing. This facilitates parsing by another program.
548 .single_quoted
550 This corresponds to the command-line option "--single-quoted". If
551 true, use single-quoting as needed (and no quotes if unneeded) for the
552 output of checklist's as well as the item-help text. If this option is
553 not set, dialog uses double quotes around each item. The latter
554 requires occasional use of backslashes to make the output useful in
555 shell scripts.
556 .size_err
558 This corresponds to the command-line option "--size-err". If true,
559 check the resulting size of a dialog box before trying to use it,
560 printing the resulting size if it is larger than the screen. (This
561 option is obsolete, since all new-window calls are checked).
562 .sleep_secs
564 This corresponds to the command-line option "--sleep secs". This
565 option is implemented in the main program, not the library. If
566 nonzero, this is the number of seconds after to delay after processing
567 a dialog box.
568 .tab_correct
570 This corresponds to the command-line option "--tab-correct". If true,
571 convert each tab character of the text to one or more spaces. Other‐
572 wise, tabs are rendered according to the curses library's interpreta‐
573 tion.
574 .time_format
576 This corresponds to the command-line option "--time-format string". If
577 the host provides strftime, and the value is nonnull, the timebox wid‐
578 get uses this to format its output.
579 .timeout_secs
581 This corresponds to the command-line option "--timeout secs". If
582 nonzero, timeout input requests (exit with error code) if no user
583 response within the given number of seconds.
584 .title
586 This corresponds to the command-line option "--title title". Specifies
587 a title string to be displayed at the top of the dialog box.
588 .trim_whitespace
590 This corresponds to the command-line option "--trim". If true, elimi‐
591 nate leading blanks, trim literal newlines and repeated blanks from
592 message text.
593 .week_start
595 This corresponds to the command-line option "--week-start". It is used
596 in the calendar widget to set the starting day for the week. The
597 string value can be
598 · a number (0 to 6, Sunday through Saturday using POSIX) or
600 · the special value “locale” (this works with systems using glibc,
602 providing an extension to the locale command, the first_weekday
603 value).
604 · a string matching one of the abbreviations for the day of the week
606 shown in the calendar widget, e.g., “Mo” for “Monday”.
607 .yes_label
609 This corresponds to the command-line option "--yes-label string". The
610 given string overrides the label used for “Yes” buttons.
611
613 Functions that implement major functionality for the command-line dia‐
614 log program, e.g., widgets, have names beginning "dialog_".
615 All dialog boxes have at least three parameters:
617 title
619 the caption for the box, shown on its top border.
620 height
622 the height of the dialog box.
623 width
625 the width of the dialog box.
626 Other parameters depend on the box type.
628 dialog_buildlist
630 implements the "--buildlist" option.
631 const char * title
633 is the title on the top of the widget.
634 const char * cprompt
636 is the prompt text shown within the widget.
637 int height
639 is the desired height of the box. If zero, the height is adjusted
640 to use the available screen size.
641 int width
643 is the desired width of the box. If zero, the height is adjusted
644 to use the available screen size.
645 int list_height
647 is the minimum height to reserve for displaying the list. If
648 zero, it is computed based on the given height and width.
649 int item_no
651 is the number of rows in items.
652 char ** items
654 is an array of strings which is viewed either as a list of rows
655 tag item status
656 or
658 tag item status help
659 depending on whether dialog_vars.item_help is set.
661 int order_mode
663 is reserved for future enhancements
664 dialog_calendar
666 implements the "--calendar" option.
667 const char * title
669 is the title on the top of the widget.
670 const char * subtitle
672 is the prompt text shown within the widget.
673 int height
675 is the height excluding the fixed-height calendar grid.
676 int width
678 is the overall width of the box, which is adjusted up to the cal‐
679 endar grid's minimum width if needed.
680 int day
682 is the initial day of the week shown, counting zero as Sunday. If
683 the value is negative, the current day of the week is used.
684 int month
686 is the initial month of the year shown, counting one as January.
687 If the value is negative, the current month of the year is used.
688 int year
690 is the initial year shown. If the value is negative, the current
691 year is used.
692 dialog_checklist
694 implements the "--checklist" and "--radiolist" options depending on the
695 flag parameter.
696 const char * title
698 is the title on the top of the widget.
699 const char * cprompt
701 is the prompt text shown within the widget.
702 int height
704 is the desired height of the box. If zero, the height is adjusted
705 to use the available screen size.
706 int width
708 is the desired width of the box. If zero, the height is adjusted
709 to use the available screen size.
710 int list_height
712 is the minimum height to reserve for displaying the list. If
713 zero, it is computed based on the given height and width.
714 int item_no
716 is the number of rows in items.
717 int items
719 is an array of strings which is viewed either as a list of rows
720 tag item status
721 or
723 tag item status help
724 depending on whether dialog_vars.item_help is set.
726 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for radi‐
728 olists.
729 dialog_dselect
731 implements the "--dselect" option.
732 const char * title
734 is the title on the top of the widget.
735 const char * path
737 is the preselected value to show in the input-box, which is used
738 also to set the directory- and file-windows.
739 int height
741 is the height excluding the minimum needed to show the dialog box
742 framework. If zero, the height is based on the screen size.
743 int width
745 is the desired width of the box. If zero, the height is based on
746 the screen size.
747 dialog_editbox
749 implements the "--editbox" option.
750 const char * title
752 is the title on the top of the widget.
753 const char * file
755 is the name of the file from which to read.
756 int height
758 is the desired height of the box. If zero, the height is adjusted
759 to use the available screen size.
760 int width
762 is the desired width of the box. If zero, the height is adjusted
763 to use the available screen size.
764 dialog_form
766 implements the "--form" option.
767 const char * title
769 is the title on the top of the widget.
770 const char * cprompt
772 is the prompt text shown within the widget.
773 int height
775 is the desired height of the box. If zero, the height is adjusted
776 to use the available screen size.
777 int width
779 is the desired width of the box. If zero, the height is adjusted
780 to use the available screen size.
781 int form_height
783 is the minimum height to reserve for displaying the list. If
784 zero, it is computed based on the given height and width.
785 int item_no
787 is the number of rows in items.
788 int items
790 is an array of strings which is viewed either as a list of rows
791 Name NameY NameX Text TextY TextX FLen ILen
792 or
794 Name NameY NameX Text TextY TextX FLen ILen Help
795 depending on whether dialog_vars.item_help is set.
797 dialog_fselect
799 implements the "--fselect" option.
800 const char * title
802 is the title on the top of the widget.
803 const char * path
805 is the preselected value to show in the input-box, which is used
806 also to set the directory- and file-windows.
807 int height
809 is the height excluding the minimum needed to show the dialog box
810 framework. If zero, the height is based on the screen size.
811 int width
813 is the desired width of the box. If zero, the height is based on
814 the screen size.
815 dialog_gauge
817 implements the "--gauge" option. Alternatively, a simpler or custom‐
818 ized gauge widget can be set up using dlg_allocate_gauge, dlg_reallo‐
819 cate_gauge, dlg_update_gauge and dlg_free_gauge.
820 const char * title
822 is the title on the top of the widget.
823 const char * cprompt
825 is the prompt text shown within the widget.
826 int height
828 is the desired height of the box. If zero, the height is based on
829 the screen size.
830 int width
832 is the desired width of the box. If zero, the height is based on
833 the screen size.
834 int percent
836 is the percentage to show in the progress bar.
837 dialog_inputbox
839 implements the "--inputbox" or "--password" option, depending on the
840 value of password.
841 const char * title
843 is the title on the top of the widget.
844 const char * cprompt
846 is the prompt text shown within the widget.
847 int height
849 is the desired height of the box. If zero, the height is based on
850 the screen size.
851 int width
853 is the desired width of the box. If zero, the height is based on
854 the screen size.
855 const char * init
857 is the initial value of the input box, whose length is taken into
858 account when auto-sizing the width of the dialog box.
859 int password
861 if true, causes typed input to be echoed as asterisks.
862 dialog_helpfile
864 implements the "--hfile" option.
865 const char * title
867 is the title on the top of the widget.
868 const char * file
870 is the name of a file containing the text to display. This func‐
871 tion is internally bound to F1 (function key “1”), passing dia‐
872 log_vars.help_file as a parameter. The dialog program sets that
873 variable when the --hfile option is given.
874 int height
876 is the desired height of the box. If zero, the height is based on
877 the screen size.
878 int width
880 is the desired width of the box. If zero, the height is based on
881 the screen size.
882 dialog_menu
884 implements the "--menu" or "--inputmenu" option depending on whether
885 dialog_vars.input_menu is set.
886 const char * title
888 is the title on the top of the widget.
889 const char * cprompt
891 is the prompt text shown within the widget.
892 int height
894 is the desired height of the box. If zero, the height is based on
895 the screen size.
896 int width
898 is the desired width of the box. If zero, the height is based on
899 the screen size.
900 int menu_height
902 is the minimum height to reserve for displaying the list. If
903 zero, it is computed based on the given height and width.
904 int item_no
906 is the number of rows in items.
907 int items
909 is an array of strings which is viewed either as a list of rows
910 tag item
911 or
913 tag item help
914 depending on whether dialog_vars.item_help is set.
916 dialog_mixedform
918 implements the "--mixedform" option.
919 const char * title
921 is the title on the top of the widget.
922 const char * cprompt
924 is the prompt text shown within the widget.
925 int height
927 is the desired height of the box. If zero, the height is adjusted
928 to use the available screen size.
929 int width
931 is the desired width of the box. If zero, the height is adjusted
932 to use the available screen size.
933 int form_height
935 is the minimum height to reserve for displaying the list. If
936 zero, it is computed based on the given height and width.
937 int item_no
939 is the number of rows in items.
940 int items
942 is an array of strings which is viewed either as a list of rows
943 Name NameY NameX Text TextY TextX FLen ILen Ityp
944 or
946 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
947 depending on whether dialog_vars.item_help is set.
949 dialog_mixedgauge
951 implements the "--mixedgauge" option
952 const char * title
954 is the title on the top of the widget.
955 const char * cprompt
957 is the caption text shown within the widget.
958 int height
960 is the desired height of the box. If zero, the height is based on
961 the screen size.
962 int width
964 is the desired width of the box. If zero, the height is based on
965 the screen size.
966 int percent
968 is the percentage to show in the progress bar.
969 int item_no
971 is the number of rows in items.
972 int items
974 is an array of strings which is viewed as a list of tag and item
975 values. The tag values are listed, one per row, in the list at
976 the top of the widget.
977 The item values are decoded: digits 0 through 9 are the following
979 strings
980 0 Succeeded
982 1 Failed
984 2 Passed
986 3 Completed
988 4 Checked
990 5 Done
992 6 Skipped
994 7 In Progress
996 8 (blank)
998 9 N/A
1000 A string with a leading "-" character is centered, marked with
1002 "%". For example, "-75" is displayed as "75%". Other strings are
1003 displayed as is.
1004 dialog_msgbox
1006 implements the "--msgbox" or "--infobox" option depending on whether
1007 pauseopt is set.
1008 const char * title
1010 is the title on the top of the widget.
1011 const char * cprompt
1013 is the prompt text shown within the widget.
1014 int height
1016 is the desired height of the box. If zero, the height is based on
1017 the screen size.
1018 int width
1020 is the desired width of the box. If zero, the height is based on
1021 the screen size.
1022 int pauseopt
1024 if true, an “OK” button will be shown, and the dialog will wait
1025 for it to complete. With an “OK” button, it is denoted a “msg‐
1026 box”, without an “OK” button, it is denoted an “infobox”.
1027 dialog_pause
1029 implements the "--pause" option.
1030 const char * title
1032 is the title on the top of the widget.
1033 int height
1035 is the desired height of the box. If zero, the height is based on
1036 the screen size.
1037 int width
1039 is the desired width of the box. If zero, the height is based on
1040 the screen size.
1041 int seconds
1043 is the timeout to use for the progress bar.
1044 dialog_prgbox
1046 implements the "--prgbox" option.
1047 const char * title
1049 is the title on the top of the widget.
1050 const char * cprompt
1052 is the prompt text shown within the widget. If empty or null, no
1053 prompt is shown.
1054 const char * command
1056 is the name of the command to execute.
1057 int height
1059 is the desired height of the box. If zero, the height is based on
1060 the screen size.
1061 int width
1063 is the desired width of the box. If zero, the height is based on
1064 the screen size.
1065 int pauseopt
1067 if true, an “OK” button will be shown, and the dialog will wait
1068 for it to complete.
1069 dialog_progressbox
1071 implements the "--progressbox" option.
1072 const char * title
1074 is the title on the top of the widget.
1075 const char * cprompt
1077 is the prompt text shown within the widget. If empty or null, no
1078 prompt is shown.
1079 int height
1081 is the desired height of the box. If zero, the height is based on
1082 the screen size.
1083 int width
1085 is the desired width of the box. If zero, the height is based on
1086 the screen size.
1087 dialog_rangebox
1089 implements the "--rangebox" option.
1090 const char * title
1092 is the title on the top of the widget.
1093 const char * cprompt
1095 is the prompt text shown within the widget. If empty or null, no
1096 prompt is shown.
1097 int height
1099 is the desired height of the widget. If zero, the height is based
1100 on the screen size.
1101 int width
1103 is the desired width of the widget. If zero, the height is based
1104 on the screen size.
1105 int min_value
1107 is the minimum value to allow.
1108 int max_value
1110 is the maximum value to allow.
1111 int default_value
1113 is the default value, if no change is made.
1114 dialog_tailbox
1116 implements the "--tailbox" or "--tailboxbg" option depending on whether
1117 bg_task is set.
1118 const char * title
1120 is the title on the top of the widget.
1121 const char * file
1123 is the name of the file to display in the dialog.
1124 int height
1126 is the desired height of the box. If zero, the height is based on
1127 the screen size.
1128 int width
1130 is the desired width of the box. If zero, the height is based on
1131 the screen size.
1132 int bg_task
1134 if true, the window is added to the callback list in dialog_state,
1135 and the application will poll for the window to be updated. Oth‐
1136 erwise an “OK” button is added to the window, and it will be
1137 closed when the button is activated.
1138 dialog_textbox
1140 implements the "--textbox" option.
1141 const char * title
1143 is the title on the top of the widget.
1144 const char * file
1146 is the name of the file to display in the dialog.
1147 int height
1149 is the desired height of the box. If zero, the height is based on
1150 the screen size.
1151 int width
1153 is the desired width of the box. If zero, the height is based on
1154 the screen size.
1155 dialog_timebox
1157 implements the "--timebox" option.
1158 const char * title
1160 is the title on the top of the widget.
1161 const char * subtitle
1163 is the prompt text shown within the widget.
1164 int height
1166 is the desired height of the box. If zero, the height is based on
1167 the screen size.
1168 int width
1170 is the desired width of the box. If zero, the height is based on
1171 the screen size.
1172 int hour
1174 is the initial hour shown. If the value is negative, the current
1175 hour is used. Returns DLG_EXIT_ERROR if the value specified is
1176 greater than or equal to 24.
1177 int minute
1179 is the initial minute shown. If the value is negative, the cur‐
1180 rent minute is used. Returns DLG_EXIT_ERROR if the value speci‐
1181 fied is greater than or equal to 60.
1182 int second
1184 is the initial second shown. If the value is negative, the cur‐
1185 rent second is used. Returns DLG_EXIT_ERROR if the value speci‐
1186 fied is greater than or equal to 60.
1187 dialog_treeview
1189 implements the "--treeview" option.
1190 const char * title
1192 is the title on the top of the widget.
1193 const char * cprompt
1195 is the prompt text shown within the widget.
1196 int height
1198 is the desired height of the box. If zero, the height is based on
1199 the screen size.
1200 int width
1202 is the desired width of the box. If zero, the height is based on
1203 the screen size.
1204 int list_height
1206 is the minimum height to reserve for displaying the list. If
1207 zero, it is computed based on the given height and width.
1208 int item_no
1210 is the number of rows in items.
1211 char ** items
1213 is the list of items, contain tag, name, and optionally help
1214 strings (if dialog_vars.item_help is set). The initial selection
1215 state for each item is also in this list.
1216 int flag
1218 flag is either FLAG_CHECK, for checklists (multiple selections), or
1220 FLAG_RADIO for radiolists (a single selection).
1221 dialog_yesno
1223 implements the "--yesno" option.
1224 const char * title
1226 is the title on the top of the widget.
1227 const char * cprompt
1229 is the prompt text shown within the widget.
1230 int height
1232 is the desired height of the box. If zero, the height is based on
1233 the screen size.
1234 int width
1236 is the desired width of the box. If zero, the height is based on
1237 the screen size.
1238
1240 Most functions that implement lower-level functionality for the com‐
1241 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
1242 ing to longstanding usage, the functions that initialize the display
1243 and end it are named init_dialog and end_dialog.
1244 The only non-widget function whose name begins with "dialog_" is dia‐
1246 log_version, which returns the version number of the library as a
1247 string.
1248 Here is a brief summary of the utility functions and their parameters:
1250 dlg_add_callback
1252 Add a callback, used to allow polling input from multiple tailbox wid‐
1253 gets.
1254 DIALOG_CALLBACK *p
1256 contains the callback information.
1257 dlg_add_callback_ref
1259 Like dlg_add_callback, but passes a reference to the DIALOG_CALLBACK as
1260 well as a pointer to a cleanup function which will be called when the
1261 associated input ends.
1262 DIALOG_CALLBACK **p
1264 points to the callback information. This is a reference to the
1265 pointer so that the caller's pointer can be zeroed when input
1266 ends.
1267 DIALOG_FREEBACK func
1269 function to call when input ends, e.g., to free caller's addi‐
1270 tional data.
1271 dlg_add_help_formitem
1273 This is a utility function used enforce consistent behavior for the
1274 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1275 int *result
1277 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1278 set.
1279 char **tag
1281 the tag- or help-text is stored here.
1282 DIALOG_FORMITEM *item
1284 contains the list item to use for tag- or help-text.
1285 dlg_add_help_listitem
1287 This is a utility function used enforce consistent behavior for the
1288 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1289 int *result
1291 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1292 set.
1293 char **tag
1295 the tag- or help-text is stored here.
1296 DIALOG_LISTITEM *item
1298 contains the list item to use for tag- or help-text.
1299 dlg_add_last_key
1301 Report the last key entered by the user. This implements the --last-
1302 key command-line option, using dialog_vars.last_key.
1303 int mode
1305 controls the way the last key report is separated from other
1306 results:
1307 -2 (no separator)
1309 -1 (separator after the key name)
1311 0 (separator is optionally before the key name)
1313 1 (same as -1)
1315 dlg_add_quoted
1317 Add a quoted string to the result buffer (see dlg_add_result). If no
1318 quotes are necessary, none are used. If dialog_vars.single_quoted is
1319 set, single-quotes are used. Otherwise, double-quotes are used.
1320 char * string
1322 is the string to add.
1323 dlg_add_result
1325 Add a string to the result buffer dialog_vars.input_result.
1326 char * string
1328 is the string to add.
1329 dlg_add_separator
1331 Add an output-separator to the result buffer dialog_vars.input_result.
1332 If dialog_vars.output_separator is set, use that. Otherwise, if dia‐
1333 log_vars.separate_output is set, use newline. If neither is set, use a
1334 space.
1335 dlg_add_string
1337 Add a quoted or unquoted string to the result buffer (see
1338 dlg_add_quoted) and dlg_add_result), according to whether dia‐
1339 log_vars.quoted is true.
1340 char * string
1342 is the string to add.
1343 dlg_align_columns
1345 Copy and reformat an array of pointers to strings, aligning according
1346 to the column separator dialog_vars.column_separator. If no column
1347 separator is set, the array will be unmodified; otherwise it is copied
1348 and reformatted.
1349 Caveat: This function is only implemented for 8-bit characters.
1351 char **target
1353 This is the array to reformat. It points to the first string to
1354 modify.
1355 int per_row
1357 This is the size of the struct for each row of the array.
1358 int num_rows
1360 This is the number of rows in the array.
1361 dlg_allocate_gauge
1363 Allocates a gauge widget. Use dlg_update_gauge to display the result.
1364 const char * title
1366 is the title string to display at the top of the widget.
1367 const char * cprompt
1369 is the prompt text shown within the widget.
1370 int height
1372 is the desired height of the box. If zero, the height is adjusted
1373 to use the available screen size.
1374 int width
1376 is the desired width of the box. If zero, the height is adjusted
1377 to use the available screen size.
1378 int percent
1380 is the percentage to show in the progress bar.
1381 dlg_asciibox
1383 returns its parameter transformed to the corresponding "+" or "-",
1384 etc., for the line-drawing characters used in dialog. If the parameter
1385 is not a line-drawing or other special character such as ACS_DARROW, it
1386 returns 0.
1387 chtype ch
1389 is the parameter, usually one of the ACS_xxx constants.
1390 dlg_attr_clear
1392 Set window to the given attribute.
1393 WINDOW * win
1395 is the window to update.
1396 int height
1398 is the number of rows to update.
1399 int width
1401 is the number of columns to update.
1402 chtype attr
1404 is the attribute, e.g., A_BOLD.
1405 dlg_auto_size
1407 Compute window size based on the size of the formatted prompt and mini‐
1408 mum dimensions for a given widget.
1409 Dialog sets dialog_state.text_height and dialog_state.text_width for
1411 the formatted prompt as a side-effect.
1412 Normally dialog writes the formatted prompt to the curses window, but
1414 it will write the formatted prompt to the output stream if dia‐
1415 log_state.text_only is set.
1416 const char * title
1418 is the title string to display at the top of the widget.
1419 const char * prompt
1421 is the message text which will be displayed in the widget, used
1422 here to determine how large the widget should be.
1423 If the value is NULL, dialog allows the widget to use the whole
1425 screen, i.e., if the values referenced by height and/or width are
1426 zero.
1427 int * height
1429 is the nominal height. Dialog checks the referenced value and may
1430 update it:
1431 · if the value is negative, dialog updates it to the available
1433 height of the screen, after reserving rows for the window bor‐
1434 der and shadow, as well as taking into account dia‐
1435 log_vars.begin_y and dialog_vars.begin_set.
1436 · if the value is zero, dialog updates it to the required height
1438 of the window, taking into account a (possibly) multi-line
1439 prompt.
1440 · if the value is greater than zero, dialog uses it internally,
1442 but restores the value on return.
1443 int * width
1445 is the nominal width. Dialog checks the referenced value and may
1446 update it:
1447 · if the value is negative, dialog updates it to the available
1449 width of the screen, after reserving rows for the window bor‐
1450 der and shadow, as well as taking into account dia‐
1451 log_vars.begin_x and dialog_vars.begin_set.
1452 · if the value is zero, dialog updates it to the required width
1454 of the window, taking into account a (possibly) multi-line
1455 prompt.
1456 · if the value is greater than zero, dialog uses it internally,
1458 but restores the value on return.
1459 int boxlines
1461 is the number of lines to reserve in the vertical direction.
1462 int mincols
1464 is the minimum number of columns to use.
1465 dlg_auto_sizefile
1467 Like dlg_auto_size, but use a file contents to decide how large the
1468 widget should be.
1469 const char * title
1471 is the title string to display at the top of the widget.
1472 const char * file
1474 is the name of the file.
1475 int * height
1477 is the nominal height.
1478 If it is -1, use the screen's height (after subtracting dia‐
1480 log_vars.begin_y if dialog_vars.begin_set is true).
1481 If it is greater than zero, limit the referenced value to the
1483 screen-height after verifying that the file exists.
1484 int * width
1486 is the nominal width.
1487 If it is -1, use the screen's width (after subtracting dia‐
1489 log_vars.begin_x if dialog_vars.begin_set is true).
1490 If it is greater than zero, limit the referenced value to the
1492 screen-width after verifying that the file exists.
1493 int boxlines
1495 is the number of lines to reserve on the screen for drawing boxes.
1496 int mincols
1498 is the number of columns to reserve on the screen for drawing
1499 boxes.
1500 dlg_beeping
1502 If dialog_vars.beep_signal is nonzero, this calls beep once and sets
1503 dialog_vars.beep_signal to zero.
1504 dlg_boxchar
1506 returns its chtype parameter transformed as follows:
1507 · if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is set.
1509 · if dialog_vars.ascii_lines is set, returns the corresponding "+" or
1511 "-", etc., for the line-drawing characters used in dialog.
1512 · otherwise, if dialog_vars.no_lines is set, returns a space for the
1514 line-drawing characters.
1515 · if the parameter is not a line-drawing or other special character
1517 such as ACS_DARROW, it returns the parameter unchanged.
1518 dlg_box_x_ordinate
1520 returns a suitable x-ordinate (column) for a new widget. If dia‐
1521 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center the
1522 widget on the screen (using the width parameter).
1523 int width
1525 is the width of the widget.
1526 dlg_box_y_ordinate
1528 returns a suitable y-ordinate (row) for a new widget. If dia‐
1529 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center the
1530 widget on the screen (using the height parameter).
1531 int height
1533 is the height of the widget.
1534 dlg_buildlist
1536 This is an alternate interface to the buildlist widget which allows the
1537 application to read the list item states back directly without putting
1538 them in the output buffer.
1539 const char * title
1541 is the title string to display at the top of the widget.
1542 const char * cprompt
1544 is the prompt text shown within the widget.
1545 int height
1547 is the desired height of the box. If zero, the height is adjusted
1548 to use the available screen size.
1549 int width
1551 is the desired width of the box. If zero, the height is adjusted
1552 to use the available screen size.
1553 int list_height
1555 is the minimum height to reserve for displaying the list. If
1556 zero, it is computed based on the given height and width.
1557 int item_no
1559 is the number of rows in items.
1560 DIALOG_LISTITEM * items
1562 is the list of items, contain tag, name, and optionally help
1563 strings (if dialog_vars.item_help is set). The initial selection
1564 state for each item is also in this list.
1565 const char * states
1567 This is a list of characters to display for the given states.
1568 Normally a buildlist provides true (1) and false (0) values, which
1569 the widget displays as "*" and space, respectively. An applica‐
1570 tion may set this parameter to an arbitrary null-terminated
1571 string. The widget determines the number of states from the
1572 length of this string, and will cycle through the corresponding
1573 display characters as the user presses the space-bar.
1574 int order_mode
1576 is reserved for future enhancements
1577 int * current_item
1579 The widget sets the referenced location to the index of the cur‐
1580 rent display item (cursor) when it returns.
1581 dlg_button_count
1583 Count the buttons in the list.
1584 const char ** labels
1586 is a list of (pointers to) button labels terminated by a null
1587 pointer.
1588 dlg_button_layout
1590 Make sure there is enough space for the buttons by computing the width
1591 required for their labels, adding margins and limiting based on the
1592 screen size.
1593 const char ** labels
1595 is a list of (pointers to) button labels terminated by a null
1596 pointer.
1597 int * limit
1599 the function sets the referenced limit to the width required for
1600 the buttons (limited by the screen size) if that is wider than the
1601 passed-in limit.
1602 dlg_button_sizes
1604 Compute the size of the button array in columns.
1605 const char ** labels
1607 is a list of (pointers to) button labels terminated by a null
1608 pointer.
1609 int vertical
1611 is true if the buttons are arranged in a column rather than a row.
1612 int * longest
1614 Return the total number of columns in the referenced location.
1615 int * length
1617 Return the longest button's columns in the referenced location.
1618 dlg_button_to_char
1620 Find the first uppercase character in the label, which we may use for
1621 an abbreviation. If the label is empty, return -1. If no uppercase
1622 character is found, return 0. Otherwise return the uppercase charac‐
1623 ter.
1624 Normally dlg_draw_buttons and dlg_char_to_button use the first upper‐
1626 case character. However, they keep track of all of the labels and if
1627 the first has already been used in another label, they will continue
1628 looking for another uppercase character. This function does not have
1629 enough information to make that check.
1630 const char * label
1632 is the label to test.
1633 dlg_button_x_step
1635 Compute the step-size needed between elements of the button array.
1636 const char ** labels
1638 is a list of (pointers to) button labels terminated by a null
1639 pointer.
1640 int limit
1642 is the maximum number of columns to allow for the buttons.
1643 int * gap
1645 store the nominal gap between buttons in the referenced location.
1646 This is constrained to be at least one.
1647 int * margin
1649 store the left+right total margins (for the list of buttons) in
1650 the referenced location.
1651 int * step
1653 store the step-size in the referenced location.
1654 dlg_calc_list_width
1656 Calculate the minimum width for the list, assuming none of the items
1657 are truncated.
1658 int item_no
1660 is the number of items.
1661 DIALOG_LISTITEM * items
1663 contains a name and text field, e.g., for checklists or radiobox
1664 lists. The function returns the sum of the widest columns needed
1665 for of each of these fields.
1666 If dialog_vars.no_items is set, the text fields in the list are
1668 ignored.
1669 dlg_calc_listh
1671 Calculate new height and list_height values.
1672 int * height
1674 on input, is the height without adding the list-height. On
1675 return, this contains the total list-height and is the actual wid‐
1676 get's height.
1677 int * list_height
1679 on input, is the requested list-height. On return, this contains
1680 the number of rows available for displaying the list after taking
1681 into account the screen size and the dialog_vars.begin_set and
1682 dialog_vars.begin_y variables.
1683 int item_no
1685 is the number of items in the list.
1686 dlg_calc_listw
1688 This function is obsolete, provided for library-compatibility. It is
1689 replaced by dlg_calc_list_width.
1690 int item_no
1692 is the number of items.
1693 char ** items
1695 is a list of character pointers.
1696 int group
1698 is the number of items in each group, e.g., the second array
1699 index.
1700 dlg_char_to_button
1702 Given a list of button labels, and a character which may be the abbre‐
1703 viation for one, find it, if it exists. An abbreviation will be the
1704 first character which happens to be capitalized in the label. If the
1705 character is found, return its index within the list of labels. Other‐
1706 wise, return DLG_EXIT_UNKNOWN.
1707 int ch
1709 is the character to find.
1710 const char ** labels
1712 is a list of (pointers to) button labels terminated by a null
1713 pointer.
1714 dlg_checklist
1716 This entrypoint provides the --checklist or --radiolist functionality
1717 without the limitations of dialog's command-line syntax (compare to
1718 dialog_checklist).
1719 const char * title
1721 is the title string to display at the top of the widget.
1722 const char * cprompt
1724 is the prompt text shown within the widget.
1725 int height
1727 is the desired height of the box. If zero, the height is adjusted
1728 to use the available screen size.
1729 int width
1731 is the desired width of the box. If zero, the height is adjusted
1732 to use the available screen size.
1733 int list_height
1735 is the minimum height to reserve for displaying the list. If
1736 zero, it is computed based on the given height and width.
1737 int item_no
1739 is the number of items.
1740 DIALOG_LISTITEM * items
1742 This is a list of the items to display in the checklist.
1743 const char * states
1745 This is a list of characters to display for the given states.
1746 Normally a checklist provides true (1) and false (0) values, which
1747 the widget displays as "*" and space, respectively. An applica‐
1748 tion may set this parameter to an arbitrary null-terminated
1749 string. The widget determines the number of states from the
1750 length of this string, and will cycle through the corresponding
1751 display characters as the user presses the space-bar.
1752 int flag
1754 This is should be one of FLAG_CHECK or FLAG_RADIO, depending on
1755 whether the widget should act as a checklist or radiobox.
1756 int * current_item
1758 The widget sets the referenced location to the index of the cur‐
1759 rent display item (cursor) when it returns.
1760 dlg_check_scrolled
1762 given a function key (or other key that was mapped to a function key),
1763 check if it is one of the up/down scrolling functions:
1764 DLGK_PAGE_FIRST,
1766 DLGK_PAGE_LAST,
1767 DLGK_GRID_UP,
1768 DLGK_GRID_DOWN,
1769 DLGK_PAGE_PREV or
1770 DLGK_PAGE_NEXT.
1771 Some widgets use these key bindings for scrolling the prompt-text up
1773 and down, to allow for display in very small windows.
1774 The function returns 0 (zero) if it finds one of these keys, and -1 if
1776 not.
1777 int key
1779 is the function-key to check
1780 int last
1782 is the number of lines which would be used to display the scrolled
1783 prompt in an arbitrarily tall window. It is used here to check
1784 limits for the offset value.
1785 int page
1787 this is the available height for writing scrolled text, which is
1788 smaller than the window if it contains buttons.
1789 bool * show
1791 on return, holds TRUE if dlg_print_scrolled should be used to
1792 redisplay the prompt text.
1793 int * offset
1795 on entry, holds the starting line number (counting from zero) last
1796 used for dlg_print_scrolled. On return, holds the updated start‐
1797 ing line number.
1798 dlg_clear
1800 Set window to the default dialog screen attribute. This is set in the
1801 rc-file with screen_color.
1802 dlg_clr_result
1804 Free storage used for the result buffer (dialog_vars.input_result).
1805 The corresponding pointer is set to NULL.
1806 dlg_color_count
1808 Return the number of colors that can be configured in dialog.
1809 dlg_color_setup
1811 Initialize the color pairs used in dialog.
1812 dlg_count_argv
1814 Count the entries in an argument vector.
1815 argv Points to the argument vector.
1817 dlg_count_columns
1819 Returns the number of columns used for a string. This is not necessar‐
1820 ily the number of bytes in a string.
1821 const char * string
1823 is the string to measure.
1824 dlg_count_real_columns
1826 Returns the number of columns used for a string, accounting for "\Z"
1827 sequences which can be used for coloring the text if dialog_vars.colors
1828 is set. This is not necessarily the number of bytes in a string.
1829 const char * string
1831 is the string to measure.
1832 dlg_count_wchars
1834 Returns the number of wide-characters in the string.
1835 const char * string
1837 is the string to measure.
1838 dlg_create_rc
1840 Create a configuration file, i.e., write internal tables to a file
1841 which can be read back by dialog as an rc-file.
1842 const char * filename
1844 is the name of the file to write to.
1845 dlg_ctl_size
1847 If dialog_vars.size_err is true, check if the given window size is too
1848 large to fit on the screen. If so, exit with an error reporting the
1849 size of the window.
1850 int height
1852 is the window's height
1853 int width
1855 is the window's width
1856 dlg_default_button
1858 If dialog_vars.default_button is positive, return the button-index for
1859 that button code, using dlg_ok_buttoncode to test indices starting with
1860 zero. Otherwise (or if no match was found for the button code), return
1861 zero.
1862 dlg_default_formitem
1864 If dialog_vars.default_item is not null, find that name by matching the
1865 name field in the list of form items. If found, return the index of
1866 that item in the list. Otherwise, return zero.
1867 DIALOG_FORMITEM * items
1869 is the list of items to search. It is terminated by an entry with
1870 a null name field.
1871 dlg_default_item
1873 This function is obsolete, provided for library-compatibility. It is
1874 replaced by dlg_default_formitem and dlg_default_listitem.
1875 char ** items
1877 is the list of items to search.
1878 int llen
1880 is the number of items in each group, e.g., the second array
1881 index.
1882 dlg_defaultno_button
1884 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not, find
1885 the button-index for the “Cancel” button. Otherwise, return the index
1886 for “OK” (always zero).
1887 dlg_del_window
1889 Remove a window, repainting everything else.
1890 WINDOW * win
1892 is the window to remove.
1893 dlg_does_output
1895 This is called each time a widget is invoked which may do output. It
1896 increments dialog_state.output_count, so the output function in dialog
1897 can test this and add a separator.
1898 dlg_draw_arrows
1900 Draw up/down arrows on a window, e.g., for scrollable lists. It calls
1901 dlg_draw_arrows2 using the menubox_color and menubox_border_color
1902 attributes.
1903 WINDOW * dialog
1905 is the window on which to draw an arrow.
1906 int top_arrow
1908 is true if an up-arrow should be drawn at the top of the window.
1909 int bottom_arrow
1911 is true if an down-arrow should be drawn at the bottom of the win‐
1912 dow.
1913 int x
1915 is the zero-based column within the window on which to draw
1916 arrows.
1917 int top
1919 is the zero-based row within the window on which to draw up-arrows
1920 as well as a horizontal line to show the window's top.
1921 int bottom
1923 is the zero-based row within the window on which to draw down-
1924 arrows as well as a horizontal line to show the window's bottom.
1925 dlg_draw_arrows2
1927 Draw up/down arrows on a window, e.g., for scrollable lists.
1928 WINDOW * dialog
1930 is the window on which to draw an arrow.
1931 int top_arrow
1933 is true if an up-arrow should be drawn at the top of the window.
1934 int bottom_arrow
1936 is true if an down-arrow should be drawn at the bottom of the win‐
1937 dow.
1938 int x
1940 is the zero-based column within the window on which to draw
1941 arrows.
1942 int top
1944 is the zero-based row within the window on which to draw up-arrows
1945 as well as a horizontal line to show the window's top.
1946 int bottom
1948 is the zero-based row within the window on which to draw down-
1949 arrows as well as a horizontal line to show the window's bottom.
1950 chtype attr
1952 is the window's background attribute.
1953 chtype borderattr
1955 is the window's border attribute.
1956 dlg_draw_bottom_box
1958 Draw a partial box at the bottom of a window, e.g., to surround a row
1959 of buttons. It is designed to merge with an existing box around the
1960 whole window (see dlg_draw_box), so it uses tee-elements rather than
1961 corner-elements on the top corners of this box.
1962 WINDOW * win
1964 is the window to update.
1965 dlg_draw_bottom_box2
1967 Draw a partial box at the bottom of a window, e.g., to surround a row
1968 of buttons. It is designed to merge with an existing box around the
1969 whole window (see dlg_draw_box2), so it uses tee-elements rather than
1970 corner-elements on the top corners of this box.
1971 WINDOW * win
1973 is the window to update.
1974 chtype on_left
1976 is used to color the upper/left edges of the box, i.e., the tee-
1977 element and horizontal line
1978 chtype on_right
1980 is used to color the right edge of the box, i.e., the tee-element
1981 chtype on_inside
1983 is used to fill-color the inside of the box
1984 dlg_draw_box
1986 Draw a rectangular box with line drawing characters.
1987 WINDOW * win
1989 is the window to update.
1990 int y
1992 is the top row of the box.
1993 int x
1995 is the left column of the box.
1996 int height
1998 is the height of the box.
1999 int width
2001 is the width of the box.
2002 chtype boxchar
2004 is used to color the right/lower edges. It also is fill-color
2005 used for the box contents.
2006 chtype borderchar
2008 is used to color the upper/left edges.
2009 dlg_draw_box2
2011 Draw a rectangular box with line drawing characters.
2012 WINDOW * win
2014 is the window to update.
2015 int y
2017 is the top row of the box.
2018 int x
2020 is the left column of the box.
2021 int height
2023 is the height of the box.
2024 int width
2026 is the width of the box.
2027 chtype boxchar
2029 is used to fill-color for the box contents.
2030 chtype borderchar
2032 is used to color the upper/left edges.
2033 chtype borderchar2
2035 is used to color the right/lower edges.
2036 dlg_draw_buttons
2038 Print a list of buttons at the given position.
2039 WINDOW * win
2041 is the window to update.
2042 int y
2044 is the starting row.
2045 int x
2047 is the starting column.
2048 const char ** labels
2050 is a list of (pointers to) button labels terminated by a null
2051 pointer.
2052 int selected
2054 is the index within the list of the selected button.
2055 int vertical
2057 is true if the buttons are arranged in a column rather than a row.
2058 int limit
2060 is the number of columns (or rows if vertical) allowed for the
2061 display.
2062 dlg_draw_helpline
2064 draw the text in dialog_vars.help_line at the bottom of the given win‐
2065 dow.
2066 WINDOW * dialog
2068 is the window to modify.
2069 bool decorations
2071 if true, allow room for the scrolling arrows.
2072 dlg_draw_scrollbar
2074 If dialog_state.use_scrollbar is set, draw a scrollbar on the right
2075 margin of windows holding scrollable data. Also (whether or not the
2076 scrollbar is drawn), annotate the bottom margin of the window with the
2077 percentage of data by the bottom of that window, and call
2078 dlg_draw_arrows2 to put markers on the window showing when more data is
2079 available.
2080 WINDOW * win
2082 is the window in which the data is scrolled. Because left, right,
2083 top, bottom are passed as parameters, this window can contain
2084 additional data.
2085 long first_data
2087 is the zero-based index to the first row of data in the current
2088 window.
2089 long this_data
2091 is the zero-based index to the current row of data.
2092 long next_data
2094 is the zero-based index to the next data after the current row.
2095 long total_data
2097 is the total number of rows of data.
2098 int left
2100 is the zero-based left margin/column of the window. The up/down
2101 arrows are draw inset by 5 columns from this point.
2102 int right
2104 is the zero-based right margin/column of the window. The scroll‐
2105 bar is drawn flush against this column.
2106 int top
2108 is the zero-based row within the window on which to draw up-arrows
2109 as well as a horizontal line to show the window's top.
2110 int bottom
2112 is the zero-based row within the window on which to draw down-
2113 arrows as well as a horizontal line to show the window's bottom.
2114 chtype attr
2116 is the window's background attribute.
2117 chtype borderattr
2119 is the window's border attribute.
2120 dlg_draw_shadow
2122 Draw shadows along the right and bottom edge of a window to give it a
2123 3-dimensional look. (The height, etc., may not be the same as the win‐
2124 dow's actual values).
2125 WINDOW * win
2127 is the window to update.
2128 int height
2130 is the height of the window.
2131 int width
2133 is the width of the window.
2134 int y
2136 is the top row of the window.
2137 int x
2139 is the left column of the window.
2140 dlg_draw_title
2142 Draw a title centered at the top of the window.
2143 WINDOW * win
2145 is the window to update.
2146 const char * title
2148 is the title string to display at the top of the widget.
2149 dlg_dummy_menutext
2151 This is a utility function which supports the --inputmenu option of the
2152 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
2153 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
2154 it passes dlg_dummy_menutext.
2155 The function should only return DLG_EXIT_ERROR.
2157 DIALOG_LISTITEM * items
2159 is the list of menu items
2160 int current
2162 is the index of the currently-selected item
2163 char * newtext
2165 is the updated text for the menu item
2166 dlg_dump_keys
2168 Write all user-defined key-bindings to the given stream, e.g., as part
2169 of dlg_create_rc.
2170 FILE * fp
2172 is the stream on which to write the bindings.
2173 dlg_dump_window_keys
2175 Write all user-defined key-bindings to the given stream, e.g., as part
2176 of dlg_create_rc.
2177 FILE * fp
2179 is the stream on which to write the bindings.
2180 WINDOW * win
2182 is the window for which bindings should be dumped. If it is null,
2183 then only built-in bindings are dumped.
2184 dlg_eat_argv
2186 Remove one or more items from an argument vector.
2187 int * argcp
2189 in/out parameter giving the length of the argument vector. char
2190 *** argvp in/out parameter pointing to the argument vector. int
2191 start starting index. int count number of arguments to remove.
2192 dlg_edit_offset
2194 Given the character-offset in the string, returns the display-offset
2195 where dialog should position the cursor. In this context, “characters”
2196 may be multicolumn, since the string can be a multibyte character
2197 string.
2198 char * string
2200 is the string to analyze
2201 int offset
2203 is the character-offset
2204 int x_last
2206 is a limit on the column positions that can be used, e.g., the
2207 window's size.
2208 dlg_edit_string
2210 Updates the string and character-offset, given various editing charac‐
2211 ters or literal characters which are inserted at the character-offset.
2212 Returns true if an editing change was made (and the display should be
2213 updated), and false if the key was something like KEY_ENTER, which is a
2214 non-editing action outside this function.
2215 char * string
2217 is the (multibyte) string to update
2218 int * offset
2220 is the character-offset
2221 int key
2223 is the editing key
2224 int fkey
2226 is true if the editing key is a function-key
2227 bool force
2229 is used in a special loop case by calling code to force the return
2230 value of this function when a function-key code 0 is passed in.
2231 dlg_exit
2233 Given an internal exit code, check if the corresponding environment
2234 variable is set. If so, remap the exit code to match the environment
2235 variable. Finally call exit with the resulting exit code.
2236 int code
2238 is the internal exit code, e.g., DLG_EXIT_OK, which may be
2239 remapped.
2240 The dialog program uses this function to allow shell scripts to remap
2242 the exit codes so they can distinguish ESC from ERROR.
2243 dlg_exit_buttoncode
2245 Map the given button index for dlg_exit_label into dialog's exit-code.
2246 int button
2248 is the button index
2249 dlg_exit_label
2251 Return a list of button labels. If dialog_vars.extra_button is true,
2252 return the result of dlg_ok_labels. Otherwise, return a list with the
2253 “Exit” label and (if dialog_vars.help_button is set) the “Help” button
2254 as well.
2255 dlg_exiterr
2257 Quit program killing all tailboxbg widgets.
2258 const char * fmt
2260 is the format of the printf-like message to write.
2261 ...
2263 are the variables to apply to the fmt format.
2264 dlg_find_index
2266 Given the character-offset to find in the list, return the correspond‐
2267 ing array index.
2268 const int *list
2270 contains a list of character-offsets, i.e., indices into a string
2271 that denote the beginning of multibyte characters.
2272 int limit
2274 is the last index into list to search.
2275 int to_find
2277 is the character-offset to find.
2278 dlg_finish_string
2280 If DIALOG_STATE.finish_string is true, this function discards data used
2281 to speed up layout computations.
2282 const char * string
2284 is the address of the string whose data should be discarded. The
2285 address rather than contents is used as the unique identifier
2286 because some of the caching is used for editable input-fields.
2287 dlg_flush_getc
2289 Cancel the local data saved by dlg_last_getc.
2290 dlg_editbox
2292 This entrypoint provides the --editbox functionality without the limi‐
2293 tations of dialog's command-line syntax (compare to dialog_editbox).
2294 const char * title
2296 is the title string to display at the top of the widget.
2297 char *** list
2299 is a pointer to an array of char * pointers. The array is allo‐
2300 cated by the caller, and so are the strings to which it points.
2301 The dlg_editbox function may reallocate the array and the strings.
2302 int * rows
2304 points to the nominal length of list. The referenced value is
2305 updated iflist is reallocated.
2306 int height
2308 is the desired height of the box. If zero, the height is adjusted
2309 to use the available screen size.
2310 int width
2312 is the desired width of the box. If zero, the height is adjusted
2313 to use the available screen size.
2314 dlg_form
2316 This entrypoint provides the --form functionality without the limita‐
2317 tions of dialog's command-line syntax (compare to dialog_form).
2318 const char * title
2320 is the title string to display at the top of the widget.
2321 const char * cprompt
2323 is the prompt text shown within the widget.
2324 int height
2326 is the desired height of the box. If zero, the height is adjusted
2327 to use the available screen size.
2328 int width
2330 is the desired width of the box. If zero, the height is adjusted
2331 to use the available screen size.
2332 int form_height
2334 is the minimum height to reserve for displaying the list. If
2335 zero, it is computed based on the given height and width.
2336 int item_no
2338 is the number of items.
2339 DIALOG_FORMITEM * items
2341 This is a list of the items to display in the form.
2342 int * current_item
2344 The widget sets the referenced location to the index of the cur‐
2345 rent display item (cursor) when it returns.
2346 dlg_free_columns
2348 Free data allocated by dlg_align_columns.
2349 char **target
2351 This is the array which was reformatted. It points to the first
2352 string to free.
2353 int per_row
2355 This is the size of the struct for each row of the array.
2356 int num_rows
2358 This is the number of rows in the array.
2359 dlg_free_formitems
2361 Free memory owned by a list of DIALOG_FORMITEM's.
2362 DIALOG_FORMITEM * items
2364 is the list to free.
2365 dlg_free_gauge
2367 Remove the gauge widget from the screen and free its associated memory.
2368 void *objptr
2370 points to the gauge widget.
2371 dlg_getc
2373 Read a character from the given window. Handle repainting here (to
2374 simplify things in the calling application). Also, if input-call‐
2375 back(s) are set up, poll the corresponding files and handle the
2376 updates, e.g., for displaying a tailbox. Returns the key-code.
2377 WINDOW * win
2379 is the window within which to read.
2380 int * fkey
2382 as a side-effect, set this to true if the key-code is really a
2383 function-key.
2384 dlg_get_attrs
2386 extract the video attributes from the given window.
2387 WINDOW * win
2389 is the window from which to get attributes.
2390 dlg_getc_callbacks
2392 passes the given key-code ch to the current window that has established
2393 a callback. If the callback returns zero, remove it and try the next
2394 window. If no more callbacks remain, return. If any callbacks were
2395 found, return true, otherwise false.
2396 int ch
2398 is the key-code
2399 int fkey
2401 is true if the key is a function-key
2402 int * result
2404 is used to pass an exit-code to the caller, which should pass that
2405 via dlg_exit.
2406 dlg_index_columns
2408 Build a list of the display-columns for the given multibyte string's
2409 characters.
2410 const char * string
2412 is the string to analyze
2413 dlg_index_wchars
2415 Build an index of the wide-characters in the string, so the caller can
2416 easily tell which byte-offset begins a given wide-character.
2417 const char * string
2419 is the string to analyze
2420 dlg_item_help
2422 Draw the string for the dialog_vars.item_help feature.
2423 const char * txt
2425 is the help-message
2426 dlg_killall_bg
2428 If dialog has callbacks active, purge the list of all that are not
2429 marked to keep in the background. If any remain, run those in a back‐
2430 ground process.
2431 int * retval
2433 stores the exit-code to pass back to the caller.
2434 dlg_last_getc
2436 returns the most recent character that was read via dlg_getc.
2437 dlg_limit_columns
2439 Given a column limit, count the number of wide characters that can fit
2440 into that limit. The offset is used to skip over a leading character
2441 that was already written.
2442 const char * string
2444 is the string to analyze
2445 int limit
2447 is the column limit
2448 int offset
2450 is the starting offset from which analysis should continue
2451 dlg_lookup_key
2453 Check for a key-binding. If there is no binding associated with the
2454 widget, it simply returns the given curses-key. Otherwise, it returns
2455 the result of the binding
2456 WINDOW * win
2458 is the window on which the binding is checked
2459 int curses_key
2461 is the curses key-code
2462 int * dialog_key
2464 is the corresponding dialog internal code (see DLG_KEYS_ENUM in
2465 dlg_key.h).
2466 dlg_max_input
2468 Limit the parameter according to dialog_vars.max_input
2469 int max_len
2471 is the value to limit
2472 dlg_match_char
2474 Match a given character against the beginning of the string, ignoring
2475 case of the given character. The matching string must begin with an
2476 uppercase character.
2477 int ch
2479 is the character to check
2480 const char * string
2482 is the string to search
2483 dlg_menu
2485 This entrypoint provides the --menu functionality without the limita‐
2486 tions of dialog's command-line syntax (compare to dialog_menu).
2487 const char * title
2489 is the title string to display at the top of the widget.
2490 const char * cprompt
2492 is the prompt text shown within the widget.
2493 int height
2495 is the desired height of the box. If zero, the height is adjusted
2496 to use the available screen size.
2497 int width
2499 is the desired width of the box. If zero, the height is adjusted
2500 to use the available screen size.
2501 int menu_height
2503 is the minimum height to reserve for displaying the list. If
2504 zero, it is computed based on the given height and width.
2505 int item_no
2507 is the number of items.
2508 DIALOG_LISTITEM * items
2510 This is a list of the items to display in the form.
2511 int * current_item
2513 The widget sets the referenced location to the index of the cur‐
2514 rent display item (cursor) when it returns.
2515 DIALOG_INPUTMENU rename_menutext
2517 If this is not dlg_dummy_menutext, the widget acts like an input‐
2518 menu widget, providing an extra “Rename” button, which activates
2519 an edit feature on the selected menu item.
2520 dlg_move_window
2522 Moves/resizes the given window to the given position and size.
2523 WINDOW *win
2525 is the window to move/resize.
2526 WINDOW *height
2528 is the height of the resized window.
2529 WINDOW *width
2531 is the width of the resized window.
2532 WINDOW *y
2534 y-ordinate to use for the repositioned window.
2535 WINDOW *x
2537 x-ordinate to use for the repositioned window.
2538 dlg_mouse_bigregion
2540 Retrieve the big-region under the pointer.
2541 int y
2543 is the row on which the mouse click occurred
2544 int x
2546 is the column on which the mouse click occurred
2547 dlg_mouse_free_regions
2549 Free the memory associated with mouse regions.
2550 dlg_mouse_mkbigregion
2552 Creates a region on which the mouse-clicks will return a specified
2553 code.
2554 int y
2556 is the top-row of the region.
2557 int x
2559 is the left-column of the region.
2560 int height
2562 is the height of the region.
2563 int width
2565 is the width of the region.
2566 int code
2568 is a code used to make the region unique within a widget
2569 int step_x
2571 is used in modes 2 (columns) and 3 (cells) to determine the width
2572 of a column/cell.
2573 int step_y
2575 is currently unused
2576 int mode
2578 is used to determine how the mouse position is translated into a
2579 code (like a function-key):
2580 1 index by lines
2582 2 index by columns
2584 3 index by cells
2586 dlg_mouse_mkregion
2588 int y
2589 is the top-row of the region.
2590 int x
2592 is the left-column of the region.
2593 int height
2595 is the height of the region.
2596 int width
2598 is the width of the region.
2599 int code
2601 is a code used to make the region unique within a widget
2602 dlg_mouse_region
2604 Retrieve the frame under the mouse pointer
2605 int y
2607 is the row of the mouse-click
2608 int x
2610 is the column of the mouse-click
2611 dlg_mouse_setbase
2613 Sets a base for subsequent calls to dlg_mouse_mkregion, so they can
2614 make regions relative to the start of a given window.
2615 int x
2617 is the left-column for the base
2618 int y
2620 is the top-row for the base
2621 dlg_mouse_setcode
2623 Sets a value used internally by dlg_mouse_mkregion which is added to
2624 the code parameter. By providing different values, e.g., multiples of
2625 KEY_MAX, it is possible to support multiple “big” regions in a widget.
2626 The buildlist widget uses this feature to recognize mouse-clicks in the
2627 left/right panes.
2628 int code
2630 is the value to add to dlg_mouse_mkregion's code parameter.
2631 dlg_mouse_wgetch
2633 is a wrapper for dlg_getc which additionally maps mouse-clicks (if the
2634 curses library supports those) into extended function-keys which encode
2635 the position according to the mode in dlg_mouse_mkbigregion. Returns
2636 the corresponding key-code.
2637 WINDOW * win
2639 is the window on which to perform the input
2640 int * fkey
2642 the referenced location is set to true if the key-code is an
2643 actual or extended (mouse) function-key.
2644 dlg_mouse_wgetch_nowait
2646 This is a non-blocking variant of dlg_mouse_wgetch.
2647 WINDOW * win
2649 is the window on which to perform the input
2650 int * fkey
2652 the referenced location is set to true if the key-code is an
2653 actual or extended (mouse) function-key.
2654 dlg_need_separator
2656 Check if an output-separator is needed. If dialog_vars.output_separa‐
2657 tor is set, return true. Otherwise, if dialog_vars.input_result is
2658 nonempty, return true. If neither, return false.
2659 dlg_new_modal_window
2661 Create a modal window, optionally with a shadow. The shadow is created
2662 if dialog_state.use_shadow is true.
2663 WINDOW * parent
2665 is the parent window (usually the top-level window of a widget)
2666 int height
2668 is the window's height
2669 int width
2671 is the window's width
2672 int y
2674 is the window's top-row
2675 int x
2677 is the window's left-column
2678 dlg_new_window
2680 Create a window, optionally with a shadow. The shadow is created if
2681 dialog_state.use_shadow is true.
2682 int height
2684 is the window's height
2685 int width
2687 is the window's width
2688 int y
2690 is the window's top-row
2691 int x
2693 is the window's left-column
2694 dlg_next_button
2696 Return the next index in the list of labels.
2697 const char ** labels
2699 is a list of (pointers to) button labels terminated by a null
2700 pointer.
2701 int button
2703 is the current button-index.
2704 dlg_next_ok_buttonindex
2706 Assuming that the caller is using dlg_ok_labels to list buttons, find
2707 the next index in the list of buttons.
2708 int current
2710 is the current index in the list of buttons
2711 int extra
2713 if negative, provides a way to enumerate extra active areas on the
2714 widget.
2715 dlg_ok_buttoncode
2717 Map the given button index for dlg_ok_labels into dialog's exit-code.
2718 int button
2720 is the button-index (which is not necessarily the same as the
2721 index in the list of labels).
2722 dlg_ok_label
2724 Returns a list with the “Ok” label, and if dialog_vars.help_button is
2725 true, the “Help” label as well.
2726 dlg_ok_labels
2728 Return a list of button labels for the OK/Cancel group of widgets.
2729 dlg_ordinate
2731 Decode the string as an integer, decrement if greater than zero to make
2732 a curses-ordinate from a dialog-ordinate.
2733 dlg_parse_bindkey
2735 Parse the parameters of the “bindkeys” configuration-file entry. This
2736 expects widget name which may be "*", followed by curses key definition
2737 and then dialog key definition.
2738 char * params
2740 is the parameter string to parse.
2741 dlg_parse_rc
2743 Parse the configuration file and set up variables.
2744 dlg_popen
2746 Open a pipe which ties the standard error and output together. The
2747 popen function captures only the standard output of a command.
2748 const char *command
2750 The shell command to run.
2751 const char *type
2753 Like popen, "r" is used to read, and "w" is used to write.
2754 dlg_prev_button
2756 Return the previous index in the list of labels.
2757 const char ** labels
2759 is a list of (pointers to) button labels terminated by a null
2760 pointer.
2761 int button
2763 is the current button index
2764 dlg_print_listitem
2766 This is a helper function used for the various “list” widgets, e.g.,
2767 checklist, menu, buildlist, treeview. Each list-widget has “tag” and
2768 “description” values for each item which can be displayed. If dia‐
2769 log_vars.no_tags is true, the “tag” value is not shown. The first
2770 character of the first value shown (tag or description) is highlighted
2771 to indicate that the widget will match it for quick navigation.
2772 WINDOW *win
2774 the window in which to display the text
2775 const char *text
2777 the value to display
2778 int climit
2780 the number of columns available for printing the text
2781 bool first
2783 true if this is the first call (for “tag” and “description”), and
2784 the first character of the value should be highlighted.
2785 int selected
2787 nonzero if the text should be displayed using the “selected” col‐
2788 ors
2789 dlg_print_scrolled
2791 This is a wrapper for dlg_print_autowrap which allows the user to
2792 scroll too-long prompt text up/down.
2793 See dlg_check_scrolled for a function which updates the offset variable
2795 used as a parameter here. It complements this function; you need both.
2796 If pauseopt is set, this function returns an updated last parameter,
2797 needed for dlg_check_scrolled calls.
2798 WINDOW * win
2800 is the window to update.
2801 const char * prompt
2803 is the string to print
2804 int offset
2806 is the starting line-number to write wrapped text.
2807 int height
2809 is the available height for writing the wrapped text
2810 int width
2812 is the width that the wrapping should occur in
2813 int pauseopt
2815 is true if the extra functionality for scrolling should be
2816 enabled. If false, this calls dlg_print_autowrap without doing
2817 any scrolling.
2818 dlg_print_line
2820 Print one line of the prompt in the window within the limits of the
2821 specified right margin. The line will end on a word boundary and a
2822 pointer to the start of the next line is returned, or a NULL pointer if
2823 the end of *prompt is reached.
2824 WINDOW *win
2826 is the window to update.
2827 chtype *attr
2829 holds the starting attributes, and is updated to reflect the final
2830 attributes applied to the string.
2831 const char *prompt
2833 is the string to print
2834 int lm
2836 is the left margin.
2837 int rm
2839 is the right margin
2840 int *x
2842 returns the ending x-ordinate.
2843 dlg_prev_ok_buttonindex
2845 Find the previous button index in the list from dlg_ok_labels.
2846 int current
2848 is the current index
2849 int extra
2851 if negative provides a way to enumerate extra active areas on the
2852 widget.
2853 dlg_print_autowrap
2855 Print a string of text in a window, automatically wrap around to the
2856 next line if the string is too long to fit on one line. Note that the
2857 string may contain embedded newlines. The text is written starting at
2858 the top of the window.
2859 WINDOW * win
2861 is the window to update.
2862 const char * prompt
2864 is the string to print
2865 int height
2867 is the nominal height the wrapped string is limited to
2868 int width
2870 is the width that the wrapping should occur in
2871 dlg_print_size
2873 If dialog_vars.print_siz is true, print the given height/width (from a
2874 widget) to dialog_state.output, e.g., Size: height, width.
2875 int height
2877 is the window's height
2878 int width
2880 is the window's width
2881 dlg_print_text
2883 Print up to cols columns from text, optionally rendering dialog's
2884 escape sequences for attributes and color.
2885 WINDOW * win
2887 is the window to update.
2888 const char * txt
2890 is the string to print
2891 int col
2893 is the column limit
2894 chtype * attr
2896 holds the starting attributes, and is updated to reflect the final
2897 attributes applied to the string.
2898 dlg_progressbox
2900 implements the "--prgbox" and "--progressbox" options.
2901 const char * title
2903 is the title on the top of the widget.
2904 const char * cprompt
2906 is the prompt text shown within the widget. If empty or null, no
2907 prompt is shown.
2908 int height
2910 is the desired height of the box. If zero, the height is based on
2911 the screen size.
2912 int width
2914 is the desired width of the box. If zero, the height is based on
2915 the screen size.
2916 int pauseopt
2918 if true, an “OK” button will be shown, and the dialog will wait
2919 for it to complete. With an “OK” button, it is denoted a “pro‐
2920 grambox”, without an “OK” button, it is denoted a “progressbox”.
2921 FILE * fp
2923 is the file pointer, which may be a pipe or a regular file.
2924 dlg_put_backtitle
2926 Display the background title if dialog_vars.backtitle is non-null. The
2927 background title is shown at the top of the screen.
2928 dlg_reallocate_gauge
2930 Allocates or reallocates a gauge widget (see dlg_allocate_gauge). Use
2931 dlg_update_gauge to display the result.
2932 void ** objptr
2934 If the pointer referenced by this parameter is null, the function
2935 creates a new gauge widget using dlg_allocate_gauge. Otherwise,
2936 it updates the title and cprompt values, reusing the window from
2937 the previous call on this function. As a side-effect, the func‐
2938 tion stores the updated object-pointer via the objptr parameter.
2939 const char * title
2941 is the title string to display at the top of the widget.
2942 const char * cprompt
2944 is the prompt text shown within the widget.
2945 int height
2947 is the desired height of the box. If zero, the height is adjusted
2948 to use the available screen size.
2949 int width
2951 is the desired width of the box. If zero, the height is adjusted
2952 to use the available screen size.
2953 int percent
2955 is the percentage to show in the progress bar.
2956 dlg_register_buttons
2958 The widget developer should call this function after dlg_register_win‐
2959 dow, for the list of button labels associated with the widget. One may
2960 bind a key to a button, e.g., “OK” for DLGK_OK,
2961 WINDOW * win
2963 is the window with which to associate the buttons
2964 const char * name
2966 is the widget's binding name (usually the name of the widget).
2967 const char ** buttons
2969 is the list of buttons
2970 dlg_register_window
2972 For a given named widget's window, associate a binding table.
2973 WINDOW * win
2975 is the window with which to associate the buttons
2976 const char * name
2978 is the widget's binding name (usually the name of the widget).
2979 DLG_KEYS_BINDING * binding
2981 is the binding table
2982 dlg_remove_callback
2984 Remove a callback.
2985 DIALOG_CALLBACK * p
2987 contains the callback information.
2988 dlg_renamed_menutext
2990 This is a utility function which supports the --inputmenu option of the
2991 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
2992 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
2993 it passes dlg_dummy_menutext.
2994 The function should add “RENAMED” to dialog_vars.input_result , fol‐
2996 lowed by the menu item's name and the newtext value (with a space sepa‐
2997 rating the three items), and return DLG_EXIT_EXTRA.
2998 DIALOG_LISTITEM * items
3000 is the list of menu items
3001 int current
3003 is the index of the currently-selected item
3004 char * newtext
3006 is the updated text for the menu item
3007 dlg_restore_vars
3009 Restore dialog's variables from the given variable (see dia‐
3010 log_save_vars).
3011 DIALOG_VARS * save
3013 is the variable from which to restore.
3014 The DIALOG_VARS.input_length and DIALOG_VARS.input_result members are
3016 treated specially, since these are used by a widget to pass data to the
3017 caller. They are not modified by this function.
3018 dlg_result_key
3020 Test a dialog internal keycode to see if it corresponds to one of the
3021 push buttons on the widget such as “OK”. This is only useful if there
3022 are user-defined key bindings, since there are no built-in bindings
3023 that map directly to DLGK_OK, etc. Return true if a mapping was done.
3024 int dialog_key
3026 is the dialog key to test
3027 int fkey
3029 is true if this is a function key
3030 int * resultp
3032 store the result of the mapping in the referenced location.
3033 dlg_save_vars
3035 Save dialog's variables into the given variable (see dlg_restore_vars).
3036 DIALOG_VARS * save
3038 is the variable into which to save.
3039 dlg_set_focus
3041 Set focus on the given window, making it display above other windows on
3042 the screen.
3043 WINDOW * parent
3045 is the parent window (usually the top-level window of a widget)
3046 WINDOW * win
3048 is the window on which to place focus (usually a subwindow of a
3049 widget)
3050 dlg_set_result
3052 Setup a fixed-buffer for the result in dialog_vars.input_result
3053 const char * string
3055 is the new contents for the result
3056 dlg_show_string
3058 Displays the string, shifted as necessary, to fit within the box and
3059 show the current character-offset.
3060 WINDOW * win
3062 is the window within which to display
3063 const char * string
3065 is the string to display
3066 int offset
3068 is the starting (character, not bytes) offset
3069 chtype attr
3071 is the window attribute to use for the string
3072 int y_base
3074 beginning row on screen
3075 int x_base
3077 beginning column on screen
3078 int x_last
3080 number of columns on screen
3081 bool hidden
3083 if true, do not echo input
3084 bool force
3086 if true, force repaint
3087 dlg_strclone
3089 duplicate the string, like strdup.
3090 const char * cprompt
3092 is the string to duplicate
3093 dlg_strcmp
3095 compare two strings, ignoring case.
3096 const char * a
3098 is one string
3099 const char * b
3101 is the other string
3102 dlg_string_to_argv
3104 Convert a string to an argument vector returning an index (which must
3105 be freed by the caller). The string is modified:
3106 · Blanks between arguments are replaced by nulls.
3108 · Normally arguments are separated by blanks; however you can double-
3110 quote an argument to enclose blanks. The surrounding double-quotes
3111 are removed from the string.
3112 · A backslash preceding a double-quote within double-quotes is
3114 removed.
3115 · A backslash preceding a newline outside double-quotes is removed.
3117 · Except for special cases, backslashes are preserved in the strings,
3119 since other dialog functions interpret backslashes, e.g., for col‐
3120 ors.
3121 char *blob
3123 is the string to convert.
3124 dlg_sub_window
3126 create a subwindow, e.g., for an input area of a widget
3127 WINDOW * win
3129 is the parent window
3130 int height
3132 is the subwindow's height
3133 int width
3135 is the subwindow's width
3136 int y
3138 is the subwindow's top-row
3139 int x
3141 is the subwindow's left-column
3142 dlg_tab_correct_str
3144 If the dialog_vars.tab_correct is true, convert tabs to single spaces.
3145 Return the converted result. The caller is responsible for freeing the
3146 string.
3147 char * prompt
3149 is the string to convert
3150 dlg_trace
3152 If the parameter is non-null, opens a trace file with that name and
3153 stores the file pointer in dialog_state.trace.
3154 dlg_trace_2n
3156 logs a numeric value as a comment.
3157 char * name
3159 is the name to log in the comment.
3160 int value
3162 is the value to log in the comment.
3163 dlg_trace_2n
3165 logs a string value as a comment. If the value contains embedded new‐
3166 lines, the comment is continued with “#+” markers.
3167 char * name
3169 is the name to log in the comment.
3170 int value
3172 is the value to log in the comment.
3173 dlg_trace_chr
3175 If dialog_state.trace is set, translate the parameters into a printable
3176 representation, log it on a “chr” line.
3177 int ch
3179 is the nominal keycode value.
3180 int fkey
3182 is nonzero if the value is really a function key. Some of these
3183 may be values declared in the DLG_KEYS_ENUM.
3184 dlg_trace_msg
3186 Write a formatted message to the trace file.
3187 const char * fmt
3189 is the format of the printf-like message to write.
3190 ...
3192 are the variables to apply to the fmt format.
3193 Use the DLG_TRACE macro for portability, in case the trace feature is
3195 not compiled into the library. It uses an extra level of parentheses
3196 to work with a variable number of parameters, e.g.,
3197 DLG_TRACE(("this is dialog version %s\n", dialog_version()));
3199 dlg_ttysize
3201 Returns the screensize without using curses. That allows the function
3202 to be used before initializing the screen.
3203 dlg_trace_win
3205 If dialog_state.trace is set, log a printable picture of the given win‐
3206 dow.
3207 dlg_treeview
3209 This is an alternate interface to 'treeview' which allows the applica‐
3210 tion to read the list item states back directly without putting them in
3211 the output buffer.
3212 const char * title
3214 is the title on the top of the widget.
3215 const char * cprompt
3217 is the prompt text shown within the widget.
3218 int height
3220 is the desired height of the box. If zero, the height is based on
3221 the screen size.
3222 int width
3224 is the desired width of the box. If zero, the height is based on
3225 the screen size.
3226 int list_height
3228 is the minimum height to reserve for displaying the list. If
3229 zero, it is computed based on the given height and width.
3230 int item_no
3232 is the number of rows in items.
3233 DIALOG_LISTITEM * items
3235 is the list of items, contain tag, name, and optionally help
3236 strings (if dialog_vars.item_help is set). The initial selection
3237 state for each item is also in this list.
3238 const char * states
3240 This is a list of characters to display for the given states.
3241 Normally a buildlist provides true (1) and false (0) values, which
3242 the widget displays as "*" and space, respectively. An applica‐
3243 tion may set this parameter to an arbitrary null-terminated
3244 string. The widget determines the number of states from the
3245 length of this string, and will cycle through the corresponding
3246 display characters as the user presses the space-bar.
3247 int * depths
3249 This is a list of depths of each item in the tree. It is a sepa‐
3250 rate parameter from items to allow reuse of the existing func‐
3251 tions.
3252 int flag
3254 is either FLAG_CHECK, for checklists (multiple selections), or
3255 FLAG_RADIO for radiolists (a single selection).
3256 int * current_item
3258 The widget sets the referenced location to the index of the cur‐
3259 rent display item (cursor) when it returns.
3260 dlg_trim_string
3262 The dialog program uses this in each widget to adjust the message
3263 string, which may contain the newline character (referred to as '\n')
3264 and/or the special substring "\n" (which can be translated into a new‐
3265 line character).
3266 There are several optional features:
3268 · Unless dialog_vars.nocollapse is set, each tab is converted to a
3270 space before other processing.
3271 · If dialog_vars.no_nl_expand is not set, and the string has "\n"
3273 substrings:
3274 · The function changes embedded "\n" substrings to '\n' charac‐
3276 ters.
3277 The function preserves extra spaces after these substitutions.
3279 For instance, spaces following a newline (substring or charac‐
3280 ter) are preserved to use as an indentation.
3281 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3283 line characters. Otherwise, each '\n' newline character is
3284 converted to a space.
3285 · Otherwise, if dialog_vars.trim_whitespace is set:
3287 · This function strips all extra spaces to simplify justifica‐
3289 tion.
3290 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3292 line characters. Otherwise, each '\n' newline character is
3293 converted to a space.
3294 · Finally (if dialog_vars.no_nl_expand is set, or the string does not
3296 contain "\n" substrings, and dialog_vars.trim_whitespace is not
3297 set):
3298 · Unless dialog_vars.nocollapse is set, sequences of spaces are
3300 reduced to a single space.
3301 char * src
3303 is the string to trim
3304 dlg_unregister_window
3306 Remove the bindings for a given window.
3307 WINDOW * win
3309 is the window from which to remove bindings
3310 dlg_update_gauge
3312 Update a gauge widget to show a different percentage value.
3313 void *objptr
3315 points to the gauge object to update.
3316 int percent
3318 is the new percentage value to display.
3319 dlg_will_resize
3321 This filters out bursts of KEY_RESIZE values. Call this after dlg_getc
3322 returns KEY_RESIZE, to improve performance.
3323 dlg_yes_buttoncode
3325 Map the given button index for dlg_yes_labels into dialog's exit-code.
3326 int button
3328 is the button index
3329 dlg_yes_labels
3331 Return a list of buttons for Yes/No labels.
3332 end_dialog
3334 End use of dialog functions.
3335 init_dialog
3337 Do some initialization for dialog.
3338 FILE *input
3340 is the real tty input of dialog. Usually it is the standard
3341 input, but if --input-fd option is used, it may be anything.
3342 FILE *output
3344 is where dialog will send its result. Usually it is the standard
3345 error, but if --stdout or --output-fd is used, it may be anything.
3346
3348 dialog (1).
3349
3351 Thomas E. Dickey
3352$Date: 2018/06/20 01:21:53 $ DIALOG(3)