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 DEFINITIONS
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 DATA STRUCTURES
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_shadow
138 This corresponds to the command-line option "--no-shadow". This
139 is set in init_dialog if the curses implementation supports
140 color. If true, suppress shadows that would be drawn to the
141 right and bottom of each dialog box.
142 DIALOG_STATE.visit_items
144 This corresponds to the command-line option "--visit-items".
145 The dialog application resets the dialog_vars data before accepting
147 options to invoke each widget. Most of the DIALOG_VARS members are set
148 directly from dialog's command-line options:
149 DIALOG_VARS.ascii_lines
151 DIALOG_VARS.backtitle
153 This corresponds to the command-line option "--backtitle backti‐
154 tle". It specifies a backtitle string to be displayed on the
155 backdrop, at the top of the screen.
156 DIALOG_VARS.beep_after_signal
158 This corresponds to the command-line option "--beep-after". If
159 true, beep after a user has completed a widget by pressing one
160 of the buttons.
161 DIALOG_VARS.beep_signal
163 This corresponds to the command-line option "--beep". It is
164 obsolete.
165 DIALOG_VARS.begin_set
167 This is true if the command-line option "--begin y x" was used.
168 It specifies the position of the upper left corner of a dialog
169 box on the screen.
170 DIALOG_VARS.begin_x
172 This corresponds to the x value from the command-line option
173 "--begin y x" (second value).
174 DIALOG_VARS.begin_y
176 This corresponds to the y value from the command-line option
177 "--begin y x" (first value).
178 DIALOG_VARS.cancel_label
180 This corresponds to the command-line option "--cancel-label
181 string". The given string overrides the label used for "Cancel"
182 buttons.
183 DIALOG_VARS.cant_kill
185 This corresponds to the command-line option "--no-kill". If
186 true, this tells dialog to put the tailboxbg box in the back‐
187 ground, printing its process id to dialog's output. SIGHUP is
188 disabled for the background process.
189 DIALOG_VARS.colors
191 This corresponds to the command-line option "--colors". If
192 true, interpret embedded "\Z" sequences in the dialog text by
193 the following character, which tells dialog to set colors or
194 video attributes: 0 through 7 are the ANSI codes used in curses:
195 black, red, green, yellow, blue, magenta, cyan and white respec‐
196 tively. Bold is set by 'b', reset by 'B'. Reverse is set by
197 'r', reset by 'R'. Underline is set by 'u', reset by 'U'. The
198 settings are cumulative, e.g., "\Zb\Z1" makes the following text
199 bright red. Restore normal settings with "\Zn".
200 DIALOG_VARS.column_separator
202 DIALOG_VARS.cr_wrap
204 This corresponds to the command-line option "--cr-wrap". If
205 true, interpret embedded newlines in the dialog text as a new‐
206 line on the screen. Otherwise, dialog will only wrap lines
207 where needed to fit inside the text box. Even though you can
208 control line breaks with this, dialog will still wrap any lines
209 that are too long for the width of the box. Without cr-wrap,
210 the layout of your text may be formatted to look nice in the
211 source code of your script without affecting the way it will
212 look in the dialog.
213 DIALOG_VARS.default_item
215 This corresponds to the command-line option "--default-item
216 string". The given string is used as the default item in a
217 checklist, form or menu box. Normally the first item in the box
218 is the default.
219 DIALOG_VARS.defaultno
221 This corresponds to the command-line option "--defaultno". If
222 true, make the default value of the yes/no box a No. Likewise,
223 make the default button of widgets that provide "OK" and "Can‐
224 cel" a Cancel. If --nocancel was given that option overrides
225 this, making the default button always "Yes" (internally the
226 same as "OK").
227 DIALOG_VARS.dlg_clear_screen
229 This corresponds to the command-line option "--clear". This
230 option is implemented in the main program, not the library. If
231 true, the screen will be cleared on exit. This may be used
232 alone, without other options.
233 DIALOG_VARS.exit_label
235 This corresponds to the command-line option "--exit-label
236 string". The given string overrides the label used for "EXIT"
237 buttons.
238 DIALOG_VARS.extra_button
240 This corresponds to the command-line option "--extra-button".
241 If true, some widgets show an extra button, between "OK" and
242 "Cancel" buttons.
243 DIALOG_VARS.extra_label
245 This corresponds to the command-line option "--extra-label
246 string". The given string overrides the label used for "Extra"
247 buttons. Note: for inputmenu widgets, this defaults to
248 "Rename".
249 DIALOG_VARS.formitem_type
251 This is set by the command-line option "--passwordform" to tell
252 the form widget that its text fields should be treated like
253 password widgets.
254 DIALOG_VARS.help_button
256 This corresponds to the command-line option "--help-button". If
257 true, some widgets show a help-button after "OK" and "Cancel"
258 buttons, i.e., in checklist, radiolist and menu boxes. If
259 --item-help is also given, on exit the return status will be the
260 same as for the "OK" button, and the item-help text will be
261 written to dialog's output after the token "HELP". Otherwise,
262 the return status will indicate that the Help button was
263 pressed, and no message printed.
264 DIALOG_VARS.help_label
266 This corresponds to the command-line option "--help-label
267 string". The given string overrides the label used for "Help"
268 buttons.
269 DIALOG_VARS.help_status
271 This corresponds to the command-line option "--help-status". If
272 true, and the the help-button is selected, writes the checklist
273 or radiolist information after the item-help "HELP" information.
274 This can be used to reconstruct the state of a checklist after
275 processing the help request.
276 DIALOG_VARS.input_length
278 This is nonzero if DIALOG_VARS.input_result is allocated, versus
279 being a pointer to the user's local variables.
280 DIALOG_VARS.input_menu
282 This flag is set to denote whether the menubox widget implements
283 a menu versus a inputmenu widget.
284 DIALOG_VARS.input_result
286 If DIALOG_VARS.input_length is zero, this is a pointer to user
287 buffer (on the stack, or static). When DIALOG_VARS.input_length
288 is nonzero, this is a dynamically-allocated buffer used by the
289 widgets to return printable results to the calling application.
290 DIALOG_VARS.insecure
292 This corresponds to the command-line option "--insecure". If
293 true, make the password widget friendlier but less secure, by
294 echoing asterisks for each character.
295 DIALOG_VARS.item_help
297 This corresponds to the command-line option "--item-help". If
298 true, interpret the tags data for checklist, radiolist and menu
299 boxes adding a column whose text is displayed in the bottom line
300 of the screen, for the currently selected item.
301 DIALOG_VARS.keep_tite
303 This is set by the command-line option "--keep-tite" to tell
304 dialog to not attempt to cancel the terminal initialization
305 (termcap ti/te) sequences which correspond to xterm's alternate-
306 screen switching. Normally dialog does this to avoid flickering
307 when run several times in a script.
308 DIALOG_VARS.keep_window
310 This corresponds to the command-line option "--keep-window". If
311 true, do not remove/repaint the window on exit. This is useful
312 for keeping the window contents visible when several widgets are
313 run in the same process. Note that curses will clear the screen
314 when starting a new process.
315 DIALOG_VARS.max_input
317 This corresponds to the command-line option "--max-input size".
318 Limit input strings to the given size. If not specified, the
319 limit is 2048.
320 DIALOG_VARS.no_label
322 This corresponds to the command-line option "--no-label string".
323 The given string overrides the label used for "No" buttons.
324 DIALOG_VARS.no_lines
326 DIALOG_VARS.nocancel
328 This corresponds to the command-line option "--no-cancel". If
329 true, suppress the "Cancel" button in checklist, inputbox and
330 menu box modes. A script can still test if the user pressed the
331 ESC key to cancel to quit.
332 DIALOG_VARS.nocollapse
334 This corresponds to the command-line option "--no-collapse".
335 Normally dialog converts tabs to spaces and reduces multiple
336 spaces to a single space for text which is displayed in a mes‐
337 sage boxes, etc. It true, that feature is disabled. Note that
338 dialog will still wrap text, subject to the --cr-wrap option.
339 DIALOG_VARS.nook
341 DIALOG_VARS.ok_label
343 This corresponds to the command-line option "--ok-label string".
344 The given string overrides the label used for "OK" buttons.
345 DIALOG_VARS.print_siz
347 This corresponds to the command-line option "--print-size". If
348 true, each widget prints its size to dialog's output when it is
349 invoked.
350 DIALOG_VARS.quoted
352 DIALOG_VARS.separate_output
354 This corresponds to the command-line option "--separate-output".
355 If true, checklist widgets output result one line at a time,
356 with no quoting. This facilitates parsing by another program.
357 DIALOG_VARS.single_quoted
359 This corresponds to the command-line option "--single-quoted".
360 If true, Use single-quoting as needed (and no quotes if
361 unneeded) for the output of checklist's as well as the item-help
362 text. If this option is not set, dialog uses double quotes
363 around each item. That requires occasional use of backslashes
364 to make the output useful in shell scripts.
365 DIALOG_VARS.size_err
367 This corresponds to the command-line option "--size-err". If
368 true, check the resulting size of a dialog box before trying to
369 use it, printing the resulting size if it is larger than the
370 screen. (This option is obsolete, since all new-window calls
371 are checked).
372 DIALOG_VARS.sleep_secs
374 This corresponds to the command-line option "--sleep secs".
375 This option is implemented in the main program, not the library.
376 If nonzero, this is the number of seconds after to delay after
377 processing a dialog box.
378 DIALOG_VARS.tab_correct
380 This corresponds to the command-line option "--tab-correct". If
381 true, convert each tab character of the text to one or more spa‐
382 ces. Otherwise, tabs are rendered according to the curses
383 library's interpretation.
384 DIALOG_VARS.timeout_secs
386 This corresponds to the command-line option "--timeout secs".
387 If nonzero, timeout input requests (exit with error code) if no
388 user response within the given number of seconds.
389 DIALOG_VARS.title
391 This corresponds to the command-line option "--title title".
392 Specifies a title string to be displayed at the top of the dia‐
393 log box.
394 DIALOG_VARS.trim_whitespace
396 This corresponds to the command-line option "--trim". If true,
397 eliminate leading blanks, trim literal newlines and repeated
398 blanks from message text.
399 DIALOG_VARS.visit_items
401 This corresponds to the command-line option "--visit-items".
402 Modify the tab-traversal of checklist, radiobox, menubox and
403 inputmenu to include the list of items as one of the states.
404 This is useful as a visual aid, i.e., the cursor position helps
405 some users.
406 DIALOG_VARS.yes_label
408 This corresponds to the command-line option "--yes-label
409 string". The given string overrides the label used for "Yes"
410 buttons.
411 WIDGETS
413 Functions that implement major functionality for the command-line dia‐
414 log program, e.g., widgets, have names beginning "dialog_".
415 All dialog boxes have at least three parameters:
417 title
419 the caption for the box, shown on its top border.
420 height
422 the height of the dialog box.
423 width
425 the width of the dialog box.
426 Other parameters depend on the box type.
428 dialog_calendar
430 implements the "--calendar" option.
431 title is the title on the top of the widget.
433 subtitle
435 is the prompt text shown within the widget.
436 height is the height excluding the fixed-height calendar grid.
438 width is the overall width of the box, which is adjusted up to
440 the calendar grid's minimum width if needed.
441 day is the initial day of the week shown, counting zero as
443 Sunday. If the value is negative, the current day of the
444 week is used.
445 month is the initial month of the year shown, counting one as
447 January. If the value is negative, the current month of
448 the year is used.
449 year is the initial year shown. If the value is negative, the
451 current year is used.
452 dialog_checklist
454 implements the "--checklist" and "--radiolist" options depending
455 on the flag parameter.
456 title is the title on the top of the widget.
458 cprompt
460 is the prompt text shown within the widget.
461 height is the desired height of the box. If zero, the height is
463 adjusted to use the available screen size.
464 width is the desired width of the box. If zero, the height is
466 adjusted to use the available screen size.
467 list_height
469 is the minimum height to reserve for displaying the list.
470 If zero, it is computed based on the given height and
471 width.
472 item_no
474 is the number of rows in items.
475 items is an array of strings which is viewed either as a list
477 of rows
478 tag item status
479 or
481 tag item status help
482 depending on whether dialog_vars.item_help is set.
484 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for
486 radiolists.
487 dialog_dselect
489 implements the "--dselect" option.
490 title is the title on the top of the widget.
492 path is the preselected value to show in the input-box, which
494 is used also to set the directory- and file-windows.
495 height is the height excluding the minimum needed to show the
497 dialog box framework. If zero, the height is based on
498 the screen size.
499 width is the desired width of the box. If zero, the height is
501 based on the screen size.
502 dialog_editbox
504 implements the "--editbox" option.
505 title is the title on the top of the widget.
507 file is the name of the file from which to read.
509 height is the desired height of the box. If zero, the height is
511 adjusted to use the available screen size.
512 width is the desired width of the box. If zero, the height is
514 adjusted to use the available screen size.
515 dialog_form
517 implements the "--form" option.
518 title is the title on the top of the widget.
520 cprompt
522 is the prompt text shown within the widget.
523 height is the desired height of the box. If zero, the height is
525 adjusted to use the available screen size.
526 width is the desired width of the box. If zero, the height is
528 adjusted to use the available screen size.
529 form_height
531 is the minimum height to reserve for displaying the list.
532 If zero, it is computed based on the given height and
533 width.
534 item_no
536 is the number of rows in items.
537 items is an array of strings which is viewed either as a list
539 of rows
540 Name NameY NameX Text TextY TextX FLen ILen
541 or
543 Name NameY NameX Text TextY TextX FLen ILen Help
544 depending on whether dialog_vars.item_help is set.
546 dialog_fselect
548 implements the "--fselect" option.
549 title is the title on the top of the widget.
551 path is the preselected value to show in the input-box, which
553 is used also to set the directory- and file-windows.
554 height is the height excluding the minimum needed to show the
556 dialog box framework. If zero, the height is based on
557 the screen size.
558 width is the desired width of the box. If zero, the height is
560 based on the screen size.
561 dialog_gauge
563 implements the "--gauge" option.
564 title is the title on the top of the widget.
566 cprompt
568 is the prompt text shown within the widget.
569 height is the desired height of the box. If zero, the height is
571 based on the screen size.
572 width is the desired width of the box. If zero, the height is
574 based on the screen size.
575 percent
577 is the percentage to show in the progress bar.
578 dialog_inputbox
580 implements the "--inputbox" or "--password" option, depending on
581 the value of password.
582 title is the title on the top of the widget.
584 cprompt
586 is the prompt text shown within the widget.
587 height is the desired height of the box. If zero, the height is
589 based on the screen size.
590 width is the desired width of the box. If zero, the height is
592 based on the screen size.
593 init is the initial value of the input box, whose length is
595 taken into account when auto-sizing the width of the dia‐
596 log box.
597 password
599 if true, causes typed input to be echoed as asterisks.
600 dialog_menu
602 implements the "--menu" or "--inputmenu" option depending on
603 whether dialog_vars.input_menu is set.
604 title is the title on the top of the widget.
606 cprompt
608 is the prompt text shown within the widget.
609 height is the desired height of the box. If zero, the height is
611 based on the screen size.
612 width is the desired width of the box. If zero, the height is
614 based on the screen size.
615 menu_height
617 is the minimum height to reserve for displaying the list.
618 If zero, it is computed based on the given height and
619 width.
620 item_no
622 is the number of rows in items.
623 items is an array of strings which is viewed either as a list
625 of rows
626 tag item
627 or
629 tag item help
630 depending on whether dialog_vars.item_help is set.
632 dialog_mixedform
634 implements the "--mixedform" option.
635 title is the title on the top of the widget.
637 cprompt
639 is the prompt text shown within the widget.
640 height is the desired height of the box. If zero, the height is
642 adjusted to use the available screen size.
643 width is the desired width of the box. If zero, the height is
645 adjusted to use the available screen size.
646 form_height
648 is the minimum height to reserve for displaying the list.
649 If zero, it is computed based on the given height and
650 width.
651 item_no
653 is the number of rows in items.
654 items is an array of strings which is viewed either as a list
656 of rows
657 Name NameY NameX Text TextY TextX FLen ILen Ityp
658 or
660 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
661 depending on whether dialog_vars.item_help is set.
663 dialog_mixedgauge
665 implements the "--mixedgauge" option
666 title is the title on the top of the widget.
668 cprompt
670 is the caption text shown within the widget.
671 height is the desired height of the box. If zero, the height is
673 based on the screen size.
674 width is the desired width of the box. If zero, the height is
676 based on the screen size.
677 percent
679 is the percentage to show in the progress bar.
680 item_no
682 is the number of rows in items.
683 items is an array of strings which is viewed as a list of tag
685 and item values. The tag values are listed, one per row,
686 in the list at the top of the widget.
687 The item values are decoded: digits 0-9 are the following
689 strings
690 0 Succeeded
692 1 Failed
694 2 Passed
696 3 Completed
698 4 Checked
700 5 Done
702 6 Skipped
704 7 In Progress
706 8 (blank)
708 9 N/A
710 A string with a leading "-" character is centered, marked
712 with "%". For example, "-75" is displayed as "75%".
713 Other strings are displayed as is.
714 dialog_msgbox
716 implements the "--msgbox" or "--infobox" option depending on
717 whether pauseopt is set.
718 title is the title on the top of the widget.
720 cprompt
722 is the prompt text shown within the widget.
723 height is the desired height of the box. If zero, the height is
725 based on the screen size.
726 width is the desired width of the box. If zero, the height is
728 based on the screen size.
729 pauseopt
731 if true, an "OK" button will be shown, and the dialog
732 will wait for it to complete. With an "OK" button, it is
733 denoted a "msgbox", without an "OK" button, it is denoted
734 an "infobox".
735 dialog_pause
737 implements the "--pause" option.
738 title is the title on the top of the widget.
740 height is the desired height of the box. If zero, the height is
742 based on the screen size.
743 width is the desired width of the box. If zero, the height is
745 based on the screen size.
746 seconds
748 is the timeout to use for the progress bar.
749 dialog_progressbox
751 implements the "--progressbox" option.
752 title is the title on the top of the widget.
754 cprompt
756 is the prompt text shown within the widget. If empty or
757 null, no prompt is shown.
758 height is the desired height of the box. If zero, the height is
760 based on the screen size.
761 width is the desired width of the box. If zero, the height is
763 based on the screen size.
764 dialog_tailbox
766 implements the "--tailbox" or "--tailboxbg" option depending on
767 whether bg_task is set.
768 title is the title on the top of the widget.
770 file is the name of the file to display in the dialog.
772 height is the desired height of the box. If zero, the height is
774 based on the screen size.
775 width is the desired width of the box. If zero, the height is
777 based on the screen size.
778 bg_task
780 if true, the window is added to the callback list in dia‐
781 log_state, and the application will poll for the window
782 to be updated. Otherwise an "OK" button is added to the
783 window, and it will be closed when the button is acti‐
784 vated.
785 dialog_textbox
787 implements the "--textbox" option.
788 title is the title on the top of the widget.
790 file is the name of the file to display in the dialog.
792 height is the desired height of the box. If zero, the height is
794 based on the screen size.
795 width is the desired width of the box. If zero, the height is
797 based on the screen size.
798 dialog_timebox
800 implements the "--timebox" option.
801 title is the title on the top of the widget.
803 subtitle
805 is the prompt text shown within the widget.
806 height is the desired height of the box. If zero, the height is
808 based on the screen size.
809 width is the desired width of the box. If zero, the height is
811 based on the screen size.
812 hour is the initial hour shown. If the value is negative, the
814 current hour is used.
815 minute is the initial minute shown. If the value is negative,
817 the current minute is used.
818 second is the initial second shown. If the value is negative,
820 the current second is used.
821 dialog_yesno
823 implements the "--yesno" option.
824 title is the title on the top of the widget.
826 cprompt
828 is the prompt text shown within the widget.
829 height is the desired height of the box. If zero, the height is
831 based on the screen size.
832 width is the desired width of the box. If zero, the height is
834 based on the screen size.
835 UTILITY FUNCTIONS
837 Most functions that implement lower-level functionality for the com‐
838 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
839 ing to longstanding usage, the functions that initialize the display
840 and end it are named init_dialog and end_dialog.
841 The only non-widget function whose name begins with "dialog_" is dia‐
843 log_version, which returns the version number of the library as a
844 string.
845 Here is a brief summary of the utility functions and their parameters:
847 dlg_add_callback
849 Add a callback, used to allow polling input from multiple tailbox
850 widgets.
851 DIALOG_CALLBACK *p
853 contains the callback information.
854 dlg_add_quoted
856 Add a quoted string to the result buffer (see dlg_add_result).
857 char * string
859 is the string to add.
860 dlg_add_result
862 Add a quoted string to the result buffer dialog_vars.input_result.
863 char * string
865 is the string to add.
866 dlg_add_separator
868 Add an output-separator to the result buffer dia‐
869 log_vars.input_result. If dialog_vars.output_separator is set,
870 use that. Otherwise, if dialog_vars.separate_output is set, use
871 newline. If neither is set, use a space.
872 dlg_add_string
874 Add a quoted or unquoted string to the result buffer (see
875 dlg_add_quoted) and dlg_add_result), according to whether dia‐
876 log_vars.quoted is true.
877 char * string
879 is the string to add.
880 dlg_align_columns
882 Copy and reformat an array of pointers to strings, aligning
883 according to the column separator dialog_vars.column_separator.
884 If no column separator is set, the array will be unmodified; oth‐
885 erwise it is copied and reformatted.
886 Caveat: This function is only implemented for 8-bit characters.
888 char **target
890 This is the array to reformat. It points to the first string
891 to modify.
892 int per_row
894 This is the size of the struct for each row of the array.
895 int num_rows
897 This is the number of rows in the array.
898 dlg_asciibox
900 returns its parameter transformed to the corresponding "+" or "-",
901 etc. for the line-drawing characters used in dialog. If the
902 parameter is not a line-drawing or other special character such as
903 ACS_DARROW, it returns 0.
904 dlg_attr_clear
906 Set window to the given attribute.
907 WINDOW * win
909 is the window to update.
910 int height
912 is the number of rows to update.
913 int width
915 is the number of columns to update.
916 chtype attr
918 is the attribute, e.g., A_BOLD.
919 dlg_auto_size
921 Automatically size the window used for a widget. If the given
922 height or width are zero, justify the prompt text and return the
923 actual limits.
924 const char * title
926 is the title string to display at the top of the widget.
927 const char * prompt
929 is the message text which will be displayed in the widget,
930 used here to determine how large the widget should be.
931 int * height
933 is the nominal height.
934 int * width
936 is the nominal width.
937 int boxlines
939 is the number of lines to reserve in the vertical direction.
940 int mincols
942 is the minimum number of columns to use.
943 dlg_auto_sizefile
945 Like dlg_auto_size, but use a file contents to decide how large
946 the widget should be.
947 const char * title
949 is the title string to display at the top of the widget.
950 const char * file
952 is the name of the file.
953 int * height
955 is the nominal height. If it is -1, use the screen's height
956 after subtracting dialog_vars.begin_y if dia‐
957 log_vars.begin_set is true.
958 int *width
960 is the nominal width. If it is -1, use the screen's width
961 after subtracting dialog_vars.begin_x if dia‐
962 log_vars.begin_set is true.
963 int boxlines
965 is the number of lines to reserve on the screen for drawing
966 boxes.
967 int mincols
969 is the number of columns to reserve on the screen for drawing
970 boxes.
971 dlg_beeping
973 If dialog_vars.beep_signal is nonzero, this calls beep once and
974 sets dialog_vars.beep_signal to zero.
975 dlg_boxchar
977 returns its parameter transformed as follows:
978 - if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is
980 set.
981 - if dialog_vars.ascii_lines is set, returns the corresponding
983 "+" or "-", etc. for the line-drawing characters used in dia‐
984 log.
985 - otherwise, if dialog_vars.no_lines is set, returns a space for
987 the line-drawing characters.
988 - if the parameter is not a line-drawing or other special charac‐
990 ter such as ACS_DARROW, it returns the parameter unchanged.
991 dlg_box_x_ordinate
993 returns a suitable x-ordinate (column) for a new widget. If dia‐
994 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center
995 the widget on the screen (using the width parameter).
996 int width
998 is the width of the widget.
999 dlg_box_y_ordinate
1001 returns a suitable y-ordinate (row) for a new widget. If dia‐
1002 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center
1003 the widget on the screen (using the height parameter).
1004 int height
1006 is the height of the widget.
1007 dlg_button_count
1009 Count the buttons in the list.
1010 const char ** labels
1012 is a list of (pointers to) button labels terminated by a null
1013 pointer.
1014 dlg_button_layout
1016 Make sure there is enough space for the buttons by computing the
1017 width required for their labels, adding margins and limiting based
1018 on the screen size.
1019 const char ** labels
1021 is a list of (pointers to) button labels terminated by a null
1022 pointer.
1023 int * limit
1025 the function sets the referenced limit to the width required
1026 for the widest label (limited by the screen size) if that is
1027 wider than the passed-in limit.
1028 dlg_button_sizes
1030 Compute the size of the button array in columns.
1031 const char ** labels
1033 is a list of (pointers to) button labels terminated by a null
1034 pointer.
1035 int vertical
1037 is true if the buttons are arranged in a column rather than a
1038 row.
1039 int * longest
1041 Return the total number of columns in the referenced loca‐
1042 tion.
1043 int * length
1045 Return the longest button's columns in the referenced loca‐
1046 tion.
1047 dlg_button_x_step
1049 Compute the step-size needed between elements of the button array.
1050 const char ** labels
1052 is a list of (pointers to) button labels terminated by a null
1053 pointer.
1054 int limit
1056 is the maximum number of columns to allow for the buttons.
1057 int * gap
1059 store the nominal gap between buttons in the referenced loca‐
1060 tion. This is constrained to be at least one.
1061 int * margin
1063 store the left+right total margins (for the list of buttons)
1064 in the referenced location.
1065 int * step
1067 store the step-size in the referenced location.
1068 dlg_button_to_char
1070 Find the first uppercase character in the label, which we may use
1071 for an abbreviation. If the label is empty, return -1. If no
1072 uppercase character is found, return 0. Otherwise return the
1073 uppercase character.
1074 const char * label
1076 is the label to test.
1077 dlg_calc_list_width
1079 Calculate the minimum width for the list, assuming none of the
1080 items are truncated.
1081 int item_no
1083 is the number of items.
1084 DIALOG_LISTITEM * items
1086 contains a name and text field, e.g., for checklists or
1087 radiobox lists. The function returns the sum of the widest
1088 columns needed for of each of these fields.
1089 dlg_calc_listh
1091 Calculate new height and list_height values.
1092 int * height
1094 on input, is the height without adding the list-height. On
1095 return, this contains the total list-height and is the actual
1096 widget's height.
1097 int * list_height
1099 on input, is the requested list-height. On return, this con‐
1100 tains the number of rows available for displaying the list
1101 after taking into account the screen size and the dia‐
1102 log_vars.begin_set and dialog_vars.begin_y variables.
1103 int item_no
1105 is the number of items in the list.
1106 dlg_calc_listw
1108 This function is obsolete, provided for library-compatibility. It
1109 is replaced by dlg_calc_list_width.
1110 int item_no
1112 is the number of items.
1113 char ** items
1115 is a list of character pointers.
1116 int group
1118 is the number of items in each group, e.g., the second array
1119 index.
1120 dlg_char_to_button
1122 Given a list of button labels, and a character which may be the
1123 abbreviation for one, find it, if it exists. An abbreviation will
1124 be the first character which happens to be capitalized in the
1125 label. If the character is found, return its index within the
1126 list of labels. Otherwise, return DLG_EXIT_UNKNOWN.
1127 int ch
1129 is the character to find.
1130 const char ** labels
1132 is a list of (pointers to) button labels terminated by a null
1133 pointer.
1134 dlg_checklist
1136 This entrypoint provides the --checklist or --radiolist function‐
1137 ality without the limitations of dialog's command-line syntax
1138 (compare to dialog_checklist).
1139 const char * title
1141 is the title string to display at the top of the widget.
1142 const char * cprompt
1144 is the prompt text shown within the widget.
1145 int height
1147 is the desired height of the box. If zero, the height is
1148 adjusted to use the available screen size.
1149 int width
1151 is the desired width of the box. If zero, the height is
1152 adjusted to use the available screen size.
1153 int list_height
1155 is the minimum height to reserve for displaying the list. If
1156 zero, it is computed based on the given height and width.
1157 int item_no
1159 is the number of items.
1160 DIALOG_LISTITEM * items
1162 This is a list of the items to display in the checklist.
1163 const char * states
1165 This is a list of characters to display for the given states.
1166 Normally a checklist provides true (1) and false (0) values,
1167 which the widget displays as "*" and space, respectively. An
1168 application may set this parameter to an arbitrary null-ter‐
1169 minated string. The widget determines the number of states
1170 from the length of this string, and will cycle through the
1171 corresponding display characters as the user presses the
1172 space-bar.
1173 int flag
1175 This is should be one of FLAG_CHECK or FLAG_RADIO, depending
1176 on whether the widget should act as a checklist or radiobox.
1177 int * current_item
1179 The widget sets the referenced location to the index of the
1180 current display item (cursor) when it returns.
1181 dlg_clear
1183 Set window to the default dialog screen attribute. This is set in
1184 the rc-file with screen_color.
1185 dlg_clr_result
1187 Free storage used for the result buffer (dia‐
1188 log_vars.input_result).
1189 dlg_color_count
1191 Return the number of colors that can be configured in dialog.
1192 dlg_color_setup
1194 Initialize the color pairs used in dialog.
1195 dlg_count_columns
1197 Returns the number of columns used for a string. This is not nec‐
1198 essarily the number of bytes in a string.
1199 const char * string
1201 is the string to measure.
1202 dlg_count_wchars
1204 Returns the number of wide-characters in the string.
1205 const char * string
1207 is the string to measure.
1208 dlg_create_rc
1210 Create a configuration file, i.e., write internal tables to a file
1211 which can be read back by dialog as an rc-file.
1212 const char * filename
1214 is the name of the file to write to.
1215 dlg_ctl_size
1217 If dialog_vars.size_err is true, check if the given window size is
1218 too large to fit on the screen. If so, exit with an error report‐
1219 ing the size of the window.
1220 int height
1222 is the window's height
1223 int width
1225 is the window's width
1226 dlg_default_formitem
1228 If dialog_vars.default_item is not null, find that name by match‐
1229 ing the name field in the list of form items. If found, return
1230 the index of that item in the list. Otherwise, return zero.
1231 DIALOG_FORMITEM * items
1233 is the list of items to search. It is terminated by an entry
1234 with a null name field.
1235 dlg_default_item
1237 This function is obsolete, provided for library-compatibility. It
1238 is replaced by dlg_default_formitem and dlg_default_listitem.
1239 char ** items
1241 is the list of items to search.
1242 int llen
1244 is the number of items in each group, e.g., the second array
1245 index.
1246 dlg_defaultno_button
1248 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not,
1249 find the button-index for the "Cancel" button. Otherwise, return
1250 the index for "OK" (always zero).
1251 dlg_del_window
1253 Remove a window, repainting everything else.
1254 WINDOW * win
1256 is the window to remove.
1257 dlg_does_output
1259 This is called each time a widget is invoked which may do output.
1260 It increments dialog_state.output_count, so the output function in
1261 dialog can test this and add a separator.
1262 dlg_draw_arrows
1264 Draw up/down arrows on a window, e.g., for scrollable lists. It
1265 calls dlg_draw_arrows2 using the menubox_color and menubox_bor‐
1266 der_color attributes.
1267 WINDOW * dialog
1269 is the window on which to draw an arrow.
1270 int top_arrow
1272 is true if an up-arrow should be drawn at the top of the win‐
1273 dow.
1274 int bottom_arrow
1276 is true if an down-arrow should be drawn at the bottom of the
1277 window.
1278 int x
1280 is the zero-based column within the window on which to draw
1281 arrows.
1282 int top
1284 is the zero-based row within the window on which to draw up-
1285 arrows as well as a horizontal line to show the window's top.
1286 int bottom
1288 is the zero-based row within the window on which to draw
1289 down-arrows as well as a horizontal line to show the window's
1290 bottom.
1291 dlg_draw_arrows2
1293 Draw up/down arrows on a window, e.g., for scrollable lists.
1294 WINDOW * dialog
1296 is the window on which to draw an arrow.
1297 int top_arrow
1299 is true if an up-arrow should be drawn at the top of the win‐
1300 dow.
1301 int bottom_arrow
1303 is true if an down-arrow should be drawn at the bottom of the
1304 window.
1305 int x
1307 is the zero-based column within the window on which to draw
1308 arrows.
1309 int top
1311 is the zero-based row within the window on which to draw up-
1312 arrows as well as a horizontal line to show the window's top.
1313 int bottom
1315 is the zero-based row within the window on which to draw
1316 down-arrows as well as a horizontal line to show the window's
1317 bottom.
1318 chtype attr
1320 is the window's background attribute.
1321 chtype borderattr
1323 is the window's border attribute.
1324 dlg_draw_bottom_box
1326 Draw a partial box at the bottom of a window, e.g., to surround a
1327 row of buttons. It is designed to merge with an existing box
1328 around the whole window, so it uses tee-elements rather than cor‐
1329 ner-elements on the top corners of this box.
1330 WINDOW * win
1332 is the window to update.
1333 dlg_draw_box
1335 Draw a rectangular box with line drawing characters.
1336 WINDOW * win
1338 is the window to update.
1339 int y
1341 is the top row of the box.
1342 int x
1344 is the left column of the box.
1345 int height
1347 is the height of the box.
1348 int width
1350 is the width of the box.
1351 chtype boxchar
1353 is used to color the right/lower edges. It also is fill-
1354 color used for the box contents.
1355 chtype borderchar
1357 is used to color the upper/left edges.
1358 dlg_draw_buttons
1360 Print a list of buttons at the given position.
1361 WINDOW * win
1363 is the window to update.
1364 int y
1366 is the starting row.
1367 int x
1369 is the starting column.
1370 const char ** labels
1372 is a list of (pointers to) button labels terminated by a null
1373 pointer.
1374 int selected
1376 is the index within the list of the selected button.
1377 int vertical
1379 is true if the buttons are arranged in a column rather than a
1380 row.
1381 int limit
1383 is the number of columns (or rows if vertical) allowed for
1384 the display.
1385 dlg_draw_shadow
1387 Draw shadows along the right and bottom edge of a window to give
1388 it a 3-dimensional look. (The height, etc., may not be the same
1389 as the window's actual values).
1390 WINDOW * win
1392 is the window to update.
1393 int height
1395 is the height of the window.
1396 int width
1398 is the width of the window.
1399 int y
1401 is the top row of the window.
1402 int x
1404 is the left column of the window.
1405 dlg_draw_title
1407 Draw a title centered at the top of the window.
1408 WINDOW * win
1410 is the window to update.
1411 const char * title
1413 is the title string to display at the top of the widget.
1414 dlg_dump_keys
1416 Write all user-defined key-bindings to the given stream, e.g., as
1417 part of dlg_create_rc.
1418 FILE * fp
1420 is the stream on which to write the bindings.
1421 dlg_edit_offset
1423 Given the character-offset in the string, returns the display-off‐
1424 set where dialog should position the cursor. In this context,
1425 "characters" may be multicolumn, since the string can be a multi‐
1426 byte character string.
1427 char * string
1429 is the string to analyze
1430 int offset
1432 is the character-offset
1433 int x_last
1435 is a limit on the column positions that can be used, e.g.,
1436 the window's size.
1437 dlg_edit_string
1439 Updates the string and character-offset, given various editing
1440 characters or literal characters which are inserted at the charac‐
1441 ter-offset. Returns true if an editing change was made (and the
1442 display should be updated), and false if the key was something
1443 like KEY_ENTER, which is a non-editing action outside this func‐
1444 tion.
1445 char * string
1447 is the (multibyte) string to update
1448 int * offset
1450 is the character-offset
1451 int key
1453 is the editing key
1454 int fkey
1456 is true if the editing key is a function-key
1457 bool force
1459 is used in a special loop case by calling code to force the
1460 return value of this function when a function-key code 0 is
1461 passed in.
1462 dlg_exit
1464 Given an internal exit code, check if the corresponding environ‐
1465 ment variable is set. If so, remap the exit code to match the
1466 environment variable. Finally call exit with the resulting exit
1467 code.
1468 int code
1470 is the internal exit code, e.g., DLG_EXIT_OK, which may be
1471 remapped.
1472 The dialog program uses this function to allow shell scripts to
1474 remap the exit codes so they can distinguish ESC from ERROR.
1475 dlg_exit_buttoncode
1477 Map the given button index for dlg_exit_label into dialog's exit-
1478 code.
1479 int button
1481 is the button index
1482 dlg_exit_label
1484 Return a list of button labels. If dialog_var.extra_button is
1485 true, return the result of dlg_ok_labels. Otherwise, return a
1486 list with the "Exit" label and (if dialog_vars.help_button is set)
1487 the "Help" button as well.
1488 dlg_exiterr
1490 Quit program killing all tailboxbg widgets.
1491 const char * fmt
1493 is the format of the printf-like message to write.
1494 are the variables to apply to the fmt format.
1496 dlg_find_index
1498 Given the character-offset to find in the list, return the corre‐
1499 sponding array index.
1500 const int *list
1502 contains a list of character-offsets, i.e., indices into a
1503 string that denote the beginning of multibyte characters.
1504 int limit
1506 is the last index into list to search.
1507 int to_find
1509 is the character-offset to find.
1510 dlg_flush_getc
1512 Cancel the local data saved by dlg_last_getc.
1513 dlg_editbox
1515 This entrypoint provides the --editbox functionality without the
1516 limitations of dialog's command-line syntax (compare to dia‐
1517 log_editbox).
1518 const char * title
1520 is the title string to display at the top of the widget.
1521 char *** list
1523 is a pointer to an array of char * pointers. The array is
1524 allocated by the caller, and so are the strings to which it
1525 points. The dlg_editbox function may reallocate the array
1526 and the strings.
1527 int * rows
1529 points to the nominal length of list. The referenced value
1530 is updated iflist is reallocated.
1531 int height
1533 is the desired height of the box. If zero, the height is
1534 adjusted to use the available screen size.
1535 int width
1537 is the desired width of the box. If zero, the height is
1538 adjusted to use the available screen size.
1539 dlg_form
1541 This entrypoint provides the --form functionality without the lim‐
1542 itations of dialog's command-line syntax (compare to dialog_form).
1543 const char * title
1545 is the title string to display at the top of the widget.
1546 const char * cprompt
1548 is the prompt text shown within the widget.
1549 int height
1551 is the desired height of the box. If zero, the height is
1552 adjusted to use the available screen size.
1553 int width
1555 is the desired width of the box. If zero, the height is
1556 adjusted to use the available screen size.
1557 int form_height
1559 is the minimum height to reserve for displaying the list. If
1560 zero, it is computed based on the given height and width.
1561 int item_no
1563 is the number of items.
1564 DIALOG_FORMITEM * items
1566 This is a list of the items to display in the form.
1567 int * current_item
1569 The widget sets the referenced location to the index of the
1570 current display item (cursor) when it returns.
1571 dlg_free_columns
1573 Free data allocated by dlg_align_columns.
1574 char **target
1576 This is the array which was reformatted. It points to the
1577 first string to free.
1578 int per_row
1580 This is the size of the struct for each row of the array.
1581 int num_rows
1583 This is the number of rows in the array.
1584 dlg_free_formitems
1586 Free memory owned by a list of DIALOG_FORMITEM's.
1587 DIALOG_FORMITEM * items
1589 is the list to free.
1590 dlg_getc
1592 Read a character from the given window. Handle repainting here
1593 (to simplify things in the calling application). Also, if input-
1594 callback(s) are set up, poll the corresponding files and handle
1595 the updates, e.g., for displaying a tailbox. Returns the key-
1596 code.
1597 WINDOW * win
1599 is the window within which to read.
1600 int * fkey
1602 as a side-effect, set this to true if the key-code is really
1603 a function-key.
1604 dlg_getc_callbacks
1606 passes the given key-code ch to the current window that has estab‐
1607 lished a callback. If the callback returns zero, remove it and
1608 try the next window. If no more callbacks remain, return. If any
1609 callbacks were found, return true, otherwise false.
1610 int ch
1612 is the key-code
1613 int fkey
1615 is true if the key is a function-key
1616 int * result
1618 is used to pass an exit-code to the caller, which should pass
1619 that via dlg_exit.
1620 dlg_index_columns
1622 Build a list of the display-columns for the given multibyte
1623 string's characters.
1624 const char * string
1626 is the string to analyze
1627 dlg_index_wchars
1629 Build an index of the wide-characters in the string, so the caller
1630 can easily tell which byte-offset begins a given wide-character.
1631 const char * string
1633 is the string to analyze
1634 dlg_item_help
1636 Draw the string for the dialog_vars.item_help feature.
1637 char * txt
1639 is the help-message
1640 dlg_killall_bg
1642 If dialog has callbacks active, purge the list of all that are not
1643 marked to keep in the background. If any remain, run those in a
1644 background process.
1645 int * retval
1647 stores the exit-code to pass back to the caller.
1648 dlg_last_getc
1650 returns the most recent character that was read via dlg_getc.
1651 dlg_limit_columns
1653 Given a column limit, count the number of wide characters that can
1654 fit into that limit. The offset is used to skip over a leading
1655 character that was already written.
1656 const char * string
1658 is the string to analyze
1659 int limit
1661 is the column limit
1662 int offset
1664 is the starting offset from which analysis should continue
1665 dlg_lookup_key
1667 Check for a key-binding. If there is no binding associated with
1668 the widget, it simply returns the given curses-key. Otherwise, it
1669 returns the result of the binding
1670 WINDOW * win
1672 is the window on which the binding is checked
1673 int curses_key
1675 is the curses key-code
1676 int * dialog_key
1678 is the corresponding dialog internal code (see DLG_KEYS_ENUM
1679 in dlg_key.h).
1680 dlg_max_input
1682 Limit the parameter according to dialog_vars.max_input
1683 int max_len
1685 is the value to limit
1686 dlg_match_char
1688 Match a given character against the beginning of the string,
1689 ignoring case of the given character. The matching string must
1690 begin with an uppercase character.
1691 int ch
1693 is the character to check
1694 const char * string
1696 is the string to search
1697 dlg_menu
1699 This entrypoint provides the --menu functionality without the lim‐
1700 itations of dialog's command-line syntax (compare to dialog_menu).
1701 const char * title
1703 is the title string to display at the top of the widget.
1704 const char * cprompt
1706 is the prompt text shown within the widget.
1707 int height
1709 is the desired height of the box. If zero, the height is
1710 adjusted to use the available screen size.
1711 int width
1713 is the desired width of the box. If zero, the height is
1714 adjusted to use the available screen size.
1715 int menu_height
1717 is the minimum height to reserve for displaying the list. If
1718 zero, it is computed based on the given height and width.
1719 int item_no
1721 is the number of items.
1722 DIALOG_LISTITEM * items
1724 This is a list of the items to display in the form.
1725 int * current_item
1727 The widget sets the referenced location to the index of the
1728 current display item (cursor) when it returns.
1729 DIALOG_INPUTMENU rename_menutext
1731 dlg_move_window
1733 Moves/resizes the given window to the given position and size.
1734 WINDOW *win
1736 is the window to move/resize.
1737 WINDOW *height
1739 is the height of the resized window.
1740 WINDOW *width
1742 is the width of the resized window.
1743 WINDOW *y
1745 y-ordinate to use for the repositioned window.
1746 WINDOW *x
1748 x-ordinate to use for the repositioned window.
1749 dlg_mouse_bigregion
1751 Retrieve the big-region under the pointer.
1752 int y
1754 is the row on which the mouse click occurred
1755 int x
1757 is the column on which the mouse click occurred
1758 dlg_mouse_free_regions
1760 Free the memory associated with mouse regions.
1761 dlg_mouse_mkbigregion
1763 Creates a region on which the mouse-clicks will return a specifed
1764 code.
1765 int y
1767 is the top-row of the region.
1768 int x
1770 is the left-column of the region.
1771 int height
1773 is the height of the region.
1774 int width
1776 is the width of the region.
1777 int code
1779 is a code used to make the region unique within a widget
1780 int step_x
1782 is used in modes 2 (columns) and 3 (cells) to determine the
1783 width of a column/cell.
1784 int step_y
1786 is currently unused
1787 int mode
1789 is used to determine how the mouse position is translated
1790 into a code (like a function-key):
1791 1 index by lines
1793 2 index by columns
1795 3 index by cells
1797 dlg_mouse_mkregion
1799 int y
1801 is the top-row of the region.
1802 int x
1804 is the left-column of the region.
1805 int height
1807 is the height of the region.
1808 int width
1810 is the width of the region.
1811 int code
1813 is a code used to make the region unique within a widget
1814 dlg_mouse_region
1816 Retrieve the frame under the mouse pointer
1817 int y
1819 is the row of the mouse-click
1820 int x
1822 is the column of the mouse-click
1823 dlg_mouse_setbase
1825 Sets a base for subsequent calls to dlg_mouse_mkregion, so they
1826 can make regions relative to the start of a given window.
1827 int x
1829 is the left-column for the base
1830 int y
1832 is the top-row for the base
1833 dlg_mouse_wgetch
1835 is a wrapper for dlg_getc which additionally maps mouse-clicks (if
1836 the curses library supports those) into extended function-keys
1837 which encode the position according to the mode in dlg_mouse_mkbi‐
1838 gregion. Returns the corresponding key-code.
1839 WINDOW * win
1841 is the window on which to perform the input
1842 int * fkey
1844 the referenced location is set to true if the key-code is an
1845 actual or extended (mouse) function-key.
1846 dlg_mouse_wgetch_nowait
1848 This is a non-blocking variant of dlg_mouse_wgetch.
1849 WINDOW * win
1851 is the window on which to perform the input
1852 int * fkey
1854 the referenced location is set to true if the key-code is an
1855 actual or extended (mouse) function-key.
1856 dlg_need_separator
1858 Check if an output-separator is needed. If dialog_vars.out‐
1859 put_separator is set, return true. Otherwise, if dia‐
1860 log_vars.input_result is nonempty, return true. If neither,
1861 return false.
1862 dlg_new_modal_window
1864 Create a modal window, optionally with a shadow. The shadow is
1865 created if dialog_state.use_shadow is true.
1866 WINDOW * parent
1868 is the parent window (usually the top-level window of a wid‐
1869 get)
1870 int height
1872 is the window's height
1873 int width
1875 is the window's width
1876 int y
1878 is the window's top-row
1879 int x
1881 is the window's left-column
1882 dlg_new_window
1884 Create a window, optionally with a shadow. The shadow is created
1885 if dialog_state.use_shadow is true.
1886 int height
1888 is the window's height
1889 int width
1891 is the window's width
1892 int y
1894 is the window's top-row
1895 int x
1897 is the window's left-column
1898 dlg_next_button
1900 Return the next index in the list of labels.
1901 const char ** labels
1903 is a list of (pointers to) button labels terminated by a null
1904 pointer.
1905 int button
1907 is the current button-index.
1908 dlg_next_ok_buttonindex
1910 Assuming that the caller is using dlg_ok_labels to list buttons,
1911 find the next index in the list of buttons.
1912 int current
1914 is the current index in the list of buttons
1915 int extra
1917 if negative, provides a way to enumerate extra active areas
1918 on the widget.
1919 dlg_ok_buttoncode
1921 Map the given button index for dlg_ok_labels into dialog's exit-
1922 code.
1923 int button
1925 is the button-index (which is not necessarily the same as the
1926 index in the list of labels).
1927 dlg_ok_label
1929 Returns a list with the "Ok" label, and if dialog_vars.help_button
1930 is true, the "Help" label as well.
1931 dlg_ok_labels
1933 Return a list of button labels for the OK/Cancel group of widgets.
1934 dlg_ordinate
1936 Decode the string as an integer, decrement if greater than zero to
1937 make a curses-ordinate from a dialog-ordinate.
1938 dlg_parse_bindkey
1940 Parse the parameters of the "bindkeys" configuration-file entry.
1941 This expects widget name which may be "*", followed by curses key
1942 definition and then dialog key definition.
1943 char * params
1945 is the parameter string to parse.
1946 dlg_parse_rc
1948 Parse the configuration file and set up variables.
1949 dlg_prev_button
1951 Return the previous index in the list of labels.
1952 const char ** labels
1954 is a list of (pointers to) button labels terminated by a null
1955 pointer.
1956 int button
1958 is the current button index
1959 dlg_print_line
1961 Print one line of the prompt in the window within the limits of
1962 the specified right margin. The line will end on a word boundary
1963 and a pointer to the start of the next line is returned, or a NULL
1964 pointer if the end of *prompt is reached.
1965 WINDOW *win
1967 is the window to update.
1968 chtype *attr
1970 holds the starting attributes, and is updated to reflect the
1971 final attributes applied to the string.
1972 const char *prompt
1974 is the string to print
1975 int lm
1977 is the left margin.
1978 int rm
1980 is the right margin
1981 int *x
1983 returns the ending x-ordinate.
1984 dlg_prev_ok_buttonindex
1986 Find the previous button index in the list from dlg_ok_labels.
1987 int current
1989 is the current index
1990 int extra
1992 if negative provides a way to enumerate extra active areas on
1993 the widget.
1994 dlg_print_autowrap
1996 Print a string of text in a window, automatically wrap around to
1997 the next line if the string is too long to fit on one line. Note
1998 that the string may contain embedded newlines.
1999 WINDOW * win
2001 is the window to update.
2002 const char * prompt
2004 is the string to print
2005 int height
2007 is the nominal height the wrapped string is limited to
2008 int width
2010 is the width that the wrapping should occur in
2011 dlg_print_size
2013 If dialog_vars.print_siz is true, print the given height/width
2014 (from a widget) to dialog_state.output, e.g., Size: height, width.
2015 int height
2017 is the window's height
2018 int width
2020 is the window's width
2021 dlg_print_text
2023 Print up to cols columns from text, optionally rendering dialog's
2024 escape sequences for attributes and color.
2025 WINDOW * win
2027 is the window to update.
2028 const char * txt
2030 is the string to print
2031 int col
2033 is the column limit
2034 chtype * attr
2036 holds the starting attributes, and is updated to reflect the
2037 final attributes applied to the string.
2038 dlg_put_backtitle
2040 Display the background title if dialog_vars.backtitle is non-null.
2041 The background title is shown at the top of the screen.
2042 dlg_register_buttons
2044 The widget developer should call this function after dlg_regis‐
2045 ter_window, for the list of button labels associated with the wid‐
2046 get. One may bind a key to a button, e.g., "OK" for DLGK_OK,
2047 WINDOW * win
2049 is the window with which to associate the buttons
2050 const char * name
2052 is the widget's binding name (usually the name of the wid‐
2053 get).
2054 const char ** buttons
2056 is the list of buttons
2057 dlg_register_window
2059 For a given named widget's window, associate a binding table.
2060 WINDOW * win
2062 is the window with which to associate the buttons
2063 const char * name
2065 is the widget's binding name (usually the name of the wid‐
2066 get).
2067 DLG_KEYS_BINDING * binding
2069 is the binding table
2070 dlg_remove_callback
2072 Remove a callback.
2073 DIALOG_CALLBACK * p
2075 contains the callback information.
2076 dlg_restore_vars
2078 Restore dialog's variables from the given variable (see dia‐
2079 log_save_vars).
2080 DIALOG_VARS * save
2082 is the variable from which to restore.
2083 dlg_result_key
2085 Test a dialog internal keycode to see if it corresponds to one of
2086 the push buttons on the widget such as "OK". This is only useful
2087 if there are user-defined key bindings, since there are no built-
2088 in bindings that map directly to DLGK_OK, etc. Return true if a
2089 mapping was done.
2090 int dialog_key
2092 is the dialog key to test
2093 int fkey
2095 is true if this is a function key
2096 int * resultp
2098 store the result of the mapping in the referenced location.
2099 dlg_save_vars
2101 Save dialog's variables into the given variable (see dia‐
2102 log_restore_vars).
2103 DIALOG_VARS * save
2105 is the variable into which to save.
2106 dlg_set_focus
2108 Set focus on the given window, making it display above other win‐
2109 dows on the screen.
2110 WINDOW * parent
2112 is the parent window (usually the top-level window of a wid‐
2113 get)
2114 WINDOW * win
2116 is the window on which to place focus (usually a subwindow of
2117 a widget)
2118 dlg_set_result
2120 Setup a fixed-buffer for the result in dialog_vars.input_result
2121 const char * string
2123 is the new contents for the result
2124 dlg_show_string
2126 Displays the string, shifted as necessary, to fit within the box
2127 and show the current character-offset.
2128 WINDOW * win
2130 is the window within which to display
2131 const char * string
2133 is the string to display
2134 int offset
2136 is the starting (character, not bytes) offset
2137 chtype attr
2139 is the window attribute to use for the string
2140 int y_base
2142 beginning row on screen
2143 int x_base
2145 beginning column on screen
2146 int x_last
2148 number of columns on screen
2149 bool hidden
2151 if true, do not echo input
2152 bool force
2154 if true, force repaint
2155 dlg_strclone
2157 duplicate the string, like strdup.
2158 const char * cprompt
2160 is the string to duplicate
2161 dlg_strcmp
2163 compare two strings, ignoring case.
2164 const char * a
2166 is one string
2167 const char * b
2169 is the other string
2170 dlg_sub_window
2172 create a subwindow, e.g., for an input area of a widget
2173 WINDOW * win
2175 is the parent window
2176 int height
2178 is the subwindow's height
2179 int width
2181 is the subwindow's width
2182 int y
2184 is the subwindow's top-row
2185 int x
2187 is the subwindow's left-column
2188 dlg_tab_correct_str
2190 If the dialog_vars.tab_correct is true, convert tabs to single
2191 spaces. Return the converted result. The caller is responsible
2192 for freeing the string.
2193 char * prompt
2195 is the string to convert
2196 dlg_trace
2198 If the parameter is non-null, opens a trace file with that name
2199 and stores the file pointer in dialog_state.trace.
2200 dlg_trace_chr
2202 If dialog_state.trace is set, translate the parameters into a
2203 printable representation, log it on a "chr" line.
2204 int ch
2206 is the nominal keycode value.
2207 int fkey
2209 is nonzero if the value is really a function key. Some of
2210 these may be values declared in the DLG_KEYS_ENUM.
2211 dlg_trace_win
2213 If dialog_state.trace is set, log a printable picture of the given
2214 window.
2215 dlg_trim_string
2217 Change embedded "\n" substrings to '\n' characters and tabs to
2218 single spaces. If there are no "\n"s, the function strips all
2219 extra spaces, for justification. If it has "\n"'s, the function
2220 preserves extra spaces. If dialog_vars.cr_wrap is set, the func‐
2221 tion preserves '\n's.
2222 char * src
2224 is the string to trim
2225 dlg_unregister_window
2227 Remove the bindings for a given window.
2228 WINDOW * win
2230 is the window from which to remove bindings
2231 dlg_yes_buttoncode
2233 Map the given button index for dlg_yes_labels into dialog's exit-
2234 code.
2235 int button
2237 is the button index
2238 dlg_yes_labels
2240 Return a list of buttons for Yes/No labels.
2241
2243 dialog (1).
2244
2246 Thomas E. Dickey
2247$Date: 2008/07/28 00:01:05 $ DIALOG(3)