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

[MathJax on]

3 Utilities using `ncurses`
3.1 `ncurses` utilities
3.1-1 NCurses.Alert
3.1-2 NCurses.Select
3.1-3 NCurses.GetLineFromUser
3.1-4 NCurses.Pager
3.1-5 Selection of help matches
3.1-6 Selection of package names
3.2 A Demo Function
3.2-1 NCurses.Demo

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

    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.

    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.

    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.

    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.

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

generated by GAPDoc2HTML