<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (Browse) - Chapter 3: Utilities using ncurses</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
</head>
<body>
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chapA.html">A</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">Top of Book</a> <a href="chap2.html">Previous Chapter</a> <a href="chap4.html">Next Chapter</a> </div>
<p><a id="X17F3A63788200AB4F" name="X17F3A63788200AB4F"></a></p>
<div class="ChapSects"><a href="chap3.html#X17F3A63788200AB4F">3 <span class="Heading">Utilities using <code class="code">ncurses</code></span></a>
<div class="ContSect"><span class="nocss"> </span><a href="chap3.html#X84E621798148857D">3.1 <span class="Heading"><code class="code">ncurses</code> utilities</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X83E95B4A83BC473E">3.1-1 NCurses.Alert</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X833D321E86528981">3.1-2 NCurses.Select</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X837EFD8A842257EA">3.1-3 NCurses.GetLineFromUser</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X87E1B27817F588CC0">3.1-4 NCurses.Pager</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X17D56857617D4FCD8E">3.1-5 <span class="Heading">Selection of help matches</span></a>
</span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chap3.html#X17EF34E0E17FBD3A3B">3.2 <span class="Heading">A Demo Function</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8681359F8064597B">3.2-1 NCurses.Demo</a></span>
</div>
</div>
<h3>3 <span class="Heading">Utilities using <code class="code">ncurses</code></span></h3>
<p>In this chapter we describe the usage of some example applications of the <code class="code">ncurses</code> interface provided by the <strong class="pkg">Browse</strong> package. They may be of interest by themselves, or they may be used as utility functions within larger applications.</p>
<p><a id="X84E621798148857D" name="X84E621798148857D"></a></p>
<h4>3.1 <span class="Heading"><code class="code">ncurses</code> utilities</span></h4>
<p>If you call the functions <code class="func">NCurses.Alert</code> (<a href="chap3.html#X83E95B4A83BC473E"><b>3.1-1</b></a>), <code class="func">NCurses.Select</code> (<a href="chap3.html#X833D321E86528981"><b>3.1-2</b></a>), <code class="func">NCurses.GetLineFromUser</code> (<a href="chap3.html#X837EFD8A842257EA"><b>3.1-3</b></a>), or <code class="func">NCurses.Pager</code> (<a href="chap3.html#X87E1B27817F588CC0"><b>3.1-4</b></a>) from another <code class="code">ncurses</code> application in visual mode, you should refresh the windows that are still open, by calling <code class="code">NCurses.update_panels</code> and <code class="code">NCurses.doupdate</code> afterwards, see Section <a href="chap2.html#X17D541BDE17BB8BED5"><b>2.1-3</b></a> and <a href="chap2.html#X800D5B6381F0356F"><b>2.1-2</b></a>. Also, if the cursor shall be hidden after that, you should call <code class="code">curs_set</code> with argument <code class="code">0</code>, see Section <a href="chap2.html#X8499A3A384BF1F2D"><b>2.1-1</b></a>, since the cursor is automatically made visible in <code class="code">NCurses.endwin</code>.</p>
<p><a id="X83E95B4A83BC473E" name="X83E95B4A83BC473E"></a></p>
<h5>3.1-1 NCurses.Alert</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> NCurses.Alert</code>( <var class="Arg">messages, timeout[, attrs]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>the integer corresponding to the character entered, or <code class="keyw">fail</code>.</p>
<p>In visual mode, <code class="func">Print</code> (<a href="../../../doc/ref/chap6.html#X17AFA64D917A1F39A3"><b>Reference: Print</b></a>) cannot be used for messages. An alternative is given by <code class="func">NCurses.Alert</code>.</p>
<p>Let <var class="Arg">messages</var> be either an attribute line or a nonempty list of attribute lines, and <var class="Arg">timeout</var> be a nonnegative integer. <code class="func">NCurses.Alert</code> shows <var class="Arg">messages</var> in a bordered box in the middle of the screen.</p>
<p>If <var class="Arg">timeout</var> is zero then the box is closed after any user input, and the integer corresponding to the entered key is returned. If <var class="Arg">timeout</var> is a positive number n, say, then the box is closed after n milliseconds, and <code class="keyw">fail</code> is returned.</p>
<p>If <code class="code">timeout</code> is zero and mouse events are enabled (see <code class="func">NCurses.UseMouse</code> (<a href="chap2.html#X1799C033A17AB582D7"><b>2.2-10</b></a>)) then the box can be moved inside the window via mouse events.</p>
<p>If the optional argument <var class="Arg">attrs</var> is given, it must be an integer representing attributes such as the components of <code class="code">NCurses.attrs</code> (see Section <a href="chap2.html#X1793D897483674294"><b>2.1-7</b></a>) or the return value of <code class="func">NCurses.ColorAttr</code> (<a href="chap2.html#X83ADB4E317C105B8C"><b>2.2-1</b></a>); these attributes are used for the border of the box. The default is <code class="code">NCurses.attrs.NORMAL</code>.</p>
<table class="example">
<tr><td><pre>
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
</pre></td></tr></table>
<p><a id="X833D321E86528981" name="X833D321E86528981"></a></p>
<h5>3.1-2 NCurses.Select</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> NCurses.Select</code>( <var class="Arg">poss[, single[, none]]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>Position or list of positions, or <code class="keyw">false</code>.</p>
<p>This function allows the user to select one or several items from a given list. In the simplest case <var class="Arg">poss</var> is a list of attribute lines (see <code class="func">NCurses.IsAttributeLine</code> (<a href="chap2.html#X81D1FC9217C455AEB"><b>2.2-3</b></a>)), each of which should fit on one line. Then <code class="func">NCurses.Select</code> displays these lines and lets the user browse through them. After pressing the <strong class="button">Return</strong> key the index of the highlighted item is returned. Note that attributes in your lines should be switched on and off separately by <code class="keyw">true</code>/<code class="keyw">false</code> entries such that the lines can be nicely highlighted.</p>
<p>The optional argument <var class="Arg">single</var> must be <code class="keyw">true</code> (default) or <code class="keyw">false</code>. In the second case, an arbitrary number of items can be marked and the function returns the list of their indices.</p>
<p>If <var class="Arg">single</var> is <code class="keyw">true</code> a third argument <var class="Arg">none</var> can be given. If it is <code class="keyw">true</code> then it is possible to leave the selection without choosing an item, in this case <code class="keyw">false</code> is returned.</p>
<p>More details can be given to the function by giving a record as argument <var class="Arg">poss</var>. It can have the following components:</p>
<dl>
<dt><strong class="Mark"><code class="code">items</code></strong></dt>
<dd><p>The list of attribute lines as described above.</p>
</dd>
<dt><strong class="Mark"><code class="code">single</code></strong></dt>
<dd><p>Boolean with the same meaning as the optional argument <var class="Arg">single</var>.</p>
</dd>
<dt><strong class="Mark"><code class="code">none</code></strong></dt>
<dd><p>Boolean with the same meaning as the optional argument <var class="Arg">none</var>.</p>
</dd>
<dt><strong class="Mark"><code class="code">size</code></strong></dt>
<dd><p>The size of the window like the first two arguments of <code class="code">NCurses.newwin</code> (default is <code class="code">[0, 0]</code>, as big as possible).</p>
</dd>
<dt><strong class="Mark"><code class="code">begin</code></strong></dt>
<dd><p>Top-left corner of the window like the last two arguments of <code class="code">NCurses.newwin</code> (default is <code class="code">[0, 0]</code>, top-left of the screen).</p>
</dd>
<dt><strong class="Mark"><code class="code">attribute</code></strong></dt>
<dd><p>An attribute used for the display of the window (default is <code class="code">NCurses.attrs.NORMAL</code>).</p>
</dd>
<dt><strong class="Mark"><code class="code">border</code></strong></dt>
<dd><p>Set to <code class="keyw">true</code> if the window should be displayed with a border (default is <code class="keyw">false</code>).</p>
</dd>
<dt><strong class="Mark"><code class="code">header</code></strong></dt>
<dd><p>An attribute line used as header line (the default depends on the settings of <code class="code">single</code> and <code class="code">none</code>).</p>
</dd>
<dt><strong class="Mark"><code class="code">hint</code></strong></dt>
<dd><p>An attribute line used as hint in the last line of the window (the default depends on the settings of <code class="code">single</code> and <code class="code">none</code>).</p>
</dd>
</dl>
<table class="example">
<tr><td><pre>
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 fruits",
> attribute := NCurses.ColorAttr("yellow","red") ) );
</pre></td></tr></table>
<p><a id="X837EFD8A842257EA" name="X837EFD8A842257EA"></a></p>
<h5>3.1-3 NCurses.GetLineFromUser</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> NCurses.GetLineFromUser</code>( <var class="Arg">pre</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>User input as string.</p>
<p>This function can be used to get an input string from the user. It opens a one line window and writes the given string <var class="Arg">pre</var> into it. Then it waits for user input. After hitting the <strong class="button">Return</strong> key the typed line is returned as a string to <strong class="pkg">GAP</strong>. If the user exits via hitting the <strong class="button">Esc</strong> key instead of hitting the <strong class="button">Return</strong> key, the function returns <code class="keyw">false</code>. (The <strong class="button">Esc</strong> key may be recognized as input only after a delay of about a second.)</p>
<p>Some simple editing is possible during user input: The <strong class="button">Left</strong>, <strong class="button">Right</strong>, <strong class="button">Home</strong> and <strong class="button">End</strong> keys, the <strong class="button">Insert</strong>/<strong class="button">Replace</strong> keys, and the <strong class="button">Backspace</strong>/<strong class="button">Delete</strong> keys are supported.</p>
<p>Instead of a string, <var class="Arg">pre</var> can also be a record with the component <code class="code">prefix</code>, whose value is the string described above. The following optional components of this record are supported.</p>
<dl>
<dt><strong class="Mark"><code class="code">window</code></strong></dt>
<dd><p>The window with the input field is created relative to this window, the default is 0.</p>
</dd>
<dt><strong class="Mark"><code class="code">begin</code></strong></dt>
<dd><p>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 <code class="code">window</code> component; the default is <code class="code">[ y-4, 2 ]</code>, where <code class="code">y</code> is the height of this window.</p>
</dd>
<dt><strong class="Mark"><code class="code">default</code></strong></dt>
<dd><p>This string appears as result when the window is opened, the default is an empty string.</p>
</dd>
</dl>
<table class="example">
<tr><td><pre>
gap> str := NCurses.GetLineFromUser("Your Name: ");;
gap> Print("Hello ", str, "!\n");
</pre></td></tr></table>
<p><a id="X87E1B27817F588CC0" name="X87E1B27817F588CC0"></a></p>
<h5>3.1-4 NCurses.Pager</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> NCurses.Pager</code>( <var class="Arg">lines[, border[, ly, lx, y, x]]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This is a simple pager utility for displaying and scrolling text. The argument <var class="Arg">lines</var> can be a list of attribute lines (see <code class="func">NCurses.IsAttributeLine</code> (<a href="chap2.html#X81D1FC9217C455AEB"><b>2.2-3</b></a>)) or a string (the lines are separated by newline characters) or a record. In case of a record the following components are recognized:</p>
<p>More details can be given to the function by using a record as argument <var class="Arg">poss</var>. It can have the following components:</p>
<dl>
<dt><strong class="Mark"><code class="code">lines</code></strong></dt>
<dd><p>The list of attribute lines or a string as described above.</p>
</dd>
<dt><strong class="Mark"><code class="code">start</code></strong></dt>
<dd><p>Line number to start the display.</p>
</dd>
<dt><strong class="Mark"><code class="code">size</code></strong></dt>
<dd><p>The size <code class="code">[ly, lx]</code> of the window like the first two arguments of <code class="code">NCurses.newwin</code> (default is <code class="code">[0, 0]</code>, as big as possible).</p>
</dd>
<dt><strong class="Mark"><code class="code">begin</code></strong></dt>
<dd><p>Top-left corner <code class="code">[y, x]</code> of the window like the last two arguments of <code class="code">NCurses.newwin</code> (default is <code class="code">[0, 0]</code>, top-left of the screen).</p>
</dd>
<dt><strong class="Mark"><code class="code">attribute</code></strong></dt>
<dd><p>An attribute used for the display of the window (default is <code class="code">NCurses.attrs.NORMAL</code>).</p>
</dd>
<dt><strong class="Mark"><code class="code">border</code></strong></dt>
<dd><p>Either one of <code class="keyw">true</code>/<code class="keyw">false</code> 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 <code class="func">NCurses.WBorder</code> (<a href="chap2.html#X82B8015817B37D571"><b>2.2-9</b></a>).</p>
</dd>
<dt><strong class="Mark"><code class="code">hint</code></strong></dt>
<dd><p>A text for usage info in the last line of the window.</p>
</dd>
</dl>
<p>As an abbreviation the information from <code class="code">border</code>, <code class="code">size</code> and <code class="code">begin</code> can also be specified in optional arguments.</p>
<table class="example">
<tr><td><pre>
gap> lines := List([1..100],i-> ["line ",NCurses.attrs.BOLD,String(i)]);;
gap> NCurses.Pager(lines);
</pre></td></tr></table>
<p><a id="X17D56857617D4FCD8E" name="X17D56857617D4FCD8E"></a></p>
<h5>3.1-5 <span class="Heading">Selection of help matches</span></h5>
<p>After loading the <strong class="pkg">Browse</strong> package <strong class="pkg">GAP</strong>'s help system behaves slightly different when a request yields several matches. The matches are shown via <code class="func">NCurses.Select</code> (<a href="chap3.html#X833D321E86528981"><b>3.1-2</b></a>) and one can choose one match for immediate display. It is possible to not choose a match and the <code class="code">?<nr></code> syntax still works.</p>
<p>If you want the original behavior define <code class="code">NoSelectHelpMatches := false;</code> in your <strong class="pkg">GAP</strong> session or <code class="file">.gaprc</code> file, see <a href="../../../doc/ref/chap3.html#X1790A23BE8348DCF2"><b>Reference: The .gaprc file</b></a>.</p>
<p><a id="X17EF34E0E17FBD3A3B" name="X17EF34E0E17FBD3A3B"></a></p>
<h4>3.2 <span class="Heading">A Demo Function</span></h4>
<p><a id="X8681359F8064597B" name="X8681359F8064597B"></a></p>
<h5>3.2-1 NCurses.Demo</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> NCurses.Demo</code>( <var class="Arg">[inputs]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">inputs</var> be a list of records, each with the components <code class="code">title</code> (a string), <code class="code">inputblocks</code> (a list of strings, each describing some <strong class="pkg">GAP</strong> statements), and optionally <code class="code">footer</code> (a string) and <code class="code">cleanup</code> (a string describing <strong class="pkg">GAP</strong> statements). The default is <code class="code">NCurses.DemoDefaults</code>.</p>
<p><code class="code">NCurses.Demo</code> lets the user choose an entry from <var class="Arg">inputs</var>, via <code class="func">NCurses.Select</code> (<a href="chap3.html#X833D321E86528981"><b>3.1-2</b></a>), and then executes the <strong class="pkg">GAP</strong> statements in the first entry of the <code class="code">inputblocks</code> list of this entry; these strings, together with the values of <code class="code">title</code> and <code class="code">footer</code>, are shown in a window, at the bottom of the screen. The effects of calls to functions using <code class="code">ncurses</code> 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 <code class="code">inputblocks</code>, or return to the <code class="code">inputs</code> selection (and thus cancel the current <code class="code">inputs</code> entry), or return to the execution of the beginning of the current <code class="code">inputs</code> entry. At the end of the current entry of <code class="code">inputs</code>, the user returns to the <code class="code">inputs</code> selection.</p>
<p>The <strong class="pkg">GAP</strong> statements in the <code class="code">cleanup</code> 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.</p>
<p>Note that the <strong class="pkg">GAP</strong> statements are executed in the <em>global</em> scope, that is, they have the same effect as if they would be entered at the <strong class="pkg">GAP</strong> prompt. Initially, <code class="code">NCurses.Demo</code> sets the value of <code class="code">BrowseData.defaults.work.windowParameters</code> to the parameters that describe the part of the screen above the window that shows the inputs; so applications of <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) 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.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">Top of Book</a> <a href="chap2.html">Previous Chapter</a> <a href="chap4.html">Next Chapter</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chapA.html">A</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
91213ddcfbe7f54821d42c2d9e091326
>
files
>
16
