contrib/dialog/dialog.3

   1 .\" $Id: dialog.3,v 1.68 2011/06/29 09:07:36 tom Exp $
   2 .\" Copyright 2005-2010,2011  Thomas E. Dickey
   3 .\"
   4 .\" This program is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU Lesser General Public License, version 2.1
   6 .\" as published by the Free Software Foundation.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful, but
   9 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 .\" Lesser General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU Lesser General Public
  14 .\" License along with this program; if not, write to
  15 .\"     Free Software Foundation, Inc.
  16 .\"     51 Franklin St., Fifth Floor
  17 .\"     Boston, MA 02110, USA.
  18 .\"
  19 .\" definitions for renaming
  20 .ds p dialog
  21 .ds l dialog
  22 .ds L Dialog
  23 .ds D DIALOG
  24 .
  25 .de ES
  26 .ne 8
  27 .IP
  28 ..
  29 .de EX
  30 .RS +10
  31 .nf
  32 ..
  33 .de EE
  34 .fi
  35 .RE
  36 ..
  37 .\" Bulleted paragraph
  38 .de bP
  39 .IP \(bu 4
  40 ..
  41 .TH \*D 3 "" "$Date: 2011/06/29 09:07:36 $"
  42 .SH NAME
  43 \*l \- widgets and utilities for the \*p program
  44 .SH SYNOPSIS
  45 .B cc [ flag ... ] file ...  -l\*l [ library ... ]
  46 .br
  47 \ \ \ or
  48 .br
  49 .B cc `\*p-config --cflags` file ... `\*p-config --libs` ]
  50 .sp
  51 .B #include <\*l.h>
  52 .PP
  53 \fB\*L\fP
  54 is a program that will let you to present a variety of questions or
  55 display messages using dialog boxes from a shell script.
  56 It is built from the \fB\*l\fP library,
  57 which consists of several widgets
  58 as well as utility functions that are used by the widgets
  59 or the main program.
  60 .
  61 .SH DESCRIPTION
  62 This manpage documents the features from \fI<\*l.h>\fP which
  63 are likely to be important to developers using the widgets directly.
  64 Some hints are also given for developing new widgets.
  65 .
  66 .\" ************************************************************************
  67 .SH DEFINITIONS
  68 Exit codes (passed back to the main program for its use)
  69 are defined with a "\fIDLG_EXIT_\fP prefix.
  70 The defined constants can be mapped using environment variables
  71 as described in \fB\*p\fP(1),
  72 e.g., \fIDLG_EXIT_OK\fP corresponds to \fI$DIALOG_OK\fP.
  73 .PP
  74 Useful character constants which correspond to user input
  75 are named with the "\fICHR_\fP" prefix, e.g.,
  76 \fICHR_BACKSPACE\fP.
  77 .PP
  78 Colors and video attributes are categorized and associated with
  79 settings in the configuration file
  80 (see the discussion of \fI$DIALOGRC\fP in \fB\*p\fP(1)).
  81 The \fIDIALOG_ATR(n)\fP macro is used for defining the references
  82 to the combined color and attribute table \fBdlg_color_table[]\fP.
  83 .PP
  84 The \fB\*p\fP application passes its command-line parameters
  85 to the widget functions.  Some of those parameters are single values,
  86 but some of the widgets accept data as an array of values.
  87 Those include checklist/radiobox, menubox and formbox.
  88 When the \fB--item-help\fP option is given, an extra column
  89 of data is expected.
  90 The USE_ITEM_HELP(), CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS
  91 macros are used to hide this difference from the calling application.
  92 .PP
  93 Most of the other definitions found in \fI<\*l.h>\fP
  94 are used for convenience in building the library or main program.
  95 These include definitions based on the generated \fI<dlg_config.h>\fP header.
  96
  97 .\" ************************************************************************
  98 .SH DATA STRUCTURES
  99 All of the global data for the \fB\*l\fP library is stored in
 100 a few structures: \fIDIALOG_STATE\fP, \fIDIALOG_VARS\fP and \fIDIALOG_COLORS\fP.
 101 The corresponding \fBdialog_state\fP, \fBdialog_vars\fP and \fBdlg_color_table\fP
 102 global variables should be initialized to zeros,
 103 and then populated with the data to use.
 104 A few of these must be nonzero for the corresponding widgets to function.
 105 As as the case with function names,
 106 variables beginning with "\fIdialog_\fP"
 107 are designed for use by the calling application
 108 while variables beginning with "\fIdlg_\fP"
 109 are intended for lower levels, e.g., by the \fB\*l\fP library.
 110 .\" ---------------------------------------------------------------------------
 111 .IP \fIDIALOG_STATE.all_windows
 112 This is a linked list of all windows created by the library.
 113 The \fBdlg_del_window\fP function uses this to locate windows which
 114 may be redrawn after deleting a window.
 115 .\" ---------------------------------------------------------------------------
 116 .IP \fIDIALOG_STATE.aspect_ratio
 117 This corresponds to the command-line option "\fB--aspect-ratio\fP".
 118 The value gives the application
 119 some control over the box dimensions when using auto
 120 sizing (specifying 0 for height and width).
 121 It represents width / height.
 122 The default is 9, which means 9 characters wide to every 1 line high.
 123 .\" ---------------------------------------------------------------------------
 124 .IP \fIDIALOG_STATE.getc_callbacks
 125 This is setup in \fIui_getc.c\fP to record windows which must be polled
 126 for input, e.g,. to handle the background tailbox widget.
 127 One window is designated as the foreground or control window.
 128 .\" ---------------------------------------------------------------------------
 129 .IP \fIDIALOG_STATE.getc_redirect
 130 If the control window for \fIDIALOG_STATE.getc_callbacks\fP is
 131 closed, the list is transferred to this variable.
 132 Closing all windows causes the application to exit.
 133 .\" ---------------------------------------------------------------------------
 134 .IP \fIDIALOG_STATE.no_mouse
 135 This corresponds to the command-line option "\fB--no-mouse\fP".
 136 If true, \fB\*p\fP will not initialize (and enable) the mouse in
 137 \fIinit_dialog\fP.
 138 .\" ---------------------------------------------------------------------------
 139 .IP \fIDIALOG_STATE.output
 140 This is set in the \fB\*p\fP application to the stream on
 141 which the application and library functions may write text results.
 142 Normally that is the standard error,
 143 since the curses library prefers to write its data to the standard output.
 144 Some scripts, trading portability for convenience,
 145 prefer to write results to the standard output,
 146 e.g., by using the "\fB--stdout\fP" option.
 147 .\" ---------------------------------------------------------------------------
 148 .IP \fIDIALOG_STATE.output_count
 149 This is incremented by \fBdlg_does_output\fP,
 150 which is called by each widget that writes text to the output.
 151 The \fB\*p\fP application uses that to decide if it should
 152 also write a separator, i.e.,
 153 \fIDIALOG_STATE.separate_str\fP,
 154 between calls to each widget.
 155 .\" ---------------------------------------------------------------------------
 156 .IP \fIDIALOG_STATE.pipe_input
 157 This is set in \fIinit_dialog\fP to a stream which can be used by the
 158 \fBgauge\fP widget, which must be the application's standard input.
 159 The \fB\*p\fP application calls \fIinit_dialog\fP normally with
 160 \fIinput\fP set to the standard input, but optionally based on the
 161 "\fB--input-fd\fP" option.
 162 Since the application cannot read from
 163 a pipe (standard input) and at the same time read
 164 the curses input from the standard input,
 165 it must allow for reopening the latter from either
 166 a specific file descriptor,
 167 or directly from the terminal.
 168 The adjusted pipe stream value is stored in this variable.
 169 .\" ---------------------------------------------------------------------------
 170 .IP \fIDIALOG_STATE.screen_initialized
 171 This is set in \fIinit_dialog\fP and
 172 reset in \fIend_dialog\fP.
 173 It is used to check if curses has been initialized,
 174 and if the \fIendwin\fP function must be called on exit.
 175 .\" ---------------------------------------------------------------------------
 176 .IP \fIDIALOG_STATE.screen_output
 177 This is set in \fIinit_dialog\fP to the output stream used
 178 by the curses library.
 179 Normally that is the standard output,
 180 unless that happens to not be a terminal (and if \fIinit_dialog\fP can
 181 successfully open the terminal directly).
 182 .\" ---------------------------------------------------------------------------
 183 .IP \fIDIALOG_STATE.separate_str
 184 This corresponds to the command-line option "\fB--separate-widget\fP".
 185 The given string
 186 specifies a string that will separate the output on \fB\*p\fP's output from
 187 each widget.
 188 This is used to simplify parsing the result of a dialog with several widgets.
 189 If this option is not given,
 190 the default separator string is a tab character.
 191 .\" ---------------------------------------------------------------------------
 192 .IP \fIDIALOG_STATE.tab_len
 193 This corresponds to the command-line option "\fB--tab-len\fP \fInumber\fP".
 194 Specify the number of spaces that a tab character occupies if the
 195 "\fB--tab-correct\fP"
 196 option is given.
 197 The default is 8.
 198 .\" ---------------------------------------------------------------------------
 199 .IP \fIDIALOG_STATE.trace_output
 200 This corresponds to the command-line option "\fB--trace\fP \fIfile\fP".
 201 It is the file pointer to which trace messages are written.
 202 .\" ---------------------------------------------------------------------------
 203 .IP \fIDIALOG_STATE.use_colors
 204 This is set in \fIinit_dialog\fP if the curses implementation supports color.
 205 .\" ---------------------------------------------------------------------------
 206 .IP \fIDIALOG_STATE.use_scrollbar
 207 This corresponds to the command-line option "\fB--scrollbar\fP".
 208 If true,
 209 draw a scrollbar to make windows holding scrolled data more readable.
 210 .\" ---------------------------------------------------------------------------
 211 .IP \fIDIALOG_STATE.use_shadow
 212 This corresponds to the command-line option "\fB--no-shadow\fP".
 213 This is set in \fIinit_dialog\fP if the curses implementation supports color.
 214 If true,
 215 suppress shadows that would be drawn to the right and bottom of each dialog box.
 216 .\" ---------------------------------------------------------------------------
 217 .IP \fIDIALOG_STATE.visit_items
 218 This corresponds to the command-line option "\fB--visit-items\fP".
 219 .\" ---------------------------------------------------------------------------
 220 .PP
 221 The \fB\*p\fP application resets the \fBdialog_vars\fP data before
 222 accepting options to invoke each widget.
 223 Most of the \fIDIALOG_VARS\fP members are set directly from \fB\*p\fP's
 224 command-line options:
 225 .\" ---------------------------------------------------------------------------
 226 .IP \fIDIALOG_VARS.ascii_lines
 227 This corresponds to the command-line option "\fB--ascii-lines\fP.
 228 It causes line-drawing to be done with ASCII characters, e.g., "+" and "-".
 229 See \fIDIALOG_VARS.no_lines\fP.
 230 .\" ---------------------------------------------------------------------------
 231 .IP \fIDIALOG_VARS.backtitle
 232 This corresponds to the command-line option "\fB--backtitle\fP \fIbacktitle\fP".
 233 It specifies a
 234 \fIbacktitle\fP
 235 string to be displayed on the backdrop, at the top of the screen.
 236 .\" ---------------------------------------------------------------------------
 237 .IP \fIDIALOG_VARS.beep_after_signal
 238 This corresponds to the command-line option "\fB--beep-after\fP".
 239 If true, beep after a user has completed a widget by pressing one of the buttons.
 240 .\" ---------------------------------------------------------------------------
 241 .IP \fIDIALOG_VARS.beep_signal
 242 This corresponds to the command-line option "\fB--beep\fP".
 243 It is obsolete.
 244 .\" ---------------------------------------------------------------------------
 245 .IP \fIDIALOG_VARS.begin_set
 246 This is true if the command-line option "\fB--begin y x\fP" was used.
 247 It specifies the position of the upper left corner of a dialog box on the screen.
 248 .\" ---------------------------------------------------------------------------
 249 .IP \fIDIALOG_VARS.begin_x
 250 This corresponds to the \fIx\fP value from
 251 the command-line option "\fB--begin\fP \fIy x\fP" (second value).
 252 .\" ---------------------------------------------------------------------------
 253 .IP \fIDIALOG_VARS.begin_y
 254 This corresponds to the \fIy\fP value from
 255 the command-line option "\fB--begin\fP \fIy x\fP" (first value).
 256 .\" ---------------------------------------------------------------------------
 257 .IP \fIDIALOG_VARS.cancel_label
 258 This corresponds to the command-line option "\fB--cancel-label\fP \fIstring\fP".
 259 The given \fIstring\fP overrides the label used for "Cancel" buttons.
 260 .\" ---------------------------------------------------------------------------
 261 .IP \fIDIALOG_VARS.cant_kill
 262 This corresponds to the command-line option "\fB--no-kill\fP".
 263 If true, this tells
 264 \fB\*p\fP
 265 to put the
 266 \fBtailboxbg\fP
 267 box in the background,
 268 printing its process id to \fB\*p\fP's output.
 269 SIGHUP is disabled for the background process.
 270 .\" ---------------------------------------------------------------------------
 271 .IP \fIDIALOG_VARS.colors
 272 This corresponds to the command-line option "\fB--colors\fP".
 273 If true, interpret embedded "\\Z" sequences in the dialog text
 274 by the following character,
 275 which tells \fB\*p\fP to set colors or video attributes:
 276 0 through 7 are the ANSI codes used in curses:
 277 black,
 278 red,
 279 green,
 280 yellow,
 281 blue,
 282 magenta,
 283 cyan and
 284 white respectively.
 285 Bold is set by 'b', reset by 'B'.
 286 Reverse is set by 'r', reset by 'R'.
 287 Underline is set by 'u', reset by 'U'.
 288 The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
 289 bright red.
 290 Restore normal settings with "\\Zn".
 291 .\" ---------------------------------------------------------------------------
 292 .IP \fIDIALOG_VARS.column_separator
 293 .\" ---------------------------------------------------------------------------
 294 .IP \fIDIALOG_VARS.cr_wrap
 295 This corresponds to the command-line option "\fB--cr-wrap\fP".
 296 If true,
 297 interpret embedded newlines in the dialog text as a newline on the screen.
 298 Otherwise, \fB\*p\fR will only wrap lines where needed to fit inside the text box.
 299 Even though you can control line breaks with this,
 300 \fB\*p\fR will still wrap any lines that are too long for the width of the box.
 301 Without cr-wrap, the layout of your text may be formatted to look nice
 302 in the source code of your script without affecting the way it will
 303 look in the dialog.
 304 .\" ---------------------------------------------------------------------------
 305 .IP \fIDIALOG_VARS.date_format
 306 This corresponds to the command-line option "\fB--date-format\fP \fIstring\fP".
 307 If the host provides \fBstrftime\fP, and the value is nonnull,
 308 the calendar widget uses this to format its output.
 309 .\" ---------------------------------------------------------------------------
 310 .IP \fIDIALOG_VARS.default_item
 311 This corresponds to the command-line option "\fB--default-item\fP \fIstring\fP".
 312 The given string is used as
 313 the default item in a checklist, form or menu box.
 314 Normally the first item in the box is the default.
 315 .IP \fIDIALOG_VARS.defaultno
 316 This corresponds to the command-line option "\fB--defaultno\fP".
 317 If true,
 318 make the default value of the
 319 \fByes/no\fP
 320 box a
 321 .BR No .
 322 Likewise, make the default button of widgets that provide "OK" and "Cancel"
 323 a \fBCancel\fP.
 324 If \fB--nocancel\fP was given that option overrides this,
 325 making the default button always "Yes" (internally the same as "OK").
 326 .\" ---------------------------------------------------------------------------
 327 .IP \fIDIALOG_VARS.dlg_clear_screen
 328 This corresponds to the command-line option "\fB--clear\fP".
 329 This option is implemented in the main program, not the library.
 330 If true,
 331 the screen will be cleared on exit.
 332 This may be used alone, without other options.
 333 .\" ---------------------------------------------------------------------------
 334 .IP \fIDIALOG_VARS.exit_label
 335 This corresponds to the command-line option "\fB--exit-label string\fP".
 336 The given string overrides the label used for "EXIT" buttons.
 337 .\" ---------------------------------------------------------------------------
 338 .IP \fIDIALOG_VARS.extra_button
 339 This corresponds to the command-line option "\fB--extra-button\fP".
 340 If true, some widgets show an extra button,
 341 between "OK" and "Cancel" buttons.
 342 .\" ---------------------------------------------------------------------------
 343 .IP \fIDIALOG_VARS.extra_label
 344 This corresponds to the command-line option "\fB--extra-label\fP \fIstring\fP".
 345 The given string overrides the label used for "Extra" buttons.
 346 Note: for inputmenu widgets, this defaults to "Rename".
 347 .\" ---------------------------------------------------------------------------
 348 .IP \fIDIALOG_VARS.formitem_type
 349 This is set by the command-line option "\fB--passwordform\fP"
 350 to tell the form widget that its text fields should be treated like
 351 password widgets.
 352 .\" ---------------------------------------------------------------------------
 353 .IP \fIDIALOG_VARS.help_button
 354 This corresponds to the command-line option "\fB--help-button\fP".
 355 If true, some widgets show a help-button after "OK" and "Cancel" buttons,
 356 i.e., in checklist, radiolist and menu boxes.
 357 If \fB--item-help\fR is also given, on exit
 358 the return status will be the same as for the "OK" button,
 359 and the item-help text will be written to \fB\*p\fP's output after the token "HELP".
 360 Otherwise, the return status will indicate that the Help button was pressed,
 361 and no message printed.
 362 .\" ---------------------------------------------------------------------------
 363 .IP \fIDIALOG_VARS.help_file
 364 This corresponds to the command-line option "\fB--hfile\fP \fIstring\fP".
 365 The given filename is passed to \fBdialog_helpfile\fP when the user
 366 presses F1.
 367 .\" ---------------------------------------------------------------------------
 368 .IP \fIDIALOG_VARS.help_label
 369 This corresponds to the command-line option "\fB--help-label\fP \fIstring\fP".
 370 The given string overrides the label used for "Help" buttons.
 371 .\" ---------------------------------------------------------------------------
 372 .IP \fIDIALOG_VARS.help_line
 373 This corresponds to the command-line option "\fB--hline\fP \fIstring\fP".
 374 The given string is displayed in the bottom of dialog windows,
 375 like a subtitle.
 376 .\" ---------------------------------------------------------------------------
 377 .IP \fIDIALOG_VARS.help_status
 378 This corresponds to the command-line option "\fB--help-status\fP".
 379 If true, and the the help-button is selected,
 380 writes the checklist or radiolist information
 381 after the item-help "HELP" information.
 382 This can be used to reconstruct the state of a checklist after processing
 383 the help request.
 384 .\" ---------------------------------------------------------------------------
 385 .IP \fIDIALOG_VARS.input_length
 386 This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated,
 387 versus being a pointer to the user's local variables.
 388 .\" ---------------------------------------------------------------------------
 389 .IP \fIDIALOG_VARS.input_menu
 390 This flag is set to denote whether the menubox widget
 391 implements a menu versus a inputmenu widget.
 392 .\" ---------------------------------------------------------------------------
 393 .IP \fIDIALOG_VARS.input_result
 394 This may be either a user-supplied buffer,
 395 or a buffer dynamically allocated by the library,
 396 depending on \fIDIALOG_VARS.input_length\fP:
 397 .RS
 398 .bP
 399 If \fIDIALOG_VARS.input_length\fP is zero,
 400 this is a pointer to user buffer (on the stack, or static).
 401 The buffer size is assumed to be \fBMAX_LEN\fP,
 402 which is defined in \fI<\*l.h>\fP.
 403 .bP
 404 When \fIDIALOG_VARS.input_length\fP is nonzero,
 405 this is a dynamically-allocated buffer used by the widgets to return
 406 printable results to the calling application.
 407 .RE
 408 .IP
 409 Certain widgets copy a result to this buffer.
 410 If the pointer is NULL, or if the length is insufficient for
 411 the result, then the \fB\*l\fP library allocates a buffer which is large enough,
 412 and sets \fIDIALOG_VARS.input_length\fP.
 413 Callers should check for this case if they have supplied their own buffer.
 414 .\" ---------------------------------------------------------------------------
 415 .IP \fIDIALOG_VARS.insecure
 416 This corresponds to the command-line option "\fB--insecure\fP".
 417 If true, make the password widget friendlier but less secure,
 418 by echoing asterisks for each character.
 419 .\" ---------------------------------------------------------------------------
 420 .IP \fIDIALOG_VARS.in_helpfile
 421 This variable is used to prevent \fBdialog_helpfile\fP from showing
 422 anything, e.g., if F1 were pressed within a help-file display.
 423 .\" ---------------------------------------------------------------------------
 424 .IP \fIDIALOG_VARS.item_help
 425 This corresponds to the command-line option "\fB--item-help\fP".
 426 If true,
 427 interpret the tags data for checklist, radiolist and menu boxes
 428 adding a column whose text is displayed in the bottom line of the
 429 screen, for the currently selected item.
 430 .\" ---------------------------------------------------------------------------
 431 .IP \fIDIALOG_VARS.keep_tite
 432 This is set by the command-line option "\fB--keep-tite\fP"
 433 to tell \fB\*p\fP to not attempt to cancel the terminal initialization
 434 (termcap \fIti\fP/\fIte\fP) sequences which correspond to xterm's alternate-screen
 435 switching.
 436 Normally \fB\*p\fP does this to avoid flickering when run several times
 437 in a script.
 438 .\" ---------------------------------------------------------------------------
 439 .IP \fIDIALOG_VARS.keep_window
 440 This corresponds to the command-line option "\fB--keep-window\fP".
 441 If true, do not remove/repaint the window on exit.
 442 This is useful for keeping the window contents visible when several
 443 widgets are run in the same process.
 444 Note that curses will clear the screen when starting a new process.
 445 .\" ---------------------------------------------------------------------------
 446 .IP \fIDIALOG_VARS.max_input
 447 This corresponds to the command-line option "\fB--max-input\fP \fIsize\fP".
 448 Limit input strings to the given size.
 449 If not specified, the limit is 2048.
 450 .\" ---------------------------------------------------------------------------
 451 .IP \fIDIALOG_VARS.no_label
 452 This corresponds to the command-line option "\fB--no-label\fP \fIstring\fP".
 453 The given string overrides the label used for "No" buttons.
 454 .\" ---------------------------------------------------------------------------
 455 .IP \fIDIALOG_VARS.no_lines
 456 This corresponds to the command-line option "\fB--no-lines\fP.
 457 It suppresses line-drawing.
 458 See \fIDIALOG_VARS.ascii_lines\fP.
 459 .\" ---------------------------------------------------------------------------
 460 .IP \fIDIALOG_VARS.no_nl_expand
 461 This corresponds to the command-line option "\fB--no-nl-expand\fP".
 462 If false, \fBdlg_trim_string\fP converts literal "\\n" substrings
 463 in a message into newlines.
 464 .\" ---------------------------------------------------------------------------
 465 .IP \fIDIALOG_VARS.nocancel
 466 This corresponds to the command-line option "\fB--no-cancel\fP".
 467 If true,
 468 suppress the "Cancel" button in checklist, inputbox and menu box modes.
 469 A script can still test if the user pressed the ESC key to cancel to quit.
 470 .\" ---------------------------------------------------------------------------
 471 .IP \fIDIALOG_VARS.nocollapse
 472 This corresponds to the command-line option "\fB--no-collapse\fP".
 473 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
 474 spaces to a single space for text which is displayed in a message boxes, etc.
 475 It true, that feature is disabled.
 476 Note that \fB\*p\fR will still wrap text, subject to the \fB--cr-wrap\fR
 477 option.
 478 .\" ---------------------------------------------------------------------------
 479 .IP \fIDIALOG_VARS.nook
 480 .\" ---------------------------------------------------------------------------
 481 .IP \fIDIALOG_VARS.ok_label
 482 This corresponds to the command-line option "\fB--ok-label\fP \fIstring\fP".
 483 The given string overrides the label used for "OK" buttons.
 484 .\" ---------------------------------------------------------------------------
 485 .IP \fIDIALOG_VARS.print_siz
 486 This corresponds to the command-line option "\fB--print-size\fP".
 487 If true,
 488 each widget prints its size to \fB\*p\fP's output when it is invoked.
 489 .\" ---------------------------------------------------------------------------
 490 .IP \fIDIALOG_VARS.quoted
 491 .\" ---------------------------------------------------------------------------
 492 .IP \fIDIALOG_VARS.separate_output
 493 This corresponds to the command-line option "\fB--separate-output\fP".
 494 If true,
 495 checklist widgets output result one line at a time, with no quoting.
 496 This facilitates parsing by another program.
 497 .\" ---------------------------------------------------------------------------
 498 .IP \fIDIALOG_VARS.single_quoted
 499 This corresponds to the command-line option "\fB--single-quoted\fP".
 500 If true,
 501 Use single-quoting as needed (and no quotes if unneeded) for the
 502 output of checklist's as well as the item-help text.
 503 If this option is not set, \fB\*p\fP uses double quotes around each item.
 504 That requires occasional use of backslashes to make the output useful in
 505 shell scripts.
 506 .IP \fIDIALOG_VARS.size_err
 507 This corresponds to the command-line option "\fB--size-err\fP".
 508 If true,
 509 check the resulting size of a dialog box before trying to use it,
 510 printing the resulting size if it is larger than the screen.
 511 (This option is obsolete, since all new-window calls are checked).
 512 .\" ---------------------------------------------------------------------------
 513 .IP \fIDIALOG_VARS.sleep_secs
 514 This corresponds to the command-line option "\fB--sleep\fP \fIsecs\fP".
 515 This option is implemented in the main program, not the library.
 516 If nonzero, this is the number of seconds after to delay after processing a dialog box.
 517 .\" ---------------------------------------------------------------------------
 518 .IP \fIDIALOG_VARS.tab_correct
 519 This corresponds to the command-line option "\fB--tab-correct\fP".
 520 If true, convert each tab character of the text to one or more spaces.
 521 Otherwise, tabs are rendered according to the curses library's interpretation.
 522 .\" ---------------------------------------------------------------------------
 523 .IP \fIDIALOG_VARS.time_format
 524 This corresponds to the command-line option "\fB--time-format\fP \fIstring\fP".
 525 If the host provides \fBstrftime\fP, and the value is nonnull,
 526 the timebox widget uses this to format its output.
 527 .\" ---------------------------------------------------------------------------
 528 .IP \fIDIALOG_VARS.timeout_secs
 529 This corresponds to the command-line option "\fB--timeout\fP \fIsecs\fP".
 530 If nonzero, timeout input requests (exit with error code)
 531 if no user response within the given number of seconds.
 532 .\" ---------------------------------------------------------------------------
 533 .IP \fIDIALOG_VARS.title
 534 This corresponds to the command-line option "\fB--title\fP \fItitle\fP".
 535 Specifies a
 536 \fItitle\fP
 537 string to be displayed at the top of the dialog box.
 538 .\" ---------------------------------------------------------------------------
 539 .IP \fIDIALOG_VARS.trim_whitespace
 540 This corresponds to the command-line option "\fB--trim\fP".
 541 If true, eliminate leading blanks,
 542 trim literal newlines and repeated blanks from message text.
 543 .\" ---------------------------------------------------------------------------
 544 .IP \fIDIALOG_VARS.visit_items
 545 This corresponds to the command-line option "\fB--visit-items\fP".
 546 Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
 547 to include the list of items as one of the states.
 548 This is useful as a visual aid,
 549 i.e., the cursor position helps some users.
 550 .\" ---------------------------------------------------------------------------
 551 .IP \fIDIALOG_VARS.yes_label
 552 This corresponds to the command-line option "\fB--yes-label\fP \fIstring\fP".
 553 The given string overrides the label used for "Yes" buttons.
 554 .
 555 .\" ************************************************************************
 556 .\" ************************************************************************
 557 .SH WIDGETS
 558 Functions that implement major functionality for the command-line \fB\*p\fP
 559 program, e.g., widgets, have names beginning "\fIdialog_\fP".
 560
 561 All dialog boxes have at least three parameters:
 562 .TP 5
 563 \fItitle\fP
 564 the caption for the box, shown on its top border.
 565 .TP 5
 566 \fIheight\fP
 567 the height of the dialog box.
 568 .TP 5
 569 \fIwidth\fP
 570 the width of the dialog box.
 571 .PP
 572 Other parameters depend on the box type.
 573 .
 574 .\" ************************************************************************
 575 .IP \fBdialog_calendar
 576 implements the "\fB--calendar\fP" option.
 577 .RS
 578 .TP 5
 579 .B const char * \fItitle
 580 is the title on the top of the widget.
 581 .TP 5
 582 .B const char * \fIsubtitle
 583 is the prompt text shown within the widget.
 584 .TP 5
 585 .B int \fIheight
 586 is the height excluding the fixed-height calendar grid.
 587 .TP 5
 588 .B int \fIwidth
 589 is the overall width of the box,
 590 which is adjusted up to the calendar grid's minimum width if needed.
 591 .TP 5
 592 .B int \fIday
 593 is the initial day of the week shown,
 594 counting zero as Sunday.
 595 If the value is negative, the current day of the week is used.
 596 .TP 5
 597 .B int \fImonth
 598 is the initial month of the year shown,
 599 counting one as January.
 600 If the value is negative, the current month of the year is used.
 601 .TP 5
 602 .B int \fIyear
 603 is the initial year shown.
 604 If the value is negative, the current year is used.
 605 .RE
 606 .\" ************************************************************************
 607 .IP \fBdialog_checklist
 608 implements the "\fB--checklist\fP" and "\fB--radiolist\fP" options
 609 depending on the \fIflag\fP parameter.
 610 .RS
 611 .TP 5
 612 .B const char * \fItitle
 613 is the title on the top of the widget.
 614 .TP 5
 615 .B const char * \fIcprompt
 616 is the prompt text shown within the widget.
 617 .TP 5
 618 .B int \fIheight
 619 is the desired height of the box.
 620 If zero, the height is adjusted to use the available screen size.
 621 .TP 5
 622 .B int \fIwidth
 623 is the desired width of the box.
 624 If zero, the height is adjusted to use the available screen size.
 625 .TP 5
 626 .B int \fIlist_height
 627 is the minimum height to reserve for displaying the list.
 628 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
 629 .TP 5
 630 .B int \fIitem_no
 631 is the number of rows in \fIitems\fP.
 632 .TP 5
 633 .B int \fIitems
 634 is an array of strings which is viewed either as a list of rows
 635 .RS
 636 \fItag item status \fR
 637 .RE
 638 .IP
 639 or
 640 .RS
 641 \fItag item status help\fR
 642 .RE
 643 .IP
 644 depending on whether \fBdialog_vars.item_help\fP is set.
 645 .IP flag
 646 is either \fIFLAG_CHECK\fP, for checklists,
 647 or \fIFLAG_RADIO\fP for radiolists.
 648 .RE
 649 .\" ************************************************************************
 650 .IP \fBdialog_dselect
 651 implements the "\fB--dselect\fP" option.
 652 .RS
 653 .TP 5
 654 .B const char * \fItitle
 655 is the title on the top of the widget.
 656 .TP 5
 657 .B const char * \fIpath
 658 is the preselected value to show in the input-box,
 659 which is used also to set the directory- and file-windows.
 660 .TP 5
 661 .B int \fIheight
 662 is the height excluding the minimum needed to show the dialog box framework.
 663 If zero, the height is based on the screen size.
 664 .TP 5
 665 .B int \fIwidth
 666 is the desired width of the box.
 667 If zero, the height is based on the screen size.
 668 .RE
 669 .\" ************************************************************************
 670 .IP \fBdialog_editbox
 671 implements the "\fB--editbox\fP" option.
 672 .RS
 673 .TP 5
 674 .B const char * \fItitle
 675 is the title on the top of the widget.
 676 .TP 5
 677 .B const char * \fIfile
 678 is the name of the file from which to read.
 679 .TP 5
 680 .B int \fIheight
 681 is the desired height of the box.
 682 If zero, the height is adjusted to use the available screen size.
 683 .TP 5
 684 .B int \fIwidth
 685 is the desired width of the box.
 686 If zero, the height is adjusted to use the available screen size.
 687 .RE
 688 .\" ************************************************************************
 689 .IP \fBdialog_form
 690 implements the "\fB--form\fP" option.
 691 .RS
 692 .TP 5
 693 .B const char * \fItitle
 694 is the title on the top of the widget.
 695 .TP 5
 696 .B const char * \fIcprompt
 697 is the prompt text shown within the widget.
 698 .TP 5
 699 .B int \fIheight
 700 is the desired height of the box.
 701 If zero, the height is adjusted to use the available screen size.
 702 .TP 5
 703 .B int \fIwidth
 704 is the desired width of the box.
 705 If zero, the height is adjusted to use the available screen size.
 706 .TP 5
 707 .B int \fIform_height
 708 is the minimum height to reserve for displaying the list.
 709 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
 710 .TP 5
 711 .B int \fIitem_no
 712 is the number of rows in \fIitems\fP.
 713 .TP 5
 714 .B int \fIitems
 715 is an array of strings which is viewed either as a list of rows
 716 .RS
 717 \fIName NameY NameX Text TextY TextX FLen ILen\fR
 718 .RE
 719 .IP
 720 or
 721 .RS
 722 \fIName NameY NameX Text TextY TextX FLen ILen Help\fR
 723 .RE
 724 .IP
 725 depending on whether \fBdialog_vars.item_help\fP is set.
 726 .RE
 727 .\" ************************************************************************
 728 .IP \fBdialog_fselect
 729 implements the "\fB--fselect\fP" option.
 730 .RS
 731 .TP 5
 732 .B const char * \fItitle
 733 is the title on the top of the widget.
 734 .TP 5
 735 .B const char * \fIpath
 736 is the preselected value to show in the input-box,
 737 which is used also to set the directory- and file-windows.
 738 .TP 5
 739 .B int \fIheight
 740 is the height excluding the minimum needed to show the dialog box framework.
 741 If zero, the height is based on the screen size.
 742 .TP 5
 743 .B int \fIwidth
 744 is the desired width of the box.
 745 If zero, the height is based on the screen size.
 746 .RE
 747 .\" ************************************************************************
 748 .IP \fBdialog_gauge
 749 implements the "\fB--gauge\fP" option.
 750 Alternatively, a simpler or customized gauge widget can be
 751 setup using
 752 \fBdlg_allocate_gauge\fP,
 753 \fBdlg_update_gauge\fP and
 754 \fBdlg_free_gauge\fP.
 755 .RS
 756 .TP 5
 757 .B const char * \fItitle
 758 is the title on the top of the widget.
 759 .TP 5
 760 .B const char * \fIcprompt
 761 is the prompt text shown within the widget.
 762 .TP 5
 763 .B int \fIheight
 764 is the desired height of the box.
 765 If zero, the height is based on the screen size.
 766 .TP 5
 767 .B int \fIwidth
 768 is the desired width of the box.
 769 If zero, the height is based on the screen size.
 770 .TP 5
 771 .B int \fIpercent
 772 is the percentage to show in the progress bar.
 773 .RE
 774 .\" ************************************************************************
 775 .IP \fBdialog_inputbox
 776 implements the "\fB--inputbox\fP" or
 777 "\fB--password\fP" option, depending on the value of \fIpassword\fP.
 778 .RS
 779 .TP 5
 780 .B const char * \fItitle
 781 is the title on the top of the widget.
 782 .TP 5
 783 .B const char * \fIcprompt
 784 is the prompt text shown within the widget.
 785 .TP 5
 786 .B int \fIheight
 787 is the desired height of the box.
 788 If zero, the height is based on the screen size.
 789 .TP 5
 790 .B int \fIwidth
 791 is the desired width of the box.
 792 If zero, the height is based on the screen size.
 793 .TP 5
 794 .B const char * \fIinit
 795 is the initial value of the input box, whose length is taken into account
 796 when auto-sizing the width of the dialog box.
 797 .TP 5
 798 .B int \fIpassword
 799 if true, causes typed input to be echoed as asterisks.
 800 .RE
 801 .\" ************************************************************************
 802 .IP \fBdialog_helpfile
 803 implements the "\fB--hfile\fP" option.
 804 .RS
 805 .TP 5
 806 .B const char * \fItitle
 807 is the title on the top of the widget.
 808 .TP 5
 809 .B const char * \fIfile
 810 is the name of a file containing the text to display.
 811 This function is internally bound to F1 (function key "1"),
 812 passing \fBdialog_vars.help_file\fP as a parameter.
 813 The \fBdialog\fP program sets that variable when the \fB--hfile\fP option
 814 is given.
 815 .TP 5
 816 .B int \fIheight
 817 is the desired height of the box.
 818 If zero, the height is based on the screen size.
 819 .TP 5
 820 .B int \fIwidth
 821 is the desired width of the box.
 822 If zero, the height is based on the screen size.
 823 .RE
 824 .\" ************************************************************************
 825 .IP \fBdialog_menu
 826 implements the "\fB--menu\fP" or "\fB--inputmenu\fP" option
 827 depending on whether \fBdialog_vars.input_menu\fP is set.
 828 .RS
 829 .TP 5
 830 .B const char * \fItitle
 831 is the title on the top of the widget.
 832 .TP 5
 833 .B const char * \fIcprompt
 834 is the prompt text shown within the widget.
 835 .TP 5
 836 .B int \fIheight
 837 is the desired height of the box.
 838 If zero, the height is based on the screen size.
 839 .TP 5
 840 .B int \fIwidth
 841 is the desired width of the box.
 842 If zero, the height is based on the screen size.
 843 .TP 5
 844 .B int \fImenu_height
 845 is the minimum height to reserve for displaying the list.
 846 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
 847 .TP 5
 848 .B int \fIitem_no
 849 is the number of rows in \fIitems\fP.
 850 .TP 5
 851 .B int \fIitems
 852 is an array of strings which is viewed either as a list of rows
 853 .RS
 854 \fItag item\fR
 855 .RE
 856 .IP
 857 or
 858 .RS
 859 \fItag item help\fR
 860 .RE
 861 .IP
 862 depending on whether \fBdialog_vars.item_help\fP is set.
 863 .RE
 864 .\" ************************************************************************
 865 .IP \fBdialog_mixedform
 866 implements the "\fB--mixedform\fP" option.
 867 .RS
 868 .TP 5
 869 .B const char * \fItitle
 870 is the title on the top of the widget.
 871 .TP 5
 872 .B const char * \fIcprompt
 873 is the prompt text shown within the widget.
 874 .TP 5
 875 .B int \fIheight
 876 is the desired height of the box.
 877 If zero, the height is adjusted to use the available screen size.
 878 .TP 5
 879 .B int \fIwidth
 880 is the desired width of the box.
 881 If zero, the height is adjusted to use the available screen size.
 882 .TP 5
 883 .B int \fIform_height
 884 is the minimum height to reserve for displaying the list.
 885 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
 886 .TP 5
 887 .B int \fIitem_no
 888 is the number of rows in \fIitems\fP.
 889 .TP 5
 890 .B int \fIitems
 891 is an array of strings which is viewed either as a list of rows
 892 .RS
 893 \fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR
 894 .RE
 895 .IP
 896 or
 897 .RS
 898 \fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR
 899 .RE
 900 .IP
 901 depending on whether \fBdialog_vars.item_help\fP is set.
 902 .RE
 903 .\" ************************************************************************
 904 .IP \fBdialog_mixedgauge
 905 implements the "\fB--mixedgauge\fP" option
 906 .RS
 907 .TP 5
 908 .B const char * \fItitle
 909 is the title on the top of the widget.
 910 .TP 5
 911 .B const char * \fIcprompt
 912 is the caption text shown within the widget.
 913 .TP 5
 914 .B int \fIheight
 915 is the desired height of the box.
 916 If zero, the height is based on the screen size.
 917 .TP 5
 918 .B int \fIwidth
 919 is the desired width of the box.
 920 If zero, the height is based on the screen size.
 921 .IP percent
 922 is the percentage to show in the progress bar.
 923 .TP 5
 924 .B int \fIitem_no
 925 is the number of rows in \fIitems\fP.
 926 .TP 5
 927 .B int \fIitems
 928 is an array of strings which is viewed as a list of \fItag\fP and \fIitem\fP values.
 929 The \fItag\fP values are listed, one per row, in the list at the top of
 930 the widget.
 931 .IP
 932 The \fIitem\fP values are decoded: digits 0-9 are the following strings
 933 .RS
 934 .IP 0
 935 Succeeded
 936 .IP 1
 937 Failed
 938 .IP 2
 939 Passed
 940 .IP 3
 941 Completed
 942 .IP 4
 943 Checked
 944 .IP 5
 945 Done
 946 .IP 6
 947 Skipped
 948 .IP 7
 949 In Progress
 950 .IP 8
 951 (blank)
 952 .IP 9
 953 N/A
 954 .RE
 955 .IP
 956 A string with a leading "-" character is centered, marked with "%".
 957 For example, "-75" is displayed as "75%".
 958 Other strings are displayed as is.
 959 .RE
 960 .\" ************************************************************************
 961 .IP \fBdialog_msgbox
 962 implements the "\fB--msgbox\fP" or "\fB--infobox\fP" option
 963 depending on whether \fIpauseopt\fP is set.
 964 .RS
 965 .TP 5
 966 .B const char * \fItitle
 967 is the title on the top of the widget.
 968 .TP 5
 969 .B const char * \fIcprompt
 970 is the prompt text shown within the widget.
 971 .TP 5
 972 .B int \fIheight
 973 is the desired height of the box.
 974 If zero, the height is based on the screen size.
 975 .TP 5
 976 .B int \fIwidth
 977 is the desired width of the box.
 978 If zero, the height is based on the screen size.
 979 .TP 5
 980 .B int \fIpauseopt
 981 if true, an "OK" button will be shown,
 982 and the dialog will wait for it to complete.
 983 With an "OK" button, it is denoted a "msgbox",
 984 without an "OK" button, it is denoted an "infobox".
 985 .RE
 986 .\" ************************************************************************
 987 .IP \fBdialog_pause
 988 implements the "\fB--pause\fP" option.
 989 .RS
 990 .TP 5
 991 .B const char * \fItitle
 992 is the title on the top of the widget.
 993 .TP 5
 994 .B int \fIheight
 995 is the desired height of the box.
 996 If zero, the height is based on the screen size.
 997 .TP 5
 998 .B int \fIwidth
 999 is the desired width of the box.
1000 If zero, the height is based on the screen size.
1001 .TP 5
1002 .B int \fIseconds
1003 is the timeout to use for the progress bar.
1004 .RE
1005 .\" ************************************************************************
1006 .IP \fBdialog_prgbox
1007 implements the "\fB--prgbox\fP" option.
1008 .RS
1009 .TP 5
1010 .B const char * \fItitle
1011 is the title on the top of the widget.
1012 .TP 5
1013 .B const char * \fIcprompt
1014 is the prompt text shown within the widget.
1015 If empty or null, no prompt is shown.
1016 .TP 5
1017 .B const char * \fIcommand
1018 is the name of the command to execute.
1019 .TP 5
1020 .B int \fIheight
1021 is the desired height of the box.
1022 If zero, the height is based on the screen size.
1023 .TP 5
1024 .B int \fIwidth
1025 is the desired width of the box.
1026 If zero, the height is based on the screen size.
1027 .TP 5
1028 .B int \fIpauseopt
1029 if true, an "OK" button will be shown,
1030 and the dialog will wait for it to complete.
1031 .RE
1032 .\" ************************************************************************
1033 .IP \fBdialog_progressbox
1034 implements the "\fB--progressbox\fP" option.
1035 .RS
1036 .TP 5
1037 .B const char * \fItitle
1038 is the title on the top of the widget.
1039 .TP 5
1040 .B const char * \fIcprompt
1041 is the prompt text shown within the widget.
1042 If empty or null, no prompt is shown.
1043 .TP 5
1044 .B int \fIheight
1045 is the desired height of the box.
1046 If zero, the height is based on the screen size.
1047 .TP 5
1048 .B int \fIwidth
1049 is the desired width of the box.
1050 If zero, the height is based on the screen size.
1051 .RE
1052 .\" ************************************************************************
1053 .IP \fBdialog_tailbox
1054 implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option
1055 depending on whether \fIbg_task\fP is set.
1056 .RS
1057 .TP 5
1058 .B const char * \fItitle
1059 is the title on the top of the widget.
1060 .TP 5
1061 .B const char * \fIfile
1062 is the name of the file to display in the dialog.
1063 .TP 5
1064 .B int \fIheight
1065 is the desired height of the box.
1066 If zero, the height is based on the screen size.
1067 .TP 5
1068 .B int \fIwidth
1069 is the desired width of the box.
1070 If zero, the height is based on the screen size.
1071 .TP 5
1072 .B int \fIbg_task
1073 if true,
1074 the window is added to the callback list in \fBdialog_state\fP,
1075 and the application will poll for the window to be updated.
1076 Otherwise an "OK" button is added to the window,
1077 and it will be closed when the button is activated.
1078 .RE
1079 .\" ************************************************************************
1080 .IP \fBdialog_textbox
1081 implements the "\fB--textbox\fP" option.
1082 .RS
1083 .TP 5
1084 .B const char * \fItitle
1085 is the title on the top of the widget.
1086 .TP 5
1087 .B const char * \fIfile
1088 is the name of the file to display in the dialog.
1089 .TP 5
1090 .B int \fIheight
1091 is the desired height of the box.
1092 If zero, the height is based on the screen size.
1093 .TP 5
1094 .B int \fIwidth
1095 is the desired width of the box.
1096 If zero, the height is based on the screen size.
1097 .RE
1098 .\" ************************************************************************
1099 .IP \fBdialog_timebox
1100 implements the "\fB--timebox\fP" option.
1101 .RS
1102 .TP 5
1103 .B const char * \fItitle
1104 is the title on the top of the widget.
1105 .TP 5
1106 .B const char * \fIsubtitle
1107 is the prompt text shown within the widget.
1108 .TP 5
1109 .B int \fIheight
1110 is the desired height of the box.
1111 If zero, the height is based on the screen size.
1112 .TP 5
1113 .B int \fIwidth
1114 is the desired width of the box.
1115 If zero, the height is based on the screen size.
1116 .TP 5
1117 .B int \fIhour
1118 is the initial hour shown.
1119 If the value is negative, the current hour is used.
1120 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24.
1121 .TP 5
1122 .B int \fIminute
1123 is the initial minute shown.
1124 If the value is negative, the current minute is used.
1125 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1126 .TP 5
1127 .B int \fIsecond
1128 is the initial second shown.
1129 If the value is negative, the current second is used.
1130 Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.
1131 .RE
1132 .\" ************************************************************************
1133 .IP \fBdialog_yesno
1134 implements the "\fB--yesno\fP" option.
1135 .RS
1136 .TP 5
1137 .B const char * \fItitle
1138 is the title on the top of the widget.
1139 .TP 5
1140 .B const char * \fIcprompt
1141 is the prompt text shown within the widget.
1142 .TP 5
1143 .B int \fIheight
1144 is the desired height of the box.
1145 If zero, the height is based on the screen size.
1146 .TP 5
1147 .B int \fIwidth
1148 is the desired width of the box.
1149 If zero, the height is based on the screen size.
1150 .RE
1151 .
1152 .\" ************************************************************************
1153 .SH UTILITY FUNCTIONS
1154 Most functions that implement lower-level
1155 functionality for the command-line \fB\*p\fP
1156 program or widgets, have names beginning "\fIdlg_\fP".
1157 Bowing to longstanding usage, the functions that initialize the
1158 display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP.
1159 .PP
1160 The only non-widget function whose name begins with "\fIdialog_\fP"
1161 is \fBdialog_version\fP, which returns the version number of the
1162 library as a string.
1163 .
1164 .PP
1165 Here is a brief summary of the utility functions and their parameters:
1166 .\" ---------------------------------------------------------------------------
1167 .TP 5
1168 .B dlg_add_callback
1169 Add a callback, used to allow polling input from multiple tailbox
1170 widgets.
1171 .RS
1172 .TP 5
1173 .B DIALOG_CALLBACK *\fIp\fP
1174 contains the callback information.
1175 .RE
1176 .\" ---------------------------------------------------------------------------
1177 .TP 5
1178 .B dlg_add_callback_ref
1179 Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP
1180 as well as a pointer to a cleanup function which will be called when the
1181 associated input ends.
1182 .RS
1183 .TP 5
1184 .B DIALOG_CALLBACK **\fIp\fP
1185 points to the callback information.
1186 This is a reference to the pointer so that the caller's pointer can be
1187 zeroed when input ends.
1188 .TP 5
1189 .B DIALOG_FREEBACK \fIfunc\fP
1190 function to call when input ends, e.g., to free caller's additional data.
1191 .RE
1192 .\" ---------------------------------------------------------------------------
1193 .TP 5
1194 .B dlg_add_quoted
1195 Add a quoted string to the result buffer (see \fBdlg_add_result\fP).
1196 .RS
1197 .TP 5
1198 .B char * \fIstring
1199 is the string to add.
1200 .RE
1201 .\" ---------------------------------------------------------------------------
1202 .TP 5
1203 .B dlg_add_result
1204 Add a quoted string to the result buffer \fBdialog_vars.input_result\fP.
1205 .RS
1206 .TP 5
1207 .B char * \fIstring
1208 is the string to add.
1209 .RE
1210 .\" ---------------------------------------------------------------------------
1211 .TP 5
1212 .B dlg_add_separator
1213 Add an output-separator to the result buffer \fBdialog_vars.input_result\fP.
1214 If \fBdialog_vars.output_separator\fP is set, use that.
1215 Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline.
1216 If neither is set, use a space.
1217 .\" ---------------------------------------------------------------------------
1218 .TP 5
1219 .B dlg_add_string
1220 Add a quoted or unquoted string to the result buffer
1221 (see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP),
1222 according to whether \fBdialog_vars.quoted\fP is true.
1223 .RS
1224 .TP 5
1225 .B char * \fIstring
1226 is the string to add.
1227 .RE
1228 .\" ---------------------------------------------------------------------------
1229 .TP 5
1230 .B dlg_align_columns
1231 Copy and reformat an array of pointers to strings, aligning according to
1232 the column separator \fBdialog_vars.column_separator\fP.
1233 If no column separator is set, the array will be unmodified;
1234 otherwise it is copied and reformatted.
1235 .IP
1236 Caveat: This function is only implemented for 8-bit characters.
1237 .RS
1238 .TP 5
1239 .B char **\fItarget
1240 This is the array to reformat.
1241 It points to the first string to modify.
1242 .TP 5
1243 .B int \fIper_row
1244 This is the size of the struct for each row of the array.
1245 .TP 5
1246 .B int \fInum_rows
1247 This is the number of rows in the array.
1248 .RE
1249 .\" ---------------------------------------------------------------------------
1250 .TP 5
1251 .B dlg_allocate_gauge
1252 Allocates a gauge widget.
1253 Use \fBdlg_update_gauge\fP to display the result.
1254 .RS
1255 .TP 5
1256 .B const char * \fItitle
1257 is the title string to display at the top of the widget.
1258 .TP 5
1259 .B const char * \fIcprompt
1260 is the prompt text shown within the widget.
1261 .TP 5
1262 .B int \fIheight
1263 is the desired height of the box.
1264 If zero, the height is adjusted to use the available screen size.
1265 .TP 5
1266 .B int \fIwidth
1267 is the desired width of the box.
1268 If zero, the height is adjusted to use the available screen size.
1269 .TP 5
1270 .B int \fIpercent
1271 is the percentage to show in the progress bar.
1272 .RE
1273 .\" ---------------------------------------------------------------------------
1274 .TP 5
1275 .B dlg_asciibox
1276 returns its parameter transformed to the
1277 corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP.
1278 If the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns 0.
1279 .RE
1280 .\" ---------------------------------------------------------------------------
1281 .TP 5
1282 .B dlg_attr_clear
1283 Set window to the given attribute.
1284 .RS
1285 .TP 5
1286 .B WINDOW * \fIwin
1287 is the window to update.
1288 .TP 5
1289 .B int \fIheight
1290 is the number of rows to update.
1291 .TP 5
1292 .B int \fIwidth
1293 is the number of columns to update.
1294 .TP 5
1295 .B chtype \fIattr
1296 is the attribute, e.g., \fBA_BOLD\fP.
1297 .RE
1298 .\" ---------------------------------------------------------------------------
1299 .TP 5
1300 .B dlg_auto_size
1301 Automatically size the window used for a widget.
1302 If the given height or width are zero,
1303 justify the \fIprompt\fP text and return the actual limits.
1304 .RS
1305 .TP 5
1306 .B const char * \fItitle
1307 is the title string to display at the top of the widget.
1308 .TP 5
1309 .B const char * \fIprompt
1310 is the message text which will be displayed in the widget,
1311 used here to determine how large the widget should be.
1312 .TP 5
1313 .B int * \fIheight
1314 is the nominal height.
1315 .TP 5
1316 .B int * \fIwidth
1317 is the nominal width.
1318 .TP 5
1319 .B int \fIboxlines
1320 is the number of lines to reserve in the vertical direction.
1321 .TP 5
1322 .B int \fImincols
1323 is the minimum number of columns to use.
1324 .RE
1325 .\" ---------------------------------------------------------------------------
1326 .TP 5
1327 .B dlg_auto_sizefile
1328 Like \fBdlg_auto_size\fP, but use a file contents to decide how large
1329 the widget should be.
1330 .RS
1331 .TP 5
1332 .B const char * \fItitle
1333 is the title string to display at the top of the widget.
1334 .TP 5
1335 .B const char * \fIfile
1336 is the name of the file.
1337 .TP 5
1338 .B int * \fIheight
1339 is the nominal height.
1340 If it is -1, use the screen's height after subtracting \fBdialog_vars.begin_y\fP
1341 if \fBdialog_vars.begin_set\fP is true.
1342 .TP 5
1343 .B int \fI*width
1344 is the nominal width.
1345 If it is -1, use the screen's width after subtracting \fBdialog_vars.begin_x\fP
1346 if \fBdialog_vars.begin_set\fP is true.
1347 .TP 5
1348 .B int \fIboxlines
1349 is the number of lines to reserve on the screen for drawing boxes.
1350 .TP 5
1351 .B int \fImincols
1352 is the number of columns to reserve on the screen for drawing boxes.
1353 .RE
1354 .\" ---------------------------------------------------------------------------
1355 .TP 5
1356 .B dlg_beeping
1357 If \fBdialog_vars.beep_signal\fP is nonzero,
1358 this calls \fBbeep\fP once and sets
1359 \fBdialog_vars.beep_signal\fP to zero.
1360 .\" ---------------------------------------------------------------------------
1361 .TP 5
1362 .B dlg_boxchar
1363 returns its parameter transformed as follows:
1364 .RS
1365 .TP 3
1366 .B -
1367 if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set.
1368 .TP 3
1369 .B -
1370 if \fBdialog_vars.ascii_lines\fP is set, returns the corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP.
1371 .TP 3
1372 .B -
1373 otherwise, if \fBdialog_vars.no_lines\fP is set, returns a space for the line-drawing characters.
1374 .TP 3
1375 .B -
1376 if the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns the parameter unchanged.
1377 .RE
1378 .\" ---------------------------------------------------------------------------
1379 .TP 5
1380 .B dlg_box_x_ordinate
1381 returns a suitable x-ordinate (column) for a new widget.
1382 If \fBdialog_vars.begin_set\fP is 1,
1383 use \fBdialog_vars.begin_x\fP;
1384 otherwise center the widget on the screen (using the \fIwidth\fP parameter).
1385 .RS
1386 .TP 5
1387 .B int \fIwidth
1388 is the width of the widget.
1389 .RE
1390 .\" ---------------------------------------------------------------------------
1391 .TP 5
1392 .B dlg_box_y_ordinate
1393 returns a suitable y-ordinate (row) for a new widget.
1394 If \fBdialog_vars.begin_set\fP is 1,
1395 use \fBdialog_vars.begin_y\fP;
1396 otherwise center the widget on the screen (using the \fIheight\fP parameter).
1397 .RS
1398 .TP 5
1399 .B int \fIheight
1400 is the height of the widget.
1401 .RE
1402 .\" ---------------------------------------------------------------------------
1403 .TP 5
1404 .B dlg_button_count
1405 Count the buttons in the list.
1406 .RS
1407 .TP 5
1408 .B const char ** \fIlabels
1409 is a list of (pointers to) button labels terminated by a null pointer.
1410 .RE
1411 .\" ---------------------------------------------------------------------------
1412 .TP 5
1413 .B dlg_button_layout
1414 Make sure there is enough space for the buttons by
1415 computing the width required for their labels,
1416 adding margins and limiting based on the screen size.
1417 .RS
1418 .TP 5
1419 .B const char ** \fIlabels
1420 is a list of (pointers to) button labels terminated by a null pointer.
1421 .TP 5
1422 .B int * \fIlimit
1423 the function sets the referenced \fIlimit\fP to the width required for
1424 the buttons (limited by the screen size)
1425 if that is wider than the passed-in limit.
1426 .RE
1427 .\" ---------------------------------------------------------------------------
1428 .TP 5
1429 .B dlg_button_sizes
1430 Compute the size of the button array in columns.
1431 .RS
1432 .TP 5
1433 .B const char ** \fIlabels
1434 is a list of (pointers to) button labels terminated by a null pointer.
1435 .TP 5
1436 .B int \fIvertical
1437 is true if the buttons are arranged in a column rather than a row.
1438 .TP 5
1439 .B int * \fIlongest
1440 Return the total number of columns in the referenced location.
1441 .TP 5
1442 .B int * \fIlength
1443 Return the longest button's columns in the referenced location.
1444 .RE
1445 .\" ---------------------------------------------------------------------------
1446 .TP 5
1447 .B dlg_button_x_step
1448 Compute the step-size needed between elements of the button array.
1449 .RS
1450 .TP 5
1451 .B const char ** \fIlabels
1452 is a list of (pointers to) button labels terminated by a null pointer.
1453 .TP 5
1454 .B int \fIlimit
1455 is the maximum number of columns to allow for the buttons.
1456 .TP 5
1457 .B int * \fIgap
1458 store the nominal gap between buttons in the referenced location.
1459 This is constrained to be at least one.
1460 .TP 5
1461 .B int * \fImargin
1462 store the left+right total margins (for the list of buttons) in the referenced
1463 location.
1464 .TP 5
1465 .B int * \fIstep
1466 store the step-size in the referenced location.
1467 .RE
1468 .\" ---------------------------------------------------------------------------
1469 .TP 5
1470 .B dlg_button_to_char
1471 Find the first uppercase character in the label, which we may use for an
1472 abbreviation.
1473 If the label is empty, return -1.
1474 If no uppercase character is found, return 0.
1475 Otherwise return the uppercase character.
1476 .RS
1477 .TP 5
1478 .B const char * \fIlabel
1479 is the label to test.
1480 .RE
1481 .\" ---------------------------------------------------------------------------
1482 .TP 5
1483 .B dlg_calc_list_width
1484 Calculate the minimum width for the list, assuming none of the items
1485 are truncated.
1486 .RS
1487 .TP 5
1488 .B int \fIitem_no
1489 is the number of \fIitems\fP.
1490 .TP 5
1491 .B DIALOG_LISTITEM * \fIitems
1492 contains a \fIname\fP and \fItext\fP field,
1493 e.g., for checklists or radiobox lists.
1494 The function returns the sum of the widest columns
1495 needed for of each of these fields.
1496 .RE
1497 .\" ---------------------------------------------------------------------------
1498 .TP 5
1499 .B dlg_calc_listh
1500 Calculate new height and list_height values.
1501 .RS
1502 .TP 5
1503 .B int * \fIheight
1504 on input, is the height without adding the list-height.
1505 On return, this contains the total list-height and is the
1506 actual widget's height.
1507 .TP 5
1508 .B int * \fIlist_height
1509 on input, is the requested list-height.
1510 On return, this contains the number of rows available for displaying
1511 the list after taking into account the screen size and
1512 the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables.
1513 .TP 5
1514 .B int \fIitem_no
1515 is the number of \fIitems\fP in the list.
1516 .RE
1517 .\" ---------------------------------------------------------------------------
1518 .TP 5
1519 .B dlg_calc_listw
1520 This function is obsolete, provided for library-compatibility.
1521 It is replaced by \fBdlg_calc_list_width\fP.
1522 .RS
1523 .TP 5
1524 .B int \fIitem_no
1525 is the number of \fIitems\fP.
1526 .TP 5
1527 .B char ** \fIitems
1528 is a list of character pointers.
1529 .TP 5
1530 .B int \fIgroup
1531 is the number of items in each group, e.g., the second array index.
1532 .RE
1533 .\" ---------------------------------------------------------------------------
1534 .TP 5
1535 .B dlg_char_to_button
1536 Given a list of button labels,
1537 and a character which may be the abbreviation for one, find it, if it exists.
1538 An abbreviation will be the first character
1539 which happens to be capitalized in the label.
1540 If the character is found, return its index within the list of \fIlabels\fP.
1541 Otherwise, return \fBDLG_EXIT_UNKNOWN\fP.
1542 .RS
1543 .TP 5
1544 .B int \fIch
1545 is the character to find.
1546 .TP 5
1547 .B const char ** \fIlabels
1548 is a list of (pointers to) button labels terminated by a null pointer.
1549 .RE
1550 .\" ---------------------------------------------------------------------------
1551 .TP 5
1552 .B dlg_checklist
1553 This entrypoint provides the \fB--checklist\fP or \fP--radiolist\fP
1554 functionality without the limitations of \fB\*p\fP's command-line syntax
1555 (compare to \fBdialog_checklist\fP).
1556 .RS
1557 .TP 5
1558 .B const char * \fItitle
1559 is the title string to display at the top of the widget.
1560 .TP 5
1561 .B const char * \fIcprompt
1562 is the prompt text shown within the widget.
1563 .TP 5
1564 .B int \fIheight
1565 is the desired height of the box.
1566 If zero, the height is adjusted to use the available screen size.
1567 .TP 5
1568 .B int \fIwidth
1569 is the desired width of the box.
1570 If zero, the height is adjusted to use the available screen size.
1571 .TP 5
1572 .B int \fIlist_height
1573 is the minimum height to reserve for displaying the list.
1574 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
1575 .TP 5
1576 .B int \fIitem_no
1577 is the number of \fIitems\fP.
1578 .TP 5
1579 .B DIALOG_LISTITEM * \fIitems
1580 This is a list of the items to display in the checklist.
1581 .TP 5
1582 .B const char * \fIstates
1583 This is a list of characters to display for the given states.
1584 Normally a checklist provides true (1) and false (0) values,
1585 which the widget displays as "*" and space, respectively.
1586 An application may set this parameter to an arbitrary null-terminated string.
1587 The widget determines the number of states from the length of this string,
1588 and will cycle through the corresponding display characters as the user
1589 presses the space-bar.
1590 .TP 5
1591 .B int \fIflag
1592 This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP,
1593 depending on whether the widget should act as a checklist or radiobox.
1594 .TP 5
1595 .B int * \fIcurrent_item
1596 The widget sets the referenced location to the index of the current display
1597 item (cursor) when it returns.
1598 .RE
1599 .\" ---------------------------------------------------------------------------
1600 .TP 5
1601 .B dlg_check_scrolled
1602 given a function key (or other key that was mapped to a function key),
1603 check if it is one of the up/down scrolling functions:
1604 .sp
1605 .RS
1606         DLGK_PAGE_FIRST,
1607 .br
1608         DLGK_PAGE_LAST,
1609 .br
1610         DLGK_GRID_UP,
1611 .br
1612         DLGK_GRID_DOWN,
1613 .br
1614         DLGK_PAGE_PREV or
1615 .br
1616         DLGK_PAGE_NEXT.
1617 .RE
1618 .fi
1619 .IP
1620 Some widgets use these key bindings for scrolling the prompt-text up and
1621 down, to allow for display in very small windows.
1622 .IP
1623 The function returns 0 (zero) if it finds one of these keys,
1624 and -1 if not.
1625 .RS
1626 .TP 5
1627 .B int \fIkey
1628 is the function-key to check
1629 .TP 5
1630 .B int \fIlast
1631 is the number of lines
1632 which would be used to display the scrolled prompt in
1633 an arbitrarily tall window.
1634 It is used here to check limits for the \fIoffset\fP value.
1635 .TP 5
1636 .B int \fIpage
1637 this is the available height for writing scrolled text,
1638 which is smaller than the window if it contains buttons.
1639 .TP 5
1640 .B bool * \fIshow
1641 on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay
1642 the prompt text.
1643 .TP 5
1644 .B int * \fIoffset
1645 on entry, holds the starting line number (counting from zero)
1646 last used for \fBdlg_print_scrolled\fP.
1647 On return, holds the updated starting line number.
1648 .RE
1649 .\" ---------------------------------------------------------------------------
1650 .TP 5
1651 .B dlg_clear
1652 Set window to the default \fB\*p\fP screen attribute.
1653 This is set in the rc-file with \fBscreen_color\fP.
1654 .\" ---------------------------------------------------------------------------
1655 .TP 5
1656 .B dlg_clr_result
1657 Free storage used for the result buffer (\fBdialog_vars.input_result\fP).
1658 The corresponding pointer is set to NULL.
1659 .\" ---------------------------------------------------------------------------
1660 .TP 5
1661 .B dlg_color_count
1662 Return the number of colors that can be configured in \fB\*p\fP.
1663 .\" ---------------------------------------------------------------------------
1664 .TP 5
1665 .B dlg_color_setup
1666 Initialize the color pairs used in \fB\*p\fP.
1667 .\" ---------------------------------------------------------------------------
1668 .TP 5
1669 .B dlg_count_argv
1670 Count the entries in an argument vector.
1671 .RS
1672 .TP 5
1673 .B argv
1674 Points to the argument vector.
1675 .RE
1676 .\" ---------------------------------------------------------------------------
1677 .TP 5
1678 .B dlg_count_columns
1679 Returns the number of columns used for a string.
1680 This is not necessarily the number of bytes in a string.
1681 .RS
1682 .TP 5
1683 .B const char * \fIstring
1684 is the string to measure.
1685 .RE
1686 .\" ---------------------------------------------------------------------------
1687 .TP 5
1688 .B dlg_count_wchars
1689 Returns the number of wide-characters in the string.
1690 .RS
1691 .TP 5
1692 .B const char * \fIstring
1693 is the string to measure.
1694 .RE
1695 .\" ---------------------------------------------------------------------------
1696 .TP 5
1697 .B dlg_create_rc
1698 Create a configuration file,
1699 i.e., write internal tables to a file which can be read back by \fB\*p\fP
1700 as an rc-file.
1701 .RS
1702 .TP 5
1703 .B const char * \fIfilename
1704 is the name of the file to write to.
1705 .RE
1706 .\" ---------------------------------------------------------------------------
1707 .TP 5
1708 .B dlg_ctl_size
1709 If \fBdialog_vars.size_err\fP is true,
1710 check if the given window size is too large to fit on the screen.
1711 If so, exit with an error reporting the size of the window.
1712 .RS
1713 .TP 5
1714 .B int \fIheight
1715 is the window's height
1716 .TP 5
1717 .B int \fIwidth
1718 is the window's width
1719 .RE
1720 .\" ---------------------------------------------------------------------------
1721 .TP 5
1722 .B dlg_default_formitem
1723 If \fBdialog_vars.default_item\fP is not null,
1724 find that name by matching the \fIname\fP field in the list of form \fIitems\fP.
1725 If found, return the index of that item in the list.
1726 Otherwise, return zero.
1727 .RS
1728 .TP 5
1729 .B DIALOG_FORMITEM * \fIitems
1730 is the list of items to search.
1731 It is terminated by an entry with a null \fIname\fP field.
1732 .RE
1733 .\" ---------------------------------------------------------------------------
1734 .TP 5
1735 .B dlg_default_item
1736 This function is obsolete, provided for library-compatibility.
1737 It is replaced by \fBdlg_default_formitem\fP and \fBdlg_default_listitem\fP.
1738 .RS
1739 .TP 5
1740 .B char ** \fIitems
1741 is the list of items to search.
1742 .TP 5
1743 .B int \fIllen
1744 is the number of items in each group, e.g., the second array index.
1745 .RE
1746 .\" ---------------------------------------------------------------------------
1747 .TP 5
1748 .B dlg_defaultno_button
1749 If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not,
1750 find the button-index for the "Cancel" button.
1751 Otherwise, return the index for "OK" (always zero).
1752 .\" ---------------------------------------------------------------------------
1753 .TP 5
1754 .B dlg_del_window
1755 Remove a window, repainting everything else.
1756 .RS
1757 .TP 5
1758 .B WINDOW * \fIwin
1759 is the window to remove.
1760 .RE
1761 .\" ---------------------------------------------------------------------------
1762 .TP 5
1763 .B dlg_does_output
1764 This is called each time a widget is invoked which may do output.
1765 It increments \fBdialog_state.output_count\fP,
1766 so the output function in \fB\*p\fP can test this and add a separator.
1767 .\" ---------------------------------------------------------------------------
1768 .TP 5
1769 .B dlg_draw_arrows
1770 Draw up/down arrows on a window, e.g., for scrollable lists.
1771 It calls \fBdlg_draw_arrows2\fP using the
1772 \fImenubox_color\fP and \fImenubox_border_color\fP attributes.
1773 .RS
1774 .TP 5
1775 .B WINDOW * \fIdialog
1776 is the window on which to draw an arrow.
1777 .TP 5
1778 .B int \fItop_arrow
1779 is true if an up-arrow should be drawn at the top of the window.
1780 .TP 5
1781 .B int \fIbottom_arrow
1782 is true if an down-arrow should be drawn at the bottom of the window.
1783 .TP 5
1784 .B int \fIx
1785 is the zero-based column within the window on which to draw arrows.
1786 .TP 5
1787 .B int \fItop
1788 is the zero-based row within the window on which to draw up-arrows
1789 as well as a horizontal line to show the window's top.
1790 .TP 5
1791 .B int \fIbottom
1792 is the zero-based row within the window on which to draw down-arrows
1793 as well as a horizontal line to show the window's bottom.
1794 .RE
1795 .\" ---------------------------------------------------------------------------
1796 .TP 5
1797 .B dlg_draw_arrows2
1798 Draw up/down arrows on a window, e.g., for scrollable lists.
1799 .RS
1800 .TP 5
1801 .B WINDOW * \fIdialog
1802 is the window on which to draw an arrow.
1803 .TP 5
1804 .B int \fItop_arrow
1805 is true if an up-arrow should be drawn at the top of the window.
1806 .TP 5
1807 .B int \fIbottom_arrow
1808 is true if an down-arrow should be drawn at the bottom of the window.
1809 .TP 5
1810 .B int \fIx
1811 is the zero-based column within the window on which to draw arrows.
1812 .TP 5
1813 .B int \fItop
1814 is the zero-based row within the window on which to draw up-arrows
1815 as well as a horizontal line to show the window's top.
1816 .TP 5
1817 .B int \fIbottom
1818 is the zero-based row within the window on which to draw down-arrows
1819 as well as a horizontal line to show the window's bottom.
1820 .TP 5
1821 .B chtype \fIattr
1822 is the window's background attribute.
1823 .TP 5
1824 .B chtype \fIborderattr
1825 is the window's border attribute.
1826 .RE
1827 .\" ---------------------------------------------------------------------------
1828 .TP 5
1829 .B dlg_draw_bottom_box
1830 Draw a partial box at the bottom of a window,
1831 e.g., to surround a row of buttons.
1832 It is designed to merge with an existing box around
1833 the whole window, so it uses tee-elements rather than corner-elements
1834 on the top corners of this box.
1835 .RS
1836 .TP 5
1837 .B WINDOW * \fIwin
1838 is the window to update.
1839 .RE
1840 .\" ---------------------------------------------------------------------------
1841 .TP 5
1842 .B dlg_draw_box
1843 Draw a rectangular box with line drawing characters.
1844 .RS
1845 .TP 5
1846 .B WINDOW * \fIwin
1847 is the window to update.
1848 .TP 5
1849 .B int \fIy
1850 is the top row of the box.
1851 .TP 5
1852 .B int \fIx
1853 is the left column of the box.
1854 .TP 5
1855 .B int \fIheight
1856 is the height of the box.
1857 .TP 5
1858 .B int \fIwidth
1859 is the width of the box.
1860 .TP 5
1861 .B chtype \fIboxchar
1862 is used to color the right/lower edges.
1863 It also is fill-color used for the box contents.
1864 .TP 5
1865 .B chtype \fIborderchar
1866 is used to color the upper/left edges.
1867 .RE
1868 .\" ---------------------------------------------------------------------------
1869 .TP 5
1870 .B dlg_draw_buttons
1871 Print a list of buttons at the given position.
1872 .RS
1873 .TP 5
1874 .B WINDOW * \fIwin
1875 is the window to update.
1876 .TP 5
1877 .B int \fIy
1878 is the starting row.
1879 .TP 5
1880 .B int \fIx
1881 is the starting column.
1882 .TP 5
1883 .B const char ** \fIlabels
1884 is a list of (pointers to) button labels terminated by a null pointer.
1885 .TP 5
1886 .B int \fIselected
1887 is the index within the list of the selected button.
1888 .TP 5
1889 .B int \fIvertical
1890 is true if the buttons are arranged in a column rather than a row.
1891 .TP 5
1892 .B int \fIlimit
1893 is the number of columns (or rows if \fIvertical\fP) allowed for the display.
1894 .RE
1895 .\" ---------------------------------------------------------------------------
1896 .TP 5
1897 .B dlg_draw_helpline
1898 draw the text in \fBdialog_vars.help_line\fP at the bottom of the given window.
1899 .RS
1900 .TP 5
1901 .B WINDOW * \fIdialog
1902 is the window to modify.
1903 .TP 5
1904 .B bool \fIdecorations
1905 if true, allow room for the scrolling arrows.
1906 .RE
1907 .\" ---------------------------------------------------------------------------
1908 .TP 5
1909 .B dlg_draw_scrollbar
1910 If \fBdialog_state.use_scrollbar\fP is set,
1911 draw a scrollbar on the right margin of windows holding scrollable data.
1912 Also (whether or not the scrollbar is drawn),
1913 annotate the bottom margin of the window with the percentage of data
1914 by the bottom of that window,
1915 and call \fBdlg_draw_arrows2\fP to put markers on the window showing
1916 when more data is available.
1917 .RS
1918 .TP 5
1919 .B WINDOW * \fIwin
1920 is the window in which the data is scrolled.
1921 Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP
1922 are passed as parameters, this window can contain additional data.
1923 .TP 5
1924 .B long \fIfirst_data
1925 is the zero-based index to the first row of data in the current window.
1926 .TP 5
1927 .B long \fIthis_data
1928 is the zero-based index to the current row of data.
1929 .TP 5
1930 .B long \fInext_data
1931 is the zero-based index to the next data after the current row.
1932 .TP 5
1933 .B long \fItotal_data
1934 is the total number of rows of data.
1935 .TP 5
1936 .B int \fIleft
1937 is the zero-based left margin/column of the window.
1938 The up/down arrows are draw inset by 5 columns from this point.
1939 .TP 5
1940 .B int \fIright
1941 is the zero-based right margin/column of the window.
1942 The scrollbar is drawn flush against this column.
1943 .TP 5
1944 .B int \fItop
1945 is the zero-based row within the window on which to draw up-arrows
1946 as well as a horizontal line to show the window's top.
1947 .TP 5
1948 .B int \fIbottom
1949 is the zero-based row within the window on which to draw down-arrows
1950 as well as a horizontal line to show the window's bottom.
1951 .TP 5
1952 .B chtype \fIattr
1953 is the window's background attribute.
1954 .TP 5
1955 .B chtype \fIborderattr
1956 is the window's border attribute.
1957 .RE
1958 .\" ---------------------------------------------------------------------------
1959 .TP 5
1960 .B dlg_draw_shadow
1961 Draw shadows along the right and bottom edge of a window to give it
1962 a 3-dimensional look.
1963 (The height, etc., may not be the same as the window's actual values).
1964 .RS
1965 .TP 5
1966 .B WINDOW * \fIwin
1967 is the window to update.
1968 .TP 5
1969 .B int \fIheight
1970 is the height of the window.
1971 .TP 5
1972 .B int \fIwidth
1973 is the width of the window.
1974 .TP 5
1975 .B int \fIy
1976 is the top row of the window.
1977 .TP 5
1978 .B int \fIx
1979 is the left column of the window.
1980 .RE
1981 .\" ---------------------------------------------------------------------------
1982 .TP 5
1983 .B dlg_draw_title
1984 Draw a title centered at the top of the window.
1985 .RS
1986 .TP 5
1987 .B WINDOW * \fIwin
1988 is the window to update.
1989 .TP 5
1990 .B const char * \fItitle
1991 is the title string to display at the top of the widget.
1992 .RE
1993 .\" ---------------------------------------------------------------------------
1994 .TP 5
1995 .B dlg_dump_keys
1996 Write all user-defined key-bindings to the given stream,
1997 e.g., as part of \fBdlg_create_rc\fP.
1998 .RS
1999 .TP 5
2000 .B FILE * \fIfp
2001 is the stream on which to write the bindings.
2002 .RE
2003 .\" ---------------------------------------------------------------------------
2004 .TP 5
2005 .B dlg_eat_argv
2006 Remove one or more items from an argument vector.
2007 .RS
2008 .TP 5
2009 .B int *argcp
2010 in/out parameter giving the length of the argument vector.
2011 .B char ***argvp
2012 in/out parameter pointing to the argument vector.
2013 .B int start
2014 starting index.
2015 .B int count
2016 number of arguments to remove.
2017 .RE
2018 .\" ---------------------------------------------------------------------------
2019 .TP 5
2020 .B dlg_edit_offset
2021 Given the character-offset in the string,
2022 returns the display-offset where
2023 \fB\*p\fP should position the cursor.
2024 In this context, "characters" may be multicolumn,
2025 since the string can be a multibyte character string.
2026 .RS
2027 .TP 5
2028 .B char * \fIstring
2029 is the string to analyze
2030 .TP 5
2031 .B int \fIoffset
2032 is the character-offset
2033 .TP 5
2034 .B int \fIx_last
2035 is a limit on the column positions that can be used,
2036 e.g., the window's size.
2037 .RE
2038 .\" ---------------------------------------------------------------------------
2039 .TP 5
2040 .B dlg_edit_string
2041 Updates the string and character-offset, given various editing characters
2042 or literal characters which are inserted at the character-offset.
2043 Returns true if an editing change was made (and the display should
2044 be updated), and false if the key was something like KEY_ENTER,
2045 which is a non-editing action outside this function.
2046 .RS
2047 .TP 5
2048 .B char * \fIstring
2049 is the (multibyte) string to update
2050 .TP 5
2051 .B int * \fIoffset
2052 is the character-offset
2053 .TP 5
2054 .B int \fIkey
2055 is the editing key
2056 .TP 5
2057 .B int \fIfkey
2058 is true if the editing key is a function-key
2059 .TP 5
2060 .B bool \fIforce
2061 is used in a special loop case by calling code to force the return
2062 value of this function when a function-key code 0 is passed in.
2063 .RE
2064 .\" ---------------------------------------------------------------------------
2065 .TP 5
2066 .B dlg_exit
2067 Given an internal exit code,
2068 check if the corresponding environment variable is set.
2069 If so, remap the exit code to match the environment variable.
2070 Finally call \fBexit\fP with the resulting exit code.
2071 .RS
2072 .TP 5
2073 .B int \fIcode
2074 is the internal exit code, e.g., \fBDLG_EXIT_OK\fP,
2075 which may be remapped.
2076 .RE
2077 .IP
2078 The \fB\*p\fP program uses this function
2079 to allow shell scripts to remap the exit codes so they can distinguish ESC
2080 from ERROR.
2081 .\" ---------------------------------------------------------------------------
2082 .TP 5
2083 .B dlg_exit_buttoncode
2084 Map the given button index for \fBdlg_exit_label\fP into \fB\*p\fP's exit-code.
2085 .RS
2086 .TP 5
2087 .B int \fIbutton
2088 is the button index
2089 .RE
2090 .\" ---------------------------------------------------------------------------
2091 .TP 5
2092 .B dlg_exit_label
2093 Return a list of button labels.
2094 If dialog_var.extra_button is true, return the result of \fBdlg_ok_labels\fP.
2095 Otherwise, return a list with the "Exit" label and (if \fBdialog_vars.help_button\fP
2096 is set) the "Help" button as well.
2097 .\" ---------------------------------------------------------------------------
2098 .TP 5
2099 .B dlg_exiterr
2100 Quit program killing all \fBtailboxbg\fP widgets.
2101 .RS
2102 .TP 5
2103 .B const char * \fIfmt
2104 is the format of the \fBprintf\fP-like message to write.
2105 .TP 5
2106 .B ...
2107 .br
2108 are the variables to apply to the \fIfmt\fP format.
2109 .RE
2110 .\" ---------------------------------------------------------------------------
2111 .TP 5
2112 .B dlg_find_index
2113 Given the character-offset to find in the list, return the corresponding
2114 array index.
2115 .RS
2116 .TP 5
2117 .B const int *\fIlist
2118 contains a list of character-offsets,
2119 i.e., indices into a string that denote the beginning of multibyte characters.
2120 .TP 5
2121 .B int \fIlimit
2122 is the last index into \fBlist\fP to search.
2123 .TP 5
2124 .B int \fIto_find
2125 is the character-offset to find.
2126 .RE
2127 .\" ---------------------------------------------------------------------------
2128 .TP 5
2129 .B dlg_flush_getc
2130 Cancel the local data saved by \fBdlg_last_getc\fP.
2131 .\" ---------------------------------------------------------------------------
2132 .IP dlg_editbox
2133 This entrypoint provides the \fB--editbox\fP
2134 functionality without the limitations of \fB\*p\fP's command-line syntax
2135 (compare to \fBdialog_editbox\fP).
2136 .RS
2137 .TP 5
2138 .B const char * \fItitle
2139 is the title string to display at the top of the widget.
2140 .TP 5
2141 .B char *** \fIlist
2142 is a pointer to an array of \fBchar\ *\fP pointers.
2143 The array is allocated by the caller,
2144 and so are the strings to which it points.
2145 The \fBdlg_editbox\fP function may reallocate the
2146 array and the strings.
2147 .TP 5
2148 .B int * \fIrows
2149 points to the nominal length of \fIlist\fP.
2150 The referenced value is updated if\fIlist\fP is reallocated.
2151 .TP 5
2152 .B int \fIheight
2153 is the desired height of the box.
2154 If zero, the height is adjusted to use the available screen size.
2155 .TP 5
2156 .B int \fIwidth
2157 is the desired width of the box.
2158 If zero, the height is adjusted to use the available screen size.
2159 .RE
2160 .\" ---------------------------------------------------------------------------
2161 .TP 5
2162 .B dlg_form
2163 This entrypoint provides the \fB--form\fP
2164 functionality without the limitations of \fB\*p\fP's command-line syntax
2165 (compare to \fBdialog_form\fP).
2166 .RS
2167 .TP 5
2168 .B const char * \fItitle
2169 is the title string to display at the top of the widget.
2170 .TP 5
2171 .B const char * \fIcprompt
2172 is the prompt text shown within the widget.
2173 .TP 5
2174 .B int \fIheight
2175 is the desired height of the box.
2176 If zero, the height is adjusted to use the available screen size.
2177 .TP 5
2178 .B int \fIwidth
2179 is the desired width of the box.
2180 If zero, the height is adjusted to use the available screen size.
2181 .TP 5
2182 .B int \fIform_height
2183 is the minimum height to reserve for displaying the list.
2184 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2185 .TP 5
2186 .B int \fIitem_no
2187 is the number of \fIitems\fP.
2188 .TP 5
2189 .B DIALOG_FORMITEM * \fIitems
2190 This is a list of the items to display in the form.
2191 .TP 5
2192 .B int * \fIcurrent_item
2193 The widget sets the referenced location to the index of the current display
2194 item (cursor) when it returns.
2195 .RE
2196 .\" ---------------------------------------------------------------------------
2197 .TP 5
2198 .B dlg_free_columns
2199 Free data allocated by \fBdlg_align_columns\fP.
2200 .RS
2201 .TP 5
2202 .B char **\fItarget
2203 This is the array which was reformatted.
2204 It points to the first string to free.
2205 .TP 5
2206 .B int \fIper_row
2207 This is the size of the struct for each row of the array.
2208 .TP 5
2209 .B int \fInum_rows
2210 This is the number of rows in the array.
2211 .RE
2212 .\" ---------------------------------------------------------------------------
2213 .TP 5
2214 .B dlg_free_formitems
2215 Free memory owned by a list of DIALOG_FORMITEM's.
2216 .RS
2217 .TP 5
2218 .B DIALOG_FORMITEM * \fIitems
2219 is the list to free.
2220 .RE
2221 .\" ---------------------------------------------------------------------------
2222 .TP 5
2223 .B dlg_free_gauge
2224 Remove the gauge widget from the screen and free its associated memory.
2225 .RS
2226 .TP 5
2227 .B void *\fIobjptr
2228 points to the gauge widget.
2229 .RE
2230 .\" ---------------------------------------------------------------------------
2231 .TP 5
2232 .B dlg_getc
2233 Read a character from the given window.
2234 Handle repainting here (to simplify
2235 things in the calling application).
2236 Also, if input-callback(s) are set up,
2237 poll the corresponding files and handle the updates,
2238 e.g., for displaying a tailbox.
2239 Returns the key-code.
2240 .RS
2241 .TP 5
2242 .B WINDOW * \fIwin
2243 is the window within which to read.
2244 .TP 5
2245 .B int * \fIfkey
2246 as a side-effect, set this to true if the key-code is really a function-key.
2247 .RE
2248 .\" ---------------------------------------------------------------------------
2249 .TP 5
2250 .B dlg_get_attrs
2251 extract the video attributes from the given window.
2252 .RS
2253 .TP 5
2254 .B WINDOW * \fIwin
2255 is the window from which to get attributes.
2256 .RE
2257 .\" ---------------------------------------------------------------------------
2258 .TP 5
2259 .B dlg_getc_callbacks
2260 passes the given key-code \fIch\fP to the current window that
2261 has established a callback.
2262 If the callback returns zero, remove it and try the next window.
2263 If no more callbacks remain, return.
2264 If any callbacks were found, return true, otherwise false.
2265 .RS
2266 .TP 5
2267 .B int \fIch
2268 is the key-code
2269 .TP 5
2270 .B int \fIfkey
2271 is true if the key is a function-key
2272 .TP 5
2273 .B int * \fIresult
2274 is used to pass an exit-code to the caller,
2275 which should pass that via \fBdlg_exit\fP.
2276 .RE
2277 .\" ---------------------------------------------------------------------------
2278 .TP 5
2279 .B dlg_index_columns
2280 Build a list of the display-columns for the given multibyte string's characters.
2281 .RS
2282 .TP 5
2283 .B const char * \fIstring
2284 is the string to analyze
2285 .RE
2286 .\" ---------------------------------------------------------------------------
2287 .TP 5
2288 .B dlg_index_wchars
2289 Build an index of the wide-characters in the string,
2290 so the caller can easily tell
2291 which byte-offset begins a given wide-character.
2292 .RS
2293 .TP 5
2294 .B const char * \fIstring
2295 is the string to analyze
2296 .RE
2297 .\" ---------------------------------------------------------------------------
2298 .TP 5
2299 .B dlg_item_help
2300 Draw the string for the \fBdialog_vars.item_help\fP feature.
2301 .RS
2302 .TP 5
2303 .B const char * \fItxt
2304 is the help-message
2305 .RE
2306 .\" ---------------------------------------------------------------------------
2307 .TP 5
2308 .B dlg_killall_bg
2309 If \fB\*p\fP has callbacks active,
2310 purge the list of all that are not marked
2311 to keep in the background.
2312 If any remain, run those in a background process.
2313 .RS
2314 .TP 5
2315 .B int * \fIretval
2316 stores the exit-code to pass back to the caller.
2317 .RE
2318 .\" ---------------------------------------------------------------------------
2319 .TP 5
2320 .B dlg_last_getc
2321 returns the most recent character that was read via \fBdlg_getc\fP.
2322 .\" ---------------------------------------------------------------------------
2323 .TP 5
2324 .B dlg_limit_columns
2325 Given a column limit,
2326 count the number of wide characters that can fit into that limit.
2327 The offset is used to skip over a leading character
2328 that was already written.
2329 .RS
2330 .TP 5
2331 .B const char * \fIstring
2332 is the string to analyze
2333 .TP 5
2334 .B int \fIlimit
2335 is the column limit
2336 .TP 5
2337 .B int \fIoffset
2338 is the starting offset from which analysis should continue
2339 .RE
2340 .\" ---------------------------------------------------------------------------
2341 .TP 5
2342 .B dlg_lookup_key
2343 Check for a key-binding.
2344 If there is no binding associated with the widget, it simply returns
2345 the given curses-key.
2346 Otherwise, it returns the result of the binding
2347 .RS
2348 .TP 5
2349 .B WINDOW * \fIwin
2350 is the window on which the binding is checked
2351 .TP 5
2352 .B int \fIcurses_key
2353 is the curses key-code
2354 .TP 5
2355 .B int * \fIdialog_key
2356 is the corresponding \fB\*p\fP internal code
2357 (see \fBDLG_KEYS_ENUM\fP in dlg_key.h).
2358 .RE
2359 .\" ---------------------------------------------------------------------------
2360 .TP 5
2361 .B dlg_max_input
2362 Limit the parameter according to \fBdialog_vars.max_input\fP
2363 .RS
2364 .TP 5
2365 .B int \fImax_len
2366 is the value to limit
2367 .RE
2368 .\" ---------------------------------------------------------------------------
2369 .TP 5
2370 .B dlg_match_char
2371 Match a given character against the beginning of the string,
2372 ignoring case of the given character.
2373 The matching string must begin with an uppercase character.
2374 .RS
2375 .TP 5
2376 .B int \fIch
2377 is the character to check
2378 .TP 5
2379 .B const char * \fIstring
2380 is the string to search
2381 .RE
2382 .\" ---------------------------------------------------------------------------
2383 .TP 5
2384 .B dlg_menu
2385 This entrypoint provides the \fB--menu\fP
2386 functionality without the limitations of \fB\*p\fP's command-line syntax
2387 (compare to \fBdialog_menu\fP).
2388 .RS
2389 .TP 5
2390 .B const char * \fItitle
2391 is the title string to display at the top of the widget.
2392 .TP 5
2393 .B const char * \fIcprompt
2394 is the prompt text shown within the widget.
2395 .TP 5
2396 .B int \fIheight
2397 is the desired height of the box.
2398 If zero, the height is adjusted to use the available screen size.
2399 .TP 5
2400 .B int \fIwidth
2401 is the desired width of the box.
2402 If zero, the height is adjusted to use the available screen size.
2403 .TP 5
2404 .B int \fImenu_height
2405 is the minimum height to reserve for displaying the list.
2406 If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP.
2407 .TP 5
2408 .B int \fIitem_no
2409 is the number of \fIitems\fP.
2410 .TP 5
2411 .B DIALOG_LISTITEM * \fIitems
2412 This is a list of the items to display in the form.
2413 .TP 5
2414 .B int * \fIcurrent_item
2415 The widget sets the referenced location to the index of the current display
2416 item (cursor) when it returns.
2417 .TP 5
2418 .B DIALOG_INPUTMENU \fIrename_menutext
2419 .RE
2420 .\" ---------------------------------------------------------------------------
2421 .TP 5
2422 .B dlg_move_window
2423 Moves/resizes the given window to the given position and size.
2424 .RS
2425 .TP 5
2426 .B WINDOW *\fIwin
2427 is the window to move/resize.
2428 .TP 5
2429 .B WINDOW *\fIheight
2430 is the height of the resized window.
2431 .TP 5
2432 .B WINDOW *\fIwidth
2433 is the width of the resized window.
2434 .TP 5
2435 .B WINDOW *\fIy
2436 y-ordinate to use for the repositioned window.
2437 .TP 5
2438 .B WINDOW *\fIx
2439 x-ordinate to use for the repositioned window.
2440 .RE
2441 .\" ---------------------------------------------------------------------------
2442 .TP 5
2443 .B dlg_mouse_bigregion
2444 Retrieve the big-region under the pointer.
2445 .RS
2446 .TP 5
2447 .B int \fIy
2448 is the row on which the mouse click occurred
2449 .TP 5
2450 .B int \fIx
2451 is the column on which the mouse click occurred
2452 .RE
2453 .\" ---------------------------------------------------------------------------
2454 .TP 5
2455 .B dlg_mouse_free_regions
2456 Free the memory associated with mouse regions.
2457 .\" ---------------------------------------------------------------------------
2458 .TP 5
2459 .B dlg_mouse_mkbigregion
2460 Creates a region on which the mouse-clicks will return a specifed code.
2461 .RS
2462 .TP 5
2463 .B int \fIy
2464 is the top-row of the region.
2465 .TP 5
2466 .B int \fIx
2467 is the left-column of the region.
2468 .TP 5
2469 .B int \fIheight
2470 is the height of the region.
2471 .TP 5
2472 .B int \fIwidth
2473 is the width of the region.
2474 .TP 5
2475 .B int \fIcode
2476 is a code used to make the region unique within a widget
2477 .TP 5
2478 .B int \fIstep_x
2479 is used in modes 2 (columns) and 3 (cells) to determine the width
2480 of a column/cell.
2481 .TP 5
2482 .B int \fIstep_y
2483 is currently unused
2484 .TP 5
2485 .B int \fImode
2486 is used to determine how the mouse position is translated into
2487 a code (like a function-key):
2488 .RS
2489 .TP
2490 1
2491 index by lines
2492 .TP
2493 2
2494 index by columns
2495 .TP
2496 3
2497 index by cells
2498 .RE
2499 .RE
2500 .\" ---------------------------------------------------------------------------
2501 .TP 5
2502 .B dlg_mouse_mkregion
2503 .RS
2504 .TP 5
2505 .B int \fIy
2506 is the top-row of the region.
2507 .TP 5
2508 .B int \fIx
2509 is the left-column of the region.
2510 .TP 5
2511 .B int \fIheight
2512 is the height of the region.
2513 .TP 5
2514 .B int \fIwidth
2515 is the width of the region.
2516 .TP 5
2517 .B int \fIcode
2518 is a code used to make the region unique within a widget
2519 .RE
2520 .\" ---------------------------------------------------------------------------
2521 .TP 5
2522 .B dlg_mouse_region
2523 Retrieve the frame under the mouse pointer
2524 .RS
2525 .TP 5
2526 .B int \fIy
2527 is the row of the mouse-click
2528 .TP 5
2529 .B int \fIx
2530 is the column of the mouse-click
2531 .RE
2532 .\" ---------------------------------------------------------------------------
2533 .TP 5
2534 .B dlg_mouse_setbase
2535 Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP,
2536 so they can make regions relative to the start of a given window.
2537 .RS
2538 .TP 5
2539 .B int \fIx
2540 is the left-column for the base
2541 .TP 5
2542 .B int \fIy
2543 is the top-row for the base
2544 .RE
2545 .\" ---------------------------------------------------------------------------
2546 .TP 5
2547 .B dlg_mouse_wgetch
2548 is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks
2549 (if the curses library supports those) into extended function-keys
2550 which encode the position according to the \fImode\fP in
2551 \fBdlg_mouse_mkbigregion\fP.
2552 Returns the corresponding key-code.
2553 .RS
2554 .TP 5
2555 .B WINDOW * \fIwin
2556 is the window on which to perform the input
2557 .TP 5
2558 .B int * \fIfkey
2559 the referenced location is set to true if the key-code is an actual
2560 or extended (mouse) function-key.
2561 .RE
2562 .\" ---------------------------------------------------------------------------
2563 .TP 5
2564 .B dlg_mouse_wgetch_nowait
2565 This is a non-blocking variant of \fBdlg_mouse_wgetch\fP.
2566 .RS
2567 .TP 5
2568 .B WINDOW * \fIwin
2569 is the window on which to perform the input
2570 .TP 5
2571 .B int * \fIfkey
2572 the referenced location is set to true if the key-code is an actual
2573 or extended (mouse) function-key.
2574 .RE
2575 .\" ---------------------------------------------------------------------------
2576 .TP 5
2577 .B dlg_need_separator
2578 Check if an output-separator is needed.
2579 If \fBdialog_vars.output_separator\fP is set, return true.
2580 Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true.
2581 If neither, return false.
2582 .\" ---------------------------------------------------------------------------
2583 .TP 5
2584 .B dlg_new_modal_window
2585 Create a modal window, optionally with a shadow.
2586 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2587 .RS
2588 .TP 5
2589 .B WINDOW * \fIparent
2590 is the parent window (usually the top-level window of a widget)
2591 .TP 5
2592 .B int \fIheight
2593 is the window's height
2594 .TP 5
2595 .B int \fIwidth
2596 is the window's width
2597 .TP 5
2598 .B int \fIy
2599 is the window's top-row
2600 .TP 5
2601 .B int \fIx
2602 is the window's left-column
2603 .RE
2604 .\" ---------------------------------------------------------------------------
2605 .TP 5
2606 .B dlg_new_window
2607 Create a window, optionally with a shadow.
2608 The shadow is created if \fBdialog_state.use_shadow\fP is true.
2609 .RS
2610 .TP 5
2611 .B int \fIheight
2612 is the window's height
2613 .TP 5
2614 .B int \fIwidth
2615 is the window's width
2616 .TP 5
2617 .B int \fIy
2618 is the window's top-row
2619 .TP 5
2620 .B int \fIx
2621 is the window's left-column
2622 .RE
2623 .\" ---------------------------------------------------------------------------
2624 .TP 5
2625 .B dlg_next_button
2626 Return the next index in the list of labels.
2627 .RS
2628 .TP 5
2629 .B const char ** \fIlabels
2630 is a list of (pointers to) button labels terminated by a null pointer.
2631 .TP 5
2632 .B int \fIbutton
2633 is the current button-index.
2634 .RE
2635 .\" ---------------------------------------------------------------------------
2636 .TP 5
2637 .B dlg_next_ok_buttonindex
2638 Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons,
2639 find the next index in the list of buttons.
2640 .RS
2641 .TP 5
2642 .B int \fIcurrent
2643 is the current index in the list of buttons
2644 .TP 5
2645 .B int \fIextra
2646 if negative, provides a way to enumerate extra active areas on the widget.
2647 .RE
2648 .\" ---------------------------------------------------------------------------
2649 .TP 5
2650 .B dlg_ok_buttoncode
2651 Map the given button index for \fBdlg_ok_labels\fP
2652 into \fB\*p\fP's exit-code.
2653 .RS
2654 .TP 5
2655 .B int \fIbutton
2656 is the button-index (which is not necessarily the same as the index
2657 in the list of labels).
2658 .RE
2659 .\" ---------------------------------------------------------------------------
2660 .TP 5
2661 .B dlg_ok_label
2662 Returns a list with the "Ok" label,
2663 and if \fBdialog_vars.help_button\fP is true, the "Help" label as well.
2664 .\" ---------------------------------------------------------------------------
2665 .TP 5
2666 .B dlg_ok_labels
2667 Return a list of button labels for the OK/Cancel group of widgets.
2668 .\" ---------------------------------------------------------------------------
2669 .TP 5
2670 .B dlg_ordinate
2671 Decode the string as an integer, decrement if greater than zero to make
2672 a curses-ordinate from a dialog-ordinate.
2673 .\" ---------------------------------------------------------------------------
2674 .TP 5
2675 .B dlg_parse_bindkey
2676 Parse the parameters of the "bindkeys" configuration-file entry.  This
2677 expects widget name which may be "*", followed by curses key definition and
2678 then \fB\*p\fP key definition.
2679 .RS
2680 .TP 5
2681 .B char * \fIparams
2682 is the parameter string to parse.
2683 .RE
2684 .\" ---------------------------------------------------------------------------
2685 .TP 5
2686 .B dlg_parse_rc
2687 Parse the configuration file and set up variables.
2688 .\" ---------------------------------------------------------------------------
2689 .TP 5
2690 .B dlg_prev_button
2691 Return the previous index in the list of labels.
2692 .RS
2693 .TP 5
2694 .B const char ** \fIlabels
2695 is a list of (pointers to) button labels terminated by a null pointer.
2696 .TP 5
2697 .B int \fIbutton
2698 is the current button index
2699 .RE
2700 .\" ---------------------------------------------------------------------------
2701 .TP 5
2702 .B dlg_print_scrolled
2703 This is a wrapper for \fBdlg_print_autowrap\fP which allows the user
2704 to scroll too-long prompt text up/down.
2705 .IP
2706 See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP
2707 variable used as a parameter here.
2708 It complements this function; you need both.
2709 If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP
2710 parameter, needed for \fBdlg_check_scrolled\fP calls.
2711 .RS
2712 .TP 5
2713 .B WINDOW * \fIwin
2714 is the window to update.
2715 .TP 5
2716 .B const char * \fIprompt
2717 is the string to print
2718 .TP 5
2719 .B int \fIoffset
2720 is the starting line-number to write wrapped text.
2721 .TP 5
2722 .B int \fIheight
2723 is the available height for writing the wrapped text
2724 .TP 5
2725 .B int \fIwidth
2726 is the width that the wrapping should occur in
2727 .TP 5
2728 .B int \fIpauseopt
2729 is true if the extra functionality for scrolling should be enabled.
2730 If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling.
2731 .RE
2732 .\" ---------------------------------------------------------------------------
2733 .TP 5
2734 .B dlg_print_line
2735 Print one line of the prompt in the window within the limits of the
2736 specified right margin.
2737 The line will end on a word boundary and a pointer
2738 to the start of the next line is returned, or a NULL pointer if the end of
2739 *prompt is reached.
2740 .RS
2741 .TP 5
2742 .B WINDOW *\fIwin
2743 is the window to update.
2744 .TP 5
2745 .B chtype *\fIattr
2746 holds the starting attributes, and is updated to reflect the final attributes
2747 applied to the string.
2748 .TP 5
2749 .B const char *\fIprompt
2750 is the string to print
2751 .TP 5
2752 .B int \fIlm
2753 is the left margin.
2754 .TP 5
2755 .B int \fIrm
2756 is the right margin
2757 .TP 5
2758 .B int *\fIx
2759 returns the ending x-ordinate.
2760 .RE
2761 .\" ---------------------------------------------------------------------------
2762 .TP 5
2763 .B dlg_prev_ok_buttonindex
2764 Find the previous button index in the list from \fBdlg_ok_labels\fP.
2765 .RS
2766 .TP 5
2767 .B int \fIcurrent
2768 is the current index
2769 .TP 5
2770 .B int \fIextra
2771 if negative provides a way to enumerate extra active areas on the widget.
2772 .RE
2773 .\" ---------------------------------------------------------------------------
2774 .TP 5
2775 .B dlg_print_autowrap
2776 Print a string of text in a window, automatically wrap around to the next
2777 line if the string is too long to fit on one line.
2778 Note that the string may contain embedded newlines.
2779 The text is written starting at the top of the window.
2780 .RS
2781 .TP 5
2782 .B WINDOW * \fIwin
2783 is the window to update.
2784 .TP 5
2785 .B const char * \fIprompt
2786 is the string to print
2787 .TP 5
2788 .B int \fIheight
2789 is the nominal height the wrapped string is limited to
2790 .TP 5
2791 .B int \fIwidth
2792 is the width that the wrapping should occur in
2793 .RE
2794 .\" ---------------------------------------------------------------------------
2795 .TP 5
2796 .B dlg_print_size
2797 If \fBdialog_vars.print_siz\fP is true,
2798 print the given height/width (from a widget)
2799 to \fBdialog_state.output\fP, e.g.,
2800 \fBSize: height, width\fP.
2801 .RS
2802 .TP 5
2803 .B int \fIheight
2804 is the window's height
2805 .TP 5
2806 .B int \fIwidth
2807 is the window's width
2808 .RE
2809 .\" ---------------------------------------------------------------------------
2810 .TP 5
2811 .B dlg_print_text
2812 Print up to \fIcols\fP columns from \fBtext\fP,
2813 optionally rendering \fB\*p\fP's escape sequences for attributes and color.
2814 .RS
2815 .TP 5
2816 .B WINDOW * \fIwin
2817 is the window to update.
2818 .TP 5
2819 .B const char * \fItxt
2820 is the string to print
2821 .TP 5
2822 .B int \fIcol
2823 is the column limit
2824 .TP 5
2825 .B chtype * \fIattr
2826 holds the starting attributes, and is updated to reflect the final attributes
2827 applied to the string.
2828 .RE
2829 .\" ---------------------------------------------------------------------------
2830 .B dlg_progressbox
2831 implements the "\fB--prgbox\fP" and "\fB--progressbox\fP" options.
2832 .RS
2833 .TP 5
2834 .B const char * \fItitle
2835 is the title on the top of the widget.
2836 .TP 5
2837 .B const char * \fIcprompt
2838 is the prompt text shown within the widget.
2839 If empty or null, no prompt is shown.
2840 .TP 5
2841 .B int \fIheight
2842 is the desired height of the box.
2843 If zero, the height is based on the screen size.
2844 .TP 5
2845 .B int \fIwidth
2846 is the desired width of the box.
2847 If zero, the height is based on the screen size.
2848 .TP 5
2849 .B int \fIpauseopt
2850 if true, an "OK" button will be shown,
2851 and the dialog will wait for it to complete.
2852 With an "OK" button, it is denoted a "programbox",
2853 without an "OK" button, it is denoted a "progressbox".
2854 .TP 5
2855 .B FILE * \fIfp
2856 is the file pointer, which may be a pipe or a regular file.
2857 .RE
2858 .\" ---------------------------------------------------------------------------
2859 .TP 5
2860 .B dlg_put_backtitle
2861 Display the background title if \fBdialog_vars.backtitle\fP is non-null.
2862 The background title is shown at the top of the screen.
2863 .\" ---------------------------------------------------------------------------
2864 .TP 5
2865 .B dlg_register_buttons
2866 The widget developer should call this function after \fBdlg_register_window\fP,
2867 for the list of button labels associated with the widget.
2868 One may bind a key to a button, e.g., "OK" for \fBDLGK_OK\fP,
2869 .RS
2870 .TP 5
2871 .B WINDOW * \fIwin
2872 is the window with which to associate the buttons
2873 .TP 5
2874 .B const char * \fIname
2875 is the widget's binding name (usually the name of the widget).
2876 .TP 5
2877 .B const char ** \fIbuttons
2878 is the list of buttons
2879 .RE
2880 .\" ---------------------------------------------------------------------------
2881 .TP 5
2882 .B dlg_register_window
2883 For a given named widget's window, associate a binding table.
2884 .RS
2885 .TP 5
2886 .B WINDOW * \fIwin
2887 is the window with which to associate the buttons
2888 .TP 5
2889 .B const char * \fIname
2890 is the widget's binding name (usually the name of the widget).
2891 .TP 5
2892 .B DLG_KEYS_BINDING * \fIbinding
2893 is the binding table
2894 .RE
2895 .\" ---------------------------------------------------------------------------
2896 .TP 5
2897 .B dlg_remove_callback
2898 Remove a callback.
2899 .RS
2900 .TP 5
2901 .B DIALOG_CALLBACK \fI* p
2902 contains the callback information.
2903 .RE
2904 .\" ---------------------------------------------------------------------------
2905 .TP 5
2906 .B dlg_restore_vars
2907 Restore \fB\*p\fP's variables from the given variable (see \fBdialog_save_vars\fP).
2908 .RS
2909 .TP 5
2910 .B DIALOG_VARS * \fIsave
2911 is the variable from which to restore.
2912 .RE
2913 .IP
2914 The
2915 \fIDIALOG_VARS.input_length\fP and
2916 \fIDIALOG_VARS.input_result\fP members are treated specially,
2917 since these are used by a widget to pass data to the caller.
2918 They are not modified by this function.
2919 .\" ---------------------------------------------------------------------------
2920 .TP 5
2921 .B dlg_result_key
2922 Test a \fB\*p\fP internal keycode to see if it corresponds to one of the push
2923 buttons on the widget such as "OK".
2924 This is only useful if there are user-defined key bindings, since there are
2925 no built-in bindings that map directly to \fBDLGK_OK\fP, etc.
2926 Return true if a mapping was done.
2927 .RS
2928 .TP 5
2929 .B int \fIdialog_key
2930 is the \fB\*p\fP key to test
2931 .TP 5
2932 .B int \fIfkey
2933 is true if this is a function key
2934 .TP 5
2935 .B int * \fIresultp
2936 store the result of the mapping in the referenced location.
2937 .RE
2938 .\" ---------------------------------------------------------------------------
2939 .TP 5
2940 .B dlg_save_vars
2941 Save \fB\*p\fP's variables into the given variable (see \fBdialog_restore_vars\fP).
2942 .RS
2943 .TP 5
2944 .B DIALOG_VARS * \fIsave
2945 is the variable into which to save.
2946 .RE
2947 .\" ---------------------------------------------------------------------------
2948 .TP 5
2949 .B dlg_set_focus
2950 Set focus on the given window,
2951 making it display above other windows on the screen.
2952 .RS
2953 .TP 5
2954 .B WINDOW * \fIparent
2955 is the parent window (usually the top-level window of a widget)
2956 .TP 5
2957 .B WINDOW * \fIwin
2958 is the window on which to place focus (usually a subwindow of a widget)
2959 .RE
2960 .\" ---------------------------------------------------------------------------
2961 .TP 5
2962 .B dlg_set_result
2963 Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP
2964 .RS
2965 .TP 5
2966 .B const char * \fIstring
2967 is the new contents for the result
2968 .RE
2969 .\" ---------------------------------------------------------------------------
2970 .TP 5
2971 .B dlg_show_string
2972 Displays the string, shifted as necessary, to fit within the box and show
2973 the current character-offset.
2974 .RS
2975 .TP 5
2976 .B WINDOW * \fIwin
2977 is the window within which to display
2978 .TP 5
2979 .B const char * \fIstring
2980 is the string to display
2981 .TP 5
2982 .B int \fIoffset
2983 is the starting (character, not bytes) offset
2984 .TP 5
2985 .B chtype \fIattr
2986 is the window attribute to use for the string
2987 .TP 5
2988 .B int \fIy_base
2989 beginning row on screen
2990 .TP 5
2991 .B int \fIx_base
2992 beginning column on screen
2993 .TP 5
2994 .B int \fIx_last
2995 number of columns on screen
2996 .TP 5
2997 .B bool \fIhidden
2998 if true, do not echo input
2999 .TP 5
3000 .B bool \fIforce
3001 if true, force repaint
3002 .RE
3003 .\" ---------------------------------------------------------------------------
3004 .TP 5
3005 .B dlg_strclone
3006 duplicate the string, like \fBstrdup\fP.
3007 .RS
3008 .TP 5
3009 .B const char * \fIcprompt
3010 is the string to duplicate
3011 .RE
3012 .\" ---------------------------------------------------------------------------
3013 .TP 5
3014 .B dlg_strcmp
3015 compare two strings, ignoring case.
3016 .RS
3017 .TP 5
3018 .B const char \fI* a
3019 is one string
3020 .TP 5
3021 .B const char \fI* b
3022 is the other string
3023 .RE
3024 .\" ---------------------------------------------------------------------------
3025 .TP 5
3026 .B dlg_string_to_argv
3027 Convert a string to an argument vector
3028 returning an index (which must be freed by the caller).
3029 The string is modified (replacing gaps between tokens with nulls).
3030 .RS
3031 .TP 5
3032 .B char *\fIblob
3033 is the string to convert.
3034 .RE
3035 .\" ---------------------------------------------------------------------------
3036 .TP 5
3037 .B dlg_sub_window
3038 create a subwindow, e.g., for an input area of a widget
3039 .RS
3040 .TP 5
3041 .B WINDOW * \fIwin
3042 is the parent window
3043 .TP 5
3044 .B int \fIheight
3045 is the subwindow's height
3046 .TP 5
3047 .B int \fIwidth
3048 is the subwindow's width
3049 .TP 5
3050 .B int \fIy
3051 is the subwindow's top-row
3052 .TP 5
3053 .B int \fIx
3054 is the subwindow's left-column
3055 .RE
3056 .\" ---------------------------------------------------------------------------
3057 .TP 5
3058 .B dlg_tab_correct_str
3059 If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces.
3060 Return the converted result.
3061 The caller is responsible for freeing the string.
3062 .RS
3063 .TP 5
3064 .B char * \fIprompt
3065 is the string to convert
3066 .RE
3067 .\" ---------------------------------------------------------------------------
3068 .TP 5
3069 .B dlg_trace
3070 If the parameter is non-null, opens a trace file with that
3071 name and stores the file pointer in \fBdialog_state.trace\fP.
3072 .\" ---------------------------------------------------------------------------
3073 .TP 5
3074 .B dlg_trace_chr
3075 If \fBdialog_state.trace\fP is set,
3076 translate the parameters into a printable representation,
3077 log it on a "chr" line.
3078 .RS
3079 .TP 5
3080 .B int ch
3081 is the nominal keycode value.
3082 .TP 5
3083 .B int fkey
3084 is nonzero if the value is really a function key.
3085 Some of these may be values declared in the DLG_KEYS_ENUM.
3086 .RE
3087 .\" ---------------------------------------------------------------------------
3088 .TP 5
3089 .B dlg_trace_msg
3090 Write a formatted message to the trace file.
3091 .RS
3092 .TP 5
3093 .B const char * \fIfmt
3094 is the format of the \fBprintf\fP-like message to write.
3095 .TP 5
3096 .B ...
3097 .br
3098 are the variables to apply to the \fIfmt\fP format.
3099 .RE
3100 .IP
3101 Use the DLG_TRACE macro for portability, in case the trace
3102 feature is not compiled into the library.
3103 It uses an extra level of parentheses to work with a variable number of
3104 parameters, e.g.,
3105 .ES
3106 .EX
3107 DLG_TRACE(("this is dialog version %s\\n", dialog_version()));
3108 .EE
3109 .\" ---------------------------------------------------------------------------
3110 .TP 5
3111 .B dlg_trace_win
3112 If \fBdialog_state.trace\fP is set,
3113 log a printable picture of the given window.
3114 .\" ---------------------------------------------------------------------------
3115 .TP 5
3116 .B dlg_trim_string
3117 The \fBdialog\fP program uses this in each widget to adjust the
3118 message string,
3119 which may contain the newline character (referred to as '\\n')
3120 and/or the special substring "\\n"
3121 (which can be translated into a newline character).
3122 .IP
3123 There are several optional features:
3124 .RS
3125 .bP
3126 Unless \fBdialog_vars.no_nl_expand\fP is set,
3127 .RS
3128 .bP
3129 If it has "\\n" substrings,
3130 the function preserves extra spaces.
3131 For instance, spaces following a newline (substring or character)
3132 are preserved to use as an indentation.
3133 .bP
3134 The function changes embedded "\\n" substrings to '\\n' characters.
3135 .RE
3136 .bP
3137 If \fBdialog_vars.no_nl_expand\fP is not set,
3138 or if there are no "\\n" substrings,
3139 this function strips all extra spaces to simplify justification.
3140 .bP
3141 If \fBdialog_vars.cr_wrap\fP is set,
3142 the function preserves '\\n' newline characters.
3143 Otherwise, each '\\n' newline character is converted to a space.
3144 .bP
3145 Unless \fBdialog_vars.nocollapse\fP is set,
3146 each tab character is converted to a space,
3147 and sequences of blanks (space or tab) are reduced to a single space.
3148 .RE
3149 .RS
3150 .TP 5
3151 .B char * \fIsrc
3152 is the string to trim
3153 .RE
3154 .\" ---------------------------------------------------------------------------
3155 .TP 5
3156 .B dlg_unregister_window
3157 Remove the bindings for a given window.
3158 .RS
3159 .TP 5
3160 .B WINDOW * \fIwin
3161 is the window from which to remove bindings
3162 .RE
3163 .\" ---------------------------------------------------------------------------
3164 .TP 5
3165 .B dlg_update_gauge
3166 Update a gauge widget to show a different percentage value.
3167 .RS
3168 .TP 5
3169 .B void *\fIobjptr
3170 points to the gauge object to update.
3171 .TP 5
3172 .B int \fIpercent
3173 is the new percentage value to display.
3174 .RE
3175 .\" ---------------------------------------------------------------------------
3176 .TP 5
3177 .B dlg_yes_buttoncode
3178 Map the given button index for \fBdlg_yes_labels\fP into \fB\*p\fP's exit-code.
3179 .RS
3180 .TP 5
3181 .B int \fIbutton
3182 is the button index
3183 .RE
3184 .\" ---------------------------------------------------------------------------
3185 .TP 5
3186 .B dlg_yes_labels
3187 Return a list of buttons for Yes/No labels.
3188 .
3189 .\" ************************************************************************
3190 .SH SEE ALSO
3191 \fB\*p\fP (1).
3192 .
3193 .\" ************************************************************************
3194 .SH AUTHOR
3195 Thomas E. Dickey