  
  [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.
  
