diff options
Diffstat (limited to 'dialog.3')
| -rw-r--r-- | dialog.3 | 407 |
1 files changed, 384 insertions, 23 deletions
@@ -1,5 +1,6 @@ -.\" $Id: dialog.3,v 1.76 2012/07/03 08:22:10 tom Exp $ -.\" Copyright 2005-2011,2012 Thomas E. Dickey +'\" t +.\" $Id: dialog.3,v 1.91 2013/03/15 09:07:30 tom Exp $ +.\" Copyright 2005-2012,2013 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 @@ -38,9 +39,9 @@ .de bP .IP \(bu 4 .. -.TH \*D 3 "" "$Date: 2012/07/03 08:22:10 $" +.TH \*D 3 "" "$Date: 2013/03/15 09:07:30 $" .SH NAME -\*l \- widgets and utilities for the \*p program +dialog \- widgets and utilities for the \*p program .SH SYNOPSIS .B cc [ flag ... ] file ... -l\*l [ library ... ] .br @@ -432,7 +433,7 @@ by echoing asterisks for each character. .\" --------------------------------------------------------------------------- .IP \fIDIALOG_VARS.in_helpfile This variable is used to prevent \fBdialog_helpfile\fP from showing -anything, e.g., if F1 were pressed within a help-file display. +anything, e.g., if F1 were pressed within a help-file display. .\" --------------------------------------------------------------------------- .IP \fIDIALOG_VARS.item_help This corresponds to the command-line option "\fB--item-help\fP". @@ -456,11 +457,21 @@ 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.last_key +This corresponds to the command-line option "\fB--last-key\fP". +.\" --------------------------------------------------------------------------- .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_items +This corresponds to the command-line option "\fB--no-items\fP". +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a "tag" and "item", i.e., "description"). +This tells \fB\*p\fP to read shorter rows from data, +omitting the "list". +.\" --------------------------------------------------------------------------- .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. @@ -475,6 +486,63 @@ This corresponds to the command-line option "\fB--no-nl-expand\fP". If false, \fBdlg_trim_string\fP converts literal "\\n" substrings in a message into newlines. .\" --------------------------------------------------------------------------- +.IP \fIDIALOG_VARS.no_tags +This corresponds to the command-line option "\fB--no-tags\fP". +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a "tag" and "item", also known as "description"). +The tag is useful for scripting, but may not help the user. +The \fB--no-tags\fP option (from Xdialog) may be used to suppress the +column of tags from the display. +.IP +Normally \fB\*p\fP allows you to quickly move to entries on the displayed list, +by matching a single character to the first character of the tag. +When the \fB--no-tags\fP option is given, \fB\*p\fP matches against +the first character of the description. +In either case, the matchable character is highlighted. +.IP +Here is a table showing how the no_tags and no_items values interact: +.TS +tab(/); +l l l l l +_ _ _ _ _ +l l l c c. +Widget/Fields Shown/Fields Read/.no_items/.no_tags +buildlist/item/tag,item/0/0* +buildlist/item/tag,item/0/1 +buildlist/tag/tag/1/0* +buildlist/tag/tag/1/1 +checklist/tag,item/tag,item/0/0 +checklist/item/tag,item/0/1 +checklist/tag/tag/1/0 +checklist/tag/tag/1/1 +inputmenu/tag,item/tag,item/0/0 +inputmenu/item/tag,item/0/1 +inputmenu/tag/tag/1/0 +inputmenu/tag/tag/1/1 +menu/tag,item/tag,item/0/0 +menu/item/tag,item/0/1 +menu/tag/tag/1/0 +menu/tag/tag/1/1 +radiolist/tag,item/tag,item/0/0 +radiolist/item/tag,item/0/1 +radiolist/tag/tag/1/0 +radiolist/tag/tag/1/1 +treeview/item/tag,item/0/0* +treeview/item/tag,item/0/1 +treeview/tag/tag/1/0* +treeview/tag/tag/1/1 +_ +.TE +.RS +.TP 2 +* +Xdialog does not display the tag column for the analogous buildlist +and treeview widgets. +\fB\*L\fP does the same on the command-line. +However the library interface defaults to displaying the tag column. +Your application can enable or disable the tag column as needed for each widget. +.RE +.\" --------------------------------------------------------------------------- .IP \fIDIALOG_VARS.nocancel This corresponds to the command-line option "\fB--no-cancel\fP". If true, @@ -560,7 +628,8 @@ 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 +Modify the tab-traversal of the list-oriented widgets +(buildlist, checklist, radiobox, menubox, inputmenu, and treeview) 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. @@ -589,6 +658,49 @@ the width of the dialog box. Other parameters depend on the box type. . .\" ************************************************************************ +.IP \fBdialog_buildlist +implements the "\fB--buildlist\fP" option. +.RS +.TP 5 +.B const char * \fItitle +is the title on 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 rows in \fIitems\fP. +.TP 5 +.B char ** \fIitems +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 \fBdialog_vars.item_help\fP is set. +.TP 5 +.B int \fIorder_mode +is reserved for future enhancements +.RE +. +.\" ************************************************************************ .IP \fBdialog_calendar implements the "\fB--calendar\fP" option. .RS @@ -764,7 +876,7 @@ If zero, the height is based on the screen size. .\" ************************************************************************ .IP \fBdialog_gauge implements the "\fB--gauge\fP" option. -Alternatively, a simpler or customized gauge widget can be +Alternatively, a simpler or customized gauge widget can be setup using \fBdlg_allocate_gauge\fP, \fBdlg_update_gauge\fP and @@ -1068,6 +1180,35 @@ is the desired width of the box. If zero, the height is based on the screen size. .RE .\" ************************************************************************ +.IP \fBdialog_rangebox +implements the "\fB--rangebox\fP" option. +.RS +.TP 5 +.B const char * \fItitle +is the title on the top of the widget. +.TP 5 +.B const char * \fIcprompt +is the prompt text shown within the widget. +If empty or null, no prompt is shown. +.TP 5 +.B int \fIheight +is the desired height of the widget. +If zero, the height is based on the screen size. +.TP 5 +.B int \fIwidth +is the desired width of the widget. +If zero, the height is based on the screen size. +.TP 5 +.B int \fImin_value +is the minimum value to allow. +.TP 5 +.B int \fImax_value +is the maximum value to allow. +.TP 5 +.B int \fIdefault_value +is the default value, if no change is made. +.RE +.\" ************************************************************************ .IP \fBdialog_tailbox implements the "\fB--tailbox\fP" or "\fB--tailboxbg\fP" option depending on whether \fIbg_task\fP is set. @@ -1148,6 +1289,42 @@ 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_treeview +implements the "\fB--treeview\fP" option. +.RS +.TP 5 +.B const char * \fItitle +is the title on 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 based on the screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is based on the 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 rows in \fIitems\fP. +.TP 5 +.B char ** \fIitems +is the list of items, contain tag, name, and optionally help strings +(if \fBdialog_vars.item_help\fP is set). +The initial selection state for each item is also in this list. +.TP 5 +.B int \fIflag +.IP flag +is either \fIFLAG_CHECK\fP, for checklists (multiple selections), +or \fIFLAG_RADIO\fP for radiolists (a single selection). +.RE +.\" ************************************************************************ .IP \fBdialog_yesno implements the "\fB--yesno\fP" option. .RS @@ -1209,6 +1386,31 @@ function to call when input ends, e.g., to free caller's additional data. .RE .\" --------------------------------------------------------------------------- .TP 5 +.B dlg_add_last_key +Report the last key entered by the user. +This implements the \fB\-\-last\-key\fP command-line option, +using \fBdialog_vars.last_key\fP. +.RS +.TP 5 +.B int \fImode +controls the way the last key report is separated from other results: +.RS +.TP 5 +-2 +(no separator) +.TP 5 +-1 +(separator after the key name) +.TP 5 +0 +(separator is optionally before the key name) +.TP 5 +1 +(same as -1) +.RE +.RE +.\" --------------------------------------------------------------------------- +.TP 5 .B dlg_add_quoted Add a quoted string to the result buffer (see \fBdlg_add_result\fP). If no quotes are necessary, none are used. @@ -1233,7 +1435,7 @@ is the string to add. .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. +Otherwise, if \fBdialog_vars.separate_output\fP is set, use newline. If neither is set, use a space. .\" --------------------------------------------------------------------------- .TP 5 @@ -1387,17 +1589,13 @@ this calls \fBbeep\fP once and sets .B dlg_boxchar returns its \fBchtype\fP parameter transformed as follows: .RS -.TP 3 -.B - +.bP if neither \fBdialog_vars.ascii_lines\fP nor \fBdialog_vars.no_lines\fP is set. -.TP 3 -.B - +.bP 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 - +.bP otherwise, if \fBdialog_vars.no_lines\fP is set, returns a space for the line-drawing characters. -.TP 3 -.B - +.bP if the parameter is not a line-drawing or other special character such as ACS_DARROW, it returns the parameter unchanged. .RE .\" --------------------------------------------------------------------------- @@ -1426,6 +1624,56 @@ is the height of the widget. .RE .\" --------------------------------------------------------------------------- .TP 5 +.B dlg_buildlist +This is an alternate interface to the \fBbuildlist\fP widget +which allows the application to read the list item states back +directly without putting them in the output buffer. +.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 rows in \fIitems\fP. +.TP 5 +.B DIALOG_LISTITEM * \fIitems +is the list of items, contain tag, name, and optionally help strings +(if \fBdialog_vars.item_help\fP is set). +The initial selection state for each item is also in this list. +.TP 5 +.B const char * \fIstates +This is a list of characters to display for the given states. +Normally a buildlist 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 \fIorder_mode +is reserved for future enhancements +.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_button_count Count the buttons in the list. .RS @@ -1498,6 +1746,16 @@ abbreviation. If the label is empty, return -1. If no uppercase character is found, return 0. Otherwise return the uppercase character. +.IP +Normally +.B dlg_draw_buttons +and +.B dlg_char_to_button +use the first uppercase character. +However, they keep track of all of the labels and +if the first has already been used in another label, +they will continue looking for another uppercase character. +This function does not have enough information to make that check. .RS .TP 5 .B const char * \fIlabel @@ -1506,8 +1764,8 @@ is the label to test. .\" --------------------------------------------------------------------------- .TP 5 .B dlg_calc_list_width -Calculate the minimum width for the list, assuming none of the items -are truncated. +Calculate the minimum width for the list, +assuming none of the items are truncated. .RS .TP 5 .B int \fIitem_no @@ -1518,6 +1776,9 @@ 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. +.IP +If \fBdialog_vars.no_items\fP is set, +the \fItext\fP fields in the list are ignored. .RE .\" --------------------------------------------------------------------------- .TP 5 @@ -2679,6 +2940,21 @@ is the top-row for the base .RE .\" --------------------------------------------------------------------------- .TP 5 +.B dlg_mouse_setcode +Sets a value used internally by \fBdlg_mouse_mkregion\fP +which is added to the \fIcode\fP parameter. +By providing different values, +e.g., multiples of \fBKEY_MAX\fP, +it is possible to support multiple "big" regions in a widget. +The \fIbuildlist\fP widget uses this feature to recognize mouse-clicks +in the left/right panes. +.RS +.TP 5 +.B int \fIcode +is the value to add to \fBdlg_mouse_mkregion\fP's \fIcode\fP parameter. +.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 @@ -2834,6 +3110,35 @@ is the current button index .RE .\" --------------------------------------------------------------------------- .TP 5 +.B dlg_print_listitem +This is a helper function used for the various "list" widgets, +e.g., checklist, menu, buildlist, treeview. +Each list-widget has "tag" and "description" values for each item +which can be displayed. +If \fBdialog_vars.no_tags\fP is true, +the "tag" value is not shown. +The first character of the first value shown (tag or description) +is highlighted to indicate that the widget will match it for quick navigation. +.RS +.TP 5 +.B WINDOW *\fIwin +the window in which to display the text +.TP 5 +.B const char *\fItext +the value to display +.TP 5 +.B int \fIclimit +the number of columns available for printing the text +.TP 5 +.B bool \fIfirst +true if this is the first call (for "tag" and "description"), +and the first character of the value should be highlighted. +.TP 5 +.B int \fIselected +nonzero if the text should be displayed using the "selected" colors +.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. @@ -3070,7 +3375,7 @@ Restore \fB\*p\fP's variables from the given variable (see \fBdialog_save_vars\f is the variable from which to restore. .RE .IP -The +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. @@ -3097,7 +3402,7 @@ store the result of the mapping in the referenced location. .\" --------------------------------------------------------------------------- .TP 5 .B dlg_save_vars -Save \fB\*p\fP's variables into the given variable (see \fBdialog_restore_vars\fP). +Save \fB\*p\fP's variables into the given variable (see \fBdlg_restore_vars\fP). .RS .TP 5 .B DIALOG_VARS * \fIsave @@ -3119,7 +3424,7 @@ is the window on which to place focus (usually a subwindow of a widget) .\" --------------------------------------------------------------------------- .TP 5 .B dlg_set_result -Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP +Setup a fixed-buffer for the result in \fBdialog_vars.input_result\fP .RS .TP 5 .B const char * \fIstring @@ -3231,7 +3536,7 @@ name and stores the file pointer in \fBdialog_state.trace\fP. .\" --------------------------------------------------------------------------- .TP 5 .B dlg_trace_chr -If \fBdialog_state.trace\fP is set, +If \fBdialog_state.trace\fP is set, translate the parameters into a printable representation, log it on a "chr" line. .RS @@ -3268,10 +3573,66 @@ DLG_TRACE(("this is dialog version %s\\n", dialog_version())); .\" --------------------------------------------------------------------------- .TP 5 .B dlg_trace_win -If \fBdialog_state.trace\fP is set, +If \fBdialog_state.trace\fP is set, log a printable picture of the given window. .\" --------------------------------------------------------------------------- .TP 5 +.B dlg_treeview +This is an alternate interface to 'treeview' which allows the application +to read the list item states back directly without putting them in the +output buffer. +.RS +.TP 5 +.B const char * \fItitle +is the title on 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 based on the screen size. +.TP 5 +.B int \fIwidth +is the desired width of the box. +If zero, the height is based on the 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 rows in \fIitems\fP. +.TP 5 +.B DIALOG_LISTITEM * \fIitems +is the list of items, contain tag, name, and optionally help strings +(if \fBdialog_vars.item_help\fP is set). +The initial selection state for each item is also in this list. +.TP 5 +.B const char * \fIstates +This is a list of characters to display for the given states. +Normally a buildlist 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 * \fIdepths +This is a list of depths of each item in the tree. +It is a separate parameter from \fIitems\fP to allow reuse of +the existing functions. +.TP 5 +.B int \fIflag +is either \fIFLAG_CHECK\fP, for checklists (multiple selections), +or \fIFLAG_RADIO\fP for radiolists (a single selection). +.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_trim_string The \fBdialog\fP program uses this in each widget to adjust the message string, |