[MathJax on]

5 Browsing Tables in GAP using ncurses –The Programming Interface

This chapter describes some aspects of the internals of the browse table handling. The relevant objects are action functions that implement the individual navigation steps (see Section 5.1), modes that describe the sets of available navigation steps in given situations (see Section 5.2), and browse applications that are given by the combination of several modes (see Section 5.3). Most of the related data is stored in the global variable BrowseData (5.4-1). For more details, one should look directly at the code in the file lib/browse.gi of the Browse package.

5.1 Navigation Steps in Browse Tables

Navigating in a browse table means that after entering visual mode by calling NCurses.BrowseGeneric (4.3-1), the user hits one or several keys, or uses a mouse button, and if this input is in a given set of admissible inputs then a corresponding function is executed with argument the browse table (plus additional information in the case of mouse events). The function call then may change components in this table (recommended: components in its dynamic component), such that the appearance in the window may be different afterwards, and also the admissible inputs and their effects may have changed.

The relation between the admissible inputs and the corresponding functions is application dependent. However, it is recommended to associate the same input to the same function in different situations; for example, the ? key and the F1 key should belong to a function that shows a help window (see Section 5.4-4), the q key and the Esc key should belong to a function that exits the current mode (Note that the Esc key may be recognized as input only after a delay of about a second.), the Q key should belong to a function that exits the browse application (see Section 5.4-6), the F2 key should belong to a function that saves the current window contents in a global variable (see Section 5.4-5), and the E key should belong to a function that enters a break loop (see Section 5.4-7). The Enter and Return keys should belong to a "click" on a selected table entry, and if a category row is selected then they should expand/collapse this category. The M key should toggle enabling and disabling mouse events. Mouse events on a cell or on a category row of a browse table should move the selected entry to this position; it is recommended that no functionality is lost if no mouse events are used, although the number of steps might be reduced when the mouse is used.

Each such function is wrapped into a record with the components action (the function itself) and helplines (a list of attribute lines that describes what the function does). The help lines are used by the help feature of NCurses.BrowseGeneric, see Section 5.4-4.

The action functions need not return anything. Whenever the shown screen shall be recomputed after the function call, the component dynamic.changed of the browse table must be set to true by the action functions.

After entering the first characters of an admissible input that consists of more characters, the last line of the window with the browse table shows these characters behind the prefix "partial input:". One can delete the last entered character of a partial input via the Delete and Backspace keys. It is not possible to make these keys part of an admissible input. When a partial input is given, only those user inputs have an effect that extend the partial input to (a prefix of) an admissible input. For example, asking for help by hitting the ? key will in general not work if a partial input had been entered before.

5.2 Modes in Browse Tables

In different situations, different inputs may be admissible for the same browse table, and different functions may belong to the same input. For example, the meaning of "moving down" can be different depending on whether a cell is selected or not.

The set of admissible user inputs and corresponding functions for a particular situation is collected in a mode of the browse table. (There should be no danger to mix up this notion of mode with the "visual mode" introduced in Section 1.1.) A mode is represented by a record with the components name (a string used to associate the mode with the components of header, headerLength, footer, footerLength, Click, and for the help screen), flag (a string that describes properties of the mode but that can be equal for different modes), actions (a list of records describing the navigation steps that are admissible in the mode, see Section 5.1), and ShowTables (the function used to eventually print the current window contents, the default is BrowseData.ShowTables). Due to the requirement that each admissible user input uniquely determines a corresponding function, no admissible user input can be a prefix of another admissible input, for the same mode.

Navigation steps (see Section 5.1) can change the current mode or keep the mode. It is recommended that each mode has an action to leave this mode; also an action to leave the browse table application is advisable.

In a browse table, all available modes are stored in the component work.availableModes, whose value is a list of mode records. The value of the component dynamic.activeModes is a list of mode records that is used as a stack: The current mode is the last entry in this list, changing the current mode is achieved by unbinding the last entry (so one returns to the mode from which the current mode had been entered by adding it to the list), by adding a new mode record (so one can later return to the current mode), or by replacing the last entry by another mode record. As soon as the dynamic.activeModes list becomes empty, the browse table application is left. (In this situation, if the browse table had been entered from the GAP prompt then visual mode is left, and one returns to the GAP prompt.)

The following modes are predefined by the Browse package. Each of these modes admits the user inputs ?, F1, q, Esc, Q, F2, E, and M that have been mentioned in Section 5.1.

browse

This mode admits scrolling of the browse table by a cell or by a screen, searching for a string, selecting a row, a column, or an entry, and expanding or collapsing all category rows.

help

This mode is entered by calling BrowseData.ShowHelpTable; it shows a help window concerning the actions available in the mode from which the help mode was entered. The help mode admits scrolling in the help table by a cell or by a screen. See Section 5.4-4 for details.

select_entry

In this mode, one table cell is regarded as selected; this cell is highlighted using the attribute in the component work.startSelect as a prefix of each attribute line, see the remark in Section 2.2-3. The mode admits moving the selection by one cell in the four directions, searching for a string and for further occurrences of this string, expanding or collapsing the current category row or all category rows, and executing the "click" function of this mode, provided that the component work.Click.( "select_entry" ) of the browse table is bound.

select_row

This is like the select_entry mode, except that a whole row of the browse table is highlighted. Searching is restricted to the selected row, and "click" refers to the function work.Click.( "select_row" ).

select_row_and_entry

This is a combination of the select_entry mode and the select_row mode.

select_column

This is like the select_row mode, just a column is selected not a row.

select_column_and_entry

This is like the select_row_and_entry mode, just a column is selected not a row.

5.3 Browse Applications

The data in a browse table together with the set of its available modes and the stack of active modes forms a browse application. So the part of or all functionality of the Browse package can be available ("standard application"), or additional functionality can be provided by extending available modes or adding new modes.

When NCurses.BrowseGeneric (4.3-1) has been called with the browse table t, say, the following loop is executed.

1. If the list t.dynamic.activeModes is empty then exit the browse table, and if the component t.dynamic.Return is bound then return its value. Otherwise proceed with step 2.

2. If t.dynamic.changed is true then call the ShowTables function of the current mode; this causes a redraw of the window that shows the browse table. Then go to step 3.

3. Get one character of user input. If then the current user input string is the name of an action of the current mode then call the corresponding action function and go to step 1; if the current user input string is just a prefix of the name of some actions of the current mode then go to step 3; if the current user input string is not a prefix of any name of an action of the current mode then discard the last read character and go to step 3.

When one designs a new application, it may be not obvious whether some functionality shall be implemented via one mode or via several modes. As a rule of thumb, introducing a new mode is recommended when one needs a new set of admissible actions in a given situation, and also if one wants to allow the user to perform some actions and then to return to the previous status.

5.4 Predefined Browse Functionalities

5.4-1 BrowseData

This is the record that contains the global data used by the function NCurses.BrowseGeneric (4.3-1). The components are actions, defaults, and several capitalized names for which the values are functions.

BrowseData.actions is a record containing the action records that are provided by the package, see Section 5.1. These actions are used in standard applications of NCurses.BrowseGeneric (4.3-1). Of course there is no problem with using actions that are not stored in BrowseData.actions.

BrowseData.defaults is a record that contains the defaults for the browse table used as the first argument of NCurses.BrowseGeneric (4.3-1). Important components have been described above, see BrowseData.IsBrowseTable (4.2-3), in the sense that these components provide default values of work components in browse tables. Here is a list of further interesting components.

The following components are provided in BrowseData.defaults.work.

windowParameters

is a list of four nonnegative integers, denoting the arguments of NCurses.newwin for the window in which the browse table shall be shown. The default is [ 0, 0, 0, 0 ], i. e., the window for the browse table is the full screen.

minyx

is a list of length two, the entries must be either nonnegative integers, denoting the minimal number of rows and columns that are required by the browse table, or unary functions that return these values when they are applied to the browse table; this is interesting for applications that do not support scrolling, or for applications that may have large row or column labels tables. The default is a list with two functions, the return value of the first function is the sum of the heights of the table header, the column labels table, the first table row, and the table footer, and the return value of the second function is the sum of widths of the row labels table and the width of the first column. (If the header/footer is given by a function then this part of the table is ignored in the minyx default.) Note that the conditions are checked only when NCurses.BrowseGeneric (4.3-1) is called, not after later changes of the screen size in a running browse table application.

align

is a substring of "bclt", which describes the alignment of the browse table in the window. The meaning and the default are the same as for BrowseData.IsBrowseTableCellData (4.2-1). (Of course this is relevant only if the table is smaller than the window.)

headerLength

describes the lengths of the headers in the modes for which header functions are provided. The value is a record whose component names are names of modes and the corresponding components are nonnegative integers. This component is ignored if the header component is unbound or bound to a list, missing values are computed by calls to the corresponding header function as soon as they are needed.

footerLength

corresponds to footer in the same way as headerLength to header.

Main

if bound to a function then this function can be used to compute missing values for the component main; this way one can avoid computing/storing all main values at the same time. The access to the entries of the main matrix is defined as follows: If mainFormatted[i][j] is bound then take it, if main[i][j] is bound then take it and compute the formatted version, if Main is a function then call it with arguments the browse table, i, and j, and compute the formatted version, otherwise compute the formatted version of work.emptyCell. (For the condition whether entries in mainFormatted can be bound, see below in the description of the component cacheEntries.)

cacheEntries

describes whether formatted values of the entries in the matrices given by the components corner, labelsCol, labelsRow, main, and of the corresponding row and column separators shall be stored in the components cornerFormatted, labelsColFormatted, labelsRowFormatted, and mainFormatted. The value must be a Boolean, the default is false; it should be set to true only if the tables are reasonably small.

cornerFormatted

is a list of lists of formatted entries corresponding to the corner component. Each entry is either an attribute line or a list of attribute lines (with the same number of displayed characters), the values can be computed from the input format with BrowseData.FormattedEntry. The entries are stored in this component only if the component cacheEntries has the value true. The default is an empty list.

labelsColFormatted

corresponds to labelsCol in the same way as cornerFormatted to corner.

labelsRowFormatted

corresponds to labelsRow in the same way as cornerFormatted to corner.

mainFormatted

corresponds to main in the same way as cornerFormatted to corner.

m0

is the maximal number of rows in the column labels table. If this value is not bound then it is computed from the components corner and labelsCol.

n0

is the maximal number of columns in corner and labelsRow.

m

is the maximal number of rows in labelsRow and main. This value must be set in advance if the values of main are computed using a Main function, and if the number of rows in main is larger than that in labelsRow.

n

is the maximal number of columns in labelsCol and main. This value must be set in advance if the values of main are computed using a Main function, and if the number of columns in main is larger than that in labelsCol.

heightLabelsCol

is a list of 2 m0+ 1 nonnegative integers, the entry at position i is the maximal height of the entries in the i-th row of cornerFormatted and labelsColFormatted. Values that are not bound are computed on demand from the table entries, with the function BrowseData.HeightLabelsCol. (So if one knows the needed heights in advance, it is advisable to set the values, in order to avoid that formatted table entries are computed just for computing their size.) The default is an empty list.

widthLabelsRow

is the corresponding list of 2 n0+ 1 maximal widths of entries in cornerFormatted and labelsRowFormatted.

heightRow

is the corresponding list of 2 m+ 1 maximal heights of entries in labelsRowFormatted and mainFormatted.

widthCol

is the corresponding list of 2 n+ 1 maximal widths of entries in labelsColFormatted and mainFormatted.

emptyCell

is a table cell data object to be used as the default for unbound positions in the four matrices. The default is the empty list.

sepCategories

is an attribute line to be used repeatedly as a separator below expanded category rows. The default is the string "-".

startCollapsedCategory

is a list of attribute lines to be used as prefixes of unhidden but collapsed category rows. For category rows of level i, the last bound entry before the (i+1)-th position is used. The default is a list of length one, the entry is the boldface variant of the string "> ", so collapsed category rows on different levels are treated equally.

startExpandedCategory

is a list of attribute lines to be used as prefixes of expanded category rows, analogously to startCollapsedCategory. The default is a list of length one, the entry is the boldface variant of the string "* ", so expanded category rows on different levels are treated equally.

startSelect

is an attribute line to be used as a prefix of each attribute line that belongs to a selected cell. The default is to switch the attribute NCurses.attrs.STANDOUT on, see Section 2.1-7.

Click

is a record whose component names are names of available modes of the browse table. The values are unary functions that take the browse table as their argument. If the action Click is available in the current mode and the corresponding input is entered then the function in the relevant component of the Click record is called.

availableModes

is a list whose entries are the mode records that can be used when one navigates through the browse table, see Section 5.2.

SpecialGrid

is a function that takes a browse table and a record as its arguments. It is called by BrowseData.ShowTables after the current contents of the window has been computed, and it is intended to draw an individual grid into the table that fits better than anything that can be specified in terms of row and column separators. (If other functions than BrowseData.ShowTables are used in some modes of the browse table, these functions must deal with this aspect themselves.) The default is to do nothing.

The following components are provided in BrowseData.defaults.dynamic.

changed

is a Boolean that must be set to true by action functions whenever a refresh of the window is necessary; it is automatically reset to false after the refresh.

indexRow

is a list of positive integers. The entry k at position i means that the k-th row in the mainFormatted table is shown as the i-th row. Note that depending on the current status of the browse table, the rows of mainFormatted (and of main) may be permuted, or it may even happen that a row in mainFormatted is shown several times, for example under different category rows. It is assumed (as a "sort convention") that the even positions in indexRow point to even numbers, and that the subsequent odd positions (corresponding to the following separators) point to the subsequent odd numbers. The default value is the list [ 1, 2, ..., m ], where m is the number of rows in mainFormatted (including the separator rows, so m is always odd).

indexCol

is the analogous list of positive integers that refers to columns.

topleft

is a list of four positive integers denoting the current topleft position of the main table. The value [ i, j, k, l ] means that the topleft entry is indexed by the i-th entry in indexRow, the j-th entry in indexCol, and the k-th row and l-th column inside the corresponding cell. The default is [ 1, 1, 1, 1 ].

isCollapsedRow

is a list of Booleans, of the same length as the indexRow value. If the entry at position i is true then the i-th row is currently not shown because it belongs to a collapsed category row. It is assumed (as a "hide convention") that the value at any even position equals the value at the subsequent odd position. The default is that all entries are false.

isCollapsedCol

is the corresponding list for indexCol.

isRejectedRow

is a list of Booleans. If the entry at position i is true then the i-th row is currently not shown because it does not match the current filtering of the table. Defaults, length, and hide convention are as for isCollapsedRow.

isRejectedCol

is the corresponding list for indexCol.

isRejectedLabelsRow

is a list of Booleans. If the entry at position i is true then the i-th column of row labels is currently not shown.

isRejectedLabelsCol

is the corresponding list for the column labels.

activeModes

is a list of mode records that are contained in the availableModes list of the work component of the browse table. The current mode is the last entry in this list. The default depends on the application, BrowseData.defaults prescribes the list containing only the mode with name component "browse".

selectedEntry

is a list [ i, j ]. If i = j = 0 then no table cell is selected, otherwise i and j are the row and column index of the selected cell. (Note that i and j are always even.) The default is [ 0, 0 ].

selectedCategory

is a list [ i, l ]. If i = l = 0 then no category row is selected, otherwise i and l are the row index and the level of the selected category row. (Note that i is always even.) The default is [ 0, 0 ].

searchString

is the last string for which the user has searched in the table. The default is the empty string.

searchParameters

is a list of parameters that are modified by the function BrowseData.SearchStringWithStartParameters. If one sets these parameters in a search then these values hold also for subsequent searches. So it may make sense to set the parameters to personally preferred ones.

sortFunctionForColumnsDefault

is a function with two arguments used to compare two entries in the same column of the main table (or two category row values). The default is the operation \<. (Note that this default may be not meaningful if some of the rows or columns contain strings representing numbers.)

sortFunctionForRowsDefault

is the analogous function for comparing two entries in the same row of the main table.

sortFunctionsForRows

is a list of comparison functions, if the i-th entry is bound then it replaces the sortFunctionForRowsDefault value when the table is sorted w.r.t. the i-th row.

sortFunctionsForColumns

is the analogous list of functions for the case that the table is sorted w.r.t. columns.

sortParametersForRowsDefault

is a list of parameters for sorting the main table w.r.t. entries in given rows, e. g., whether one wants to sort ascending or descending.

sortParametersForColumnsDefault

is the analogous list of parameters for sorting w.r.t. given columns. In addition to the parameters for rows, also parameters concerning category rows are available, e. g., whether the data columns that are transformed into category rows shall be hidden afterwards or not.

sortParametersForRows

is a list that contains ar position i, if bound, a list of parameters that shall replace those in sortParametersForRowsDefault when the table is sorted w.r.t. the i-th row.

sortParametersForColumns

is the analogous list of parameters lists for sorting w.r.t. columns.

categories

describes the current category rows. The value is a list [ l_1, l_2, l_3 ] where l_1 is a sorted list [ i_1, i_2, ..., i_k ] of positive integers, l_2 is a list of length k where the j-th entry is a record with the components pos (with value i_j), level (the level of the category row), value (an attribute line to be shown), separator (the separator below this category row is a repetition of this string), isUnderCollapsedCategory (true if the category row is hidden because a category row of an outer level is collapsed; note that in the false case, the category row itself can be collapsed), isRejectedCategory (true if the category row is hidden because none of th edata rows below this category match the current filtering of the table); the list l_3 contains the levels for which the category rows shall include the numbers of data rows under these category rows. The default value is [ [], [], [] ]. (Note that this "hide convention" makes sense mainly if together with a hidden category row, also the category rows on higher levels and the corresponding data rows are hidden –but this property is not checked.) Category rows are computed with the CategoryValues function in the work component of the browse table.

log

describes the session log which is currently written. The value is a list of positive integers, representing the user inputs in the current session. When GAP returns from a call to NCurses.BrowseGeneric (4.3-1), one can access the log list of the user interactions in the browse table as the value of its component dynamic.log.

If BrowseData.logStore had been set to true before NCurses.BrowseGeneric (4.3-1) had been called then the list can also be accessed as the value of BrowseData.log. If BrowseData.logStore is unbound or has a value different from true then BrowseData.log is not written. (This can be interesting in the case of browse table applications where the user does not get access to the browse table itself.)

replay

describes the non-interactive input for the current browse table. The value is a record with the components logs (a dense list of records, the default is an empty list) and pointer (a positive integer, the default is 1). If pointer is a position in logs then currently the pointer-th record is processed, otherwise the browse table has exhausted its non-interactive part, and requires interactive input. The records in log have the components steps (a list of user inputs, the default is an empty list), position (a positive integer denoting the current position in the steps list if the log is currently processed, the default is 1), replayInterval (the timeout between two steps in milliseconds if the log is processed, the default is 0), and quiet (a Boolean, true if the steps shall not be shown on the screen until the end of the log is reached, the default is false).

5.4-2 BrowseData.SetReplay

This function sets and resets the value of BrowseData.defaults.dynamic.replay.

When BrowseData.SetReplay is called with a list data as its argument then the entries are assumed to describe user inputs for a browse table for which NCurses.BrowseGeneric (4.3-1) will be called afterwards, such that replay of the inputs runs. (Valid input lists can be obtained from the component dynamic.log of the browse table in question.)

When BrowseData.SetReplay is called with the only argument false, the component is unbound (so replay is disabled, and thus calls to NCurses.BrowseGeneric (4.3-1) will require interactive user input).

The replay feature should be used by initially setting the input list, then running the replay (perhaps several times), and finally unbinding the inputs, such that subsequent uses of other browse tables do not erroneously expect their input in BrowseData.defaults.dynamic.replay.

Note that the value of BrowseData.defaults.dynamic.replay is used in a call to NCurses.BrowseGeneric (4.3-1) only if the browse table in question does not have a component dynamic.replay before the call.

5.4-3 BrowseData.AlertWithReplay

Returns: an integer representing a (simulated) user input.

The function BrowseData.AlertWithReplay is a variant of NCurses.Alert (3.1-1) that is adapted for the replay feature of the browse table t, see Section 4.1. The arguments messages and attrs are the same as the corresponding arguments of NCurses.Alert (3.1-1), the argument timeout of NCurses.Alert (3.1-1) is taken from the browse table t, as follows. If BrowseData.IsDoneReplay returns true for t then timeout is zero, so a user input is requested for closing the alert box; otherwise the requested input character is fetched from t.dynamic.replay.

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.

No alert box is shown if BrowseData.IsQuietSession returns true when called with t.dynamic.replay, otherwise the alert box is closed after the time (in milliseconds) that is given by the replayInterval value of the current entry in t.dynamic.replay.logs.

The function returns either the return value of the call to NCurses.Alert (3.1-1) (in the interactive case) or the value that was fetched from the current replay record (in the replay case).

5.4-4 BrowseData.actions.ShowHelp

There are two predefined ways for showing an overview of the admissible inputs and their meaning in the current mode of a browse table. The function BrowseData.ShowHelpTable displays this overview in a browse table (using the help mode), and BrowseData.ShowHelpPager uses NCurses.Pager.

Technically, the only difference between these two functions is that BrowseData.ShowHelpTable supports the replay feature of NCurses.BrowseGeneric (4.3-1), whereas BrowseData.ShowHelpPager simply does not call the pager in replay situations.

The action record BrowseData.actions.ShowHelp is associated with the user inputs ? or F1 in standard NCurses.BrowseGeneric (4.3-1) applications, and it is recommended to do the same in other NCurses.BrowseGeneric (4.3-1) applications. This action calls the function stored in the component work.ShowHelp of the browse table, the default (i. e., the value of BrowseData.defaults.work.ShowHelp) is BrowseData.ShowHelpTable.

gap> xpl1.work.ShowHelp:= BrowseData.ShowHelpPager;;
gap> BrowseData.SetReplay( "?Q" );
gap> Unbind( xpl1.dynamic );
gap> NCurses.BrowseGeneric( xpl1 );
gap> xpl1.work.ShowHelp:= BrowseData.ShowHelpTable;;
gap> BrowseData.SetReplay( "?dQQ" );
gap> Unbind( xpl1.dynamic );
gap> NCurses.BrowseGeneric( xpl1 );
gap> BrowseData.SetReplay( false );
gap> Unbind( xpl1.dynamic );

5.4-5 BrowseData.actions.SaveWindow

The function BrowseData.actions.SaveWindow.action asks the user to enter the name of a global GAP variable, using NCurses.GetLineFromUser (3.1-3). If this variable name is valid and if no value is bound to this variable yet then the current contents of the window of the browse table that is given as the argument is saved in this variable, using NCurses.SaveWin (2.2-11).

5.4-6 BrowseData.actions.QuitMode

The function BrowseData.actions.QuitMode.action unbinds the current mode in the browse table that is given as its argument (see Section 5.2), so the browse table returns to the mode from which this mode had been called. If the current mode is the only one, first the user is asked for confirmation whether she really wants to quit the table; only if the y key is hit, the last mode is unbound.

The function BrowseData.actions.QuitTable.action unbinds all modes in the browse table that is given as its argument, without asking for confirmation; the effect is to exit the browse application (see Section 5.3).

5.4-7 BrowseData.actions.Error

After NCurses.BrowseGeneric (4.3-1) has been called, interrupting by hitting the Ctrl-C keys is not possible. It is recommended to provide the action BrowseData.actions.Error for each mode of a NCurses.BrowseGeneric (4.3-1) application, which enters a break loop and admits returning to the application. The recommended user input for this action is the E key.

generated by GAPDoc2HTML