1DIALOG(3) Library Functions Manual DIALOG(3)
2
6 dialog - widgets and utilities for the dialog program
7
9 cc [ flag ... ] file ... -ldialog [ library ... ]
10 or
11 cc `dialog-config --cflags` file ... `dialog-config --libs` ]
12 #include <dialog.h>
14 Dialog is a program that will let you to present a variety of questions
16 or display messages using dialog boxes from a shell script. It is
17 built from the dialog library, which consists of several widgets as
18 well as utility functions that are used by the widgets or the main pro‐
19 gram.
20
22 This manpage documents the features from <dialog.h> which are likely to
23 be important to developers using the widgets directly. Some hints are
24 also given for developing new widgets.
25
27 Exit codes (passed back to the main program for its use) are defined
28 with a "DLG_EXIT_ prefix. The defined constants can be mapped using
29 environment variables as described in dialog(1), e.g., DLG_EXIT_OK cor‐
30 responds to $DIALOG_OK.
31 Useful character constants which correspond to user input are named
33 with the "CHR_" prefix, e.g., CHR_BACKSPACE.
34 Colors and video attributes are categorized and associated with set‐
36 tings in the configuration file (see the discussion of $DIALOGRC in
37 dialog(1)). The DIALOG_ATR(n) macro is used for defining the refer‐
38 ences to the combined color and attribute table dlg_color_table[].
39 The dialog application passes its command-line parameters to the widget
41 functions. Some of those parameters are single values, but some of the
42 widgets accept data as an array of values. Those include check‐
43 list/radiobox, menubox and formbox. When the --item-help option is
44 given, an extra column of data is expected. The USE_ITEM_HELP(),
45 CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS macros are used to hide
46 this difference from the calling application.
47 Most of the other definitions found in <dialog.h> are used for conve‐
49 nience in building the library or main program. These include defini‐
50 tions based on the generated <dlg_config.h> header.
51
54 All of the global data for the dialog library is stored in a few struc‐
55 tures: DIALOG_STATE, DIALOG_VARS and DIALOG_COLORS. The corresponding
56 dialog_state, dialog_vars and dlg_color_table global variables should
57 be initialized to zeros, and then populated with the data to use. A
58 few of these must be nonzero for the corresponding widgets to function.
59 As as the case with function names, variables beginning with "dialog_"
60 are designed for use by the calling application while variables begin‐
61 ning with "dlg_" are intended for lower levels, e.g., by the dialog
62 library.
63 DIALOG_STATE.all_subwindows
65 This is a linked list of all subwindows created by the library.
66 The dlg_del_window function uses this to free storage for sub‐
67 windows when deleting a window.
68 DIALOG_STATE.all_windows
70 This is a linked list of all windows created by the library.
71 The dlg_del_window function uses this to locate windows which
72 may be redrawn after deleting a window.
73 DIALOG_STATE.aspect_ratio
75 This corresponds to the command-line option "--aspect-ratio".
76 The value gives the application some control over the box dimen‐
77 sions when using auto sizing (specifying 0 for height and
78 width). It represents width / height. The default is 9, which
79 means 9 characters wide to every 1 line high.
80 DIALOG_STATE.getc_callbacks
82 This is setup in ui_getc.c to record windows which must be
83 polled for input, e.g,. to handle the background tailbox widget.
84 One window is designated as the foreground or control window.
85 DIALOG_STATE.getc_redirect
87 If the control window for DIALOG_STATE.getc_callbacks is closed,
88 the list is transferred to this variable. Closing all windows
89 causes the application to exit.
90 DIALOG_STATE.no_mouse
92 This corresponds to the command-line option "--no-mouse". If
93 true, dialog will not initialize (and enable) the mouse in
94 init_dialog.
95 DIALOG_STATE.output
97 This is set in the dialog application to the stream on which the
98 application and library functions may write text results. Nor‐
99 mally that is the standard error, since the curses library
100 prefers to write its data to the standard output. Some scripts,
101 trading portability for convenience, prefer to write results to
102 the standard output, e.g., by using the "--stdout" option.
103 DIALOG_STATE.output_count
105 This is incremented by dlg_does_output, which is called by each
106 widget that writes text to the output. The dialog application
107 uses that to decide if it should also write a separator, i.e.,
108 DIALOG_STATE.separate_str, between calls to each widget.
109 DIALOG_STATE.pipe_input
111 This is set in init_dialog to a stream which can be used by the
112 gauge widget, which must be the application's standard input.
113 The dialog application calls init_dialog normally with input set
114 to the standard input, but optionally based on the "--input-fd"
115 option. Since the application cannot read from a pipe (standard
116 input) and at the same time read the curses input from the stan‐
117 dard input, it must allow for reopening the latter from either a
118 specific file descriptor, or directly from the terminal. The
119 adjusted pipe stream value is stored in this variable.
120 DIALOG_STATE.screen_initialized
122 This is set in init_dialog and reset in end_dialog. It is used
123 to check if curses has been initialized, and if the endwin func‐
124 tion must be called on exit.
125 DIALOG_STATE.screen_output
127 This is set in init_dialog to the output stream used by the
128 curses library. Normally that is the standard output, unless
129 that happens to not be a terminal (and if init_dialog can suc‐
130 cessfully open the terminal directly).
131 DIALOG_STATE.separate_str
133 This corresponds to the command-line option "--separate-widget".
134 The given string specifies a string that will separate the out‐
135 put on dialog's output from each widget. This is used to sim‐
136 plify parsing the result of a dialog with several widgets. If
137 this option is not given, the default separator string is a tab
138 character.
139 DIALOG_STATE.tab_len
141 This corresponds to the command-line option "--tab-len number".
142 Specify the number of spaces that a tab character occupies if
143 the "--tab-correct" option is given. The default is 8.
144 DIALOG_STATE.trace_output
146 This corresponds to the command-line option "--trace file". It
147 is the file pointer to which trace messages are written.
148 DIALOG_STATE.use_colors
150 This is set in init_dialog if the curses implementation supports
151 color.
152 DIALOG_STATE.use_scrollbar
154 This corresponds to the command-line option "--scrollbar". If
155 true, draw a scrollbar to make windows holding scrolled data
156 more readable.
157 DIALOG_STATE.use_shadow
159 This corresponds to the command-line option "--no-shadow". This
160 is set in init_dialog if the curses implementation supports
161 color. If true, suppress shadows that would be drawn to the
162 right and bottom of each dialog box.
163 DIALOG_STATE.visit_items
165 This corresponds to the command-line option "--visit-items".
166 The dialog application resets the dialog_vars data before accepting
168 options to invoke each widget. Most of the DIALOG_VARS members are set
169 directly from dialog's command-line options:
170 DIALOG_VARS.ascii_lines
172 This corresponds to the command-line option "--ascii-lines. It
173 causes line-drawing to be done with ASCII characters, e.g., "+"
174 and "-". See DIALOG_VARS.no_lines.
175 DIALOG_VARS.backtitle
177 This corresponds to the command-line option "--backtitle backti‐
178 tle". It specifies a backtitle string to be displayed on the
179 backdrop, at the top of the screen.
180 DIALOG_VARS.beep_after_signal
182 This corresponds to the command-line option "--beep-after". If
183 true, beep after a user has completed a widget by pressing one
184 of the buttons.
185 DIALOG_VARS.beep_signal
187 This corresponds to the command-line option "--beep". It is
188 obsolete.
189 DIALOG_VARS.begin_set
191 This is true if the command-line option "--begin y x" was used.
192 It specifies the position of the upper left corner of a dialog
193 box on the screen.
194 DIALOG_VARS.begin_x
196 This corresponds to the x value from the command-line option
197 "--begin y x" (second value).
198 DIALOG_VARS.begin_y
200 This corresponds to the y value from the command-line option
201 "--begin y x" (first value).
202 DIALOG_VARS.cancel_label
204 This corresponds to the command-line option "--cancel-label
205 string". The given string overrides the label used for "Cancel"
206 buttons.
207 DIALOG_VARS.cant_kill
209 This corresponds to the command-line option "--no-kill". If
210 true, this tells dialog to put the tailboxbg box in the back‐
211 ground, printing its process id to dialog's output. SIGHUP is
212 disabled for the background process.
213 DIALOG_VARS.colors
215 This corresponds to the command-line option "--colors". If
216 true, interpret embedded "\Z" sequences in the dialog text by
217 the following character, which tells dialog to set colors or
218 video attributes: 0 through 7 are the ANSI codes used in curses:
219 black, red, green, yellow, blue, magenta, cyan and white respec‐
220 tively. Bold is set by 'b', reset by 'B'. Reverse is set by
221 'r', reset by 'R'. Underline is set by 'u', reset by 'U'. The
222 settings are cumulative, e.g., "\Zb\Z1" makes the following text
223 bright red. Restore normal settings with "\Zn".
224 DIALOG_VARS.column_separator
226 This corresponds to the command-line option "--column-separa‐
227 tor". Dialog splits data for radio/checkboxes and menus on the
228 occurrences of the given string, and aligns the split data into
229 columns.
230 DIALOG_VARS.cr_wrap
232 This corresponds to the command-line option "--cr-wrap". If
233 true, interpret embedded newlines in the dialog text as a new‐
234 line on the screen. Otherwise, dialog will only wrap lines
235 where needed to fit inside the text box. Even though you can
236 control line breaks with this, dialog will still wrap any lines
237 that are too long for the width of the box. Without cr-wrap,
238 the layout of your text may be formatted to look nice in the
239 source code of your script without affecting the way it will
240 look in the dialog.
241 DIALOG_VARS.date_format
243 This corresponds to the command-line option "--date-format
244 string". If the host provides strftime, and the value is non‐
245 null, the calendar widget uses this to format its output.
246 DIALOG_VARS.default_button
248 This is set by the command-line option "--default-button. It is
249 used by dlg_default_button.
250 DIALOG_VARS.default_item
252 This corresponds to the command-line option "--default-item
253 string". The given string is used as the default item in a
254 checklist, form or menu box. Normally the first item in the box
255 is the default.
256 DIALOG_VARS.defaultno
258 This corresponds to the command-line option "--defaultno". If
259 true, make the default value of the yes/no box a No. Likewise,
260 make the default button of widgets that provide "OK" and "Can‐
261 cel" a Cancel. If --nocancel was given that option overrides
262 this, making the default button always "Yes" (internally the
263 same as "OK").
264 DIALOG_VARS.dlg_clear_screen
266 This corresponds to the command-line option "--clear". This
267 option is implemented in the main program, not the library. If
268 true, the screen will be cleared on exit. This may be used
269 alone, without other options.
270 DIALOG_VARS.exit_label
272 This corresponds to the command-line option "--exit-label
273 string". The given string overrides the label used for "EXIT"
274 buttons.
275 DIALOG_VARS.extra_button
277 This corresponds to the command-line option "--extra-button".
278 If true, some widgets show an extra button, between "OK" and
279 "Cancel" buttons.
280 DIALOG_VARS.extra_label
282 This corresponds to the command-line option "--extra-label
283 string". The given string overrides the label used for "Extra"
284 buttons. Note: for inputmenu widgets, this defaults to
285 "Rename".
286 DIALOG_VARS.formitem_type
288 This is set by the command-line option "--passwordform" to tell
289 the form widget that its text fields should be treated like
290 password widgets.
291 DIALOG_VARS.help_button
293 This corresponds to the command-line option "--help-button". If
294 true, some widgets show a help-button after "OK" and "Cancel"
295 buttons, i.e., in checklist, radiolist and menu boxes. If
296 --item-help is also given, on exit the return status will be the
297 same as for the "OK" button, and the item-help text will be
298 written to dialog's output after the token "HELP". Otherwise,
299 the return status will indicate that the Help button was
300 pressed, and no message printed.
301 DIALOG_VARS.help_file
303 This corresponds to the command-line option "--hfile string".
304 The given filename is passed to dialog_helpfile when the user
305 presses F1.
306 DIALOG_VARS.help_label
308 This corresponds to the command-line option "--help-label
309 string". The given string overrides the label used for "Help"
310 buttons.
311 DIALOG_VARS.help_line
313 This corresponds to the command-line option "--hline string".
314 The given string is displayed in the bottom of dialog windows,
315 like a subtitle.
316 DIALOG_VARS.help_status
318 This corresponds to the command-line option "--help-status". If
319 true, and the the help-button is selected, writes the checklist
320 or radiolist information after the item-help "HELP" information.
321 This can be used to reconstruct the state of a checklist after
322 processing the help request.
323 DIALOG_VARS.input_length
325 This is nonzero if DIALOG_VARS.input_result is allocated, versus
326 being a pointer to the user's local variables.
327 DIALOG_VARS.input_menu
329 This flag is set to denote whether the menubox widget implements
330 a menu versus a inputmenu widget.
331 DIALOG_VARS.input_result
333 This may be either a user-supplied buffer, or a buffer dynami‐
334 cally allocated by the library, depending on DIA‐
335 LOG_VARS.input_length:
336 · If DIALOG_VARS.input_length is zero, this is a pointer to
338 user buffer (on the stack, or static). The buffer size is
339 assumed to be MAX_LEN, which is defined in <dialog.h>.
340 · When DIALOG_VARS.input_length is nonzero, this is a dynami‐
342 cally-allocated buffer used by the widgets to return print‐
343 able results to the calling application.
344 Certain widgets copy a result to this buffer. If the pointer is
346 NULL, or if the length is insufficient for the result, then the
347 dialog library allocates a buffer which is large enough, and
348 sets DIALOG_VARS.input_length. Callers should check for this
349 case if they have supplied their own buffer.
350 DIALOG_VARS.insecure
352 This corresponds to the command-line option "--insecure". If
353 true, make the password widget friendlier but less secure, by
354 echoing asterisks for each character.
355 DIALOG_VARS.in_helpfile
357 This variable is used to prevent dialog_helpfile from showing
358 anything, e.g., if F1 were pressed within a help-file display.
359 DIALOG_VARS.item_help
361 This corresponds to the command-line option "--item-help". If
362 true, interpret the tags data for checklist, radiolist and menu
363 boxes adding a column whose text is displayed in the bottom line
364 of the screen, for the currently selected item.
365 DIALOG_VARS.keep_tite
367 This is set by the command-line option "--keep-tite" to tell
368 dialog to not attempt to cancel the terminal initialization
369 (termcap ti/te) sequences which correspond to xterm's alternate-
370 screen switching. Normally dialog does this to avoid flickering
371 when run several times in a script.
372 DIALOG_VARS.keep_window
374 This corresponds to the command-line option "--keep-window". If
375 true, do not remove/repaint the window on exit. This is useful
376 for keeping the window contents visible when several widgets are
377 run in the same process. Note that curses will clear the screen
378 when starting a new process.
379 DIALOG_VARS.last_key
381 This corresponds to the command-line option "--last-key".
382 DIALOG_VARS.max_input
384 This corresponds to the command-line option "--max-input size".
385 Limit input strings to the given size. If not specified, the
386 limit is 2048.
387 DIALOG_VARS.no_items
389 This corresponds to the command-line option "--no-items". Some
390 widgets (checklist, inputmenu, radiolist, menu) display a list
391 with two columns (a "tag" and "item", i.e., "description").
392 This tells dialog to read shorter rows from data, omitting the
393 "list".
394 DIALOG_VARS.no_label
396 This corresponds to the command-line option "--no-label string".
397 The given string overrides the label used for "No" buttons.
398 DIALOG_VARS.no_lines
400 This corresponds to the command-line option "--no-lines. It
401 suppresses line-drawing. See DIALOG_VARS.ascii_lines.
402 DIALOG_VARS.no_nl_expand
404 This corresponds to the command-line option "--no-nl-expand".
405 If false, dlg_trim_string converts literal "\n" substrings in a
406 message into newlines.
407 DIALOG_VARS.no_tags
409 This corresponds to the command-line option "--no-tags". Some
410 widgets (checklist, inputmenu, radiolist, menu) display a list
411 with two columns (a "tag" and "item", also known as "descrip‐
412 tion"). The tag is useful for scripting, but may not help the
413 user. The --no-tags option (from Xdialog) may be used to sup‐
414 press the column of tags from the display.
415 Normally dialog allows you to quickly move to entries on the
417 displayed list, by matching a single character to the first
418 character of the tag. When the --no-tags option is given, dia‐
419 log matches against the first character of the description. In
420 either case, the matchable character is highlighted.
421 Here is a table showing how the no_tags and no_items values
423 interact:
424 Widget Fields Shown Fields Read .no_items .no_tags
426 ──────────────────────────────────────────────────────────────
427 buildlist item tag,item 0 0*
428 buildlist item tag,item 0 1
429 buildlist tag tag 1 0*
430 buildlist tag tag 1 1
431 checklist tag,item tag,item 0 0
432 checklist item tag,item 0 1
433 checklist tag tag 1 0
434 checklist tag tag 1 1
435 inputmenu tag,item tag,item 0 0
436 inputmenu item tag,item 0 1
437 inputmenu tag tag 1 0
438 inputmenu tag tag 1 1
439 menu tag,item tag,item 0 0
440 menu item tag,item 0 1
441 menu tag tag 1 0
442 menu tag tag 1 1
443 radiolist tag,item tag,item 0 0
444 radiolist item tag,item 0 1
445 radiolist tag tag 1 0
446 radiolist tag tag 1 1
447 treeview item tag,item 0 0*
448 treeview item tag,item 0 1
449 treeview tag tag 1 0*
450 treeview tag tag 1 1
451 ──────────────────────────────────────────────────────────────
452 * Xdialog does not display the tag column for the analogous
454 buildlist and treeview widgets. Dialog does the same on the
455 command-line. However the library interface defaults to dis‐
456 playing the tag column. Your application can enable or dis‐
457 able the tag column as needed for each widget.
458 DIALOG_VARS.nocancel
460 This corresponds to the command-line option "--no-cancel". If
461 true, suppress the "Cancel" button in checklist, inputbox and
462 menu box modes. A script can still test if the user pressed the
463 ESC key to cancel to quit.
464 DIALOG_VARS.nocollapse
466 This corresponds to the command-line option "--no-collapse".
467 Normally dialog converts tabs to spaces and reduces multiple
468 spaces to a single space for text which is displayed in a mes‐
469 sage boxes, etc. It true, that feature is disabled. Note that
470 dialog will still wrap text, subject to the --cr-wrap option.
471 DIALOG_VARS.nook
473 This corresponds to the command-line option "--nook. Dialog
474 will suppress the "ok" (or "yes") button from the widget.
475 DIALOG_VARS.ok_label
477 This corresponds to the command-line option "--ok-label string".
478 The given string overrides the label used for "OK" buttons.
479 DIALOG_VARS.print_siz
481 This corresponds to the command-line option "--print-size". If
482 true, each widget prints its size to dialog's output when it is
483 invoked.
484 DIALOG_VARS.quoted
486 This corresponds to the command-line option "--quoted.
487 DIALOG_VARS.separate_output
489 This corresponds to the command-line option "--separate-output".
490 If true, checklist widgets output result one line at a time,
491 with no quoting. This facilitates parsing by another program.
492 DIALOG_VARS.single_quoted
494 This corresponds to the command-line option "--single-quoted".
495 If true, Use single-quoting as needed (and no quotes if
496 unneeded) for the output of checklist's as well as the item-help
497 text. If this option is not set, dialog uses double quotes
498 around each item. The latter requires occasional use of back‐
499 slashes to make the output useful in shell scripts.
500 DIALOG_VARS.size_err
502 This corresponds to the command-line option "--size-err". If
503 true, check the resulting size of a dialog box before trying to
504 use it, printing the resulting size if it is larger than the
505 screen. (This option is obsolete, since all new-window calls
506 are checked).
507 DIALOG_VARS.sleep_secs
509 This corresponds to the command-line option "--sleep secs".
510 This option is implemented in the main program, not the library.
511 If nonzero, this is the number of seconds after to delay after
512 processing a dialog box.
513 DIALOG_VARS.tab_correct
515 This corresponds to the command-line option "--tab-correct". If
516 true, convert each tab character of the text to one or more spa‐
517 ces. Otherwise, tabs are rendered according to the curses
518 library's interpretation.
519 DIALOG_VARS.time_format
521 This corresponds to the command-line option "--time-format
522 string". If the host provides strftime, and the value is non‐
523 null, the timebox widget uses this to format its output.
524 DIALOG_VARS.timeout_secs
526 This corresponds to the command-line option "--timeout secs".
527 If nonzero, timeout input requests (exit with error code) if no
528 user response within the given number of seconds.
529 DIALOG_VARS.title
531 This corresponds to the command-line option "--title title".
532 Specifies a title string to be displayed at the top of the dia‐
533 log box.
534 DIALOG_VARS.trim_whitespace
536 This corresponds to the command-line option "--trim". If true,
537 eliminate leading blanks, trim literal newlines and repeated
538 blanks from message text.
539 DIALOG_VARS.visit_items
541 This corresponds to the command-line option "--visit-items".
542 Modify the tab-traversal of the list-oriented widgets
543 (buildlist, checklist, radiobox, menubox, inputmenu, and tree‐
544 view) to include the list of items as one of the states. This
545 is useful as a visual aid, i.e., the cursor position helps some
546 users.
547 DIALOG_VARS.yes_label
549 This corresponds to the command-line option "--yes-label
550 string". The given string overrides the label used for "Yes"
551 buttons.
552
554 Functions that implement major functionality for the command-line dia‐
555 log program, e.g., widgets, have names beginning "dialog_".
556 All dialog boxes have at least three parameters:
558 title
560 the caption for the box, shown on its top border.
561 height
563 the height of the dialog box.
564 width
566 the width of the dialog box.
567 Other parameters depend on the box type.
569 dialog_buildlist
571 implements the "--buildlist" option.
572 const char * title
574 is the title on the top of the widget.
575 const char * cprompt
577 is the prompt text shown within the widget.
578 int height
580 is the desired height of the box. If zero, the height is
581 adjusted to use the available screen size.
582 int width
584 is the desired width of the box. If zero, the height is
585 adjusted to use the available screen size.
586 int list_height
588 is the minimum height to reserve for displaying the list.
589 If zero, it is computed based on the given height and
590 width.
591 int item_no
593 is the number of rows in items.
594 char ** items
596 is an array of strings which is viewed either as a list of
597 rows
598 tag item status
599 or
601 tag item status help
602 depending on whether dialog_vars.item_help is set.
604 int order_mode
606 is reserved for future enhancements
607 dialog_calendar
609 implements the "--calendar" option.
610 const char * title
612 is the title on the top of the widget.
613 const char * subtitle
615 is the prompt text shown within the widget.
616 int height
618 is the height excluding the fixed-height calendar grid.
619 int width
621 is the overall width of the box, which is adjusted up to
622 the calendar grid's minimum width if needed.
623 int day
625 is the initial day of the week shown, counting zero as Sun‐
626 day. If the value is negative, the current day of the week
627 is used.
628 int month
630 is the initial month of the year shown, counting one as
631 January. If the value is negative, the current month of
632 the year is used.
633 int year
635 is the initial year shown. If the value is negative, the
636 current year is used.
637 dialog_checklist
639 implements the "--checklist" and "--radiolist" options depending
640 on the flag parameter.
641 const char * title
643 is the title on the top of the widget.
644 const char * cprompt
646 is the prompt text shown within the widget.
647 int height
649 is the desired height of the box. If zero, the height is
650 adjusted to use the available screen size.
651 int width
653 is the desired width of the box. If zero, the height is
654 adjusted to use the available screen size.
655 int list_height
657 is the minimum height to reserve for displaying the list.
658 If zero, it is computed based on the given height and
659 width.
660 int item_no
662 is the number of rows in items.
663 int items
665 is an array of strings which is viewed either as a list of
666 rows
667 tag item status
668 or
670 tag item status help
671 depending on whether dialog_vars.item_help is set.
673 flag is either FLAG_CHECK, for checklists, or FLAG_RADIO for
675 radiolists.
676 dialog_dselect
678 implements the "--dselect" option.
679 const char * title
681 is the title on the top of the widget.
682 const char * path
684 is the preselected value to show in the input-box, which is
685 used also to set the directory- and file-windows.
686 int height
688 is the height excluding the minimum needed to show the dia‐
689 log box framework. If zero, the height is based on the
690 screen size.
691 int width
693 is the desired width of the box. If zero, the height is
694 based on the screen size.
695 dialog_editbox
697 implements the "--editbox" option.
698 const char * title
700 is the title on the top of the widget.
701 const char * file
703 is the name of the file from which to read.
704 int height
706 is the desired height of the box. If zero, the height is
707 adjusted to use the available screen size.
708 int width
710 is the desired width of the box. If zero, the height is
711 adjusted to use the available screen size.
712 dialog_form
714 implements the "--form" option.
715 const char * title
717 is the title on the top of the widget.
718 const char * cprompt
720 is the prompt text shown within the widget.
721 int height
723 is the desired height of the box. If zero, the height is
724 adjusted to use the available screen size.
725 int width
727 is the desired width of the box. If zero, the height is
728 adjusted to use the available screen size.
729 int form_height
731 is the minimum height to reserve for displaying the list.
732 If zero, it is computed based on the given height and
733 width.
734 int item_no
736 is the number of rows in items.
737 int items
739 is an array of strings which is viewed either as a list of
740 rows
741 Name NameY NameX Text TextY TextX FLen ILen
742 or
744 Name NameY NameX Text TextY TextX FLen ILen Help
745 depending on whether dialog_vars.item_help is set.
747 dialog_fselect
749 implements the "--fselect" option.
750 const char * title
752 is the title on the top of the widget.
753 const char * path
755 is the preselected value to show in the input-box, which is
756 used also to set the directory- and file-windows.
757 int height
759 is the height excluding the minimum needed to show the dia‐
760 log box framework. If zero, the height is based on the
761 screen size.
762 int width
764 is the desired width of the box. If zero, the height is
765 based on the screen size.
766 dialog_gauge
768 implements the "--gauge" option. Alternatively, a simpler or
769 customized gauge widget can be setup using dlg_allocate_gauge,
770 dlg_update_gauge and dlg_free_gauge.
771 const char * title
773 is the title on the top of the widget.
774 const char * cprompt
776 is the prompt text shown within the widget.
777 int height
779 is the desired height of the box. If zero, the height is
780 based on the screen size.
781 int width
783 is the desired width of the box. If zero, the height is
784 based on the screen size.
785 int percent
787 is the percentage to show in the progress bar.
788 dialog_inputbox
790 implements the "--inputbox" or "--password" option, depending on
791 the value of password.
792 const char * title
794 is the title on the top of the widget.
795 const char * cprompt
797 is the prompt text shown within the widget.
798 int height
800 is the desired height of the box. If zero, the height is
801 based on the screen size.
802 int width
804 is the desired width of the box. If zero, the height is
805 based on the screen size.
806 const char * init
808 is the initial value of the input box, whose length is
809 taken into account when auto-sizing the width of the dialog
810 box.
811 int password
813 if true, causes typed input to be echoed as asterisks.
814 dialog_helpfile
816 implements the "--hfile" option.
817 const char * title
819 is the title on the top of the widget.
820 const char * file
822 is the name of a file containing the text to display. This
823 function is internally bound to F1 (function key "1"),
824 passing dialog_vars.help_file as a parameter. The dialog
825 program sets that variable when the --hfile option is
826 given.
827 int height
829 is the desired height of the box. If zero, the height is
830 based on the screen size.
831 int width
833 is the desired width of the box. If zero, the height is
834 based on the screen size.
835 dialog_menu
837 implements the "--menu" or "--inputmenu" option depending on
838 whether dialog_vars.input_menu is set.
839 const char * title
841 is the title on the top of the widget.
842 const char * cprompt
844 is the prompt text shown within the widget.
845 int height
847 is the desired height of the box. If zero, the height is
848 based on the screen size.
849 int width
851 is the desired width of the box. If zero, the height is
852 based on the screen size.
853 int menu_height
855 is the minimum height to reserve for displaying the list.
856 If zero, it is computed based on the given height and
857 width.
858 int item_no
860 is the number of rows in items.
861 int items
863 is an array of strings which is viewed either as a list of
864 rows
865 tag item
866 or
868 tag item help
869 depending on whether dialog_vars.item_help is set.
871 dialog_mixedform
873 implements the "--mixedform" option.
874 const char * title
876 is the title on the top of the widget.
877 const char * cprompt
879 is the prompt text shown within the widget.
880 int height
882 is the desired height of the box. If zero, the height is
883 adjusted to use the available screen size.
884 int width
886 is the desired width of the box. If zero, the height is
887 adjusted to use the available screen size.
888 int form_height
890 is the minimum height to reserve for displaying the list.
891 If zero, it is computed based on the given height and
892 width.
893 int item_no
895 is the number of rows in items.
896 int items
898 is an array of strings which is viewed either as a list of
899 rows
900 Name NameY NameX Text TextY TextX FLen ILen Ityp
901 or
903 Name NameY NameX Text TextY TextX FLen ILen Ityp Help
904 depending on whether dialog_vars.item_help is set.
906 dialog_mixedgauge
908 implements the "--mixedgauge" option
909 const char * title
911 is the title on the top of the widget.
912 const char * cprompt
914 is the caption text shown within the widget.
915 int height
917 is the desired height of the box. If zero, the height is
918 based on the screen size.
919 int width
921 is the desired width of the box. If zero, the height is
922 based on the screen size.
923 int percent
925 is the percentage to show in the progress bar.
926 int item_no
928 is the number of rows in items.
929 int items
931 is an array of strings which is viewed as a list of tag and
932 item values. The tag values are listed, one per row, in
933 the list at the top of the widget.
934 The item values are decoded: digits 0-9 are the following
936 strings
937 0 Succeeded
939 1 Failed
941 2 Passed
943 3 Completed
945 4 Checked
947 5 Done
949 6 Skipped
951 7 In Progress
953 8 (blank)
955 9 N/A
957 A string with a leading "-" character is centered, marked
959 with "%". For example, "-75" is displayed as "75%". Other
960 strings are displayed as is.
961 dialog_msgbox
963 implements the "--msgbox" or "--infobox" option depending on
964 whether pauseopt is set.
965 const char * title
967 is the title on the top of the widget.
968 const char * cprompt
970 is the prompt text shown within the widget.
971 int height
973 is the desired height of the box. If zero, the height is
974 based on the screen size.
975 int width
977 is the desired width of the box. If zero, the height is
978 based on the screen size.
979 int pauseopt
981 if true, an "OK" button will be shown, and the dialog will
982 wait for it to complete. With an "OK" button, it is
983 denoted a "msgbox", without an "OK" button, it is denoted
984 an "infobox".
985 dialog_pause
987 implements the "--pause" option.
988 const char * title
990 is the title on the top of the widget.
991 int height
993 is the desired height of the box. If zero, the height is
994 based on the screen size.
995 int width
997 is the desired width of the box. If zero, the height is
998 based on the screen size.
999 int seconds
1001 is the timeout to use for the progress bar.
1002 dialog_prgbox
1004 implements the "--prgbox" option.
1005 const char * title
1007 is the title on the top of the widget.
1008 const char * cprompt
1010 is the prompt text shown within the widget. If empty or
1011 null, no prompt is shown.
1012 const char * command
1014 is the name of the command to execute.
1015 int height
1017 is the desired height of the box. If zero, the height is
1018 based on the screen size.
1019 int width
1021 is the desired width of the box. If zero, the height is
1022 based on the screen size.
1023 int pauseopt
1025 if true, an "OK" button will be shown, and the dialog will
1026 wait for it to complete.
1027 dialog_progressbox
1029 implements the "--progressbox" option.
1030 const char * title
1032 is the title on the top of the widget.
1033 const char * cprompt
1035 is the prompt text shown within the widget. If empty or
1036 null, no prompt is shown.
1037 int height
1039 is the desired height of the box. If zero, the height is
1040 based on the screen size.
1041 int width
1043 is the desired width of the box. If zero, the height is
1044 based on the screen size.
1045 dialog_rangebox
1047 implements the "--rangebox" option.
1048 const char * title
1050 is the title on the top of the widget.
1051 const char * cprompt
1053 is the prompt text shown within the widget. If empty or
1054 null, no prompt is shown.
1055 int height
1057 is the desired height of the widget. If zero, the height
1058 is based on the screen size.
1059 int width
1061 is the desired width of the widget. If zero, the height is
1062 based on the screen size.
1063 int min_value
1065 is the minimum value to allow.
1066 int max_value
1068 is the maximum value to allow.
1069 int default_value
1071 is the default value, if no change is made.
1072 dialog_tailbox
1074 implements the "--tailbox" or "--tailboxbg" option depending on
1075 whether bg_task is set.
1076 const char * title
1078 is the title on the top of the widget.
1079 const char * file
1081 is the name of the file to display in the dialog.
1082 int height
1084 is the desired height of the box. If zero, the height is
1085 based on the screen size.
1086 int width
1088 is the desired width of the box. If zero, the height is
1089 based on the screen size.
1090 int bg_task
1092 if true, the window is added to the callback list in dia‐
1093 log_state, and the application will poll for the window to
1094 be updated. Otherwise an "OK" button is added to the win‐
1095 dow, and it will be closed when the button is activated.
1096 dialog_textbox
1098 implements the "--textbox" option.
1099 const char * title
1101 is the title on the top of the widget.
1102 const char * file
1104 is the name of the file to display in the dialog.
1105 int height
1107 is the desired height of the box. If zero, the height is
1108 based on the screen size.
1109 int width
1111 is the desired width of the box. If zero, the height is
1112 based on the screen size.
1113 dialog_timebox
1115 implements the "--timebox" option.
1116 const char * title
1118 is the title on the top of the widget.
1119 const char * subtitle
1121 is the prompt text shown within the widget.
1122 int height
1124 is the desired height of the box. If zero, the height is
1125 based on the screen size.
1126 int width
1128 is the desired width of the box. If zero, the height is
1129 based on the screen size.
1130 int hour
1132 is the initial hour shown. If the value is negative, the
1133 current hour is used. Returns DLG_EXIT_ERROR if the value
1134 specified is greater than or equal to 24.
1135 int minute
1137 is the initial minute shown. If the value is negative, the
1138 current minute is used. Returns DLG_EXIT_ERROR if the
1139 value specified is greater than or equal to 60.
1140 int second
1142 is the initial second shown. If the value is negative, the
1143 current second is used. Returns DLG_EXIT_ERROR if the
1144 value specified is greater than or equal to 60.
1145 dialog_treeview
1147 implements the "--treeview" option.
1148 const char * title
1150 is the title on the top of the widget.
1151 const char * cprompt
1153 is the prompt text shown within the widget.
1154 int height
1156 is the desired height of the box. If zero, the height is
1157 based on the screen size.
1158 int width
1160 is the desired width of the box. If zero, the height is
1161 based on the screen size.
1162 int list_height
1164 is the minimum height to reserve for displaying the list.
1165 If zero, it is computed based on the given height and
1166 width.
1167 int item_no
1169 is the number of rows in items.
1170 char ** items
1172 is the list of items, contain tag, name, and optionally
1173 help strings (if dialog_vars.item_help is set). The ini‐
1174 tial selection state for each item is also in this list.
1175 int flag
1177 flag is either FLAG_CHECK, for checklists (multiple selections),
1179 or FLAG_RADIO for radiolists (a single selection).
1180 dialog_yesno
1182 implements the "--yesno" option.
1183 const char * title
1185 is the title on the top of the widget.
1186 const char * cprompt
1188 is the prompt text shown within the widget.
1189 int height
1191 is the desired height of the box. If zero, the height is
1192 based on the screen size.
1193 int width
1195 is the desired width of the box. If zero, the height is
1196 based on the screen size.
1197
1199 Most functions that implement lower-level functionality for the com‐
1200 mand-line dialog program or widgets, have names beginning "dlg_". Bow‐
1201 ing to longstanding usage, the functions that initialize the display
1202 and end it are named init_dialog and end_dialog.
1203 The only non-widget function whose name begins with "dialog_" is dia‐
1205 log_version, which returns the version number of the library as a
1206 string.
1207 Here is a brief summary of the utility functions and their parameters:
1209 dlg_add_callback
1211 Add a callback, used to allow polling input from multiple tailbox
1212 widgets.
1213 DIALOG_CALLBACK *p
1215 contains the callback information.
1216 dlg_add_callback_ref
1218 Like dlg_add_callback, but passes a reference to the DIALOG_CALL‐
1219 BACK as well as a pointer to a cleanup function which will be
1220 called when the associated input ends.
1221 DIALOG_CALLBACK **p
1223 points to the callback information. This is a reference to
1224 the pointer so that the caller's pointer can be zeroed when
1225 input ends.
1226 DIALOG_FREEBACK func
1228 function to call when input ends, e.g., to free caller's
1229 additional data.
1230 dlg_add_last_key
1232 Report the last key entered by the user. This implements the
1233 --last-key command-line option, using dialog_vars.last_key.
1234 int mode
1236 controls the way the last key report is separated from other
1237 results:
1238 -2 (no separator)
1240 -1 (separator after the key name)
1242 0 (separator is optionally before the key name)
1244 1 (same as -1)
1246 dlg_add_quoted
1248 Add a quoted string to the result buffer (see dlg_add_result). If
1249 no quotes are necessary, none are used. If dialog_vars.sin‐
1250 gle_quoted is set, single-quotes are used. Otherwise, double-
1251 quotes are used.
1252 char * string
1254 is the string to add.
1255 dlg_add_result
1257 Add a string to the result buffer dialog_vars.input_result.
1258 char * string
1260 is the string to add.
1261 dlg_add_separator
1263 Add an output-separator to the result buffer dia‐
1264 log_vars.input_result. If dialog_vars.output_separator is set,
1265 use that. Otherwise, if dialog_vars.separate_output is set, use
1266 newline. If neither is set, use a space.
1267 dlg_add_string
1269 Add a quoted or unquoted string to the result buffer (see
1270 dlg_add_quoted) and dlg_add_result), according to whether dia‐
1271 log_vars.quoted is true.
1272 char * string
1274 is the string to add.
1275 dlg_align_columns
1277 Copy and reformat an array of pointers to strings, aligning
1278 according to the column separator dialog_vars.column_separator.
1279 If no column separator is set, the array will be unmodified; oth‐
1280 erwise it is copied and reformatted.
1281 Caveat: This function is only implemented for 8-bit characters.
1283 char **target
1285 This is the array to reformat. It points to the first string
1286 to modify.
1287 int per_row
1289 This is the size of the struct for each row of the array.
1290 int num_rows
1292 This is the number of rows in the array.
1293 dlg_allocate_gauge
1295 Allocates a gauge widget. Use dlg_update_gauge to display the
1296 result.
1297 const char * title
1299 is the title string to display at the top of the widget.
1300 const char * cprompt
1302 is the prompt text shown within the widget.
1303 int height
1305 is the desired height of the box. If zero, the height is
1306 adjusted to use the available screen size.
1307 int width
1309 is the desired width of the box. If zero, the height is
1310 adjusted to use the available screen size.
1311 int percent
1313 is the percentage to show in the progress bar.
1314 dlg_asciibox
1316 returns its parameter transformed to the corresponding "+" or "-",
1317 etc. for the line-drawing characters used in dialog. If the
1318 parameter is not a line-drawing or other special character such as
1319 ACS_DARROW, it returns 0.
1320 chtype ch
1322 is the parameter, usually one of the ACS_xxx constants.
1323 dlg_attr_clear
1325 Set window to the given attribute.
1326 WINDOW * win
1328 is the window to update.
1329 int height
1331 is the number of rows to update.
1332 int width
1334 is the number of columns to update.
1335 chtype attr
1337 is the attribute, e.g., A_BOLD.
1338 dlg_auto_size
1340 Automatically size the window used for a widget. If the given
1341 height or width are zero, justify the prompt text and return the
1342 actual limits.
1343 const char * title
1345 is the title string to display at the top of the widget.
1346 const char * prompt
1348 is the message text which will be displayed in the widget,
1349 used here to determine how large the widget should be.
1350 int * height
1352 is the nominal height.
1353 int * width
1355 is the nominal width.
1356 int boxlines
1358 is the number of lines to reserve in the vertical direction.
1359 int mincols
1361 is the minimum number of columns to use.
1362 dlg_auto_sizefile
1364 Like dlg_auto_size, but use a file contents to decide how large
1365 the widget should be.
1366 const char * title
1368 is the title string to display at the top of the widget.
1369 const char * file
1371 is the name of the file.
1372 int * height
1374 is the nominal height. If it is -1, use the screen's height
1375 (after subtracting dialog_vars.begin_y if dia‐
1376 log_vars.begin_set is true).
1377 int * width
1379 is the nominal width. If it is -1, use the screen's width
1380 (after subtracting dialog_vars.begin_x if dia‐
1381 log_vars.begin_set is true).
1382 int boxlines
1384 is the number of lines to reserve on the screen for drawing
1385 boxes.
1386 int mincols
1388 is the number of columns to reserve on the screen for drawing
1389 boxes.
1390 dlg_beeping
1392 If dialog_vars.beep_signal is nonzero, this calls beep once and
1393 sets dialog_vars.beep_signal to zero.
1394 dlg_boxchar
1396 returns its chtype parameter transformed as follows:
1397 · if neither dialog_vars.ascii_lines nor dialog_vars.no_lines is
1399 set.
1400 · if dialog_vars.ascii_lines is set, returns the corresponding
1402 "+" or "-", etc. for the line-drawing characters used in dia‐
1403 log.
1404 · otherwise, if dialog_vars.no_lines is set, returns a space for
1406 the line-drawing characters.
1407 · if the parameter is not a line-drawing or other special char‐
1409 acter such as ACS_DARROW, it returns the parameter unchanged.
1410 dlg_box_x_ordinate
1412 returns a suitable x-ordinate (column) for a new widget. If dia‐
1413 log_vars.begin_set is 1, use dialog_vars.begin_x; otherwise center
1414 the widget on the screen (using the width parameter).
1415 int width
1417 is the width of the widget.
1418 dlg_box_y_ordinate
1420 returns a suitable y-ordinate (row) for a new widget. If dia‐
1421 log_vars.begin_set is 1, use dialog_vars.begin_y; otherwise center
1422 the widget on the screen (using the height parameter).
1423 int height
1425 is the height of the widget.
1426 dlg_buildlist
1428 This is an alternate interface to the buildlist widget which
1429 allows the application to read the list item states back directly
1430 without putting them in the output buffer.
1431 const char * title
1433 is the title string to display at the top of the widget.
1434 const char * cprompt
1436 is the prompt text shown within the widget.
1437 int height
1439 is the desired height of the box. If zero, the height is
1440 adjusted to use the available screen size.
1441 int width
1443 is the desired width of the box. If zero, the height is
1444 adjusted to use the available screen size.
1445 int list_height
1447 is the minimum height to reserve for displaying the list. If
1448 zero, it is computed based on the given height and width.
1449 int item_no
1451 is the number of rows in items.
1452 DIALOG_LISTITEM * items
1454 is the list of items, contain tag, name, and optionally help
1455 strings (if dialog_vars.item_help is set). The initial
1456 selection state for each item is also in this list.
1457 const char * states
1459 This is a list of characters to display for the given states.
1460 Normally a buildlist provides true (1) and false (0) values,
1461 which the widget displays as "*" and space, respectively. An
1462 application may set this parameter to an arbitrary null-ter‐
1463 minated string. The widget determines the number of states
1464 from the length of this string, and will cycle through the
1465 corresponding display characters as the user presses the
1466 space-bar.
1467 int order_mode
1469 is reserved for future enhancements
1470 int * current_item
1472 The widget sets the referenced location to the index of the
1473 current display item (cursor) when it returns.
1474 dlg_button_count
1476 Count the buttons in the list.
1477 const char ** labels
1479 is a list of (pointers to) button labels terminated by a null
1480 pointer.
1481 dlg_button_layout
1483 Make sure there is enough space for the buttons by computing the
1484 width required for their labels, adding margins and limiting based
1485 on the screen size.
1486 const char ** labels
1488 is a list of (pointers to) button labels terminated by a null
1489 pointer.
1490 int * limit
1492 the function sets the referenced limit to the width required
1493 for the buttons (limited by the screen size) if that is wider
1494 than the passed-in limit.
1495 dlg_button_sizes
1497 Compute the size of the button array in columns.
1498 const char ** labels
1500 is a list of (pointers to) button labels terminated by a null
1501 pointer.
1502 int vertical
1504 is true if the buttons are arranged in a column rather than a
1505 row.
1506 int * longest
1508 Return the total number of columns in the referenced loca‐
1509 tion.
1510 int * length
1512 Return the longest button's columns in the referenced loca‐
1513 tion.
1514 dlg_button_x_step
1516 Compute the step-size needed between elements of the button array.
1517 const char ** labels
1519 is a list of (pointers to) button labels terminated by a null
1520 pointer.
1521 int limit
1523 is the maximum number of columns to allow for the buttons.
1524 int * gap
1526 store the nominal gap between buttons in the referenced loca‐
1527 tion. This is constrained to be at least one.
1528 int * margin
1530 store the left+right total margins (for the list of buttons)
1531 in the referenced location.
1532 int * step
1534 store the step-size in the referenced location.
1535 dlg_button_to_char
1537 Find the first uppercase character in the label, which we may use
1538 for an abbreviation. If the label is empty, return -1. If no
1539 uppercase character is found, return 0. Otherwise return the
1540 uppercase character.
1541 Normally dlg_draw_buttons and dlg_char_to_button use the first
1543 uppercase character. However, they keep track of all of the
1544 labels and if the first has already been used in another label,
1545 they will continue looking for another uppercase character. This
1546 function does not have enough information to make that check.
1547 const char * label
1549 is the label to test.
1550 dlg_calc_list_width
1552 Calculate the minimum width for the list, assuming none of the
1553 items are truncated.
1554 int item_no
1556 is the number of items.
1557 DIALOG_LISTITEM * items
1559 contains a name and text field, e.g., for checklists or
1560 radiobox lists. The function returns the sum of the widest
1561 columns needed for of each of these fields.
1562 If dialog_vars.no_items is set, the text fields in the list
1564 are ignored.
1565 dlg_calc_listh
1567 Calculate new height and list_height values.
1568 int * height
1570 on input, is the height without adding the list-height. On
1571 return, this contains the total list-height and is the actual
1572 widget's height.
1573 int * list_height
1575 on input, is the requested list-height. On return, this con‐
1576 tains the number of rows available for displaying the list
1577 after taking into account the screen size and the dia‐
1578 log_vars.begin_set and dialog_vars.begin_y variables.
1579 int item_no
1581 is the number of items in the list.
1582 dlg_calc_listw
1584 This function is obsolete, provided for library-compatibility. It
1585 is replaced by dlg_calc_list_width.
1586 int item_no
1588 is the number of items.
1589 char ** items
1591 is a list of character pointers.
1592 int group
1594 is the number of items in each group, e.g., the second array
1595 index.
1596 dlg_char_to_button
1598 Given a list of button labels, and a character which may be the
1599 abbreviation for one, find it, if it exists. An abbreviation will
1600 be the first character which happens to be capitalized in the
1601 label. If the character is found, return its index within the
1602 list of labels. Otherwise, return DLG_EXIT_UNKNOWN.
1603 int ch
1605 is the character to find.
1606 const char ** labels
1608 is a list of (pointers to) button labels terminated by a null
1609 pointer.
1610 dlg_checklist
1612 This entrypoint provides the --checklist or --radiolist function‐
1613 ality without the limitations of dialog's command-line syntax
1614 (compare to dialog_checklist).
1615 const char * title
1617 is the title string to display at the top of the widget.
1618 const char * cprompt
1620 is the prompt text shown within the widget.
1621 int height
1623 is the desired height of the box. If zero, the height is
1624 adjusted to use the available screen size.
1625 int width
1627 is the desired width of the box. If zero, the height is
1628 adjusted to use the available screen size.
1629 int list_height
1631 is the minimum height to reserve for displaying the list. If
1632 zero, it is computed based on the given height and width.
1633 int item_no
1635 is the number of items.
1636 DIALOG_LISTITEM * items
1638 This is a list of the items to display in the checklist.
1639 const char * states
1641 This is a list of characters to display for the given states.
1642 Normally a checklist provides true (1) and false (0) values,
1643 which the widget displays as "*" and space, respectively. An
1644 application may set this parameter to an arbitrary null-ter‐
1645 minated string. The widget determines the number of states
1646 from the length of this string, and will cycle through the
1647 corresponding display characters as the user presses the
1648 space-bar.
1649 int flag
1651 This is should be one of FLAG_CHECK or FLAG_RADIO, depending
1652 on whether the widget should act as a checklist or radiobox.
1653 int * current_item
1655 The widget sets the referenced location to the index of the
1656 current display item (cursor) when it returns.
1657 dlg_check_scrolled
1659 given a function key (or other key that was mapped to a function
1660 key), check if it is one of the up/down scrolling functions:
1661 DLGK_PAGE_FIRST,
1663 DLGK_PAGE_LAST,
1664 DLGK_GRID_UP,
1665 DLGK_GRID_DOWN,
1666 DLGK_PAGE_PREV or
1667 DLGK_PAGE_NEXT.
1668 Some widgets use these key bindings for scrolling the prompt-text
1670 up and down, to allow for display in very small windows.
1671 The function returns 0 (zero) if it finds one of these keys, and
1673 -1 if not.
1674 int key
1676 is the function-key to check
1677 int last
1679 is the number of lines which would be used to display the
1680 scrolled prompt in an arbitrarily tall window. It is used
1681 here to check limits for the offset value.
1682 int page
1684 this is the available height for writing scrolled text, which
1685 is smaller than the window if it contains buttons.
1686 bool * show
1688 on return, holds TRUE if dlg_print_scrolled should be used to
1689 redisplay the prompt text.
1690 int * offset
1692 on entry, holds the starting line number (counting from zero)
1693 last used for dlg_print_scrolled. On return, holds the
1694 updated starting line number.
1695 dlg_clear
1697 Set window to the default dialog screen attribute. This is set in
1698 the rc-file with screen_color.
1699 dlg_clr_result
1701 Free storage used for the result buffer (dia‐
1702 log_vars.input_result). The corresponding pointer is set to NULL.
1703 dlg_color_count
1705 Return the number of colors that can be configured in dialog.
1706 dlg_color_setup
1708 Initialize the color pairs used in dialog.
1709 dlg_count_argv
1711 Count the entries in an argument vector.
1712 argv Points to the argument vector.
1714 dlg_count_columns
1716 Returns the number of columns used for a string. This is not nec‐
1717 essarily the number of bytes in a string.
1718 const char * string
1720 is the string to measure.
1721 dlg_count_real_columns
1723 Returns the number of columns used for a string, accounting for
1724 "\Z" sequences which can be used for coloring the text if dia‐
1725 log_vars.colors is set. This is not necessarily the number of
1726 bytes in a string.
1727 const char * string
1729 is the string to measure.
1730 dlg_count_wchars
1732 Returns the number of wide-characters in the string.
1733 const char * string
1735 is the string to measure.
1736 dlg_create_rc
1738 Create a configuration file, i.e., write internal tables to a file
1739 which can be read back by dialog as an rc-file.
1740 const char * filename
1742 is the name of the file to write to.
1743 dlg_ctl_size
1745 If dialog_vars.size_err is true, check if the given window size is
1746 too large to fit on the screen. If so, exit with an error report‐
1747 ing the size of the window.
1748 int height
1750 is the window's height
1751 int width
1753 is the window's width
1754 dlg_default_button
1756 If dialog_vars.default_button is positive, return the button-index
1757 for that button code, using dlg_ok_buttoncode to test indices
1758 starting with zero. Otherwise (or if no match was found for the
1759 button code), return zero.
1760 dlg_default_formitem
1762 If dialog_vars.default_item is not null, find that name by match‐
1763 ing the name field in the list of form items. If found, return
1764 the index of that item in the list. Otherwise, return zero.
1765 DIALOG_FORMITEM * items
1767 is the list of items to search. It is terminated by an entry
1768 with a null name field.
1769 dlg_default_item
1771 This function is obsolete, provided for library-compatibility. It
1772 is replaced by dlg_default_formitem and dlg_default_listitem.
1773 char ** items
1775 is the list of items to search.
1776 int llen
1778 is the number of items in each group, e.g., the second array
1779 index.
1780 dlg_defaultno_button
1782 If dialog_vars.defaultno is true, and dialog_vars.nocancel is not,
1783 find the button-index for the "Cancel" button. Otherwise, return
1784 the index for "OK" (always zero).
1785 dlg_del_window
1787 Remove a window, repainting everything else.
1788 WINDOW * win
1790 is the window to remove.
1791 dlg_does_output
1793 This is called each time a widget is invoked which may do output.
1794 It increments dialog_state.output_count, so the output function in
1795 dialog can test this and add a separator.
1796 dlg_draw_arrows
1798 Draw up/down arrows on a window, e.g., for scrollable lists. It
1799 calls dlg_draw_arrows2 using the menubox_color and menubox_bor‐
1800 der_color attributes.
1801 WINDOW * dialog
1803 is the window on which to draw an arrow.
1804 int top_arrow
1806 is true if an up-arrow should be drawn at the top of the win‐
1807 dow.
1808 int bottom_arrow
1810 is true if an down-arrow should be drawn at the bottom of the
1811 window.
1812 int x
1814 is the zero-based column within the window on which to draw
1815 arrows.
1816 int top
1818 is the zero-based row within the window on which to draw up-
1819 arrows as well as a horizontal line to show the window's top.
1820 int bottom
1822 is the zero-based row within the window on which to draw
1823 down-arrows as well as a horizontal line to show the window's
1824 bottom.
1825 dlg_draw_arrows2
1827 Draw up/down arrows on a window, e.g., for scrollable lists.
1828 WINDOW * dialog
1830 is the window on which to draw an arrow.
1831 int top_arrow
1833 is true if an up-arrow should be drawn at the top of the win‐
1834 dow.
1835 int bottom_arrow
1837 is true if an down-arrow should be drawn at the bottom of the
1838 window.
1839 int x
1841 is the zero-based column within the window on which to draw
1842 arrows.
1843 int top
1845 is the zero-based row within the window on which to draw up-
1846 arrows as well as a horizontal line to show the window's top.
1847 int bottom
1849 is the zero-based row within the window on which to draw
1850 down-arrows as well as a horizontal line to show the window's
1851 bottom.
1852 chtype attr
1854 is the window's background attribute.
1855 chtype borderattr
1857 is the window's border attribute.
1858 dlg_draw_bottom_box
1860 Draw a partial box at the bottom of a window, e.g., to surround a
1861 row of buttons. It is designed to merge with an existing box
1862 around the whole window (see dlg_draw_box), so it uses tee-ele‐
1863 ments rather than corner-elements on the top corners of this box.
1864 WINDOW * win
1866 is the window to update.
1867 dlg_draw_bottom_box2
1869 Draw a partial box at the bottom of a window, e.g., to surround a
1870 row of buttons. It is designed to merge with an existing box
1871 around the whole window (see dlg_draw_box2), so it uses tee-ele‐
1872 ments rather than corner-elements on the top corners of this box.
1873 WINDOW * win
1875 is the window to update. chtype on_left is used to color the
1876 upper/left edges of the box, i.e., the tee-element and hori‐
1877 zontal line chtype on_right is used to color the right edge
1878 of the box, i.e., the tee-element chtype on_inside is used to
1879 fill-color the inside of the box
1880 dlg_draw_box
1882 Draw a rectangular box with line drawing characters.
1883 WINDOW * win
1885 is the window to update.
1886 int y
1888 is the top row of the box.
1889 int x
1891 is the left column of the box.
1892 int height
1894 is the height of the box.
1895 int width
1897 is the width of the box.
1898 chtype boxchar
1900 is used to color the right/lower edges. It also is fill-
1901 color used for the box contents.
1902 chtype borderchar
1904 is used to color the upper/left edges.
1905 dlg_draw_box2
1907 Draw a rectangular box with line drawing characters.
1908 WINDOW * win
1910 is the window to update.
1911 int y
1913 is the top row of the box.
1914 int x
1916 is the left column of the box.
1917 int height
1919 is the height of the box.
1920 int width
1922 is the width of the box.
1923 chtype boxchar
1925 is used to fill-color for the box contents.
1926 chtype borderchar
1928 is used to color the upper/left edges.
1929 chtype borderchar2
1931 is used to color the right/lower edges.
1932 dlg_draw_buttons
1934 Print a list of buttons at the given position.
1935 WINDOW * win
1937 is the window to update.
1938 int y
1940 is the starting row.
1941 int x
1943 is the starting column.
1944 const char ** labels
1946 is a list of (pointers to) button labels terminated by a null
1947 pointer.
1948 int selected
1950 is the index within the list of the selected button.
1951 int vertical
1953 is true if the buttons are arranged in a column rather than a
1954 row.
1955 int limit
1957 is the number of columns (or rows if vertical) allowed for
1958 the display.
1959 dlg_draw_helpline
1961 draw the text in dialog_vars.help_line at the bottom of the given
1962 window.
1963 WINDOW * dialog
1965 is the window to modify.
1966 bool decorations
1968 if true, allow room for the scrolling arrows.
1969 dlg_draw_scrollbar
1971 If dialog_state.use_scrollbar is set, draw a scrollbar on the
1972 right margin of windows holding scrollable data. Also (whether or
1973 not the scrollbar is drawn), annotate the bottom margin of the
1974 window with the percentage of data by the bottom of that window,
1975 and call dlg_draw_arrows2 to put markers on the window showing
1976 when more data is available.
1977 WINDOW * win
1979 is the window in which the data is scrolled. Because left,
1980 right, top, bottom are passed as parameters, this window can
1981 contain additional data.
1982 long first_data
1984 is the zero-based index to the first row of data in the cur‐
1985 rent window.
1986 long this_data
1988 is the zero-based index to the current row of data.
1989 long next_data
1991 is the zero-based index to the next data after the current
1992 row.
1993 long total_data
1995 is the total number of rows of data.
1996 int left
1998 is the zero-based left margin/column of the window. The
1999 up/down arrows are draw inset by 5 columns from this point.
2000 int right
2002 is the zero-based right margin/column of the window. The
2003 scrollbar is drawn flush against this column.
2004 int top
2006 is the zero-based row within the window on which to draw up-
2007 arrows as well as a horizontal line to show the window's top.
2008 int bottom
2010 is the zero-based row within the window on which to draw
2011 down-arrows as well as a horizontal line to show the window's
2012 bottom.
2013 chtype attr
2015 is the window's background attribute.
2016 chtype borderattr
2018 is the window's border attribute.
2019 dlg_draw_shadow
2021 Draw shadows along the right and bottom edge of a window to give
2022 it a 3-dimensional look. (The height, etc., may not be the same
2023 as the window's actual values).
2024 WINDOW * win
2026 is the window to update.
2027 int height
2029 is the height of the window.
2030 int width
2032 is the width of the window.
2033 int y
2035 is the top row of the window.
2036 int x
2038 is the left column of the window.
2039 dlg_draw_title
2041 Draw a title centered at the top of the window.
2042 WINDOW * win
2044 is the window to update.
2045 const char * title
2047 is the title string to display at the top of the widget.
2048 dlg_dummy_menutext
2050 This is a utility function which supports the --inputmenu option
2051 of the dialog program. If dialog_vars.input_menu is set, dia‐
2052 log_menu passes this pointer to dlg_menu as the rename_menutext
2053 parameter. Otherwise, it passes dlg_dummy_menutext.
2054 The function should only return DLG_EXIT_ERROR.
2056 DIALOG_LISTITEM * items
2058 is the list of menu items
2059 int current
2061 is the index of the currently-selected item
2062 char * newtext
2064 is the updated text for the menu item
2065 dlg_dump_keys
2067 Write all user-defined key-bindings to the given stream, e.g., as
2068 part of dlg_create_rc.
2069 FILE * fp
2071 is the stream on which to write the bindings.
2072 dlg_dump_window_keys
2074 Write all user-defined key-bindings to the given stream, e.g., as
2075 part of dlg_create_rc.
2076 FILE * fp
2078 is the stream on which to write the bindings.
2079 WINDOW * win
2081 is the window for which bindings should be dumped. If it is
2082 null, then only built-in bindings are dumped.
2083 dlg_eat_argv
2085 Remove one or more items from an argument vector.
2086 int *argcp
2088 in/out parameter giving the length of the argument vector.
2089 char ***argvp in/out parameter pointing to the argument vec‐
2090 tor. int start starting index. int count number of argu‐
2091 ments to remove.
2092 dlg_edit_offset
2094 Given the character-offset in the string, returns the display-off‐
2095 set where dialog should position the cursor. In this context,
2096 "characters" may be multicolumn, since the string can be a multi‐
2097 byte character string.
2098 char * string
2100 is the string to analyze
2101 int offset
2103 is the character-offset
2104 int x_last
2106 is a limit on the column positions that can be used, e.g.,
2107 the window's size.
2108 dlg_edit_string
2110 Updates the string and character-offset, given various editing
2111 characters or literal characters which are inserted at the charac‐
2112 ter-offset. Returns true if an editing change was made (and the
2113 display should be updated), and false if the key was something
2114 like KEY_ENTER, which is a non-editing action outside this func‐
2115 tion.
2116 char * string
2118 is the (multibyte) string to update
2119 int * offset
2121 is the character-offset
2122 int key
2124 is the editing key
2125 int fkey
2127 is true if the editing key is a function-key
2128 bool force
2130 is used in a special loop case by calling code to force the
2131 return value of this function when a function-key code 0 is
2132 passed in.
2133 dlg_exit
2135 Given an internal exit code, check if the corresponding environ‐
2136 ment variable is set. If so, remap the exit code to match the
2137 environment variable. Finally call exit with the resulting exit
2138 code.
2139 int code
2141 is the internal exit code, e.g., DLG_EXIT_OK, which may be
2142 remapped.
2143 The dialog program uses this function to allow shell scripts to
2145 remap the exit codes so they can distinguish ESC from ERROR.
2146 dlg_exit_buttoncode
2148 Map the given button index for dlg_exit_label into dialog's exit-
2149 code.
2150 int button
2152 is the button index
2153 dlg_exit_label
2155 Return a list of button labels. If dialog_var.extra_button is
2156 true, return the result of dlg_ok_labels. Otherwise, return a
2157 list with the "Exit" label and (if dialog_vars.help_button is set)
2158 the "Help" button as well.
2159 dlg_exiterr
2161 Quit program killing all tailboxbg widgets.
2162 const char * fmt
2164 is the format of the printf-like message to write.
2165 ...
2167 are the variables to apply to the fmt format.
2168 dlg_find_index
2170 Given the character-offset to find in the list, return the corre‐
2171 sponding array index.
2172 const int *list
2174 contains a list of character-offsets, i.e., indices into a
2175 string that denote the beginning of multibyte characters.
2176 int limit
2178 is the last index into list to search.
2179 int to_find
2181 is the character-offset to find.
2182 dlg_flush_getc
2184 Cancel the local data saved by dlg_last_getc.
2185 dlg_editbox
2187 This entrypoint provides the --editbox functionality without the
2188 limitations of dialog's command-line syntax (compare to dia‐
2189 log_editbox).
2190 const char * title
2192 is the title string to display at the top of the widget.
2193 char *** list
2195 is a pointer to an array of char * pointers. The array is
2196 allocated by the caller, and so are the strings to which it
2197 points. The dlg_editbox function may reallocate the array
2198 and the strings.
2199 int * rows
2201 points to the nominal length of list. The referenced value
2202 is updated iflist is reallocated.
2203 int height
2205 is the desired height of the box. If zero, the height is
2206 adjusted to use the available screen size.
2207 int width
2209 is the desired width of the box. If zero, the height is
2210 adjusted to use the available screen size.
2211 dlg_form
2213 This entrypoint provides the --form functionality without the lim‐
2214 itations of dialog's command-line syntax (compare to dialog_form).
2215 const char * title
2217 is the title string to display at the top of the widget.
2218 const char * cprompt
2220 is the prompt text shown within the widget.
2221 int height
2223 is the desired height of the box. If zero, the height is
2224 adjusted to use the available screen size.
2225 int width
2227 is the desired width of the box. If zero, the height is
2228 adjusted to use the available screen size.
2229 int form_height
2231 is the minimum height to reserve for displaying the list. If
2232 zero, it is computed based on the given height and width.
2233 int item_no
2235 is the number of items.
2236 DIALOG_FORMITEM * items
2238 This is a list of the items to display in the form.
2239 int * current_item
2241 The widget sets the referenced location to the index of the
2242 current display item (cursor) when it returns.
2243 dlg_free_columns
2245 Free data allocated by dlg_align_columns.
2246 char **target
2248 This is the array which was reformatted. It points to the
2249 first string to free.
2250 int per_row
2252 This is the size of the struct for each row of the array.
2253 int num_rows
2255 This is the number of rows in the array.
2256 dlg_free_formitems
2258 Free memory owned by a list of DIALOG_FORMITEM's.
2259 DIALOG_FORMITEM * items
2261 is the list to free.
2262 dlg_free_gauge
2264 Remove the gauge widget from the screen and free its associated
2265 memory.
2266 void *objptr
2268 points to the gauge widget.
2269 dlg_getc
2271 Read a character from the given window. Handle repainting here
2272 (to simplify things in the calling application). Also, if input-
2273 callback(s) are set up, poll the corresponding files and handle
2274 the updates, e.g., for displaying a tailbox. Returns the key-
2275 code.
2276 WINDOW * win
2278 is the window within which to read.
2279 int * fkey
2281 as a side-effect, set this to true if the key-code is really
2282 a function-key.
2283 dlg_get_attrs
2285 extract the video attributes from the given window.
2286 WINDOW * win
2288 is the window from which to get attributes.
2289 dlg_getc_callbacks
2291 passes the given key-code ch to the current window that has estab‐
2292 lished a callback. If the callback returns zero, remove it and
2293 try the next window. If no more callbacks remain, return. If any
2294 callbacks were found, return true, otherwise false.
2295 int ch
2297 is the key-code
2298 int fkey
2300 is true if the key is a function-key
2301 int * result
2303 is used to pass an exit-code to the caller, which should pass
2304 that via dlg_exit.
2305 dlg_index_columns
2307 Build a list of the display-columns for the given multibyte
2308 string's characters.
2309 const char * string
2311 is the string to analyze
2312 dlg_index_wchars
2314 Build an index of the wide-characters in the string, so the caller
2315 can easily tell which byte-offset begins a given wide-character.
2316 const char * string
2318 is the string to analyze
2319 dlg_item_help
2321 Draw the string for the dialog_vars.item_help feature.
2322 const char * txt
2324 is the help-message
2325 dlg_killall_bg
2327 If dialog has callbacks active, purge the list of all that are not
2328 marked to keep in the background. If any remain, run those in a
2329 background process.
2330 int * retval
2332 stores the exit-code to pass back to the caller.
2333 dlg_last_getc
2335 returns the most recent character that was read via dlg_getc.
2336 dlg_limit_columns
2338 Given a column limit, count the number of wide characters that can
2339 fit into that limit. The offset is used to skip over a leading
2340 character that was already written.
2341 const char * string
2343 is the string to analyze
2344 int limit
2346 is the column limit
2347 int offset
2349 is the starting offset from which analysis should continue
2350 dlg_lookup_key
2352 Check for a key-binding. If there is no binding associated with
2353 the widget, it simply returns the given curses-key. Otherwise, it
2354 returns the result of the binding
2355 WINDOW * win
2357 is the window on which the binding is checked
2358 int curses_key
2360 is the curses key-code
2361 int * dialog_key
2363 is the corresponding dialog internal code (see DLG_KEYS_ENUM
2364 in dlg_key.h).
2365 dlg_max_input
2367 Limit the parameter according to dialog_vars.max_input
2368 int max_len
2370 is the value to limit
2371 dlg_match_char
2373 Match a given character against the beginning of the string,
2374 ignoring case of the given character. The matching string must
2375 begin with an uppercase character.
2376 int ch
2378 is the character to check
2379 const char * string
2381 is the string to search
2382 dlg_menu
2384 This entrypoint provides the --menu functionality without the lim‐
2385 itations of dialog's command-line syntax (compare to dialog_menu).
2386 const char * title
2388 is the title string to display at the top of the widget.
2389 const char * cprompt
2391 is the prompt text shown within the widget.
2392 int height
2394 is the desired height of the box. If zero, the height is
2395 adjusted to use the available screen size.
2396 int width
2398 is the desired width of the box. If zero, the height is
2399 adjusted to use the available screen size.
2400 int menu_height
2402 is the minimum height to reserve for displaying the list. If
2403 zero, it is computed based on the given height and width.
2404 int item_no
2406 is the number of items.
2407 DIALOG_LISTITEM * items
2409 This is a list of the items to display in the form.
2410 int * current_item
2412 The widget sets the referenced location to the index of the
2413 current display item (cursor) when it returns.
2414 DIALOG_INPUTMENU rename_menutext
2416 If this is not dlg_dummy_menutext, the widget acts like an
2417 inputmenu widget, providing an extra "Rename" button, which
2418 activates an edit feature on the selected menu item.
2419 dlg_move_window
2421 Moves/resizes the given window to the given position and size.
2422 WINDOW *win
2424 is the window to move/resize.
2425 WINDOW *height
2427 is the height of the resized window.
2428 WINDOW *width
2430 is the width of the resized window.
2431 WINDOW *y
2433 y-ordinate to use for the repositioned window.
2434 WINDOW *x
2436 x-ordinate to use for the repositioned window.
2437 dlg_mouse_bigregion
2439 Retrieve the big-region under the pointer.
2440 int y
2442 is the row on which the mouse click occurred
2443 int x
2445 is the column on which the mouse click occurred
2446 dlg_mouse_free_regions
2448 Free the memory associated with mouse regions.
2449 dlg_mouse_mkbigregion
2451 Creates a region on which the mouse-clicks will return a specifed
2452 code.
2453 int y
2455 is the top-row of the region.
2456 int x
2458 is the left-column of the region.
2459 int height
2461 is the height of the region.
2462 int width
2464 is the width of the region.
2465 int code
2467 is a code used to make the region unique within a widget
2468 int step_x
2470 is used in modes 2 (columns) and 3 (cells) to determine the
2471 width of a column/cell.
2472 int step_y
2474 is currently unused
2475 int mode
2477 is used to determine how the mouse position is translated
2478 into a code (like a function-key):
2479 1 index by lines
2481 2 index by columns
2483 3 index by cells
2485 dlg_mouse_mkregion
2487 int y
2489 is the top-row of the region.
2490 int x
2492 is the left-column of the region.
2493 int height
2495 is the height of the region.
2496 int width
2498 is the width of the region.
2499 int code
2501 is a code used to make the region unique within a widget
2502 dlg_mouse_region
2504 Retrieve the frame under the mouse pointer
2505 int y
2507 is the row of the mouse-click
2508 int x
2510 is the column of the mouse-click
2511 dlg_mouse_setbase
2513 Sets a base for subsequent calls to dlg_mouse_mkregion, so they
2514 can make regions relative to the start of a given window.
2515 int x
2517 is the left-column for the base
2518 int y
2520 is the top-row for the base
2521 dlg_mouse_setcode
2523 Sets a value used internally by dlg_mouse_mkregion which is added
2524 to the code parameter. By providing different values, e.g., mul‐
2525 tiples of KEY_MAX, it is possible to support multiple "big"
2526 regions in a widget. The buildlist widget uses this feature to
2527 recognize mouse-clicks in the left/right panes.
2528 int code
2530 is the value to add to dlg_mouse_mkregion's code parameter.
2531 dlg_mouse_wgetch
2533 is a wrapper for dlg_getc which additionally maps mouse-clicks (if
2534 the curses library supports those) into extended function-keys
2535 which encode the position according to the mode in dlg_mouse_mkbi‐
2536 gregion. Returns the corresponding key-code.
2537 WINDOW * win
2539 is the window on which to perform the input
2540 int * fkey
2542 the referenced location is set to true if the key-code is an
2543 actual or extended (mouse) function-key.
2544 dlg_mouse_wgetch_nowait
2546 This is a non-blocking variant of dlg_mouse_wgetch.
2547 WINDOW * win
2549 is the window on which to perform the input
2550 int * fkey
2552 the referenced location is set to true if the key-code is an
2553 actual or extended (mouse) function-key.
2554 dlg_need_separator
2556 Check if an output-separator is needed. If dialog_vars.out‐
2557 put_separator is set, return true. Otherwise, if dia‐
2558 log_vars.input_result is nonempty, return true. If neither,
2559 return false.
2560 dlg_new_modal_window
2562 Create a modal window, optionally with a shadow. The shadow is
2563 created if dialog_state.use_shadow is true.
2564 WINDOW * parent
2566 is the parent window (usually the top-level window of a wid‐
2567 get)
2568 int height
2570 is the window's height
2571 int width
2573 is the window's width
2574 int y
2576 is the window's top-row
2577 int x
2579 is the window's left-column
2580 dlg_new_window
2582 Create a window, optionally with a shadow. The shadow is created
2583 if dialog_state.use_shadow is true.
2584 int height
2586 is the window's height
2587 int width
2589 is the window's width
2590 int y
2592 is the window's top-row
2593 int x
2595 is the window's left-column
2596 dlg_next_button
2598 Return the next index in the list of labels.
2599 const char ** labels
2601 is a list of (pointers to) button labels terminated by a null
2602 pointer.
2603 int button
2605 is the current button-index.
2606 dlg_next_ok_buttonindex
2608 Assuming that the caller is using dlg_ok_labels to list buttons,
2609 find the next index in the list of buttons.
2610 int current
2612 is the current index in the list of buttons
2613 int extra
2615 if negative, provides a way to enumerate extra active areas
2616 on the widget.
2617 dlg_ok_buttoncode
2619 Map the given button index for dlg_ok_labels into dialog's exit-
2620 code.
2621 int button
2623 is the button-index (which is not necessarily the same as the
2624 index in the list of labels).
2625 dlg_ok_label
2627 Returns a list with the "Ok" label, and if dialog_vars.help_button
2628 is true, the "Help" label as well.
2629 dlg_ok_labels
2631 Return a list of button labels for the OK/Cancel group of widgets.
2632 dlg_ordinate
2634 Decode the string as an integer, decrement if greater than zero to
2635 make a curses-ordinate from a dialog-ordinate.
2636 dlg_parse_bindkey
2638 Parse the parameters of the "bindkeys" configuration-file entry.
2639 This expects widget name which may be "*", followed by curses key
2640 definition and then dialog key definition.
2641 char * params
2643 is the parameter string to parse.
2644 dlg_parse_rc
2646 Parse the configuration file and set up variables.
2647 dlg_prev_button
2649 Return the previous index in the list of labels.
2650 const char ** labels
2652 is a list of (pointers to) button labels terminated by a null
2653 pointer.
2654 int button
2656 is the current button index
2657 dlg_print_listitem
2659 This is a helper function used for the various "list" widgets,
2660 e.g., checklist, menu, buildlist, treeview. Each list-widget has
2661 "tag" and "description" values for each item which can be dis‐
2662 played. If dialog_vars.no_tags is true, the "tag" value is not
2663 shown. The first character of the first value shown (tag or
2664 description) is highlighted to indicate that the widget will match
2665 it for quick navigation.
2666 WINDOW *win
2668 the window in which to display the text
2669 const char *text
2671 the value to display
2672 int climit
2674 the number of columns available for printing the text
2675 bool first
2677 true if this is the first call (for "tag" and "description"),
2678 and the first character of the value should be highlighted.
2679 int selected
2681 nonzero if the text should be displayed using the "selected"
2682 colors
2683 dlg_print_scrolled
2685 This is a wrapper for dlg_print_autowrap which allows the user to
2686 scroll too-long prompt text up/down.
2687 See dlg_check_scrolled for a function which updates the offset
2689 variable used as a parameter here. It complements this function;
2690 you need both. If pauseopt is set, this function returns an
2691 updated last parameter, needed for dlg_check_scrolled calls.
2692 WINDOW * win
2694 is the window to update.
2695 const char * prompt
2697 is the string to print
2698 int offset
2700 is the starting line-number to write wrapped text.
2701 int height
2703 is the available height for writing the wrapped text
2704 int width
2706 is the width that the wrapping should occur in
2707 int pauseopt
2709 is true if the extra functionality for scrolling should be
2710 enabled. If false, this calls dlg_print_autowrap without
2711 doing any scrolling.
2712 dlg_print_line
2714 Print one line of the prompt in the window within the limits of
2715 the specified right margin. The line will end on a word boundary
2716 and a pointer to the start of the next line is returned, or a NULL
2717 pointer if the end of *prompt is reached.
2718 WINDOW *win
2720 is the window to update.
2721 chtype *attr
2723 holds the starting attributes, and is updated to reflect the
2724 final attributes applied to the string.
2725 const char *prompt
2727 is the string to print
2728 int lm
2730 is the left margin.
2731 int rm
2733 is the right margin
2734 int *x
2736 returns the ending x-ordinate.
2737 dlg_prev_ok_buttonindex
2739 Find the previous button index in the list from dlg_ok_labels.
2740 int current
2742 is the current index
2743 int extra
2745 if negative provides a way to enumerate extra active areas on
2746 the widget.
2747 dlg_print_autowrap
2749 Print a string of text in a window, automatically wrap around to
2750 the next line if the string is too long to fit on one line. Note
2751 that the string may contain embedded newlines. The text is writ‐
2752 ten starting at the top of the window.
2753 WINDOW * win
2755 is the window to update.
2756 const char * prompt
2758 is the string to print
2759 int height
2761 is the nominal height the wrapped string is limited to
2762 int width
2764 is the width that the wrapping should occur in
2765 dlg_print_size
2767 If dialog_vars.print_siz is true, print the given height/width
2768 (from a widget) to dialog_state.output, e.g., Size: height, width.
2769 int height
2771 is the window's height
2772 int width
2774 is the window's width
2775 dlg_print_text
2777 Print up to cols columns from text, optionally rendering dialog's
2778 escape sequences for attributes and color.
2779 WINDOW * win
2781 is the window to update.
2782 const char * txt
2784 is the string to print
2785 int col
2787 is the column limit
2788 chtype * attr
2790 holds the starting attributes, and is updated to reflect the
2791 final attributes applied to the string.
2792 dlg_progressbox implements the "--prgbox" and "--progressbox" options.
2793 const char * title
2795 is the title on the top of the widget.
2796 const char * cprompt
2798 is the prompt text shown within the widget. If empty or
2799 null, no prompt is shown.
2800 int height
2802 is the desired height of the box. If zero, the height is
2803 based on the screen size.
2804 int width
2806 is the desired width of the box. If zero, the height is
2807 based on the screen size.
2808 int pauseopt
2810 if true, an "OK" button will be shown, and the dialog will
2811 wait for it to complete. With an "OK" button, it is denoted
2812 a "programbox", without an "OK" button, it is denoted a "pro‐
2813 gressbox".
2814 FILE * fp
2816 is the file pointer, which may be a pipe or a regular file.
2817 dlg_put_backtitle
2819 Display the background title if dialog_vars.backtitle is non-null.
2820 The background title is shown at the top of the screen.
2821 dlg_register_buttons
2823 The widget developer should call this function after dlg_regis‐
2824 ter_window, for the list of button labels associated with the wid‐
2825 get. One may bind a key to a button, e.g., "OK" for DLGK_OK,
2826 WINDOW * win
2828 is the window with which to associate the buttons
2829 const char * name
2831 is the widget's binding name (usually the name of the wid‐
2832 get).
2833 const char ** buttons
2835 is the list of buttons
2836 dlg_register_window
2838 For a given named widget's window, associate a binding table.
2839 WINDOW * win
2841 is the window with which to associate the buttons
2842 const char * name
2844 is the widget's binding name (usually the name of the wid‐
2845 get).
2846 DLG_KEYS_BINDING * binding
2848 is the binding table
2849 dlg_remove_callback
2851 Remove a callback.
2852 DIALOG_CALLBACK * p
2854 contains the callback information.
2855 dlg_renamed_menutext
2857 This is a utility function which supports the --inputmenu option
2858 of the dialog program. If dialog_vars.input_menu is set, dia‐
2859 log_menu passes this pointer to dlg_menu as the rename_menutext
2860 parameter. Otherwise, it passes dlg_dummy_menutext.
2861 The function should add "RENAMED" to dialog_vars.input_result ,
2863 followed by the menu item's name and the newtext value (with a
2864 space separating the three items), and return DLG_EXIT_EXTRA.
2865 DIALOG_LISTITEM * items
2867 is the list of menu items
2868 int current
2870 is the index of the currently-selected item
2871 char * newtext
2873 is the updated text for the menu item
2874 dlg_restore_vars
2876 Restore dialog's variables from the given variable (see dia‐
2877 log_save_vars).
2878 DIALOG_VARS * save
2880 is the variable from which to restore.
2881 The DIALOG_VARS.input_length and DIALOG_VARS.input_result members
2883 are treated specially, since these are used by a widget to pass
2884 data to the caller. They are not modified by this function.
2885 dlg_result_key
2887 Test a dialog internal keycode to see if it corresponds to one of
2888 the push buttons on the widget such as "OK". This is only useful
2889 if there are user-defined key bindings, since there are no built-
2890 in bindings that map directly to DLGK_OK, etc. Return true if a
2891 mapping was done.
2892 int dialog_key
2894 is the dialog key to test
2895 int fkey
2897 is true if this is a function key
2898 int * resultp
2900 store the result of the mapping in the referenced location.
2901 dlg_save_vars
2903 Save dialog's variables into the given variable (see
2904 dlg_restore_vars).
2905 DIALOG_VARS * save
2907 is the variable into which to save.
2908 dlg_set_focus
2910 Set focus on the given window, making it display above other win‐
2911 dows on the screen.
2912 WINDOW * parent
2914 is the parent window (usually the top-level window of a wid‐
2915 get)
2916 WINDOW * win
2918 is the window on which to place focus (usually a subwindow of
2919 a widget)
2920 dlg_set_result
2922 Setup a fixed-buffer for the result in dialog_vars.input_result
2923 const char * string
2925 is the new contents for the result
2926 dlg_show_string
2928 Displays the string, shifted as necessary, to fit within the box
2929 and show the current character-offset.
2930 WINDOW * win
2932 is the window within which to display
2933 const char * string
2935 is the string to display
2936 int offset
2938 is the starting (character, not bytes) offset
2939 chtype attr
2941 is the window attribute to use for the string
2942 int y_base
2944 beginning row on screen
2945 int x_base
2947 beginning column on screen
2948 int x_last
2950 number of columns on screen
2951 bool hidden
2953 if true, do not echo input
2954 bool force
2956 if true, force repaint
2957 dlg_strclone
2959 duplicate the string, like strdup.
2960 const char * cprompt
2962 is the string to duplicate
2963 dlg_strcmp
2965 compare two strings, ignoring case.
2966 const char * a
2968 is one string
2969 const char * b
2971 is the other string
2972 dlg_string_to_argv
2974 Convert a string to an argument vector returning an index (which
2975 must be freed by the caller). The string is modified (replacing
2976 gaps between tokens with nulls).
2977 char *blob
2979 is the string to convert.
2980 dlg_sub_window
2982 create a subwindow, e.g., for an input area of a widget
2983 WINDOW * win
2985 is the parent window
2986 int height
2988 is the subwindow's height
2989 int width
2991 is the subwindow's width
2992 int y
2994 is the subwindow's top-row
2995 int x
2997 is the subwindow's left-column
2998 dlg_tab_correct_str
3000 If the dialog_vars.tab_correct is true, convert tabs to single
3001 spaces. Return the converted result. The caller is responsible
3002 for freeing the string.
3003 char * prompt
3005 is the string to convert
3006 dlg_trace
3008 If the parameter is non-null, opens a trace file with that name
3009 and stores the file pointer in dialog_state.trace.
3010 dlg_trace_chr
3012 If dialog_state.trace is set, translate the parameters into a
3013 printable representation, log it on a "chr" line.
3014 int ch
3016 is the nominal keycode value.
3017 int fkey
3019 is nonzero if the value is really a function key. Some of
3020 these may be values declared in the DLG_KEYS_ENUM.
3021 dlg_trace_msg
3023 Write a formatted message to the trace file.
3024 const char * fmt
3026 is the format of the printf-like message to write.
3027 ...
3029 are the variables to apply to the fmt format.
3030 Use the DLG_TRACE macro for portability, in case the trace feature
3032 is not compiled into the library. It uses an extra level of
3033 parentheses to work with a variable number of parameters, e.g.,
3034 DLG_TRACE(("this is dialog version %s\n", dialog_version()));
3036 dlg_trace_win
3038 If dialog_state.trace is set, log a printable picture of the given
3039 window.
3040 dlg_treeview
3042 This is an alternate interface to 'treeview' which allows the
3043 application to read the list item states back directly without
3044 putting them in the output buffer.
3045 const char * title
3047 is the title on the top of the widget.
3048 const char * cprompt
3050 is the prompt text shown within the widget.
3051 int height
3053 is the desired height of the box. If zero, the height is
3054 based on the screen size.
3055 int width
3057 is the desired width of the box. If zero, the height is
3058 based on the screen size.
3059 int list_height
3061 is the minimum height to reserve for displaying the list. If
3062 zero, it is computed based on the given height and width.
3063 int item_no
3065 is the number of rows in items.
3066 DIALOG_LISTITEM * items
3068 is the list of items, contain tag, name, and optionally help
3069 strings (if dialog_vars.item_help is set). The initial
3070 selection state for each item is also in this list.
3071 const char * states
3073 This is a list of characters to display for the given states.
3074 Normally a buildlist provides true (1) and false (0) values,
3075 which the widget displays as "*" and space, respectively. An
3076 application may set this parameter to an arbitrary null-ter‐
3077 minated string. The widget determines the number of states
3078 from the length of this string, and will cycle through the
3079 corresponding display characters as the user presses the
3080 space-bar.
3081 int * depths
3083 This is a list of depths of each item in the tree. It is a
3084 separate parameter from items to allow reuse of the existing
3085 functions.
3086 int flag
3088 is either FLAG_CHECK, for checklists (multiple selections),
3089 or FLAG_RADIO for radiolists (a single selection).
3090 int * current_item
3092 The widget sets the referenced location to the index of the
3093 current display item (cursor) when it returns.
3094 dlg_trim_string
3096 The dialog program uses this in each widget to adjust the message
3097 string, which may contain the newline character (referred to as
3098 '\n') and/or the special substring "\n" (which can be translated
3099 into a newline character).
3100 There are several optional features:
3102 · Unless dialog_vars.no_nl_expand is set,
3104 · If it has "\n" substrings, the function preserves extra
3106 spaces. For instance, spaces following a newline (sub‐
3107 string or character) are preserved to use as an indenta‐
3108 tion.
3109 · The function changes embedded "\n" substrings to '\n'
3111 characters.
3112 · If dialog_vars.no_nl_expand is not set, or if there are no
3114 "\n" substrings, this function strips all extra spaces to sim‐
3115 plify justification.
3116 · If dialog_vars.cr_wrap is set, the function preserves '\n'
3118 newline characters. Otherwise, each '\n' newline character is
3119 converted to a space.
3120 · Unless dialog_vars.nocollapse is set, each tab character is
3122 converted to a space, and sequences of blanks (space or tab)
3123 are reduced to a single space.
3124 char * src
3126 is the string to trim
3127 dlg_unregister_window
3129 Remove the bindings for a given window.
3130 WINDOW * win
3132 is the window from which to remove bindings
3133 dlg_update_gauge
3135 Update a gauge widget to show a different percentage value.
3136 void *objptr
3138 points to the gauge object to update.
3139 int percent
3141 is the new percentage value to display.
3142 dlg_yes_buttoncode
3144 Map the given button index for dlg_yes_labels into dialog's exit-
3145 code.
3146 int button
3148 is the button index
3149 dlg_yes_labels
3151 Return a list of buttons for Yes/No labels.
3152
3154 dialog (1).
3155
3157 Thomas E. Dickey
3158$Date: 2013/03/15 09:07:30 $ DIALOG(3)