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 The dialog application resets the dialog_vars data before accepting
144 options to invoke each widget. Most of the DIALOG_VARS members are set
145 directly from dialog's command-line options:
146 DIALOG_VARS.backtitle
148 This corresponds to the command-line option "--backtitle backti‐
149 tle". It specifies a backtitle string to be displayed on the
150 backdrop, at the top of the screen.
151 DIALOG_VARS.beep_after_signal
153 This corresponds to the command-line option "--beep-after". If
154 true, beep after a user has completed a widget by pressing one
155 of the buttons.
156 DIALOG_VARS.beep_signal
158 This corresponds to the command-line option "--beep". It is
159 obsolete.
160 DIALOG_VARS.begin_set
162 This is true if the command-line option "--begin y x" was used.
163 It specifies the position of the upper left corner of a dialog
164 box on the screen.
165 DIALOG_VARS.begin_x
167 This corresponds to the x value from the command-line option
168 "--begin y x" (second value).
169 DIALOG_VARS.begin_y
171 This corresponds to the y value from the command-line option
172 "--begin y x" (first value).
173 DIALOG_VARS.cancel_label
175 This corresponds to the command-line option "--cancel-label
176 string". The given string overrides the label used for "Cancel"
177 buttons.
178 DIALOG_VARS.cant_kill
180 This corresponds to the command-line option "--no-kill". If
181 true, this tells dialog to put the tailboxbg box in the back‐
182 ground, printing its process id to dialog's output. SIGHUP is
183 disabled for the background process.
184 DIALOG_VARS.colors
186 This corresponds to the command-line option "--colors". If
187 true, interpret embedded "\Z" sequences in the dialog text by
188 the following character, which tells dialog to set colors or
189 video attributes: 0 through 7 are the ANSI used in curses:
190 black, red, green, yellow, blue, magenta, cyan and white respec‐
191 tively. Bold is set by 'b', reset by 'B'. Reverse is set by
192 'r', reset by 'R'. Underline is set by 'u', reset by 'U'. The
193 settings are cumulative, e.g., "\Zb\Z1" makes the following text
194 bright red. Restore normal settings with "\Zn".
195 DIALOG_VARS.cr_wrap
197 This corresponds to the command-line option "--cr-wrap". If
198 true, interpret embedded newlines in the dialog text as a new‐
199 line on the screen. Otherwise, dialog will only wrap lines
200 where needed to fit inside the text box. Even though you can
201 control line breaks with this, dialog will still wrap any lines
202 that are too long for the width of the box. Without cr-wrap,
203 the layout of your text may be formatted to look nice in the
204 source code of your script without affecting the way it will
205 look in the dialog.
206 DIALOG_VARS.default_item
208 This corresponds to the command-line option "--default-item
209 string". The given string is used as the default item in a
210 checklist, form or menu box. Normally the first item in the box
211 is the default.
212 DIALOG_VARS.defaultno
214 This corresponds to the command-line option "--defaultno". If
215 true, make the default value of the yes/no box a No. Likewise,
216 make the default button of widgets that provide "OK" and "Can‐
217 cel" a Cancel. If --nocancel was given that option overrides
218 this, making the default button always "Yes" (internally the
219 same as "OK").
220 DIALOG_VARS.dlg_clear_screen
222 This corresponds to the command-line option "--clear". This
223 option is implemented in the main program, not the library. If
224 true, the screen will be cleared on exit. This may be used
225 alone, without other options.
226 DIALOG_VARS.exit_label
228 This corresponds to the command-line option "--exit-label
229 string". The given string overrides the label used for "EXIT"
230 buttons.
231 DIALOG_VARS.extra_button
233 This corresponds to the command-line option "--extra-button".
234 If true, some widgets show an extra button, between "OK" and
235 "Cancel" buttons.
236 DIALOG_VARS.extra_label
238 This corresponds to the command-line option "--extra-label
239 string". The given string overrides the label used for "Extra"
240 buttons. Note: for inputmenu widgets, this defaults to
241 "Rename".
242 DIALOG_VARS.formitem_type
244 This is set by the command-line option "--passwordform" to tell
245 the form widget that its text fields should be treated like
246 password widgets.
247 DIALOG_VARS.help_button
249 This corresponds to the command-line option "--help-button". If
250 true, some widgets show a help-button after "OK" and "Cancel"
251 buttons, i.e., in checklist, radiolist and menu boxes. If
252 --item-help is also given, on exit the return status will be the
253 same as for the "OK" button, and the item-help text will be
254 written to dialog's output after the token "HELP". Otherwise,
255 the return status will indicate that the Help button was
256 pressed, and no message printed.
257 DIALOG_VARS.help_label
259 This corresponds to the command-line option "--help-label
260 string". The given string overrides the label used for "Help"
261 buttons.
262 DIALOG_VARS.help_status
264 This corresponds to the command-line option "--help-status". If
265 true, and the the help-button is selected, writes the checklist
266 or radiolist information after the item-help "HELP" information.
267 This can be used to reconstruct the state of a checklist after
268 processing the help request.
269 DIALOG_VARS.input_length
271 This is nonzero if DIALOG_VARS.input_result is allocated, versus
272 being a pointer to the user's local variables.
273 DIALOG_VARS.input_menu
275 This flag is set to denote whether the menubox widget implements
276 a menu versus a inputmenu widget.
277 DIALOG_VARS.input_result
279 If DIALOG_VARS.input_length is zero, this is a pointer to user
280 buffer (on the stack, or static). When DIALOG_VARS.input_length
281 is nonzero, this is a dynamically-allocated buffer used by the
282 widgets to return printable results to the calling application.
283 DIALOG_VARS.insecure
285 This corresponds to the command-line option "--insecure". If
286 true, make the password widget friendlier but less secure, by
287 echoing asterisks for each character.
288 DIALOG_VARS.item_help
290 This corresponds to the command-line option "--item-help". If
291 true, interpret the tags data for checklist, radiolist and menu
292 boxes adding a column whose text is displayed in the bottom line
293 of the screen, for the currently selected item.
294 DIALOG_VARS.keep_window
296 This corresponds to the command-line option "--keep-window". If
297 true, do not remove/repaint the window on exit. This is useful
298 for keeping the window contents visible when several widgets are
299 run in the same process. Note that curses will clear the screen
300 when starting a new process.
301 DIALOG_VARS.max_input
303 This corresponds to the command-line option "--max-input size".
304 Limit input strings to the given size. If not specified, the
305 limit is 2048.
306 DIALOG_VARS.no_label
308 This corresponds to the command-line option "--no-label string".
309 The given string overrides the label used for "No" buttons.
310 DIALOG_VARS.nocancel
312 This corresponds to the command-line option "--no-cancel". If
313 true, suppress the "Cancel" button in checklist, inputbox and
314 menu box modes. A script can still test if the user pressed the
315 ESC key to cancel to quit.
316 DIALOG_VARS.nocollapse
318 This corresponds to the command-line option "--no-collapse".
319 Normally dialog converts tabs to spaces and reduces multiple
320 spaces to a single space for text which is displayed in a mes‐
321 sage boxes, etc. It true, that feature is disabled. Note that
322 dialog will still wrap text, subject to the --cr-wrap option.
323 DIALOG_VARS.ok_label
325 This corresponds to the command-line option "--ok-label string".
326 The given string overrides the label used for "OK" buttons.
327 DIALOG_VARS.print_siz
329 This corresponds to the command-line option "--print-size". If
330 true, each widget prints its size to dialog's output when it is
331 invoked.
332 DIALOG_VARS.separate_output
334 This corresponds to the command-line option "--separate-output".
335 If true, checklist widgets output result one line at a time,
336 with no quoting. This facilitates parsing by another program.
337 DIALOG_VARS.single_quoted
339 This corresponds to the command-line option "--single-quoted".
340 If true, Use single-quoting as needed (and no quotes if
341 unneeded) for the output of checklist's as well as the item-help
342 text. If this option is not set, dialog uses double quotes
343 around each item. That requires occasional use of backslashes
344 to make the output useful in shell scripts.
345 DIALOG_VARS.size_err
347 This corresponds to the command-line option "--size-err". If
348 true, check the resulting size of a dialog box before trying to
349 use it, printing the resulting size if it is larger than the
350 screen. (This option is obsolete, since all new-window calls
351 are checked).
352 DIALOG_VARS.sleep_secs
354 This corresponds to the command-line option "--sleep secs".
355 This option is implemented in the main program, not the library.
356 If nonzero, this is the number of seconds after to delay after
357 processing a dialog box.
358 DIALOG_VARS.tab_correct
360 This corresponds to the command-line option "--tab-correct". If
361 true, convert each tab character of the text to one or more spa‐
362 ces. Otherwise, tabs are rendered according to the curses
363 library's interpretation.
364 DIALOG_VARS.timeout_secs
366 This corresponds to the command-line option "--timeout secs".
367 If nonzero, timeout input requests (exit with error code) if no
368 user response within the given number of seconds.
369 DIALOG_VARS.title
371 This corresponds to the command-line option "--title title".
372 Specifies a title string to be displayed at the top of the dia‐
373 log box.
374 DIALOG_VARS.trim_whitespace
376 This corresponds to the command-line option "--trim". If true,
377 eliminate leading blanks, trim literal newlines and repeated
378 blanks from message text.
379 DIALOG_VARS.visit_items
381 This corresponds to the command-line option "--visit-items".
382 Modify the tab-traversal of checklist, radiobox, menubox and
383 inputmenu to include the list of items as one of the states.
384 This is useful as a visual aid, i.e., the cursor position helps
385 some users.
386 DIALOG_VARS.yes_label
388 This corresponds to the command-line option "--yes-label
389 string". The given string overrides the label used for "Yes"
390 buttons.
391 WIDGETS
393 Functions that implement major functionality for the command-line dia‐
394 log program, e.g., widgets, have names beginning "dialog_".
395 All dialog boxes have at least three parameters:
397 title
399 the caption for the box, shown on its top border.
400 height
402 the height of the dialog box.
403 width
405 the width of the dialog box.
406 Other parameters depend on the box type.
408 dialog_calendar
410 implements the "--calendar" option.
411 title is the title on the top of the widget.
413 subtitle
415 is the prompt text shown within the widget.
416 height is the height excluding the fixed-height calendar grid.
418 width is the overall width of the box, which is adjusted up to
420 the calendar grid's minimum width if needed.
421 day is the initial day of the week shown, counting zero as
423 Sunday. If the value is negative, the current day of the
424 week is used.
425 month is the initial month of the year shown, counting one as
427 January. If the value is negative, the current month of
428 the year is used.
429 year is the initial year shown. If the value is negative, the
431 current year is used.
432 dialog_checklist
434 implements the "--checklist" and "--radiolist" options depending
435 on the flag parameter.
436 title is the title on the top of the widget.
438 cprompt
440 is the prompt text shown within the widget.
441 height is the desired height of the box. If zero, the height is
443 adjusted to use the available screen size.
444 width is the desired width of the box. If zero, the height is
446 adjusted to use the available screen size.
447 list_height
449 is the minimum height to reserve for displaying the list.
450 If zero, it is computed based on the given height and
451 width.
452 item_no
454 is the number of rows in items.
455 items is an array of strings which is viewed either as a list
457 of rows
458 tag item status
459 or
461 tag item status help
462 depending on whether dialog_vars.item_help is set.
464 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for
466 radiolists.
467 dialog_dselect
469 implements the "--dselect" option.
470 title is the title on the top of the widget.
472 path is the preselected value to show in the input-box, which
474 is used also to set the directory- and file-windows.
475 height is the height excluding the minimum needed to show the
477 dialog box framework. If zero, the height is based on
478 the screen size.
479 width is the desired width of the box. If zero, the height is
481 based on the screen size.
482 dialog_editbox
484 implements the "--editbox" option.
485 title is the title on the top of the widget.
487 file is the name of the file from which to read.
489 height is the desired height of the box. If zero, the height is
491 adjusted to use the available screen size.
492 width is the desired width of the box. If zero, the height is
494 adjusted to use the available screen size.
495 dialog_form
497 implements the "--form" option.
498 title is the title on the top of the widget.
500 cprompt
502 is the prompt text shown within the widget.
503 height is the desired height of the box. If zero, the height is
505 adjusted to use the available screen size.
506 width is the desired width of the box. If zero, the height is
508 adjusted to use the available screen size.
509 form_height
511 is the minimum height to reserve for displaying the list.
512 If zero, it is computed based on the given height and
513 width.
514 item_no
516 is the number of rows in items.
517 items is an array of strings which is viewed either as a list
519 of rows
520 Name NameY NameX Text TextY TextX FLen ILen
521 or
523 Name NameY NameX Text TextY TextX FLen ILen Help
524 depending on whether dialog_vars.item_help is set.
526 dialog_fselect
528 implements the "--fselect" option.
529 title is the title on the top of the widget.
531 path is the preselected value to show in the input-box, which
533 is used also to set the directory- and file-windows.
534 height is the height excluding the minimum needed to show the
536 dialog box framework. If zero, the height is based on
537 the screen size.
538 width is the desired width of the box. If zero, the height is
540 based on the screen size.
541 dialog_gauge
543 implements the "--gauge" option.
544 title is the title on the top of the widget.
546 cprompt
548 is the prompt text shown within the widget.
549 height is the desired height of the box. If zero, the height is
551 based on the screen size.
552 width is the desired width of the box. If zero, the height is
554 based on the screen size.
555 percent
557 is the percentage to show in the progress bar.
558 dialog_inputbox
560 implements the "--inputbox" or "--password" option, depending on
561 the value of password.
562 title is the title on the top of the widget.
564 cprompt
566 is the prompt text shown within the widget.
567 height is the desired height of the box. If zero, the height is
569 based on the screen size.
570 width is the desired width of the box. If zero, the height is
572 based on the screen size.
573 init is the initial value of the input box, whose length is
575 taken into account when auto-sizing the width of the dia‐
576 log box.
577 password
579 if true, causes typed input to be echoed as asterisks.
580 dialog_menu
582 implements the "--menu" or "--inputmenu" option depending on
583 whether dialog_vars.input_menu is set.
584 title is the title on the top of the widget.
586 cprompt
588 is the prompt text shown within the widget.
589 height is the desired height of the box. If zero, the height is
591 based on the screen size.
592 width is the desired width of the box. If zero, the height is
594 based on the screen size.
595 menu_height
597 is the minimum height to reserve for displaying the list.
598 If zero, it is computed based on the given height and
599 width.
600 item_no
602 is the number of rows in items.
603 items is an array of strings which is viewed either as a list
605 of rows
606 tag item
607 or
609 tag item help
610 depending on whether dialog_vars.item_help is set.
612 dialog_mixedform
614 implements the "--mixedform" option.
615 title is the title on the top of the widget.
617 cprompt
619 is the prompt text shown within the widget.
620 height is the desired height of the box. If zero, the height is
622 adjusted to use the available screen size.
623 width is the desired width of the box. If zero, the height is
625 adjusted to use the available screen size.
626 form_height
628 is the minimum height to reserve for displaying the list.
629 If zero, it is computed based on the given height and
630 width.
631 item_no
633 is the number of rows in items.
634 items is an array of strings which is viewed either as a list
636 of rows
637 Name NameY NameX Text TextY TextX FLen ILen Ityp
638 or
640 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
641 depending on whether dialog_vars.item_help is set.
643 dialog_mixedgauge
645 implements the "--mixedgauge" option
646 title is the title on the top of the widget.
648 cprompt
650 is the caption text shown within the widget.
651 height is the desired height of the box. If zero, the height is
653 based on the screen size.
654 width is the desired width of the box. If zero, the height is
656 based on the screen size.
657 percent
659 is the percentage to show in the progress bar.
660 item_no
662 is the number of rows in items.
663 items is an array of strings which is viewed as a list of tag
665 and item values. The tag values are listed, one per row,
666 in the list at the top of the widget.
667 The item values are decoded: digits 0-9 are the following
669 strings
670 0 Succeeded
672 1 Failed
674 2 Passed
676 3 Completed
678 4 Checked
680 5 Done
682 6 Skipped
684 7 In Progress
686 8 (blank)
688 9 N/A
690 A string with a leading "-" character is centered, marked
692 with "%". For example, "-75" is displayed as "75%".
693 Other strings are displayed as is.
694 dialog_msgbox
696 implements the "--msgbox" or "--infobox" option depending on
697 whether pauseopt is set.
698 title is the title on the top of the widget.
700 cprompt
702 is the prompt text shown within the widget.
703 height is the desired height of the box. If zero, the height is
705 based on the screen size.
706 width is the desired width of the box. If zero, the height is
708 based on the screen size.
709 pauseopt
711 if true, an "OK" button will be shown, and the dialog
712 will wait for it to complete. With an "OK" button, it is
713 denoted a "msgbox", without an "OK" button, it is denoted
714 an "infobox".
715 dialog_pause
717 implements the "--pause" option.
718 title is the title on the top of the widget.
720 height is the desired height of the box. If zero, the height is
722 based on the screen size.
723 width is the desired width of the box. If zero, the height is
725 based on the screen size.
726 seconds
728 is the timeout to use for the progress bar.
729 dialog_progressbox
731 implements the "--progressbox" option.
732 title is the title on the top of the widget.
734 cprompt
736 is the prompt text shown within the widget. If empty or
737 null, no prompt is shown.
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 dialog_tailbox
746 implements the "--tailbox" or "--tailboxbg" option depending on
747 whether bg_task is set.
748 title is the title on the top of the widget.
750 file is the name of the file to display in the dialog.
752 height is the desired height of the box. If zero, the height is
754 based on the screen size.
755 width is the desired width of the box. If zero, the height is
757 based on the screen size.
758 bg_task
760 if true, the window is added to the callback list in dia‐
761 log_state, and the application will poll for the window
762 to be updated. Otherwise an "OK" button is added to the
763 window, and it will be closed when the button is acti‐
764 vated.
765 dialog_textbox
767 implements the "--textbox" option.
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 dialog_timebox
780 implements the "--timebox" option.
781 title is the title on the top of the widget.
783 subtitle
785 is the prompt text shown within the widget.
786 height is the desired height of the box. If zero, the height is
788 based on the screen size.
789 width is the desired width of the box. If zero, the height is
791 based on the screen size.
792 hour is the initial hour shown. If the value is negative, the
794 current hour is used.
795 minute is the initial minute shown. If the value is negative,
797 the current minute is used.
798 second is the initial second shown. If the value is negative,
800 the current second is used.
801 dialog_yesno
803 implements the "--yesno" option.
804 title is the title on the top of the widget.
806 cprompt
808 is the prompt text shown within the widget.
809 height is the desired height of the box. If zero, the height is
811 based on the screen size.
812 width is the desired width of the box. If zero, the height is
814 based on the screen size.
815 UTILITY FUNCTIONS
817 Most functions that implement lower-level functionality for the com‐
818 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
819 ing to longstanding usage, the functions that initialize the display
820 and end it are named init_dialog and end_dialog.
821 The only non-widget function whose name begins with "dialog_" is dia‐
823 log_version, which returns the version number of the library as a
824 string.
825 Here is a brief summary of the utility functions and their parameters:
827 dlg_add_callback
829 Add a callback, used to allow polling input from multiple tailbox
830 widgets.
831 DIALOG_CALLBACK *p
833 contains the callback information.
834 dlg_add_quoted
836 Add a quoted string to the result buffer (see dlg_add_result).
837 char * string
839 is the string to add.
840 dlg_add_result
842 Add a quoted string to the result buffer dialog_vars.input_result.
843 char * string
845 is the string to add.
846 dlg_asciibox
848 returns its parameter transformed to the corresponding "+" or "-",
849 etc. for the line-drawing characters used in dialog. If the
850 parameter is not a line-drawing or other special character such as
851 ACS_DARROW, it returns 0.
852 dlg_attr_clear
854 Set window to the given attribute.
855 WINDOW * win
857 is the window to update.
858 int height
860 is the number of rows to update.
861 int width
863 is the number of columns to update.
864 chtype attr
866 is the attribute, e.g., A_BOLD.
867 dlg_auto_size
869 Automatically size the window used for a widget. If the given
870 height or width are zero, justify the prompt text and return the
871 actual limits.
872 const char * title
874 is the title string to display at the top of the widget.
875 const char * prompt
877 is the message text which will be displayed in the widget,
878 used here to determine how large the widget should be.
879 int * height
881 is the nominal height.
882 int * width
884 is the nominal width.
885 int boxlines
887 is the number of lines to reserve in the vertical direction.
888 int mincols
890 is the minimum number of columns to use.
891 dlg_auto_sizefile
893 Like dlg_auto_size, but use a file contents to decide how large
894 the widget should be.
895 const char * title
897 is the title string to display at the top of the widget.
898 const char * file
900 is the name of the file.
901 int * height
903 is the nominal height. If it is -1, use the screen's height
904 after subtracting dialog_vars.begin_y if dia‐
905 log_vars.begin_set is true.
906 int *width
908 is the nominal width. If it is -1, use the screen's width
909 after subtracting dialog_vars.begin_x if dia‐
910 log_vars.begin_set is true.
911 int boxlines
913 is the number of lines to reserve on the screen for drawing
914 boxes.
915 int mincols
917 is the number of columns to reserve on the screen for drawing
918 boxes.
919 dlg_beeping
921 If dialog_vars.beep_signal is nonzero, this calls beep once and
922 sets dialog_vars.beep_signal to zero.
923 dlg_boxchar
925 returns its parameter transformed as follows:
926 - if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is
928 set.
929 - if dialog_vars.ascii_lines is set, returns the corresponding
931 "+" or "-", etc. for the line-drawing characters used in dia‐
932 log.
933 - otherwise, if dialog_vars.no_lines is set, returns a space for
935 the line-drawing characters.
936 - if the parameter is not a line-drawing or other special charac‐
938 ter such as ACS_DARROW, it returns the parameter unchanged.
939 dlg_box_x_ordinate
941 returns a suitable x-ordinate (column) for a new widget. If dia‐
942 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center
943 the widget on the screen (using the width parameter).
944 int width
946 is the width of the widget.
947 dlg_box_y_ordinate
949 returns a suitable y-ordinate (row) for a new widget. If dia‐
950 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center
951 the widget on the screen (using the height parameter).
952 int height
954 is the height of the widget.
955 dlg_button_count
957 Count the buttons in the list.
958 const char ** labels
960 is a list of (pointers to) button labels terminated by a null
961 pointer.
962 dlg_button_layout
964 Make sure there is enough space for the buttons by computing the
965 width required for their labels, adding margins and limiting based
966 on the screen size.
967 const char ** labels
969 is a list of (pointers to) button labels terminated by a null
970 pointer.
971 int * limit
973 the function sets the referenced limit to the width required
974 for the widest label (limited by the screen size) if that is
975 wider than the passed-in limit.
976 dlg_button_sizes
978 Compute the size of the button array in columns.
979 const char ** labels
981 is a list of (pointers to) button labels terminated by a null
982 pointer.
983 int vertical
985 is true if the buttons are arranged in a column rather than a
986 row.
987 int * longest
989 Return the total number of columns in the referenced loca‐
990 tion.
991 int * length
993 Return the longest button's columns in the referenced loca‐
994 tion.
995 dlg_button_x_step
997 Compute the step-size needed between elements of the button array.
998 const char ** labels
1000 is a list of (pointers to) button labels terminated by a null
1001 pointer.
1002 int limit
1004 is the maximum number of columns to allow for the buttons.
1005 int * gap
1007 store the nominal gap between buttons in the referenced loca‐
1008 tion. This is constrained to be at least one.
1009 int * margin
1011 store the left+right total margins (for the list of buttons)
1012 in the referenced location.
1013 int * step
1015 store the step-size in the referenced location.
1016 dlg_button_to_char
1018 Find the first uppercase character in the label, which we may use
1019 for an abbreviation. If the label is empty, return -1. If no
1020 uppercase character is found, return 0. Otherwise return the
1021 uppercase character.
1022 const char * label
1024 is the label to test.
1025 dlg_calc_list_width
1027 Calculate the minimum width for the list, assuming none of the
1028 items are truncated.
1029 int item_no
1031 is the number of items.
1032 DIALOG_LISTITEM * items
1034 contains a name and text field, e.g., for checklists or
1035 radiobox lists. The function returns the sum of the widest
1036 columns needed for of each of these fields.
1037 dlg_calc_listh
1039 Calculate new height and list_height values.
1040 int * height
1042 on input, is the height without adding the list-height. On
1043 return, this contains the total list-height and is the actual
1044 widget's height.
1045 int * list_height
1047 on input, is the requested list-height. On return, this con‐
1048 tains the number of rows available for displaying the list
1049 after taking into account the screen size and the dia‐
1050 log_vars.begin_set and dialog_vars.begin_y variables.
1051 int item_no
1053 is the number of items in the list.
1054 dlg_calc_listw
1056 This function is obsolete, provided for library-compatibility. It
1057 is replaced by dlg_calc_list_width.
1058 int item_no
1060 is the number of items.
1061 char ** items
1063 is a list of character pointers.
1064 int group
1066 is the number of items in each group, e.g., the second array
1067 index.
1068 dlg_char_to_button
1070 Given a list of button labels, and a character which may be the
1071 abbreviation for one, find it, if it exists. An abbreviation will
1072 be the first character which happens to be capitalized in the
1073 label. If the character is found, return its index within the
1074 list of labels. Otherwise, return DLG_EXIT_UNKNOWN.
1075 int ch
1077 is the character to find.
1078 const char ** labels
1080 is a list of (pointers to) button labels terminated by a null
1081 pointer.
1082 dlg_checklist
1084 This entrypoint provides the --checklist or --radiolist function‐
1085 ality without the limitations of dialog's command-line syntax
1086 (compare to dialog_checklist).
1087 const char * title
1089 is the title string to display at the top of the widget.
1090 const char * cprompt
1092 is the prompt text shown within the widget.
1093 int height
1095 is the desired height of the box. If zero, the height is
1096 adjusted to use the available screen size.
1097 int width
1099 is the desired width of the box. If zero, the height is
1100 adjusted to use the available screen size.
1101 int list_height
1103 is the minimum height to reserve for displaying the list. If
1104 zero, it is computed based on the given height and width.
1105 int item_no
1107 is the number of items.
1108 DIALOG_LISTITEM * items
1110 This is a list of the items to display in the checklist.
1111 const char * states
1113 This is a list of characters to display for the given states.
1114 Normally a checklist provides true (1) and false (0) values,
1115 which the widget displays as "*" and space, respectively. An
1116 application may set this parameter to an arbitrary null-ter‐
1117 minated string. The widget determines the number of states
1118 from the length of this string, and will cycle through the
1119 corresponding display characters as the user presses the
1120 space-bar.
1121 int flag
1123 This is should be one of FLAG_CHECK or FLAG_RADIO, depending
1124 on whether the widget should act as a checklist or radiobox.
1125 int * current_item
1127 The widget sets the referenced location to the index of the
1128 current display item (cursor) when it returns.
1129 dlg_clear
1131 Set window to the default dialog screen attribute. This is set in
1132 the rc-file with screen_color.
1133 dlg_clr_result
1135 Free storage used for the result buffer (dia‐
1136 log_vars.input_result).
1137 dlg_color_count
1139 Return the number of colors that can be configured in dialog.
1140 dlg_color_setup
1142 Initialize the color pairs used in dialog.
1143 dlg_count_columns
1145 Returns the number of columns used for a string. This is not nec‐
1146 essarily the number of bytes in a string.
1147 const char * string
1149 is the string to measure.
1150 dlg_count_wchars
1152 Returns the number of wide-characters in the string.
1153 const char * string
1155 is the string to measure.
1156 dlg_create_rc
1158 Create a configuration file, i.e., write internal tables to a file
1159 which can be read back by dialog as an rc-file.
1160 const char * filename
1162 is the name of the file to write to.
1163 dlg_ctl_size
1165 If dialog_vars.size_err is true, check if the given window size is
1166 too large to fit on the screen. If so, exit with an error report‐
1167 ing the size of the window.
1168 int height
1170 is the window's height
1171 int width
1173 is the window's width
1174 dlg_default_formitem
1176 If dialog_vars.default_item is not null, find that name by match‐
1177 ing the name field in the list of form items. If found, return
1178 the index of that item in the list. Otherwise, return zero.
1179 DIALOG_FORMITEM * items
1181 is the list of items to search. It is terminated by an entry
1182 with a null name field.
1183 dlg_default_item
1185 This function is obsolete, provided for library-compatibility. It
1186 is replaced by dlg_default_formitem and dlg_default_listitem.
1187 char ** items
1189 is the list of items to search.
1190 int llen
1192 is the number of items in each group, e.g., the second array
1193 index.
1194 dlg_defaultno_button
1196 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not,
1197 find the button-index for the "Cancel" button. Otherwise, return
1198 the index for "OK" (always zero).
1199 dlg_del_window
1201 Remove a window, repainting everything else.
1202 WINDOW * win
1204 is the window to remove.
1205 dlg_does_output
1207 This is called each time a widget is invoked which may do output.
1208 It increments dialog_state.output_count, so the output function in
1209 dialog can test this and add a separator.
1210 dlg_draw_arrows
1212 Draw up/down arrows on a window, e.g., for scrollable lists. It
1213 calls dlg_draw_arrows2 using the menubox_color and menubox_bor‐
1214 der_color attributes.
1215 WINDOW * dialog
1217 is the window on which to draw an arrow.
1218 int top_arrow
1220 is true if an up-arrow should be drawn at the top of the win‐
1221 dow.
1222 int bottom_arrow
1224 is true if an down-arrow should be drawn at the bottom of the
1225 window.
1226 int x
1228 is the zero-based column within the window on which to draw
1229 arrows.
1230 int top
1232 is the zero-based row within the window on which to draw up-
1233 arrows as well as a horizontal line to show the window's top.
1234 int bottom
1236 is the zero-based row within the window on which to draw
1237 down-arrows as well as a horizontal line to show the window's
1238 bottom.
1239 dlg_draw_arrows2
1241 Draw up/down arrows on a window, e.g., for scrollable lists.
1242 WINDOW * dialog
1244 is the window on which to draw an arrow.
1245 int top_arrow
1247 is true if an up-arrow should be drawn at the top of the win‐
1248 dow.
1249 int bottom_arrow
1251 is true if an down-arrow should be drawn at the bottom of the
1252 window.
1253 int x
1255 is the zero-based column within the window on which to draw
1256 arrows.
1257 int top
1259 is the zero-based row within the window on which to draw up-
1260 arrows as well as a horizontal line to show the window's top.
1261 int bottom
1263 is the zero-based row within the window on which to draw
1264 down-arrows as well as a horizontal line to show the window's
1265 bottom.
1266 chtype attr
1268 is the window's background attribute.
1269 chtype borderattr
1271 is the window's border attribute.
1272 dlg_draw_bottom_box
1274 Draw a partial box at the bottom of a window, e.g., to surround a
1275 row of buttons. It is designed to merge with an existing box
1276 around the whole window, so it uses tee-elements rather than cor‐
1277 ner-elements on the top corners of this box.
1278 WINDOW * win
1280 is the window to update.
1281 dlg_draw_box
1283 Draw a rectangular box with line drawing characters.
1284 WINDOW * win
1286 is the window to update.
1287 int y
1289 is the top row of the box.
1290 int x
1292 is the left column of the box.
1293 int height
1295 is the height of the box.
1296 int width
1298 is the width of the box.
1299 chtype boxchar
1301 is used to color the right/lower edges. It also is fill-
1302 color used for the box contents.
1303 chtype borderchar
1305 is used to color the upper/left edges.
1306 dlg_draw_buttons
1308 Print a list of buttons at the given position.
1309 WINDOW * win
1311 is the window to update.
1312 int y
1314 is the starting row.
1315 int x
1317 is the starting column.
1318 const char ** labels
1320 is a list of (pointers to) button labels terminated by a null
1321 pointer.
1322 int selected
1324 is the index within the list of the selected button.
1325 int vertical
1327 is true if the buttons are arranged in a column rather than a
1328 row.
1329 int limit
1331 is the number of columns (or rows if vertical) allowed for
1332 the display.
1333 dlg_draw_shadow
1335 Draw shadows along the right and bottom edge of a window to give
1336 it a 3-dimensional look. (The height, etc., may not be the same
1337 as the window's actual values).
1338 WINDOW * win
1340 is the window to update.
1341 int height
1343 is the height of the window.
1344 int width
1346 is the width of the window.
1347 int y
1349 is the top row of the window.
1350 int x
1352 is the left column of the window.
1353 dlg_draw_title
1355 Draw a title centered at the top of the window.
1356 WINDOW * win
1358 is the window to update.
1359 const char * title
1361 is the title string to display at the top of the widget.
1362 dlg_dump_keys
1364 Write all user-defined key-bindings to the given stream, e.g., as
1365 part of dlg_create_rc.
1366 FILE * fp
1368 is the stream on which to write the bindings.
1369 dlg_edit_offset
1371 Given the character-offset in the string, returns the display-off‐
1372 set where dialog should position the cursor. In this context,
1373 "characters" may be multicolumn, since the string can be a multi‐
1374 byte character string.
1375 char * string
1377 is the string to analyze
1378 int offset
1380 is the character-offset
1381 int x_last
1383 is a limit on the column positions that can be used, e.g.,
1384 the window's size.
1385 dlg_edit_string
1387 Updates the string and character-offset, given various editing
1388 characters or literal characters which are inserted at the charac‐
1389 ter-offset. Returns true if an editing change was made (and the
1390 display should be updated), and false if the key was something
1391 like KEY_ENTER, which is a non-editing action outside this func‐
1392 tion.
1393 char * string
1395 is the (multibyte) string to update
1396 int * offset
1398 is the character-offset
1399 int key
1401 is the editing key
1402 int fkey
1404 is true if the editing key is a function-key
1405 bool force
1407 is used in a special loop case by calling code to force the
1408 return value of this function when a function-key code 0 is
1409 passed in.
1410 dlg_exit
1412 Given an internal exit code, check if the corresponding environ‐
1413 ment variable is set. If so, remap the exit code to match the
1414 environment variable. Finally call exit with the resulting exit
1415 code.
1416 int code
1418 is the internal exit code, e.g., DLG_EXIT_OK, which may be
1419 remapped.
1420 The dialog program uses this function to allow shell scripts to
1422 remap the exit codes so they can distinguish ESC from ERROR.
1423 dlg_exit_buttoncode
1425 Map the given button index for dlg_exit_label into dialog's exit-
1426 code.
1427 int button
1429 is the button index
1430 dlg_exit_label
1432 Return a list of button labels. If dialog_var.extra_button is
1433 true, return the result of dlg_ok_labels. Otherwise, return a
1434 list with the "Exit" label and (if dialog_vars.help_button is set)
1435 the "Help" button as well.
1436 dlg_exiterr
1438 Quit program killing all tailboxbg widgets.
1439 const char * fmt
1441 is the format of the printf-like message to write.
1442 are the variables to apply to the fmt format.
1444 dlg_find_index
1446 Given the character-offset to find in the list, return the corre‐
1447 sponding array index.
1448 const int *list
1450 contains a list of character-offsets, i.e., indices into a
1451 string that denote the beginning of multibyte characters.
1452 int limit
1454 is the last index into list to search.
1455 int to_find
1457 is the character-offset to find.
1458 dlg_flush_getc
1460 Cancel the local data saved by dlg_last_getc.
1461 dlg_editbox
1463 This entrypoint provides the --editbox functionality without the
1464 limitations of dialog's command-line syntax (compare to dia‐
1465 log_editbox).
1466 const char * title
1468 is the title string to display at the top of the widget.
1469 char *** list
1471 is a pointer to an array of char * pointers. The array is
1472 allocated by the caller, and so are the strings to which it
1473 points. The dlg_editbox function may reallocate the array
1474 and the strings.
1475 int * rows
1477 points to the nominal length of list. The referenced value
1478 is updated iflist is reallocated.
1479 int height
1481 is the desired height of the box. If zero, the height is
1482 adjusted to use the available screen size.
1483 int width
1485 is the desired width of the box. If zero, the height is
1486 adjusted to use the available screen size.
1487 dlg_form
1489 This entrypoint provides the --form functionality without the lim‐
1490 itations of dialog's command-line syntax (compare to dialog_form).
1491 const char * title
1493 is the title string to display at the top of the widget.
1494 const char * cprompt
1496 is the prompt text shown within the widget.
1497 int height
1499 is the desired height of the box. If zero, the height is
1500 adjusted to use the available screen size.
1501 int width
1503 is the desired width of the box. If zero, the height is
1504 adjusted to use the available screen size.
1505 int form_height
1507 is the minimum height to reserve for displaying the list. If
1508 zero, it is computed based on the given height and width.
1509 int item_no
1511 is the number of items.
1512 DIALOG_FORMITEM * items
1514 This is a list of the items to display in the form.
1515 int * current_item
1517 The widget sets the referenced location to the index of the
1518 current display item (cursor) when it returns.
1519 dlg_free_formitems
1521 Free memory owned by a list of DIALOG_FORMITEM's.
1522 DIALOG_FORMITEM * items
1524 is the list to free.
1525 dlg_getc
1527 Read a character from the given window. Handle repainting here
1528 (to simplify things in the calling application). Also, if input-
1529 callback(s) are set up, poll the corresponding files and handle
1530 the updates, e.g., for displaying a tailbox. Returns the key-
1531 code.
1532 WINDOW * win
1534 is the window within which to read.
1535 int * fkey
1537 as a side-effect, set this to true if the key-code is really
1538 a function-key.
1539 dlg_getc_callbacks
1541 passes the given key-code ch to the current window that has estab‐
1542 lished a callback. If the callback returns zero, remove it and
1543 try the next window. If no more callbacks remain, return. If any
1544 callbacks were found, return true, otherwise false.
1545 int ch
1547 is the key-code
1548 int fkey
1550 is true if the key is a function-key
1551 int * result
1553 is used to pass an exit-code to the caller, which should pass
1554 that via dlg_exit.
1555 dlg_index_columns
1557 Build a list of the display-columns for the given multibyte
1558 string's characters.
1559 const char * string
1561 is the string to analyze
1562 dlg_index_wchars
1564 Build an index of the wide-characters in the string, so the caller
1565 can easily tell which byte-offset begins a given wide-character.
1566 const char * string
1568 is the string to analyze
1569 dlg_item_help
1571 Draw the string for the dialog_vars.item_help feature.
1572 char * txt
1574 is the help-message
1575 dlg_killall_bg
1577 If dialog has callbacks active, purge the list of all that are not
1578 marked to keep in the background. If any remain, run those in a
1579 background process.
1580 int * retval
1582 stores the exit-code to pass back to the caller.
1583 dlg_last_getc
1585 returns the most recent character that was read via dlg_getc.
1586 dlg_limit_columns
1588 Given a column limit, count the number of wide characters that can
1589 fit into that limit. The offset is used to skip over a leading
1590 character that was already written.
1591 const char * string
1593 is the string to analyze
1594 int limit
1596 is the column limit
1597 int offset
1599 is the starting offset from which analysis should continue
1600 dlg_lookup_key
1602 Check for a key-binding. If there is no binding associated with
1603 the widget, it simply returns the given curses-key. Otherwise, it
1604 returns the result of the binding
1605 WINDOW * win
1607 is the window on which the binding is checked
1608 int curses_key
1610 is the curses key-code
1611 int * dialog_key
1613 is the corresponding dialog internal code (see DLG_KEYS_ENUM
1614 in dlg_key.h).
1615 dlg_max_input
1617 Limit the parameter according to dialog_vars.max_input
1618 int max_len
1620 is the value to limit
1621 dlg_match_char
1623 Match a given character against the beginning of the string,
1624 ignoring case of the given character. The matching string must
1625 begin with an uppercase character.
1626 int ch
1628 is the character to check
1629 const char * string
1631 is the string to search
1632 dlg_menu
1634 This entrypoint provides the --menu functionality without the lim‐
1635 itations of dialog's command-line syntax (compare to dialog_menu).
1636 const char * title
1638 is the title string to display at the top of the widget.
1639 const char * cprompt
1641 is the prompt text shown within the widget.
1642 int height
1644 is the desired height of the box. If zero, the height is
1645 adjusted to use the available screen size.
1646 int width
1648 is the desired width of the box. If zero, the height is
1649 adjusted to use the available screen size.
1650 int menu_height
1652 is the minimum height to reserve for displaying the list. If
1653 zero, it is computed based on the given height and width.
1654 int item_no
1656 is the number of items.
1657 DIALOG_LISTITEM * items
1659 This is a list of the items to display in the form.
1660 int * current_item
1662 The widget sets the referenced location to the index of the
1663 current display item (cursor) when it returns.
1664 DIALOG_INPUTMENU rename_menutext
1666 dlg_move_window
1668 Moves/resizes the given window to the given position and size.
1669 WINDOW *win
1671 is the window to move/resize.
1672 WINDOW *height
1674 is the height of the resized window.
1675 WINDOW *width
1677 is the width of the resized window.
1678 WINDOW *y
1680 y-ordinate to use for the repositioned window.
1681 WINDOW *x
1683 x-ordinate to use for the repositioned window.
1684 dlg_mouse_bigregion
1686 Retrieve the big-region under the pointer.
1687 int y
1689 is the row on which the mouse click occurred
1690 int x
1692 is the column on which the mouse click occurred
1693 dlg_mouse_free_regions
1695 Free the memory associated with mouse regions.
1696 dlg_mouse_mkbigregion
1698 Creates a region on which the mouse-clicks will return a specifed
1699 code.
1700 int y
1702 is the top-row of the region.
1703 int x
1705 is the left-column of the region.
1706 int height
1708 is the height of the region.
1709 int width
1711 is the width of the region.
1712 int code
1714 is a code used to make the region unique within a widget
1715 int step_x
1717 is used in modes 2 (columns) and 3 (cells) to determine the
1718 width of a column/cell.
1719 int step_y
1721 is currently unused
1722 int mode
1724 is used to determine how the mouse position is translated
1725 into a code (like a function-key):
1726 1 index by lines
1728 2 index by columns
1730 3 index by cells
1732 dlg_mouse_mkregion
1734 int y
1736 is the top-row of the region.
1737 int x
1739 is the left-column of the region.
1740 int height
1742 is the height of the region.
1743 int width
1745 is the width of the region.
1746 int code
1748 is a code used to make the region unique within a widget
1749 dlg_mouse_region
1751 Retrieve the frame under the mouse pointer
1752 int y
1754 is the row of the mouse-click
1755 int x
1757 is the column of the mouse-click
1758 dlg_mouse_setbase
1760 Sets a base for subsequent calls to dlg_mouse_mkregion, so they
1761 can make regions relative to the start of a given window.
1762 int x
1764 is the left-column for the base
1765 int y
1767 is the top-row for the base
1768 dlg_mouse_wgetch
1770 is a wrapper for dlg_getc which additionally maps mouse-clicks (if
1771 the curses library supports those) into extended function-keys
1772 which encode the position according to the mode in dlg_mouse_mkbi‐
1773 gregion. Returns the corresponding key-code.
1774 WINDOW * win
1776 is the window on which to perform the input
1777 int * fkey
1779 the referenced location is set to true if the key-code is an
1780 actual or extended (mouse) function-key.
1781 dlg_mouse_wgetch_nowait
1783 This is a non-blocking variant of dlg_mouse_wgetch.
1784 WINDOW * win
1786 is the window on which to perform the input
1787 int * fkey
1789 the referenced location is set to true if the key-code is an
1790 actual or extended (mouse) function-key.
1791 dlg_new_window
1793 Create a window, optionally with a shadow. The shadow is created
1794 if dialog_state.use_shadow is true.
1795 int height
1797 is the window's height
1798 int width
1800 is the window's width
1801 int y
1803 is the window's top-row
1804 int x
1806 is the window's left-column
1807 dlg_next_button
1809 Return the next index in the list of labels.
1810 const char ** labels
1812 is a list of (pointers to) button labels terminated by a null
1813 pointer.
1814 int button
1816 is the current button-index.
1817 dlg_next_ok_buttonindex
1819 Assuming that the caller is using dlg_ok_labels to list buttons,
1820 find the next index in the list of buttons.
1821 int current
1823 is the current index in the list of buttons
1824 int extra
1826 if negative, provides a way to enumerate extra active areas
1827 on the widget.
1828 dlg_ok_buttoncode
1830 Map the given button index for dlg_ok_labels into dialog's exit-
1831 code.
1832 int button
1834 is the button-index (which is not necessarily the same as the
1835 index in the list of labels).
1836 dlg_ok_label
1838 Returns a list with the "Ok" label, and if dialog_vars.help_button
1839 is true, the "Help" label as well.
1840 dlg_ok_labels
1842 Return a list of button labels for the OK/Cancel group of widgets.
1843 dlg_ordinate
1845 Decode the string as an integer, decrement if greater than zero to
1846 make a curses-ordinate from a dialog-ordinate.
1847 dlg_parse_bindkey
1849 Parse the parameters of the "bindkeys" configuration-file entry.
1850 This expects widget name which may be "*", followed by curses key
1851 definition and then dialog key definition.
1852 char * params
1854 is the parameter string to parse.
1855 dlg_parse_rc
1857 Parse the configuration file and set up variables.
1858 dlg_prev_button
1860 Return the previous index in the list of labels.
1861 const char ** labels
1863 is a list of (pointers to) button labels terminated by a null
1864 pointer.
1865 int button
1867 is the current button index
1868 dlg_print_line
1870 Print one line of the prompt in the window within the limits of
1871 the specified right margin. The line will end on a word boundary
1872 and a pointer to the start of the next line is returned, or a NULL
1873 pointer if the end of *prompt is reached.
1874 WINDOW *win
1876 is the window to update.
1877 chtype *attr
1879 holds the starting attributes, and is updated to reflect the
1880 final attributes applied to the string.
1881 const char *prompt
1883 is the string to print
1884 int lm
1886 is the left margin.
1887 int rm
1889 is the right margin
1890 int *x
1892 returns the ending x-ordinate.
1893 dlg_prev_ok_buttonindex
1895 Find the previous button index in the list from dlg_ok_labels.
1896 int current
1898 is the current index
1899 int extra
1901 if negative provides a way to enumerate extra active areas on
1902 the widget.
1903 dlg_print_autowrap
1905 Print a string of text in a window, automatically wrap around to
1906 the next line if the string is too long to fit on one line. Note
1907 that the string may contain embedded newlines.
1908 WINDOW * win
1910 is the window to update.
1911 const char * prompt
1913 is the string to print
1914 int height
1916 is the nominal height the wrapped string is limited to
1917 int width
1919 is the width that the wrapping should occur in
1920 dlg_print_size
1922 If dialog_vars.print_siz is true, print the given height/width
1923 (from a widget) to dialog_state.output, e.g., Size: height, width.
1924 int height
1926 is the window's height
1927 int width
1929 is the window's width
1930 dlg_print_text
1932 Print up to cols columns from text, optionally rendering dialog's
1933 escape sequences for attributes and color.
1934 WINDOW * win
1936 is the window to update.
1937 const char * txt
1939 is the string to print
1940 int col
1942 is the column limit
1943 chtype * attr
1945 holds the starting attributes, and is updated to reflect the
1946 final attributes applied to the string.
1947 dlg_put_backtitle
1949 Display the background title if dialog_vars.backtitle is non-null.
1950 The background title is shown at the top of the screen.
1951 dlg_register_buttons
1953 The widget developer should call this function after dlg_regis‐
1954 ter_window, for the list of button labels associated with the wid‐
1955 get. One may bind a key to a button, e.g., "OK" for DLGK_OK,
1956 WINDOW * win
1958 is the window with which to associate the buttons
1959 const char * name
1961 is the widget's binding name (usually the name of the wid‐
1962 get).
1963 const char ** buttons
1965 is the list of buttons
1966 dlg_register_window
1968 For a given named widget's window, associate a binding table.
1969 WINDOW * win
1971 is the window with which to associate the buttons
1972 const char * name
1974 is the widget's binding name (usually the name of the wid‐
1975 get).
1976 DLG_KEYS_BINDING * binding
1978 is the binding table
1979 dlg_remove_callback
1981 Remove a callback.
1982 DIALOG_CALLBACK * p
1984 contains the callback information.
1985 dlg_result_key
1987 Test a dialog internal keycode to see if it corresponds to one of
1988 the push buttons on the widget such as "OK". This is only useful
1989 if there are user-defined key bindings, since there are no built-
1990 in bindings that map directly to DLGK_OK, etc. Return true if a
1991 mapping was done.
1992 int dialog_key
1994 is the dialog key to test
1995 int fkey
1997 is true if this is a function key
1998 int * resultp
2000 store the result of the mapping in the referenced location.
2001 dlg_set_focus
2003 Set focus on the given window, making it display above other win‐
2004 dows on the screen.
2005 WINDOW * parent
2007 is the parent window (usually the top-level window of a wid‐
2008 get)
2009 WINDOW * win
2011 is the window on which to place focus (usually a subwindow of
2012 a widget)
2013 dlg_set_result
2015 Setup a fixed-buffer for the result in dialog_vars.input_result
2016 const char * string
2018 is the new contents for the result
2019 dlg_show_string
2021 Displays the string, shifted as necessary, to fit within the box
2022 and show the current character-offset.
2023 WINDOW * win
2025 is the window within which to display
2026 const char * string
2028 is the string to display
2029 int offset
2031 is the starting (character, not bytes) offset
2032 chtype attr
2034 is the window attribute to use for the string
2035 int y_base
2037 beginning row on screen
2038 int x_base
2040 beginning column on screen
2041 int x_last
2043 number of columns on screen
2044 bool hidden
2046 if true, do not echo input
2047 bool force
2049 if true, force repaint
2050 dlg_strclone
2052 duplicate the string, like strdup.
2053 const char * cprompt
2055 is the string to duplicate
2056 dlg_strcmp
2058 compare two strings, ignoring case.
2059 const char * a
2061 is one string
2062 const char * b
2064 is the other string
2065 dlg_sub_window
2067 create a subwindow, e.g., for an input area of a widget
2068 WINDOW * win
2070 is the parent window
2071 int height
2073 is the subwindow's height
2074 int width
2076 is the subwindow's width
2077 int y
2079 is the subwindow's top-row
2080 int x
2082 is the subwindow's left-column
2083 dlg_tab_correct_str
2085 If the dialog_vars.tab_correct is true, convert tabs to single
2086 spaces. Return the converted result. The caller is responsible
2087 for freeing the string.
2088 char * prompt
2090 is the string to convert
2091 dlg_trace
2093 If the parameter is non-null, opens a trace file with that name
2094 and stores the file pointer in dialog_state.trace.
2095 dlg_trace_chr
2097 If dialog_state.trace is set, translate the parameters into a
2098 printable representation, log it on a "chr" line.
2099 int ch
2101 is the nominal keycode value.
2102 int fkey
2104 is nonzero if the value is really a function key. Some of
2105 these may be values declared in the DLG_KEYS_ENUM.
2106 dlg_trace_win
2108 If dialog_state.trace is set, log a printable picture of the given
2109 window.
2110 dlg_trim_string
2112 Change embedded "\n" substrings to '\n' characters and tabs to
2113 single spaces. If there are no "\n"s, the function strips all
2114 extra spaces, for justification. If it has "\n"'s, the function
2115 preserves extra spaces. If dialog_vars.cr_wrap is set, the func‐
2116 tion preserves '\n's.
2117 char * src
2119 is the string to trim
2120 dlg_unregister_window
2122 Remove the bindings for a given window.
2123 WINDOW * win
2125 is the window from which to remove bindings
2126 dlg_yes_buttoncode
2128 Map the given button index for dlg_yes_labels into dialog's exit-
2129 code.
2130 int button
2132 is the button index
2133 dlg_yes_labels
2135 Return a list of buttons for Yes/No labels.
2136
2138 dialog (1).
2139
2141 Thomas E. Dickey
2142$Date: 2007/02/25 20:58:11 $ DIALOG(3)