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 .had_resize
112 This is set to TRUE in dlg_will_resize or dlg_result_key when
113 KEY_RESIZE is read, to tell dialog to ignore subsequent ERRs.
114 .no_mouse
116 This corresponds to the command-line option "--no-mouse". If true,
117 dialog will not initialize (and enable) the mouse in init_dialog.
118 .output
120 This is set in the dialog application to the stream on which the appli‐
121 cation and library functions may write text results. Normally that is
122 the standard error, since the curses library prefers to write its data
123 to the standard output. Some scripts, trading portability for conve‐
124 nience, prefer to write results to the standard output, e.g., by using
125 the "--stdout" option.
126 .output_count
128 This is incremented by dlg_does_output, which is called by each widget
129 that writes text to the output. The dialog application uses that to
130 decide if it should also write a separator, i.e., DIALOG_STATE.sepa‐
131 rate_str, between calls to each widget.
132 .pipe_input
134 This is set in init_dialog to a stream which can be used by the gauge
135 widget, which must be the application's standard input. The dialog
136 application calls init_dialog normally with input set to the standard
137 input, but optionally based on the "--input-fd" option. Since the
138 application cannot read from a pipe (standard input) and at the same
139 time read the curses input from the standard input, it must allow for
140 reopening the latter from either a specific file descriptor, or
141 directly from the terminal. The adjusted pipe stream value is stored
142 in this variable.
143 .screen_height
145 The text-formatting functions use this for the number of rows used for
146 formatting a string.
147 It is used by dialog for the command-line options "--print-text-size"
149 and "--print-text-only".
150 .screen_initialized
152 This is set in init_dialog and reset in end_dialog. It is used to
153 check if curses has been initialized, and if the endwin function must
154 be called on exit.
155 .screen_output
157 This is set in init_dialog to the output stream used by the curses
158 library. Normally that is the standard output, unless that happens to
159 not be a terminal (and if init_dialog can successfully open the termi‐
160 nal directly).
161 .screen_width
163 The text-formatting functions use this for the number of columns used
164 for formatting a string.
165 It is used by dialog for the command-line options "--print-text-size"
167 and "--print-text-only".
168 .separate_str
170 This corresponds to the command-line option "--separate-widget". The
171 given string specifies a string that will separate the output on dia‐
172 log's output from each widget. This is used to simplify parsing the
173 result of a dialog with several widgets. If this option is not given,
174 the default separator string is a tab character.
175 .tab_len
177 This corresponds to the command-line option "--tab-len number". Spec‐
178 ify the number of spaces that a tab character occupies if the "--tab-
179 correct" option is given. The default is 8.
180 .text_height
182 The text-formatting functions set this to the number of lines used for
183 formatting a string.
184 It is used by dialog for the command-line options "--print-text-size"
186 and "--print-text-only".
187 .text_only
189 Dialog uses this in the command-line option "--print-text-only".
190 The text-formatting functions (dlg_print_text, dlg_print_line, and
192 dlg_print_autowrap) check this to decide whether to print the formatted
193 text to dialog's output or to the curses-display.
194 Also, dlg_auto_size checks the flag, allowing it to be used before
196 init_dialog is called.
197 .text_width
199 The text-formatting functions set this to the number of columns used
200 for formatting a string.
201 It is used by dialog for the command-line options "--print-text-size"
203 and "--print-text-only".
204 .trace_output
206 This corresponds to the command-line option "--trace file". It is the
207 file pointer to which trace messages are written.
208 .use_colors
210 This is set in init_dialog if the curses implementation supports color.
211 .use_scrollbar
213 This corresponds to the command-line option "--scrollbar". If true,
214 draw a scrollbar to make windows holding scrolled data more readable.
215 .use_shadow
217 This corresponds to the command-line option "--no-shadow". This is set
218 in init_dialog if the curses implementation supports color. If true,
219 suppress shadows that would be drawn to the right and bottom of each
220 dialog box.
221 .visit_items
223 This corresponds to the command-line option "--visit-items". Modify
224 the tab-traversal of the list-oriented widgets (buildlist, checklist,
225 radiobox, menubox, inputmenu, and treeview) to include the list of
226 items as one of the states. This is useful as a visual aid, i.e., the
227 cursor position helps some users.
228 The dialog application resets the dialog_vars data before accepting
230 options to invoke each widget. Most of the DIALOG_VARS members are set
231 directly from dialog's command-line options:
232
234 In contrast to DIALOG_STATE, the members of DIALOG_VARS are set by com‐
235 mand-line options in dialog.
236 .ascii_lines
238 This corresponds to the command-line option "--ascii-lines. It causes
239 line-drawing to be done with ASCII characters, e.g., "+" and "-". See
240 DIALOG_VARS.no_lines.
241 .backtitle
243 This corresponds to the command-line option "--backtitle backtitle".
244 It specifies a backtitle string to be displayed on the backdrop, at the
245 top of the screen.
246 .beep_after_signal
248 This corresponds to the command-line option "--beep-after". If true,
249 beep after a user has completed a widget by pressing one of the but‐
250 tons.
251 .beep_signal
253 This corresponds to the command-line option "--beep". It is obsolete.
254 .begin_set
256 This is true if the command-line option "--begin y x" was used. It
257 specifies the position of the upper left corner of a dialog box on the
258 screen.
259 .begin_x
261 This corresponds to the x value from the command-line option "--begin y
262 x" (second value).
263 .begin_y
265 This corresponds to the y value from the command-line option "--begin y
266 x" (first value).
267 .cancel_label
269 This corresponds to the command-line option "--cancel-label string".
270 The given string overrides the label used for “Cancel” buttons.
271 .cant_kill
273 This corresponds to the command-line option "--no-kill". If true, this
274 tells dialog to put the tailboxbg box in the background, printing its
275 process id to dialog's output. SIGHUP is disabled for the background
276 process.
277 .colors
279 This corresponds to the command-line option "--colors". If true,
280 interpret embedded "\Z" sequences in the dialog text by the following
281 character, which tells dialog to set colors or video attributes: 0
282 through 7 are the ANSI codes used in curses: black, red, green, yellow,
283 blue, magenta, cyan and white respectively. Bold is set by 'b', reset
284 by 'B'. Reverse is set by 'r', reset by 'R'. Underline is set by 'u',
285 reset by 'U'. The settings are cumulative, e.g., "\Zb\Z1" makes the
286 following text bright red. Restore normal settings with "\Zn".
287 .column_separator
289 This corresponds to the command-line option "--column-separator". Dia‐
290 log splits data for radio/checkboxes and menus on the occurrences of
291 the given string, and aligns the split data into columns.
292 .cr_wrap
294 This corresponds to the command-line option "--cr-wrap". If true,
295 interpret embedded newlines in the dialog text as a newline on the
296 screen. Otherwise, dialog will only wrap lines where needed to fit
297 inside the text box. Even though you can control line breaks with
298 this, dialog will still wrap any lines that are too long for the width
299 of the box. Without cr-wrap, the layout of your text may be formatted
300 to look nice in the source code of your script without affecting the
301 way it will look in the dialog.
302 .date_format
304 This corresponds to the command-line option "--date-format string". If
305 the host provides strftime, and the value is nonnull, the calendar wid‐
306 get uses this to format its output.
307 .default_button
309 This is set by the command-line option "--default-button. It is used
310 by dlg_default_button.
311 .default_item
313 This corresponds to the command-line option "--default-item string".
314 The given string is used as the default item in a checklist, form or
315 menu box. Normally the first item in the box is the default.
316 .defaultno
318 This corresponds to the command-line option "--defaultno". If true,
319 make the default value of the yes/no box a No. Likewise, treat the
320 default button of widgets that provide “OK” and “Cancel” as a Cancel.
321 If --nocancel was given that option overrides this, making the default
322 button always “Yes” (internally the same as “OK”).
323 .dlg_clear_screen
325 This corresponds to the command-line option "--clear". This option is
326 implemented in the main program, not the library. If true, the screen
327 will be cleared on exit. This may be used alone, without other
328 options.
329 .exit_label
331 This corresponds to the command-line option "--exit-label string". The
332 given string overrides the label used for “EXIT” buttons.
333 .extra_button
335 This corresponds to the command-line option "--extra-button". If true,
336 some widgets show an extra button, between “OK” and “Cancel” buttons.
337 .extra_label
339 This corresponds to the command-line option "--extra-label string".
340 The given string overrides the label used for “Extra” buttons. Note:
341 for inputmenu widgets, this defaults to “Rename”.
342 .formitem_type
344 This is set by the command-line option "--passwordform" to tell the
345 form widget that its text fields should be treated like password wid‐
346 gets.
347 .help_button
349 This corresponds to the command-line option "--help-button". If true,
350 some widgets show a help-button after “OK” and “Cancel” buttons, i.e.,
351 in checklist, radiolist and menu boxes. If --item-help is also given,
352 on exit the return status will be the same as for the “OK” button, and
353 the item-help text will be written to dialog's output after the token
354 “HELP”. Otherwise, the return status will indicate that the Help but‐
355 ton was pressed, and no message printed.
356 .help_file
358 This corresponds to the command-line option "--hfile string". The
359 given filename is passed to dialog_helpfile when the user presses F1.
360 .help_label
362 This corresponds to the command-line option "--help-label string". The
363 given string overrides the label used for “Help” buttons.
364 .help_line
366 This corresponds to the command-line option "--hline string". The
367 given string is displayed in the bottom of dialog windows, like a sub‐
368 title.
369 .help_status
371 This corresponds to the command-line option "--help-status". If true,
372 and the the help-button is selected, writes the checklist or radiolist
373 information after the item-help “HELP” information. This can be used
374 to reconstruct the state of a checklist after processing the help
375 request.
376 .help_tags
378 This corresponds to the command-line option "--help-tags". If true,
379 dlg_add_help_formitem and dlg_add_help_listitem use the item's tag
380 value consistently rather than using the tag's help-text value when
381 DIALOG_VARS.item_help is set.
382 .input_length
384 This is nonzero if DIALOG_VARS.input_result is allocated, versus being
385 a pointer to the user's local variables.
386 .input_menu
388 This flag is set to denote whether the menubox widget implements a menu
389 versus a inputmenu widget.
390 .input_result
392 This may be either a user-supplied buffer, or a buffer dynamically
393 allocated by the library, depending on DIALOG_VARS.input_length:
394 · If DIALOG_VARS.input_length is zero, this is a pointer to user buf‐
396 fer (on the stack, or static). The buffer size is assumed to be
397 MAX_LEN, which is defined in <dialog.h>.
398 · When DIALOG_VARS.input_length is nonzero, this is a dynamically-
400 allocated buffer used by the widgets to return printable results to
401 the calling application.
402 Certain widgets copy a result to this buffer. If the pointer is NULL,
404 or if the length is insufficient for the result, then the dialog
405 library allocates a buffer which is large enough, and sets DIA‐
406 LOG_VARS.input_length. Callers should check for this case if they have
407 supplied their own buffer.
408 .insecure
410 This corresponds to the command-line option "--insecure". If true,
411 make the password widget friendlier but less secure, by echoing aster‐
412 isks for each character.
413 .in_helpfile
415 This variable is used to prevent dialog_helpfile from showing anything,
416 e.g., if F1 were pressed within a help-file display.
417 .iso_week
419 This corresponds to the command-line option "--iso-week". It is used
420 in the calendar widget to tell how to compute the starting week for the
421 year:
422 · by default, the calendar treats January 1 as the first week of the
424 year.
425 · If this variable is true, the calendar uses ISO 8601's convention.
427 ISO 8601 numbers weeks starting with the first week in January with
428 a Thursday in the current year. January 1 may be in the previous
429 year.
430 .item_help
432 This corresponds to the command-line option "--item-help". If true,
433 interpret the tags data for checklist, radiolist and menu boxes adding
434 a column whose text is displayed in the bottom line of the screen, for
435 the currently selected item.
436 .keep_tite
438 This is set by the command-line option "--keep-tite" to tell dialog to
439 not attempt to cancel the terminal initialization (termcap ti/te)
440 sequences which correspond to xterm's alternate-screen switching. Nor‐
441 mally dialog does this to avoid flickering when run several times in a
442 script.
443 .keep_window
445 This corresponds to the command-line option "--keep-window". If true,
446 do not remove/repaint the window on exit. This is useful for keeping
447 the window contents visible when several widgets are run in the same
448 process. Note that curses will clear the screen when starting a new
449 process.
450 .last_key
452 This corresponds to the command-line option "--last-key".
453 .max_input
455 This corresponds to the command-line option "--max-input size". Limit
456 input strings to the given size. If not specified, the limit is 2048.
457 .no_items
459 This corresponds to the command-line option "--no-items". Some widgets
460 (checklist, inputmenu, radiolist, menu) display a list with two columns
461 (a “tag” and “item”, i.e., “description”). This tells dialog to read
462 shorter rows from data, omitting the “list”.
463 .no_label
465 This corresponds to the command-line option "--no-label string". The
466 given string overrides the label used for “No” buttons.
467 .no_lines
469 This corresponds to the command-line option "--no-lines. It suppresses
470 line-drawing. See DIALOG_VARS.ascii_lines.
471 .no_nl_expand
473 This corresponds to the command-line option "--no-nl-expand". If
474 false, dlg_trim_string converts literal "\n" substrings in a message
475 into newlines.
476 .no_tags
478 This corresponds to the command-line option "--no-tags". Some widgets
479 (checklist, inputmenu, radiolist, menu) display a list with two columns
480 (a “tag” and “item”, also known as “description”). The tag is useful
481 for scripting, but may not help the user. The --no-tags option (from
482 Xdialog) may be used to suppress the column of tags from the display.
483 Normally dialog allows you to quickly move to entries on the displayed
485 list, by matching a single character to the first character of the tag.
486 When the --no-tags option is given, dialog matches against the first
487 character of the description. In either case, the matchable character
488 is highlighted.
489 Here is a table showing how the no_tags and no_items values interact:
491 Widget Fields Shown Fields Read .no_items .no_tags
493 ──────────────────────────────────────────────────────────────
494 buildlist item tag,item 0 0*
495 buildlist item tag,item 0 1
496 buildlist tag tag 1 0*
497 buildlist tag tag 1 1
498 checklist tag,item tag,item 0 0
499 checklist item tag,item 0 1
500 checklist tag tag 1 0
501 checklist tag tag 1 1
502 inputmenu tag,item tag,item 0 0
503 inputmenu item tag,item 0 1
504 inputmenu tag tag 1 0
505 inputmenu tag tag 1 1
506 menu tag,item tag,item 0 0
507 menu item tag,item 0 1
508 menu tag tag 1 0
509 menu tag tag 1 1
510 radiolist tag,item tag,item 0 0
511 radiolist item tag,item 0 1
512 radiolist tag tag 1 0
513 radiolist tag tag 1 1
514 treeview item tag,item 0 0*
515 treeview item tag,item 0 1
516 treeview tag tag 1 0*
517 treeview tag tag 1 1
518 ──────────────────────────────────────────────────────────────
519 * Xdialog does not display the tag column for the analogous buildlist
521 and treeview widgets. Dialog does the same on the command-line.
522 However the library interface defaults to displaying the tag column.
523 Your application can enable or disable the tag column as needed for
524 each widget.
525 .nocancel
527 This corresponds to the command-line option "--no-cancel". If true,
528 suppress the “Cancel” button in checklist, inputbox and menu box modes.
529 A script can still test if the user pressed the ESC key to cancel to
530 quit.
531 .nocollapse
533 This corresponds to the command-line option "--no-collapse". Normally
534 dialog converts tabs to spaces and reduces multiple spaces to a single
535 space for text which is displayed in a message boxes, etc. It true,
536 that feature is disabled. Note that dialog will still wrap text, sub‐
537 ject to the --cr-wrap option.
538 .nook
540 This corresponds to the command-line option "--nook. Dialog will sup‐
541 press the “ok” (or “yes”) button from the widget.
542 .ok_label
544 This corresponds to the command-line option "--ok-label string". The
545 given string overrides the label used for “OK” buttons.
546 .print_siz
548 This corresponds to the command-line option "--print-size". If true,
549 each widget prints its size to dialog's output when it is invoked.
550 .quoted
552 This corresponds to the command-line option "--quoted. Normally dialog
553 quotes the strings returned by checklist's as well as the item-help
554 text. If true, dialog will quote all string results.
555 .reorder
557 This corresponds to the command-line option "--reorder. By default,
558 the buildlist widget uses the same order for the output (right) list as
559 for the input (left). If true, dialog will use the order in which a
560 user adds selections to the output list.
561 .separate_output
563 This corresponds to the command-line option "--separate-output". If
564 true, checklist widgets output result one line at a time, with no quot‐
565 ing. This facilitates parsing by another program.
566 .single_quoted
568 This corresponds to the command-line option "--single-quoted". If
569 true, use single-quoting as needed (and no quotes if unneeded) for the
570 output of checklist's as well as the item-help text. If this option is
571 not set, dialog uses double quotes around each item. The latter
572 requires occasional use of backslashes to make the output useful in
573 shell scripts.
574 .size_err
576 This corresponds to the command-line option "--size-err". If true,
577 check the resulting size of a dialog box before trying to use it,
578 printing the resulting size if it is larger than the screen. (This
579 option is obsolete, since all new-window calls are checked).
580 .sleep_secs
582 This corresponds to the command-line option "--sleep secs". This
583 option is implemented in the main program, not the library. If
584 nonzero, this is the number of seconds after to delay after processing
585 a dialog box.
586 .tab_correct
588 This corresponds to the command-line option "--tab-correct". If true,
589 convert each tab character of the text to one or more spaces. Other‐
590 wise, tabs are rendered according to the curses library's interpreta‐
591 tion.
592 .time_format
594 This corresponds to the command-line option "--time-format string". If
595 the host provides strftime, and the value is nonnull, the timebox wid‐
596 get uses this to format its output.
597 .timeout_secs
599 This corresponds to the command-line option "--timeout secs". If
600 nonzero, timeout input requests (exit with error code) if no user
601 response within the given number of seconds.
602 .title
604 This corresponds to the command-line option "--title title". Specifies
605 a title string to be displayed at the top of the dialog box.
606 .trim_whitespace
608 This corresponds to the command-line option "--trim". If true, elimi‐
609 nate leading blanks, trim literal newlines and repeated blanks from
610 message text.
611 .week_start
613 This corresponds to the command-line option "--week-start". It is used
614 in the calendar widget to set the starting day for the week. The
615 string value can be
616 · a number (0 to 6, Sunday through Saturday using POSIX) or
618 · the special value “locale” (this works with systems using glibc,
620 providing an extension to the locale command, the first_weekday
621 value).
622 · a string matching one of the abbreviations for the day of the week
624 shown in the calendar widget, e.g., “Mo” for “Monday”.
625 .yes_label
627 This corresponds to the command-line option "--yes-label string". The
628 given string overrides the label used for “Yes” buttons.
629
631 Functions that implement major functionality for the command-line dia‐
632 log program, e.g., widgets, have names beginning "dialog_".
633 All dialog boxes have at least three parameters:
635 title
637 the caption for the box, shown on its top border.
638 height
640 the height of the dialog box.
641 width
643 the width of the dialog box.
644 Other parameters depend on the box type.
646 dialog_buildlist
648 implements the "--buildlist" option.
649 const char * title
651 is the title on the top of the widget.
652 const char * cprompt
654 is the prompt text shown within the widget.
655 int height
657 is the desired height of the box. If zero, the height is adjusted
658 to use the available screen size.
659 int width
661 is the desired width of the box. If zero, the height is adjusted
662 to use the available screen size.
663 int list_height
665 is the minimum height to reserve for displaying the list. If
666 zero, it is computed based on the given height and width.
667 int item_no
669 is the number of rows in items.
670 char ** items
672 is an array of strings which is viewed either as a list of rows
673 tag item status
674 or
676 tag item status help
677 depending on whether dialog_vars.item_help is set.
679 int order_mode
681 is reserved for future enhancements
682 dialog_calendar
684 implements the "--calendar" option.
685 const char * title
687 is the title on the top of the widget.
688 const char * subtitle
690 is the prompt text shown within the widget.
691 int height
693 is the height excluding the fixed-height calendar grid.
694 int width
696 is the overall width of the box, which is adjusted up to the cal‐
697 endar grid's minimum width if needed.
698 int day
700 is the initial day of the week shown, counting zero as Sunday. If
701 the value is negative, the current day of the week is used.
702 int month
704 is the initial month of the year shown, counting one as January.
705 If the value is negative, the current month of the year is used.
706 int year
708 is the initial year shown. If the value is negative, the current
709 year is used.
710 dialog_checklist
712 implements the "--checklist" and "--radiolist" options depending on the
713 flag parameter.
714 const char * title
716 is the title on the top of the widget.
717 const char * cprompt
719 is the prompt text shown within the widget.
720 int height
722 is the desired height of the box. If zero, the height is adjusted
723 to use the available screen size.
724 int width
726 is the desired width of the box. If zero, the height is adjusted
727 to use the available screen size.
728 int list_height
730 is the minimum height to reserve for displaying the list. If
731 zero, it is computed based on the given height and width.
732 int item_no
734 is the number of rows in items.
735 int items
737 is an array of strings which is viewed either as a list of rows
738 tag item status
739 or
741 tag item status help
742 depending on whether dialog_vars.item_help is set.
744 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for radi‐
746 olists.
747 dialog_dselect
749 implements the "--dselect" option.
750 const char * title
752 is the title on the top of the widget.
753 const char * path
755 is the preselected value to show in the input-box, which is used
756 also to set the directory- and file-windows.
757 int height
759 is the height excluding the minimum needed to show the dialog box
760 framework. If zero, the height is based on the screen size.
761 int width
763 is the desired width of the box. If zero, the height is based on
764 the screen size.
765 dialog_editbox
767 implements the "--editbox" option.
768 const char * title
770 is the title on the top of the widget.
771 const char * file
773 is the name of the file from which to read.
774 int height
776 is the desired height of the box. If zero, the height is adjusted
777 to use the available screen size.
778 int width
780 is the desired width of the box. If zero, the height is adjusted
781 to use the available screen size.
782 dialog_form
784 implements the "--form" option.
785 const char * title
787 is the title on the top of the widget.
788 const char * cprompt
790 is the prompt text shown within the widget.
791 int height
793 is the desired height of the box. If zero, the height is adjusted
794 to use the available screen size.
795 int width
797 is the desired width of the box. If zero, the height is adjusted
798 to use the available screen size.
799 int form_height
801 is the minimum height to reserve for displaying the list. If
802 zero, it is computed based on the given height and width.
803 int item_no
805 is the number of rows in items.
806 int items
808 is an array of strings which is viewed either as a list of rows
809 Name NameY NameX Text TextY TextX FLen ILen
810 or
812 Name NameY NameX Text TextY TextX FLen ILen Help
813 depending on whether dialog_vars.item_help is set.
815 dialog_fselect
817 implements the "--fselect" option.
818 const char * title
820 is the title on the top of the widget.
821 const char * path
823 is the preselected value to show in the input-box, which is used
824 also to set the directory- and file-windows.
825 int height
827 is the height excluding the minimum needed to show the dialog box
828 framework. If zero, the height is based on the screen size.
829 int width
831 is the desired width of the box. If zero, the height is based on
832 the screen size.
833 dialog_gauge
835 implements the "--gauge" option. Alternatively, a simpler or custom‐
836 ized gauge widget can be set up using dlg_allocate_gauge, dlg_reallo‐
837 cate_gauge, dlg_update_gauge and dlg_free_gauge.
838 const char * title
840 is the title on the top of the widget.
841 const char * cprompt
843 is the prompt text shown within the widget.
844 int height
846 is the desired height of the box. If zero, the height is based on
847 the screen size.
848 int width
850 is the desired width of the box. If zero, the height is based on
851 the screen size.
852 int percent
854 is the percentage to show in the progress bar.
855 dialog_inputbox
857 implements the "--inputbox" or "--password" option, depending on the
858 value of password.
859 const char * title
861 is the title on the top of the widget.
862 const char * cprompt
864 is the prompt text shown within the widget.
865 int height
867 is the desired height of the box. If zero, the height is based on
868 the screen size.
869 int width
871 is the desired width of the box. If zero, the height is based on
872 the screen size.
873 const char * init
875 is the initial value of the input box, whose length is taken into
876 account when auto-sizing the width of the dialog box.
877 int password
879 if true, causes typed input to be echoed as asterisks.
880 dialog_helpfile
882 implements the "--hfile" option.
883 const char * title
885 is the title on the top of the widget.
886 const char * file
888 is the name of a file containing the text to display. This func‐
889 tion is internally bound to F1 (function key “1”), passing dia‐
890 log_vars.help_file as a parameter. The dialog program sets that
891 variable when the --hfile option is given.
892 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 dialog_menu
902 implements the "--menu" or "--inputmenu" option depending on whether
903 dialog_vars.input_menu is set.
904 const char * title
906 is the title on the top of the widget.
907 const char * cprompt
909 is the prompt text shown within the widget.
910 int height
912 is the desired height of the box. If zero, the height is based on
913 the screen size.
914 int width
916 is the desired width of the box. If zero, the height is based on
917 the screen size.
918 int menu_height
920 is the minimum height to reserve for displaying the list. If
921 zero, it is computed based on the given height and width.
922 int item_no
924 is the number of rows in items.
925 int items
927 is an array of strings which is viewed either as a list of rows
928 tag item
929 or
931 tag item help
932 depending on whether dialog_vars.item_help is set.
934 dialog_mixedform
936 implements the "--mixedform" option.
937 const char * title
939 is the title on the top of the widget.
940 const char * cprompt
942 is the prompt text shown within the widget.
943 int height
945 is the desired height of the box. If zero, the height is adjusted
946 to use the available screen size.
947 int width
949 is the desired width of the box. If zero, the height is adjusted
950 to use the available screen size.
951 int form_height
953 is the minimum height to reserve for displaying the list. If
954 zero, it is computed based on the given height and width.
955 int item_no
957 is the number of rows in items.
958 int items
960 is an array of strings which is viewed either as a list of rows
961 Name NameY NameX Text TextY TextX FLen ILen Ityp
962 or
964 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
965 depending on whether dialog_vars.item_help is set.
967 dialog_mixedgauge
969 implements the "--mixedgauge" option
970 const char * title
972 is the title on the top of the widget.
973 const char * cprompt
975 is the caption text shown within the widget.
976 int height
978 is the desired height of the box. If zero, the height is based on
979 the screen size.
980 int width
982 is the desired width of the box. If zero, the height is based on
983 the screen size.
984 int percent
986 is the percentage to show in the progress bar.
987 int item_no
989 is the number of rows in items.
990 int items
992 is an array of strings which is viewed as a list of tag and item
993 values. The tag values are listed, one per row, in the list at
994 the top of the widget.
995 The item values are decoded: digits 0 through 9 are the following
997 strings
998 0 Succeeded
1000 1 Failed
1002 2 Passed
1004 3 Completed
1006 4 Checked
1008 5 Done
1010 6 Skipped
1012 7 In Progress
1014 8 (blank)
1016 9 N/A
1018 A string with a leading "-" character is centered, marked with
1020 "%". For example, "-75" is displayed as "75%". Other strings are
1021 displayed as is.
1022 dialog_msgbox
1024 implements the "--msgbox" or "--infobox" option depending on whether
1025 pauseopt is set.
1026 const char * title
1028 is the title on the top of the widget.
1029 const char * cprompt
1031 is the prompt text shown within the widget.
1032 int height
1034 is the desired height of the box. If zero, the height is based on
1035 the screen size.
1036 int width
1038 is the desired width of the box. If zero, the height is based on
1039 the screen size.
1040 int pauseopt
1042 if true, an “OK” button will be shown, and the dialog will wait
1043 for it to complete. With an “OK” button, it is denoted a “msg‐
1044 box”, without an “OK” button, it is denoted an “infobox”.
1045 dialog_pause
1047 implements the "--pause" option.
1048 const char * title
1050 is the title on the top of the widget.
1051 int height
1053 is the desired height of the box. If zero, the height is based on
1054 the screen size.
1055 int width
1057 is the desired width of the box. If zero, the height is based on
1058 the screen size.
1059 int seconds
1061 is the timeout to use for the progress bar.
1062 dialog_prgbox
1064 implements the "--prgbox" option.
1065 const char * title
1067 is the title on the top of the widget.
1068 const char * cprompt
1070 is the prompt text shown within the widget. If empty or null, no
1071 prompt is shown.
1072 const char * command
1074 is the name of the command to execute.
1075 int height
1077 is the desired height of the box. If zero, the height is based on
1078 the screen size.
1079 int width
1081 is the desired width of the box. If zero, the height is based on
1082 the screen size.
1083 int pauseopt
1085 if true, an “OK” button will be shown, and the dialog will wait
1086 for it to complete.
1087 dialog_progressbox
1089 implements the "--progressbox" 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 box. If zero, the height is based on
1100 the screen size.
1101 int width
1103 is the desired width of the box. If zero, the height is based on
1104 the screen size.
1105 dialog_rangebox
1107 implements the "--rangebox" option.
1108 const char * title
1110 is the title on the top of the widget.
1111 const char * cprompt
1113 is the prompt text shown within the widget. If empty or null, no
1114 prompt is shown.
1115 int height
1117 is the desired height of the widget. If zero, the height is based
1118 on the screen size.
1119 int width
1121 is the desired width of the widget. If zero, the height is based
1122 on the screen size.
1123 int min_value
1125 is the minimum value to allow.
1126 int max_value
1128 is the maximum value to allow.
1129 int default_value
1131 is the default value, if no change is made.
1132 dialog_tailbox
1134 implements the "--tailbox" or "--tailboxbg" option depending on whether
1135 bg_task is set.
1136 const char * title
1138 is the title on the top of the widget.
1139 const char * file
1141 is the name of the file to display in the dialog.
1142 int height
1144 is the desired height of the box. If zero, the height is based on
1145 the screen size.
1146 int width
1148 is the desired width of the box. If zero, the height is based on
1149 the screen size.
1150 int bg_task
1152 if true, the window is added to the callback list in dialog_state,
1153 and the application will poll for the window to be updated. Oth‐
1154 erwise an “OK” button is added to the window, and it will be
1155 closed when the button is activated.
1156 dialog_textbox
1158 implements the "--textbox" option.
1159 const char * title
1161 is the title on the top of the widget.
1162 const char * file
1164 is the name of the file to display in the dialog.
1165 int height
1167 is the desired height of the box. If zero, the height is based on
1168 the screen size.
1169 int width
1171 is the desired width of the box. If zero, the height is based on
1172 the screen size.
1173 dialog_timebox
1175 implements the "--timebox" option.
1176 const char * title
1178 is the title on the top of the widget.
1179 const char * subtitle
1181 is the prompt text shown within the widget.
1182 int height
1184 is the desired height of the box. If zero, the height is based on
1185 the screen size.
1186 int width
1188 is the desired width of the box. If zero, the height is based on
1189 the screen size.
1190 int hour
1192 is the initial hour shown. If the value is negative, the current
1193 hour is used. Returns DLG_EXIT_ERROR if the value specified is
1194 greater than or equal to 24.
1195 int minute
1197 is the initial minute shown. If the value is negative, the cur‐
1198 rent minute is used. Returns DLG_EXIT_ERROR if the value speci‐
1199 fied is greater than or equal to 60.
1200 int second
1202 is the initial second shown. If the value is negative, the cur‐
1203 rent second is used. Returns DLG_EXIT_ERROR if the value speci‐
1204 fied is greater than or equal to 60.
1205 dialog_treeview
1207 implements the "--treeview" option.
1208 const char * title
1210 is the title on the top of the widget.
1211 const char * cprompt
1213 is the prompt text shown within the widget.
1214 int height
1216 is the desired height of the box. If zero, the height is based on
1217 the screen size.
1218 int width
1220 is the desired width of the box. If zero, the height is based on
1221 the screen size.
1222 int list_height
1224 is the minimum height to reserve for displaying the list. If
1225 zero, it is computed based on the given height and width.
1226 int item_no
1228 is the number of rows in items.
1229 char ** items
1231 is the list of items, contain tag, name, and optionally help
1232 strings (if dialog_vars.item_help is set). The initial selection
1233 state for each item is also in this list.
1234 int flag
1236 flag is either FLAG_CHECK, for checklists (multiple selections), or
1238 FLAG_RADIO for radiolists (a single selection).
1239 dialog_yesno
1241 implements the "--yesno" option.
1242 const char * title
1244 is the title on the top of the widget.
1245 const char * cprompt
1247 is the prompt text shown within the widget.
1248 int height
1250 is the desired height of the box. If zero, the height is based on
1251 the screen size.
1252 int width
1254 is the desired width of the box. If zero, the height is based on
1255 the screen size.
1256
1258 Most functions that implement lower-level functionality for the com‐
1259 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
1260 ing to longstanding usage, the functions that initialize the display
1261 and end it are named init_dialog and end_dialog.
1262 The only non-widget function whose name begins with "dialog_" is dia‐
1264 log_version, which returns the version number of the library as a
1265 string.
1266 Here is a brief summary of the utility functions and their parameters:
1268 dlg_add_callback
1270 Add a callback, used to allow polling input from multiple tailbox wid‐
1271 gets.
1272 DIALOG_CALLBACK *p
1274 contains the callback information.
1275 dlg_add_callback_ref
1277 Like dlg_add_callback, but passes a reference to the DIALOG_CALLBACK as
1278 well as a pointer to a cleanup function which will be called when the
1279 associated input ends.
1280 DIALOG_CALLBACK **p
1282 points to the callback information. This is a reference to the
1283 pointer so that the caller's pointer can be zeroed when input
1284 ends.
1285 DIALOG_FREEBACK func
1287 function to call when input ends, e.g., to free caller's addi‐
1288 tional data.
1289 dlg_add_help_formitem
1291 This is a utility function used enforce consistent behavior for the
1292 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1293 int *result
1295 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1296 set.
1297 char **tag
1299 the tag- or help-text is stored here.
1300 DIALOG_FORMITEM *item
1302 contains the list item to use for tag- or help-text.
1303 dlg_add_help_listitem
1305 This is a utility function used enforce consistent behavior for the
1306 DIALOG_VARS.help_tags and DIALOG_VARS.item_help variables.
1307 int *result
1309 this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is
1310 set.
1311 char **tag
1313 the tag- or help-text is stored here.
1314 DIALOG_LISTITEM *item
1316 contains the list item to use for tag- or help-text.
1317 dlg_add_last_key
1319 Report the last key entered by the user. This implements the --last-
1320 key command-line option, using dialog_vars.last_key.
1321 int mode
1323 controls the way the last key report is separated from other
1324 results:
1325 -2 (no separator)
1327 -1 (separator after the key name)
1329 0 (separator is optionally before the key name)
1331 1 (same as -1)
1333 dlg_add_quoted
1335 Add a quoted string to the result buffer (see dlg_add_result). If no
1336 quotes are necessary, none are used. If dialog_vars.single_quoted is
1337 set, single-quotes are used. Otherwise, double-quotes are used.
1338 char * string
1340 is the string to add.
1341 dlg_add_result
1343 Add a string to the result buffer dialog_vars.input_result.
1344 char * string
1346 is the string to add.
1347 dlg_add_separator
1349 Add an output-separator to the result buffer dialog_vars.input_result.
1350 If dialog_vars.output_separator is set, use that. Otherwise, if dia‐
1351 log_vars.separate_output is set, use newline. If neither is set, use a
1352 space.
1353 dlg_add_string
1355 Add a quoted or unquoted string to the result buffer (see
1356 dlg_add_quoted) and dlg_add_result), according to whether dia‐
1357 log_vars.quoted is true.
1358 char * string
1360 is the string to add.
1361 dlg_align_columns
1363 Copy and reformat an array of pointers to strings, aligning according
1364 to the column separator dialog_vars.column_separator. If no column
1365 separator is set, the array will be unmodified; otherwise it is copied
1366 and reformatted.
1367 Caveat: This function is only implemented for 8-bit characters.
1369 char **target
1371 This is the array to reformat. It points to the first string to
1372 modify.
1373 int per_row
1375 This is the size of the struct for each row of the array.
1376 int num_rows
1378 This is the number of rows in the array.
1379 dlg_allocate_gauge
1381 Allocates a gauge widget. Use dlg_update_gauge to display the result.
1382 const char * title
1384 is the title string to display at the top of the widget.
1385 const char * cprompt
1387 is the prompt text shown within the widget.
1388 int height
1390 is the desired height of the box. If zero, the height is adjusted
1391 to use the available screen size.
1392 int width
1394 is the desired width of the box. If zero, the height is adjusted
1395 to use the available screen size.
1396 int percent
1398 is the percentage to show in the progress bar.
1399 dlg_asciibox
1401 returns its parameter transformed to the corresponding "+" or "-",
1402 etc., for the line-drawing characters used in dialog. If the parameter
1403 is not a line-drawing or other special character such as ACS_DARROW, it
1404 returns 0.
1405 chtype ch
1407 is the parameter, usually one of the ACS_xxx constants.
1408 dlg_attr_clear
1410 Set window to the given attribute.
1411 WINDOW * win
1413 is the window to update.
1414 int height
1416 is the number of rows to update.
1417 int width
1419 is the number of columns to update.
1420 chtype attr
1422 is the attribute, e.g., A_BOLD.
1423 dlg_auto_size
1425 Compute window size based on the size of the formatted prompt and mini‐
1426 mum dimensions for a given widget.
1427 Dialog sets dialog_state.text_height and dialog_state.text_width for
1429 the formatted prompt as a side-effect.
1430 Normally dialog writes the formatted prompt to the curses window, but
1432 it will write the formatted prompt to the output stream if dia‐
1433 log_state.text_only is set.
1434 const char * title
1436 is the title string to display at the top of the widget.
1437 const char * prompt
1439 is the message text which will be displayed in the widget, used
1440 here to determine how large the widget should be.
1441 If the value is NULL, dialog allows the widget to use the whole
1443 screen, i.e., if the values referenced by height and/or width are
1444 zero.
1445 int * height
1447 is the nominal height. Dialog checks the referenced value and may
1448 update it:
1449 · if the value is negative, dialog updates it to the available
1451 height of the screen, after reserving rows for the window bor‐
1452 der and shadow, as well as taking into account dia‐
1453 log_vars.begin_y and dialog_vars.begin_set.
1454 · if the value is zero, dialog updates it to the required height
1456 of the window, taking into account a (possibly) multi-line
1457 prompt.
1458 · if the value is greater than zero, dialog uses it internally,
1460 but restores the value on return.
1461 int * width
1463 is the nominal width. Dialog checks the referenced value and may
1464 update it:
1465 · if the value is negative, dialog updates it to the available
1467 width of the screen, after reserving rows for the window bor‐
1468 der and shadow, as well as taking into account dia‐
1469 log_vars.begin_x and dialog_vars.begin_set.
1470 · if the value is zero, dialog updates it to the required width
1472 of the window, taking into account a (possibly) multi-line
1473 prompt.
1474 · if the value is greater than zero, dialog uses it internally,
1476 but restores the value on return.
1477 int boxlines
1479 is the number of lines to reserve in the vertical direction.
1480 int mincols
1482 is the minimum number of columns to use.
1483 dlg_auto_sizefile
1485 Like dlg_auto_size, but use a file contents to decide how large the
1486 widget should be.
1487 const char * title
1489 is the title string to display at the top of the widget.
1490 const char * file
1492 is the name of the file.
1493 int * height
1495 is the nominal height.
1496 If it is -1, use the screen's height (after subtracting dia‐
1498 log_vars.begin_y if dialog_vars.begin_set is true).
1499 If it is greater than zero, limit the referenced value to the
1501 screen-height after verifying that the file exists.
1502 int * width
1504 is the nominal width.
1505 If it is -1, use the screen's width (after subtracting dia‐
1507 log_vars.begin_x if dialog_vars.begin_set is true).
1508 If it is greater than zero, limit the referenced value to the
1510 screen-width after verifying that the file exists.
1511 int boxlines
1513 is the number of lines to reserve on the screen for drawing boxes.
1514 int mincols
1516 is the number of columns to reserve on the screen for drawing
1517 boxes.
1518 dlg_beeping
1520 If dialog_vars.beep_signal is nonzero, this calls beep once and sets
1521 dialog_vars.beep_signal to zero.
1522 dlg_boxchar
1524 returns its chtype parameter transformed as follows:
1525 · if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is set.
1527 · if dialog_vars.ascii_lines is set, returns the corresponding "+" or
1529 "-", etc., for the line-drawing characters used in dialog.
1530 · otherwise, if dialog_vars.no_lines is set, returns a space for the
1532 line-drawing characters.
1533 · if the parameter is not a line-drawing or other special character
1535 such as ACS_DARROW, it returns the parameter unchanged.
1536 dlg_box_x_ordinate
1538 returns a suitable x-ordinate (column) for a new widget. If dia‐
1539 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center the
1540 widget on the screen (using the width parameter).
1541 int width
1543 is the width of the widget.
1544 dlg_box_y_ordinate
1546 returns a suitable y-ordinate (row) for a new widget. If dia‐
1547 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center the
1548 widget on the screen (using the height parameter).
1549 int height
1551 is the height of the widget.
1552 dlg_buildlist
1554 This is an alternate interface to the buildlist widget which allows the
1555 application to read the list item states back directly without putting
1556 them in the output buffer.
1557 const char * title
1559 is the title string to display at the top of the widget.
1560 const char * cprompt
1562 is the prompt text shown within the widget.
1563 int height
1565 is the desired height of the box. If zero, the height is adjusted
1566 to use the available screen size.
1567 int width
1569 is the desired width of the box. If zero, the height is adjusted
1570 to use the available screen size.
1571 int list_height
1573 is the minimum height to reserve for displaying the list. If
1574 zero, it is computed based on the given height and width.
1575 int item_no
1577 is the number of rows in items.
1578 DIALOG_LISTITEM * items
1580 is the list of items, contain tag, name, and optionally help
1581 strings (if dialog_vars.item_help is set). The initial selection
1582 state for each item is also in this list.
1583 const char * states
1585 This is a list of characters to display for the given states.
1586 Normally a buildlist provides true (1) and false (0) values, which
1587 the widget displays as "*" and space, respectively. An applica‐
1588 tion may set this parameter to an arbitrary null-terminated
1589 string. The widget determines the number of states from the
1590 length of this string, and will cycle through the corresponding
1591 display characters as the user presses the space-bar.
1592 int order_mode
1594 is reserved for future enhancements
1595 int * current_item
1597 The widget sets the referenced location to the index of the cur‐
1598 rent display item (cursor) when it returns.
1599 dlg_button_count
1601 Count the buttons in the list.
1602 const char ** labels
1604 is a list of (pointers to) button labels terminated by a null
1605 pointer.
1606 dlg_button_key
1608 If a key was bound to one of the button-codes in dlg_result_key, fake a
1609 button-value and an “Cancel” key to cause the calling widget to return
1610 the corresponding status.
1611 See dlg_ok_buttoncode, which maps settings for ok/extra/help and button
1613 number into exit-code.
1614 dlg_button_layout
1616 Make sure there is enough space for the buttons by computing the width
1617 required for their labels, adding margins and limiting based on the
1618 screen size.
1619 const char ** labels
1621 is a list of (pointers to) button labels terminated by a null
1622 pointer.
1623 int * limit
1625 the function sets the referenced limit to the width required for
1626 the buttons (limited by the screen size) if that is wider than the
1627 passed-in limit.
1628 dlg_button_sizes
1630 Compute the size of the button array in columns.
1631 const char ** labels
1633 is a list of (pointers to) button labels terminated by a null
1634 pointer.
1635 int vertical
1637 is true if the buttons are arranged in a column rather than a row.
1638 int * longest
1640 Return the total number of columns in the referenced location.
1641 int * length
1643 Return the longest button's columns in the referenced location.
1644 dlg_button_to_char
1646 Find the first uppercase character in the label, which we may use for
1647 an abbreviation. If the label is empty, return -1. If no uppercase
1648 character is found, return 0. Otherwise return the uppercase charac‐
1649 ter.
1650 Normally dlg_draw_buttons and dlg_char_to_button use the first upper‐
1652 case character. However, they keep track of all of the labels and if
1653 the first has already been used in another label, they will continue
1654 looking for another uppercase character. This function does not have
1655 enough information to make that check.
1656 const char * label
1658 is the label to test.
1659 dlg_button_x_step
1661 Compute the step-size needed between elements of the button array.
1662 const char ** labels
1664 is a list of (pointers to) button labels terminated by a null
1665 pointer.
1666 int limit
1668 is the maximum number of columns to allow for the buttons.
1669 int * gap
1671 store the nominal gap between buttons in the referenced location.
1672 This is constrained to be at least one.
1673 int * margin
1675 store the left+right total margins (for the list of buttons) in
1676 the referenced location.
1677 int * step
1679 store the step-size in the referenced location.
1680 dlg_calc_list_width
1682 Calculate the minimum width for the list, assuming none of the items
1683 are truncated.
1684 int item_no
1686 is the number of items.
1687 DIALOG_LISTITEM * items
1689 contains a name and text field, e.g., for checklists or radiobox
1690 lists. The function returns the sum of the widest columns needed
1691 for of each of these fields.
1692 If dialog_vars.no_items is set, the text fields in the list are
1694 ignored.
1695 dlg_calc_listh
1697 Calculate new height and list_height values.
1698 int * height
1700 on input, is the height without adding the list-height. On
1701 return, this contains the total list-height and is the actual wid‐
1702 get's height.
1703 int * list_height
1705 on input, is the requested list-height. On return, this contains
1706 the number of rows available for displaying the list after taking
1707 into account the screen size and the dialog_vars.begin_set and
1708 dialog_vars.begin_y variables.
1709 int item_no
1711 is the number of items in the list.
1712 dlg_calc_listw
1714 This function is obsolete, provided for library-compatibility. It is
1715 replaced by dlg_calc_list_width.
1716 int item_no
1718 is the number of items.
1719 char ** items
1721 is a list of character pointers.
1722 int group
1724 is the number of items in each group, e.g., the second array
1725 index.
1726 dlg_char_to_button
1728 Given a list of button labels, and a character which may be the abbre‐
1729 viation for one, find it, if it exists. An abbreviation will be the
1730 first character which happens to be capitalized in the label. If the
1731 character is found, return its index within the list of labels. Other‐
1732 wise, return DLG_EXIT_UNKNOWN.
1733 int ch
1735 is the character to find.
1736 const char ** labels
1738 is a list of (pointers to) button labels terminated by a null
1739 pointer.
1740 dlg_checklist
1742 This entrypoint provides the --checklist or --radiolist functionality
1743 without the limitations of dialog's command-line syntax (compare to
1744 dialog_checklist).
1745 const char * title
1747 is the title string to display at the top of the widget.
1748 const char * cprompt
1750 is the prompt text shown within the widget.
1751 int height
1753 is the desired height of the box. If zero, the height is adjusted
1754 to use the available screen size.
1755 int width
1757 is the desired width of the box. If zero, the height is adjusted
1758 to use the available screen size.
1759 int list_height
1761 is the minimum height to reserve for displaying the list. If
1762 zero, it is computed based on the given height and width.
1763 int item_no
1765 is the number of items.
1766 DIALOG_LISTITEM * items
1768 This is a list of the items to display in the checklist.
1769 const char * states
1771 This is a list of characters to display for the given states.
1772 Normally a checklist provides true (1) and false (0) values, which
1773 the widget displays as "*" and space, respectively. An applica‐
1774 tion may set this parameter to an arbitrary null-terminated
1775 string. The widget determines the number of states from the
1776 length of this string, and will cycle through the corresponding
1777 display characters as the user presses the space-bar.
1778 int flag
1780 This is should be one of FLAG_CHECK or FLAG_RADIO, depending on
1781 whether the widget should act as a checklist or radiobox.
1782 int * current_item
1784 The widget sets the referenced location to the index of the cur‐
1785 rent display item (cursor) when it returns.
1786 dlg_check_scrolled
1788 given a function key (or other key that was mapped to a function key),
1789 check if it is one of the up/down scrolling functions:
1790 DLGK_PAGE_FIRST,
1792 DLGK_PAGE_LAST,
1793 DLGK_GRID_UP,
1794 DLGK_GRID_DOWN,
1795 DLGK_PAGE_PREV or
1796 DLGK_PAGE_NEXT.
1797 Some widgets use these key bindings for scrolling the prompt-text up
1799 and down, to allow for display in very small windows.
1800 The function returns 0 (zero) if it finds one of these keys, and -1 if
1802 not.
1803 int key
1805 is the function-key to check
1806 int last
1808 is the number of lines which would be used to display the scrolled
1809 prompt in an arbitrarily tall window. It is used here to check
1810 limits for the offset value.
1811 int page
1813 this is the available height for writing scrolled text, which is
1814 smaller than the window if it contains buttons.
1815 bool * show
1817 on return, holds TRUE if dlg_print_scrolled should be used to
1818 redisplay the prompt text.
1819 int * offset
1821 on entry, holds the starting line number (counting from zero) last
1822 used for dlg_print_scrolled. On return, holds the updated start‐
1823 ing line number.
1824 dlg_clear
1826 Set window to the default dialog screen attribute. This is set in the
1827 rc-file with screen_color.
1828 dlg_clr_result
1830 Free storage used for the result buffer (dialog_vars.input_result).
1831 The corresponding pointer is set to NULL.
1832 dlg_color_count
1834 Return the number of colors that can be configured in dialog.
1835 dlg_color_setup
1837 Initialize the color pairs used in dialog.
1838 dlg_count_argv
1840 Count the entries in an argument vector.
1841 argv Points to the argument vector.
1843 dlg_count_columns
1845 Returns the number of columns used for a string. This is not necessar‐
1846 ily the number of bytes in a string.
1847 const char * string
1849 is the string to measure.
1850 dlg_count_real_columns
1852 Returns the number of columns used for a string, accounting for "\Z"
1853 sequences which can be used for coloring the text if dialog_vars.colors
1854 is set. This is not necessarily the number of bytes in a string.
1855 const char * string
1857 is the string to measure.
1858 dlg_count_wchars
1860 Returns the number of wide-characters in the string.
1861 const char * string
1863 is the string to measure.
1864 dlg_create_rc
1866 Create a configuration file, i.e., write internal tables to a file
1867 which can be read back by dialog as an rc-file.
1868 const char * filename
1870 is the name of the file to write to.
1871 dlg_ctl_size
1873 If dialog_vars.size_err is true, check if the given window size is too
1874 large to fit on the screen. If so, exit with an error reporting the
1875 size of the window.
1876 int height
1878 is the window's height
1879 int width
1881 is the window's width
1882 dlg_default_button
1884 If dialog_vars.default_button is positive, return the button-index for
1885 that button code, using dlg_ok_buttoncode to test indices starting with
1886 zero. Otherwise (or if no match was found for the button code), return
1887 zero.
1888 dlg_default_formitem
1890 If dialog_vars.default_item is not null, find that name by matching the
1891 name field in the list of form items. If found, return the index of
1892 that item in the list. Otherwise, return zero.
1893 DIALOG_FORMITEM * items
1895 is the list of items to search. It is terminated by an entry with
1896 a null name field.
1897 dlg_default_item
1899 This function is obsolete, provided for library-compatibility. It is
1900 replaced by dlg_default_formitem and dlg_default_listitem.
1901 char ** items
1903 is the list of items to search.
1904 int llen
1906 is the number of items in each group, e.g., the second array
1907 index.
1908 dlg_defaultno_button
1910 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not, find
1911 the button-index for the “Cancel” button. Otherwise, return the index
1912 for “OK” (always zero).
1913 dlg_del_window
1915 Remove a window, repainting everything else.
1916 WINDOW * win
1918 is the window to remove.
1919 dlg_does_output
1921 This is called each time a widget is invoked which may do output. It
1922 increments dialog_state.output_count, so the output function in dialog
1923 can test this and add a separator.
1924 dlg_draw_arrows
1926 Draw up/down arrows on a window, e.g., for scrollable lists. It calls
1927 dlg_draw_arrows2 using the menubox_color and menubox_border_color
1928 attributes.
1929 WINDOW * dialog
1931 is the window on which to draw an arrow.
1932 int top_arrow
1934 is true if an up-arrow should be drawn at the top of the window.
1935 int bottom_arrow
1937 is true if an down-arrow should be drawn at the bottom of the win‐
1938 dow.
1939 int x
1941 is the zero-based column within the window on which to draw
1942 arrows.
1943 int top
1945 is the zero-based row within the window on which to draw up-arrows
1946 as well as a horizontal line to show the window's top.
1947 int bottom
1949 is the zero-based row within the window on which to draw down-
1950 arrows as well as a horizontal line to show the window's bottom.
1951 dlg_draw_arrows2
1953 Draw up/down arrows on a window, e.g., for scrollable lists.
1954 WINDOW * dialog
1956 is the window on which to draw an arrow.
1957 int top_arrow
1959 is true if an up-arrow should be drawn at the top of the window.
1960 int bottom_arrow
1962 is true if an down-arrow should be drawn at the bottom of the win‐
1963 dow.
1964 int x
1966 is the zero-based column within the window on which to draw
1967 arrows.
1968 int top
1970 is the zero-based row within the window on which to draw up-arrows
1971 as well as a horizontal line to show the window's top.
1972 int bottom
1974 is the zero-based row within the window on which to draw down-
1975 arrows as well as a horizontal line to show the window's bottom.
1976 chtype attr
1978 is the window's background attribute.
1979 chtype borderattr
1981 is the window's border attribute.
1982 dlg_draw_bottom_box
1984 Draw a partial box at the bottom of a window, e.g., to surround a row
1985 of buttons. It is designed to merge with an existing box around the
1986 whole window (see dlg_draw_box), so it uses tee-elements rather than
1987 corner-elements on the top corners of this box.
1988 WINDOW * win
1990 is the window to update.
1991 dlg_draw_bottom_box2
1993 Draw a partial box at the bottom of a window, e.g., to surround a row
1994 of buttons. It is designed to merge with an existing box around the
1995 whole window (see dlg_draw_box2), so it uses tee-elements rather than
1996 corner-elements on the top corners of this box.
1997 WINDOW * win
1999 is the window to update.
2000 chtype on_left
2002 is used to color the upper/left edges of the box, i.e., the tee-
2003 element and horizontal line
2004 chtype on_right
2006 is used to color the right edge of the box, i.e., the tee-element
2007 chtype on_inside
2009 is used to fill-color the inside of the box
2010 dlg_draw_box
2012 Draw a rectangular box with line drawing characters.
2013 WINDOW * win
2015 is the window to update.
2016 int y
2018 is the top row of the box.
2019 int x
2021 is the left column of the box.
2022 int height
2024 is the height of the box.
2025 int width
2027 is the width of the box.
2028 chtype boxchar
2030 is used to color the right/lower edges. It also is fill-color
2031 used for the box contents.
2032 chtype borderchar
2034 is used to color the upper/left edges.
2035 dlg_draw_box2
2037 Draw a rectangular box with line drawing characters.
2038 WINDOW * win
2040 is the window to update.
2041 int y
2043 is the top row of the box.
2044 int x
2046 is the left column of the box.
2047 int height
2049 is the height of the box.
2050 int width
2052 is the width of the box.
2053 chtype boxchar
2055 is used to fill-color for the box contents.
2056 chtype borderchar
2058 is used to color the upper/left edges.
2059 chtype borderchar2
2061 is used to color the right/lower edges.
2062 dlg_draw_buttons
2064 Print a list of buttons at the given position.
2065 WINDOW * win
2067 is the window to update.
2068 int y
2070 is the starting row.
2071 int x
2073 is the starting column.
2074 const char ** labels
2076 is a list of (pointers to) button labels terminated by a null
2077 pointer.
2078 int selected
2080 is the index within the list of the selected button.
2081 int vertical
2083 is true if the buttons are arranged in a column rather than a row.
2084 int limit
2086 is the number of columns (or rows if vertical) allowed for the
2087 display.
2088 dlg_draw_helpline
2090 draw the text in dialog_vars.help_line at the bottom of the given win‐
2091 dow.
2092 WINDOW * dialog
2094 is the window to modify.
2095 bool decorations
2097 if true, allow room for the scrolling arrows.
2098 dlg_draw_scrollbar
2100 If dialog_state.use_scrollbar is set, draw a scrollbar on the right
2101 margin of windows holding scrollable data. Also (whether or not the
2102 scrollbar is drawn), annotate the bottom margin of the window with the
2103 percentage of data by the bottom of that window, and call
2104 dlg_draw_arrows2 to put markers on the window showing when more data is
2105 available.
2106 WINDOW * win
2108 is the window in which the data is scrolled. Because left, right,
2109 top, bottom are passed as parameters, this window can contain
2110 additional data.
2111 long first_data
2113 is the zero-based index to the first row of data in the current
2114 window.
2115 long this_data
2117 is the zero-based index to the current row of data.
2118 long next_data
2120 is the zero-based index to the next data after the current row.
2121 long total_data
2123 is the total number of rows of data.
2124 int left
2126 is the zero-based left margin/column of the window. The up/down
2127 arrows are draw inset by 5 columns from this point.
2128 int right
2130 is the zero-based right margin/column of the window. The scroll‐
2131 bar is drawn flush against this column.
2132 int top
2134 is the zero-based row within the window on which to draw up-arrows
2135 as well as a horizontal line to show the window's top.
2136 int bottom
2138 is the zero-based row within the window on which to draw down-
2139 arrows as well as a horizontal line to show the window's bottom.
2140 chtype attr
2142 is the window's background attribute.
2143 chtype borderattr
2145 is the window's border attribute.
2146 dlg_draw_shadow
2148 Draw shadows along the right and bottom edge of a window to give it a
2149 3-dimensional look. (The height, etc., may not be the same as the win‐
2150 dow's actual values).
2151 WINDOW * win
2153 is the window to update.
2154 int height
2156 is the height of the window.
2157 int width
2159 is the width of the window.
2160 int y
2162 is the top row of the window.
2163 int x
2165 is the left column of the window.
2166 dlg_draw_title
2168 Draw a title centered at the top of the window.
2169 WINDOW * win
2171 is the window to update.
2172 const char * title
2174 is the title string to display at the top of the widget.
2175 dlg_dummy_menutext
2177 This is a utility function which supports the --inputmenu option of the
2178 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
2179 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
2180 it passes dlg_dummy_menutext.
2181 The function should only return DLG_EXIT_ERROR.
2183 DIALOG_LISTITEM * items
2185 is the list of menu items
2186 int current
2188 is the index of the currently-selected item
2189 char * newtext
2191 is the updated text for the menu item
2192 dlg_dump_keys
2194 Write all user-defined key-bindings to the given stream, e.g., as part
2195 of dlg_create_rc.
2196 FILE * fp
2198 is the stream on which to write the bindings.
2199 dlg_dump_window_keys
2201 Write all user-defined key-bindings to the given stream, e.g., as part
2202 of dlg_create_rc.
2203 FILE * fp
2205 is the stream on which to write the bindings.
2206 WINDOW * win
2208 is the window for which bindings should be dumped. If it is null,
2209 then only built-in bindings are dumped.
2210 dlg_eat_argv
2212 Remove one or more items from an argument vector.
2213 int * argcp
2215 in/out parameter giving the length of the argument vector. char
2216 *** argvp in/out parameter pointing to the argument vector. int
2217 start starting index. int count number of arguments to remove.
2218 dlg_edit_offset
2220 Given the character-offset in the string, returns the display-offset
2221 where dialog should position the cursor. In this context, “characters”
2222 may be multicolumn, since the string can be a multibyte character
2223 string.
2224 char * string
2226 is the string to analyze
2227 int offset
2229 is the character-offset
2230 int x_last
2232 is a limit on the column positions that can be used, e.g., the
2233 window's size.
2234 dlg_edit_string
2236 Updates the string and character-offset, given various editing charac‐
2237 ters or literal characters which are inserted at the character-offset.
2238 Returns true if an editing change was made (and the display should be
2239 updated), and false if the key was something like KEY_ENTER, which is a
2240 non-editing action outside this function.
2241 char * string
2243 is the (multibyte) string to update
2244 int * offset
2246 is the character-offset
2247 int key
2249 is the editing key
2250 int fkey
2252 is true if the editing key is a function-key
2253 bool force
2255 is used in a special loop case by calling code to force the return
2256 value of this function when a function-key code 0 is passed in.
2257 dlg_exit
2259 Given an internal exit code, check if the corresponding environment
2260 variable is set. If so, remap the exit code to match the environment
2261 variable. Finally call exit with the resulting exit code.
2262 int code
2264 is the internal exit code, e.g., DLG_EXIT_OK, which may be
2265 remapped.
2266 The dialog program uses this function to allow shell scripts to remap
2268 the exit codes so they can distinguish ESC from ERROR.
2269 dlg_exitcode2s
2271 Returns the name of an exit-code, e.g., “OK” for DLG_EXIT_OK.
2272 int code
2274 is an exit-code for dialog as defined in <dialog.h>.
2275 dlg_exitname2n
2277 Returns an exit-code as the reverse of dlg_exitcode2n, e.g., 0
2278 (DLG_EXIT_OK) for the “OK” string.
2279 const char * name
2281 is the name of an exit-code for dialog as defined in <dialog.h>
2282 but omitting the “DLG_EXIT_” prefix.
2283 dlg_exit_buttoncode
2285 Map the given button index for dlg_exit_label into dialog's exit-code.
2286 int button
2288 is the button index
2289 dlg_exit_label
2291 Return a list of button labels. If dialog_vars.extra_button is true,
2292 return the result of dlg_ok_labels. Otherwise, return a list with the
2293 “Exit” label and (if dialog_vars.help_button is set) the “Help” button
2294 as well.
2295 dlg_exiterr
2297 Quit program killing all tailboxbg widgets.
2298 const char * fmt
2300 is the format of the printf-like message to write.
2301 ...
2303 are the variables to apply to the fmt format.
2304 dlg_find_index
2306 Given the character-offset to find in the list, return the correspond‐
2307 ing array index.
2308 const int *list
2310 contains a list of character-offsets, i.e., indices into a string
2311 that denote the beginning of multibyte characters.
2312 int limit
2314 is the last index into list to search.
2315 int to_find
2317 is the character-offset to find.
2318 dlg_finish_string
2320 If DIALOG_STATE.finish_string is true, this function discards data used
2321 to speed up layout computations.
2322 const char * string
2324 is the address of the string whose data should be discarded. The
2325 address rather than contents is used as the unique identifier
2326 because some of the caching is used for editable input-fields.
2327 dlg_flush_getc
2329 Cancel the local data saved by dlg_last_getc.
2330 dlg_editbox
2332 This entrypoint provides the --editbox functionality without the limi‐
2333 tations of dialog's command-line syntax (compare to dialog_editbox).
2334 const char * title
2336 is the title string to display at the top of the widget.
2337 char *** list
2339 is a pointer to an array of char * pointers. The array is allo‐
2340 cated by the caller, and so are the strings to which it points.
2341 The dlg_editbox function may reallocate the array and the strings.
2342 int * rows
2344 points to the nominal length of list. The referenced value is
2345 updated iflist is reallocated.
2346 int height
2348 is the desired height of the box. If zero, the height is adjusted
2349 to use the available screen size.
2350 int width
2352 is the desired width of the box. If zero, the height is adjusted
2353 to use the available screen size.
2354 dlg_form
2356 This entrypoint provides the --form functionality without the limita‐
2357 tions of dialog's command-line syntax (compare to dialog_form).
2358 const char * title
2360 is the title string to display at the top of the widget.
2361 const char * cprompt
2363 is the prompt text shown within the widget.
2364 int height
2366 is the desired height of the box. If zero, the height is adjusted
2367 to use the available screen size.
2368 int width
2370 is the desired width of the box. If zero, the height is adjusted
2371 to use the available screen size.
2372 int form_height
2374 is the minimum height to reserve for displaying the list. If
2375 zero, it is computed based on the given height and width.
2376 int item_no
2378 is the number of items.
2379 DIALOG_FORMITEM * items
2381 This is a list of the items to display in the form.
2382 int * current_item
2384 The widget sets the referenced location to the index of the cur‐
2385 rent display item (cursor) when it returns.
2386 dlg_free_columns
2388 Free data allocated by dlg_align_columns.
2389 char **target
2391 This is the array which was reformatted. It points to the first
2392 string to free.
2393 int per_row
2395 This is the size of the struct for each row of the array.
2396 int num_rows
2398 This is the number of rows in the array.
2399 dlg_free_formitems
2401 Free memory owned by a list of DIALOG_FORMITEM's.
2402 DIALOG_FORMITEM * items
2404 is the list to free.
2405 dlg_free_gauge
2407 Remove the gauge widget from the screen and free its associated memory.
2408 void *objptr
2410 points to the gauge widget.
2411 dlg_getc
2413 Read a character from the given window. Handle repainting here (to
2414 simplify things in the calling application). Also, if input-call‐
2415 back(s) are set up, poll the corresponding files and handle the
2416 updates, e.g., for displaying a tailbox. Returns the key-code.
2417 WINDOW * win
2419 is the window within which to read.
2420 int * fkey
2422 as a side-effect, set this to true if the key-code is really a
2423 function-key.
2424 dlg_get_attrs
2426 extract the video attributes from the given window.
2427 WINDOW * win
2429 is the window from which to get attributes.
2430 dlg_getc_callbacks
2432 passes the given key-code ch to the current window that has established
2433 a callback. If the callback returns zero, remove it and try the next
2434 window. If no more callbacks remain, return. If any callbacks were
2435 found, return true, otherwise false.
2436 int ch
2438 is the key-code
2439 int fkey
2441 is true if the key is a function-key
2442 int * result
2444 is used to pass an exit-code to the caller, which should pass that
2445 via dlg_exit.
2446 dlg_index_columns
2448 Build a list of the display-columns for the given multibyte string's
2449 characters.
2450 const char * string
2452 is the string to analyze
2453 dlg_index_wchars
2455 Build an index of the wide-characters in the string, so the caller can
2456 easily tell which byte-offset begins a given wide-character.
2457 const char * string
2459 is the string to analyze
2460 dlg_item_help
2462 Draw the string for the dialog_vars.item_help feature.
2463 const char * txt
2465 is the help-message
2466 dlg_killall_bg
2468 If dialog has callbacks active, purge the list of all that are not
2469 marked to keep in the background. If any remain, run those in a back‐
2470 ground process.
2471 int * retval
2473 stores the exit-code to pass back to the caller.
2474 dlg_last_getc
2476 returns the most recent character that was read via dlg_getc.
2477 dlg_limit_columns
2479 Given a column limit, count the number of wide characters that can fit
2480 into that limit. The offset is used to skip over a leading character
2481 that was already written.
2482 const char * string
2484 is the string to analyze
2485 int limit
2487 is the column limit
2488 int offset
2490 is the starting offset from which analysis should continue
2491 dlg_lookup_key
2493 Check for a key-binding. If there is no binding associated with the
2494 widget, it simply returns the given curses-key. Otherwise, it returns
2495 the result of the binding
2496 WINDOW * win
2498 is the window on which the binding is checked
2499 int curses_key
2501 is the curses key-code
2502 int * dialog_key
2504 is the corresponding dialog internal code (see DLG_KEYS_ENUM in
2505 dlg_key.h).
2506 dlg_max_input
2508 Limit the parameter according to dialog_vars.max_input
2509 int max_len
2511 is the value to limit
2512 dlg_match_char
2514 Match a given character against the beginning of the string, ignoring
2515 case of the given character. The matching string must begin with an
2516 uppercase character.
2517 int ch
2519 is the character to check
2520 const char * string
2522 is the string to search
2523 dlg_menu
2525 This entrypoint provides the --menu functionality without the limita‐
2526 tions of dialog's command-line syntax (compare to dialog_menu).
2527 const char * title
2529 is the title string to display at the top of the widget.
2530 const char * cprompt
2532 is the prompt text shown within the widget.
2533 int height
2535 is the desired height of the box. If zero, the height is adjusted
2536 to use the available screen size.
2537 int width
2539 is the desired width of the box. If zero, the height is adjusted
2540 to use the available screen size.
2541 int menu_height
2543 is the minimum height to reserve for displaying the list. If
2544 zero, it is computed based on the given height and width.
2545 int item_no
2547 is the number of items.
2548 DIALOG_LISTITEM * items
2550 This is a list of the items to display in the form.
2551 int * current_item
2553 The widget sets the referenced location to the index of the cur‐
2554 rent display item (cursor) when it returns.
2555 DIALOG_INPUTMENU rename_menutext
2557 If this is not dlg_dummy_menutext, the widget acts like an input‐
2558 menu widget, providing an extra “Rename” button, which activates
2559 an edit feature on the selected menu item.
2560 dlg_move_window
2562 Moves/resizes the given window to the given position and size.
2563 WINDOW *win
2565 is the window to move/resize.
2566 WINDOW *height
2568 is the height of the resized window.
2569 WINDOW *width
2571 is the width of the resized window.
2572 WINDOW *y
2574 y-ordinate to use for the repositioned window.
2575 WINDOW *x
2577 x-ordinate to use for the repositioned window.
2578 dlg_mouse_bigregion
2580 Retrieve the big-region under the pointer.
2581 int y
2583 is the row on which the mouse click occurred
2584 int x
2586 is the column on which the mouse click occurred
2587 dlg_mouse_free_regions
2589 Free the memory associated with mouse regions.
2590 dlg_mouse_mkbigregion
2592 Creates a region on which the mouse-clicks will return a specified
2593 code.
2594 int y
2596 is the top-row of the region.
2597 int x
2599 is the left-column of the region.
2600 int height
2602 is the height of the region.
2603 int width
2605 is the width of the region.
2606 int code
2608 is a code used to make the region unique within a widget
2609 int step_x
2611 is used in modes 2 (columns) and 3 (cells) to determine the width
2612 of a column/cell.
2613 int step_y
2615 is currently unused
2616 int mode
2618 is used to determine how the mouse position is translated into a
2619 code (like a function-key):
2620 1 index by lines
2622 2 index by columns
2624 3 index by cells
2626 dlg_mouse_mkregion
2628 int y
2629 is the top-row of the region.
2630 int x
2632 is the left-column of the region.
2633 int height
2635 is the height of the region.
2636 int width
2638 is the width of the region.
2639 int code
2641 is a code used to make the region unique within a widget
2642 dlg_mouse_region
2644 Retrieve the frame under the mouse pointer
2645 int y
2647 is the row of the mouse-click
2648 int x
2650 is the column of the mouse-click
2651 dlg_mouse_setbase
2653 Sets a base for subsequent calls to dlg_mouse_mkregion, so they can
2654 make regions relative to the start of a given window.
2655 int x
2657 is the left-column for the base
2658 int y
2660 is the top-row for the base
2661 dlg_mouse_setcode
2663 Sets a value used internally by dlg_mouse_mkregion which is added to
2664 the code parameter. By providing different values, e.g., multiples of
2665 KEY_MAX, it is possible to support multiple “big” regions in a widget.
2666 The buildlist widget uses this feature to recognize mouse-clicks in the
2667 left/right panes.
2668 int code
2670 is the value to add to dlg_mouse_mkregion's code parameter.
2671 dlg_mouse_wgetch
2673 is a wrapper for dlg_getc which additionally maps mouse-clicks (if the
2674 curses library supports those) into extended function-keys which encode
2675 the position according to the mode in dlg_mouse_mkbigregion. Returns
2676 the corresponding key-code.
2677 WINDOW * win
2679 is the window on which to perform the input
2680 int * fkey
2682 the referenced location is set to true if the key-code is an
2683 actual or extended (mouse) function-key.
2684 dlg_mouse_wgetch_nowait
2686 This is a non-blocking variant of dlg_mouse_wgetch.
2687 WINDOW * win
2689 is the window on which to perform the input
2690 int * fkey
2692 the referenced location is set to true if the key-code is an
2693 actual or extended (mouse) function-key.
2694 dlg_need_separator
2696 Check if an output-separator is needed. If dialog_vars.output_separa‐
2697 tor is set, return true. Otherwise, if dialog_vars.input_result is
2698 nonempty, return true. If neither, return false.
2699 dlg_new_modal_window
2701 Create a modal window, optionally with a shadow. The shadow is created
2702 if dialog_state.use_shadow is true.
2703 WINDOW * parent
2705 is the parent window (usually the top-level window of a widget)
2706 int height
2708 is the window's height
2709 int width
2711 is the window's width
2712 int y
2714 is the window's top-row
2715 int x
2717 is the window's left-column
2718 dlg_new_window
2720 Create a window, optionally with a shadow. The shadow is created if
2721 dialog_state.use_shadow is true.
2722 int height
2724 is the window's height
2725 int width
2727 is the window's width
2728 int y
2730 is the window's top-row
2731 int x
2733 is the window's left-column
2734 dlg_next_button
2736 Return the next index in the list of labels.
2737 const char ** labels
2739 is a list of (pointers to) button labels terminated by a null
2740 pointer.
2741 int button
2743 is the current button-index.
2744 dlg_next_ok_buttonindex
2746 Assuming that the caller is using dlg_ok_labels to list buttons, find
2747 the next index in the list of buttons.
2748 int current
2750 is the current index in the list of buttons
2751 int extra
2753 if negative, provides a way to enumerate extra active areas on the
2754 widget.
2755 dlg_ok_buttoncode
2757 Map the given button index for dlg_ok_labels into dialog's exit-code.
2758 int button
2760 is the button-index (which is not necessarily the same as the
2761 index in the list of labels).
2762 dlg_ok_button_key
2764 Calls dlg_button_key with the “Cancel” button disabled, e.g., for the
2765 textbox widget.
2766 dlg_ok_label
2768 Returns a list with the “Ok” label, and if dialog_vars.help_button is
2769 true, the “Help” label as well.
2770 dlg_ok_labels
2772 Return a list of button labels for the OK/Cancel group of widgets.
2773 dlg_ordinate
2775 Decode the string as an integer, decrement if greater than zero to make
2776 a curses-ordinate from a dialog-ordinate.
2777 dlg_parse_bindkey
2779 Parse the parameters of the “bindkeys” configuration-file entry. This
2780 expects widget name which may be "*", followed by curses key definition
2781 and then dialog key definition.
2782 char * params
2784 is the parameter string to parse.
2785 dlg_parse_rc
2787 Parse the configuration file and set up variables.
2788 dlg_popen
2790 Open a pipe which ties the standard error and output together. The
2791 popen function captures only the standard output of a command.
2792 const char *command
2794 The shell command to run.
2795 const char *type
2797 Like popen, "r" is used to read, and "w" is used to write.
2798 dlg_prev_button
2800 Return the previous index in the list of labels.
2801 const char ** labels
2803 is a list of (pointers to) button labels terminated by a null
2804 pointer.
2805 int button
2807 is the current button index
2808 dlg_print_listitem
2810 This is a helper function used for the various “list” widgets, e.g.,
2811 checklist, menu, buildlist, treeview. Each list-widget has “tag” and
2812 “description” values for each item which can be displayed. If dia‐
2813 log_vars.no_tags is true, the “tag” value is not shown. The first
2814 character of the first value shown (tag or description) is highlighted
2815 to indicate that the widget will match it for quick navigation.
2816 WINDOW *win
2818 the window in which to display the text
2819 const char *text
2821 the value to display
2822 int climit
2824 the number of columns available for printing the text
2825 bool first
2827 true if this is the first call (for “tag” and “description”), and
2828 the first character of the value should be highlighted.
2829 int selected
2831 nonzero if the text should be displayed using the “selected” col‐
2832 ors
2833 dlg_print_scrolled
2835 This is a wrapper for dlg_print_autowrap which allows the user to
2836 scroll too-long prompt text up/down.
2837 See dlg_check_scrolled for a function which updates the offset variable
2839 used as a parameter here. It complements this function; you need both.
2840 If pauseopt is set, this function returns an updated last parameter,
2841 needed for dlg_check_scrolled calls.
2842 WINDOW * win
2844 is the window to update.
2845 const char * prompt
2847 is the string to print
2848 int offset
2850 is the starting line-number to write wrapped text.
2851 int height
2853 is the available height for writing the wrapped text
2854 int width
2856 is the width that the wrapping should occur in
2857 int pauseopt
2859 is true if the extra functionality for scrolling should be
2860 enabled. If false, this calls dlg_print_autowrap without doing
2861 any scrolling.
2862 dlg_print_line
2864 Print one line of the prompt in the window within the limits of the
2865 specified right margin. The line will end on a word boundary and a
2866 pointer to the start of the next line is returned, or a NULL pointer if
2867 the end of *prompt is reached.
2868 WINDOW *win
2870 is the window to update.
2871 chtype *attr
2873 holds the starting attributes, and is updated to reflect the final
2874 attributes applied to the string.
2875 const char *prompt
2877 is the string to print
2878 int lm
2880 is the left margin.
2881 int rm
2883 is the right margin
2884 int *x
2886 returns the ending x-ordinate.
2887 dlg_prev_ok_buttonindex
2889 Find the previous button index in the list from dlg_ok_labels.
2890 int current
2892 is the current index
2893 int extra
2895 if negative provides a way to enumerate extra active areas on the
2896 widget.
2897 dlg_print_autowrap
2899 Print a string of text in a window, automatically wrap around to the
2900 next line if the string is too long to fit on one line. Note that the
2901 string may contain embedded newlines. The text is written starting at
2902 the top of the window.
2903 WINDOW * win
2905 is the window to update.
2906 const char * prompt
2908 is the string to print
2909 int height
2911 is the nominal height the wrapped string is limited to
2912 int width
2914 is the width that the wrapping should occur in
2915 dlg_print_size
2917 If dialog_vars.print_siz is true, print the given height/width (from a
2918 widget) to dialog_state.output, e.g., Size: height, width.
2919 int height
2921 is the window's height
2922 int width
2924 is the window's width
2925 dlg_print_text
2927 Print up to cols columns from text, optionally rendering dialog's
2928 escape sequences for attributes and color.
2929 WINDOW * win
2931 is the window to update.
2932 const char * txt
2934 is the string to print
2935 int col
2937 is the column limit
2938 chtype * attr
2940 holds the starting attributes, and is updated to reflect the final
2941 attributes applied to the string.
2942 dlg_progressbox
2944 implements the "--prgbox" and "--progressbox" options.
2945 const char * title
2947 is the title on the top of the widget.
2948 const char * cprompt
2950 is the prompt text shown within the widget. If empty or null, no
2951 prompt is shown.
2952 int height
2954 is the desired height of the box. If zero, the height is based on
2955 the screen size.
2956 int width
2958 is the desired width of the box. If zero, the height is based on
2959 the screen size.
2960 int pauseopt
2962 if true, an “OK” button will be shown, and the dialog will wait
2963 for it to complete. With an “OK” button, it is denoted a “pro‐
2964 grambox”, without an “OK” button, it is denoted a “progressbox”.
2965 FILE * fp
2967 is the file pointer, which may be a pipe or a regular file.
2968 dlg_put_backtitle
2970 Display the background title if dialog_vars.backtitle is non-null. The
2971 background title is shown at the top of the screen.
2972 dlg_reallocate_gauge
2974 Allocates or reallocates a gauge widget (see dlg_allocate_gauge). Use
2975 dlg_update_gauge to display the result.
2976 void ** objptr
2978 If the pointer referenced by this parameter is null, the function
2979 creates a new gauge widget using dlg_allocate_gauge. Otherwise,
2980 it updates the title and cprompt values, reusing the window from
2981 the previous call on this function. As a side-effect, the func‐
2982 tion stores the updated object-pointer via the objptr parameter.
2983 const char * title
2985 is the title string to display at the top of the widget.
2986 const char * cprompt
2988 is the prompt text shown within the widget.
2989 int height
2991 is the desired height of the box. If zero, the height is adjusted
2992 to use the available screen size.
2993 int width
2995 is the desired width of the box. If zero, the height is adjusted
2996 to use the available screen size.
2997 int percent
2999 is the percentage to show in the progress bar.
3000 dlg_register_buttons
3002 The widget developer should call this function after dlg_register_win‐
3003 dow, for the list of button labels associated with the widget. One may
3004 bind a key to a button, e.g., “OK” for DLGK_OK,
3005 WINDOW * win
3007 is the window with which to associate the buttons
3008 const char * name
3010 is the widget's binding name (usually the name of the widget).
3011 const char ** buttons
3013 is the list of buttons
3014 dlg_register_window
3016 For a given named widget's window, associate a binding table.
3017 WINDOW * win
3019 is the window with which to associate the buttons
3020 const char * name
3022 is the widget's binding name (usually the name of the widget).
3023 DLG_KEYS_BINDING * binding
3025 is the binding table
3026 dlg_remove_callback
3028 Remove a callback.
3029 DIALOG_CALLBACK * p
3031 contains the callback information.
3032 dlg_renamed_menutext
3034 This is a utility function which supports the --inputmenu option of the
3035 dialog program. If dialog_vars.input_menu is set, dialog_menu passes
3036 this pointer to dlg_menu as the rename_menutext parameter. Otherwise,
3037 it passes dlg_dummy_menutext.
3038 The function should add “RENAMED” to dialog_vars.input_result , fol‐
3040 lowed by the menu item's name and the newtext value (with a space sepa‐
3041 rating the three items), and return DLG_EXIT_EXTRA.
3042 DIALOG_LISTITEM * items
3044 is the list of menu items
3045 int current
3047 is the index of the currently-selected item
3048 char * newtext
3050 is the updated text for the menu item
3051 dlg_reset_timeout
3053 Calls wtimeout with the value saved for a window in the last call to
3054 dlg_set_timeout.
3055 dlg_restore_vars
3057 Restore dialog's variables from the given variable (see dia‐
3058 log_save_vars).
3059 DIALOG_VARS * save
3061 is the variable from which to restore.
3062 The DIALOG_VARS.input_length and DIALOG_VARS.input_result members are
3064 treated specially, since these are used by a widget to pass data to the
3065 caller. They are not modified by this function.
3066 dlg_result_key
3068 Test a dialog internal keycode to see if it corresponds to one of the
3069 push buttons on the widget such as “OK”. This is only useful if there
3070 are user-defined key bindings, since there are no built-in bindings
3071 that map directly to DLGK_OK, etc. Return true if a mapping was done.
3072 int dialog_key
3074 is the dialog key to test
3075 int fkey
3077 is true if this is a function key
3078 int * resultp
3080 store the result of the mapping in the referenced location.
3081 dlg_save_vars
3083 Save dialog's variables into the given variable (see dlg_restore_vars).
3084 DIALOG_VARS * save
3086 is the variable into which to save.
3087 dlg_set_focus
3089 Set focus on the given window, making it display above other windows on
3090 the screen.
3091 WINDOW * parent
3093 is the parent window (usually the top-level window of a widget)
3094 WINDOW * win
3096 is the window on which to place focus (usually a subwindow of a
3097 widget)
3098 dlg_set_result
3100 Setup a fixed-buffer for the result in dialog_vars.input_result
3101 const char * string
3103 is the new contents for the result
3104 dlg_set_timeout
3106 Calls wtimeout to establish a preferred timeout for nonblocking reads,
3107 e.g., to allow the gauge widget to handle window-resizing events. The
3108 dlg_may_resize function temporarily overrides this value, to allow it
3109 to skip over the error codes returned while the ncurses library pro‐
3110 cesses window-resizing events. It restores the value established in
3111 this call by calling dlg_restore_timeout.
3112 WINDOW * win
3114 is the window whose input-timeout should be set
3115 bool will_getc
3117 is true if the widget is expected to read keyboard characters.
3118 Some (such as the gauge widget) do not.
3119 dlg_show_string
3121 Displays the string, shifted as necessary, to fit within the box and
3122 show the current character-offset.
3123 WINDOW * win
3125 is the window within which to display
3126 const char * string
3128 is the string to display
3129 int offset
3131 is the starting (character, not bytes) offset
3132 chtype attr
3134 is the window attribute to use for the string
3135 int y_base
3137 beginning row on screen
3138 int x_base
3140 beginning column on screen
3141 int x_last
3143 number of columns on screen
3144 bool hidden
3146 if true, do not echo input
3147 bool force
3149 if true, force repaint
3150 dlg_strclone
3152 duplicate the string, like strdup.
3153 const char * cprompt
3155 is the string to duplicate
3156 dlg_strcmp
3158 compare two strings, ignoring case.
3159 const char * a
3161 is one string
3162 const char * b
3164 is the other string
3165 dlg_string_to_argv
3167 Convert a string to an argument vector returning an index (which must
3168 be freed by the caller). The string is modified:
3169 · Blanks between arguments are replaced by nulls.
3171 · Normally arguments are separated by blanks; however you can double-
3173 quote an argument to enclose blanks. The surrounding double-quotes
3174 are removed from the string.
3175 · A backslash preceding a double-quote within double-quotes is
3177 removed.
3178 · A backslash preceding a newline outside double-quotes is removed.
3180 · Except for special cases, backslashes are preserved in the strings,
3182 since other dialog functions interpret backslashes, e.g., for col‐
3183 ors.
3184 char *blob
3186 is the string to convert.
3187 dlg_sub_window
3189 create a subwindow, e.g., for an input area of a widget
3190 WINDOW * win
3192 is the parent window
3193 int height
3195 is the subwindow's height
3196 int width
3198 is the subwindow's width
3199 int y
3201 is the subwindow's top-row
3202 int x
3204 is the subwindow's left-column
3205 dlg_tab_correct_str
3207 If the dialog_vars.tab_correct is true, convert tabs to single spaces.
3208 Return the converted result. The caller is responsible for freeing the
3209 string.
3210 char * prompt
3212 is the string to convert
3213 dlg_trace
3215 If the parameter is non-null, opens a trace file with that name and
3216 stores the file pointer in dialog_state.trace.
3217 dlg_trace_2n
3219 logs a numeric value as a comment.
3220 char * name
3222 is the name to log in the comment.
3223 int value
3225 is the value to log in the comment.
3226 dlg_trace_2s
3228 logs a string value as a comment. If the value contains embedded new‐
3229 lines, the comment is continued with “#+” markers.
3230 char * name
3232 is the name to log in the comment.
3233 int value
3235 is the value to log in the comment.
3236 dlg_trace_chr
3238 If dialog_state.trace is set, translate the parameters into a printable
3239 representation, log it on a “chr” line.
3240 int ch
3242 is the nominal keycode value.
3243 int fkey
3245 is nonzero if the value is really a function key. Some of these
3246 may be values declared in the DLG_KEYS_ENUM.
3247 dlg_trace_msg
3249 Write a formatted message to the trace file.
3250 const char * fmt
3252 is the format of the printf-like message to write.
3253 ...
3255 are the variables to apply to the fmt format.
3256 Use the DLG_TRACE macro for portability, in case the trace feature is
3258 not compiled into the library. It uses an extra level of parentheses
3259 to work with a variable number of parameters, e.g.,
3260 DLG_TRACE(("this is dialog version %s\n", dialog_version()));
3262 dlg_trace_va_msg
3264 Write a formatted message to the trace file.
3265 const char *fmt
3267 is the format of the printf-like message to write.
3268 va_list ap
3270 are the variables to apply to the fmt format.
3271 This is used in dlg_exiterr to capture error messages in the trace
3273 file:
3274 va_start(ap, fmt);
3276 dlg_trace_msg("## Error: ");
3277 dlg_trace_va_msg(fmt, ap);
3278 va_end(ap);
3279 Unlike dlg_trace_msg, an extra macro is not needed.
3281 dlg_ttysize
3283 Returns the screensize without using curses. That allows the function
3284 to be used before initializing the screen.
3285 dlg_trace_win
3287 If dialog_state.trace is set, log a printable picture of the given win‐
3288 dow.
3289 dlg_treeview
3291 This is an alternate interface to 'treeview' which allows the applica‐
3292 tion to read the list item states back directly without putting them in
3293 the output buffer.
3294 const char * title
3296 is the title on the top of the widget.
3297 const char * cprompt
3299 is the prompt text shown within the widget.
3300 int height
3302 is the desired height of the box. If zero, the height is based on
3303 the screen size.
3304 int width
3306 is the desired width of the box. If zero, the height is based on
3307 the screen size.
3308 int list_height
3310 is the minimum height to reserve for displaying the list. If
3311 zero, it is computed based on the given height and width.
3312 int item_no
3314 is the number of rows in items.
3315 DIALOG_LISTITEM * items
3317 is the list of items, contain tag, name, and optionally help
3318 strings (if dialog_vars.item_help is set). The initial selection
3319 state for each item is also in this list.
3320 const char * states
3322 This is a list of characters to display for the given states.
3323 Normally a buildlist provides true (1) and false (0) values, which
3324 the widget displays as "*" and space, respectively. An applica‐
3325 tion may set this parameter to an arbitrary null-terminated
3326 string. The widget determines the number of states from the
3327 length of this string, and will cycle through the corresponding
3328 display characters as the user presses the space-bar.
3329 int * depths
3331 This is a list of depths of each item in the tree. It is a sepa‐
3332 rate parameter from items to allow reuse of the existing func‐
3333 tions.
3334 int flag
3336 is either FLAG_CHECK, for checklists (multiple selections), or
3337 FLAG_RADIO for radiolists (a single selection).
3338 int * current_item
3340 The widget sets the referenced location to the index of the cur‐
3341 rent display item (cursor) when it returns.
3342 dlg_trim_string
3344 The dialog program uses this in each widget to adjust the message
3345 string, which may contain the newline character (referred to as '\n')
3346 and/or the special substring "\n" (which can be translated into a new‐
3347 line character).
3348 There are several optional features:
3350 · Unless dialog_vars.nocollapse is set, each tab is converted to a
3352 space before other processing.
3353 · If dialog_vars.no_nl_expand is not set, and the string has "\n"
3355 substrings:
3356 · The function changes embedded "\n" substrings to '\n' charac‐
3358 ters.
3359 The function preserves extra spaces after these substitutions.
3361 For instance, spaces following a newline (substring or charac‐
3362 ter) are preserved to use as an indentation.
3363 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3365 line characters. Otherwise, each '\n' newline character is
3366 converted to a space.
3367 · Otherwise, if dialog_vars.trim_whitespace is set:
3369 · This function strips all extra spaces to simplify justifica‐
3371 tion.
3372 · If dialog_vars.cr_wrap is set, the function preserves '\n' new‐
3374 line characters. Otherwise, each '\n' newline character is
3375 converted to a space.
3376 · Finally (if dialog_vars.no_nl_expand is set, or the string does not
3378 contain "\n" substrings, and dialog_vars.trim_whitespace is not
3379 set):
3380 · Unless dialog_vars.nocollapse is set, sequences of spaces are
3382 reduced to a single space.
3383 char * src
3385 is the string to trim
3386 dlg_unregister_window
3388 Remove the bindings for a given window.
3389 WINDOW * win
3391 is the window from which to remove bindings
3392 dlg_update_gauge
3394 Update a gauge widget to show a different percentage value.
3395 void *objptr
3397 points to the gauge object to update.
3398 int percent
3400 is the new percentage value to display.
3401 dlg_will_resize
3403 This filters out bursts of KEY_RESIZE values. Call this after dlg_getc
3404 returns KEY_RESIZE, to improve performance.
3405 dlg_yes_buttoncode
3407 Map the given button index for dlg_yes_labels into dialog's exit-code.
3408 int button
3410 is the button index
3411 dlg_yes_labels
3413 Return a list of buttons for Yes/No labels.
3414 end_dialog
3416 End use of dialog functions.
3417 init_dialog
3419 Do some initialization for dialog.
3420 FILE *input
3422 is the real tty input of dialog. Usually it is the standard
3423 input, but if --input-fd option is used, it may be anything.
3424 FILE *output
3426 is where dialog will send its result. Usually it is the standard
3427 error, but if --stdout or --output-fd is used, it may be anything.
3428
3430 dialog (1).
3431
3433 Thomas E. Dickey
3434$Date: 2020/03/24 00:26:28 $ DIALOG(3)