The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

dialog_textbox (3)
  • >> dialog_textbox (3) ( FreeBSD man: Библиотечные вызовы )

  • BSD mandoc
     

    NAME

    
    
    draw_shadow
    
     
    draw_box
    
     
    line_edit
    
     
    strheight
    
     
    strwidth
    
     
    dialog_create_rc
    
     
    dialog_yesno
    
     
    dialog_noyes
    
     
    dialog_prgbox
    
     
    dialog_msgbox
    
     
    dialog_textbox
    
     
    dialog_menu
    
     
    dialog_checklist
    
     
    dialog_radiolist
    
     
    dialog_inputbox
    
     
    dialog_clear_norefresh
    
     
    dialog_clear
    
     
    dialog_update
    
     
    dialog_fselect
    
     
    dialog_notify
    
     
    dialog_mesgbox
    
     
    dialog_gauge
    
     
    init_dialog
    
     
    end_dialog
    
     
    use_helpfile
    
     
    use_helpline
    
     
    get_helpline
    
     
    restore_helpline
    
     
    dialog_ftree
    
     
    dialog_tree
    
     - provide a simple ncurses-based GUI interface
    
     
    

    SYNOPSIS

       #include <dialog.h>
    void draw_shadow (WINDOW *win int y int x int height int width);
    void draw_box (WINDOW *win int y int x int height int width chtype box chtype border);
    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 strheight (const char *p);
    int strwidth (const char *p);
    void dialog_create_rc (unsigned char *filename);
    int dialog_yesno (unsigned char *title unsigned char *prompt int height int width);
    int dialog_noyes (unsigned char *title unsigned char *prompt int height int width);
    int dialog_prgbox (unsigned char *title const unsigned char *line int height int width int pause int use_shell);
    int dialog_textbox (unsigned char *title unsigned char *file int height int width);
    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 dialog_checklist (unsigned char *title unsigned char *prompt int height int width int list_height int cnt void *it unsigned char *result);
    int dialog_radiolist (unsigned char *title unsigned char *prompt int height int width int list_height int cnt void *it unsigned char *result);
    int dialog_inputbox (unsigned char *title unsigned char *prompt int height int width unsigned char *result);
    char * dialog_fselect (char *dir char *fmask);
    int dialog_dselect (char *dir char *fmask);
    void dialog_notify (char *msg);
    int dialog_mesgbox (unsigned char *title unsigned char *prompt int height int width);
    void dialog_gauge (char *title char *prompt int y int x int height int width int perc);
    void use_helpfile (char *hfile);
    void use_helpline (char *hline);
    char * get_helpline (void);
    void dialog_clear_norefresh (void);
    void dialog_clear (void);
    void dialog_update (void);
    void init_dialog (void);
    void end_dialog (void);
    int dialog_ftree (unsigned char *filename unsigned char FS unsigned char *title unsigned char *prompt int height int width int menu_height unsigned char **result);
    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  

    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 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 dialogMenuItem structures, giving the user much more control over the internal behavior of each control. The dialogMenuItem structure internals are public:
    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;
    

    The prompt and title strings are pretty much self-explanatory, and the checked and fire function pointers provide optional display and action hooks (the 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 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 lbra (default: '['), mark (default: '*' for radio menus, 'X' for check menus) and rbra (default: ']') and declaring a reasonable checked hook, which should return TRUE for the ``marked'' state and FALSE for ``unmarked'' The aux field is not used internally, and is available for miscellaneous usage. If an item has a 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:

    #define DITEM_SUCCESS           0    /* Successful completion */
    #define DITEM_FAILURE           1    /* Failed to "fire" */
    

    The following flags are in the upper 16 bits of return status:

    #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)
    

    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.

    Below is a short description of the various functions:

    The draw_shadow ();
    function draws a shadow in curses window win using the dimensions of x , y , width and height

    The draw_box ();
    function draws a bordered box using the dimensions of x , y , width and height The attributes from box and border are used, if specified, while painting the box and border regions of the object.

    The line_edit ();
    function invokes a simple line editor with an edit box of dimensions box_x , box_y and box_width The field length is constrained by flen starting at the first character specified and optionally displayed with character attributes attr The string being edited is stored in result Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.

    The strheight ();
    function returns the height of string in p counting newlines.

    The strwidth ();
    function returns the width of string in p counting newlines.

    The dialog_create_rc ();
    function dumps dialog library settings into filename for later retrieval as defaults. Returns 0 on success, -1 on failure.

    The dialog_yesno ();
    function displays a text box using title and prompt strings of dimensions height and width Also paint a pair of Yes and buttons at the bottom. The default selection is Yes If the Yes button is chosen, return FALSE. If , return TRUE.

    The dialog_noyes ();
    function is the same as dialog_yesno (,);
    except the default selection is

    The dialog_prgbox ();
    function displays a text box of dimensions height and width containing the output of command line If use_shell is TRUE, line is passed as an argument to sh(1), otherwise it is simply passed to exec(3). If pause is TRUE, a final confirmation requestor will be put up when execution terminates. Returns 0 on success, -1 on failure.

    The dialog_textbox ();
    function displays a text box containing the contents of file with dimensions of height and width

    The dialog_menu ();
    function displays a menu of dimensions height and width with an optional internal menu height of menu_height The cnt and 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, cnt should be a positive integer representing the number of string pointer pairs to find in it (which should be of type char ** ) , the strings are expected to be in prompt and title order for each item and the 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, cnt should be a negative integer representing the number of dialogMenuItem structures pointed to by it (which should be of type Vt dialogMenuItem * ) , one structure per item. In the new interface, the result variable is used as a simple boolean (not a pointer) and should be NULL if it only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then it is actually expected to point 2 locations past the start of the menu item list. it is then expected to point to an item representing the Cancel button, from which the prompt and fire actions are used to override the default behavior, and it to the same for the OK button.

    Using either API behavior, the ch and sc values may be passed in to preserve current item selection and scroll position values across calls.

    The dialog_checklist ();
    function displays a menu of dimensions height and width with an optional internal menu height of list_height The cnt and 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, cnt should be a positive integer representing the number of string pointer tuples to find in it (which should be of type char ** ) , the strings are expected to be in prompt, title and state ("on" or "off") order for each item and the 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, cnt should be a negative integer representing the number of dialogMenuItem structures pointed to by it (which should be of type dialogMenuItem * ) , one structure per item. In the new interface, the result variable is used as a simple boolean (not a pointer) and should be NULL if it only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then it is actually expected to point 2 locations past the start of the menu item list. it is then expected to point to an item representing the Cancel button, from which the prompt and fire actions are used to override the default behavior, and it to the same for the OK button.

    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 result string.

    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 dialog_checklist ();
    over dialog_radiolist ();
    in the new API model is to inherit the base behavior, you are no longer constrained by it.

    Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.

    The dialog_radiolist ();
    function displays a menu of dimensions height and width with an optional internal menu height of list_height The cnt and 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, cnt should be a positive integer representing the number of string pointer tuples to find in it (which should be of type char ** ) , the strings are expected to be in prompt, title and state ("on" or "off") order for each item and the 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, cnt should be a negative integer representing the number of dialogMenuItem structures pointed to by it (which should be of type dialogMenuItem * , one structure per item. In the new interface, the result variable is used as a simple boolean (not a pointer) and should be NULL if it only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then it is actually expected to point 2 locations past the start of the menu item list. it is then expected to point to an item representing the Cancel button, from which the prompt and fire actions are used to override the default behavior, and it does the same for the traditional OK button.

    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 result string.

    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 dialog_radiolist ();
    over dialog_checklistlist ();
    in the new API model is to inherit the base behavior.

    Returns 0 on success, 1 on Cancel and -1 on failure or ESC.

    The dialog_inputbox ();
    function displays a single-line text input field in a box displaying title and prompt of dimensions height and width The field entered is stored in result

    Returns 0 on success, -1 on failure or ESC.

    The dialog_fselect ();
    function brings up a file selector dialog starting at dir and showing only those file names matching fmask

    Returns filename selected or NULL.

    The dialog_dselect ();
    function brings up a directory selector dialog starting at dir and showing only those directory names matching fmask

    Returns directory name selected or NULL.

    The dialog_notify ();
    function brings up a generic "hey, you!" notifier dialog containing msg

    The dialog_mesgbox ();
    function displays a notifier dialog, but with more control over title prompt width and height This object will also wait for user confirmation, unlike dialog_notify (.);

    Returns 0 on success, -1 on failure.

    The dialog_gauge ();
    function displays a horizontal bar-graph style gauge. A value of 100 for perc constitutes a full gauge, a value of 0 an empty one.

    The use_helpfile ();
    function for any menu supporting context sensitive help, invokes the text box object on this file whenever the F1 key is pressed.

    The use_helpline ();
    function displays this line of helpful text below any menu being displayed.

    The get_helpline ();
    function gets the current value of the helpful text line.

    The dialog_clear_norefresh ();
    function clears the screen back to the dialog background color, but do not refresh the contents just yet.

    The dialog_clear ();
    function clears the screen back to the dialog background color immediately.

    The dialog_update ();
    function does any pending screen refreshes now.

    The init_dialog ();
    function initializes the dialog library (call this routine before any other dialog API calls).

    The end_dialog ();
    function shuts down the dialog library (call this if you need to get back to sanity).

    The dialog_ftree ();
    function shows a tree described by the data from the file filename The data in the file should look like find(1) output. For the find(1) output, the field separator FS will be ``/'' If height and width are positive numbers, they set the absolute size of the whole dialog_ftree ();
    box. If height and width are negative numbers, the size of the dialog_ftree ();
    box will be calculated automatically. menu_height sets the height of the tree subwindow inside the dialog_ftree ();
    box and must be set. title is shown centered on the upper border of the dialog_ftree ();
    box. prompt is shown inside the dialog_ftree ();
    box above the tree subwindow and can contain `\n' to split lines. One can navigate in the tree by pressing UP/DOWN or So + Sc / So - Sc , PG_UP/PG_DOWN or So b Sc /SPACE and HOME/END or So g Sc / So G Sc . A leaf of the tree is selected by pressing TAB or LEFT/RIGHT the OK button and pressing ENTER. filename may contain data like find(1) output, as well as like the output of find(1) with -d option. Some of the transient paths to the leaves of the tree may be absent. Such data is corrected when fed from filename.

    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 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 dialog_ftree ();
    on ESC, the function returns -1.

    The dialog_tree ();
    function returns the same results as dialog_ftree (.);
    If 0 is returned, result will contain a pointer from the array names  

    SEE ALSO

    dialog(1), ncurses(3)  

    HISTORY

    These functions appeared in Fx 2.0 as the 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 dialog_ftree ();
    and dialog_tree (.);
     

    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 .  

    BUGS

    Sure!


     

    Index

    NAME
    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    HISTORY
    AUTHORS
    BUGS


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру