[1X3 Utilities using [10Xncurses[1X[0X In this chapter we describe the usage of some example applications of the [10Xncurses[0m interface provided by the [5XBrowse[0m package. They may be of interest by themselves, or they may be used as utility functions within larger applications. [1X3.1 [10Xncurses[1X utilities[0X If you call the functions [2XNCurses.Alert[0m ([14X3.1-1[0m), [2XNCurses.Select[0m ([14X3.1-2[0m), [2XNCurses.GetLineFromUser[0m ([14X3.1-3[0m), or [2XNCurses.Pager[0m ([14X3.1-4[0m) from another [10Xncurses[0m application in visual mode, you should refresh the windows that are still open, by calling [10XNCurses.update_panels[0m and [10XNCurses.doupdate[0m afterwards, see Section [14X2.1-3[0m and [14X2.1-2[0m. Also, if the cursor shall be hidden after that, you should call [10Xcurs_set[0m with argument [10X0[0m, see Section [14X2.1-1[0m, since the cursor is automatically made visible in [10XNCurses.endwin[0m. [1X3.1-1 NCurses.Alert[0m [2X> NCurses.Alert( [0X[3Xmessages, timeout[, attrs][0X[2X ) ______________________[0Xfunction [6XReturns:[0X the integer corresponding to the character entered, or [9Xfail[0m. In visual mode, [2XPrint[0m ([14XReference: Print[0m) cannot be used for messages. An alternative is given by [2XNCurses.Alert[0m. Let [3Xmessages[0m be either an attribute line or a nonempty list of attribute lines, and [3Xtimeout[0m be a nonnegative integer. [2XNCurses.Alert[0m shows [3Xmessages[0m in a bordered box in the middle of the screen. If [3Xtimeout[0m is zero then the box is closed after any user input, and the integer corresponding to the entered key is returned. If [3Xtimeout[0m is a positive number n, say, then the box is closed after n milliseconds, and [9Xfail[0m is returned. If [10Xtimeout[0m is zero and mouse events are enabled (see [2XNCurses.UseMouse[0m ([14X2.2-10[0m)) then the box can be moved inside the window via mouse events. If the optional argument [3Xattrs[0m is given, it must be an integer representing attributes such as the components of [10XNCurses.attrs[0m (see Section [14X2.1-7[0m) or the return value of [2XNCurses.ColorAttr[0m ([14X2.2-1[0m); these attributes are used for the border of the box. The default is [10XNCurses.attrs.NORMAL[0m. [4X--------------------------- Example ----------------------------[0X [4Xgap> NCurses.Alert( "Hello world!", 1000 );[0X [4Xfail[0X [4Xgap> NCurses.Alert( [ "Hello world!",[0X [4X> [ "Hello ", NCurses.attrs.BOLD, "bold!" ] ], 1500,[0X [4X> NCurses.ColorAttr( "red", -1 ) + NCurses.attrs.BOLD );[0X [4Xfail[0X [4X------------------------------------------------------------------[0X [1X3.1-2 NCurses.Select[0m [2X> NCurses.Select( [0X[3Xposs[, single[, none]][0X[2X ) _________________________[0Xfunction [6XReturns:[0X Position or list of positions, or [9Xfalse[0m. This function allows the user to select one or several items from a given list. In the simplest case [3Xposs[0m is a list of attribute lines (see [2XNCurses.IsAttributeLine[0m ([14X2.2-3[0m)), each of which should fit on one line. Then [2XNCurses.Select[0m displays these lines and lets the user browse through them. After pressing the [12XReturn[0m key the index of the highlighted item is returned. Note that attributes in your lines should be switched on and off separately by [9Xtrue[0m/[9Xfalse[0m entries such that the lines can be nicely highlighted. The optional argument [3Xsingle[0m must be [9Xtrue[0m (default) or [9Xfalse[0m. In the second case, an arbitrary number of items can be marked and the function returns the list of their indices. If [3Xsingle[0m is [9Xtrue[0m a third argument [3Xnone[0m can be given. If it is [9Xtrue[0m then it is possible to leave the selection without choosing an item, in this case [9Xfalse[0m is returned. More details can be given to the function by giving a record as argument [3Xposs[0m. It can have the following components: [8X[10Xitems[0m[8X[0m The list of attribute lines as described above. [8X[10Xsingle[0m[8X[0m Boolean with the same meaning as the optional argument [3Xsingle[0m. [8X[10Xnone[0m[8X[0m Boolean with the same meaning as the optional argument [3Xnone[0m. [8X[10Xsize[0m[8X[0m The size of the window like the first two arguments of [10XNCurses.newwin[0m (default is [10X[0, 0][0m, as big as possible). [8X[10Xbegin[0m[8X[0m Top-left corner of the window like the last two arguments of [10XNCurses.newwin[0m (default is [10X[0, 0][0m, top-left of the screen). [8X[10Xattribute[0m[8X[0m An attribute used for the display of the window (default is [10XNCurses.attrs.NORMAL[0m). [8X[10Xborder[0m[8X[0m Set to [9Xtrue[0m if the window should be displayed with a border (default is [9Xfalse[0m). [8X[10Xheader[0m[8X[0m An attribute line used as header line (the default depends on the settings of [10Xsingle[0m and [10Xnone[0m). [8X[10Xhint[0m[8X[0m An attribute line used as hint in the last line of the window (the default depends on the settings of [10Xsingle[0m and [10Xnone[0m). [4X--------------------------- Example ----------------------------[0X [4Xgap> index := NCurses.Select(["Apples", "Pears", "Oranges"]);[0X [4Xgap> index := NCurses.Select(rec([0X [4X> items := ["Apples", "Pears", "Oranges"],[0X [4X> single := false,[0X [4X> border := true,[0X [4X> begin := [5, 5],[0X [4X> size := [8, 60],[0X [4X> header := "Choose fruits",[0X [4X> attribute := NCurses.ColorAttr("yellow","red") ) );[0X [4X------------------------------------------------------------------[0X [1X3.1-3 NCurses.GetLineFromUser[0m [2X> NCurses.GetLineFromUser( [0X[3Xpre[0X[2X ) ___________________________________[0Xfunction [6XReturns:[0X User input as string. This function can be used to get an input string from the user. It opens a one line window and writes the given string [3Xpre[0m into it. Then it waits for user input. After hitting the [12XReturn[0m key the typed line is returned as a string to [5XGAP[0m. If the user exits via hitting the [12XEsc[0m key instead of hitting the [12XReturn[0m key, the function returns [9Xfalse[0m. (The [12XEsc[0m key may be recognized as input only after a delay of about a second.) Some simple editing is possible during user input: The [12XLeft[0m, [12XRight[0m, [12XHome[0m and [12XEnd[0m keys, the [12XInsert[0m/[12XReplace[0m keys, and the [12XBackspace[0m/[12XDelete[0m keys are supported. Instead of a string, [3Xpre[0m can also be a record with the component [10Xprefix[0m, whose value is the string described above. The following optional components of this record are supported. [8X[10Xwindow[0m[8X[0m The window with the input field is created relative to this window, the default is 0. [8X[10Xbegin[0m[8X[0m This is a list with the coordinates of the upper left corner of the window with the input field, relative to the window described by the [10Xwindow[0m component; the default is [10X[ y-4, 2 ][0m, where [10Xy[0m is the height of this window. [8X[10Xdefault[0m[8X[0m This string appears as result when the window is opened, the default is an empty string. [4X--------------------------- Example ----------------------------[0X [4Xgap> str := NCurses.GetLineFromUser("Your Name: ");;[0X [4Xgap> Print("Hello ", str, "!\n");[0X [4X------------------------------------------------------------------[0X [1X3.1-4 NCurses.Pager[0m [2X> NCurses.Pager( [0X[3Xlines[, border[, ly, lx, y, x]][0X[2X ) _________________[0Xfunction This is a simple pager utility for displaying and scrolling text. The argument [3Xlines[0m can be a list of attribute lines (see [2XNCurses.IsAttributeLine[0m ([14X2.2-3[0m)) or a string (the lines are separated by newline characters) or a record. In case of a record the following components are recognized: More details can be given to the function by using a record as argument [3Xposs[0m. It can have the following components: [8X[10Xlines[0m[8X[0m The list of attribute lines or a string as described above. [8X[10Xstart[0m[8X[0m Line number to start the display. [8X[10Xsize[0m[8X[0m The size [10X[ly, lx][0m of the window like the first two arguments of [10XNCurses.newwin[0m (default is [10X[0, 0][0m, as big as possible). [8X[10Xbegin[0m[8X[0m Top-left corner [10X[y, x][0m of the window like the last two arguments of [10XNCurses.newwin[0m (default is [10X[0, 0][0m, top-left of the screen). [8X[10Xattribute[0m[8X[0m An attribute used for the display of the window (default is [10XNCurses.attrs.NORMAL[0m). [8X[10Xborder[0m[8X[0m Either one of [9Xtrue[0m/[9Xfalse[0m to show the pager window with or without a standard border. Or it can be string with eight, two or one characters, giving characters to be used for a border, see [2XNCurses.WBorder[0m ([14X2.2-9[0m). [8X[10Xhint[0m[8X[0m A text for usage info in the last line of the window. As an abbreviation the information from [10Xborder[0m, [10Xsize[0m and [10Xbegin[0m can also be specified in optional arguments. [4X--------------------------- Example ----------------------------[0X [4Xgap> lines := List([1..100],i-> ["line ",NCurses.attrs.BOLD,String(i)]);;[0X [4Xgap> NCurses.Pager(lines);[0X [4X------------------------------------------------------------------[0X [1X3.1-5 Selection of help matches[0X After loading the [5XBrowse[0m package [5XGAP[0m's help system behaves slightly different when a request yields several matches. The matches are shown via [2XNCurses.Select[0m ([14X3.1-2[0m) and one can choose one match for immediate display. It is possible to not choose a match and the [10X?<nr>[0m syntax still works. If you want the original behavior define [10XNoSelectHelpMatches := false;[0m in your [5XGAP[0m session or [11X.gaprc[0m file, see [14X'Reference: The .gaprc file'[0m. [1X3.2 A Demo Function[0X [1X3.2-1 NCurses.Demo[0m [2X> NCurses.Demo( [0X[3X[inputs][0X[2X ) _________________________________________[0Xfunction Let [3Xinputs[0m be a list of records, each with the components [10Xtitle[0m (a string), [10Xinputblocks[0m (a list of strings, each describing some [5XGAP[0m statements), and optionally [10Xfooter[0m (a string) and [10Xcleanup[0m (a string describing [5XGAP[0m statements). The default is [10XNCurses.DemoDefaults[0m. [10XNCurses.Demo[0m lets the user choose an entry from [3Xinputs[0m, via [2XNCurses.Select[0m ([14X3.1-2[0m), and then executes the [5XGAP[0m statements in the first entry of the [10Xinputblocks[0m list of this entry; these strings, together with the values of [10Xtitle[0m and [10Xfooter[0m, are shown in a window, at the bottom of the screen. The effects of calls to functions using [10Xncurses[0m are shown in the rest of the screen. After the execution of the statements (which may require user input), the user can continue with the next entry of [10Xinputblocks[0m, or return to the [10Xinputs[0m selection (and thus cancel the current [10Xinputs[0m entry), or return to the execution of the beginning of the current [10Xinputs[0m entry. At the end of the current entry of [10Xinputs[0m, the user returns to the [10Xinputs[0m selection. The [5XGAP[0m statements in the [10Xcleanup[0m component, if available, are executed whenever the user does not continue; this is needed for deleting panels and windows that are defined in the statements of the current entry. Note that the [5XGAP[0m statements are executed in the [13Xglobal[0m scope, that is, they have the same effect as if they would be entered at the [5XGAP[0m prompt. Initially, [10XNCurses.Demo[0m sets the value of [10XBrowseData.defaults.work.windowParameters[0m to the parameters that describe the part of the screen above the window that shows the inputs; so applications of [2XNCurses.BrowseGeneric[0m ([14X4.3-1[0m) use automatically the maximal part of the screen as their window. It is recommended to use a screen with at least 80 columns and at least 37 rows.