Sophie

Sophie

distrib > Mandriva > 2010.0 > i586 > media > contrib-release > by-pkgid > 91213ddcfbe7f54821d42c2d9e091326 > files > 18

gap-system-packages-4.4.12-5mdv2010.0.i586.rpm

<?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 4: Browsing Tables in GAP using ncurses
–The User Interface</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">&nbsp;<a href="chap0.html">Top of Book</a>&nbsp;  &nbsp;<a href="chap3.html">Previous Chapter</a>&nbsp;  &nbsp;<a href="chap5.html">Next Chapter</a>&nbsp;  </div>

<p><a id="X877E60DE17F53FDEC" name="X877E60DE17F53FDEC"></a></p>
<div class="ChapSects"><a href="chap4.html#X877E60DE17F53FDEC">4 <span class="Heading">Browsing Tables in <strong class="pkg">GAP</strong> using <code class="code">ncurses</code>
–The User Interface</span></a>
<div class="ContSect"><span class="nocss">&nbsp;</span><a href="chap4.html#X869EDB308717F199">4.1 <span class="Heading">Features Supported by the Function <code class="code">NCurses.BrowseGeneric</code>
</span></a>
</div>
<div class="ContSect"><span class="nocss">&nbsp;</span><a href="chap4.html#X826892121794DA877">4.2 <span class="Heading">Data Structures used by <code class="code">NCurses.BrowseGeneric</code></span></a>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap4.html#X82157A2684969A5F">4.2-1 BrowseData.IsBrowseTableCellData</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap4.html#X17CA598A717A70C3B3">4.2-2 BrowseData.BlockEntry</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap4.html#X81007E2F8552523B">4.2-3 BrowseData.IsBrowseTable</a></span>
</div>
<div class="ContSect"><span class="nocss">&nbsp;</span><a href="chap4.html#X8135D3C2806D8F92">4.3 <span class="Heading">The Function <code class="code">NCurses.BrowseGeneric</code></span></a>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap4.html#X85FC163D87FAFD12">4.3-1 NCurses.BrowseGeneric</a></span>
</div>
</div>

<h3>4 <span class="Heading">Browsing Tables in <strong class="pkg">GAP</strong> using <code class="code">ncurses</code>
–The User Interface</span></h3>

<p>As stated in Section <a href="chap1.html#X17DFB63A917E67C0A1"><b>1.1</b></a>, one aim of the <strong class="pkg">Browse</strong> package is to provide tools for the quite usual task to show a two-dimensional array or certain rows and columns of it on a character screen in a formatted way, to navigate in this array via key strokes (and mouse events), and to search for strings, to sort the array by row or column values etc.</p>

<p>The idea is that one starts with an array of data, the <em>main table</em>. Optionally, labels for each row of the main table are given, which are also arranged in an array (with perhaps several columns), the <em>row labels table</em>; analogously, a <em>column labels table</em> of labels for the columns of the main table may be given. The row labels are shown to the left of the main table, the column labels are shown above the main table. The space above the row labels and to the left of the column labels can be used for a fourth table, the <em>corner table</em>, with information about the labels or about the main table. Optionally, a <em>header</em> and a <em>footer</em> may be shown above and below these four tables, respectively. Header and footer are not separated into columns. So the shown window has the following structure.</p>

<p></p> <table rules="all" border="3"> <thead> <tr> <td colspan="2" align="center">header</td> </tr> </thead> <tfoot> <tr> <td colspan="2" align="center">footer</td> </tr> </tfoot> <tbody> <tr> <td align="center">corner</td> <td align="center">column labels</td> </tr> <tr> <td align="center">row labels</td> <td align="center">main table</td> </tr> </tbody> </table><p></p>

<p>If not the whole tables fit into the window then only subranges of rows and columns of the main table are shown, together with the corresponding row and column labels. Also in this case, the row heights and column widths are computed w.r.t. the whole table not w.r.t. the shown rows and columns. This means that the shown row labels are unchanged if the range of shown columns is changed, the shown column labels are unchanged if the range of shown rows is changed, and the whole corner table is always shown.</p>

<p>The current chapter describes the user interface for <em>standard applications</em> of this kind, i. e., those applications for which one just has to collect the data to be shown in a record –which we call a <em>browse table</em>– without need for additional <strong class="pkg">GAP</strong> programming.</p>

<p>Section <a href="chap4.html#X869EDB308717F199"><b>4.1</b></a> gives an overview of the features available in standard browse table applications, and Section <a href="chap4.html#X826892121794DA877"><b>4.2</b></a> describes the data structures used in browse tables. Finally, Section <a href="chap4.html#X8135D3C2806D8F92"><b>4.3</b></a> introduces the function <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>), which is the generic function for showing browse table in visual mode.</p>

<p>For technical details needed to extend these applications and to build other applications, see Chapter <a href="chap5.html#X82DDDC1783B4CA30"><b>5</b></a>.</p>

<p>Examples of browse table applications are shown in Chapter <a href="chap6.html#X178D4F8EA179405AF9"><b>6</b></a>.</p>

<p><a id="X869EDB308717F199" name="X869EDB308717F199"></a></p>

<h4>4.1 <span class="Heading">Features Supported by the Function <code class="code">NCurses.BrowseGeneric</code>
</span></h4>

<p>Standard applications of the function <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) have the following functionality. Other applications may provide only a subset, or add further functionality, see Chapters <a href="chap5.html#X82DDDC1783B4CA30"><b>5</b></a> and <a href="chap6.html#X178D4F8EA179405AF9"><b>6</b></a>.</p>


<dl>
<dt><strong class="Mark">Scrolling:</strong></dt>
<dd><p>The subranges of shown rows and columns of the main table can be modified, such that the focus area is moved to the left, to the right, up, or down; depending on the context, the focus is moved by one character, by one table cell or a part of it, by the window height/width (minus one character or minus one table cell). If mouse events are enabled then cells can be selected also via mouse clicks.</p>

</dd>
<dt><strong class="Mark">Selecting:</strong></dt>
<dd><p>A cell, row, or column of the main table can be selected; then it is shown highlighted on the screen (by default using the attribute <code class="code">NCurses.attrs.STANDOUT</code>, see Section <a href="chap2.html#X1793D897483674294"><b>2.1-7</b></a>). The selection can be moved inside the main table to a neighboring cell, row, or column; this causes also scrolling of the main table when the window borders are reached.</p>

</dd>
<dt><strong class="Mark">Searching:</strong></dt>
<dd><p>A search string is entered by the user, and the first matching cell becomes selected; one can search further for the next matching cell. Global search parameters define what matching means (case sensitive or not, search for substrings or complete words) and what the first and the next matching cells are (search in the whole table or just in the selected row or column, search for whole words or prefixes or suffixes, search forwards or backwards).</p>

</dd>
<dt><strong class="Mark">Sorting:</strong></dt>
<dd><p>If a row or column is selected then the main table can be sorted w.r.t. the entries in this row or column. Global sort parameters describe for example whether one wants to sort ascending or descending, or case sensitive or not.</p>

<p>If a categorized table is sorted by a column then the category rows are removed and the current sorting and filtering by rows is reset before the table is sorted by the given column. If a table is sorted by a column/row that is already sorted by a column/row then this ordering is reset first.</p>

<p>Sorting can be undone globally, i. e., one can return to the unsorted table.</p>

</dd>
<dt><strong class="Mark">Sorting and Categorizing:
</strong></dt>
<dd><p>If a column is selected then the main table can be sorted w.r.t. the entries in this column, and additionally these entries are turned into <em>category rows</em>, i. e., additional rows are added to the main table, appearing immediately above the table rows with a fixed value in the selected column, and showing this column value. (There should be no danger to mix up this notion of categories with the one introduced in <a href="../../../doc/ref/chap13.html#X17CC6903E178F24167"><b>Reference: Categories</b></a>.) The category rows can be <em>collapsed</em> (that is, the table rows that belong to this category row are not shown) or <em>expanded</em> (that is, the corresponding table rows are shown). Some of the global search parameters affect the category rows, for example, whether the category rows shall involve a counter showing the number of corresponding data rows, or whether a row of the browse table appears under different category rows.</p>

<p>Sorting and categorizing can be undone globally, i. e., one can return to the unsorted table without category rows.</p>

</dd>
<dt><strong class="Mark">Filtering:
</strong></dt>
<dd><p>The browse table can be restricted to those rows or columns in which a given search string occurs. (Also entries in collapsed rows can match; they remain collapsed then.) As a consequence, the category rows are restricted to those under which a matching row occurs. (It is irrelevant whether the search string occurs in category rows.)</p>

<p>If the search string does not occur at all then a message is printed, and the table remains as it was before. If a browse table is restricted then this fact is indicated by the message "restricted table" in the lower right corner of the window.</p>

<p>When a column or row is selected then the search is restricted to the entries in this column or row, respectively. Besides using a search, one can also explicitly hide the selected row or column. Filtering in an already restricted table restricts the shown rows or columns further.</p>

<p>Filtering can be undone globally, i. e., one can return to the unrestricted table.</p>

</dd>
<dt><strong class="Mark">Help:</strong></dt>
<dd><p>Depending on the application and on the situation, different sets of user inputs may be available and different meanings of these inputs are possible. An overview of the currently available inputs and their meanings can be opened in each situation, by hitting the <strong class="button">?</strong> key.</p>

</dd>
<dt><strong class="Mark">Re-entering:</strong></dt>
<dd><p>When one has called <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) with a browse table, and returns from visual mode to the <strong class="pkg">GAP</strong> prompt after some navigation steps, calling <code class="code">NCurses.BrowseGeneric</code> again with this table will enter visual mode in the same situation where it was left. For example, the cell in the top-left position will be the same as before, and if a cell was selected before then this cell will be selected now. (One can avoid this behavior using the optional second argument of <code class="code">NCurses.BrowseGeneric</code>.)</p>

</dd>
<dt><strong class="Mark">Logging:</strong></dt>
<dd><p>The integers corresponding to the user inputs in visual mode are collected in a list that is stored in the component <code class="code">dynamic.log</code> of the browse table. It can be used for repeating the inputs with the replay feature. (For browse table applications that give the user no access to the browse table itself, one can force the log to be assigned to the component <code class="code">log</code> of the global variable <code class="code">BrowseData</code>, see Section <a href="chap5.html#X86E80E578085F137"><b>5.4-1</b></a>.)</p>

</dd>
<dt><strong class="Mark">Replay:</strong></dt>
<dd><p>Instead of interactively hitting keys in visual mode, one can prescribe the user inputs to a browse table via a "replay record"; the inputs are then processed with given time intervals. The easiest way to create a meaningful replay record is via the function <code class="func">BrowseData.SetReplay</code> (<a href="chap5.html#X1791FB5BA17A9951F4"><b>5.4-2</b></a>), with argument the <code class="code">dynamic.log</code> component of the browse table in question that was stored in an interactive session.</p>

</dd>
</dl>
<p>The following features are not available in standard applications. They require additional programming.</p>


<dl>
<dt><strong class="Mark">Clicking:</strong></dt>
<dd><p>One possible action is to "click" a selected cell, row, or column, by hitting the <strong class="button">Enter</strong> key. It depends on the application what the effect is. A typical situation is that a corresponding <strong class="pkg">GAP</strong> object is added to the list of return values of <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>). Again it depends on the application what this <strong class="pkg">GAP</strong> object is. In order to use this feature, one has to provide a record whose components are <strong class="pkg">GAP</strong> functions, see Section <a href="chap5.html#X86E80E578085F137"><b>5.4-1</b></a> for details. If mouse events are enabled then also mouse clicks can be used as an alternative to hitting the <strong class="button">Enter</strong> key.</p>

</dd>
<dt><strong class="Mark">Return Value:
</strong></dt>
<dd><p>The function <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) may have an application dependent return value. A typical situation is that a list of objects corresponding to those cells is returned that were "clicked" in visual mode. In order to use this feature, one has to assign the desired value to the component <code class="code">dynamic.Return</code> of the browse table.</p>

</dd>
</dl>
<p><a id="X826892121794DA877" name="X826892121794DA877"></a></p>

<h4>4.2 <span class="Heading">Data Structures used by <code class="code">NCurses.BrowseGeneric</code></span></h4>

<p><a id="X82157A2684969A5F" name="X82157A2684969A5F"></a></p>

<h5>4.2-1 BrowseData.IsBrowseTableCellData</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&gt; BrowseData.IsBrowseTableCellData</code>( <var class="Arg">obj</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> if the argument is a list or a record in a supported format.</p>

<p>A <em>table cell data object</em> describes the input data for the contents of a cell in a browse table. It is represented by either an attribute line (see <code class="func">NCurses.IsAttributeLine</code> (<a href="chap2.html#X81D1FC9217C455AEB"><b>2.2-3</b></a>)), for cells of height one, or a list of attribute lines or a record with the components <code class="code">rows</code>, a list of attribute lines, and optionally <code class="code">align</code>, a substring of <code class="code">"bclt"</code>, which describes the alignment of the attribute lines in the table cell -- bottom, horizontally centered, left, and top alignment; the default is right and vertically centered alignment. (Note that the height of a table row and the width of a table column can be larger than the height and width of an individual cell.)</p>


<table class="example">
<tr><td><pre>
gap&gt; BrowseData.IsBrowseTableCellData( "abc" );
true
gap&gt; BrowseData.IsBrowseTableCellData( [ "abc", "def" ] );
true
gap&gt; BrowseData.IsBrowseTableCellData( rec( rows:= [ "ab", "cd" ],
&gt;                                           align:= "tl" ) );
true
gap&gt; BrowseData.IsBrowseTableCellData( "" );
true
gap&gt; BrowseData.IsBrowseTableCellData( [] );
true
</pre></td></tr></table>

<p>The <em>empty string</em> is a table cell data object of height one and width zero whereas the <em>empty list</em> (which is not in <code class="func">IsStringRep</code> (<a href="../../../doc/ref/chap25.html#X17A17EDF81785C9F58"><b>Reference: IsStringRep</b></a>)) is a table cell data object of height zero and width zero.</p>

<p><a id="X17CA598A717A70C3B3" name="X17CA598A717A70C3B3"></a></p>

<h5>4.2-2 BrowseData.BlockEntry</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&gt; BrowseData.BlockEntry</code>( <var class="Arg">tablecelldata, height, width</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a list of attribute lines.</p>

<p>For a table cell data object <var class="Arg">tablecelldata</var> (see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>)) and two positive integers <var class="Arg">height</var> and <var class="Arg">width</var>, <code class="code">BrowseData.BlockEntry</code> returns a list of <var class="Arg">height</var> attribute lines of displayed length <var class="Arg">width</var> each (see <code class="func">NCurses.WidthAttributeLine</code> (<a href="chap2.html#X82C53ACD805EE0C3"><b>2.2-7</b></a>)), that represents the formatted version of <var class="Arg">tablecelldata</var>.</p>

<p>If the rows of <var class="Arg">tablecelldata</var> have different numbers of displayed characters then they are filled up to the desired numbers of rows and columns, according to the alignment prescribed by <var class="Arg">tablecelldata</var>; the default alignment is right and vertically centered.</p>


<table class="example">
<tr><td><pre>
gap&gt; BrowseData.BlockEntry( "abc", 3, 5 );
[ "     ", "  abc", "     " ]
gap&gt; BrowseData.BlockEntry( rec( rows:= [ "ab", "cd" ],
&gt;                                align:= "tl" ), 3, 5 );
[ "ab   ", "cd   ", "     " ]
</pre></td></tr></table>

<p><a id="X81007E2F8552523B" name="X81007E2F8552523B"></a></p>

<h5>4.2-3 BrowseData.IsBrowseTable</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&gt; BrowseData.IsBrowseTable</code>( <var class="Arg">obj</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> if the argument record has the required components and is consistent.</p>

<p>A <em>browse table</em> is a <strong class="pkg">GAP</strong> record that can be used as the first argument of the function <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>).</p>

<p>The supported components of a browse table are <code class="code">work</code> and <code class="code">dynamic</code>, their values must be records: The components in <code class="code">work</code> describe that part of the data that are not likely to depend on user interactions, such as the table entries and their heights and widths. The components in <code class="code">dynamic</code> describe that part of the data that is intended to change with user interactions, such as the currently shown top-left entry of the table, or the current status w.r.t. sorting. For example, suppose you call <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) twice with the same browse table; the second call enters the table in the same status where it was left <em>after</em> the first call if the component <code class="code">dynamic</code> is kept, whereas one has to reset (which usually simply means to unbind) the component <code class="code">dynamic</code> if one wants to start in the same status as <em>before</em> the first call.</p>

<p>The following components are the most important ones for standard browse applications. All these components belong to the <code class="code">work</code> record. For other supported components (of <code class="code">work</code> as well as of <code class="code">dynamic</code>) and for the meaning of the term "mode", see Section <a href="chap5.html#X83290BB6864B2DD0"><b>5.2</b></a>.</p>


<dl>
<dt><strong class="Mark"><code class="code">main</code></strong></dt>
<dd><p>is the list of lists of table cell data objects that form the matrix to be shown. There is no default for this component. (It is possible to compute the entries of the main table on demand, see the description of the component <code class="code">Main</code> in Section <a href="chap5.html#X86E80E578085F137"><b>5.4-1</b></a>. In this situation, the value of the component <code class="code">main</code> can be an empty list.)</p>

</dd>
<dt><strong class="Mark"><code class="code">header</code></strong></dt>
<dd><p>describes a header that shall be shown above the column labels. The value is either a list of attribute lines ("static header") or a function or a record whose component names are names of available modes of the browse table ("dynamic header"). In the function case, the function must take the browse table as its only argument, and return a list of attribute lines. In the record case, the values of the components must be such functions. It is assumed that the number of these lines depends at most on the mode. The default is an empty list, i. e., there is no header.</p>

</dd>
<dt><strong class="Mark"><code class="code">footer</code></strong></dt>
<dd><p>describes a footer that shall be shown below the table. The value is analogous to that of <code class="code">footer</code>. The default is an empty list, i. e., there is no footer.</p>

</dd>
<dt><strong class="Mark"><code class="code">labelsRow</code></strong></dt>
<dd><p>is a list of row label rows, each being a list of table cell data objects. These rows are shown to the left of the main table. The default is an empty list, i. e., there are no row labels.</p>

</dd>
<dt><strong class="Mark"><code class="code">labelsCol</code></strong></dt>
<dd><p>is a list of column information rows, each being a list of table cell data objects. These rows are shown between the header and the main table. The default is an empty list, i. e., there are no column labels.</p>

</dd>
<dt><strong class="Mark"><code class="code">corner</code></strong></dt>
<dd><p>is a list of lists of table cell data objects that are printed in the upper left corner, i. e., to the left of the column label rows and above the row label columns. The default is an empty list.</p>

</dd>
<dt><strong class="Mark"><code class="code">sepRow</code></strong></dt>
<dd><p>describes the separators above and below rows of the main table and of the row labels table. The value is either an attribute line or a (not necessarily dense) list of attribute lines. In the former case, repetitions of the attribute line are used as separators below each row and above the first row of the table; in the latter case, repetitions of the entry at the first position (if bound) are used above the first row, and repetitions of the last bound entry before the (i+2)-th position (if there is such an entry at all) are used below the i-th table row. The default is an empty string, which means that there are no row separators.</p>

</dd>
<dt><strong class="Mark"><code class="code">sepCol</code></strong></dt>
<dd><p>describes the separators in front of and behind columns of the main table and of the column labels table. The format of the value is analogous to that of the component <code class="code">sepRow</code>; the default is the string <code class="code">" "</code> (whitespace of width one).</p>

</dd>
<dt><strong class="Mark"><code class="code">sepLabelsCol</code></strong></dt>
<dd><p>describes the separators above and below rows of the column labels table and of the corner table, analogously to <code class="code">sepRow</code>. The default is an empty string, which means that there are no column label separators.</p>

</dd>
<dt><strong class="Mark"><code class="code">sepLabelsRow</code></strong></dt>
<dd><p>describes the separators in front of and behind columns of the row labels table and of the corner table, analogously to <code class="code">sepCol</code>. The default is an empty string.</p>

</dd>
</dl>
<p>We give a few examples of standard applications.</p>

<p>The first example defines a small browse table by prescribing only the component <code class="code">work.main</code>, so the defaults for row and column labels (no such labels), and for separators are used. The table cells are given by plain strings, so they have height one. Usually this table will fit on the screen.</p>


<table class="example">
<tr><td><pre>
gap&gt; m:= 10;;  n:= 5;;
gap&gt; xpl1:= rec( work:= rec(
&gt;      main:= List( [ 1 .. m ], i -&gt; List( [ 1 .. n ],
&gt;        j -&gt; String( [ i, j ] ) ) ) ) );;
gap&gt; BrowseData.IsBrowseTable( xpl1 );
true
</pre></td></tr></table>

<p>In the second example, also row and column labels appear, and different separators are used. The table cells have height three. Also this table will usually fit on the screen.</p>


<table class="example">
<tr><td><pre>
gap&gt; m:= 6;;  n:= 5;;
gap&gt; xpl2:= rec( work:= rec(
&gt;      main:= List( [ 1 .. m ], i -&gt; List( [ 1 .. n ],
&gt;        j -&gt; rec( rows:= List( [ -i*j, i*j*1000+j, i-j ], String ),
&gt;                  align:= "c" ) ) ),
&gt;      labelsRow:= List( [ 1 .. m ], i -&gt; [ String( i ) ] ),
&gt;      labelsCol:= [ List( [ 1 .. n ], String ) ],
&gt;      sepRow:= "-",
&gt;      sepCol:= "|",
&gt;  ) );;
gap&gt; BrowseData.IsBrowseTable( xpl2 );
true
</pre></td></tr></table>

<p>The third example additionally has a static header and a dynamic footer, and the table cells involve attributes. This table will usually not fit on the screen.</p>


<table class="example">
<tr><td><pre>
gap&gt; m:= 30;;  n:= 25;;
gap&gt; xpl3:= rec( work:= rec(
&gt;      header:= [ "                    Example 3" ],
&gt;      main:= List( [ 1 .. m ], i -&gt; List( [ 1 .. n ],
&gt;        j -&gt; rec( rows:= [ String( -i*j ),
&gt;                           [ NCurses.attrs.BOLD, true,
&gt;                             NCurses.attrs.ColorPairs[56+1], true,
&gt;                             String( i*j*1000+j ),
&gt;                             NCurses.attrs.NORMAL, true ],
&gt;                             String( i-j ) ],
&gt;                  align:= "c" ) ) ),
&gt;      labelsRow:= List( [ 1 .. 30 ], i -&gt; [ String( i ) ] ),
&gt;      sepLabelsRow:= " % ",
&gt;      labelsCol:= [ List( [ 1 .. 30 ], i -&gt; [
&gt;        NCurses.attrs.ColorPairs[ 56+4 ], true,
&gt;        String( i ),
&gt;        NCurses.attrs.NORMAL, true ] ) ],
&gt;      sepLabelsCol:= "=",
&gt;      sepRow:= "*",
&gt;      sepCol:= " |",
&gt;      footer:= t -&gt; [ Concatenation( "top-left entry is: ",
&gt;                          String( t.dynamic.topleft{ [ 1, 2] } ) ) ],
&gt;  ) );;
gap&gt; BrowseData.IsBrowseTable( xpl3 );
true
</pre></td></tr></table>

<p>The fourth example illustrates that highlighting may not work properly for browse tables containing entries whose attributes are not set with explicit Boolean values, see <code class="func">NCurses.IsAttributeLine</code> (<a href="chap2.html#X81D1FC9217C455AEB"><b>2.2-3</b></a>). Call <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) with the browse table <code class="code">xpl4</code>, and select an entry (or a column or a row): Only the middle row of each selected cell will be highlighted, because only in this row, the color attribute is switched on with an explicit <code class="keyw">true</code>.</p>


<table class="example">
<tr><td><pre>
gap&gt; xpl4:= rec(
&gt;     defc:= NCurses.defaultColors,
&gt;     wd:= Maximum( List( ~.defc, Length ) ),
&gt;     ca:= NCurses.ColorAttr,
&gt;     work:= rec(
&gt;       header:= [ "Examples of NCurses.ColorAttr" ],
&gt;       main:= List( ~.defc, i -&gt; List( ~.defc,
&gt;         j -&gt; [ [ ~.ca( i, j ), String( i, ~.wd ) ],        # no true!
&gt;                [ ~.ca( i, j ), true, String( "on", ~.wd ) ],
&gt;                [ ~.ca( i, j ), String( j, ~.wd ) ] ] ) ),  # no true!
&gt;       labelsRow:= List( ~.defc, i -&gt; [ String( i ) ] ),
&gt;       labelsCol:= [ List( ~.defc, String ) ],
&gt;       sepRow:= "-",
&gt;       sepCol:= [ " |", "|" ],
&gt;  ) );;
gap&gt; BrowseData.IsBrowseTable( xpl4 );
true
</pre></td></tr></table>

<p><a id="X8135D3C2806D8F92" name="X8135D3C2806D8F92"></a></p>

<h4>4.3 <span class="Heading">The Function <code class="code">NCurses.BrowseGeneric</code></span></h4>

<p><a id="X85FC163D87FAFD12" name="X85FC163D87FAFD12"></a></p>

<h5>4.3-1 NCurses.BrowseGeneric</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&gt; NCurses.BrowseGeneric</code>( <var class="Arg">t[, arec]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>an application dependent value, or nothing.</p>

<p><code class="func">NCurses.BrowseGeneric</code> is used to show the browse table <var class="Arg">t</var> (see <code class="func">BrowseData.IsBrowseTable</code> (<a href="chap4.html#X81007E2F8552523B"><b>4.2-3</b></a>)) in a formatted way on a text screen, and allows the user to navigate in this table.</p>

<p>The optional argument <var class="Arg">arec</var>, if given, must be a record whose components <code class="code">work</code> and <code class="code">dynamic</code>, if bound, are used to provide defaults for missing values in the corresponding components of <var class="Arg">t</var>. The default for <var class="Arg">arec</var> and for the components not provided in <var class="Arg">arec</var> is <code class="code">BrowseData.defaults</code>, see <code class="func">BrowseData</code> (<a href="chap5.html#X86E80E578085F137"><b>5.4-1</b></a>), the function <code class="code">BrowseData.SetDefaults</code> sets these default values.</p>

<p>At least the component <code class="code">work.main</code> must be bound in <var class="Arg">t</var>, with value a list of list of table cell data objects, see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>).</p>

<p>When the window or the screen is too small for the browse table, according to its component <code class="code">work.minyx</code>, the table will not be shown in visual mode, and <code class="keyw">fail</code> is returned. (This holds also if there would be no return value of the call in a large enough screen.) Thus one should check for <code class="keyw">fail</code> results of programmatic calls of <code class="func">NCurses.BrowseGeneric</code>, and one should better not admit <code class="keyw">fail</code> as a regular return value.</p>

<p>Most likely, <code class="func">NCurses.BrowseGeneric</code> will not be called on the command line, but the browse table <var class="Arg">t</var> will be composed by a suitable function which then calls <code class="func">NCurses.BrowseGeneric</code>, see the examples in Chapter <a href="chap6.html#X178D4F8EA179405AF9"><b>6</b></a>.</p>


<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">Top of Book</a>&nbsp;  &nbsp;<a href="chap3.html">Previous Chapter</a>&nbsp;  &nbsp;<a href="chap5.html">Next Chapter</a>&nbsp;  </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>