..

or

cc $(\*p-config --cflags) file ... $(\*p-config --libs) ] #include <\*l.h>

\*L is a program that will let you present a variety of questions or display messages using dialog boxes from a shell script. It is built from the \*l library, which consists of several widgets as well as utility functions that are used by the widgets or the main program. .

Here is a \*l version of Hello World\/:

int main(void)
{
 int status;
 init_dialog(stdin, stdout);
 status = dialog_yesno(
 "Hello, in dialog-format",
 "Hello World!",
 0, 0);
 end_dialog();
 return status;
}

Useful character constants which correspond to user input are named with the "CHR_" prefix, e.g., CHR_BACKSPACE.

Colors and video attributes are categorized and associated with settings in the configuration file (see the discussion of $DIALOGRC in \*p\/(1)). The DIALOG_ATR(n) macro is used for defining the references to the combined color and attribute table dlg_color_table[].

The \*p 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 --item-help 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.

Most of the other definitions found in <\*l.h> are used for convenience in building the library or main program. These include definitions based on the generated <dlg_config.h> header. . ************************************************************************

It is used by \*l for the command-line options "--print-text-size" and "--print-text-only". ---------------------------------------------------------------------------

It is used by \*l for the command-line options "--print-text-size" and "--print-text-only". ---------------------------------------------------------------------------

It is used by \*l for the command-line options "--print-text-size" and "--print-text-only". ---------------------------------------------------------------------------

The text-formatting functions (dlg_print_text, dlg_print_line, and dlg_print_autowrap) check this to decide whether to print the formatted text to \*p's output or to the curses-display.

Also, dlg_auto_size checks the flag, allowing it to be used before init_dialog is called. ---------------------------------------------------------------------------

It is used by \*l for the command-line options "--print-text-size" and "--print-text-only". ---------------------------------------------------------------------------

The \*p application resets the dialog_vars data before accepting options to invoke each widget. Most of the DIALOG_VARS members are set directly from \*p's command-line options: ---------------------------------------------------------------------------

In contrast to DIALOG_STATE, the members of DIALOG_VARS are set by command-line options in \*p. ---------------------------------------------------------------------------

Certain widgets copy a result to this buffer. If the pointer is NULL, or if the length is insufficient for the result, then the \*l library allocates a buffer which is large enough, and sets DIALOG_VARS.input_length. Callers should check for this case if they have supplied their own buffer. ---------------------------------------------------------------------------

Some widgets (buildlist, checklist, inputmenu, menu, radiolist, treeview) display a list for which the leading capital letter in each entry is accepted as a hot-key, to quickly move the focus to that entry.

Setting this variable to TRUE disables the feature. ---------------------------------------------------------------------------

Normally \*p 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 --no-tags option is given, \*p matches against the first character of the description. In either case, the matchable character is highlighted.

Here is a table showing how the no_tags and no_items values interact:

2 * Xdialog does not display the tag column for the analogous buildlist and treeview widgets. \*L 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. ---------------------------------------------------------------------------

All dialog boxes have at least three parameters:

Other parameters depend on the box type. . ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 char ** items is an array of strings which is viewed either as a list of rows

5 int order_mode is reserved for future enhancements . ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * subtitle is the prompt text shown within the widget.

5 int height is the height excluding the fixed-height calendar grid.

5 int width is the overall width of the box, which is adjusted up to the calendar grid's minimum width if needed.

5 int 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.

5 int 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.

5 int year is the initial year shown. If the value is negative, the current year is used. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 int items is an array of strings which is viewed either as a list of rows

5 const char * title is the title on the top of the widget.

5 const char * path is the preselected value to show in the input-box, which is used also to set the directory- and file-windows.

5 int height is the height excluding the minimum needed to show the dialog box framework. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * file is the name of the file from which to read.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int form_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 int items is an array of strings which is viewed either as a list of rows

5 const char * title is the title on the top of the widget.

5 const char * path is the preselected value to show in the input-box, which is used also to set the directory- and file-windows.

5 int height is the height excluding the minimum needed to show the dialog box framework. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int percent is the percentage to show in the progress bar. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 const char * init is the initial value of the input box, whose length is taken into account when auto-sizing the width of the dialog box.

5 int password if true, causes typed input to be echoed as asterisks. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * file is the name of a file containing the text to display. This function is internally bound to F1 (function key \*(``1\*(''), passing dialog_vars.help_file as a parameter. The \*p program sets that variable when the --hfile option is given.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int menu_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 int items is an array of strings which is viewed either as a list of rows

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int form_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 int items is an array of strings which is viewed either as a list of rows

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the caption text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int percent is the percentage to show in the progress bar.

5 int item_no is the number of rows in items.

5 int items is an array of strings which is viewed as a list of tag and item values. The tag values are listed, one per row, in the list at the top of the widget.

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int 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\*(''. ************************************************************************

5 const char * title is the title on the top of the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int seconds is the timeout to use for the progress bar. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget. If empty or null, no prompt is shown.

5 const char * command is the name of the command to execute.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int pauseopt if true, an \*(``OK\*('' button will be shown, and the dialog will wait for it to complete. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget. If empty or null, no prompt is shown.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget. If empty or null, no prompt is shown.

5 int height is the desired height of the widget. If zero, the height is based on the screen size.

5 int width is the desired width of the widget. If zero, the height is based on the screen size.

5 int min_value is the minimum value to allow.

5 int max_value is the maximum value to allow.

5 int default_value is the default value, if no change is made. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * file is the name of the file to display in the dialog.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int bg_task if true, the window is added to the callback list in dialog_state, 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. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * file is the name of the file to display in the dialog.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * subtitle is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int hour is the initial hour shown. If the value is negative, the current hour is used. Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 24.

5 int minute is the initial minute shown. If the value is negative, the current minute is used. Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60.

5 int second is the initial second shown. If the value is negative, the current second is used. Returns DLG_EXIT_ERROR if the value specified is greater than or equal to 60. ************************************************************************

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 char ** items is the list of items, contain tag, name, and optionally help strings (if dialog_vars.item_help is set). The initial selection state for each item is also in this list.

5 int flag

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size. . ************************************************************************

The only non-widget function whose name begins with "dialog_" is dialog_version, which returns the version number of the library as a string.

A few functions are prefixed "_dlg_", because they are required for internal use, but not intended as part of the library application programming interface. .

Here is a brief summary of the utility functions and their parameters: ---------------------------------------------------------------------------

5 DIALOG_CALLBACK *p contains the callback information. ---------------------------------------------------------------------------

5 DIALOG_CALLBACK **p points to the callback information. This is a reference to the pointer so that the caller's pointer can be zeroed when input ends.

5 DIALOG_FREEBACK func function to call when input ends, e.g., to free caller's additional data. ---------------------------------------------------------------------------

5 int *result this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is set.

5 char **tag the tag- or help-text is stored here.

5 DIALOG_FORMITEM *item contains the list item to use for tag- or help-text. ---------------------------------------------------------------------------

5 int *result this is updated to DLG_EXIT_ITEM_HELP if DIALOG_VARS.item_help is set.

5 char **tag the tag- or help-text is stored here.

5 DIALOG_LISTITEM *item contains the list item to use for tag- or help-text. ---------------------------------------------------------------------------

5 int mode controls the way the last key report is separated from other results:

5 char * string is the string to add. ---------------------------------------------------------------------------

5 char * string is the string to add. ---------------------------------------------------------------------------

5 char * string is the string to add. ---------------------------------------------------------------------------

5 char **target This is the array to reformat. It points to the first string to modify.

5 int per_row This is the size of the struct for each row of the array.

5 int num_rows This is the number of rows in the array. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int percent is the percentage to show in the progress bar. ---------------------------------------------------------------------------

5 chtype ch is the parameter, usually one of the ACS_xxx constants. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 int height is the number of rows to update.

5 int width is the number of columns to update.

5 chtype attr is the attribute, e.g., A_BOLD. ---------------------------------------------------------------------------

\*L sets dialog_state.text_height and dialog_state.text_width for the formatted prompt as a side-effect.

Normally \*l writes the formatted prompt to the curses window, but it will write the formatted prompt to the output stream if dialog_state.text_only is set.

5 const char * title is the title string to display at the top of the widget.

5 const char * prompt is the message text which will be displayed in the widget, used here to determine how large the widget should be.

5 int * height is the nominal height. \*L checks the referenced value and may update it:

5 int * width is the nominal width. \*L checks the referenced value and may update it:

5 int boxlines is the number of lines to reserve in the vertical direction.

5 int mincols is the minimum number of columns to use. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * file is the name of the file.

5 int * height is the nominal height.

5 int * width is the nominal width.

5 int boxlines is the number of lines to reserve on the screen for drawing boxes.

5 int mincols is the number of columns to reserve on the screen for drawing boxes. ---------------------------------------------------------------------------

5 int width is the width of the widget. ---------------------------------------------------------------------------

5 int height is the height of the widget. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 DIALOG_LISTITEM * items is the list of items, contain tag, name, and optionally help strings (if dialog_vars.item_help is set). The initial selection state for each item is also in this list.

5 const char * states 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.

5 int order_mode is reserved for future enhancements

5 int * current_item The widget sets the referenced location to the index of the current display item (cursor) when it returns. ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer. ---------------------------------------------------------------------------

See dlg_ok_buttoncode, which maps settings for ok/extra/help and button number into exit-code. ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int * limit the function sets the referenced limit to the width required for the buttons (limited by the screen size) if that is wider than the passed-in limit. ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int vertical is true if the buttons are arranged in a column rather than a row.

5 int * longest Return the total number of columns in the referenced location.

5 int * length Return the longest button's columns in the referenced location. ---------------------------------------------------------------------------

Normally dlg_draw_buttons and 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.

5 const char * label is the label to test. ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int limit is the maximum number of columns to allow for the buttons.

5 int * gap store the nominal gap between buttons in the referenced location. This is constrained to be at least one.

5 int * margin store the left+right total margins (for the list of buttons) in the referenced location.

5 int * step store the step-size in the referenced location. ---------------------------------------------------------------------------

5 int item_no is the number of items.

5 DIALOG_LISTITEM * items contains a name and text field, e.g., for checklists or radiobox lists. The function returns the sum of the widest columns needed for of each of these fields.

5 int * height 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.

5 int * list_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 dialog_vars.begin_set and dialog_vars.begin_y variables.

5 int item_no is the number of items in the list. ---------------------------------------------------------------------------

5 int item_no is the number of items.

5 char ** items is a list of character pointers.

5 int group is the number of items in each group, e.g., the second array index. ---------------------------------------------------------------------------

5 int ch is the character to find.

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of items.

5 DIALOG_LISTITEM * items This is a list of the items to display in the checklist.

5 const char * states 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.

5 int flag This is should be one of FLAG_CHECK or FLAG_RADIO, depending on whether the widget should act as a checklist or radiobox.

5 int * current_item The widget sets the referenced location to the index of the current display item (cursor) when it returns. ---------------------------------------------------------------------------

Some widgets use these key bindings for scrolling the prompt-text up and down, to allow for display in very small windows.

The function returns 0 (zero) if it finds one of these keys, and -1 if not.

5 int key is the function-key to check

5 int last is the number of lines which would be used to display the scrolled prompt in an arbitrarily tall window. It is used here to check limits for the offset value.

5 int page this is the available height for writing scrolled text, which is smaller than the window if it contains buttons.

5 bool * show on return, holds TRUE if dlg_print_scrolled should be used to redisplay the prompt text.

5 int * offset on entry, holds the starting line number (counting from zero) last used for dlg_print_scrolled. On return, holds the updated starting line number. ---------------------------------------------------------------------------

5 argv Points to the argument vector. ---------------------------------------------------------------------------

5 const char * string is the string to measure. ---------------------------------------------------------------------------

5 const char * string is the string to measure. ---------------------------------------------------------------------------

5 const char * string is the string to measure. ---------------------------------------------------------------------------

5 const char * filename is the name of the file to write to. ---------------------------------------------------------------------------

5 int height is the window's height

5 int width is the window's width ---------------------------------------------------------------------------

5 DIALOG_FORMITEM * items is the list of items to search. It is terminated by an entry with a null name field. ---------------------------------------------------------------------------

5 char ** items is the list of items to search.

5 int llen is the number of items in each group, e.g., the second array index. ---------------------------------------------------------------------------

5 WINDOW * win is the window to remove. ---------------------------------------------------------------------------

5 WINDOW * win is the parent window

5 int height is the subwindow's height

5 int width is the subwindow's width

5 int y is the subwindow's top-row

5 int x is the subwindow's left-column ---------------------------------------------------------------------------

5 WINDOW * dialog is the window on which to draw an arrow.

5 int top_arrow is true if an up-arrow should be drawn at the top of the window.

5 int bottom_arrow is true if an down-arrow should be drawn at the bottom of the window.

5 int x is the zero-based column within the window on which to draw arrows.

5 int top 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.

5 int bottom 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. ---------------------------------------------------------------------------

5 WINDOW * dialog is the window on which to draw an arrow.

5 int top_arrow is true if an up-arrow should be drawn at the top of the window.

5 int bottom_arrow is true if an down-arrow should be drawn at the bottom of the window.

5 int x is the zero-based column within the window on which to draw arrows.

5 int top 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.

5 int bottom 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.

5 chtype attr is the window's background attribute.

5 chtype borderattr is the window's border attribute. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 chtype on_left is used to color the upper/left edges of the box, i.e., the tee-element and horizontal line

5 chtype on_right is used to color the right edge of the box, i.e., the tee-element

5 chtype on_inside is used to fill-color the inside of the box ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 int y is the top row of the box.

5 int x is the left column of the box.

5 int height is the height of the box.

5 int width is the width of the box.

5 chtype boxchar is used to color the right/lower edges. It also is fill-color used for the box contents.

5 chtype borderchar is used to color the upper/left edges. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 int y is the top row of the box.

5 int x is the left column of the box.

5 int height is the height of the box.

5 int width is the width of the box.

5 chtype boxchar is used to fill-color for the box contents.

5 chtype borderchar is used to color the upper/left edges.

5 chtype borderchar2 is used to color the right/lower edges. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 int y is the starting row.

5 int x is the starting column.

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int selected is the index within the list of the selected button.

5 int vertical is true if the buttons are arranged in a column rather than a row.

5 int limit is the number of columns (or rows if vertical\/) allowed for the display. ---------------------------------------------------------------------------

5 WINDOW * dialog is the window to modify.

5 bool decorations if true, allow room for the scrolling arrows. ---------------------------------------------------------------------------

5 WINDOW * win is the window in which the data is scrolled. Because left, right, top, bottom are passed as parameters, this window can contain additional data.

5 long first_data is the zero-based index to the first row of data in the current window.

5 long this_data is the zero-based index to the current row of data.

5 long next_data is the zero-based index to the next data after the current row.

5 long total_data is the total number of rows of data.

5 int left is the zero-based left margin/column of the window. The up/down arrows are draw inset by 5 columns from this point.

5 int right is the zero-based right margin/column of the window. The scrollbar is drawn flush against this column.

5 int top 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.

5 int bottom 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.

5 chtype attr is the window's background attribute.

5 chtype borderattr is the window's border attribute. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 int height is the height of the window.

5 int width is the width of the window.

5 int y is the top row of the window.

5 int x is the left column of the window. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 const char * title is the title string to display at the top of the widget. ---------------------------------------------------------------------------

The function should only return DLG_EXIT_ERROR.

5 DIALOG_LISTITEM * items is the list of menu items

5 int current is the index of the currently-selected item

5 char * newtext is the updated text for the menu item ---------------------------------------------------------------------------

5 FILE * fp is the stream on which to write the bindings. ---------------------------------------------------------------------------

5 FILE * fp is the stream on which to write the bindings.

5 WINDOW * win is the window for which bindings should be dumped. If it is null, then only built-in bindings are dumped. ---------------------------------------------------------------------------

5 int * argcp in/out parameter giving the length of the argument vector. char *** argvp in/out parameter pointing to the argument vector. int start starting index. int count number of arguments to remove. ---------------------------------------------------------------------------

5 char * string is the string to analyze

5 int offset is the character-offset

5 int x_last is a limit on the column positions that can be used, e.g., the window's size. ---------------------------------------------------------------------------

5 char * string is the (multibyte) string to update

5 int * offset is the character-offset

5 int key is the editing key

5 int fkey is true if the editing key is a function-key

5 bool force 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. ---------------------------------------------------------------------------

5 int code is the internal exit code, e.g., DLG_EXIT_OK, which may be remapped.

The \*p program uses this function to allow shell scripts to remap the exit codes so they can distinguish ESC from ERROR. ---------------------------------------------------------------------------

5 int code is an exit-code for \*p as defined in <\*p.h>. ---------------------------------------------------------------------------

5 const char * name is the name of an exit-code for \*p as defined in <\*p.h> but omitting the \*(``DLG_EXIT_\*('' prefix. ---------------------------------------------------------------------------

5 int button is the button index ---------------------------------------------------------------------------

5 const char * fmt is the format of the printf-like message to write.

5 ...

are the variables to apply to the fmt format. ---------------------------------------------------------------------------

5 const int *list contains a list of character-offsets, i.e., indices into a string that denote the beginning of multibyte characters.

5 int limit is the last index into list to search.

5 int to_find is the character-offset to find. ---------------------------------------------------------------------------

5 const char * string is the address of the string whose data should be discarded. The address rather than contents is used as the unique identifier because some of the caching is used for editable input-fields. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 char *** list is a pointer to an array of char * pointers. The array is allocated by the caller, and so are the strings to which it points. The dlg_editbox function may reallocate the array and the strings.

5 int * rows points to the nominal length of list. The referenced value is updated iflist is reallocated.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size. ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int form_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of items.

5 DIALOG_FORMITEM * items This is a list of the items to display in the form.

5 int * current_item The widget sets the referenced location to the index of the current display item (cursor) when it returns. ---------------------------------------------------------------------------

5 char **target This is the array which was reformatted. It points to the first string to free.

5 int per_row This is the size of the struct for each row of the array.

5 int num_rows This is the number of rows in the array. ---------------------------------------------------------------------------

5 DIALOG_FORMITEM * items is the list to free. ---------------------------------------------------------------------------

5 void *objptr points to the gauge widget. ---------------------------------------------------------------------------

5 WINDOW * win is the window within which to read.

5 int * fkey as a side-effect, set this to true if the key-code is really a function-key. ---------------------------------------------------------------------------

5 char * name is the name of the environment-variable to retrieve.

5 int * value is the optional pointer to a return-value. ---------------------------------------------------------------------------

5 char * name is the name of the environment-variable to retrieve. ---------------------------------------------------------------------------

5 WINDOW * win is the window from which to get attributes. ---------------------------------------------------------------------------

5 int ch is the key-code

5 int fkey is true if the key is a function-key

5 int * result is used to pass an exit-code to the caller, which should pass that via dlg_exit. ---------------------------------------------------------------------------

5 const char * string is the string to analyze ---------------------------------------------------------------------------

5 const char * string is the string to analyze ---------------------------------------------------------------------------

5 const char * txt is the help-message ---------------------------------------------------------------------------

5 FILE * output is the output stream used for displaying widgets. It is either stdout or stderr, depending on the --stdout option. ---------------------------------------------------------------------------

5 int * retval stores the exit-code to pass back to the caller. ---------------------------------------------------------------------------

5 const char * string is the string to analyze

5 int limit is the column limit

5 int offset is the starting offset from which analysis should continue ---------------------------------------------------------------------------

5 WINDOW * win is the window on which the binding is checked

5 int curses_key is the curses key-code

5 int * dialog_key is the corresponding \*p internal code (see DLG_KEYS_ENUM in dlg_key.h). ---------------------------------------------------------------------------

5 int max_len is the value to limit ---------------------------------------------------------------------------

5 int ch is the character to check

5 const char * string is the string to search ---------------------------------------------------------------------------

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int menu_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of items.

5 DIALOG_LISTITEM * items This is a list of the items to display in the form.

5 int * current_item The widget sets the referenced location to the index of the current display item (cursor) when it returns.

5 DIALOG_INPUTMENU rename_menutext If this is not dlg_dummy_menutext, the widget acts like an inputmenu widget, providing an extra \*(``Rename\*('' button, which activates an edit feature on the selected menu item. ---------------------------------------------------------------------------

5 WINDOW *win is the window to move/resize.

5 WINDOW *height is the height of the resized window.

5 WINDOW *width is the width of the resized window.

5 WINDOW *y y-ordinate to use for the repositioned window.

5 WINDOW *x x-ordinate to use for the repositioned window. ---------------------------------------------------------------------------

5 int y is the row on which the mouse click occurred

5 int x is the column on which the mouse click occurred ---------------------------------------------------------------------------

5 int y is the top-row of the region.

5 int x is the left-column of the region.

5 int height is the height of the region.

5 int width is the width of the region.

5 int code is a code used to make the region unique within a widget

5 int step_x is used in modes 2 (columns) and 3 (cells) to determine the width of a column/cell.

5 int step_y is currently unused

5 int mode is used to determine how the mouse position is translated into a code (like a function-key):

5 int y is the top-row of the region.

5 int x is the left-column of the region.

5 int height is the height of the region.

5 int width is the width of the region.

5 int code is a code used to make the region unique within a widget ---------------------------------------------------------------------------

5 int y is the row of the mouse-click

5 int x is the column of the mouse-click ---------------------------------------------------------------------------

5 int x is the left-column for the base

5 int y is the top-row for the base ---------------------------------------------------------------------------

5 int code is the value to add to dlg_mouse_mkregion's code parameter. ---------------------------------------------------------------------------

5 WINDOW * win is the window on which to perform the input

5 int * fkey the referenced location is set to true if the key-code is an actual or extended (mouse) function-key. ---------------------------------------------------------------------------

5 WINDOW * win is the window on which to perform the input

5 int * fkey the referenced location is set to true if the key-code is an actual or extended (mouse) function-key. ---------------------------------------------------------------------------

5 WINDOW * parent is the parent window (usually the top-level window of a widget)

5 int height is the window's height

5 int width is the window's width

5 int y is the window's top-row

5 int x is the window's left-column ---------------------------------------------------------------------------

5 int height is the window's height

5 int width is the window's width

5 int y is the window's top-row

5 int x is the window's left-column ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int button is the current button-index. ---------------------------------------------------------------------------

5 int current is the current index in the list of buttons

5 int extra if negative, provides a way to enumerate extra active areas on the widget. ---------------------------------------------------------------------------

5 int button is the button-index (which is not necessarily the same as the index in the list of labels). ---------------------------------------------------------------------------

5 char * params is the parameter string to parse. ---------------------------------------------------------------------------

5 const char *command The shell command to run.

5 const char *type Like popen, "r" is used to read, and "w" is used to write. ---------------------------------------------------------------------------

5 const char ** labels is a list of (pointers to) button labels terminated by a null pointer.

5 int button is the current button index ---------------------------------------------------------------------------

5 WINDOW *win the window in which to display the text

5 const char *text the value to display

5 int climit the number of columns available for printing the text

5 bool first true if this is the first call (for \*(``tag\*('' and \*(``description\*(''), and the first character of the value should be highlighted.

5 int selected nonzero if the text should be displayed using the \*(``selected\*('' colors ---------------------------------------------------------------------------

See dlg_check_scrolled for a function which updates the offset variable used as a parameter here. It complements this function; you need both. If pauseopt is set, this function returns an updated last parameter, needed for dlg_check_scrolled calls.

5 WINDOW * win is the window to update.

5 const char * prompt is the string to print

5 int offset is the starting line-number to write wrapped text.

5 int height is the available height for writing the wrapped text

5 int width is the width that the wrapping should occur in

5 int pauseopt is true if the extra functionality for scrolling should be enabled. If false, this calls dlg_print_autowrap without doing any scrolling. ---------------------------------------------------------------------------

5 WINDOW *win is the window to update.

5 chtype *attr holds the starting attributes, and is updated to reflect the final attributes applied to the string.

5 const char *prompt is the string to print

5 int lm is the left margin.

5 int rm is the right margin

5 int *x returns the ending x-ordinate. ---------------------------------------------------------------------------

5 int current is the current index

5 int extra if negative provides a way to enumerate extra active areas on the widget. ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 const char * prompt is the string to print

5 int height is the nominal height the wrapped string is limited to

5 int width is the width that the wrapping should occur in ---------------------------------------------------------------------------

5 int height is the window's height

5 int width is the window's width ---------------------------------------------------------------------------

5 WINDOW * win is the window to update.

5 const char * txt is the string to print

5 int col is the column limit

5 chtype * attr holds the starting attributes, and is updated to reflect the final attributes applied to the string. ---------------------------------------------------------------------------

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget. If empty or null, no prompt is shown.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int pauseopt if true, an \*(``OK\*('' button will be shown, and the dialog will wait for it to complete. With an \*(``OK\*('' button, it is denoted a \*(``programbox\*('', without an \*(``OK\*('' button, it is denoted a \*(``progressbox\*(''.

5 FILE * fp is the file pointer, which may be a pipe or a regular file. ---------------------------------------------------------------------------

5 void ** objptr If the pointer referenced by this parameter is null, the function creates a new gauge widget using dlg_allocate_gauge. Otherwise, it updates the title and cprompt values, reusing the window from the previous call on this function. As a side-effect, the function stores the updated object-pointer via the objptr parameter.

5 const char * title is the title string to display at the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is adjusted to use the available screen size.

5 int width is the desired width of the box. If zero, the height is adjusted to use the available screen size.

5 int percent is the percentage to show in the progress bar. ---------------------------------------------------------------------------

5 WINDOW * win is the window with which to associate the buttons

5 const char * name is the widget's binding name (usually the name of the widget).

5 const char ** buttons is the list of buttons ---------------------------------------------------------------------------

5 WINDOW * win is the window with which to associate the buttons

5 const char * name is the widget's binding name (usually the name of the widget).

5 DLG_KEYS_BINDING * binding is the binding table ---------------------------------------------------------------------------

5 DIALOG_CALLBACK * p contains the callback information. ---------------------------------------------------------------------------

The function should add \*(``RENAMED\*('' to dialog_vars.input_result , followed by the menu item's name and the newtext value (with a space separating the three items), and return DLG_EXIT_EXTRA.

5 DIALOG_LISTITEM * items is the list of menu items

5 int current is the index of the currently-selected item

5 char * newtext is the updated text for the menu item ---------------------------------------------------------------------------

5 DIALOG_VARS * save is the variable from which to restore.

The DIALOG_VARS.input_length and DIALOG_VARS.input_result members are treated specially, since these are used by a widget to pass data to the caller. They are not modified by this function. ---------------------------------------------------------------------------

5 int dialog_key is the \*p key to test

5 int fkey is true if this is a function key

5 int * resultp store the result of the mapping in the referenced location. ---------------------------------------------------------------------------

5 DIALOG_VARS * save is the variable into which to save. ---------------------------------------------------------------------------

5 WINDOW * parent is the parent window (usually the top-level window of a widget)

5 WINDOW * win is the window on which to place focus (usually a subwindow of a widget) ---------------------------------------------------------------------------

5 const char * string is the new contents for the result ---------------------------------------------------------------------------

5 WINDOW * win is the window whose input-timeout should be set

5 bool will_getc is true if the widget is expected to read keyboard characters. Some (such as the gauge widget) do not. ---------------------------------------------------------------------------

5 WINDOW * win is the window within which to display

5 const char * string is the string to display

5 int offset is the starting (character, not bytes) offset

5 chtype attr is the window attribute to use for the string

5 int y_base beginning row on screen

5 int x_base beginning column on screen

5 int x_last number of columns on screen

5 bool hidden if true, do not echo input

5 bool force if true, force repaint ---------------------------------------------------------------------------

5 const char * cprompt is the string to duplicate ---------------------------------------------------------------------------

5 const char * a is one string

5 const char * b is the other string ---------------------------------------------------------------------------

5 char *blob is the string to convert. ---------------------------------------------------------------------------

5 WINDOW * win is the parent window

5 int height is the subwindow's height

5 int width is the subwindow's width

5 int y is the subwindow's top-row

5 int x is the subwindow's left-column ---------------------------------------------------------------------------

5 char * prompt is the string to convert ---------------------------------------------------------------------------

5 char * name is the name to log in the comment.

5 int value is the value to log in the comment. ---------------------------------------------------------------------------

5 char * name is the name to log in the comment.

5 int value is the value to log in the comment. ---------------------------------------------------------------------------

5 int ch is the nominal keycode value.

5 int fkey is nonzero if the value is really a function key. Some of these may be values declared in the DLG_KEYS_ENUM. ---------------------------------------------------------------------------

5 const char * fmt is the format of the printf-like message to write.

5 ...

are the variables to apply to the fmt format.

Use the DLG_TRACE macro for portability, in case the trace feature is not compiled into the library. It uses an extra level of parentheses to work with a variable number of parameters, e.g., .Ex DLG_TRACE(("this is dialog version %s\en", dialog_version())); .Ee ---------------------------------------------------------------------------

5 const char *fmt is the format of the printf-like message to write.

5 va_list ap are the variables to apply to the fmt format.

This is used in dlg_exiterr to capture error messages in the trace file: .Ex va_start(ap, fmt); dlg_trace_msg("## Error: "); dlg_trace_va_msg(fmt, ap); va_end(ap); .Ee

Unlike dlg_trace_msg, an extra macro is not needed. ---------------------------------------------------------------------------

5 const char * title is the title on the top of the widget.

5 const char * cprompt is the prompt text shown within the widget.

5 int height is the desired height of the box. If zero, the height is based on the screen size.

5 int width is the desired width of the box. If zero, the height is based on the screen size.

5 int list_height is the minimum height to reserve for displaying the list. If zero, it is computed based on the given height and width.

5 int item_no is the number of rows in items.

5 DIALOG_LISTITEM * items is the list of items, contain tag, name, and optionally help strings (if dialog_vars.item_help is set). The initial selection state for each item is also in this list.

5 const char * states 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.

5 int * depths This is a list of depths of each item in the tree. It is a separate parameter from items to allow reuse of the existing functions.

5 int flag is either FLAG_CHECK, for checklists (multiple selections), or FLAG_RADIO for radiolists (a single selection).

5 int * current_item The widget sets the referenced location to the index of the current display item (cursor) when it returns. ---------------------------------------------------------------------------

There are several optional features: .bP Unless dialog_vars.nocollapse is set, each tab is converted to a space before other processing. .bP If dialog_vars.no_nl_expand is not set, and the string has "\en" substrings:

5 char * src is the string to trim ---------------------------------------------------------------------------

5 WINDOW * win is the window from which to remove bindings ---------------------------------------------------------------------------

5 void *objptr points to the gauge object to update.

5 int percent is the new percentage value to display. ---------------------------------------------------------------------------

5 int button is the button index ---------------------------------------------------------------------------

5 FILE *input is the real tty input of \*p. Usually it is the standard input, but if --input-fd option is used, it may be anything.

5 FILE *output is where \*p will send its result. Usually it is the standard error, but if --stdout or --output-fd is used, it may be anything. . ************************************************************************