Quelle main.tex
Sprache: Latech
|
|
% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}
%% for a long time these were red and blue by default,
%% now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\usepackage{fancyvrb}
\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[
pdftex=true,
bookmarks=true,
a4paper=true,
pdftitle={Written with GAPDoc},
pdfcreator={LaTeX with hyperref package / GAPDoc},
colorlinks=true,
backref=page,
breaklinks=true,
linkcolor=linkColor,
citecolor=citeColor,
filecolor=fileColor,
urlcolor=urlColor,
pdfpagemode={UseNone},
]{hyperref}
\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}
% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages
\newcommand{\GAP}{\textsf{GAP}}
%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}
%% depth of toc
\setcounter{tocdepth}{1}
%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}
\begin{document}
\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill
\begin{center}{\maintitlesize \textbf{\textsf{Browse}\mbox{}}}\\
\vfill
\hypersetup{pdftitle=\textsf{Browse}}
\markright{\scriptsize \mbox{}\hfill \textsf{Browse} \hfill\mbox{}}
{\Huge ( Version 1.8.21 ) \mbox{}}\\[1cm]
{March 2023\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Thomas Breuer \mbox{}}}\\
{\Large \textbf{ Frank L{\"u}beck \mbox{}}}\\
\hypersetup{pdfauthor= Thomas Breuer ; Frank L{\"u}beck }
\end{center}\vfill
\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Thomas Breuer } Email: \href{mailto://Thomas.Breuer@Math.RWTH-Aachen.De} {\texttt{Thomas.Breuer@Math.RWTH-Aachen.De}}\\
Homepage: \href{https://www.math.rwth-aachen.de/~Thomas.Breuer} {\texttt{https://www.math.rwth-aachen.de/\texttt{\symbol{126}}Thomas.Breuer}}}\\
{\mbox{}\\
\small \noindent \textbf{ Frank L{\"u}beck } Email: \href{mailto://Frank.Luebeck@Math.RWTH-Aachen.De} {\texttt{Frank.Luebeck@Math.RWTH-Aachen.De}}\\
Homepage: \href{https://www.math.rwth-aachen.de/~Frank.Luebeck} {\texttt{https://www.math.rwth-aachen.de/\texttt{\symbol{126}}Frank.Luebeck}}}\\
\end{titlepage}
\newpage\setcounter{page}{2}
{\small
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
{\copyright} 2006-2023 by Thomas Breuer and Frank L{\"u}beck
This package may be distributed under the terms and conditions of the GNU
Public License Version 3 or later, see \href{http://www.gnu.org/licenses} {\texttt{http://www.gnu.org/licenses}}. \mbox{}}\\[1cm]
\newpage
\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}
\tableofcontents
\newpage
\chapter{\textcolor{Chapter }{Introduction and Overview}}\label{ch:intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X794AAAFB7FFAA46C}{}
{
\section{\textcolor{Chapter }{Introduction}}\label{sec:intro}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
The motivation of the package \textsf{Browse} was to provide better functionality for displaying two-dimensional arrays of
data (e.g., character tables): moving through the data without loosing row and
column labels, searching for text, displaying extra information, hiding
information, allowing interactive user input, ...
We wanted to achieve this by using the capabilities of the terminal emulations
in which \textsf{GAP} is running, and not by some external graphical user interface. For this we
have chosen to use the widely available \texttt{C}-library \texttt{ncurses}, see \cite{NCursesWeb}. It contains functions to find out terminal capabilities, to change
properties of terminals, to place text, to handle several windows with
overlapping, ... To use these functions the terminal is switched to a \emph{visual mode} \index{visual mode} so that the display of the non-visual mode of your terminal in which \textsf{GAP} is running is not clobbered.
\textsf{Browse} has now three levels of functionality:
\begin{description}
\item[{A low level interface to \texttt{ncurses}}] This may be interesting for all kinds of applications which want to display
text with some markup including \index{colors as text attributes}colors, maybe in several windows, using the available capabilities of a
terminal.
\item[{A medium level interface to a generic function \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric})}] This is for displaying two-dimensional arrays of data, handles labels for rows
and columns, searching, sorting, binding keys to actions, ... If you want to
implement such applications for further kinds of data, first look at the
examples in Section \texttt{BrowseData.IsBrowseTable} (\ref{BrowseData.IsBrowseTable}), then check what can be copied from the examples in Chapter \ref{ch:appl}, and consult the descriptions in Chapters \ref{chap:browse-user} and \ref{chap:browse-prg}.
\item[{Applications of these interfaces}] We provide some applications of the \texttt{ncurses} interface and of the generic \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric}) function. These may be interesting for end users, and also as examples for
programmers of further applications. This includes (of course) a method for
browsing through character tables, functions for browsing through data
collections, several games,\index{game} and an interface for demos.
\end{description}
Users interested only in these applications should perhaps just try \texttt{NCurses.Demo()}. }
\section{\textcolor{Chapter }{Overview}}\label{sec:overview}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X8389AD927B74BA4A}{}
{
\subsection{\textcolor{Chapter }{The \texttt{ncurses} interface}}\label{ssec:ov_ncurses}
\logpage{[ 1, 2, 1 ]}
\hyperdef{L}{X87A6D24784C21E54}{}
{
Chapter \ref{ch:curses} describes \textsf{GAP}'s interface to the \texttt{ncurses} \texttt{C}-library. The imported \texttt{C}-functions are shortly explained, but for further details we refer to the
documentation of that library. There are also a few utility functions on \textsf{GAP} level, such as \texttt{NCurses.SetTerm} (\ref{NCurses.SetTerm}), which simplify the use of the library.
The concept of an \emph{attribute line}\index{attribute line}, see \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine}), helps to deal with text with markup for its display in a terminal window.
This chapter is for users who want to write their own applications of \texttt{ncurses}. }
\subsection{\textcolor{Chapter }{Applications of \texttt{ncurses}}}\label{ssec:ov_ncappl}
\logpage{[ 1, 2, 2 ]}
\hyperdef{L}{X80C054D881502061}{}
{
In Chapter \ref{ch:util} we describe some interactive applications of the \texttt{ncurses} interface. For example, there is \texttt{NCurses.Select} (\ref{NCurses.Select}) for asking a user to choose one or several of a given list of items. There is
also a demo function \texttt{NCurses.Demo} (\ref{NCurses.Demo}) which we use to demonstrate features of the \textsf{Browse} package, but it may be interesting for other kinds of demos as well. }
\subsection{\textcolor{Chapter }{The interface to browse two-dimensional arrays}}\label{ssec:ov_genbrowse}
\logpage{[ 1, 2, 3 ]}
\hyperdef{L}{X7CF47ACC83A95689}{}
{
Chapters \ref{chap:browse-user} and \ref{chap:browse-prg} describe the interface to a generic function \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric}) which can be used for an interactive display of two-dimensional arrays of
data. The first of these covers the basic functionality which may be
sufficient for many applications and the second gives more technical details.
With interactive display we mean that it is not only possible to scroll
through the data, but one can search for strings, sort by rows or columns,
select entries, bind arbitrary actions to keys and mouse events, ask for help,
and more. }
\subsection{\textcolor{Chapter }{Applications of the generic function \texttt{NCurses.BrowseGeneric}}}\label{ssec:ov_browseappl}
\logpage{[ 1, 2, 4 ]}
\hyperdef{L}{X7A0055DE7A2C5DC9}{}
{
In Chapter \ref{ch:appl} we describe several applications which are using the generic \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric}) interface introduced before. They are provided as prototype applications and
so we include some implementation remarks in their documentation.
Users who just want to use these applications hopefully do not need to read
this \textsf{Browse} manual, all applications are coming with built-in help windows.
There are different kinds of applications. First, there are methods for
browsing through character tables and tables of marks (our original motivation
for this package). Then there are applications for browsing through data
collections, e.g., the data available through the \textsf{AtlasRep} package, the \textsf{GAP} bibliography or the sections of the \textsf{GAP} manuals. Finally, there are several games like Sam Loyd's fifteen puzzle
(generalized), peg solitaire, and Sudoku (including functions to create new
puzzles and to solve puzzles). }
}
\section{\textcolor{Chapter }{User preferences provided by the \textsf{Browse} package}}\label{sec:pkg_userprefs}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X825F23FF825334B4}{}
{
See \texttt{SetUserPreference} (\textbf{Reference: SetUserPreference}) for \textsf{GAP}'s user preferences mechanism, and \texttt{BrowseUserPreferences} (\ref{BrowseUserPreferences}) for viewing and modifying user preferences.
\subsection{\textcolor{Chapter }{The user preference \texttt{EnableMouseEvents}}}\label{subsec:EnableMouseEvents}
\logpage{[ 1, 3, 1 ]}
\hyperdef{L}{X859EAEDA850D3B02}{}
{
This user preference defines whether mouse events are enabled by default in
visual mode (value \texttt{true}) or not (value \texttt{false}, this is the default). During the \textsf{GAP} session, the value can be changed using \texttt{NCurses.UseMouse} (\ref{NCurses.UseMouse}). Inside browse applications based on \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric}) or \texttt{NCurses.Select} (\ref{NCurses.Select}), the value can be toggled usually by hitting the \textsc{M} key. }
\subsection{\textcolor{Chapter }{The user preference \texttt{SelectHelpMatches}}}\label{subsec:SelectHelpMatches}
\logpage{[ 1, 3, 2 ]}
\hyperdef{L}{X7D242D4286EAB00A}{}
{
In the case that the \textsf{GAP} help system finds multiple matches, \texttt{true} (the default) means that the user can choose one entry from a list that is
shown via \texttt{NCurses.Select} (\ref{NCurses.Select}), and \texttt{false} means that the matches are just shown in a pager. }
\subsection{\textcolor{Chapter }{The user preference \texttt{SelectPackageName}}}\label{subsec:SelectPackageName}
\logpage{[ 1, 3, 3 ]}
\hyperdef{L}{X7BC3B5827A4B09C3}{}
{
In the case that \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) is called with a prefix of some package names, \texttt{true} (the default) means that the user can choose one matching entry, and \texttt{false} means that the matches are just printed. }
}
}
\chapter{\textcolor{Chapter }{Interface to the \texttt{ncurses} Library}}\label{ch:curses}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7E049B1185A56B30}{}
{
In this chapter we describe the \textsf{GAP} interface to the \textsf{GNU} \texttt{curses}/\texttt{ncurses} \texttt{C}-library. This library contains routines to manipulate the contents of
terminal windows. It allows one to write programs which should work on a wide
variety of terminal emulations with different sets of capabilities.
This technical chapter is intended for readers who want to program new
applications using the \texttt{ncurses} functionality. If you are only interested in the function \texttt{NCurses.BrowseGeneric} (\ref{NCurses.BrowseGeneric}) from this package or some of its applications you can skip this chapter.
Detailed documentation of the \texttt{ncurses} library is probably available in your operating system (try \texttt{man ncurses}) and from the web (see for example \cite{NCursesWeb}). Here, we only give short reminders about the functions provided in the \textsf{GAP} interface and explain how to use the \textsf{GAP} functions.
\section{\textcolor{Chapter }{The \texttt{ncurses} Library}}\label{sec:cursesC}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X85DE9B75837BA65B}{}
{
In this section we list the functions from the GNU \texttt{ncurses} library and its \texttt{panel} extension which are made available in \textsf{GAP} via the \textsf{Browse} package. See the following section \ref{sec:cursesGAP} for explanations how to use these functions from within \textsf{GAP}.
The basic objects to manipulate are called \emph{windows}, they correspond to rectangular regions of the terminal screen. Windows can
overlap but \texttt{ncurses} cannot handle this for the display. Therefore windows can be wrapped in \emph{panels}, they provide a display depth for windows and it is possible to move panels
to the top and bottom of the display or to hide a panel.
We will not import all the functions of the \texttt{ncurses} library to \textsf{GAP}. For example, there are many pairs of functions with the same name except for
a leading \texttt{w} (like \texttt{move} and \texttt{wmove} for moving the cursor in a window). Here, we only import the versions with \texttt{w}, which get a window as first argument. The functions without \texttt{w} are for the \texttt{ncurses} standard screen window \texttt{stdscr} which is available as window \texttt{0} in \textsf{GAP}. Similarly, there are functions with the same name except for an extra \texttt{n} (like \texttt{waddstr} and \texttt{waddnstr} for placing a string into a window). Here, we only import the safer functions
with \texttt{n} which get the number of characters to write as argument. (More convenient
functions are then implemented on the \textsf{GAP} level.)
\subsection{\textcolor{Chapter }{Setting the terminal}}\label{ssec:ncursesTermset}
\logpage{[ 2, 1, 1 ]}
\hyperdef{L}{X8499A3A384BF1F2D}{}
{
We first list flags for setting the basic behavior of a terminal. With \texttt{savetty}/\texttt{resetty} a setting can be stored and recovered.
\begin{description}
\item[{\index{savetty@\texttt{savetty}}\texttt{savetty()}}] This stores the current setting of the terminal in a buffer.
\item[{\index{resetty@\texttt{resetty}}\texttt{resetty()}}] This resets the terminal to what was stored in the last call to \texttt{savetty}.
\item[{\index{cbreak@\texttt{cbreak}} \index{nocbreak@\texttt{nocbreak}}\texttt{cbreak()/nocbreak()}}] In \texttt{cbreak} mode each input character from a terminal is directly forwarded to the
application (but see \texttt{keypad}). With \texttt{nocbreak} this only happens after a newline or return is typed.
\item[{\index{keypad@\texttt{keypad}}\texttt{keypad(win, bool)}}] If set to \texttt{true} some special input like arrow or function keys can be read as single
characters from the input (such keys actually generate certain sequences of
characters), see also \ref{ssec:ncursesInput}. (The \mbox{\texttt{\mdseries\slshape win}} argument is irrelevant.)
\item[{\index{echo@\texttt{echo}} \index{noecho@\texttt{noecho}}\texttt{echo()}/\texttt{noecho()}}] This determines if input characters are automatically echoed by the terminal
at the current cursor position.
\item[{\index{curs_set@\texttt{curs{\textunderscore}set}}\texttt{curs{\textunderscore}set(vis)}}] This determines the visibility of the cursor. The argument \mbox{\texttt{\mdseries\slshape vis}}=0 makes the cursor invisible. With \mbox{\texttt{\mdseries\slshape vis}}=1 it becomes visible; some terminals allow also higher levels of visibility.
\item[{\index{wtimeout@\texttt{wtimeout}}\texttt{wtimeout(win, delay)}}] Here \mbox{\texttt{\mdseries\slshape delay}} determines a timeout in milliseconds for reading characters from the input of
a window. Negative values mean infinity, that is a blocking read.
\item[{\index{nonl@\texttt{nonl}} \index{nl@\texttt{nl}}\texttt{nl()}/\texttt{nonl()}}] With \texttt{nl} a return on input is translated to a newline character and a newline on output
is interpreted as return and linefeed.
\item[{\index{intrflush@\texttt{intrflush}}\texttt{intrflush(win, bool)}}] This flag determines if after an interrupt pending output to the terminal is
flushed. (The \mbox{\texttt{\mdseries\slshape win}} argument is irrelevant.)
\item[{\index{idlok@\texttt{idlok}}\texttt{idlok(win, bool)}}] With \texttt{true} the library tries to use a hardware line insertion functionality (in
particular for scrolling).
\item[{\index{scrollok@\texttt{scrollok}}\texttt{scrollok(win, bool)}}] If set to \texttt{true} moving the cursor down from the last line of a window causes scrolling of the
whole window, otherwise nothing happens.
\item[{\index{leaveok@\texttt{leaveok}}\texttt{leaveok(win, bool)}}] If set to \texttt{true} a refresh of the window leaves the cursor at its current location, otherwise
this is not guaranteed.
\item[{\index{clearok@\texttt{clearok}}\texttt{clearok(win, bool)}}] If set to \texttt{true} the next refresh of the window will clear the screen completely and redraw
everything.
\item[{\index{immedok@\texttt{immedok}}\texttt{immedok(win, bool)}}] If set to \texttt{true} all changes of the window will automatically also call a \texttt{wrefresh}.
\item[{\index{noraw@\texttt{noraw}} \index{raw@\texttt{raw}}\texttt{raw()}/\texttt{noraw()}}] Similar to \texttt{cbreak}, usually not needed (see the \texttt{ncurses} documentation for details).
\end{description}
}
\subsection{\textcolor{Chapter }{Manipulating windows}}\label{ssec:ncursesWin}
\logpage{[ 2, 1, 2 ]}
\hyperdef{L}{X800D5B6381F0356F}{}
{
In \texttt{ncurses} an arbitrary number of windows which correspond to rectangular regions (maybe
overlapping) of the screen can be handled. You should always delete windows
which are no longer needed. To get a proper display of overlapping windows
(which may occur by recursively called functions using this library) we
suggest that you always wrap windows in panels, see \ref{ssec:ncursesPan}.
For functions which involve coordinates recall that the upper left corner of
the screen or internally of any window has the coordinates (0,0).
\begin{description}
\item[{\index{newwin@\texttt{newwin}}\texttt{newwin(nlines, ncols, y, x)}}] This creates a new window whose upper left corner has the coordinates (\mbox{\texttt{\mdseries\slshape y}},\mbox{\texttt{\mdseries\slshape x}}) on the screen and has \mbox{\texttt{\mdseries\slshape nlines}} lines and \mbox{\texttt{\mdseries\slshape ncols}} columns, if this is possible. The arguments \mbox{\texttt{\mdseries\slshape nlines}} and \mbox{\texttt{\mdseries\slshape ncols}} can be zero, then their maximal possible values are assumed.
\item[{\index{delwin@\texttt{delwin}}\texttt{delwin(win)}}] Deletes a window.
\item[{\index{mvwin@\texttt{mvwin}}\texttt{mvwin(win, y, x)}}] Moves the upper left corner of the window to the given coordinates, if the
window still fits on the screen. With panels don't use this function, but use \texttt{move{\textunderscore}panel} mentioned below.
\item[{\index{wrefresh@\texttt{wrefresh}}\texttt{wrefresh(win)}}] Writing to a window only changes some internal buffers, this function copies
the window content to the actual display screen. You don't need this function
if you wrap your windows in panels, use \texttt{update{\textunderscore}panels} and \texttt{doupdate} instead.
\item[{\index{doupdate@\texttt{doupdate}}\texttt{doupdate()}}] Use this function to update the content of your display screen to the current
content of all windows. If your terminal is not yet in visual mode this
function changes to visual mode.
\item[{\index{endwin@\texttt{endwin}}\texttt{endwin()}}] Use this function to leave the visual mode of your terminal. (Remark: If you
use this function while not in visual mode the cursor will be moved to the
line where the visual mode was started last time. To avoid this use \texttt{isendwin} first.)
\item[{\index{isendwin@\texttt{isendwin}}\texttt{isendwin()}}] Returns \texttt{true} if called while not in visual mode and \texttt{false} otherwise
\item[{\index{getbegyx@\texttt{getbegyx}}\texttt{getbegyx(win)}}] Get the coordinates of the upper left corner of a window on the screen.
\item[{\index{getmaxyx@\texttt{getmaxyx}}\texttt{getmaxyx(win)}}] Get the number of lines and columns of a window.
\end{description}
}
\subsection{\textcolor{Chapter }{Manipulating panels}}\label{ssec:ncursesPan}
\logpage{[ 2, 1, 3 ]}
\hyperdef{L}{X7D541BDE7BB8BED5}{}
{
Wrap windows in panels to get a proper handling of overlapping windows on the
display. Don't forget to delete a panel before deleting the corresponding
window.
\begin{description}
\item[{\index{new_panel@\texttt{new{\textunderscore}panel}}\texttt{new{\textunderscore}panel(win)}}] Create a panel for a window.
\item[{\index{del_panel@\texttt{del{\textunderscore}panel}}\texttt{del{\textunderscore}panel(pan)}}] Delete a panel.
\item[{\index{update_panels@\texttt{update{\textunderscore}panels}}\texttt{update{\textunderscore}panels()}}] Use this function to copy changes of windows and panels to a screen buffer.
Then call \texttt{doupdate()} to update the display screen.
\item[{\index{move_panel@\texttt{move{\textunderscore}panel}}\texttt{move{\textunderscore}panel(pan, y, x)}}] Move top left corner of a panel wrapped window to coordinates (\mbox{\texttt{\mdseries\slshape y}},\mbox{\texttt{\mdseries\slshape x}}) if possible.
\item[{\index{show_panel@\texttt{show{\textunderscore}panel}} \index{hide_panel@\texttt{hide{\textunderscore}panel}}\texttt{hide{\textunderscore}panel(pan)}/\texttt{show{\textunderscore}panel(pan)}}] Hide or show, respectively, the content of a panel on the display screen.
\item[{\index{bottom_panel@\texttt{bottom{\textunderscore}panel}} \index{top_panel(@\texttt{top{\textunderscore}panel}}\texttt{top{\textunderscore}panel(pan)}/\texttt{bottom{\textunderscore}panel(pan)}}] Move a panel to the top or bottom of all panels, respectively.
\item[{\index{panel_above@\texttt{panel{\textunderscore}above}} \index{panel_below@\texttt{panel{\textunderscore}below}}\texttt{panel{\textunderscore}below(pan)}/\texttt{panel{\textunderscore}above(pan)}}] Return the panel directly below or above the given one, respectively. With
argument \texttt{0} the top or bottom panel are returned, respectively. If argument is the bottom
or top panel, respectively, then \texttt{false} is returned.
\end{description}
}
\subsection{\textcolor{Chapter }{Getting keyboard input}}\label{ssec:ncursesInput}
\logpage{[ 2, 1, 4 ]}
\hyperdef{L}{X7F23F5F48650A78B}{}
{
If you want to read input from the user first adjust the terminal settings of \texttt{cbreak}, \texttt{keypad}, \texttt{echo}, \texttt{wtimeout} and \texttt{curs{\textunderscore}set} to your needs, see \ref{ssec:ncursesTermset}. The basic functions are as follows.
\begin{description}
\item[{\index{wgetch@\texttt{wgetch}}\texttt{wgetch(win)}}] Reads one character from user input (returned as integer). If \texttt{wtimeout} was set with a positive \mbox{\texttt{\mdseries\slshape delay}} then the function returns \texttt{false} if there was no input for \mbox{\texttt{\mdseries\slshape delay}} milliseconds. Note that in \texttt{nocbreak} mode typed characters reach the application only after typing a return. If the \texttt{keypad} flag is set to \texttt{true} some special keys can be read like single characters; the keys are explained
below. (Note that there is only one input queue for all windows.)
\item[{\index{ungetch@\texttt{ungetch}}\texttt{ungetch(char)}}] Puts back the character \mbox{\texttt{\mdseries\slshape char}} on the input queue.
\end{description}
\index{NCurses.keys@\texttt{NCurses.keys}} Some terminals allow one to read special keys like one character, we import
some of the symbolic names of such keys into \textsf{GAP}. You can check for such characters by comparing with the components of the
record \texttt{NCurses.keys}, these are
\begin{description}
\item[{\texttt{UP}/\texttt{DOWN}/\texttt{LEFT}/\texttt{RIGHT}}] the arrow keys
\item[{\texttt{PPAGE}/\texttt{NPAGE}}] the page up and page down keys
\item[{\texttt{HOME}/\texttt{END}}] the home and end keys
\item[{\texttt{BACKSPACE}/\texttt{DC}}] the backspace and delete keys
\item[{\texttt{IC}}] the insert key
\item[{\texttt{ENTER}}] the enter key
\item[{\texttt{F1}/\texttt{F2}/../\texttt{F24}}] the function keys
\item[{\texttt{MOUSE}}] a pseudo key to detect mouse events
\item[{\texttt{A1}/\texttt{A3}/\texttt{B2}/\texttt{C1}/\texttt{C3}}] the keys around the arrow keys on a num pad
\end{description}
It can happen that on a specific keyboard there is no key for some of these.
Also, not all terminals can interpret all of these keys. You can check this
with the function
\begin{description}
\item[{\index{has_key@\texttt{has{\textunderscore}key}}\texttt{has{\textunderscore}key(key)}}] Checks if the special key \mbox{\texttt{\mdseries\slshape key}} is recognized by the terminal.
\end{description}
}
\subsection{\textcolor{Chapter }{Writing to windows}}\label{ssec:ncursesWrite}
\logpage{[ 2, 1, 5 ]}
\hyperdef{L}{X7FD4E558816B3146}{}
{
The display of text in \texttt{ncurses} windows has two aspects. The first is to get actual characters on the screen.
The second is to specify attributes which influence the display, for example
normal or bold fonts or colors. This subsection is for the first aspect.
Possible attributes are explained below in \ref{ssec:ncursesAttrs}.
\begin{description}
\item[{\index{wmove@\texttt{wmove}}\texttt{wmove(win, y, x)}}] Moves the cursor to position (\mbox{\texttt{\mdseries\slshape y}},\mbox{\texttt{\mdseries\slshape x}}), recall that the coordinates are zero based, (0,0) being the top left
corner.
\item[{\index{waddnstr@\texttt{waddnstr}}\texttt{waddnstr(win, str, len)}}] Writes the string \mbox{\texttt{\mdseries\slshape str}} to the window starting from the current cursor position. Writes at most \mbox{\texttt{\mdseries\slshape len}} characters. At end of line the cursor moves to the beginning of next line. The
behavior at the end of the window depends on the setting of \texttt{scrollok}, see \ref{ssec:ncursesTermset}.
\item[{\index{waddch@\texttt{waddch}}\texttt{waddch(win, char)}}] Writes a character to the window at the current cursor position and moves the
cursor on. The character \mbox{\texttt{\mdseries\slshape char}} is given as integer and can include attribute information.
\item[{\index{wborder@\texttt{wborder}}\texttt{wborder(win, charlist)}}] Draws a border around the window. If \mbox{\texttt{\mdseries\slshape charlist}} is a plain list of eight \textsf{GAP} characters these are taken for left/right/top/bottom sides and
top-left/top-right/bottom-left/bottom-right corners. Otherwise default
characters are used. (See \texttt{NCurses.WBorder} (\ref{NCurses.WBorder}) for a more user friendly interface.)
\item[{\index{wvline@\texttt{wvline}}\texttt{wvline(win, char, len)}}] Writes a vertical line of length \mbox{\texttt{\mdseries\slshape len}} (or as long as fitting into the window) starting from the current cursor
position to the bottom, using the character \mbox{\texttt{\mdseries\slshape char}}. If \mbox{\texttt{\mdseries\slshape char}}=\texttt{0} the default character is used.
\item[{\index{whline@\texttt{whline}}\texttt{whline(win, char, len)}}] Same as \texttt{wvline} but for horizontal lines starting from the cursor position to the right.
\item[{\index{werase@\texttt{werase}}\texttt{werase(win)}}] Deletes all characters in the window.
\item[{\index{wclear@\texttt{wclear}}\texttt{wclear(win)}}] Like \texttt{werase}, but also calls \texttt{clearok}.
\item[{\index{wclrtobot@\texttt{wclrtobot}}\texttt{wclrtobot(win)}}] Deletes all characters from cursor position to the right and bottom.
\item[{\index{wclrtoeol@\texttt{wclrtoeol}}\texttt{wclrtoeol(win)}}] Deletes all characters from cursor position to end of line.
\item[{\index{winch@\texttt{winch}}\texttt{winch(win)}}] Returns the character at current cursor position, as integer and including
color and attribute information.
\item[{\index{getyx@\texttt{getyx}}\texttt{getyx(win)}}] Returns the current cursor position.
\item[{\index{waddstr@\texttt{waddstr}}\texttt{waddstr(win, str)}}] Delegates to \texttt{waddnstr(win, str, Length(str))}.
\end{description}
}
\subsection{\textcolor{Chapter }{Line drawing characters}}\label{ssec:ncursesLines}
\logpage{[ 2, 1, 6 ]}
\hyperdef{L}{X8091936586CCD248}{}
{
\index{NCurses.lineDraw@\texttt{NCurses.lineDraw}} For drawing lines and grids in a terminal window you should use some "virtual"
characters which are available as components of the record \texttt{NCurses.lineDraw}. On some terminals these are nicely displayed as proper lines (on others they
are simulated by ASCII characters). These are:
\begin{description}
\item[{\texttt{BLOCK}}] solid block
\item[{\texttt{BOARD}}] board of squares
\item[{\texttt{BTEE/LTEE/RTEE/TTEE}}] bottom/left/right/top tee
\item[{\texttt{BULLET}}] bullet
\item[{\texttt{CKBOARD}}] checker board
\item[{\texttt{DARROW/LARROW/RARROW/UARROW}}] down/left/right/up arrow
\item[{\texttt{DEGREE}}] degree symbol
\item[{\texttt{DIAMOND}}] diamond
\item[{\texttt{GEQUAL}}] greater than or equal
\item[{\texttt{HLINE/VLINE}}] horizontal/vertical line
\item[{\texttt{LANTERN}}] lantern symbol
\item[{\texttt{LEQUAL}}] less than or equal
\item[{\texttt{LLCORNER/LRCORNER/ULCORNER/URCORNER}}] lower left/lower right/upper left/upper right corner
\item[{\texttt{NEQUAL}}] not equal
\item[{\texttt{PI}}] letter pi
\item[{\texttt{PLMINUS}}] plus-minus
\item[{\texttt{PLUS}}] crossing lines like a plus
\item[{\texttt{S1/S3/S7/S9}}] scan line 1/3/7/9
\item[{\texttt{STERLING}}] pound sterling
\end{description}
}
\subsection{\textcolor{Chapter }{Text attributes and colors}}\label{ssec:ncursesAttrs}
\logpage{[ 2, 1, 7 ]}
\hyperdef{L}{X793D897483674294}{}
{
In addition to the actual characters to be written to the screen the way they
are displayed can be changed by additional \emph{attributes}. \index{attributes of text} (There should be no danger to mix up this notion of attributes with the one
introduced in{\nobreakspace} (\textbf{Reference: Attributes}).) \index{NCurses.attrs@\texttt{NCurses.attrs}} The available attributes are stored in the record \texttt{NCurses.attrs}, they are
\begin{description}
\item[{\texttt{NORMAL}}] normal display with no extra attributes.
\item[{\texttt{STANDOUT}}] displays text in the best highlighting mode of the terminal.
\item[{\texttt{UNDERLINE}}] underlines the text.
\item[{\texttt{REVERSE}}] display in reverse video by exchanging the foreground and background color.
\item[{\texttt{BLINK}}] displays the text blinking.
\item[{\texttt{DIM}}] displays the text half bright.
\item[{\texttt{BOLD}}] displays the text in a bold font.
\end{description}
Note that not all of these work with all types of terminals, or some may cause
the same display. Furthermore, if \texttt{NCurses.attrs.has{\textunderscore}colors} is \texttt{true} there is a list \texttt{NCurses.attrs.ColorPairs} of attributes to set the foreground and background color. These should be
accessed indirectly with \texttt{NCurses.ColorAttr} (\ref{NCurses.ColorAttr}). Attributes can be combined by adding their values (internally, they are
represented by integers). They can also be added to the integer representing a
character for use with \texttt{waddch}.
The library functions for setting attributes are:
\begin{description}
\item[{\index{wattrset@\texttt{wattrset}}\texttt{wattrset(win, attr)}}] This sets the default (combined) attributes for a window which is added to all
characters written to it; using \texttt{NCurses.attrs.NORMAL} as attribute is a reset.
\item[{\index{wattroff@\texttt{wattroff}} \index{wattron@\texttt{wattron}}\texttt{wattron(win, attr)}/\texttt{wattroff(win, attr)}}] This sets or unsets one or some default attributes of the window without
changing the others.
\item[{\index{wattr_get@\texttt{wattr{\textunderscore}get}}\texttt{wattr{\textunderscore}get(win)}}] This returns the current default attribute and default color pair of a window.
\item[{\index{wbkgdset@\texttt{wbkgdset}}\texttt{wbkgdset(win, attr)}}] This is similar to \texttt{wattrset} but you can also add a character to \mbox{\texttt{\mdseries\slshape attr}} which is used as default instead of blanks.
\item[{\index{wbkgd@\texttt{wbkgd}}\texttt{wbkgd(win, attr)}}] This function changes the attributes for all characters in the window to \mbox{\texttt{\mdseries\slshape attr}}, also used for further characters written to that window.
\end{description}
}
\subsection{\textcolor{Chapter }{Low level \texttt{ncurses} mouse support}}\label{ssec:ncursesMouse}
\logpage{[ 2, 1, 8 ]}
\hyperdef{L}{X86675F5F791FEFEF}{}
{
Many \texttt{xterm} based terminals support mouse events. The recognition of mouse events by the \texttt{ncurses} input queue can be switched on and off. If switched on and a mouse event
occurs, then \texttt{NCurses.wgetch} gets \texttt{NCurses.keys.MOUSE} if the \texttt{keypad} flag is \texttt{true} (see \ref{ssec:ncursesInput}). If this is read one must call \texttt{NCurses.getmouse} which reads further characters from the input queue and interprets them as
details on the mouse event. In most cases the function \texttt{NCurses.GetMouseEvent} (\ref{NCurses.GetMouseEvent}) can be used in applications (it calls \texttt{NCurses.getmouse}). The following low level functions are available as components of the record \texttt{NCurses}.
The names of mouse events which may be possible are stored in the list \texttt{NCurses.mouseEvents}, which starts \texttt{[} \texttt{"BUTTON1{\textunderscore}PRESSED",} \texttt{"BUTTON1{\textunderscore}RELEASED",} \texttt{"BUTTON1{\textunderscore}CLICKED",} \texttt{"BUTTON1{\textunderscore}DOUBLE{\textunderscore}CLICKED",} \texttt{"BUTTON1{\textunderscore}TRIPLE{\textunderscore}CLICKED",} \texttt{...} and contains the same for buttons number 2 to 5 and a few other events.
\begin{description}
\item[{\index{mousemask@\texttt{mousemask}} \texttt{mousemask(intlist)}}] The argument \mbox{\texttt{\mdseries\slshape intlist}} is a list of integers specifying mouse events. An entry \texttt{i} refers to the event described in \texttt{NCurses.mouseEvents[i+1]}. It returns a record with components \texttt{.new} (for the current setting) and \texttt{.old} (for the previous setting) which are again lists of integers with the same
meaning. Note that \texttt{.new} may be different from \mbox{\texttt{\mdseries\slshape intlist}}, it is always the empty list if the terminal does not support mouse events.
In applications use \texttt{NCurses.UseMouse} (\ref{NCurses.UseMouse}) instead of this low level function.
\item[{\index{getmouse@\texttt{getmouse}} \texttt{getmouse()}}] This function must be called after a key \texttt{NCurses.keys.MOUSE} was read. It returns a list with three entries \texttt{[y, x, intlist]} where \texttt{y} and \texttt{x} are the coordinates of the character cell where the mouse event occured and \texttt{intlist} describes the event, it should have length one and refers to a position in \texttt{NCurses.mouseEvents}.
\item[{\index{wenclose@\texttt{wenclose}} \texttt{wenclose(win, y, x)}}] This functions returns \texttt{true} if the screen position \mbox{\texttt{\mdseries\slshape y}}, \mbox{\texttt{\mdseries\slshape x}} is within window \mbox{\texttt{\mdseries\slshape win}} and \texttt{false} otherwise.
\item[{\index{mouseinterval@\texttt{mouseinterval}} \texttt{mouseinterval(t)}}] Sets the time to recognize a press and release of a mouse button as a click to \mbox{\texttt{\mdseries\slshape t}} milliseconds. (Note that this may have no effect because a window manager may
catch this.)
\end{description}
}
\subsection{\textcolor{Chapter }{Miscellaneous function}}\label{ssec:ncursesMisc}
\logpage{[ 2, 1, 9 ]}
\hyperdef{L}{X83897BF984211EFD}{}
{
\index{mnap@\texttt{mnap}} \index{IsStdinATty@\texttt{IsStdinATty}} \index{IsStdoutATty@\texttt{IsStdoutATty}} We also provide the \texttt{ncurses} function \texttt{mnap(msec)} which is a sleep for \mbox{\texttt{\mdseries\slshape msec}} milliseconds.
Furthermore, there a two utilities which can be useful for scripts and
testing, namely a check if standard input or standard output are connected to
terminals. These can be called as \texttt{NCurses.IsStdinATty()} or \texttt{NCurses.IsStdoutATty()}, respectively. }
}
\section{\textcolor{Chapter }{The \texttt{ncurses} \textsf{GAP} functions}}\label{sec:cursesGAP}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X864A5C1C7F181B4B}{}
{
The functions of the \texttt{ncurses} library are used within \textsf{GAP} very similarly to their \texttt{C} equivalents. The functions are available as components of a record \texttt{NCurses} with the name of the \texttt{C} function (e.g., \texttt{NCurses.newwin}).
In \textsf{GAP} the \texttt{ncurses} windows are accessed via integers (as returned by \texttt{NCurses.newwin}). The standard screen \texttt{stdscr} from the \texttt{ncurses} library is available as window number \texttt{0}. But this should not be used; to allow recursive applications of \texttt{ncurses} always create a new window, wrap it in a panel and delete both when they are
no longer needed.
Each window can be wrapped in one panel which is accessed by the same integer.
(Window \texttt{0} cannot be used with a panel.)
Coordinates in windows are the same zero based integers as in the
corresponding \texttt{C} functions. The interface of functions which \emph{return} coordinates is slightly different from the \texttt{C} version; they just return lists of integers and you just give the window as
argument, e.g., \texttt{NCurses.getmaxyx(win)} returns a list \texttt{[nrows, ncols]} of two integers.
Characters to be written to a window can be given either as \textsf{GAP} characters like \texttt{'a'} or as integers like \texttt{INT{\textunderscore}CHAR('a') = 97}. If you use the integer version you can also add attributes including color
settings to it for use with \texttt{NCurses.waddch}.
When writing an application decide about an appropriate terminal setting for
your visual mode windows, see \ref{ssec:ncursesTermset} and the utility function \texttt{NCurses.SetTerm} (\ref{NCurses.SetTerm}) below. Use \texttt{NCurses.savetty()} and \texttt{NCurses.resetty()} to save and restore the previous setting.
We also provide some higher level functionality for displaying marked up text,
see \texttt{NCurses.PutLine} (\ref{NCurses.PutLine}) and \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine}).
We now describe some utility functions for putting text on a terminal window.
\subsection{\textcolor{Chapter }{NCurses.ColorAttr}}
\logpage{[ 2, 2, 1 ]}\nobreak
\hyperdef{L}{X83ADB4E37C105B8C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.ColorAttr({\mdseries\slshape fgcolor, bgcolor})\index{NCurses.ColorAttr@\texttt{NCurses.ColorAttr}}
\label{NCurses.ColorAttr}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an attribute for setting the foreground and background color to be used on a
terminal window (it is a \textsf{GAP} integer).
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.attrs.has{\textunderscore}colors\index{NCurses.attrs.has{\textunderscore}colors@\texttt{NCurses.attrs.has{\textunderscore}colors}}
\label{NCurses.attrs.hasuScorecolors}
}\hfill{\scriptsize (global variable)}}\\
The return value can be used like any other attribute as described in \ref{ssec:ncursesAttrs}. The arguments \mbox{\texttt{\mdseries\slshape fgcolor}} and \mbox{\texttt{\mdseries\slshape bgcolor}} can be given as strings, allowed are those in \texttt{[ "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white" ]}. These are the default foreground colors 0 to 7 on ANSI terminals.
Alternatively, the numbers 0 to 7 can be used directly as arguments.
Note that terminals can be configured in a way such that these named colors
are not the colors which are actually displayed.
The variable \texttt{NCurses.attrs.has{\textunderscore}colors} (\ref{NCurses.attrs.hasuScorecolors}) \index{colors, availability} is set to \texttt{true} or \texttt{false} if the terminal supports colors or not, respectively. If a terminal does not
support colors then \texttt{NCurses.ColorAttr} always returns \texttt{NCurses.attrs.NORMAL}.
For an attribute setting the foreground color with the default background
color of the terminal use \texttt{-1} as \mbox{\texttt{\mdseries\slshape bgcolor}} or the same as \mbox{\texttt{\mdseries\slshape fgcolor}}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@win := NCurses.newwin(0,0,0,0);; pan := NCurses.new_panel(win);;|
!gapprompt@gap>| !gapinput@defc := NCurses.defaultColors;;|
!gapprompt@gap>| !gapinput@NCurses.wmove(win, 0, 0);;|
!gapprompt@gap>| !gapinput@for a in defc do for b in defc do|
!gapprompt@>| !gapinput@ NCurses.wattrset(win, NCurses.ColorAttr(a, b));|
!gapprompt@>| !gapinput@ NCurses.waddstr(win, Concatenation(a,"/",b,"\t"));|
!gapprompt@>| !gapinput@ od; od;|
!gapprompt@gap>| !gapinput@if NCurses.IsStdoutATty() then|
!gapprompt@>| !gapinput@ NCurses.update_panels();; NCurses.doupdate();;|
!gapprompt@>| !gapinput@ NCurses.napms(5000);; # show for 5 seconds|
!gapprompt@>| !gapinput@ NCurses.endwin();; NCurses.del_panel(pan);; NCurses.delwin(win);;|
!gapprompt@>| !gapinput@ fi;|
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NCurses.SetTerm}}
\logpage{[ 2, 2, 2 ]}\nobreak
\hyperdef{L}{X879D81B37A0A4E8F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.SetTerm({\mdseries\slshape [record]})\index{NCurses.SetTerm@\texttt{NCurses.SetTerm}}
\label{NCurses.SetTerm}
}\hfill{\scriptsize (function)}}\\
This function provides a unified interface to the various terminal setting
functions of \texttt{ncurses} listed in \ref{ssec:ncursesTermset}. The optional argument is a record with components which are assigned to \texttt{true} or \texttt{false}. Recognised components are: \texttt{cbreak}, \texttt{echo}, \texttt{nl}, \texttt{intrflush}, \texttt{leaveok}, \texttt{scrollok}, \texttt{keypad}, \texttt{raw} (with the obvious meaning if set to \texttt{true} or \texttt{false}, respectively).
The default, if no argument is given, is \texttt{rec(cbreak := true, echo := false, nl := false, intrflush := false, leaveok :=
true, scrollok := false, keypad := true)}. (This is a useful setting for many applications.) If there is an argument \mbox{\texttt{\mdseries\slshape record}}, then the given components overwrite the corresponding defaults. }
\subsection{\textcolor{Chapter }{NCurses.IsAttributeLine}}
\logpage{[ 2, 2, 3 ]}\nobreak
\hyperdef{L}{X81D1FC927C455AEB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.IsAttributeLine({\mdseries\slshape obj})\index{NCurses.IsAttributeLine@\texttt{NCurses.IsAttributeLine}}
\label{NCurses.IsAttributeLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if the argument describes a string with attributes.
An \emph{attribute line} describes a string with attributes. It is represented by either a string or a
dense list of strings, integers, and Booleans immediately following integers,
where at least one list entry must \emph{not} be a string. (The reason is that we want to be able to distinguish between an
attribute line and a list of such lines, and that the case of plain strings is
perhaps the most usual one, so we do not want to force wrapping each string in
a list.) The integers denote attribute values such as color or font
information, the Booleans denote that the attribute given by the preceding
integer is set or reset.
If an integer is not followed by a Boolean then it is used as the attribute
for the following characters, that is it overwrites all previously set
attributes. Note that in some applications the variant with explicit Boolean
values is preferable, because such a line can nicely be highlighted just by
prepending a \texttt{NCurses.attrs.STANDOUT} attribute.
For an overview of attributes, see{\nobreakspace}\ref{ssec:ncursesAttrs}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@NCurses.IsAttributeLine( "abc" );|
true
!gapprompt@gap>| !gapinput@NCurses.IsAttributeLine( [ "abc", "def" ] );|
false
!gapprompt@gap>| !gapinput@NCurses.IsAttributeLine( [ NCurses.attrs.UNDERLINE, true, "abc" ] );|
true
!gapprompt@gap>| !gapinput@NCurses.IsAttributeLine( "" ); NCurses.IsAttributeLine( [] );|
true
false
\end{Verbatim}
The \emph{empty string} is an attribute line whereas the \emph{empty list} (which is not in \texttt{IsStringRep} (\textbf{Reference: IsStringRep})) is \emph{not} an attribute line. }
\subsection{\textcolor{Chapter }{NCurses.ConcatenationAttributeLines}}
\logpage{[ 2, 2, 4 ]}\nobreak
\hyperdef{L}{X8372F0C57816A29E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.ConcatenationAttributeLines({\mdseries\slshape lines[, keep]})\index{NCurses.ConcatenationAttributeLines@\texttt{NCurses.ConcatenationAttributeLines}}
\label{NCurses.ConcatenationAttributeLines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an attribute line.
For a list \mbox{\texttt{\mdseries\slshape lines}} of attribute lines (see \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine})), \texttt{NCurses.ConcatenationAttributeLines} returns the attribute line obtained by concatenating the attribute lines in \mbox{\texttt{\mdseries\slshape lines}}.
If the optional argument \mbox{\texttt{\mdseries\slshape keep}} is \texttt{true} then attributes set in an entry of \mbox{\texttt{\mdseries\slshape lines}} are valid also for the following entries of \mbox{\texttt{\mdseries\slshape lines}}. Otherwise (in particular if there is no second argument) the attributes are
reset to \texttt{NCurses.attrs.NORMAL} between the entries of \mbox{\texttt{\mdseries\slshape lines}}.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@plain_str:= "hello";;|
!gapprompt@gap>| !gapinput@with_attr:= [ NCurses.attrs.BOLD, "bold" ];;|
!gapprompt@gap>| !gapinput@NCurses.ConcatenationAttributeLines( [ plain_str, plain_str ] );|
"hellohello"
!gapprompt@gap>| !gapinput@NCurses.ConcatenationAttributeLines( [ plain_str, with_attr ] );|
[ "hello", 2097152, "bold" ]
!gapprompt@gap>| !gapinput@NCurses.ConcatenationAttributeLines( [ with_attr, plain_str ] );|
[ 2097152, "bold", 0, "hello" ]
!gapprompt@gap>| !gapinput@NCurses.ConcatenationAttributeLines( [ with_attr, with_attr ] );|
[ 2097152, "bold", 0, 2097152, "bold" ]
!gapprompt@gap>| !gapinput@NCurses.ConcatenationAttributeLines( [ with_attr, with_attr ], true );|
[ 2097152, "bold", 2097152, "bold" ]
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NCurses.RepeatedAttributeLine}}
\logpage{[ 2, 2, 5 ]}\nobreak
\hyperdef{L}{X7D2EB0BF82C4F25C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.RepeatedAttributeLine({\mdseries\slshape line, width})\index{NCurses.RepeatedAttributeLine@\texttt{NCurses.RepeatedAttributeLine}}
\label{NCurses.RepeatedAttributeLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
an attribute line.
For an attribute line \mbox{\texttt{\mdseries\slshape line}} (see \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine})) and a positive integer \mbox{\texttt{\mdseries\slshape width}}, \texttt{NCurses.RepeatedAttributeLine} returns an attribute line with \mbox{\texttt{\mdseries\slshape width}} displayed characters (see{\nobreakspace}\texttt{NCurses.WidthAttributeLine} (\ref{NCurses.WidthAttributeLine})) that is obtained by concatenating sufficiently many copies of \mbox{\texttt{\mdseries\slshape line}} and cutting off a tail if applicable.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@NCurses.RepeatedAttributeLine( "12345", 23 );|
"12345123451234512345123"
!gapprompt@gap>| !gapinput@NCurses.RepeatedAttributeLine( [ NCurses.attrs.BOLD, "12345" ], 13 );|
[ 2097152, "12345", 0, 2097152, "12345", 0, 2097152, "123" ]
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NCurses.PutLine}}
\logpage{[ 2, 2, 6 ]}\nobreak
\hyperdef{L}{X83FFD5047ADE716E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.PutLine({\mdseries\slshape win, y, x, lines[, skip]})\index{NCurses.PutLine@\texttt{NCurses.PutLine}}
\label{NCurses.PutLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\mdseries\slshape lines}} were written, otherwise \texttt{false}.
The argument \mbox{\texttt{\mdseries\slshape lines}} can be a list of attribute lines (see \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine})) or a single attribute line. This function writes the attribute lines to
window \mbox{\texttt{\mdseries\slshape win}} at and below of position \mbox{\texttt{\mdseries\slshape y}}, \mbox{\texttt{\mdseries\slshape x}}.
If the argument \mbox{\texttt{\mdseries\slshape skip}} is given, it must be a nonnegative integer. In that case the first \mbox{\texttt{\mdseries\slshape skip}} characters of each given line are not written to the window (but the
attributes are). }
\subsection{\textcolor{Chapter }{NCurses.WidthAttributeLine}}
\logpage{[ 2, 2, 7 ]}\nobreak
\hyperdef{L}{X82C53ACD805EE0C3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.WidthAttributeLine({\mdseries\slshape line})\index{NCurses.WidthAttributeLine@\texttt{NCurses.WidthAttributeLine}}
\label{NCurses.WidthAttributeLine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
number of displayed characters in an attribute line.
For an attribute line \mbox{\texttt{\mdseries\slshape line}} (see \texttt{NCurses.IsAttributeLine} (\ref{NCurses.IsAttributeLine})), the function returns the number of displayed characters of \mbox{\texttt{\mdseries\slshape line}}. \index{displayed characters}
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@NCurses.WidthAttributeLine( "abcde" );|
5
!gapprompt@gap>| !gapinput@NCurses.WidthAttributeLine( [ NCurses.attrs.BOLD, "abc",|
!gapprompt@>| !gapinput@ NCurses.attrs.NORMAL, "de" ] );|
5
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NCurses.Grid}}
\logpage{[ 2, 2, 8 ]}\nobreak
\hyperdef{L}{X790715F683BF1E66}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.Grid({\mdseries\slshape win, trow, brow, lcol, rcol, rowinds, colinds})\index{NCurses.Grid@\texttt{NCurses.Grid}}
\label{NCurses.Grid}
}\hfill{\scriptsize (function)}}\\
This function draws a grid of horizontal and vertical lines on the window \mbox{\texttt{\mdseries\slshape win}}, using the line drawing characters explained in \ref{ssec:ncursesLines}. The given arguments specify the top and bottom row of the grid, its left and
right column, and lists of row and column numbers where lines should be drawn.
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
!gapprompt@gap>| !gapinput@fun := function() local win, pan;|
!gapprompt@>| !gapinput@ win := NCurses.newwin(0,0,0,0);|
!gapprompt@>| !gapinput@ pan := NCurses.new_panel(win);|
!gapprompt@>| !gapinput@ NCurses.Grid(win, 2, 11, 5, 22, [5, 6], [13, 14]);|
!gapprompt@>| !gapinput@ NCurses.PutLine(win, 12, 0, "Press to quit");|
!gapprompt@>| !gapinput@ NCurses.update_panels(); NCurses.doupdate();|
!gapprompt@>| !gapinput@ NCurses.wgetch(win);|
!gapprompt@>| !gapinput@ NCurses.endwin();|
!gapprompt@>| !gapinput@ NCurses.del_panel(pan); NCurses.delwin(win);|
!gapprompt@>| !gapinput@end;;|
!gapprompt@gap>| !gapinput@fun();|
\end{Verbatim}
}
\subsection{\textcolor{Chapter }{NCurses.WBorder}}
\logpage{[ 2, 2, 9 ]}\nobreak
\hyperdef{L}{X82B801587B37D571}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.WBorder({\mdseries\slshape win[, chars]})\index{NCurses.WBorder@\texttt{NCurses.WBorder}}
\label{NCurses.WBorder}
}\hfill{\scriptsize (function)}}\\
This is a convenient interface to the \texttt{ncurses} function \texttt{wborder}. It draws a border around the window \mbox{\texttt{\mdseries\slshape win}}. If no second argument is given the default line drawing characters are used,
see \ref{ssec:ncursesLines}. Otherwise, \mbox{\texttt{\mdseries\slshape chars}} must be a list of \textsf{GAP} characters or integers specifying characters, possibly with attributes. If \mbox{\texttt{\mdseries\slshape chars}} has length 8 the characters are used for the left/right/top/bottom sides and
top-left/top-right/bottom-left/bottom-right corners. If \mbox{\texttt{\mdseries\slshape chars}} contains 2 characters the first is used for the sides and the second for all
corners. If \mbox{\texttt{\mdseries\slshape chars}} contains just one character it is used for all sides including the corners. }
\subsection{\textcolor{Chapter }{Mouse support in \texttt{ncurses} applications}}\logpage{[ 2, 2, 10 ]}
\hyperdef{L}{X799C033A7AB582D7}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.UseMouse({\mdseries\slshape on})\index{NCurses.UseMouse@\texttt{NCurses.UseMouse}}
\label{NCurses.UseMouse}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a record
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NCurses.GetMouseEvent({\mdseries\slshape })\index{NCurses.GetMouseEvent@\texttt{NCurses.GetMouseEvent}}
\label{NCurses.GetMouseEvent}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
a list of records
\texttt{ncurses} allows on some terminals (\texttt{xterm} and related) to catch mouse events. In principle a subset of events can be
caught, see \texttt{mousemask} in \ref{ssec:ncursesMouse}. But this does not seem to work well with proper subsets of possible events
(probably due to intermediate processes X, window manager, terminal
application, ...). Therefore we suggest to catch either all or no mouse events
in applications.
This can be done with \texttt{NCurses.UseMouse} with argument \texttt{true} to switch on the recognition of mouse events and \texttt{false} to switch it off. The function returns a record with components \texttt{.new} and \texttt{.old} which are both set to the status \texttt{true} or \texttt{false} from after and before the call, respectively. (There does not seem to be a
possibility to get the current status without calling \texttt{NCurses.UseMouse}.) If you call the function with argument \texttt{true} and the \texttt{.new} component of the result is \t | |
