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