diff options
Diffstat (limited to 'Build/source/utils/dialog/dialog-1.1-20110302/dialog.3')
| -rw-r--r-- | Build/source/utils/dialog/dialog-1.1-20110302/dialog.3 | 2912 |
1 files changed, 2912 insertions, 0 deletions
diff --git a/Build/source/utils/dialog/dialog-1.1-20110302/dialog.3 b/Build/source/utils/dialog/dialog-1.1-20110302/dialog.3 new file mode 100644 index 00000000000..521684a6121 --- /dev/null +++ b/Build/source/utils/dialog/dialog-1.1-20110302/dialog.3 @@ -0,0 +1,2912 @@ +.\" $Id: dialog.3,v 1.60 2011/03/02 10:19:12 tom Exp $ +.\" Copyright 2005-2010,2011 Thomas E. Dickey +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU Lesser General Public License, version 2.1 +.\" as published by the Free Software Foundation. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" Lesser General Public License for more details. +.\" +.\" You should have received a copy of the GNU Lesser General Public +.\" License along with this program; if not, write to +.\" Free Software Foundation, Inc. +.\" 51 Franklin St., Fifth Floor +.\" Boston, MA 02110, USA. +.\" +.\" definitions for renaming +.ds p dialog +.ds l dialog +.ds L Dialog +.ds D DIALOG +.\" Bulleted paragraph +.de bP +.IP \(bu 4 +.. +.TH \*D 3 "" "$Date: 2011/03/02 10:19:12 $" +.SH NAME +\*l \- widgets and utilities for the \*p program +.SH SYNOPSIS +.B cc [ flag ... ] file ... -l\*l [ library ... ] +.br +\ \ \ or +.br +.B cc `\*p-config --cflags` file ... `\*p-config --libs` ] +.sp +.B #include <\*l.h> +.PP +\fB\*L\fP +is a program that will let you to present a variety of questions or +display messages using dialog boxes from a shell script. +It is built from the \fB\*l\fP library, +which consists of several widgets +as well as utility functions that are used by the widgets +or the main program. +. +.SH DESCRIPTION +This manpage documents the features from \fI<\*l.h>\fP which +are likely to be important to developers using the widgets directly. +Some hints are also given for developing new widgets. +. +.\" ************************************************************************ +.SH DEFINITIONS +Exit codes (passed back to the main program for its use) +are defined with a "\fIDLG_EXIT_\fP prefix. +The defined constants can be mapped using environment variables +as described in \fB\*p\fP(1), +e.g., \fIDLG_EXIT_OK\fP corresponds to \fI$DIALOG_OK\fP. +.PP +Useful character constants which correspond to user input +are named with the "\fICHR_\fP" prefix, e.g., +\fICHR_BACKSPACE\fP. +.PP +Colors and video attributes are categorized and associated with +settings in the configuration file +(see the discussion of \fI$DIALOGRC\fP in \fB\*p\fP(1)). +The \fIDIALOG_ATR(n)\fP macro is used for defining the references +to the combined color and attribute table \fIdlg_color_table[]\fP. +.PP +The \fB\*p\fP application passes its command-line parameters +to the widget functions. Some of those parameters are single values, +but some of the widgets accept data as an array of values. +Those include checklist/radiobox, menubox and formbox. +When the \fB--item-help\fP option is given, an extra column +of data is expected. +The USE_ITEM_HELP(), CHECKBOX_TAGS, MENUBOX_TAGS and FORMBOX_TAGS +macros are used to hide this difference from the calling application. +.PP +Most of the other definitions found in \fI<\*l.h>\fP +are used for convenience in building the library or main program. +These include definitions based on the generated \fI<dlg_config.h>\fP header. + +.\" ************************************************************************ +.SH DATA STRUCTURES +All of the global data for the \fB\*l\fP library is stored in +a few structures: \fIDIALOG_STATE\fP, \fIDIALOG_VARS\fP and \fIDIALOG_COLORS\fP. +The corresponding \fIdialog_state\fP, \fIdialog_vars\fP and \fIdlg_color_table\fP +global variables should be initialized to zeros, +and then populated with the data to use. +A few of these must be nonzero for the corresponding widgets to function. +As as the case with function names, +variables beginning with "\fIdialog_\fP" +are designed for use by the calling application +while variables beginning with "\fIdlg_\fP" +are intended for lower levels, e.g., by the \fB\*l\fP library. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.all_windows +This is a linked list of all windows created by the library. +The \fBdlg_del_window\fP function uses this to locate windows which +may be redrawn after deleting a window. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.aspect_ratio +This corresponds to the command-line option "\fB--aspect-ratio\fP". +The value gives the application +some control over the box dimensions when using auto +sizing (specifying 0 for height and width). +It represents width / height. +The default is 9, which means 9 characters wide to every 1 line high. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.getc_callbacks +This is setup in \fIui_getc.c\fP to record windows which must be polled +for input, e.g,. to handle the background tailbox widget. +One window is designated as the foreground or control window. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.getc_redirect +If the control window for \fIDIALOG_STATE.getc_callbacks\fP is +closed, the list is transferred to this variable. +Closing all windows causes the application to exit. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.no_mouse +This corresponds to the command-line option "\fB--no-mouse\fP". +If true, \fB\*p\fP will not initialize (and enable) the mouse in +\fIinit_dialog\fP. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.output +This is set in the \fB\*p\fP application to the stream on +which the application and library functions may write text results. +Normally that is the standard error, +since the curses library prefers to write its data to the standard output. +Some scripts, trading portability for convenience, +prefer to write results to the standard output, +e.g., by using the "\fB--stdout\fP" option. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.output_count +This is incremented by \fIdlg_does_output\fP, +which is called by each widget that writes text to the output. +The \fB\*p\fP application uses that to decide if it should +also write a separator, i.e., +\fIDIALOG_STATE.separate_str\fP, +between calls to each widget. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.pipe_input +This is set in \fIinit_dialog\fP to a stream which can be used by the +\fBgauge\fP widget, which must be the application's standard input. +The \fB\*p\fP application calls \fIinit_dialog\fP normally with +\fIinput\fP set to the standard input, but optionally based on the +"\fB--input-fd\fP" option. +Since the application cannot read from +a pipe (standard input) and at the same time read +the curses input from the standard input, +it must allow for reopening the latter from either +a specific file descriptor, +or directly from the terminal. +The adjusted pipe stream value is stored in this variable. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.screen_initialized +This is set in \fIinit_dialog\fP and +reset in \fIend_dialog\fP. +It is used to check if curses has been initialized, +and if the \fIendwin\fP function must be called on exit. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.screen_output +This is set in \fIinit_dialog\fP to the output stream used +by the curses library. +Normally that is the standard output, +unless that happens to not be a terminal (and if \fIinit_dialog\fP can +successfully open the terminal directly). +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.separate_str +This corresponds to the command-line option "\fB--separate-widget\fP". +The given string +specifies a string that will separate the output on \fB\*p\fP's output from +each widget. +This is used to simplify parsing the result of a dialog with several widgets. +If this option is not given, +the default separator string is a tab character. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.tab_len +This corresponds to the command-line option "\fB--tab-len\fP \fInumber\fP". +Specify the number of spaces that a tab character occupies if the +"\fB--tab-correct\fP" +option is given. +The default is 8. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.trace_output +This corresponds to the command-line option "\fB--trace\fP \fIfile\fP". +It is the file pointer to which trace messages are written. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.use_colors +This is set in \fIinit_dialog\fP if the curses implementation supports color. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.use_scrollbar +This corresponds to the command-line option "\fB--scrollbar\fP". +If true, +draw a scrollbar to make windows holding scrolled data more readable. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.use_shadow +This corresponds to the command-line option "\fB--no-shadow\fP". +This is set in \fIinit_dialog\fP if the curses implementation supports color. +If true, +suppress shadows that would be drawn to the right and bottom of each dialog box. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_STATE.visit_items +This corresponds to the command-line option "\fB--visit-items\fP". +.\" --------------------------------------------------------------------------- +.PP +The \fB\*p\fP application resets the \fIdialog_vars\fP data before +accepting options to invoke each widget. +Most of the \fIDIALOG_VARS\fP members are set directly from \fB\*p\fP's +command-line options: +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.ascii_lines +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.backtitle +This corresponds to the command-line option "\fB--backtitle\fP \fIbacktitle\fP". +It specifies a +\fIbacktitle\fP +string to be displayed on the backdrop, at the top of the screen. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.beep_after_signal +This corresponds to the command-line option "\fB--beep-after\fP". +If true, beep after a user has completed a widget by pressing one of the buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.beep_signal +This corresponds to the command-line option "\fB--beep\fP". +It is obsolete. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.begin_set +This is true if the command-line option "\fB--begin y x\fP" was used. +It specifies the position of the upper left corner of a dialog box on the screen. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.begin_x +This corresponds to the \fIx\fP value from +the command-line option "\fB--begin\fP \fIy x\fP" (second value). +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.begin_y +This corresponds to the \fIy\fP value from +the command-line option "\fB--begin\fP \fIy x\fP" (first value). +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.cancel_label +This corresponds to the command-line option "\fB--cancel-label\fP \fIstring\fP". +The given \fIstring\fP overrides the label used for "Cancel" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.cant_kill +This corresponds to the command-line option "\fB--no-kill\fP". +If true, this tells +\fB\*p\fP +to put the +\fBtailboxbg\fP +box in the background, +printing its process id to \fB\*p\fP's output. +SIGHUP is disabled for the background process. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.colors +This corresponds to the command-line option "\fB--colors\fP". +If true, interpret embedded "\\Z" sequences in the dialog text +by the following character, +which tells \fB\*p\fP to set colors or video attributes: +0 through 7 are the ANSI codes used in curses: +black, +red, +green, +yellow, +blue, +magenta, +cyan and +white respectively. +Bold is set by 'b', reset by 'B'. +Reverse is set by 'r', reset by 'R'. +Underline is set by 'u', reset by 'U'. +The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text +bright red. +Restore normal settings with "\\Zn". +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.column_separator +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.cr_wrap +This corresponds to the command-line option "\fB--cr-wrap\fP". +If true, +interpret embedded newlines in the dialog text as a newline on the screen. +Otherwise, \fB\*p\fR will only wrap lines where needed to fit inside the text box. +Even though you can control line breaks with this, +\fB\*p\fR will still wrap any lines that are too long for the width of the box. +Without cr-wrap, the layout of your text may be formatted to look nice +in the source code of your script without affecting the way it will +look in the dialog. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.date_format +This corresponds to the command-line option "\fB--date-format\fP \fIstring\fP". +If the host provides \fBstrftime\fP, and the value is nonnull, +the calendar widget uses this to format its output. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.default_item +This corresponds to the command-line option "\fB--default-item\fP \fIstring\fP". +The given string is used as +the default item in a checklist, form or menu box. +Normally the first item in the box is the default. +.IP \fIDIALOG_VARS.defaultno +This corresponds to the command-line option "\fB--defaultno\fP". +If true, +make the default value of the +\fByes/no\fP +box a +.BR No . +Likewise, make the default button of widgets that provide "OK" and "Cancel" +a \fBCancel\fP. +If \fB--nocancel\fP was given that option overrides this, +making the default button always "Yes" (internally the same as "OK"). +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.dlg_clear_screen +This corresponds to the command-line option "\fB--clear\fP". +This option is implemented in the main program, not the library. +If true, +the screen will be cleared on exit. +This may be used alone, without other options. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.exit_label +This corresponds to the command-line option "\fB--exit-label string\fP". +The given string overrides the label used for "EXIT" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.extra_button +This corresponds to the command-line option "\fB--extra-button\fP". +If true, some widgets show an extra button, +between "OK" and "Cancel" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.extra_label +This corresponds to the command-line option "\fB--extra-label\fP \fIstring\fP". +The given string overrides the label used for "Extra" buttons. +Note: for inputmenu widgets, this defaults to "Rename". +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.formitem_type +This is set by the command-line option "\fB--passwordform\fP" +to tell the form widget that its text fields should be treated like +password widgets. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.help_button +This corresponds to the command-line option "\fB--help-button\fP". +If true, some widgets show a help-button after "OK" and "Cancel" buttons, +i.e., in checklist, radiolist and menu boxes. +If \fB--item-help\fR is also given, on exit +the return status will be the same as for the "OK" button, +and the item-help text will be written to \fB\*p\fP's output after the token "HELP". +Otherwise, the return status will indicate that the Help button was pressed, +and no message printed. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.help_label +This corresponds to the command-line option "\fB--help-label\fP \fIstring\fP". +The given string overrides the label used for "Help" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.help_status +This corresponds to the command-line option "\fB--help-status\fP". +If true, and the the help-button is selected, +writes the checklist or radiolist information +after the item-help "HELP" information. +This can be used to reconstruct the state of a checklist after processing +the help request. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.input_length +This is nonzero if \fIDIALOG_VARS.input_result\fP is allocated, +versus being a pointer to the user's local variables. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.input_menu +This flag is set to denote whether the menubox widget +implements a menu versus a inputmenu widget. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.input_result +This may be either a user-supplied buffer, +or a buffer dynamically allocated by the library, +depending on \fIDIALOG_VARS.input_length\fP: +.RS +.bP +If \fIDIALOG_VARS.input_length\fP is zero, +this is a pointer to user buffer (on the stack, or static). +The buffer size is assumed to be \fBMAX_LEN\fP, +which is defined in \fI<\*l.h>\fP. +.bP +When \fIDIALOG_VARS.input_length\fP is nonzero, +this is a dynamically-allocated buffer used by the widgets to return +printable results to the calling application. +.RE +.IP +Certain widgets copy a result to this buffer. +If the pointer is NULL, or if the length is insufficient for +the result, then the \fB\*l\fP library allocates a buffer which is large enough, +and sets \fIDIALOG_VARS.input_length\fP. +Callers should check for this case if they have supplied their own buffer. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.insecure +This corresponds to the command-line option "\fB--insecure\fP". +If true, make the password widget friendlier but less secure, +by echoing asterisks for each character. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.item_help +This corresponds to the command-line option "\fB--item-help\fP". +If true, +interpret the tags data for checklist, radiolist and menu boxes +adding a column whose text is displayed in the bottom line of the +screen, for the currently selected item. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.keep_tite +This is set by the command-line option "\fB--keep-tite\fP" +to tell \fB\*p\fP to not attempt to cancel the terminal initialization +(termcap \fIti\fP/\fIte\fP) sequences which correspond to xterm's alternate-screen +switching. +Normally \fB\*p\fP does this to avoid flickering when run several times +in a script. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.keep_window +This corresponds to the command-line option "\fB--keep-window\fP". +If true, do not remove/repaint the window on exit. +This is useful for keeping the window contents visible when several +widgets are run in the same process. +Note that curses will clear the screen when starting a new process. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.max_input +This corresponds to the command-line option "\fB--max-input\fP \fIsize\fP". +Limit input strings to the given size. +If not specified, the limit is 2048. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.no_label +This corresponds to the command-line option "\fB--no-label\fP \fIstring\fP". +The given string overrides the label used for "No" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.no_lines +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.nocancel +This corresponds to the command-line option "\fB--no-cancel\fP". +If true, +suppress the "Cancel" button in checklist, inputbox and menu box modes. +A script can still test if the user pressed the ESC key to cancel to quit. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.nocollapse +This corresponds to the command-line option "\fB--no-collapse\fP". +Normally \fB\*p\fR converts tabs to spaces and reduces multiple +spaces to a single space for text which is displayed in a message boxes, etc. +It true, that feature is disabled. +Note that \fB\*p\fR will still wrap text, subject to the \fB--cr-wrap\fR +option. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.nook +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.ok_label +This corresponds to the command-line option "\fB--ok-label\fP \fIstring\fP". +The given string overrides the label used for "OK" buttons. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.print_siz +This corresponds to the command-line option "\fB--print-size\fP". +If true, +each widget prints its size to \fB\*p\fP's output when it is invoked. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.quoted +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.separate_output +This corresponds to the command-line option "\fB--separate-output\fP". +If true, +checklist widgets output result one line at a time, with no quoting. +This facilitates parsing by another program. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.single_quoted +This corresponds to the command-line option "\fB--single-quoted\fP". +If true, +Use single-quoting as needed (and no quotes if unneeded) for the +output of checklist's as well as the item-help text. +If this option is not set, \fB\*p\fP uses double quotes around each item. +That requires occasional use of backslashes to make the output useful in +shell scripts. +.IP \fIDIALOG_VARS.size_err +This corresponds to the command-line option "\fB--size-err\fP". +If true, +check the resulting size of a dialog box before trying to use it, +printing the resulting size if it is larger than the screen. +(This option is obsolete, since all new-window calls are checked). +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.sleep_secs +This corresponds to the command-line option "\fB--sleep\fP \fIsecs\fP". +This option is implemented in the main program, not the library. +If nonzero, this is the number of seconds after to delay after processing a dialog box. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.tab_correct +This corresponds to the command-line option "\fB--tab-correct\fP". +If true, convert each tab character of the text to one or more spaces. +Otherwise, tabs are rendered according to the curses library's interpretation. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.time_format +This corresponds to the command-line option "\fB--time-format\fP \fIstring\fP". +If the host provides \fBstrftime\fP, and the value is nonnull, +the timebox widget uses this to format its output. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.timeout_secs +This corresponds to the command-line option "\fB--timeout\fP \fIsecs\fP". +If nonzero, timeout input requests (exit with error code) +if no user response within the given number of seconds. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.title +This corresponds to the command-line option "\fB--title\fP \fItitle\fP". +Specifies a +\fItitle\fP +string to be displayed at the top of the dialog box. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.trim_whitespace +This corresponds to the command-line option "\fB--trim\fP". +If true, eliminate leading blanks, +trim literal newlines and repeated blanks from message text. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.visit_items +This corresponds to the command-line option "\fB--visit-items\fP". +Modify the tab-traversal of checklist, radiobox, menubox and inputmenu +to include the list of items as one of the states. +This is useful as a visual aid, +i.e., the cursor position helps some users. +.\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.yes_label +This corresponds to the command-line option "\fB--yes-label\fP \fIstring\fP". +The given string overrides the label used for "Yes" buttons. +. +.\" ************************************************************************ +.\" ************************************************************************ +.SH WIDGETS +Functions that implement major functionality for the command-line \fB\*p\fP +program, e.g., widgets, have names beginning "\fIdialog_\fP". + +All dialog boxes have at least three parameters: +.TP 5 +\fItitle\fP +the caption for the box, shown on its top border. +.TP 5 +\fIheight\fP +the height of the dialog box. +.TP 5 +\fIwidth\fP +the width of the dialog box. +.PP +Other parameters depend on the box type. +. +.\" ************************************************************************ +.IP \fBdialog_calendar +implements the "\fB--calendar\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP subtitle +is the prompt text shown within the widget. +.IP height +is the height excluding the fixed-height calendar grid. +.IP width +is the overall width of the box, +which is adjusted up to the calendar grid's minimum width if needed. +.IP day +is the initial day of the week shown, +counting zero as Sunday. +If the value is negative, the current day of the week is used. +.IP month +is the initial month of the year shown, +counting one as January. +If the value is negative, the current month of the year is used. +.IP year +is the initial year shown. +If the value is negative, the current year is used. +.RE +.\" ************************************************************************ +.IP \fBdialog_checklist +implements the "\fB--checklist\fP" and "\fB--radiolist\fP" options +depending on the \fIflag\fP parameter. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.IP width +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.IP list_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.IP item_no +is the number of rows in \fIitems\fP. +.IP items +is an array of strings which is viewed either as a list of rows +.RS +\fItag item status \fR +.RE +.IP +or +.RS +\fItag item status help\fR +.RE +.IP +depending on whether \fIdialog_vars.item_help\fP is set. +.IP flag +is either \fIFLAG_CHECK\fP, for checklists, +or \fIFLAG_RADIO\fP for radiolists. +.RE +.\" ************************************************************************ +.IP \fBdialog_dselect +implements the "\fB--dselect\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP path +is the preselected value to show in the input-box, +which is used also to set the directory- and file-windows. +.IP height +is the height excluding the minimum needed to show the dialog box framework. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.RE +.\" ************************************************************************ +.IP \fBdialog_editbox +implements the "\fB--editbox\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP file +is the name of the file from which to read. +.IP height +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.IP width +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.RE +.\" ************************************************************************ +.IP \fBdialog_form +implements the "\fB--form\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.IP width +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.IP form_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.IP item_no +is the number of rows in \fIitems\fP. +.IP items +is an array of strings which is viewed either as a list of rows +.RS +\fIName NameY NameX Text TextY TextX FLen ILen\fR +.RE +.IP +or +.RS +\fIName NameY NameX Text TextY TextX FLen ILen Help\fR +.RE +.IP +depending on whether \fIdialog_vars.item_help\fP is set. +.RE +.\" ************************************************************************ +.IP \fBdialog_fselect +implements the "\fB--fselect\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP path +is the preselected value to show in the input-box, +which is used also to set the directory- and file-windows. +.IP height +is the height excluding the minimum needed to show the dialog box framework. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.RE +.\" ************************************************************************ +.IP \fBdialog_gauge +implements the "\fB--gauge\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP percent +is the percentage to show in the progress bar. +.RE +.\" ************************************************************************ +.IP \fBdialog_inputbox +implements the "\fB--inputbox\fP" or +"\fB--password\fP" option, depending on the value of \fIpassword\fP. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP init +is the initial value of the input box, whose length is taken into account +when auto-sizing the width of the dialog box. +.IP password +if true, causes typed input to be echoed as asterisks. +.RE +.\" ************************************************************************ +.IP \fBdialog_menu +implements the "\fB--menu\fP" or "\fB--inputmenu\fP" option +depending on whether \fIdialog_vars.input_menu\fP is set. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP menu_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.IP item_no +is the number of rows in \fIitems\fP. +.IP items +is an array of strings which is viewed either as a list of rows +.RS +\fItag item\fR +.RE +.IP +or +.RS +\fItag item help\fR +.RE +.IP +depending on whether \fIdialog_vars.item_help\fP is set. +.RE +.\" ************************************************************************ +.IP \fBdialog_mixedform +implements the "\fB--mixedform\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.IP width +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.IP form_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.IP item_no +is the number of rows in \fIitems\fP. +.IP items +is an array of strings which is viewed either as a list of rows +.RS +\fIName NameY NameX Text TextY TextX FLen ILen Ityp\fR +.RE +.IP +or +.RS +\fIName NameY NameX Text TextY TextX FLen ILen Ityp Help\fR +.RE +.IP +depending on whether \fIdialog_vars.item_help\fP is set. +.RE +.\" ************************************************************************ +.IP \fBdialog_mixedgauge +implements the "\fB--mixedgauge\fP" option +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the caption text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP percent +is the percentage to show in the progress bar. +.IP item_no +is the number of rows in \fIitems\fP. +.IP items +is an array of strings which is viewed as a list of \fItag\fP and \fIitem\fP values. +The \fItag\fP values are listed, one per row, in the list at the top of +the widget. +.IP +The \fIitem\fP values are decoded: digits 0-9 are the following strings +.RS +.IP 0 +Succeeded +.IP 1 +Failed +.IP 2 +Passed +.IP 3 +Completed +.IP 4 +Checked +.IP 5 +Done +.IP 6 +Skipped +.IP 7 +In Progress +.IP 8 +(blank) +.IP 9 +N/A +.RE +.IP +A string with a leading "-" character is centered, marked with "%". +For example, "-75" is displayed as "75%". +Other strings are displayed as is. +.RE +.\" ************************************************************************ +.IP \fBdialog_msgbox +implements the "\fB--msgbox\fP" or "\fB--infobox\fP" option +depending on whether \fIpauseopt\fP is set. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP pauseopt +if true, an "OK" button will be shown, +and the dialog will wait for it to complete. +With an "OK" button, it is denoted a "msgbox", +without an "OK" button, it is denoted an "infobox". +.RE +.\" ************************************************************************ +.IP \fBdialog_pause +implements the "\fB--pause\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP seconds +is the timeout to use for the progress bar. +.RE +.\" ************************************************************************ +.IP \fBdialog_prgbox +implements the "\fB--prgbox\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +If empty or null, no prompt is shown. +.IP command +is the name of the command to execute. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP pauseopt +if true, an "OK" button will be shown, +and the dialog will wait for it to complete. +.RE +.\" ************************************************************************ +.IP \fBdialog_progressbox +implements the "\fB--progressbox\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +If empty or null, no prompt is shown. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.RE +.\" ************************************************************************ +.IP \fBdialog_tailbox +implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option +depending on whether \fIbg_task\fP is set. +.RS +.IP title +is the title on the top of the widget. +.IP file +is the name of the file to display in the dialog. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP bg_task +if true, +the window is added to the callback list in \fIdialog_state\fP, +and the application will poll for the window to be updated. +Otherwise an "OK" button is added to the window, +and it will be closed when the button is activated. +.RE +.\" ************************************************************************ +.IP \fBdialog_textbox +implements the "\fB--textbox\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP file +is the name of the file to display in the dialog. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.RE +.\" ************************************************************************ +.IP \fBdialog_timebox +implements the "\fB--timebox\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP subtitle +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP hour +is the initial hour shown. +If the value is negative, the current hour is used. +Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24. +.IP minute +is the initial minute shown. +If the value is negative, the current minute is used. +Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60. +.IP second +is the initial second shown. +If the value is negative, the current second is used. +Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60. +.RE +.\" ************************************************************************ +.IP \fBdialog_yesno +implements the "\fB--yesno\fP" option. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.RE +. +.\" ************************************************************************ +.SH UTILITY FUNCTIONS +Most functions that implement lower-level +functionality for the command-line \fB\*p\fP +program or widgets, have names beginning "\fIdlg_\fP". +Bowing to longstanding usage, the functions that initialize the +display and end it are named \fIinit_dialog\fP and \fIend_dialog\fP. +.PP +The only non-widget function whose name begins with "\fIdialog_\fP" +is \fIdialog_version\fP, which returns the version number of the +library as a string. +. +.PP +Here is a brief summary of the utility functions and their parameters: +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_callback +Add a callback, used to allow polling input from multiple tailbox +widgets. +.RS +.TP 5 +.B DIALOG_CALLBACK *\fIp\fP +contains the callback information. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_callback_ref +Like \fBdlg_add_callback\fP, but passes a reference to the \fBDIALOG_CALLBACK\fP +as well as a pointer to a cleanup function which will be called when the +associated input ends. +.RS +.TP 5 +.B DIALOG_CALLBACK **\fIp\fP +points to the callback information. +This is a reference to the pointer so that the caller's pointer can be +zeroed when input ends. +.TP 5 +.B DIALOG_FREEBACK \fIfunc\fP +function to call when input ends, e.g., to free caller's additional data. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_quoted +Add a quoted string to the result buffer (see \fBdlg_add_result\fP). +.RS +.TP 5 +.B char * \fIstring +is the string to add. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_result +Add a quoted string to the result buffer \fBdialog_vars.input_result\fP. +.RS +.TP 5 +.B char * \fIstring +is the string to add. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_separator +Add an output-separator to the result buffer \fBdialog_vars.input_result\fP. +If \fBdialog_vars.output_separator\fP is set, use that. +Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline. +If neither is set, use a space. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_add_string +Add a quoted or unquoted string to the result buffer +(see \fBdlg_add_quoted\fP) and \fBdlg_add_result\fP), +according to whether \fBdialog_vars.quoted\fP is true. +.RS +.TP 5 +.B char * \fIstring +is the string to add. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_align_columns +Copy and reformat an array of pointers to strings, aligning according to +the column separator \fBdialog_vars.column_separator\fP. +If no column separator is set, the array will be unmodified; +otherwise it is copied and reformatted. +.IP +Caveat: This function is only implemented for 8-bit characters. +.RS +.TP 5 +.B char **\fItarget +This is the array to reformat. +It points to the first string to modify. +.TP 5 +.B int \fIper_row +This is the size of the struct for each row of the array. +.TP 5 +.B int \fInum_rows +This is the number of rows in the array. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_asciibox +returns its parameter transformed to the +corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP. +If the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns 0. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_attr_clear +Set window to the given attribute. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B int \fIheight +is the number of rows to update. +.TP 5 +.B int \fIwidth +is the number of columns to update. +.TP 5 +.B chtype \fIattr +is the attribute, e.g., \fBA_BOLD\fP. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_auto_size +Automatically size the window used for a widget. +If the given height or width are zero, +justify the \fIprompt\fP text and return the actual limits. +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B const char * \fIprompt +is the message text which will be displayed in the widget, +used here to determine how large the widget should be. +.TP 5 +.B int * \fIheight +is the nominal height. +.TP 5 +.B int * \fIwidth +is the nominal width. +.TP 5 +.B int \fIboxlines +is the number of lines to reserve in the vertical direction. +.TP 5 +.B int \fImincols +is the minimum number of columns to use. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_auto_sizefile +Like \fBdlg_auto_size\fP, but use a file contents to decide how large +the widget should be. +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B const char * \fIfile +is the name of the file. +.TP 5 +.B int * \fIheight +is the nominal height. +If it is -1, use the screen's height after subtracting \fBdialog_vars.begin_y\fP +if \fBdialog_vars.begin_set\fP is true. +.TP 5 +.B int \fI*width +is the nominal width. +If it is -1, use the screen's width after subtracting \fBdialog_vars.begin_x\fP +if \fBdialog_vars.begin_set\fP is true. +.TP 5 +.B int \fIboxlines +is the number of lines to reserve on the screen for drawing boxes. +.TP 5 +.B int \fImincols +is the number of columns to reserve on the screen for drawing boxes. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_beeping +If \fBdialog_vars.beep_signal\fP is nonzero, +this calls \fBbeep\fP once and sets +\fBdialog_vars.beep_signal\fP to zero. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_boxchar +returns its parameter transformed as follows: +.RS +.TP 3 +.B - +if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set. +.TP 3 +.B - +if \fBdialog_vars.ascii_lines\fP is set, returns the corresponding "+" or "-", etc. for the line-drawing characters used in \fB\*p\fP. +.TP 3 +.B - +otherwise, if \fBdialog_vars.no_lines\fP is set, returns a space for the line-drawing characters. +.TP 3 +.B - +if the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns the parameter unchanged. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_box_x_ordinate +returns a suitable x-ordinate (column) for a new widget. +If \fBdialog_vars.begin_set\fP is 1, +use \fBdialog_vars.begin_x\fP; +otherwise center the widget on the screen (using the \fIwidth\fP parameter). +.RS +.TP 5 +.B int \fIwidth +is the width of the widget. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_box_y_ordinate +returns a suitable y-ordinate (row) for a new widget. +If \fBdialog_vars.begin_set\fP is 1, +use \fBdialog_vars.begin_y\fP; +otherwise center the widget on the screen (using the \fIheight\fP parameter). +.RS +.TP 5 +.B int \fIheight +is the height of the widget. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_button_count +Count the buttons in the list. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_button_layout +Make sure there is enough space for the buttons by +computing the width required for their labels, +adding margins and limiting based on the screen size. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int * \fIlimit +the function sets the referenced \fIlimit\fP to the width required for +the buttons (limited by the screen size) +if that is wider than the passed-in limit. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_button_sizes +Compute the size of the button array in columns. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int \fIvertical +is true if the buttons are arranged in a column rather than a row. +.TP 5 +.B int * \fIlongest +Return the total number of columns in the referenced location. +.TP 5 +.B int * \fIlength +Return the longest button's columns in the referenced location. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_button_x_step +Compute the step-size needed between elements of the button array. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int \fIlimit +is the maximum number of columns to allow for the buttons. +.TP 5 +.B int * \fIgap +store the nominal gap between buttons in the referenced location. +This is constrained to be at least one. +.TP 5 +.B int * \fImargin +store the left+right total margins (for the list of buttons) in the referenced +location. +.TP 5 +.B int * \fIstep +store the step-size in the referenced location. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_button_to_char +Find the first uppercase character in the label, which we may use for an +abbreviation. +If the label is empty, return -1. +If no uppercase character is found, return 0. +Otherwise return the uppercase character. +.RS +.TP 5 +.B const char * \fIlabel +is the label to test. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_calc_list_width +Calculate the minimum width for the list, assuming none of the items +are truncated. +.RS +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP. +.TP 5 +.B DIALOG_LISTITEM * \fIitems +contains a \fIname\fP and \fItext\fP field, +e.g., for checklists or radiobox lists. +The function returns the sum of the widest columns +needed for of each of these fields. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_calc_listh +Calculate new height and list_height values. +.RS +.TP 5 +.B int * \fIheight +on input, is the height without adding the list-height. +On return, this contains the total list-height and is the +actual widget's height. +.TP 5 +.B int * \fIlist_height +on input, is the requested list-height. +On return, this contains the number of rows available for displaying +the list after taking into account the screen size and +the \fBdialog_vars.begin_set\fP and \fBdialog_vars.begin_y\fP variables. +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP in the list. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_calc_listw +This function is obsolete, provided for library-compatibility. +It is replaced by \fIdlg_calc_list_width\fP. +.RS +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP. +.TP 5 +.B char ** \fIitems +is a list of character pointers. +.TP 5 +.B int \fIgroup +is the number of items in each group, e.g., the second array index. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_char_to_button +Given a list of button labels, +and a character which may be the abbreviation for one, find it, if it exists. +An abbreviation will be the first character +which happens to be capitalized in the label. +If the character is found, return its index within the list of \fIlabels\fP. +Otherwise, return \fBDLG_EXIT_UNKNOWN\fP. +.RS +.TP 5 +.B int \fIch +is the character to find. +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_checklist +This entrypoint provides the \fB--checklist\fP or \fP--radiolist\fP +functionality without the limitations of \fB\*p\fP's command-line syntax +(compare to \fBdialog_checklist\fP). +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B const char * \fIcprompt +is the prompt text shown within the widget. +.TP 5 +.B int \fIheight +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIlist_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP. +.TP 5 +.B DIALOG_LISTITEM * \fIitems +This is a list of the items to display in the checklist. +.TP 5 +.B const char * \fIstates +This is a list of characters to display for the given states. +Normally a checklist provides true (1) and false (0) values, +which the widget displays as "*" and space, respectively. +An application may set this parameter to an arbitrary null-terminated string. +The widget determines the number of states from the length of this string, +and will cycle through the corresponding display characters as the user +presses the space-bar. +.TP 5 +.B int \fIflag +This is should be one of \fBFLAG_CHECK\fP or \fPFLAG_RADIO\fP, +depending on whether the widget should act as a checklist or radiobox. +.TP 5 +.B int * \fIcurrent_item +The widget sets the referenced location to the index of the current display +item (cursor) when it returns. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_check_scrolled +given a function key (or other key that was mapped to a function key), +check if it is one of the up/down scrolling functions: +.sp +.RS + DLGK_PAGE_FIRST, +.br + DLGK_PAGE_LAST, +.br + DLGK_GRID_UP, +.br + DLGK_GRID_DOWN, +.br + DLGK_PAGE_PREV or +.br + DLGK_PAGE_NEXT. +.RE +.fi +.IP +Some widgets use these key bindings for scrolling the prompt-text up and +down, to allow for display in very small windows. +.IP +The function returns 0 (zero) if it finds one of these keys, +and -1 if not. +.RS +.TP 5 +.B int \fIkey +is the function-key to check +.TP 5 +.B int \fIlast +is the number of lines +which would be used to display the scrolled prompt in +an arbitrarily tall window. +It is used here to check limits for the \fIoffset\fP value. +.TP 5 +.B int \fIpage +this is the available height for writing scrolled text, +which is smaller than the window if it contains buttons. +.TP 5 +.B bool * \fIshow +on return, holds TRUE if \fBdlg_print_scrolled\fP should be used to redisplay +the prompt text. +.TP 5 +.B int * \fIoffset +on entry, holds the starting line number (counting from zero) +last used for \fBdlg_print_scrolled\fP. +On return, holds the updated starting line number. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_clear +Set window to the default \fB\*p\fP screen attribute. +This is set in the rc-file with \fBscreen_color\fP. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_clr_result +Free storage used for the result buffer (\fBdialog_vars.input_result\fP). +The corresponding pointer is set to NULL. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_color_count +Return the number of colors that can be configured in \fB\*p\fP. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_color_setup +Initialize the color pairs used in \fB\*p\fP. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_count_argv +Count the entries in an argument vector. +.RS +.TP 5 +.B argv +Points to the argument vector. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_count_columns +Returns the number of columns used for a string. +This is not necessarily the number of bytes in a string. +.RS +.TP 5 +.B const char * \fIstring +is the string to measure. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_count_wchars +Returns the number of wide-characters in the string. +.RS +.TP 5 +.B const char * \fIstring +is the string to measure. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_create_rc +Create a configuration file, +i.e., write internal tables to a file which can be read back by \fB\*p\fP +as an rc-file. +.RS +.TP 5 +.B const char * \fIfilename +is the name of the file to write to. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_ctl_size +If \fBdialog_vars.size_err\fP is true, +check if the given window size is too large to fit on the screen. +If so, exit with an error reporting the size of the window. +.RS +.TP 5 +.B int \fIheight +is the window's height +.TP 5 +.B int \fIwidth +is the window's width +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_default_formitem +If \fBdialog_vars.default_item\fP is not null, +find that name by matching the \fIname\fP field in the list of form \fIitems\fP. +If found, return the index of that item in the list. +Otherwise, return zero. +.RS +.TP 5 +.B DIALOG_FORMITEM * \fIitems +is the list of items to search. +It is terminated by an entry with a null \fIname\fP field. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_default_item +This function is obsolete, provided for library-compatibility. +It is replaced by \fIdlg_default_formitem\fP and \fIdlg_default_listitem\fP. +.RS +.TP 5 +.B char ** \fIitems +is the list of items to search. +.TP 5 +.B int \fIllen +is the number of items in each group, e.g., the second array index. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_defaultno_button +If \fBdialog_vars.defaultno\fP is true, and \fBdialog_vars.nocancel\fP is not, +find the button-index for the "Cancel" button. +Otherwise, return the index for "OK" (always zero). +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_del_window +Remove a window, repainting everything else. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to remove. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_does_output +This is called each time a widget is invoked which may do output. +It increments \fBdialog_state.output_count\fP, +so the output function in \fB\*p\fP can test this and add a separator. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_arrows +Draw up/down arrows on a window, e.g., for scrollable lists. +It calls \fBdlg_draw_arrows2\fP using the +\fImenubox_color\fP and \fImenubox_border_color\fP attributes. +.RS +.TP 5 +.B WINDOW * \fIdialog +is the window on which to draw an arrow. +.TP 5 +.B int \fItop_arrow +is true if an up-arrow should be drawn at the top of the window. +.TP 5 +.B int \fIbottom_arrow +is true if an down-arrow should be drawn at the bottom of the window. +.TP 5 +.B int \fIx +is the zero-based column within the window on which to draw arrows. +.TP 5 +.B int \fItop +is the zero-based row within the window on which to draw up-arrows +as well as a horizontal line to show the window's top. +.TP 5 +.B int \fIbottom +is the zero-based row within the window on which to draw down-arrows +as well as a horizontal line to show the window's bottom. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_arrows2 +Draw up/down arrows on a window, e.g., for scrollable lists. +.RS +.TP 5 +.B WINDOW * \fIdialog +is the window on which to draw an arrow. +.TP 5 +.B int \fItop_arrow +is true if an up-arrow should be drawn at the top of the window. +.TP 5 +.B int \fIbottom_arrow +is true if an down-arrow should be drawn at the bottom of the window. +.TP 5 +.B int \fIx +is the zero-based column within the window on which to draw arrows. +.TP 5 +.B int \fItop +is the zero-based row within the window on which to draw up-arrows +as well as a horizontal line to show the window's top. +.TP 5 +.B int \fIbottom +is the zero-based row within the window on which to draw down-arrows +as well as a horizontal line to show the window's bottom. +.TP 5 +.B chtype \fIattr +is the window's background attribute. +.TP 5 +.B chtype \fIborderattr +is the window's border attribute. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_bottom_box +Draw a partial box at the bottom of a window, +e.g., to surround a row of buttons. +It is designed to merge with an existing box around +the whole window, so it uses tee-elements rather than corner-elements +on the top corners of this box. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_box +Draw a rectangular box with line drawing characters. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B int \fIy +is the top row of the box. +.TP 5 +.B int \fIx +is the left column of the box. +.TP 5 +.B int \fIheight +is the height of the box. +.TP 5 +.B int \fIwidth +is the width of the box. +.TP 5 +.B chtype \fIboxchar +is used to color the right/lower edges. +It also is fill-color used for the box contents. +.TP 5 +.B chtype \fIborderchar +is used to color the upper/left edges. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_buttons +Print a list of buttons at the given position. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B int \fIy +is the starting row. +.TP 5 +.B int \fIx +is the starting column. +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int \fIselected +is the index within the list of the selected button. +.TP 5 +.B int \fIvertical +is true if the buttons are arranged in a column rather than a row. +.TP 5 +.B int \fIlimit +is the number of columns (or rows if \fIvertical\fP) allowed for the display. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_scrollbar +If \fBdialog_state.use_scrollbar\fP is set, +draw a scrollbar on the right margin of windows holding scrollable data. +Also (whether or not the scrollbar is drawn), +annotate the bottom margin of the window with the percentage of data +by the bottom of that window, +and call \fBdlg_draw_arrows2\fP to put markers on the window showing +when more data is available. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window in which the data is scrolled. +Because \fIleft\fP, \fIright\fP, \fItop\fP, \fIbottom\fP +are passed as parameters, this window can contain additional data. +.TP 5 +.B long \fIfirst_data +is the zero-based index to the first row of data in the current window. +.TP 5 +.B long \fIthis_data +is the zero-based index to the current row of data. +.TP 5 +.B long \fInext_data +is the zero-based index to the next data after the current row. +.TP 5 +.B long \fItotal_data +is the total number of rows of data. +.TP 5 +.B int \fIleft +is the zero-based left margin/column of the window. +The up/down arrows are draw inset by 5 columns from this point. +.TP 5 +.B int \fIright +is the zero-based right margin/column of the window. +The scrollbar is drawn flush against this column. +.TP 5 +.B int \fItop +is the zero-based row within the window on which to draw up-arrows +as well as a horizontal line to show the window's top. +.TP 5 +.B int \fIbottom +is the zero-based row within the window on which to draw down-arrows +as well as a horizontal line to show the window's bottom. +.TP 5 +.B chtype \fIattr +is the window's background attribute. +.TP 5 +.B chtype \fIborderattr +is the window's border attribute. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_shadow +Draw shadows along the right and bottom edge of a window to give it +a 3-dimensional look. +(The height, etc., may not be the same as the window's actual values). +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B int \fIheight +is the height of the window. +.TP 5 +.B int \fIwidth +is the width of the window. +.TP 5 +.B int \fIy +is the top row of the window. +.TP 5 +.B int \fIx +is the left column of the window. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_draw_title +Draw a title centered at the top of the window. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_dump_keys +Write all user-defined key-bindings to the given stream, +e.g., as part of \fBdlg_create_rc\fP. +.RS +.TP 5 +.B FILE * \fIfp +is the stream on which to write the bindings. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_eat_argv +Remove one or more items from an argument vector. +.RS +.TP 5 +.B int *argcp +in/out parameter giving the length of the argument vector. +.B char ***argvp +in/out parameter pointing to the argument vector. +.B int start +starting index. +.B int count +number of arguments to remove. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_edit_offset +Given the character-offset in the string, +returns the display-offset where +\fB\*p\fP should position the cursor. +In this context, "characters" may be multicolumn, +since the string can be a multibyte character string. +.RS +.TP 5 +.B char * \fIstring +is the string to analyze +.TP 5 +.B int \fIoffset +is the character-offset +.TP 5 +.B int \fIx_last +is a limit on the column positions that can be used, +e.g., the window's size. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_edit_string +Updates the string and character-offset, given various editing characters +or literal characters which are inserted at the character-offset. +Returns true if an editing change was made (and the display should +be updated), and false if the key was something like KEY_ENTER, +which is a non-editing action outside this function. +.RS +.TP 5 +.B char * \fIstring +is the (multibyte) string to update +.TP 5 +.B int * \fIoffset +is the character-offset +.TP 5 +.B int \fIkey +is the editing key +.TP 5 +.B int \fIfkey +is true if the editing key is a function-key +.TP 5 +.B bool \fIforce +is used in a special loop case by calling code to force the return +value of this function when a function-key code 0 is passed in. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_exit +Given an internal exit code, +check if the corresponding environment variable is set. +If so, remap the exit code to match the environment variable. +Finally call \fBexit\fP with the resulting exit code. +.RS +.TP 5 +.B int \fIcode +is the internal exit code, e.g., \fBDLG_EXIT_OK\fP, +which may be remapped. +.RE +.IP +The \fB\*p\fP program uses this function +to allow shell scripts to remap the exit codes so they can distinguish ESC +from ERROR. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_exit_buttoncode +Map the given button index for \fBdlg_exit_label\fP into \fB\*p\fP's exit-code. +.RS +.TP 5 +.B int \fIbutton +is the button index +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_exit_label +Return a list of button labels. +If dialog_var.extra_button is true, return the result of \fBdlg_ok_labels\fP. +Otherwise, return a list with the "Exit" label and (if \fBdialog_vars.help_button\fP +is set) the "Help" button as well. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_exiterr +Quit program killing all \fBtailboxbg\fP widgets. +.RS +.TP 5 +.B const char * \fIfmt +is the format of the \fBprintf\fP-like message to write. +.TP 5 +. +are the variables to apply to the \fIfmt\fP format. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_find_index +Given the character-offset to find in the list, return the corresponding +array index. +.RS +.TP 5 +.B const int *\fIlist +contains a list of character-offsets, +i.e., indices into a string that denote the beginning of multibyte characters. +.TP 5 +.B int \fIlimit +is the last index into \fBlist\fP to search. +.TP 5 +.B int \fIto_find +is the character-offset to find. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_flush_getc +Cancel the local data saved by \fBdlg_last_getc\fP. +.\" --------------------------------------------------------------------------- +.IP dlg_editbox +This entrypoint provides the \fB--editbox\fP +functionality without the limitations of \fB\*p\fP's command-line syntax +(compare to \fBdialog_editbox\fP). +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B char *** \fIlist +is a pointer to an array of \fBchar\ *\fP pointers. +The array is allocated by the caller, +and so are the strings to which it points. +The \fBdlg_editbox\fP function may reallocate the +array and the strings. +.TP 5 +.B int * \fIrows +points to the nominal length of \fIlist\fP. +The referenced value is updated if\fIlist\fP is reallocated. +.TP 5 +.B int \fIheight +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_form +This entrypoint provides the \fB--form\fP +functionality without the limitations of \fB\*p\fP's command-line syntax +(compare to \fBdialog_form\fP). +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B const char * \fIcprompt +is the prompt text shown within the widget. +.TP 5 +.B int \fIheight +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIform_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP. +.TP 5 +.B DIALOG_FORMITEM * \fIitems +This is a list of the items to display in the form. +.TP 5 +.B int * \fIcurrent_item +The widget sets the referenced location to the index of the current display +item (cursor) when it returns. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_free_columns +Free data allocated by \fBdlg_align_columns\fP. +.RS +.TP 5 +.B char **\fItarget +This is the array which was reformatted. +It points to the first string to free. +.TP 5 +.B int \fIper_row +This is the size of the struct for each row of the array. +.TP 5 +.B int \fInum_rows +This is the number of rows in the array. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_free_formitems +Free memory owned by a list of DIALOG_FORMITEM's. +.RS +.TP 5 +.B DIALOG_FORMITEM * \fIitems +is the list to free. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_getc +Read a character from the given window. +Handle repainting here (to simplify +things in the calling application). +Also, if input-callback(s) are set up, +poll the corresponding files and handle the updates, +e.g., for displaying a tailbox. +Returns the key-code. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window within which to read. +.TP 5 +.B int * \fIfkey +as a side-effect, set this to true if the key-code is really a function-key. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_get_attrs +extract the video attributes from the given window. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window from which to get attributes. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_getc_callbacks +passes the given key-code \fIch\fP to the current window that +has established a callback. +If the callback returns zero, remove it and try the next window. +If no more callbacks remain, return. +If any callbacks were found, return true, otherwise false. +.RS +.TP 5 +.B int \fIch +is the key-code +.TP 5 +.B int \fIfkey +is true if the key is a function-key +.TP 5 +.B int * \fIresult +is used to pass an exit-code to the caller, +which should pass that via \fBdlg_exit\fP. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_index_columns +Build a list of the display-columns for the given multibyte string's characters. +.RS +.TP 5 +.B const char * \fIstring +is the string to analyze +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_index_wchars +Build an index of the wide-characters in the string, +so the caller can easily tell +which byte-offset begins a given wide-character. +.RS +.TP 5 +.B const char * \fIstring +is the string to analyze +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_item_help +Draw the string for the \fBdialog_vars.item_help\fP feature. +.RS +.TP 5 +.B const char * \fItxt +is the help-message +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_killall_bg +If \fB\*p\fP has callbacks active, +purge the list of all that are not marked +to keep in the background. +If any remain, run those in a background process. +.RS +.TP 5 +.B int * \fIretval +stores the exit-code to pass back to the caller. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_last_getc +returns the most recent character that was read via \fBdlg_getc\fP. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_limit_columns +Given a column limit, +count the number of wide characters that can fit into that limit. +The offset is used to skip over a leading character +that was already written. +.RS +.TP 5 +.B const char * \fIstring +is the string to analyze +.TP 5 +.B int \fIlimit +is the column limit +.TP 5 +.B int \fIoffset +is the starting offset from which analysis should continue +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_lookup_key +Check for a key-binding. +If there is no binding associated with the widget, it simply returns +the given curses-key. +Otherwise, it returns the result of the binding +.RS +.TP 5 +.B WINDOW * \fIwin +is the window on which the binding is checked +.TP 5 +.B int \fIcurses_key +is the curses key-code +.TP 5 +.B int * \fIdialog_key +is the corresponding \fB\*p\fP internal code +(see \fBDLG_KEYS_ENUM\fP in dlg_key.h). +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_max_input +Limit the parameter according to \fBdialog_vars.max_input\fP +.RS +.TP 5 +.B int \fImax_len +is the value to limit +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_match_char +Match a given character against the beginning of the string, +ignoring case of the given character. +The matching string must begin with an uppercase character. +.RS +.TP 5 +.B int \fIch +is the character to check +.TP 5 +.B const char * \fIstring +is the string to search +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_menu +This entrypoint provides the \fB--menu\fP +functionality without the limitations of \fB\*p\fP's command-line syntax +(compare to \fBdialog_menu\fP). +.RS +.TP 5 +.B const char * \fItitle +is the title string to display at the top of the widget. +.TP 5 +.B const char * \fIcprompt +is the prompt text shown within the widget. +.TP 5 +.B int \fIheight +is the desired height of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is adjusted to use the available screen size. +.TP 5 +.B int \fImenu_height +is the minimum height to reserve for displaying the list. +If zero, it is computed based on the given \fIheight\fP and \fIwidth\fP. +.TP 5 +.B int \fIitem_no +is the number of \fIitems\fP. +.TP 5 +.B DIALOG_LISTITEM * \fIitems +This is a list of the items to display in the form. +.TP 5 +.B int * \fIcurrent_item +The widget sets the referenced location to the index of the current display +item (cursor) when it returns. +.TP 5 +.B DIALOG_INPUTMENU \fIrename_menutext +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_move_window +Moves/resizes the given window to the given position and size. +.RS +.TP 5 +.B WINDOW *\fIwin +is the window to move/resize. +.TP 5 +.B WINDOW *\fIheight +is the height of the resized window. +.TP 5 +.B WINDOW *\fIwidth +is the width of the resized window. +.TP 5 +.B WINDOW *\fIy +y-ordinate to use for the repositioned window. +.TP 5 +.B WINDOW *\fIx +x-ordinate to use for the repositioned window. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_bigregion +Retrieve the big-region under the pointer. +.RS +.TP 5 +.B int \fIy +is the row on which the mouse click occurred +.TP 5 +.B int \fIx +is the column on which the mouse click occurred +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_free_regions +Free the memory associated with mouse regions. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_mkbigregion +Creates a region on which the mouse-clicks will return a specifed code. +.RS +.TP 5 +.B int \fIy +is the top-row of the region. +.TP 5 +.B int \fIx +is the left-column of the region. +.TP 5 +.B int \fIheight +is the height of the region. +.TP 5 +.B int \fIwidth +is the width of the region. +.TP 5 +.B int \fIcode +is a code used to make the region unique within a widget +.TP 5 +.B int \fIstep_x +is used in modes 2 (columns) and 3 (cells) to determine the width +of a column/cell. +.TP 5 +.B int \fIstep_y +is currently unused +.TP 5 +.B int \fImode +is used to determine how the mouse position is translated into +a code (like a function-key): +.RS +.TP +1 +index by lines +.TP +2 +index by columns +.TP +3 +index by cells +.RE +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_mkregion +.RS +.TP 5 +.B int \fIy +is the top-row of the region. +.TP 5 +.B int \fIx +is the left-column of the region. +.TP 5 +.B int \fIheight +is the height of the region. +.TP 5 +.B int \fIwidth +is the width of the region. +.TP 5 +.B int \fIcode +is a code used to make the region unique within a widget +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_region +Retrieve the frame under the mouse pointer +.RS +.TP 5 +.B int \fIy +is the row of the mouse-click +.TP 5 +.B int \fIx +is the column of the mouse-click +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_setbase +Sets a base for subsequent calls to \fBdlg_mouse_mkregion\fP, +so they can make regions relative to the start of a given window. +.RS +.TP 5 +.B int \fIx +is the left-column for the base +.TP 5 +.B int \fIy +is the top-row for the base +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_wgetch +is a wrapper for \fBdlg_getc\fP which additionally maps mouse-clicks +(if the curses library supports those) into extended function-keys +which encode the position according to the \fImode\fP in +\fBdlg_mouse_mkbigregion\fP. +Returns the corresponding key-code. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window on which to perform the input +.TP 5 +.B int * \fIfkey +the referenced location is set to true if the key-code is an actual +or extended (mouse) function-key. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_mouse_wgetch_nowait +This is a non-blocking variant of \fBdlg_mouse_wgetch\fP. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window on which to perform the input +.TP 5 +.B int * \fIfkey +the referenced location is set to true if the key-code is an actual +or extended (mouse) function-key. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_need_separator +Check if an output-separator is needed. +If \fBdialog_vars.output_separator\fP is set, return true. +Otherwise, if \fBdialog_vars.input_result\fP is nonempty, return true. +If neither, return false. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_new_modal_window +Create a modal window, optionally with a shadow. +The shadow is created if \fBdialog_state.use_shadow\fP is true. +.RS +.TP 5 +.B WINDOW * \fIparent +is the parent window (usually the top-level window of a widget) +.TP 5 +.B int \fIheight +is the window's height +.TP 5 +.B int \fIwidth +is the window's width +.TP 5 +.B int \fIy +is the window's top-row +.TP 5 +.B int \fIx +is the window's left-column +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_new_window +Create a window, optionally with a shadow. +The shadow is created if \fBdialog_state.use_shadow\fP is true. +.RS +.TP 5 +.B int \fIheight +is the window's height +.TP 5 +.B int \fIwidth +is the window's width +.TP 5 +.B int \fIy +is the window's top-row +.TP 5 +.B int \fIx +is the window's left-column +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_next_button +Return the next index in the list of labels. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int \fIbutton +is the current button-index. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_next_ok_buttonindex +Assuming that the caller is using \fBdlg_ok_labels\fP to list buttons, +find the next index in the list of buttons. +.RS +.TP 5 +.B int \fIcurrent +is the current index in the list of buttons +.TP 5 +.B int \fIextra +if negative, provides a way to enumerate extra active areas on the widget. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_ok_buttoncode +Map the given button index for \fBdlg_ok_labels\fP +into \fB\*p\fP's exit-code. +.RS +.TP 5 +.B int \fIbutton +is the button-index (which is not necessarily the same as the index +in the list of labels). +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_ok_label +Returns a list with the "Ok" label, +and if \fBdialog_vars.help_button\fP is true, the "Help" label as well. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_ok_labels +Return a list of button labels for the OK/Cancel group of widgets. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_ordinate +Decode the string as an integer, decrement if greater than zero to make +a curses-ordinate from a dialog-ordinate. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_parse_bindkey +Parse the parameters of the "bindkeys" configuration-file entry. This +expects widget name which may be "*", followed by curses key definition and +then \fB\*p\fP key definition. +.RS +.TP 5 +.B char * \fIparams +is the parameter string to parse. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_parse_rc +Parse the configuration file and set up variables. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_prev_button +Return the previous index in the list of labels. +.RS +.TP 5 +.B const char ** \fIlabels +is a list of (pointers to) button labels terminated by a null pointer. +.TP 5 +.B int \fIbutton +is the current button index +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_print_scrolled +This is a wrapper for \fBdlg_print_autowrap\fP which allows the user +to scroll too-long prompt text up/down. +.IP +See \fBdlg_check_scrolled\fP for a function which updates the \fIoffset\fP +variable used as a parameter here. +It complements this function; you need both. +If \fIpauseopt\fP is set, this function returns an updated \fIlast\fP +parameter, needed for \fBdlg_check_scrolled\fP calls. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B const char * \fIprompt +is the string to print +.TP 5 +.B int \fIoffset +is the starting line-number to write wrapped text. +.TP 5 +.B int \fIheight +is the available height for writing the wrapped text +.TP 5 +.B int \fIwidth +is the width that the wrapping should occur in +.TP 5 +.B int \fIpauseopt +is true if the extra functionality for scrolling should be enabled. +If false, this calls \fBdlg_print_autowrap\fP without doing any scrolling. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_print_line +Print one line of the prompt in the window within the limits of the +specified right margin. +The line will end on a word boundary and a pointer +to the start of the next line is returned, or a NULL pointer if the end of +*prompt is reached. +.RS +.TP 5 +.B WINDOW *\fIwin +is the window to update. +.TP 5 +.B chtype *\fIattr +holds the starting attributes, and is updated to reflect the final attributes +applied to the string. +.TP 5 +.B const char *\fIprompt +is the string to print +.TP 5 +.B int \fIlm +is the left margin. +.TP 5 +.B int \fIrm +is the right margin +.TP 5 +.B int *\fIx +returns the ending x-ordinate. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_prev_ok_buttonindex +Find the previous button index in the list from \fBdlg_ok_labels\fP. +.RS +.TP 5 +.B int \fIcurrent +is the current index +.TP 5 +.B int \fIextra +if negative provides a way to enumerate extra active areas on the widget. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_print_autowrap +Print a string of text in a window, automatically wrap around to the next +line if the string is too long to fit on one line. +Note that the string may contain embedded newlines. +The text is written starting at the top of the window. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B const char * \fIprompt +is the string to print +.TP 5 +.B int \fIheight +is the nominal height the wrapped string is limited to +.TP 5 +.B int \fIwidth +is the width that the wrapping should occur in +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_print_size +If \fBdialog_vars.print_siz\fP is true, +print the given height/width (from a widget) +to \fBdialog_state.output\fP, e.g., +\fBSize: height, width\fP. +.RS +.TP 5 +.B int \fIheight +is the window's height +.TP 5 +.B int \fIwidth +is the window's width +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_print_text +Print up to \fIcols\fP columns from \fBtext\fP, +optionally rendering \fB\*p\fP's escape sequences for attributes and color. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window to update. +.TP 5 +.B const char * \fItxt +is the string to print +.TP 5 +.B int \fIcol +is the column limit +.TP 5 +.B chtype * \fIattr +holds the starting attributes, and is updated to reflect the final attributes +applied to the string. +.RE +.\" --------------------------------------------------------------------------- +.B dlg_progressbox +implements the "\fB--prgbox\fP" and "\fB--progressbox\fP" options. +.RS +.IP title +is the title on the top of the widget. +.IP cprompt +is the prompt text shown within the widget. +If empty or null, no prompt is shown. +.IP height +is the desired height of the box. +If zero, the height is based on the screen size. +.IP width +is the desired width of the box. +If zero, the height is based on the screen size. +.IP pauseopt +if true, an "OK" button will be shown, +and the dialog will wait for it to complete. +With an "OK" button, it is denoted a "programbox", +without an "OK" button, it is denoted a "progressbox". +.IP fp +is the file pointer, which may be a pipe or a regular file. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_put_backtitle +Display the background title if \fBdialog_vars.backtitle\fP is non-null. +The background title is shown at the top of the screen. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_register_buttons +The widget developer should call this function after \fBdlg_register_window\fP, +for the list of button labels associated with the widget. +One may bind a key to a button, e.g., "OK" for \fBDLGK_OK\fP, +.RS +.TP 5 +.B WINDOW * \fIwin +is the window with which to associate the buttons +.TP 5 +.B const char * \fIname +is the widget's binding name (usually the name of the widget). +.TP 5 +.B const char ** \fIbuttons +is the list of buttons +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_register_window +For a given named widget's window, associate a binding table. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window with which to associate the buttons +.TP 5 +.B const char * \fIname +is the widget's binding name (usually the name of the widget). +.TP 5 +.B DLG_KEYS_BINDING * \fIbinding +is the binding table +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_remove_callback +Remove a callback. +.RS +.TP 5 +.B DIALOG_CALLBACK \fI* p +contains the callback information. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_restore_vars +Restore \fB\*p\fP's variables from the given variable (see \fBdialog_save_vars\fP). +.RS +.TP 5 +.B DIALOG_VARS * \fIsave +is the variable from which to restore. +.RE +.IP +The +\fIDIALOG_VARS.input_length\fP and +\fIDIALOG_VARS.input_result\fP members are treated specially, +since these are used by a widget to pass data to the caller. +They are not modified by this function. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_result_key +Test a \fB\*p\fP internal keycode to see if it corresponds to one of the push +buttons on the widget such as "OK". +This is only useful if there are user-defined key bindings, since there are +no built-in bindings that map directly to \fBDLGK_OK\fP, etc. +Return true if a mapping was done. +.RS +.TP 5 +.B int \fIdialog_key +is the \fB\*p\fP key to test +.TP 5 +.B int \fIfkey +is true if this is a function key +.TP 5 +.B int * \fIresultp +store the result of the mapping in the referenced location. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_save_vars +Save \fB\*p\fP's variables into the given variable (see \fBdialog_restore_vars\fP). +.RS +.TP 5 +.B DIALOG_VARS * \fIsave +is the variable into which to save. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_set_focus +Set focus on the given window, +making it display above other windows on the screen. +.RS +.TP 5 +.B WINDOW * \fIparent +is the parent window (usually the top-level window of a widget) +.TP 5 +.B WINDOW * \fIwin +is the window on which to place focus (usually a subwindow of a widget) +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_set_result +Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP +.RS +.TP 5 +.B const char * \fIstring +is the new contents for the result +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_show_string +Displays the string, shifted as necessary, to fit within the box and show +the current character-offset. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window within which to display +.TP 5 +.B const char * \fIstring +is the string to display +.TP 5 +.B int \fIoffset +is the starting (character, not bytes) offset +.TP 5 +.B chtype \fIattr +is the window attribute to use for the string +.TP 5 +.B int \fIy_base +beginning row on screen +.TP 5 +.B int \fIx_base +beginning column on screen +.TP 5 +.B int \fIx_last +number of columns on screen +.TP 5 +.B bool \fIhidden +if true, do not echo input +.TP 5 +.B bool \fIforce +if true, force repaint +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_strclone +duplicate the string, like \fBstrdup\fP. +.RS +.TP 5 +.B const char * \fIcprompt +is the string to duplicate +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_strcmp +compare two strings, ignoring case. +.RS +.TP 5 +.B const char \fI* a +is one string +.TP 5 +.B const char \fI* b +is the other string +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_string_to_argv +Convert a string to an argument vector +returning an index (which must be freed by the caller). +The string is modified (replacing gaps between tokens with nulls). +.RS +.TP 5 +.B char *\fIblob +is the string to convert. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_sub_window +create a subwindow, e.g., for an input area of a widget +.RS +.TP 5 +.B WINDOW * \fIwin +is the parent window +.TP 5 +.B int \fIheight +is the subwindow's height +.TP 5 +.B int \fIwidth +is the subwindow's width +.TP 5 +.B int \fIy +is the subwindow's top-row +.TP 5 +.B int \fIx +is the subwindow's left-column +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_tab_correct_str +If the \fBdialog_vars.tab_correct\fP is true, convert tabs to single spaces. +Return the converted result. +The caller is responsible for freeing the string. +.RS +.TP 5 +.B char * \fIprompt +is the string to convert +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_trace +If the parameter is non-null, opens a trace file with that +name and stores the file pointer in \fBdialog_state.trace\fP. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_trace_chr +If \fBdialog_state.trace\fP is set, +translate the parameters into a printable representation, +log it on a "chr" line. +.RS +.TP 5 +.B int ch +is the nominal keycode value. +.TP 5 +.B int fkey +is nonzero if the value is really a function key. +Some of these may be values declared in the DLG_KEYS_ENUM. +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_trace_win +If \fBdialog_state.trace\fP is set, +log a printable picture of the given window. +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_trim_string +Change embedded "\\n" substrings to '\\n' characters and tabs to single spaces. +If there are no "\\n"s, the function strips all extra spaces, for justification. +If it has "\\n"'s, the function preserves extra spaces. +If \fBdialog_vars.cr_wrap\fP is set, the function preserves '\\n's. +.RS +.TP 5 +.B char * \fIsrc +is the string to trim +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_unregister_window +Remove the bindings for a given window. +.RS +.TP 5 +.B WINDOW * \fIwin +is the window from which to remove bindings +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_yes_buttoncode +Map the given button index for \fBdlg_yes_labels\fP into \fB\*p\fP's exit-code. +.RS +.TP 5 +.B int \fIbutton +is the button index +.RE +.\" --------------------------------------------------------------------------- +.TP 5 +.B dlg_yes_labels +Return a list of buttons for Yes/No labels. +. +.\" ************************************************************************ +.SH SEE ALSO +\fB\*p\fP (1). +. +.\" ************************************************************************ +.SH AUTHOR +Thomas E. Dickey |