chap1.txt

  
  1 Introduction and Overview
  
  
  1.1 Introduction
  
  The motivation of the package Browse was to provide better functionality for
  displaying  two-dimensional  arrays of data (e.g., character tables): moving
  through  the data without loosing row and column labels, searching for text,
  displaying  extra information, hiding information, allowing interactive user
  input, ...
  
  We  wanted  to  achieve  this  by  using  the  capabilities  of the terminal
  emulations  in which GAP is running, and not by some external graphical user
  interface.  For  this  we  have chosen to use the widely available C-library
  ncurses, see [NCu]. It contains functions to find out terminal capabilities,
  to  change properties of terminals, to place text, to handle several windows
  with  overlapping,  ... To use these functions the terminal is switched to a
  visual  mode  so that the display of the non-visual mode of your terminal in
  which GAP is running is not clobbered.
  
  Browse has now three levels of functionality:
  
  A low level interface to ncurses
        This  may  be  interesting for all kinds of applications which want to
        display  text  with  some  markup  including  colors, maybe in several
        windows, using the available capabilities of a terminal.
  
  A medium level interface to a generic function NCurses.BrowseGeneric (4.3-1)
        This  is for displaying two-dimensional arrays of data, handles labels
        for rows and columns, searching, sorting, binding keys to actions, ...
        If  you want to implement such applications for further kinds of data,
        first   look  at  the  examples  in  Section  BrowseData.IsBrowseTable
        (4.2-3), then check what can be copied from the examples in Chapter 6,
        and consult the descriptions in Chapters 4 and 5.
  
  Applications of these interfaces
        We  provide  some  applications  of  the  ncurses interface and of the
        generic   NCurses.BrowseGeneric   (4.3-1)   function.   These  may  be
        interesting  for  end  users,  and also as examples for programmers of
        further  applications. This includes (of course) a method for browsing
        through   character   tables,  functions  for  browsing  through  data
        collections, several games, and an interface for demos.
  
  Users  interested  only  in  these  applications  should  perhaps  just  try
  NCurses.Demo().
  
  
  1.2 Overview
  
  
  1.2-1 The ncurses interface
  
  Chapter  2  describes GAP's interface to the ncurses C-library. The imported
  C-functions  are  shortly explained, but for further details we refer to the
  documentation of that library. There are also a few utility functions on GAP
  level,  such  as  NCurses.SetTerm  (2.2-2),  which  simplify  the use of the
  library.
  
  The concept of an attribute line, see NCurses.IsAttributeLine (2.2-3), helps
  to deal with text with markup for its display in a terminal window.
  
  This  chapter  is  for  users  who  want  to write their own applications of
  ncurses.
  
  
  1.2-2 Applications of ncurses
  
  In  Chapter  3  we  describe  some  interactive  applications of the ncurses
  interface. For example, there is NCurses.Select (3.1-2) for asking a user to
  choose  one  or  several  of  a  given  list  of items. There is also a demo
  function  NCurses.Demo  (3.2-1)  which we use to demonstrate features of the
  Browse package, but it may be interesting for other kinds of demos as well.
  
  
  1.2-3 The interface to browse two-dimensional arrays
  
  Chapters   4   and   5   describe   the  interface  to  a  generic  function
  NCurses.BrowseGeneric  (4.3-1)  which can be used for an interactive display
  of  two-dimensional  arrays  of  data.  The  first of these covers the basic
  functionality  which  may be sufficient for many applications and the second
  gives  more  technical  details. With interactive display we mean that it is
  not  only  possible  to  scroll  through  the  data,  but one can search for
  strings,  sort by rows or columns, select entries, bind arbitrary actions to
  keys and mouse events, ask for help, and more.
  
  
  1.2-4 Applications of the generic function NCurses.BrowseGeneric
  
  In  Chapter  6  we describe several applications which are using the generic
  NCurses.BrowseGeneric (4.3-1) interface introduced before. They are provided
  as  prototype  applications and so we include some implementation remarks in
  their documentation.
  
  Users  who just want to use these applications hopefully do not need to read
  this Browse manual, all applications are coming with built-in help windows.
  
  There  are  different  kinds  of  applications. First, there are methods for
  browsing  through  character  tables  and  tables  of  marks  (our  original
  motivation  for  this  package).  Then  there  are applications for browsing
  through  data  collections,  e.g.,  the  data available through the AtlasRep
  package,  the  GAP bibliography or the sections of the GAP manuals. Finally,
  there  are  several  games like Sam Loyd's fifteen puzzle (generalized), peg
  solitaire,  and  Sudoku  (including  functions  to create new puzzles and to
  solve puzzles).
  
  
  1.3 User preferences provided by the Browse package
  
  See   SetUserPreference   (Reference:   SetUserPreference)  for  GAP's  user
  preferences  mechanism,  and  BrowseUserPreferences (6.10-1) for viewing and
  modifying user preferences.
  
  
  1.3-1 The user preference EnableMouseEvents
  
  This  user preference defines whether mouse events are enabled by default in
  visual  mode  (value true) or not (value false, this is the default). During
  the  GAP  session, the value can be changed using NCurses.UseMouse (2.2-10).
  Inside   browse  applications  based  on  NCurses.BrowseGeneric  (4.3-1)  or
  NCurses.Select  (3.1-2),  the  value can be toggled usually by hitting the M
  key.
  
  
  1.3-2 The user preference SelectHelpMatches
  
  In  the  case  that  the  GAP  help system finds multiple matches, true (the
  default)  means that the user can choose one entry from a list that is shown
  via  NCurses.Select (3.1-2), and false means that the matches are just shown
  in a pager.
  
  
  1.3-3 The user preference SelectPackageName
  
  In  the  case  that  LoadPackage  (Reference:  LoadPackage) is called with a
  prefix  of  some  package  names, true (the default) means that the user can
  choose  one  matching  entry,  and  false  means  that  the matches are just
  printed.