  
  [1m[4m[31m3. Utilities using [22m[32mncurses[1m[4m[31m[0m
  
  In  this  chapter  we describe the usage of some example applications of the
  [22m[32mncurses[0m interface provided by the [1mBrowse[0m package. They may be of interest by
  themselves,  or  they  may  be  used  as  utility  functions  within  larger
  applications.
  
  
  [1m[4m[31m3.1 [22m[32mncurses[1m[4m[31m utilities[0m
  
  If  you  call  the  functions [1m[34mNCurses.Alert[0m ([1m3.1-1[0m), [1m[34mNCurses.Select[0m ([1m3.1-2[0m),
  [1m[34mNCurses.GetLineFromUser[0m  ([1m3.1-3[0m),  or  [1m[34mNCurses.Pager[0m  ([1m3.1-4[0m)  from  another
  [22m[32mncurses[0m  application in visual mode, you should refresh the windows that are
  still   open,   by   calling   [22m[32mNCurses.update_panels[0m   and  [22m[32mNCurses.doupdate[0m
  afterwards, see Section [1m2.1-3[0m and [1m2.1-2[0m. Also, if the cursor shall be hidden
  after  that,  you  should  call [22m[32mcurs_set[0m with argument [22m[32m0[0m, see Section [1m2.1-1[0m,
  since the cursor is automatically made visible in [22m[32mNCurses.endwin[0m.
  
  [1m[4m[31m3.1-1 NCurses.Alert[0m
  
  [1m[34m> NCurses.Alert( [0m[22m[34mmessages, timeout[, attrs][0m[1m[34m ) ______________________[0mfunction
  [1mReturns:[0m  the integer corresponding to the character entered, or [22m[32mfail[0m.
  
  In  visual  mode, [22m[32mPrint[0m cannot be used for messages. An alternative is given
  by [22m[32mNCurses.Alert[0m.
  
  Let  [22m[34mmessages[0m  be  either  an attribute line or a nonempty list of attribute
  lines, and [22m[34mtimeout[0m be a nonnegative integer. [22m[32mNCurses.Alert[0m shows [22m[34mmessages[0m in
  a bordered box in the middle of the screen.
  
  If  [22m[34mtimeout[0m  is  zero  then  the box is closed after any user input, and the
  integer  corresponding  to  the  entered  key  is  returned. If [22m[34mtimeout[0m is a
  positive  number  n,  say,  then the box is closed after n milliseconds, and
  [22m[32mfail[0m is returned.
  
  If  the optional argument [22m[34mattrs[0m is given, it must be an integer representing
  attributes  such  as  the components of [22m[32mNCurses.attrs[0m (see Section [1m2.1-7[0m) or
  the return value of [1m[34mNCurses.ColorAttr[0m ([1m2.2-1[0m); these attributes are used for
  the border of the box. The default is [22m[32mNCurses.attrs.NORMAL[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> NCurses.Alert( "Hello world!", 1000 );[0m
    [22m[35mfail[0m
    [22m[35mgap> NCurses.Alert( [ "Hello world!",                       [0m
    [22m[35m>      [ "Hello ", NCurses.attrs.BOLD, "bold!" ] ], 1500,[0m
    [22m[35m>      NCurses.ColorAttr( "red", -1 ) + NCurses.attrs.BOLD );[0m
    [22m[35mfail[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.1-2 NCurses.Select[0m
  
  [1m[34m> NCurses.Select( [0m[22m[34mposs[, single[, none]][0m[1m[34m ) _________________________[0mfunction
  [1mReturns:[0m  Position or list of positions, or [22m[32mfalse[0m.
  
  This  function  allows  the user to select one or several items from a given
  list.  In  the  simplest  case  [22m[34mposs[0m  is  a  list  of  attribute  lines (see
  [1m[34mNCurses.IsAttributeLine[0m ([1m2.2-3[0m)), each of which should fit on one line. Then
  [1m[34mNCurses.Select[0m  displays  these lines and lets the user browse through them.
  After pressing the [1m[46mReturn[0m key the index of the highlighted item is returned.
  Note  that attributes in your lines should be switched on and off separately
  by [22m[32mtrue[0m/[22m[32mfalse[0m entries such that the lines can be nicely highlighted.
  
  The  optional argument [22m[34msingle[0m must be [22m[32mtrue[0m (default) or [22m[32mfalse[0m. In the second
  case,  an  arbitrary  number of items can be marked and the function returns
  the list of their indices.
  
  If  [22m[34msingle[0m is [22m[32mtrue[0m a third argument [22m[34mnone[0m can be given. If it is [22m[32mtrue[0m then it
  is  possible  to  leave the selection without choosing an item, in this case
  [22m[32mfalse[0m is returned.
  
  More  details  can  be  given to the function by giving a record as argument
  [22m[34mposs[0m. It can have the following components:
  
  [1m[33m[22m[32mitems[0m[0m
        The list of attribute lines as described above.
  
  [1m[33m[22m[32msingle[0m[0m
        Boolean with the same meaning as the optional argument [22m[34msingle[0m.
  
  [1m[33m[22m[32mnone[0m[0m
        Boolean with the same meaning as the optional argument [22m[34mnone[0m.
  
  [1m[33m[22m[32msize[0m[0m
        The  size of the window like the first two arguments of [22m[32mNCurses.newwin[0m
        (default is [22m[32m[0, 0][0m, as big as possible).
  
  [1m[33m[22m[32mbegin[0m[0m
        Top-left  corner  of  the  window  like  the  last  two  arguments  of
        [22m[32mNCurses.newwin[0m (default is [22m[32m[0, 0][0m, top-left of the screen).
  
  [1m[33m[22m[32mattribute[0m[0m
        An   attribute  used  for  the  display  of  the  window  (default  is
        [22m[32mNCurses.attrs.NORMAL[0m).
  
  [1m[33m[22m[32mborder[0m[0m
        Set  to  [22m[32mtrue[0m if the window should be displayed with a border (default
        is [22m[32mfalse[0m).
  
  [1m[33m[22m[32mheader[0m[0m
        An  attribute  line  used  as  header line (the default depends on the
        settings of [22m[32msingle[0m and [22m[32mnone[0m).
  
  [1m[33m[22m[32mhint[0m[0m
        An  attribute  line  used  as hint in the last line of the window (the
        default depends on the settings of [22m[32msingle[0m and [22m[32mnone[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> index := NCurses.Select(["Apples", "Pears", "Oranges"]);[0m
    [22m[35mgap> index := NCurses.Select(rec([0m
    [22m[35m>                     items := ["Apples", "Pears", "Oranges"],[0m
    [22m[35m>                     single := false,[0m
    [22m[35m>                     border := true,[0m
    [22m[35m>                     begin := [5, 5],[0m
    [22m[35m>                     size := [8, 60],[0m
    [22m[35m>                     header := "Choose fruits",[0m
    [22m[35m>                     attribute := NCurses.ColorAttr("yellow","red") ) );[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.1-3 NCurses.GetLineFromUser[0m
  
  [1m[34m> NCurses.GetLineFromUser( [0m[22m[34mpre[0m[1m[34m ) ___________________________________[0mfunction
  [1mReturns:[0m  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 [22m[34mpre[0m into it. Then it waits for
  user  input.  After  hitting  the [1m[46mReturn[0m key the typed line is returned as a
  string  to [1mGAP[0m. If the user exits via hitting the [1m[46mEsc[0m key instead of hitting
  the  [1m[46mReturn[0m  key, the function returns [22m[32mfalse[0m. (The [1m[46mEsc[0m key may be recognized
  as input only after a delay of about a second.)
  
  Some simple editing is possible during user input: The [1m[46mLeft[0m, [1m[46mRight[0m, [1m[46mHome[0m and
  [1m[46mEnd[0m  keys,  the  [1m[46mInsert[0m/[1m[46mReplace[0m  keys,  and  the  [1m[46mBackspace[0m/[1m[46mDelete[0m  keys are
  supported.
  
  Instead  of  a  string,  [22m[34mpre[0m can also be a record with the component [22m[32mprefix[0m,
  whose value is the string described above. The following optional components
  of this record are supported.
  
  [1m[33m[22m[32mwindow[0m[0m
        The  window  with  the input field is created relative to this window,
        the default is 0.
  
  [1m[33m[22m[32mbegin[0m[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
        [22m[32mwindow[0m  component; the default is [22m[32m[ y-4, 2 ][0m, where [22m[32my[0m is the height of
        this window.
  
  [1m[33m[22m[32mdefault[0m[0m
        This  string  appears as result when the window is opened, the default
        is an empty string.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> str := NCurses.GetLineFromUser("Your Name: ");;[0m
    [22m[35mgap> Print("Hello ", str, "!\n");[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m3.1-4 NCurses.Pager[0m
  
  [1m[34m> NCurses.Pager( [0m[22m[34mlines[, border[, ly, lx, y, x]][0m[1m[34m ) _________________[0mfunction
  
  This  is  a  simple  pager  utility  for  displaying and scrolling text. The
  argument [22m[34mlines[0m can be a list of attribute lines (see [1m[34mNCurses.IsAttributeLine[0m
  ([1m2.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
  [22m[34mposs[0m. It can have the following components:
  
  [1m[33m[22m[32mlines[0m[0m
        The list of attribute lines or a string as described above.
  
  [1m[33m[22m[32mstart[0m[0m
        Line number to start the display.
  
  [1m[33m[22m[32msize[0m[0m
        The  size  [22m[32m[ly,  lx][0m  of  the  window  like the first two arguments of
        [22m[32mNCurses.newwin[0m (default is [22m[32m[0, 0][0m, as big as possible).
  
  [1m[33m[22m[32mbegin[0m[0m
        Top-left  corner  [22m[32m[y,  x][0m of the window like the last two arguments of
        [22m[32mNCurses.newwin[0m (default is [22m[32m[0, 0][0m, top-left of the screen).
  
  [1m[33m[22m[32mattribute[0m[0m
        An   attribute  used  for  the  display  of  the  window  (default  is
        [22m[32mNCurses.attrs.NORMAL[0m).
  
  [1m[33m[22m[32mborder[0m[0m
        Either  one  of  [22m[32mtrue[0m/[22m[32mfalse[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
        [1m[34mNCurses.WBorder[0m ([1m2.2-9[0m).
  
  [1m[33m[22m[32mhint[0m[0m
        A text for usage info in the last line of the window.
  
  As  an  abbreviation the information from [22m[32mborder[0m, [22m[32msize[0m and [22m[32mbegin[0m can also be
  specified in optional arguments.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> lines := List([1..100],i-> ["line ",NCurses.attrs.BOLD,String(i)]);;[0m
    [22m[35mgap> NCurses.Pager(lines);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m3.1-5 Selection of help matches[0m
  
  After  loading  the  [1mBrowse[0m  package  [1mGAP[0m's  help  system  behaves  slightly
  different  when  a request yields several matches. The matches are shown via
  [1m[34mNCurses.Select[0m  ([1m3.1-2[0m)  and one can choose one match for immediate display.
  It is possible to not choose a match and the [22m[32m?<nr>[0m syntax still works.
  
  If  you  want  the original behavior define [22m[32mNoSelectHelpMatches := false;[0m in
  your [1mGAP[0m session or [1m.gaprc[0m file, see [1m`Reference: The .gaprc file'[0m.
  
  
  [1m[4m[31m3.2 A Demo Function[0m
  
  [1m[4m[31m3.2-1 NCurses.Demo[0m
  
  [1m[34m> NCurses.Demo( [0m[22m[34m[inputs][0m[1m[34m ) _________________________________________[0mfunction
  
  Let  [22m[34minputs[0m be a list of records, each with the components [22m[32mtitle[0m (a string),
  [22m[32minputblocks[0m  (a  list  of strings, each describing some [1mGAP[0m statements), and
  optionally   [22m[32mfooter[0m   (a  string)  and  [22m[32mcleanup[0m  (a  string  describing  [1mGAP[0m
  statements). The default is [22m[32mNCurses.DemoDefaults[0m.
  
  [22m[32mNCurses.Demo[0m  lets  the user choose an entry from [22m[34minputs[0m, via [1m[34mNCurses.Select[0m
  ([1m3.1-2[0m),  and  then  executes  the  [1mGAP[0m statements in the first entry of the
  [22m[32minputblocks[0m  list  of this entry; these strings, together with the values of
  [22m[32mtitle[0m  and  [22m[32mfooter[0m,  are shown in a window, at the bottom of the screen. The
  effects  of  calls  to  functions using [22m[32mncurses[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 [22m[32minputblocks[0m, or return
  to  the  [22m[32minputs[0m  selection  (and  thus  cancel the current [22m[32minputs[0m entry), or
  return to the execution of the beginning of the current [22m[32minputs[0m entry. At the
  end  of  the  current  entry  of  [22m[32minputs[0m,  the  user  returns  to the [22m[32minputs[0m
  selection.
  
  The  [1mGAP[0m  statements  in  the  [22m[32mcleanup[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 [1mGAP[0m statements are executed in the [22m[36mglobal[0m scope, that is, they
  have  the  same  effect  as  if  they  would  be  entered at the [1mGAP[0m prompt.
  Initially,        [22m[32mNCurses.Demo[0m        sets        the        value        of
  [22m[32mBrowseData.defaults.work.windowParameters[0m  to  the  parameters that describe
  the  part  of  the  screen  above  the  window  that  shows  the  inputs; so
  applications  of [1m[34mNCurses.BrowseGeneric[0m ([1m4.3-1[0m) 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.
  
