[MathJax off]

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

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

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

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

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

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.

generated by GAPDoc2HTML