Update dialog to 1.2-20130523

1 files changed, 384 insertions, 23 deletions

diff --git a/dialog.3 b/dialog.3
index 737b577..c3a6aac 100644
--- a/dialog.3
+++ b/dialog.3
@@ -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,