Goto Chapter: Top 1 2 3 4 5 6 A Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

1 Introduction and Overview
1.1 Introduction
1.2 Overview
1.2-1 The `ncurses` interface
1.2-2 Applications of `ncurses`
1.2-3 The interface to browse two-dimensional arrays
1.2-4 Applications of the generic function `NCurses.BrowseGeneric`
1.3 User preferences provided by the Browse package
1.3-1 The user preference `EnableMouseEvents`
1.3-2 The user preference `SelectHelpMatches`
1.3-3 The user preference `SelectPackageName`

### 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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 A Bib Ind

generated by GAPDoc2HTML