diff options
Diffstat (limited to 'gnu/lib/libodialog/dialog.3')
| -rw-r--r-- | gnu/lib/libodialog/dialog.3 | 842 |
1 files changed, 0 insertions, 842 deletions
diff --git a/gnu/lib/libodialog/dialog.3 b/gnu/lib/libodialog/dialog.3 deleted file mode 100644 index 2e4b8fb..0000000 --- a/gnu/lib/libodialog/dialog.3 +++ /dev/null @@ -1,842 +0,0 @@ -.\" -.\" Copyright (c) 1995, Jordan Hubbard -.\" -.\" All rights reserved. -.\" -.\" This manual page may be used, modified, copied, distributed, and -.\" sold, in both source and binary form provided that the above -.\" copyright and these terms are retained, verbatim, as the first -.\" lines of this file. Under no circumstances is the author -.\" responsible for the proper functioning of the software described herein -.\" nor does the author assume any responsibility for damages incurred with -.\" its use. -.\" -.\" $FreeBSD$ -.\" -.Dd January 1, 2000 -.Dt DIALOG 3 -.Os -.Sh NAME -.Nm draw_shadow , -.Nm draw_box , -.Nm line_edit , -.Nm strheight , -.Nm strwidth , -.Nm dialog_create_rc , -.Nm dialog_yesno , -.Nm dialog_noyes , -.Nm dialog_prgbox , -.Nm dialog_msgbox , -.Nm dialog_textbox , -.Nm dialog_menu , -.Nm dialog_checklist , -.Nm dialog_radiolist , -.Nm dialog_inputbox , -.Nm dialog_clear_norefresh , -.Nm dialog_clear , -.Nm dialog_update , -.Nm dialog_fselect , -.Nm dialog_notify , -.Nm dialog_mesgbox , -.Nm dialog_gauge , -.Nm init_dialog , -.Nm end_dialog , -.Nm use_helpfile , -.Nm use_helpline , -.Nm get_helpline , -.Nm restore_helpline , -.Nm dialog_ftree , -.Nm dialog_tree -.Nd provide a simple ncurses-based GUI interface -.Sh SYNOPSIS -.In dialog.h -.Ft "void" -.Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width" -.Ft "void" -.Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border" -.Ft "int" -.Fo line_edit -.Fa "WINDOW *dialog" -.Fa "int box_y" -.Fa "int box_x" -.Fa "int flen" -.Fa "int box_width" -.Fa "chtype attr" -.Fa "int first" -.Fa "unsigned char *result" -.Fa "int attr_mask" -.Fc -.Ft "int" -.Fn strheight "const char *p" -.Ft "int" -.Fn strwidth "const char *p" -.Ft "void" -.Fn dialog_create_rc "unsigned char *filename" -.Ft "int" -.Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width" -.Ft "int" -.Fn dialog_noyes "unsigned char *title" "unsigned char *prompt" "int height" "int width" -.Ft "int" -.Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell" -.Ft "int" -.Fn dialog_textbox "unsigned char *title" "unsigned char *file" "int height" "int width" -.Ft "int" -.Fo dialog_menu -.Fa "unsigned char *title" -.Fa "unsigned char *prompt" -.Fa "int height" -.Fa "int width" -.Fa "int menu_height" -.Fa "int cnt" -.Fa "void *it" -.Fa "unsigned char *result" -.Fa "int *ch" -.Fa "int *sc" -.Fc -.Ft "int" -.Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result" -.Ft "int" -.Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result" -.Ft "int" -.Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result" -.Ft "char *" -.Fn dialog_fselect "char *dir" "char *fmask" -.Ft "int" -.Fn dialog_dselect "char *dir" "char *fmask" -.Ft "void" -.Fn dialog_notify "char *msg" -.Ft "int" -.Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" -.Ft "void" -.Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc" -.Ft "void" -.Fn use_helpfile "char *hfile" -.Ft "void" -.Fn use_helpline "char *hline" -.Ft "char *" -.Fn get_helpline "void" -.Ft "void" -.Fn dialog_clear_norefresh "void" -.Ft "void" -.Fn dialog_clear "void" -.Ft "void" -.Fn dialog_update "void" -.Ft "void" -.Fn init_dialog "void" -.Ft "void" -.Fn end_dialog "void" -.Ft "int" -.Fn dialog_ftree "unsigned char *filename" "unsigned char FS" "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int menu_height" "unsigned char **result" -.Ft "int" -.Fo dialog_tree -.Fa "unsigned char **names" -.Fa "int size" -.Fa "unsigned char FS" -.Fa "unsigned char *title" -.Fa "unsigned char *prompt" -.Fa "int height" -.Fa "int width" -.Fa "int menu_height" -.Fa "unsigned char **result" -.Fc -.Sh DESCRIPTION -The dialog library attempts to provide a fairly simplistic set of -fixed-presentation menus, input boxes, gauges, file requestors and -other general purpose GUI (a bit of a stretch, since it uses -ncurses) objects. -Since the library also had its roots in a -shell-script writer's utility (see the -.Xr dialog 1 -command), the -early API was somewhat primitively based on strings being passed in or -out and parsed. -This API was later extended to take either the -original arguments or arrays of -.Va dialogMenuItem -structures, -giving the user much more control over the internal behavior of each -control. -The -.Va dialogMenuItem -structure internals are public: -.Bd -literal -offset indent -typedef struct _dmenu_item { - char *prompt; - char *title; - int (*checked)(struct _dmenu_item *self); - int (*fire)(struct _dmenu_item *self); - int (*selected)(struct _dmenu_item *self, int is_selected); - void *data; - char lbra, mark, rbra; - long aux; -} dialogMenuItem; -.Ed -.Pp -The -.Dv prompt -and -.Dv title -strings are pretty much self-explanatory, -and the -.Va checked -and -.Va fire -function pointers provide optional -display and action hooks (the -.Dv data -variable being available for -the convenience of those hooks) when more tightly coupled feedback between -a menu object and user code is required. -The -.Va selected -hook also -allows you to verify whether or not a given item is selected (the cursor is -over it) for implementing pretty much any possible context-sensitive -behavior. -A number of clever tricks for simulating various kinds of item -types can also be done by adjusting the values of -.Va lbra -(default: '['), -.Va mark -(default: '*' for radio menus, 'X' for check menus) -and -.Va rbra -(default: ']') and declaring a reasonable -.Va checked -hook, -which should return TRUE for the -.Dq marked -state and FALSE for -.Dq unmarked . -The -.Va aux -field is not used internally, and is available for miscellaneous usage. -If an item has a -.Va fire -hook associated with it, it will also be called -whenever the item is "toggled" in some way and should return one of the -following codes: -.Bd -literal -offset 4n -#define DITEM_SUCCESS 0 /* Successful completion */ -#define DITEM_FAILURE 1 /* Failed to "fire" */ -.Ed -.Pp -The following flags are in the upper 16 bits of return status: -.Bd -literal -offset 4n -#define DITEM_LEAVE_MENU (1 << 16) -#define DITEM_REDRAW (1 << 17) -#define DITEM_RECREATE (1 << 18) -#define DITEM_RESTORE (1 << 19) -#define DITEM_CONTINUE (1 << 20) -.Ed -.Pp -Two special globals also exist for putting a dialog at any arbitrary -X,Y location (the early designers rather short-sightedly made no provisions -for this). -If set to zero, the default centering behavior will be in -effect. -.Pp -Below is a short description of the various functions: -.Pp -The -.Fn draw_shadow -function draws a shadow in curses window -.Va win -using the dimensions of -.Va x , y , width -and -.Va height . -.Pp -The -.Fn draw_box -function draws a bordered box using the dimensions of -.Va x , y , width -and -.Va height . -The attributes from -.Va box -and -.Va border -are used, if specified, while painting the box and border regions of the -object. -.Pp -The -.Fn line_edit -function invokes a simple line editor with an edit box of dimensions -.Va box_x , box_y -and -.Va box_width . -The field length is constrained by -.Va flen , -starting at the -.Va first -character specified and -optionally displayed with character attributes -.Va attr . -The string being edited is stored in -.Va result . -Returns 0 on success, 1 on Cancel, and -1 on failure or ESC. -.Pp -The -.Fn strheight -function returns the height of string in -.Va p , -counting newlines. -.Pp -The -.Fn strwidth -function returns the width of string in -.Va p , -counting newlines. -.Pp -The -.Fn dialog_create_rc -function dumps dialog library settings into -.Pa filename -for later retrieval as defaults. -Returns 0 on success, -1 on failure. -.Pp -The -.Fn dialog_yesno -function displays a text box using -.Va title -and -.Va prompt -strings of dimensions -.Va height -and -.Va width . -Also paint a pair of -.Em Yes -and -.Em \&No -buttons at the bottom. -The default selection is -.Em Yes . -If the -.Em Yes -button is chosen, return FALSE. -If -.Em \&No , -return TRUE. -.Pp -The -.Fn dialog_noyes -function is the same as -.Fn dialog_yesno , -except the default selection is -.Em \&No . -.Pp -The -.Fn dialog_prgbox -function displays a text box of dimensions -.Va height -and -.Va width -containing the output of command -.Va line . -If -.Va use_shell -is TRUE, -.Va line -is passed as an argument to -.Xr sh 1 , -otherwise it is simply passed to -.Xr exec 3 . -If -.Va pause -is TRUE, a final confirmation requestor will be put up when execution -terminates. -Returns 0 on success, -1 on failure. -.Pp -The -.Fn dialog_textbox -function displays a text box containing the contents of -.Va file -with dimensions of -.Va height -and -.Va width . -.Pp -The -.Fn dialog_menu -function displays a menu of dimensions -.Va height -and -.Va width -with an optional internal menu height of -.Va menu_height . -The -.Va cnt -and -.Va it -arguments are of particular importance since they, -together, determine which of the 2 available APIs to use. -To use the -older and traditional interface, -.Va cnt -should be a positive -integer representing the number of string pointer pairs to find in -.Va it -(which should be of type -.Ft char "**" ) , -the strings are -expected to be in prompt and title order for each item and the -.Va result -parameter is expected to point to an array where the -prompt string of the item selected will be copied. -To use the newer -interface, -.Va cnt -should be a -.Va negative -integer representing the number of -.Va dialogMenuItem -structures pointed to by -.Va it -(which should be of type -.Vt dialogMenuItem "*" ) , -one structure per item. -In the new interface, the -.Va result -variable is used as a simple boolean (not a pointer) and should be NULL if -.Va it -only points to menu items and the default OK and Cancel buttons are desired. -If -.Va result -is non-NULL, then -.Va it -is actually expected to point 2 locations -.Va past -the start of the menu item list. -.Va it -is then expected to -point to an item representing the Cancel button, from which the -.Va prompt -and -.Va fire -actions are used to override the default behavior, and -.Va it -to the same for the OK button. -.Pp -Using either API behavior, the -.Va ch -and -.Va sc -values may be passed in to preserve current -item selection and scroll position values across calls. -.Pp -The -.Fn dialog_checklist -function displays a menu of dimensions -.Va height -and -.Va width -with an -optional internal menu height of -.Va list_height . -The -.Va cnt -and -.Va it -arguments are of particular importance since they, -together, determine which of the 2 available APIs to use. -To use the -older and traditional interface, -.Va cnt -should be a positive -integer representing the number of string pointer tuples to find in -.Va it -(which should be of type -.Ft "char **" ) , -the strings are -expected to be in prompt, title and state ("on" or "off") order for -each item and the -.Va result -parameter is expected to point to an -array where the prompt string of the item(s) selected will be -copied. -To use the newer interface, -.Va cnt -should be a -.Em negative -integer representing the number of -.Ft dialogMenuItem -structures pointed to by -.Va it -(which should be of type -.Ft "dialogMenuItem *" ) , -one structure per item. -In the new interface, -the -.Va result -variable is used as a simple boolean (not a pointer) -and should be NULL if -.Va it -only points to menu items and the default OK and Cancel -buttons are desired. -If -.Va result -is non-NULL, then -.Va it -is actually expected to -point 2 locations -.Va past -the start of the menu item list. -.Va it -is then expected to point to an item representing the Cancel -button, from which the -.Va prompt -and -.Va fire -actions are used to override the default behavior, and -.Va it -to the same for the OK button. -.Pp -In the standard API model, the menu supports the selection of multiple items, -each of which is marked with an `X' character to denote selection. -When -the OK button is selected, the prompt values for all items selected are -concatenated into the -.Va result -string. -.Pp -In the new API model, it is not actually necessary to preserve -"checklist" semantics at all since practically everything about how -each item is displayed or marked as "selected" is fully configurable. -You could have a single checklist menu that actually contained a group -of items with "radio" behavior, "checklist" behavior and standard menu -item behavior. -The only reason to call -.Fn dialog_checklist -over -.Fn dialog_radiolist -in the new API model is to inherit the base -behavior, you are no longer constrained by it. -.Pp -Returns 0 on success, 1 on Cancel, and -1 on failure or ESC. -.Pp -The -.Fn dialog_radiolist -function displays a menu of dimensions -.Va height -and -.Va width -with an -optional internal menu height of -.Va list_height . -The -.Va cnt -and -.Va it -arguments are of particular importance since they, -together, determine which of the 2 available APIs to use. -To use the -older and traditional interface, -.Va cnt -should be a positive -integer representing the number of string pointer tuples to find in -.Va it -(which should be of type -.Ft "char **" ) , -the strings are -expected to be in prompt, title and state ("on" or "off") order for -each item and the -.Va result -parameter is expected to point to an -array where the prompt string of the item(s) selected will be -copied. -To use the newer interface, -.Va cnt -should be a -.Dv negative -integer representing the number of -.Ft dialogMenuItem -structures pointed to by -.Va it -(which should be of type -.Ft "dialogMenuItem *" , -one structure per item. -In the new interface, -the -.Va result -variable is used as a simple boolean (not a pointer) -and should be NULL if -.Va it -only points to menu items and the default OK and Cancel -buttons are desired. -If -.Va result -is non-NULL, then -.Va it -is actually expected to point 2 locations -.Va past -the start of the menu item list. -.Va it -is then expected to point to an item representing the Cancel -button, from which the -.Va prompt -and -.Va fire -actions are used to override the default behavior, and -.Va it -does the same for the traditional OK button. -.Pp -In the standard API model, the menu supports the selection of only one -of multiple items, the currently active item marked with an `*' -character to denote selection. -When the OK button is selected, the -prompt value for this item is copied into the -.Va result -string. -.Pp -In the new API model, it is not actually necessary to preserve -"radio button" semantics at all since practically everything about how -each item is displayed or marked as "selected" is fully configurable. -You could have a single radio menu that actually contained a group -of items with "checklist" behavior, "radio" behavior and standard menu -item behavior. -The only reason to call -.Fn dialog_radiolist -over -.Fn dialog_checklistlist -in the new API model is to inherit the base -behavior. -.Pp -Returns 0 on success, 1 on Cancel and -1 on failure or ESC. -.Pp -The -.Fn dialog_inputbox -function displays a single-line text input field in a box displaying -.Va title -and -.Va prompt -of dimensions -.Va height -and -.Va width . -The field entered is stored in -.Va result . -.Pp -Returns 0 on success, -1 on failure or ESC. -.Pp -The -.Fn dialog_fselect -function brings up a file selector dialog starting at -.Va dir -and showing only those file names -matching -.Va fmask . -.Pp -Returns filename selected or NULL. -.Pp -The -.Fn dialog_dselect -function brings up a directory selector dialog starting at -.Va dir -and showing only those directory names -matching -.Va fmask . -.Pp -Returns directory name selected or NULL. -.Pp -The -.Fn dialog_notify -function brings up a generic "hey, you!" notifier dialog containing -.Va msg . -.Pp -The -.Fn dialog_mesgbox -function displays a notifier dialog, but with more control over -.Va title , -.Va prompt , -.Va width -and -.Va height . -This object will also wait for user confirmation, unlike -.Fn dialog_notify . -.Pp -Returns 0 on success, -1 on failure. -.Pp -The -.Fn dialog_gauge -function displays a horizontal bar-graph style gauge. -A value of -.Em 100 -for -.Em perc -constitutes a full gauge, a value of -.Em 0 -an empty one. -.Pp -The -.Fn use_helpfile -function for any menu supporting context sensitive help, invokes the text box -object on this file whenever the -.Em F1 -key is pressed. -.Pp -The -.Fn use_helpline -function displays this line of helpful text below any menu being displayed. -.Pp -The -.Fn get_helpline -function gets the current value of the helpful text line. -.Pp -The -.Fn dialog_clear_norefresh -function clears the screen back to the dialog background color, but do not -refresh the contents just yet. -.Pp -The -.Fn dialog_clear -function clears the screen back to the dialog background color immediately. -.Pp -The -.Fn dialog_update -function does any pending screen refreshes now. -.Pp -The -.Fn init_dialog -function initializes the dialog library (call this routine before any other -dialog API calls). -.Pp -The -.Fn end_dialog -function shuts down the dialog library (call this if you need to get back to -sanity). -.Pp -The -.Fn dialog_ftree -function shows a tree described by the data from the file -.Pa filename . -The data in the file should look like -.Xr find 1 -output. -For the -.Xr find 1 -output, the field separator -.Va FS -will be -.Dq \&/ . -If -.Va height -and -.Va width -are positive numbers, they set the absolute -size of the whole -.Fn dialog_ftree -box. -If -.Va height -and -.Va width -are negative numbers, the size of the -.Fn dialog_ftree -box will be calculated automatically. -.Va menu_height -sets the height of the tree subwindow inside the -.Fn dialog_ftree -box and must be set. -.Va title -is shown centered on the upper border of the -.Fn dialog_ftree -box. -.Va prompt -is shown inside the -.Fn dialog_ftree -box above the tree subwindow and can contain -.Ql \e\&n -to split lines. -One can navigate in -the tree by pressing UP/DOWN or -.Sm off -.So \&+ Sc \&/ So \&- Sc , -.Sm on -PG_UP/PG_DOWN or -.Sm off -.So b Sc \&/SPACE -.Sm on -and -HOME/END or -.Sm off -.So g Sc \&/ So G Sc . -.Sm on -A leaf of the -tree is selected by pressing TAB or LEFT/RIGHT the OK -button and pressing ENTER. -filename may contain data like -.Xr find 1 -output, as well as like the output of -.Xr find 1 -with -.Fl d -option. -Some of the transient paths to the leaves of the tree may -be absent. -Such data is corrected when fed from filename. -.Pp -The function returns 0 and a pointer to the selected leaf (to the path to -the leaf from the root of the tree) into result, if the OK button was -selected. -The memory allocated for the building of the tree is freed on -exiting -.Fn dialog_ftree . -The memory for the result line should be freed -later manually, if necessary. -If the Cancel button was selected, the -function returns 1. -In case of exiting -.Fn dialog_ftree -on ESC, the function returns -1. -.Pp -The -.Fn dialog_tree -function returns the same results as -.Fn dialog_ftree . -If 0 is returned, result will contain a pointer from the array -.Va names . -.\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does, -.\" with some exceptions. The source data for the building of the tree is an -.\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR -.\" output) of the size \fBsize\fR. However, there is no correction of data like -.\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must -.\" already contain correct data. Besides, in each session every unique use of -.\" \fBdialog_tree\fR is kept in memory, and later, when calling -.\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR, -.\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor -.\" in the tree subwindow is restored. -.Sh SEE ALSO -.Xr dialog 1 , -.Xr ncurses 3 -.Sh HISTORY -These functions appeared in -.Fx 2.0 -as the -.Xr dialog 1 -command and were soon split into a separate library -and command by -.An Andrey Chernov . -.An Marc van Kempen -implemented most of the extra controls and objects, -.An Jordan Hubbard -added the dialogMenuItem renovations and this man page and -.An Anatoly A. Orehovsky -implemented -.Fn dialog_ftree -and -.Fn dialog_tree . -.Sh AUTHORS -.An -nosplit -The primary author would appear to be -.An Savio Lam Aq lam836@cs.cuhk.hk -with contributions over the years by -.An Stuart Herbert Aq S.Herbert@sheffield.ac.uk , -.An Marc van Kempen Aq wmbfmk@urc.tue.nl , -.An Andrey Chernov Aq ache@FreeBSD.org , -.An Jordan Hubbard Aq jkh@FreeBSD.org -and -.An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su . -.Sh BUGS -Sure! |
