diff options
Diffstat (limited to 'Build/source/utils/dialog/dialog-1.1-20080819/dialog.3')
| -rw-r--r-- | Build/source/utils/dialog/dialog-1.1-20080819/dialog.3 | 2617 |
1 files changed, 0 insertions, 2617 deletions
diff --git a/Build/source/utils/dialog/dialog-1.1-20080819/dialog.3 b/Build/source/utils/dialog/dialog-1.1-20080819/dialog.3 deleted file mode 100644 index 8c32322b959..00000000000 --- a/Build/source/utils/dialog/dialog-1.1-20080819/dialog.3 +++ /dev/null @@ -1,2617 +0,0 @@ -.\" $Id: dialog.3,v 1.42 2008/07/28 00:01:05 tom Exp $ -.\" Copyright 2005-2007,2008 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. -.TH DIALOG 3 "" "$Date: 2008/07/28 00:01:05 $" -.SH NAME -dialog \- widgets and utilities for the dialog program -.SH SYNOPSIS -.B cc [ flag ... ] file ... -ldialog [ library ... ] - -.B #include <dialog.h> -.PP -\fBDialog\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 \fBdialog\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<dialog.h>\fP which -are likely to be important to developers using the widgets directly. -Some hints are also given for developing new widgets. -. -.\" ************************************************************************ -.SS 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 \fBdialog\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 \fBdialog\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 \fBdialog\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<dialog.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. - -.\" ************************************************************************ -.SS DATA STRUCTURES -All of the global data for the \fBdialog\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 \fBdialog\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.output -This is set in the \fBdialog\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 \fBdialog\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 \fBdialog\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 \fBdialog\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.use_colors -This is set in \fIinit_dialog\fP if the curses implementation supports color. -.\" --------------------------------------------------------------------------- -.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 \fBdialog\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 \fBdialog\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 -\fBdialog\fP -to put the -\fBtailboxbg\fP -box in the background, -printing its process id to \fBdialog\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 dialog 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, \fBdialog\fR will only wrap lines where needed to fit inside the text box. -Even though you can control line breaks with this, -\fBdialog\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.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 \fBdialog\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 -If \fIDIALOG_VARS.input_length\fP is zero, -this is a pointer to user buffer (on the stack, or static). -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. -.\" --------------------------------------------------------------------------- -.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 \fBdialog\fP to not attempt to cancel the terminal initialization -(termcap \fIti\fP/\fIte\fP) sequences which correspond to xterm's alternate-screen -switching. -Normally \fBdialog\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 \fBdialog\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 \fBdialog\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 \fBdialog\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, \fBdialog\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.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. -. -.\" ************************************************************************ -.\" ************************************************************************ -.SS WIDGETS -Functions that implement major functionality for the command-line \fBdialog\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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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 dialog_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. -.IP minute -is the initial minute shown. -If the value is negative, -the current minute is used. -.IP second -is the initial second shown. -If the value is negative, -the current second is used. -.RE -.\" ************************************************************************ -.IP dialog_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 -. -.\" ************************************************************************ -.SS UTILITY FUNCTIONS -Most functions that implement lower-level -functionality for the command-line \fBdialog\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_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 \fBdialog\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 \fBdialog\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 widest label (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 \fBdialog\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_clear -Set window to the default dialog 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). -.\" --------------------------------------------------------------------------- -.TP 5 -.B dlg_color_count -Return the number of colors that can be configured in \fBdialog\fP. -.\" --------------------------------------------------------------------------- -.TP 5 -.B dlg_color_setup -Initialize the color pairs used in \fBdialog\fP. -.\" --------------------------------------------------------------------------- -.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 \fBdialog\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 dialog_state.output_count, -so the output function in \fBdialog\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_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_edit_offset -Given the character-offset in the string, -returns the display-offset where -dialog 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 \fBdialog\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 dialog'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 \fBdialog\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 \fBdialog\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_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 char * \fItxt -is the help-message -.RE -.\" --------------------------------------------------------------------------- -.TP 5 -.B dlg_killall_bg -If \fBdialog\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 dialog 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 \fBdialog\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 dialog_state.use_shadow 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 dialog_state.use_shadow 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 \fBdialog\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 dialog 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_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. -.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 dialog_state.output, 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 \fBdialog\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 -.\" --------------------------------------------------------------------------- -.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 dialog'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 -.\" --------------------------------------------------------------------------- -.TP 5 -.B dlg_result_key -Test a dialog 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 dialog 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 dialog'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_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 \fBdialog\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 -dialog (1). -. -.\" ************************************************************************ -.SH AUTHOR -Thomas E. Dickey |