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 #include <dialog.h>
12 Dialog is a program that will let you to present a variety of questions
14 or display messages using dialog boxes from a shell script. It is
15 built from the dialog library, which consists of several widgets as
16 well as utility functions that are used by the widgets or the main pro‐
17 gram.
18
20 This manpage documents the features from <dialog.h> which are likely to
21 be important to developers using the widgets directly. Some hints are
22 also given for developing new widgets.
23
25 Exit codes (passed back to the main program for its use) are defined
26 with a "DLG_EXIT_ prefix. The defined constants can be mapped using
27 environment variables as described in dialog(1), e.g., DLG_EXIT_OK cor‐
28 responds to $DIALOG_OK.
29 Useful character constants which correspond to user input are named
31 with the "CHR_" prefix, e.g., CHR_BACKSPACE.
32 Colors and video attributes are categorized and associated with set‐
34 tings in the configuration file (see the discussion of $DIALOGRC in
35 dialog(1)). The DIALOG_ATR(n) macro is used for defining the refer‐
36 ences to the combined color and attribute table dlg_color_table[].
37 The dialog application passes its command-line parameters to the widget
39 functions. Some of those parameters are single values, but some of the
40 widgets accept data as an array of values. Those include check‐
41 list/radiobox, menubox and formbox. When the --item-help option is
42 given, an extra column of data is expected. The USE_ITEM_HELP(),
43 CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS macros are used to hide
44 this difference from the calling application.
45 Most of the other definitions found in <dialog.h> are used for conve‐
47 nience in building the library or main program. These include defini‐
48 tions based on the generated <dlg_config.h> header.
49
52 All of the global data for the dialog library is stored in a few struc‐
53 tures: DIALOG_STATE, DIALOG_VARS and DIALOG_COLORS. The corresponding
54 dialog_state, dialog_vars and dlg_color_table global variables should
55 be initialized to zeros, and then populated with the data to use. A
56 few of these must be nonzero for the corresponding widgets to function.
57 As as the case with function names, variables beginning with "dialog_"
58 are designed for use by the calling application while variables begin‐
59 ning with "dlg_" are intended for lower levels, e.g., by the dialog
60 library.
61 DIALOG_STATE.all_windows
63 This is a linked list of all windows created by the library.
64 The dlg_del_window function uses this to locate windows which
65 may be redrawn after deleting a window.
66 DIALOG_STATE.aspect_ratio
68 This corresponds to the command-line option "--aspect-ratio".
69 The value gives the application some control over the box dimen‐
70 sions when using auto sizing (specifying 0 for height and
71 width). It represents width / height. The default is 9, which
72 means 9 characters wide to every 1 line high.
73 DIALOG_STATE.getc_callbacks
75 This is setup in ui_getc.c to record windows which must be
76 polled for input, e.g,. to handle the background tailbox widget.
77 One window is designated as the foreground or control window.
78 DIALOG_STATE.getc_redirect
80 If the control window for DIALOG_STATE.getc_callbacks is closed,
81 the list is transferred to this variable. Closing all windows
82 causes the application to exit.
83 DIALOG_STATE.output
85 This is set in the dialog application to the stream on which the
86 application and library functions may write text results. Nor‐
87 mally that is the standard error, since the curses library
88 prefers to write its data to the standard output. Some scripts,
89 trading portability for convenience, prefer to write results to
90 the standard output, e.g., by using the "--stdout" option.
91 DIALOG_STATE.output_count
93 This is incremented by dlg_does_output, which is called by each
94 widget that writes text to the output. The dialog application
95 uses that to decide if it should also write a separator, i.e.,
96 DIALOG_STATE.separate_str, between calls to each widget.
97 DIALOG_STATE.pipe_input
99 This is set in init_dialog to a stream which can be used by the
100 gauge widget, which must be the application's standard input.
101 The dialog application calls init_dialog normally with input set
102 to the standard input, but optionally based on the "--input-fd"
103 option. Since the application cannot read from a pipe (standard
104 input) and at the same time read the curses input from the stan‐
105 dard input, it must allow for reopening the latter from either a
106 specific file descriptor, or directly from the terminal. The
107 adjusted pipe stream value is stored in this variable.
108 DIALOG_STATE.screen_initialized
110 This is set in init_dialog and reset in end_dialog. It is used
111 to check if curses has been initialized, and if the endwin func‐
112 tion must be called on exit.
113 DIALOG_STATE.screen_output
115 This is set in init_dialog to the output stream used by the
116 curses library. Normally that is the standard output, unless
117 that happens to not be a terminal (and if init_dialog can suc‐
118 cessfully open the terminal directly).
119 DIALOG_STATE.separate_str
121 This corresponds to the command-line option "--separate-widget".
122 The given string specifies a string that will separate the out‐
123 put on dialog's output from each widget. This is used to sim‐
124 plify parsing the result of a dialog with several widgets. If
125 this option is not given, the default separator string is a tab
126 character.
127 DIALOG_STATE.tab_len
129 This corresponds to the command-line option "--tab-len number".
130 Specify the number of spaces that a tab character occupies if
131 the "--tab-correct" option is given. The default is 8.
132 DIALOG_STATE.use_colors
134 This is set in init_dialog if the curses implementation supports
135 color.
136 DIALOG_STATE.use_scrollbar
138 This corresponds to the command-line option "--scrollbar". If
139 true, draw a scrollbar to make windows holding scrolled data
140 more readable.
141 DIALOG_STATE.use_shadow
143 This corresponds to the command-line option "--no-shadow". This
144 is set in init_dialog if the curses implementation supports
145 color. If true, suppress shadows that would be drawn to the
146 right and bottom of each dialog box.
147 DIALOG_STATE.visit_items
149 This corresponds to the command-line option "--visit-items".
150 The dialog application resets the dialog_vars data before accepting
152 options to invoke each widget. Most of the DIALOG_VARS members are set
153 directly from dialog's command-line options:
154 DIALOG_VARS.ascii_lines
156 DIALOG_VARS.backtitle
158 This corresponds to the command-line option "--backtitle backti‐
159 tle". It specifies a backtitle string to be displayed on the
160 backdrop, at the top of the screen.
161 DIALOG_VARS.beep_after_signal
163 This corresponds to the command-line option "--beep-after". If
164 true, beep after a user has completed a widget by pressing one
165 of the buttons.
166 DIALOG_VARS.beep_signal
168 This corresponds to the command-line option "--beep". It is
169 obsolete.
170 DIALOG_VARS.begin_set
172 This is true if the command-line option "--begin y x" was used.
173 It specifies the position of the upper left corner of a dialog
174 box on the screen.
175 DIALOG_VARS.begin_x
177 This corresponds to the x value from the command-line option
178 "--begin y x" (second value).
179 DIALOG_VARS.begin_y
181 This corresponds to the y value from the command-line option
182 "--begin y x" (first value).
183 DIALOG_VARS.cancel_label
185 This corresponds to the command-line option "--cancel-label
186 string". The given string overrides the label used for "Cancel"
187 buttons.
188 DIALOG_VARS.cant_kill
190 This corresponds to the command-line option "--no-kill". If
191 true, this tells dialog to put the tailboxbg box in the back‐
192 ground, printing its process id to dialog's output. SIGHUP is
193 disabled for the background process.
194 DIALOG_VARS.colors
196 This corresponds to the command-line option "--colors". If
197 true, interpret embedded "\Z" sequences in the dialog text by
198 the following character, which tells dialog to set colors or
199 video attributes: 0 through 7 are the ANSI codes used in curses:
200 black, red, green, yellow, blue, magenta, cyan and white respec‐
201 tively. Bold is set by 'b', reset by 'B'. Reverse is set by
202 'r', reset by 'R'. Underline is set by 'u', reset by 'U'. The
203 settings are cumulative, e.g., "\Zb\Z1" makes the following text
204 bright red. Restore normal settings with "\Zn".
205 DIALOG_VARS.column_separator
207 DIALOG_VARS.cr_wrap
209 This corresponds to the command-line option "--cr-wrap". If
210 true, interpret embedded newlines in the dialog text as a new‐
211 line on the screen. Otherwise, dialog will only wrap lines
212 where needed to fit inside the text box. Even though you can
213 control line breaks with this, dialog will still wrap any lines
214 that are too long for the width of the box. Without cr-wrap,
215 the layout of your text may be formatted to look nice in the
216 source code of your script without affecting the way it will
217 look in the dialog.
218 DIALOG_VARS.date_format
220 This corresponds to the command-line option "--date-format
221 string". If the host provides strftime, and the value is non‐
222 null, the calendar widget uses this to format its output.
223 DIALOG_VARS.default_item
225 This corresponds to the command-line option "--default-item
226 string". The given string is used as the default item in a
227 checklist, form or menu box. Normally the first item in the box
228 is the default.
229 DIALOG_VARS.defaultno
231 This corresponds to the command-line option "--defaultno". If
232 true, make the default value of the yes/no box a No. Likewise,
233 make the default button of widgets that provide "OK" and "Can‐
234 cel" a Cancel. If --nocancel was given that option overrides
235 this, making the default button always "Yes" (internally the
236 same as "OK").
237 DIALOG_VARS.dlg_clear_screen
239 This corresponds to the command-line option "--clear". This
240 option is implemented in the main program, not the library. If
241 true, the screen will be cleared on exit. This may be used
242 alone, without other options.
243 DIALOG_VARS.exit_label
245 This corresponds to the command-line option "--exit-label
246 string". The given string overrides the label used for "EXIT"
247 buttons.
248 DIALOG_VARS.extra_button
250 This corresponds to the command-line option "--extra-button".
251 If true, some widgets show an extra button, between "OK" and
252 "Cancel" buttons.
253 DIALOG_VARS.extra_label
255 This corresponds to the command-line option "--extra-label
256 string". The given string overrides the label used for "Extra"
257 buttons. Note: for inputmenu widgets, this defaults to
258 "Rename".
259 DIALOG_VARS.formitem_type
261 This is set by the command-line option "--passwordform" to tell
262 the form widget that its text fields should be treated like
263 password widgets.
264 DIALOG_VARS.help_button
266 This corresponds to the command-line option "--help-button". If
267 true, some widgets show a help-button after "OK" and "Cancel"
268 buttons, i.e., in checklist, radiolist and menu boxes. If
269 --item-help is also given, on exit the return status will be the
270 same as for the "OK" button, and the item-help text will be
271 written to dialog's output after the token "HELP". Otherwise,
272 the return status will indicate that the Help button was
273 pressed, and no message printed.
274 DIALOG_VARS.help_label
276 This corresponds to the command-line option "--help-label
277 string". The given string overrides the label used for "Help"
278 buttons.
279 DIALOG_VARS.help_status
281 This corresponds to the command-line option "--help-status". If
282 true, and the the help-button is selected, writes the checklist
283 or radiolist information after the item-help "HELP" information.
284 This can be used to reconstruct the state of a checklist after
285 processing the help request.
286 DIALOG_VARS.input_length
288 This is nonzero if DIALOG_VARS.input_result is allocated, versus
289 being a pointer to the user's local variables.
290 DIALOG_VARS.input_menu
292 This flag is set to denote whether the menubox widget implements
293 a menu versus a inputmenu widget.
294 DIALOG_VARS.input_result
296 If DIALOG_VARS.input_length is zero, this is a pointer to user
297 buffer (on the stack, or static). When DIALOG_VARS.input_length
298 is nonzero, this is a dynamically-allocated buffer used by the
299 widgets to return printable results to the calling application.
300 DIALOG_VARS.insecure
302 This corresponds to the command-line option "--insecure". If
303 true, make the password widget friendlier but less secure, by
304 echoing asterisks for each character.
305 DIALOG_VARS.item_help
307 This corresponds to the command-line option "--item-help". If
308 true, interpret the tags data for checklist, radiolist and menu
309 boxes adding a column whose text is displayed in the bottom line
310 of the screen, for the currently selected item.
311 DIALOG_VARS.keep_tite
313 This is set by the command-line option "--keep-tite" to tell
314 dialog to not attempt to cancel the terminal initialization
315 (termcap ti/te) sequences which correspond to xterm's alternate-
316 screen switching. Normally dialog does this to avoid flickering
317 when run several times in a script.
318 DIALOG_VARS.keep_window
320 This corresponds to the command-line option "--keep-window". If
321 true, do not remove/repaint the window on exit. This is useful
322 for keeping the window contents visible when several widgets are
323 run in the same process. Note that curses will clear the screen
324 when starting a new process.
325 DIALOG_VARS.max_input
327 This corresponds to the command-line option "--max-input size".
328 Limit input strings to the given size. If not specified, the
329 limit is 2048.
330 DIALOG_VARS.no_label
332 This corresponds to the command-line option "--no-label string".
333 The given string overrides the label used for "No" buttons.
334 DIALOG_VARS.no_lines
336 DIALOG_VARS.nocancel
338 This corresponds to the command-line option "--no-cancel". If
339 true, suppress the "Cancel" button in checklist, inputbox and
340 menu box modes. A script can still test if the user pressed the
341 ESC key to cancel to quit.
342 DIALOG_VARS.nocollapse
344 This corresponds to the command-line option "--no-collapse".
345 Normally dialog converts tabs to spaces and reduces multiple
346 spaces to a single space for text which is displayed in a mes‐
347 sage boxes, etc. It true, that feature is disabled. Note that
348 dialog will still wrap text, subject to the --cr-wrap option.
349 DIALOG_VARS.nook
351 DIALOG_VARS.ok_label
353 This corresponds to the command-line option "--ok-label string".
354 The given string overrides the label used for "OK" buttons.
355 DIALOG_VARS.print_siz
357 This corresponds to the command-line option "--print-size". If
358 true, each widget prints its size to dialog's output when it is
359 invoked.
360 DIALOG_VARS.quoted
362 DIALOG_VARS.separate_output
364 This corresponds to the command-line option "--separate-output".
365 If true, checklist widgets output result one line at a time,
366 with no quoting. This facilitates parsing by another program.
367 DIALOG_VARS.single_quoted
369 This corresponds to the command-line option "--single-quoted".
370 If true, Use single-quoting as needed (and no quotes if
371 unneeded) for the output of checklist's as well as the item-help
372 text. If this option is not set, dialog uses double quotes
373 around each item. That requires occasional use of backslashes
374 to make the output useful in shell scripts.
375 DIALOG_VARS.size_err
377 This corresponds to the command-line option "--size-err". If
378 true, check the resulting size of a dialog box before trying to
379 use it, printing the resulting size if it is larger than the
380 screen. (This option is obsolete, since all new-window calls
381 are checked).
382 DIALOG_VARS.sleep_secs
384 This corresponds to the command-line option "--sleep secs".
385 This option is implemented in the main program, not the library.
386 If nonzero, this is the number of seconds after to delay after
387 processing a dialog box.
388 DIALOG_VARS.tab_correct
390 This corresponds to the command-line option "--tab-correct". If
391 true, convert each tab character of the text to one or more spa‐
392 ces. Otherwise, tabs are rendered according to the curses
393 library's interpretation.
394 DIALOG_VARS.time_format
396 This corresponds to the command-line option "--time-format
397 string". If the host provides strftime, and the value is non‐
398 null, the timebox widget uses this to format its output.
399 DIALOG_VARS.timeout_secs
401 This corresponds to the command-line option "--timeout secs".
402 If nonzero, timeout input requests (exit with error code) if no
403 user response within the given number of seconds.
404 DIALOG_VARS.title
406 This corresponds to the command-line option "--title title".
407 Specifies a title string to be displayed at the top of the dia‐
408 log box.
409 DIALOG_VARS.trim_whitespace
411 This corresponds to the command-line option "--trim". If true,
412 eliminate leading blanks, trim literal newlines and repeated
413 blanks from message text.
414 DIALOG_VARS.visit_items
416 This corresponds to the command-line option "--visit-items".
417 Modify the tab-traversal of checklist, radiobox, menubox and
418 inputmenu to include the list of items as one of the states.
419 This is useful as a visual aid, i.e., the cursor position helps
420 some users.
421 DIALOG_VARS.yes_label
423 This corresponds to the command-line option "--yes-label
424 string". The given string overrides the label used for "Yes"
425 buttons.
426
428 Functions that implement major functionality for the command-line dia‐
429 log program, e.g., widgets, have names beginning "dialog_".
430 All dialog boxes have at least three parameters:
432 title
434 the caption for the box, shown on its top border.
435 height
437 the height of the dialog box.
438 width
440 the width of the dialog box.
441 Other parameters depend on the box type.
443 dialog_calendar
445 implements the "--calendar" option.
446 title is the title on the top of the widget.
448 subtitle
450 is the prompt text shown within the widget.
451 height is the height excluding the fixed-height calendar grid.
453 width is the overall width of the box, which is adjusted up to
455 the calendar grid's minimum width if needed.
456 day is the initial day of the week shown, counting zero as
458 Sunday. If the value is negative, the current day of the
459 week is used.
460 month is the initial month of the year shown, counting one as
462 January. If the value is negative, the current month of
463 the year is used.
464 year is the initial year shown. If the value is negative, the
466 current year is used.
467 dialog_checklist
469 implements the "--checklist" and "--radiolist" options depending
470 on the flag parameter.
471 title is the title on the top of the widget.
473 cprompt
475 is the prompt text shown within the widget.
476 height is the desired height of the box. If zero, the height is
478 adjusted to use the available screen size.
479 width is the desired width of the box. If zero, the height is
481 adjusted to use the available screen size.
482 list_height
484 is the minimum height to reserve for displaying the list.
485 If zero, it is computed based on the given height and
486 width.
487 item_no
489 is the number of rows in items.
490 items is an array of strings which is viewed either as a list
492 of rows
493 tag item status
494 or
496 tag item status help
497 depending on whether dialog_vars.item_help is set.
499 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for
501 radiolists.
502 dialog_dselect
504 implements the "--dselect" option.
505 title is the title on the top of the widget.
507 path is the preselected value to show in the input-box, which
509 is used also to set the directory- and file-windows.
510 height is the height excluding the minimum needed to show the
512 dialog box framework. If zero, the height is based on
513 the screen size.
514 width is the desired width of the box. If zero, the height is
516 based on the screen size.
517 dialog_editbox
519 implements the "--editbox" option.
520 title is the title on the top of the widget.
522 file is the name of the file from which to read.
524 height is the desired height of the box. If zero, the height is
526 adjusted to use the available screen size.
527 width is the desired width of the box. If zero, the height is
529 adjusted to use the available screen size.
530 dialog_form
532 implements the "--form" option.
533 title is the title on the top of the widget.
535 cprompt
537 is the prompt text shown within the widget.
538 height is the desired height of the box. If zero, the height is
540 adjusted to use the available screen size.
541 width is the desired width of the box. If zero, the height is
543 adjusted to use the available screen size.
544 form_height
546 is the minimum height to reserve for displaying the list.
547 If zero, it is computed based on the given height and
548 width.
549 item_no
551 is the number of rows in items.
552 items is an array of strings which is viewed either as a list
554 of rows
555 Name NameY NameX Text TextY TextX FLen ILen
556 or
558 Name NameY NameX Text TextY TextX FLen ILen Help
559 depending on whether dialog_vars.item_help is set.
561 dialog_fselect
563 implements the "--fselect" option.
564 title is the title on the top of the widget.
566 path is the preselected value to show in the input-box, which
568 is used also to set the directory- and file-windows.
569 height is the height excluding the minimum needed to show the
571 dialog box framework. If zero, the height is based on
572 the screen size.
573 width is the desired width of the box. If zero, the height is
575 based on the screen size.
576 dialog_gauge
578 implements the "--gauge" option.
579 title is the title on the top of the widget.
581 cprompt
583 is the prompt text shown within the widget.
584 height is the desired height of the box. If zero, the height is
586 based on the screen size.
587 width is the desired width of the box. If zero, the height is
589 based on the screen size.
590 percent
592 is the percentage to show in the progress bar.
593 dialog_inputbox
595 implements the "--inputbox" or "--password" option, depending on
596 the value of password.
597 title is the title on the top of the widget.
599 cprompt
601 is the prompt text shown within the widget.
602 height is the desired height of the box. If zero, the height is
604 based on the screen size.
605 width is the desired width of the box. If zero, the height is
607 based on the screen size.
608 init is the initial value of the input box, whose length is
610 taken into account when auto-sizing the width of the dia‐
611 log box.
612 password
614 if true, causes typed input to be echoed as asterisks.
615 dialog_menu
617 implements the "--menu" or "--inputmenu" option depending on
618 whether dialog_vars.input_menu is set.
619 title is the title on the top of the widget.
621 cprompt
623 is the prompt text shown within the widget.
624 height is the desired height of the box. If zero, the height is
626 based on the screen size.
627 width is the desired width of the box. If zero, the height is
629 based on the screen size.
630 menu_height
632 is the minimum height to reserve for displaying the list.
633 If zero, it is computed based on the given height and
634 width.
635 item_no
637 is the number of rows in items.
638 items is an array of strings which is viewed either as a list
640 of rows
641 tag item
642 or
644 tag item help
645 depending on whether dialog_vars.item_help is set.
647 dialog_mixedform
649 implements the "--mixedform" option.
650 title is the title on the top of the widget.
652 cprompt
654 is the prompt text shown within the widget.
655 height is the desired height of the box. If zero, the height is
657 adjusted to use the available screen size.
658 width is the desired width of the box. If zero, the height is
660 adjusted to use the available screen size.
661 form_height
663 is the minimum height to reserve for displaying the list.
664 If zero, it is computed based on the given height and
665 width.
666 item_no
668 is the number of rows in items.
669 items is an array of strings which is viewed either as a list
671 of rows
672 Name NameY NameX Text TextY TextX FLen ILen Ityp
673 or
675 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
676 depending on whether dialog_vars.item_help is set.
678 dialog_mixedgauge
680 implements the "--mixedgauge" option
681 title is the title on the top of the widget.
683 cprompt
685 is the caption text shown within the widget.
686 height is the desired height of the box. If zero, the height is
688 based on the screen size.
689 width is the desired width of the box. If zero, the height is
691 based on the screen size.
692 percent
694 is the percentage to show in the progress bar.
695 item_no
697 is the number of rows in items.
698 items is an array of strings which is viewed as a list of tag
700 and item values. The tag values are listed, one per row,
701 in the list at the top of the widget.
702 The item values are decoded: digits 0-9 are the following
704 strings
705 0 Succeeded
707 1 Failed
709 2 Passed
711 3 Completed
713 4 Checked
715 5 Done
717 6 Skipped
719 7 In Progress
721 8 (blank)
723 9 N/A
725 A string with a leading "-" character is centered, marked
727 with "%". For example, "-75" is displayed as "75%".
728 Other strings are displayed as is.
729 dialog_msgbox
731 implements the "--msgbox" or "--infobox" option depending on
732 whether pauseopt is set.
733 title is the title on the top of the widget.
735 cprompt
737 is the prompt text shown within the widget.
738 height is the desired height of the box. If zero, the height is
740 based on the screen size.
741 width is the desired width of the box. If zero, the height is
743 based on the screen size.
744 pauseopt
746 if true, an "OK" button will be shown, and the dialog
747 will wait for it to complete. With an "OK" button, it is
748 denoted a "msgbox", without an "OK" button, it is denoted
749 an "infobox".
750 dialog_pause
752 implements the "--pause" option.
753 title is the title on the top of the widget.
755 height is the desired height of the box. If zero, the height is
757 based on the screen size.
758 width is the desired width of the box. If zero, the height is
760 based on the screen size.
761 seconds
763 is the timeout to use for the progress bar.
764 dialog_progressbox
766 implements the "--progressbox" option.
767 title is the title on the top of the widget.
769 cprompt
771 is the prompt text shown within the widget. If empty or
772 null, no prompt is shown.
773 height is the desired height of the box. If zero, the height is
775 based on the screen size.
776 width is the desired width of the box. If zero, the height is
778 based on the screen size.
779 dialog_tailbox
781 implements the "--tailbox" or "--tailboxbg" option depending on
782 whether bg_task is set.
783 title is the title on the top of the widget.
785 file is the name of the file to display in the dialog.
787 height is the desired height of the box. If zero, the height is
789 based on the screen size.
790 width is the desired width of the box. If zero, the height is
792 based on the screen size.
793 bg_task
795 if true, the window is added to the callback list in dia‐
796 log_state, and the application will poll for the window
797 to be updated. Otherwise an "OK" button is added to the
798 window, and it will be closed when the button is acti‐
799 vated.
800 dialog_textbox
802 implements the "--textbox" option.
803 title is the title on the top of the widget.
805 file is the name of the file to display in the dialog.
807 height is the desired height of the box. If zero, the height is
809 based on the screen size.
810 width is the desired width of the box. If zero, the height is
812 based on the screen size.
813 dialog_timebox
815 implements the "--timebox" option.
816 title is the title on the top of the widget.
818 subtitle
820 is the prompt text shown within the widget.
821 height is the desired height of the box. If zero, the height is
823 based on the screen size.
824 width is the desired width of the box. If zero, the height is
826 based on the screen size.
827 hour is the initial hour shown. If the value is negative, the
829 current hour is used.
830 minute is the initial minute shown. If the value is negative,
832 the current minute is used.
833 second is the initial second shown. If the value is negative,
835 the current second is used.
836 dialog_yesno
838 implements the "--yesno" option.
839 title is the title on the top of the widget.
841 cprompt
843 is the prompt text shown within the widget.
844 height is the desired height of the box. If zero, the height is
846 based on the screen size.
847 width is the desired width of the box. If zero, the height is
849 based on the screen size.
850
852 Most functions that implement lower-level functionality for the com‐
853 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
854 ing to longstanding usage, the functions that initialize the display
855 and end it are named init_dialog and end_dialog.
856 The only non-widget function whose name begins with "dialog_" is dia‐
858 log_version, which returns the version number of the library as a
859 string.
860 Here is a brief summary of the utility functions and their parameters:
862 dlg_add_callback
864 Add a callback, used to allow polling input from multiple tailbox
865 widgets.
866 DIALOG_CALLBACK *p
868 contains the callback information.
869 dlg_add_callback_ref
871 Like dlg_add_callback, but passes a reference to the DIALOG_CALL‐
872 BACK as well as a pointer to a cleanup function which will be
873 called when the associated input ends.
874 DIALOG_CALLBACK **p
876 points to the callback information. This is a reference to
877 the pointer so that the caller's pointer can be zeroed when
878 input ends.
879 DIALOG_FREEBACK func
881 function to call when input ends, e.g., to free caller's
882 additional data.
883 dlg_add_quoted
885 Add a quoted string to the result buffer (see dlg_add_result).
886 char * string
888 is the string to add.
889 dlg_add_result
891 Add a quoted string to the result buffer dialog_vars.input_result.
892 char * string
894 is the string to add.
895 dlg_add_separator
897 Add an output-separator to the result buffer dia‐
898 log_vars.input_result. If dialog_vars.output_separator is set,
899 use that. Otherwise, if dialog_vars.separate_output is set, use
900 newline. If neither is set, use a space.
901 dlg_add_string
903 Add a quoted or unquoted string to the result buffer (see
904 dlg_add_quoted) and dlg_add_result), according to whether dia‐
905 log_vars.quoted is true.
906 char * string
908 is the string to add.
909 dlg_align_columns
911 Copy and reformat an array of pointers to strings, aligning
912 according to the column separator dialog_vars.column_separator.
913 If no column separator is set, the array will be unmodified; oth‐
914 erwise it is copied and reformatted.
915 Caveat: This function is only implemented for 8-bit characters.
917 char **target
919 This is the array to reformat. It points to the first string
920 to modify.
921 int per_row
923 This is the size of the struct for each row of the array.
924 int num_rows
926 This is the number of rows in the array.
927 dlg_asciibox
929 returns its parameter transformed to the corresponding "+" or "-",
930 etc. for the line-drawing characters used in dialog. If the
931 parameter is not a line-drawing or other special character such as
932 ACS_DARROW, it returns 0.
933 dlg_attr_clear
935 Set window to the given attribute.
936 WINDOW * win
938 is the window to update.
939 int height
941 is the number of rows to update.
942 int width
944 is the number of columns to update.
945 chtype attr
947 is the attribute, e.g., A_BOLD.
948 dlg_auto_size
950 Automatically size the window used for a widget. If the given
951 height or width are zero, justify the prompt text and return the
952 actual limits.
953 const char * title
955 is the title string to display at the top of the widget.
956 const char * prompt
958 is the message text which will be displayed in the widget,
959 used here to determine how large the widget should be.
960 int * height
962 is the nominal height.
963 int * width
965 is the nominal width.
966 int boxlines
968 is the number of lines to reserve in the vertical direction.
969 int mincols
971 is the minimum number of columns to use.
972 dlg_auto_sizefile
974 Like dlg_auto_size, but use a file contents to decide how large
975 the widget should be.
976 const char * title
978 is the title string to display at the top of the widget.
979 const char * file
981 is the name of the file.
982 int * height
984 is the nominal height. If it is -1, use the screen's height
985 after subtracting dialog_vars.begin_y if dia‐
986 log_vars.begin_set is true.
987 int *width
989 is the nominal width. If it is -1, use the screen's width
990 after subtracting dialog_vars.begin_x if dia‐
991 log_vars.begin_set is true.
992 int boxlines
994 is the number of lines to reserve on the screen for drawing
995 boxes.
996 int mincols
998 is the number of columns to reserve on the screen for drawing
999 boxes.
1000 dlg_beeping
1002 If dialog_vars.beep_signal is nonzero, this calls beep once and
1003 sets dialog_vars.beep_signal to zero.
1004 dlg_boxchar
1006 returns its parameter transformed as follows:
1007 - if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is
1009 set.
1010 - if dialog_vars.ascii_lines is set, returns the corresponding
1012 "+" or "-", etc. for the line-drawing characters used in dia‐
1013 log.
1014 - otherwise, if dialog_vars.no_lines is set, returns a space for
1016 the line-drawing characters.
1017 - if the parameter is not a line-drawing or other special charac‐
1019 ter such as ACS_DARROW, it returns the parameter unchanged.
1020 dlg_box_x_ordinate
1022 returns a suitable x-ordinate (column) for a new widget. If dia‐
1023 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center
1024 the widget on the screen (using the width parameter).
1025 int width
1027 is the width of the widget.
1028 dlg_box_y_ordinate
1030 returns a suitable y-ordinate (row) for a new widget. If dia‐
1031 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center
1032 the widget on the screen (using the height parameter).
1033 int height
1035 is the height of the widget.
1036 dlg_button_count
1038 Count the buttons in the list.
1039 const char ** labels
1041 is a list of (pointers to) button labels terminated by a null
1042 pointer.
1043 dlg_button_layout
1045 Make sure there is enough space for the buttons by computing the
1046 width required for their labels, adding margins and limiting based
1047 on the screen size.
1048 const char ** labels
1050 is a list of (pointers to) button labels terminated by a null
1051 pointer.
1052 int * limit
1054 the function sets the referenced limit to the width required
1055 for the buttons (limited by the screen size) if that is wider
1056 than the passed-in limit.
1057 dlg_button_sizes
1059 Compute the size of the button array in columns.
1060 const char ** labels
1062 is a list of (pointers to) button labels terminated by a null
1063 pointer.
1064 int vertical
1066 is true if the buttons are arranged in a column rather than a
1067 row.
1068 int * longest
1070 Return the total number of columns in the referenced loca‐
1071 tion.
1072 int * length
1074 Return the longest button's columns in the referenced loca‐
1075 tion.
1076 dlg_button_x_step
1078 Compute the step-size needed between elements of the button array.
1079 const char ** labels
1081 is a list of (pointers to) button labels terminated by a null
1082 pointer.
1083 int limit
1085 is the maximum number of columns to allow for the buttons.
1086 int * gap
1088 store the nominal gap between buttons in the referenced loca‐
1089 tion. This is constrained to be at least one.
1090 int * margin
1092 store the left+right total margins (for the list of buttons)
1093 in the referenced location.
1094 int * step
1096 store the step-size in the referenced location.
1097 dlg_button_to_char
1099 Find the first uppercase character in the label, which we may use
1100 for an abbreviation. If the label is empty, return -1. If no
1101 uppercase character is found, return 0. Otherwise return the
1102 uppercase character.
1103 const char * label
1105 is the label to test.
1106 dlg_calc_list_width
1108 Calculate the minimum width for the list, assuming none of the
1109 items are truncated.
1110 int item_no
1112 is the number of items.
1113 DIALOG_LISTITEM * items
1115 contains a name and text field, e.g., for checklists or
1116 radiobox lists. The function returns the sum of the widest
1117 columns needed for of each of these fields.
1118 dlg_calc_listh
1120 Calculate new height and list_height values.
1121 int * height
1123 on input, is the height without adding the list-height. On
1124 return, this contains the total list-height and is the actual
1125 widget's height.
1126 int * list_height
1128 on input, is the requested list-height. On return, this con‐
1129 tains the number of rows available for displaying the list
1130 after taking into account the screen size and the dia‐
1131 log_vars.begin_set and dialog_vars.begin_y variables.
1132 int item_no
1134 is the number of items in the list.
1135 dlg_calc_listw
1137 This function is obsolete, provided for library-compatibility. It
1138 is replaced by dlg_calc_list_width.
1139 int item_no
1141 is the number of items.
1142 char ** items
1144 is a list of character pointers.
1145 int group
1147 is the number of items in each group, e.g., the second array
1148 index.
1149 dlg_char_to_button
1151 Given a list of button labels, and a character which may be the
1152 abbreviation for one, find it, if it exists. An abbreviation will
1153 be the first character which happens to be capitalized in the
1154 label. If the character is found, return its index within the
1155 list of labels. Otherwise, return DLG_EXIT_UNKNOWN.
1156 int ch
1158 is the character to find.
1159 const char ** labels
1161 is a list of (pointers to) button labels terminated by a null
1162 pointer.
1163 dlg_checklist
1165 This entrypoint provides the --checklist or --radiolist function‐
1166 ality without the limitations of dialog's command-line syntax
1167 (compare to dialog_checklist).
1168 const char * title
1170 is the title string to display at the top of the widget.
1171 const char * cprompt
1173 is the prompt text shown within the widget.
1174 int height
1176 is the desired height of the box. If zero, the height is
1177 adjusted to use the available screen size.
1178 int width
1180 is the desired width of the box. If zero, the height is
1181 adjusted to use the available screen size.
1182 int list_height
1184 is the minimum height to reserve for displaying the list. If
1185 zero, it is computed based on the given height and width.
1186 int item_no
1188 is the number of items.
1189 DIALOG_LISTITEM * items
1191 This is a list of the items to display in the checklist.
1192 const char * states
1194 This is a list of characters to display for the given states.
1195 Normally a checklist provides true (1) and false (0) values,
1196 which the widget displays as "*" and space, respectively. An
1197 application may set this parameter to an arbitrary null-ter‐
1198 minated string. The widget determines the number of states
1199 from the length of this string, and will cycle through the
1200 corresponding display characters as the user presses the
1201 space-bar.
1202 int flag
1204 This is should be one of FLAG_CHECK or FLAG_RADIO, depending
1205 on whether the widget should act as a checklist or radiobox.
1206 int * current_item
1208 The widget sets the referenced location to the index of the
1209 current display item (cursor) when it returns.
1210 dlg_check_scrolled
1212 given a function key (or other key that was mapped to a function
1213 key), check if it is one of the up/down scrolling functions:
1214 DLGK_PAGE_FIRST,
1216 DLGK_PAGE_LAST,
1217 DLGK_GRID_UP,
1218 DLGK_GRID_DOWN,
1219 DLGK_PAGE_PREV or
1220 DLGK_PAGE_NEXT.
1221 Some widgets use these key bindings for scrolling the prompt-text
1223 up and down, to allow for display in very small windows.
1224 The function returns 0 (zero) if it finds one of these keys, and
1226 -1 if not.
1227 int key
1229 is the function-key to check
1230 int last
1232 is the number of lines which would be used to display the
1233 scrolled prompt in an arbitrarily tall window. It is used
1234 here to check limits for the offset value.
1235 int page
1237 this is the available height for writing scrolled text, which
1238 is smaller than the window if it contains buttons.
1239 bool * show
1241 on return, holds TRUE if dlg_print_scrolled should be used to
1242 redisplay the prompt text.
1243 int * offset
1245 on entry, holds the starting line number (counting from zero)
1246 last used for dlg_print_scrolled. On return, holds the
1247 updated starting line number.
1248 dlg_clear
1250 Set window to the default dialog screen attribute. This is set in
1251 the rc-file with screen_color.
1252 dlg_clr_result
1254 Free storage used for the result buffer (dia‐
1255 log_vars.input_result).
1256 dlg_color_count
1258 Return the number of colors that can be configured in dialog.
1259 dlg_color_setup
1261 Initialize the color pairs used in dialog.
1262 dlg_count_columns
1264 Returns the number of columns used for a string. This is not nec‐
1265 essarily the number of bytes in a string.
1266 const char * string
1268 is the string to measure.
1269 dlg_count_wchars
1271 Returns the number of wide-characters in the string.
1272 const char * string
1274 is the string to measure.
1275 dlg_create_rc
1277 Create a configuration file, i.e., write internal tables to a file
1278 which can be read back by dialog as an rc-file.
1279 const char * filename
1281 is the name of the file to write to.
1282 dlg_ctl_size
1284 If dialog_vars.size_err is true, check if the given window size is
1285 too large to fit on the screen. If so, exit with an error report‐
1286 ing the size of the window.
1287 int height
1289 is the window's height
1290 int width
1292 is the window's width
1293 dlg_default_formitem
1295 If dialog_vars.default_item is not null, find that name by match‐
1296 ing the name field in the list of form items. If found, return
1297 the index of that item in the list. Otherwise, return zero.
1298 DIALOG_FORMITEM * items
1300 is the list of items to search. It is terminated by an entry
1301 with a null name field.
1302 dlg_default_item
1304 This function is obsolete, provided for library-compatibility. It
1305 is replaced by dlg_default_formitem and dlg_default_listitem.
1306 char ** items
1308 is the list of items to search.
1309 int llen
1311 is the number of items in each group, e.g., the second array
1312 index.
1313 dlg_defaultno_button
1315 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not,
1316 find the button-index for the "Cancel" button. Otherwise, return
1317 the index for "OK" (always zero).
1318 dlg_del_window
1320 Remove a window, repainting everything else.
1321 WINDOW * win
1323 is the window to remove.
1324 dlg_does_output
1326 This is called each time a widget is invoked which may do output.
1327 It increments dialog_state.output_count, so the output function in
1328 dialog can test this and add a separator.
1329 dlg_draw_arrows
1331 Draw up/down arrows on a window, e.g., for scrollable lists. It
1332 calls dlg_draw_arrows2 using the menubox_color and menubox_bor‐
1333 der_color attributes.
1334 WINDOW * dialog
1336 is the window on which to draw an arrow.
1337 int top_arrow
1339 is true if an up-arrow should be drawn at the top of the win‐
1340 dow.
1341 int bottom_arrow
1343 is true if an down-arrow should be drawn at the bottom of the
1344 window.
1345 int x
1347 is the zero-based column within the window on which to draw
1348 arrows.
1349 int top
1351 is the zero-based row within the window on which to draw up-
1352 arrows as well as a horizontal line to show the window's top.
1353 int bottom
1355 is the zero-based row within the window on which to draw
1356 down-arrows as well as a horizontal line to show the window's
1357 bottom.
1358 dlg_draw_arrows2
1360 Draw up/down arrows on a window, e.g., for scrollable lists.
1361 WINDOW * dialog
1363 is the window on which to draw an arrow.
1364 int top_arrow
1366 is true if an up-arrow should be drawn at the top of the win‐
1367 dow.
1368 int bottom_arrow
1370 is true if an down-arrow should be drawn at the bottom of the
1371 window.
1372 int x
1374 is the zero-based column within the window on which to draw
1375 arrows.
1376 int top
1378 is the zero-based row within the window on which to draw up-
1379 arrows as well as a horizontal line to show the window's top.
1380 int bottom
1382 is the zero-based row within the window on which to draw
1383 down-arrows as well as a horizontal line to show the window's
1384 bottom.
1385 chtype attr
1387 is the window's background attribute.
1388 chtype borderattr
1390 is the window's border attribute.
1391 dlg_draw_bottom_box
1393 Draw a partial box at the bottom of a window, e.g., to surround a
1394 row of buttons. It is designed to merge with an existing box
1395 around the whole window, so it uses tee-elements rather than cor‐
1396 ner-elements on the top corners of this box.
1397 WINDOW * win
1399 is the window to update.
1400 dlg_draw_box
1402 Draw a rectangular box with line drawing characters.
1403 WINDOW * win
1405 is the window to update.
1406 int y
1408 is the top row of the box.
1409 int x
1411 is the left column of the box.
1412 int height
1414 is the height of the box.
1415 int width
1417 is the width of the box.
1418 chtype boxchar
1420 is used to color the right/lower edges. It also is fill-
1421 color used for the box contents.
1422 chtype borderchar
1424 is used to color the upper/left edges.
1425 dlg_draw_buttons
1427 Print a list of buttons at the given position.
1428 WINDOW * win
1430 is the window to update.
1431 int y
1433 is the starting row.
1434 int x
1436 is the starting column.
1437 const char ** labels
1439 is a list of (pointers to) button labels terminated by a null
1440 pointer.
1441 int selected
1443 is the index within the list of the selected button.
1444 int vertical
1446 is true if the buttons are arranged in a column rather than a
1447 row.
1448 int limit
1450 is the number of columns (or rows if vertical) allowed for
1451 the display.
1452 dlg_draw_scrollbar
1454 If dialog_state.use_scrollbar is set, draw a scrollbar on the
1455 right margin of windows holding scrollable data. Also (whether or
1456 not the scrollbar is drawn), annotate the bottom margin of the
1457 window with the percentage of data by the bottom of that window,
1458 and call dlg_draw_arrows2 to put markers on the window showing
1459 when more data is available.
1460 WINDOW * win
1462 is the window in which the data is scrolled. Because left,
1463 right, top, bottom are passed as parameters, this window can
1464 contain additional data.
1465 long first_data
1467 is the zero-based index to the first row of data in the cur‐
1468 rent window.
1469 long this_data
1471 is the zero-based index to the current row of data.
1472 long next_data
1474 is the zero-based index to the next data after the current
1475 row.
1476 long total_data
1478 is the total number of rows of data.
1479 int left
1481 is the zero-based left margin/column of the window. The
1482 up/down arrows are draw inset by 5 columns from this point.
1483 int right
1485 is the zero-based right margin/column of the window. The
1486 scrollbar is drawn flush against this column.
1487 int top
1489 is the zero-based row within the window on which to draw up-
1490 arrows as well as a horizontal line to show the window's top.
1491 int bottom
1493 is the zero-based row within the window on which to draw
1494 down-arrows as well as a horizontal line to show the window's
1495 bottom.
1496 chtype attr
1498 is the window's background attribute.
1499 chtype borderattr
1501 is the window's border attribute.
1502 dlg_draw_shadow
1504 Draw shadows along the right and bottom edge of a window to give
1505 it a 3-dimensional look. (The height, etc., may not be the same
1506 as the window's actual values).
1507 WINDOW * win
1509 is the window to update.
1510 int height
1512 is the height of the window.
1513 int width
1515 is the width of the window.
1516 int y
1518 is the top row of the window.
1519 int x
1521 is the left column of the window.
1522 dlg_draw_title
1524 Draw a title centered at the top of the window.
1525 WINDOW * win
1527 is the window to update.
1528 const char * title
1530 is the title string to display at the top of the widget.
1531 dlg_dump_keys
1533 Write all user-defined key-bindings to the given stream, e.g., as
1534 part of dlg_create_rc.
1535 FILE * fp
1537 is the stream on which to write the bindings.
1538 dlg_edit_offset
1540 Given the character-offset in the string, returns the display-off‐
1541 set where dialog should position the cursor. In this context,
1542 "characters" may be multicolumn, since the string can be a multi‐
1543 byte character string.
1544 char * string
1546 is the string to analyze
1547 int offset
1549 is the character-offset
1550 int x_last
1552 is a limit on the column positions that can be used, e.g.,
1553 the window's size.
1554 dlg_edit_string
1556 Updates the string and character-offset, given various editing
1557 characters or literal characters which are inserted at the charac‐
1558 ter-offset. Returns true if an editing change was made (and the
1559 display should be updated), and false if the key was something
1560 like KEY_ENTER, which is a non-editing action outside this func‐
1561 tion.
1562 char * string
1564 is the (multibyte) string to update
1565 int * offset
1567 is the character-offset
1568 int key
1570 is the editing key
1571 int fkey
1573 is true if the editing key is a function-key
1574 bool force
1576 is used in a special loop case by calling code to force the
1577 return value of this function when a function-key code 0 is
1578 passed in.
1579 dlg_exit
1581 Given an internal exit code, check if the corresponding environ‐
1582 ment variable is set. If so, remap the exit code to match the
1583 environment variable. Finally call exit with the resulting exit
1584 code.
1585 int code
1587 is the internal exit code, e.g., DLG_EXIT_OK, which may be
1588 remapped.
1589 The dialog program uses this function to allow shell scripts to
1591 remap the exit codes so they can distinguish ESC from ERROR.
1592 dlg_exit_buttoncode
1594 Map the given button index for dlg_exit_label into dialog's exit-
1595 code.
1596 int button
1598 is the button index
1599 dlg_exit_label
1601 Return a list of button labels. If dialog_var.extra_button is
1602 true, return the result of dlg_ok_labels. Otherwise, return a
1603 list with the "Exit" label and (if dialog_vars.help_button is set)
1604 the "Help" button as well.
1605 dlg_exiterr
1607 Quit program killing all tailboxbg widgets.
1608 const char * fmt
1610 is the format of the printf-like message to write.
1611 are the variables to apply to the fmt format.
1613 dlg_find_index
1615 Given the character-offset to find in the list, return the corre‐
1616 sponding array index.
1617 const int *list
1619 contains a list of character-offsets, i.e., indices into a
1620 string that denote the beginning of multibyte characters.
1621 int limit
1623 is the last index into list to search.
1624 int to_find
1626 is the character-offset to find.
1627 dlg_flush_getc
1629 Cancel the local data saved by dlg_last_getc.
1630 dlg_editbox
1632 This entrypoint provides the --editbox functionality without the
1633 limitations of dialog's command-line syntax (compare to dia‐
1634 log_editbox).
1635 const char * title
1637 is the title string to display at the top of the widget.
1638 char *** list
1640 is a pointer to an array of char * pointers. The array is
1641 allocated by the caller, and so are the strings to which it
1642 points. The dlg_editbox function may reallocate the array
1643 and the strings.
1644 int * rows
1646 points to the nominal length of list. The referenced value
1647 is updated iflist is reallocated.
1648 int height
1650 is the desired height of the box. If zero, the height is
1651 adjusted to use the available screen size.
1652 int width
1654 is the desired width of the box. If zero, the height is
1655 adjusted to use the available screen size.
1656 dlg_form
1658 This entrypoint provides the --form functionality without the lim‐
1659 itations of dialog's command-line syntax (compare to dialog_form).
1660 const char * title
1662 is the title string to display at the top of the widget.
1663 const char * cprompt
1665 is the prompt text shown within the widget.
1666 int height
1668 is the desired height of the box. If zero, the height is
1669 adjusted to use the available screen size.
1670 int width
1672 is the desired width of the box. If zero, the height is
1673 adjusted to use the available screen size.
1674 int form_height
1676 is the minimum height to reserve for displaying the list. If
1677 zero, it is computed based on the given height and width.
1678 int item_no
1680 is the number of items.
1681 DIALOG_FORMITEM * items
1683 This is a list of the items to display in the form.
1684 int * current_item
1686 The widget sets the referenced location to the index of the
1687 current display item (cursor) when it returns.
1688 dlg_free_columns
1690 Free data allocated by dlg_align_columns.
1691 char **target
1693 This is the array which was reformatted. It points to the
1694 first string to free.
1695 int per_row
1697 This is the size of the struct for each row of the array.
1698 int num_rows
1700 This is the number of rows in the array.
1701 dlg_free_formitems
1703 Free memory owned by a list of DIALOG_FORMITEM's.
1704 DIALOG_FORMITEM * items
1706 is the list to free.
1707 dlg_getc
1709 Read a character from the given window. Handle repainting here
1710 (to simplify things in the calling application). Also, if input-
1711 callback(s) are set up, poll the corresponding files and handle
1712 the updates, e.g., for displaying a tailbox. Returns the key-
1713 code.
1714 WINDOW * win
1716 is the window within which to read.
1717 int * fkey
1719 as a side-effect, set this to true if the key-code is really
1720 a function-key.
1721 dlg_getc_callbacks
1723 passes the given key-code ch to the current window that has estab‐
1724 lished a callback. If the callback returns zero, remove it and
1725 try the next window. If no more callbacks remain, return. If any
1726 callbacks were found, return true, otherwise false.
1727 int ch
1729 is the key-code
1730 int fkey
1732 is true if the key is a function-key
1733 int * result
1735 is used to pass an exit-code to the caller, which should pass
1736 that via dlg_exit.
1737 dlg_index_columns
1739 Build a list of the display-columns for the given multibyte
1740 string's characters.
1741 const char * string
1743 is the string to analyze
1744 dlg_index_wchars
1746 Build an index of the wide-characters in the string, so the caller
1747 can easily tell which byte-offset begins a given wide-character.
1748 const char * string
1750 is the string to analyze
1751 dlg_item_help
1753 Draw the string for the dialog_vars.item_help feature.
1754 const char * txt
1756 is the help-message
1757 dlg_killall_bg
1759 If dialog has callbacks active, purge the list of all that are not
1760 marked to keep in the background. If any remain, run those in a
1761 background process.
1762 int * retval
1764 stores the exit-code to pass back to the caller.
1765 dlg_last_getc
1767 returns the most recent character that was read via dlg_getc.
1768 dlg_limit_columns
1770 Given a column limit, count the number of wide characters that can
1771 fit into that limit. The offset is used to skip over a leading
1772 character that was already written.
1773 const char * string
1775 is the string to analyze
1776 int limit
1778 is the column limit
1779 int offset
1781 is the starting offset from which analysis should continue
1782 dlg_lookup_key
1784 Check for a key-binding. If there is no binding associated with
1785 the widget, it simply returns the given curses-key. Otherwise, it
1786 returns the result of the binding
1787 WINDOW * win
1789 is the window on which the binding is checked
1790 int curses_key
1792 is the curses key-code
1793 int * dialog_key
1795 is the corresponding dialog internal code (see DLG_KEYS_ENUM
1796 in dlg_key.h).
1797 dlg_max_input
1799 Limit the parameter according to dialog_vars.max_input
1800 int max_len
1802 is the value to limit
1803 dlg_match_char
1805 Match a given character against the beginning of the string,
1806 ignoring case of the given character. The matching string must
1807 begin with an uppercase character.
1808 int ch
1810 is the character to check
1811 const char * string
1813 is the string to search
1814 dlg_menu
1816 This entrypoint provides the --menu functionality without the lim‐
1817 itations of dialog's command-line syntax (compare to dialog_menu).
1818 const char * title
1820 is the title string to display at the top of the widget.
1821 const char * cprompt
1823 is the prompt text shown within the widget.
1824 int height
1826 is the desired height of the box. If zero, the height is
1827 adjusted to use the available screen size.
1828 int width
1830 is the desired width of the box. If zero, the height is
1831 adjusted to use the available screen size.
1832 int menu_height
1834 is the minimum height to reserve for displaying the list. If
1835 zero, it is computed based on the given height and width.
1836 int item_no
1838 is the number of items.
1839 DIALOG_LISTITEM * items
1841 This is a list of the items to display in the form.
1842 int * current_item
1844 The widget sets the referenced location to the index of the
1845 current display item (cursor) when it returns.
1846 DIALOG_INPUTMENU rename_menutext
1848 dlg_move_window
1850 Moves/resizes the given window to the given position and size.
1851 WINDOW *win
1853 is the window to move/resize.
1854 WINDOW *height
1856 is the height of the resized window.
1857 WINDOW *width
1859 is the width of the resized window.
1860 WINDOW *y
1862 y-ordinate to use for the repositioned window.
1863 WINDOW *x
1865 x-ordinate to use for the repositioned window.
1866 dlg_mouse_bigregion
1868 Retrieve the big-region under the pointer.
1869 int y
1871 is the row on which the mouse click occurred
1872 int x
1874 is the column on which the mouse click occurred
1875 dlg_mouse_free_regions
1877 Free the memory associated with mouse regions.
1878 dlg_mouse_mkbigregion
1880 Creates a region on which the mouse-clicks will return a specifed
1881 code.
1882 int y
1884 is the top-row of the region.
1885 int x
1887 is the left-column of the region.
1888 int height
1890 is the height of the region.
1891 int width
1893 is the width of the region.
1894 int code
1896 is a code used to make the region unique within a widget
1897 int step_x
1899 is used in modes 2 (columns) and 3 (cells) to determine the
1900 width of a column/cell.
1901 int step_y
1903 is currently unused
1904 int mode
1906 is used to determine how the mouse position is translated
1907 into a code (like a function-key):
1908 1 index by lines
1910 2 index by columns
1912 3 index by cells
1914 dlg_mouse_mkregion
1916 int y
1918 is the top-row of the region.
1919 int x
1921 is the left-column of the region.
1922 int height
1924 is the height of the region.
1925 int width
1927 is the width of the region.
1928 int code
1930 is a code used to make the region unique within a widget
1931 dlg_mouse_region
1933 Retrieve the frame under the mouse pointer
1934 int y
1936 is the row of the mouse-click
1937 int x
1939 is the column of the mouse-click
1940 dlg_mouse_setbase
1942 Sets a base for subsequent calls to dlg_mouse_mkregion, so they
1943 can make regions relative to the start of a given window.
1944 int x
1946 is the left-column for the base
1947 int y
1949 is the top-row for the base
1950 dlg_mouse_wgetch
1952 is a wrapper for dlg_getc which additionally maps mouse-clicks (if
1953 the curses library supports those) into extended function-keys
1954 which encode the position according to the mode in dlg_mouse_mkbi‐
1955 gregion. Returns the corresponding key-code.
1956 WINDOW * win
1958 is the window on which to perform the input
1959 int * fkey
1961 the referenced location is set to true if the key-code is an
1962 actual or extended (mouse) function-key.
1963 dlg_mouse_wgetch_nowait
1965 This is a non-blocking variant of dlg_mouse_wgetch.
1966 WINDOW * win
1968 is the window on which to perform the input
1969 int * fkey
1971 the referenced location is set to true if the key-code is an
1972 actual or extended (mouse) function-key.
1973 dlg_need_separator
1975 Check if an output-separator is needed. If dialog_vars.out‐
1976 put_separator is set, return true. Otherwise, if dia‐
1977 log_vars.input_result is nonempty, return true. If neither,
1978 return false.
1979 dlg_new_modal_window
1981 Create a modal window, optionally with a shadow. The shadow is
1982 created if dialog_state.use_shadow is true.
1983 WINDOW * parent
1985 is the parent window (usually the top-level window of a wid‐
1986 get)
1987 int height
1989 is the window's height
1990 int width
1992 is the window's width
1993 int y
1995 is the window's top-row
1996 int x
1998 is the window's left-column
1999 dlg_new_window
2001 Create a window, optionally with a shadow. The shadow is created
2002 if dialog_state.use_shadow is true.
2003 int height
2005 is the window's height
2006 int width
2008 is the window's width
2009 int y
2011 is the window's top-row
2012 int x
2014 is the window's left-column
2015 dlg_next_button
2017 Return the next index in the list of labels.
2018 const char ** labels
2020 is a list of (pointers to) button labels terminated by a null
2021 pointer.
2022 int button
2024 is the current button-index.
2025 dlg_next_ok_buttonindex
2027 Assuming that the caller is using dlg_ok_labels to list buttons,
2028 find the next index in the list of buttons.
2029 int current
2031 is the current index in the list of buttons
2032 int extra
2034 if negative, provides a way to enumerate extra active areas
2035 on the widget.
2036 dlg_ok_buttoncode
2038 Map the given button index for dlg_ok_labels into dialog's exit-
2039 code.
2040 int button
2042 is the button-index (which is not necessarily the same as the
2043 index in the list of labels).
2044 dlg_ok_label
2046 Returns a list with the "Ok" label, and if dialog_vars.help_button
2047 is true, the "Help" label as well.
2048 dlg_ok_labels
2050 Return a list of button labels for the OK/Cancel group of widgets.
2051 dlg_ordinate
2053 Decode the string as an integer, decrement if greater than zero to
2054 make a curses-ordinate from a dialog-ordinate.
2055 dlg_parse_bindkey
2057 Parse the parameters of the "bindkeys" configuration-file entry.
2058 This expects widget name which may be "*", followed by curses key
2059 definition and then dialog key definition.
2060 char * params
2062 is the parameter string to parse.
2063 dlg_parse_rc
2065 Parse the configuration file and set up variables.
2066 dlg_prev_button
2068 Return the previous index in the list of labels.
2069 const char ** labels
2071 is a list of (pointers to) button labels terminated by a null
2072 pointer.
2073 int button
2075 is the current button index
2076 dlg_print_scrolled
2078 This is a wrapper for dlg_print_autowrap which allows the user to
2079 scroll too-long prompt text up/down.
2080 See dlg_check_scrolled for a function which updates the offset
2082 variable used as a parameter here. It complements this function;
2083 you need both. If pauseopt is set, this function returns an
2084 updated last parameter, needed for dlg_check_scrolled calls.
2085 WINDOW * win
2087 is the window to update.
2088 const char * prompt
2090 is the string to print
2091 int offset
2093 is the starting line-number to write wrapped text.
2094 int height
2096 is the available height for writing the wrapped text
2097 int width
2099 is the width that the wrapping should occur in
2100 int pauseopt
2102 is true if the extra functionality for scrolling should be
2103 enabled. If false, this calls dlg_print_autowrap without
2104 doing any scrolling.
2105 dlg_print_line
2107 Print one line of the prompt in the window within the limits of
2108 the specified right margin. The line will end on a word boundary
2109 and a pointer to the start of the next line is returned, or a NULL
2110 pointer if the end of *prompt is reached.
2111 WINDOW *win
2113 is the window to update.
2114 chtype *attr
2116 holds the starting attributes, and is updated to reflect the
2117 final attributes applied to the string.
2118 const char *prompt
2120 is the string to print
2121 int lm
2123 is the left margin.
2124 int rm
2126 is the right margin
2127 int *x
2129 returns the ending x-ordinate.
2130 dlg_prev_ok_buttonindex
2132 Find the previous button index in the list from dlg_ok_labels.
2133 int current
2135 is the current index
2136 int extra
2138 if negative provides a way to enumerate extra active areas on
2139 the widget.
2140 dlg_print_autowrap
2142 Print a string of text in a window, automatically wrap around to
2143 the next line if the string is too long to fit on one line. Note
2144 that the string may contain embedded newlines. The text is writ‐
2145 ten starting at the top of the window.
2146 WINDOW * win
2148 is the window to update.
2149 const char * prompt
2151 is the string to print
2152 int height
2154 is the nominal height the wrapped string is limited to
2155 int width
2157 is the width that the wrapping should occur in
2158 dlg_print_size
2160 If dialog_vars.print_siz is true, print the given height/width
2161 (from a widget) to dialog_state.output, e.g., Size: height, width.
2162 int height
2164 is the window's height
2165 int width
2167 is the window's width
2168 dlg_print_text
2170 Print up to cols columns from text, optionally rendering dialog's
2171 escape sequences for attributes and color.
2172 WINDOW * win
2174 is the window to update.
2175 const char * txt
2177 is the string to print
2178 int col
2180 is the column limit
2181 chtype * attr
2183 holds the starting attributes, and is updated to reflect the
2184 final attributes applied to the string.
2185 dlg_put_backtitle
2187 Display the background title if dialog_vars.backtitle is non-null.
2188 The background title is shown at the top of the screen.
2189 dlg_register_buttons
2191 The widget developer should call this function after dlg_regis‐
2192 ter_window, for the list of button labels associated with the wid‐
2193 get. One may bind a key to a button, e.g., "OK" for DLGK_OK,
2194 WINDOW * win
2196 is the window with which to associate the buttons
2197 const char * name
2199 is the widget's binding name (usually the name of the wid‐
2200 get).
2201 const char ** buttons
2203 is the list of buttons
2204 dlg_register_window
2206 For a given named widget's window, associate a binding table.
2207 WINDOW * win
2209 is the window with which to associate the buttons
2210 const char * name
2212 is the widget's binding name (usually the name of the wid‐
2213 get).
2214 DLG_KEYS_BINDING * binding
2216 is the binding table
2217 dlg_remove_callback
2219 Remove a callback.
2220 DIALOG_CALLBACK * p
2222 contains the callback information.
2223 dlg_restore_vars
2225 Restore dialog's variables from the given variable (see dia‐
2226 log_save_vars).
2227 DIALOG_VARS * save
2229 is the variable from which to restore.
2230 dlg_result_key
2232 Test a dialog internal keycode to see if it corresponds to one of
2233 the push buttons on the widget such as "OK". This is only useful
2234 if there are user-defined key bindings, since there are no built-
2235 in bindings that map directly to DLGK_OK, etc. Return true if a
2236 mapping was done.
2237 int dialog_key
2239 is the dialog key to test
2240 int fkey
2242 is true if this is a function key
2243 int * resultp
2245 store the result of the mapping in the referenced location.
2246 dlg_save_vars
2248 Save dialog's variables into the given variable (see dia‐
2249 log_restore_vars).
2250 DIALOG_VARS * save
2252 is the variable into which to save.
2253 dlg_set_focus
2255 Set focus on the given window, making it display above other win‐
2256 dows on the screen.
2257 WINDOW * parent
2259 is the parent window (usually the top-level window of a wid‐
2260 get)
2261 WINDOW * win
2263 is the window on which to place focus (usually a subwindow of
2264 a widget)
2265 dlg_set_result
2267 Setup a fixed-buffer for the result in dialog_vars.input_result
2268 const char * string
2270 is the new contents for the result
2271 dlg_show_string
2273 Displays the string, shifted as necessary, to fit within the box
2274 and show the current character-offset.
2275 WINDOW * win
2277 is the window within which to display
2278 const char * string
2280 is the string to display
2281 int offset
2283 is the starting (character, not bytes) offset
2284 chtype attr
2286 is the window attribute to use for the string
2287 int y_base
2289 beginning row on screen
2290 int x_base
2292 beginning column on screen
2293 int x_last
2295 number of columns on screen
2296 bool hidden
2298 if true, do not echo input
2299 bool force
2301 if true, force repaint
2302 dlg_strclone
2304 duplicate the string, like strdup.
2305 const char * cprompt
2307 is the string to duplicate
2308 dlg_strcmp
2310 compare two strings, ignoring case.
2311 const char * a
2313 is one string
2314 const char * b
2316 is the other string
2317 dlg_sub_window
2319 create a subwindow, e.g., for an input area of a widget
2320 WINDOW * win
2322 is the parent window
2323 int height
2325 is the subwindow's height
2326 int width
2328 is the subwindow's width
2329 int y
2331 is the subwindow's top-row
2332 int x
2334 is the subwindow's left-column
2335 dlg_tab_correct_str
2337 If the dialog_vars.tab_correct is true, convert tabs to single
2338 spaces. Return the converted result. The caller is responsible
2339 for freeing the string.
2340 char * prompt
2342 is the string to convert
2343 dlg_trace
2345 If the parameter is non-null, opens a trace file with that name
2346 and stores the file pointer in dialog_state.trace.
2347 dlg_trace_chr
2349 If dialog_state.trace is set, translate the parameters into a
2350 printable representation, log it on a "chr" line.
2351 int ch
2353 is the nominal keycode value.
2354 int fkey
2356 is nonzero if the value is really a function key. Some of
2357 these may be values declared in the DLG_KEYS_ENUM.
2358 dlg_trace_win
2360 If dialog_state.trace is set, log a printable picture of the given
2361 window.
2362 dlg_trim_string
2364 Change embedded "\n" substrings to '\n' characters and tabs to
2365 single spaces. If there are no "\n"s, the function strips all
2366 extra spaces, for justification. If it has "\n"'s, the function
2367 preserves extra spaces. If dialog_vars.cr_wrap is set, the func‐
2368 tion preserves '\n's.
2369 char * src
2371 is the string to trim
2372 dlg_unregister_window
2374 Remove the bindings for a given window.
2375 WINDOW * win
2377 is the window from which to remove bindings
2378 dlg_yes_buttoncode
2380 Map the given button index for dlg_yes_labels into dialog's exit-
2381 code.
2382 int button
2384 is the button index
2385 dlg_yes_labels
2387 Return a list of buttons for Yes/No labels.
2388
2390 dialog (1).
2391
2393 Thomas E. Dickey
2394$Date: 2010/02/23 10:33:59 $ DIALOG(3)