chap3.txt

  
  3 Utilities using ncurses
  
  In  this  chapter  we describe the usage of some example applications of the
  ncurses interface provided by the Browse package. They may be of interest by
  themselves,  or  they  may  be  used  as  utility  functions  within  larger
  applications.
  
  
  3.1 ncurses utilities
  
  If  you  call  the  functions NCurses.Alert (3.1-1), NCurses.Select (3.1-2),
  NCurses.GetLineFromUser  (3.1-3),  or  NCurses.Pager  (3.1-4)  from  another
  ncurses  application in visual mode, you should refresh the windows that are
  still   open,   by   calling   NCurses.update_panels   and  NCurses.doupdate
  afterwards, see Section 2.1-3 and 2.1-2. Also, if the cursor shall be hidden
  after  that,  you  should  call curs_set with argument 0, see Section 2.1-1,
  since the cursor is automatically made visible in NCurses.endwin.
  
  3.1-1 NCurses.Alert
  
  NCurses.Alert( messages, timeout[, attrs] )  function
  Returns:  the integer corresponding to the character entered, or fail.
  
  In  visual  mode,  Print  (Reference: Print) cannot be used for messages. An
  alternative is given by NCurses.Alert.
  
  Let  messages  be  either  an attribute line or a nonempty list of attribute
  lines, and timeout be a nonnegative integer. NCurses.Alert shows messages in
  a bordered box in the middle of the screen.
  
  If  timeout  is  zero  then  the box is closed after any user input, and the
  integer  corresponding  to  the  entered  key  is  returned. If timeout is a
  positive  number  n,  say,  then the box is closed after n milliseconds, and
  fail is returned.
  
  If  timeout  is  zero  and  mouse  events  are enabled (see NCurses.UseMouse
  (2.2-10)) then the box can be moved inside the window via mouse events.
  
  If  the optional argument attrs is given, it must be an integer representing
  attributes  such  as  the components of NCurses.attrs (see Section 2.1-7) or
  the return value of NCurses.ColorAttr (2.2-1); these attributes are used for
  the border of the box. The default is NCurses.attrs.NORMAL.
  
    Example  
    gap> NCurses.Alert( "Hello world!", 1000 );
    fail
    gap> NCurses.Alert( [ "Hello world!",
    >      [ "Hello ", NCurses.attrs.BOLD, "bold!" ] ], 1500,
    >      NCurses.ColorAttr( "red", -1 ) + NCurses.attrs.BOLD );
    fail
  
  
  3.1-2 NCurses.Select
  
  NCurses.Select( poss[, single[, none]] )  function
  Returns:  Position or list of positions, or false.
  
  This  function  allows  the user to select one or several items from a given
  list.  In  the  simplest  case  poss  is  a  list  of  attribute  lines (see
  NCurses.IsAttributeLine (2.2-3)), each of which should fit on one line. Then
  NCurses.Select  displays  these lines and lets the user browse through them.
  After pressing the Return key the index of the highlighted item is returned.
  Note  that attributes in your lines should be switched on and off separately
  by true/false entries such that the lines can be nicely highlighted.
  
  The  optional argument single must be true (default) or false. In the second
  case,  an  arbitrary  number of items can be marked and the function returns
  the list of their indices.
  
  If  single is true a third argument none can be given. If it is true then it
  is  possible  to  leave the selection without choosing an item, in this case
  false is returned.
  
  More  details  can  be  given to the function by giving a record as argument
  poss. It can have the following components:
  
  items
        The list of attribute lines as described above.
  
  single
        Boolean with the same meaning as the optional argument single.
  
  none
        Boolean with the same meaning as the optional argument none.
  
  size
        The  size of the window like the first two arguments of NCurses.newwin
        (default  is  [0,  0],  as big as possible), or the string "fit" which
        means the smallest possible window.
  
  align
        A  substring of "bclt", which describes the alignment of the window in
        the  terminal.  The  meaning  and  the  default  are  the  same as for
        BrowseData.IsBrowseTableCellData (4.2-1).
  
  begin
        Top-left  corner  of  the  window  like  the  last  two  arguments  of
        NCurses.newwin (default is [0, 0], top-left of the screen). This value
        has priority over the align component.
  
  attribute
        An   attribute  used  for  the  display  of  the  window  (default  is
        NCurses.attrs.NORMAL).
  
  border
        If  the  window  should  be  displayed  with a border then set to true
        (default  is  false)  or to an integer representing attributes such as
        the  components  of  NCurses.attrs  (see  Section 2.1-7) or the return
        value  of NCurses.ColorAttr (2.2-1); these attributes are used for the
        border of the box. The default is NCurses.attrs.NORMAL.
  
  header
        An  attribute  line  used  as  header line (the default depends on the
        settings of single and none).
  
  hint
        An  attribute  line  used  as hint in the last line of the window (the
        default depends on the settings of single and none).
  
  onSubmitFunction
        A  function  that  is  called when the user submits the selection; the
        argument for this call is the current value of the record poss. If the
        function returns true then the selected entries are returned as usual,
        otherwise  the  selection window is kept open, waiting for new inputs;
        if  the function returns a nonempty list of attribute lines then these
        messages are shown using NCurses.Alert (3.1-1).
  
  If  mouse events are enabled (see NCurses.UseMouse (2.2-10)) then the window
  can  be  moved  on the screen via mouse events, the focus can be moved to an
  entry, and (if single is false) the selection of an entry can be toggled.
  
    Example  
    gap> index := NCurses.Select(["Apples", "Pears", "Oranges"]);
    gap> index := NCurses.Select(rec(
    >                     items := ["Apples", "Pears", "Oranges"],
    >                     single := false,
    >                     border := true,
    >                     begin := [5, 5],
    >                     size := [8, 60],
    >                     header := "Choose at least two fruits",
    >                     attribute := NCurses.ColorAttr("yellow","red"),
    >                     onSubmitFunction:= function( r )
    >                       if Length( r.RESULT ) < 2 then
    >                         return [ "Choose at least two fruits" ];
    >                       else
    >                         return true;
    >                       fi;
    >                     end ) );
  
  
  3.1-3 NCurses.GetLineFromUser
  
  NCurses.GetLineFromUser( pre )  function
  Returns:  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 pre into it. Then it waits for
  user  input.  After  hitting  the Return key the typed line is returned as a
  string  to GAP. If the user exits via hitting the Esc key instead of hitting
  the  Return  key, the function returns false. (The Esc key may be recognized
  as input only after a delay of about a second.)
  
  Some simple editing is possible during user input: The Left, Right, Home and
  End  keys,  the  Insert/Replace  keys,  and  the  Backspace/Delete  keys are
  supported.
  
  Instead  of  a  string,  pre can also be a record with the component prefix,
  whose value is the string described above. The following optional components
  of this record are supported.
  
  window
        The  window  with  the input field is created relative to this window,
        the default is 0.
  
  begin
        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
        window  component; the default is [ y-4, 2 ], where y is the height of
        this window.
  
  default
        This  string  appears as result when the window is opened, the default
        is an empty string.
  
    Example  
    gap> str := NCurses.GetLineFromUser("Your Name: ");;
    gap> Print("Hello ", str, "!\n");
  
  
  3.1-4 NCurses.Pager
  
  NCurses.Pager( lines[, border[, ly, lx, y, x]] )  function
  
  This  is  a  simple  pager  utility  for  displaying and scrolling text. The
  argument lines can be a list of attribute lines (see NCurses.IsAttributeLine
  (2.2-3))  or  a  string (the lines are separated by newline characters) or a
  record. In case of a record the following components are recognized:
  
  lines
        The list of attribute lines or a string as described above.
  
  start
        Line number to start the display.
  
  size
        The  size  [ly,  lx]  of  the  window  like the first two arguments of
        NCurses.newwin (default is [0, 0], as big as possible).
  
  begin
        Top-left  corner  [y,  x] of the window like the last two arguments of
        NCurses.newwin (default is [0, 0], top-left of the screen).
  
  attribute
        An   attribute  used  for  the  display  of  the  window  (default  is
        NCurses.attrs.NORMAL).
  
  border
        Either  one  of  true/false 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
        NCurses.WBorder (2.2-9).
  
  hint
        A text for usage info in the last line of the window.
  
  As  an  abbreviation the information from border, size and begin can also be
  specified in optional arguments.
  
    Example  
    gap> lines := List([1..100],i-> ["line ",NCurses.attrs.BOLD,String(i)]);;
    gap> NCurses.Pager(lines);
  
  
  
  3.1-5 Selection of help matches
  
  After  loading  the  Browse  package  GAP's  help  system  behaves  slightly
  different  when  a request yields several matches. The matches are shown via
  NCurses.Select  (3.1-2),  the list can be searched and filtered, and one can
  choose one match for immediate display. It is possible to not choose a match
  and the ?<nr> syntax still works.
  
  If   you  want  the  original  behavior  call  SetUserPreference(  "Browse",
  "SelectHelpMatches",   false  );  in  your  GAP  session  or  gap.ini  file,
  see 'Reference: Configuring User preferences'.
  
  
  3.1-6 Selection of package names
  
  The function LoadPackage (Reference: LoadPackage) shows a list of matches if
  only  a prefix of a package name is given. After loading the Browse package,
  NCurses.Select (3.1-2) is used for that, and one can choose a match.
  
  If   you  want  the  original  behavior  call  SetUserPreference(  "Browse",
  "SelectPackageName",   false  );  in  your  GAP  session  or  gap.ini  file,
  see 'Reference: Configuring User preferences'.
  
  
  3.2 A Demo Function
  
  3.2-1 NCurses.Demo
  
  NCurses.Demo( [inputs] )  function
  
  Let  inputs be a list of records, each with the components title (a string),
  inputblocks  (a  list  of strings, each describing some GAP statements), and
  optionally   footer   (a  string)  and  cleanup  (a  string  describing  GAP
  statements). The default is NCurses.DemoDefaults.
  
  NCurses.Demo  lets  the user choose an entry from inputs, via NCurses.Select
  (3.1-2),  and  then  executes  the  GAP statements in the first entry of the
  inputblocks  list  of this entry; these strings, together with the values of
  title  and  footer,  are shown in a window, at the bottom of the screen. The
  effects  of  calls  to  functions using ncurses 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 inputblocks, or return
  to  the  inputs  selection  (and  thus  cancel the current inputs entry), or
  return to the execution of the beginning of the current inputs entry. At the
  end  of  the  current  entry  of  inputs,  the  user  returns  to the inputs
  selection.
  
  The  GAP  statements  in  the  cleanup 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 GAP statements are executed in the global scope, that is, they
  have  the  same  effect  as  if  they  would  be  entered at the GAP prompt.
  Initially,        NCurses.Demo        sets        the        value        of
  BrowseData.defaults.work.windowParameters  to  the  parameters that describe
  the  part  of  the  screen  above  the  window  that  shows  the  inputs; so
  applications  of NCurses.BrowseGeneric (4.3-1) 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.