  
  [1X2 Interface to the [10Xncurses[1X Library[0X
  
  In  this  chapter  we  describe  the [5XGAP[0m interface to the [5XGNU[0m [10Xcurses[0m/[10Xncurses[0m
  [10XC[0m-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 [10Xncurses[0m functionality. If you are only interested in
  the  function [2XNCurses.BrowseGeneric[0m ([14X4.3-1[0m) from this package or some of its
  applications you can skip this chapter.
  
  Detailed  documentation of the [10Xncurses[0m library is probably available in your
  operating system (try [10Xman ncurses[0m) and from the web (see for example [NCu]).
  Here,  we  only give short reminders about the functions provided in the [5XGAP[0m
  interface and explain how to use the [5XGAP[0m functions.
  
  
  [1X2.1 The [10Xncurses[1X Library[0X
  
  In  this  section we list the functions from the GNU [10Xncurses[0m library and its
  [10Xpanel[0m  extension which are made available in [5XGAP[0m via the [5XBrowse[0m package. See
  the  following  section [14X2.2[0m for explanations how to use these functions from
  within [5XGAP[0m.
  
  The  basic  objects  to  manipulate  are  called [13Xwindows[0m, they correspond to
  rectangular  regions of the terminal screen. Windows can overlap but [10Xncurses[0m
  cannot  handle  this  for  the  display. Therefore windows can be wrapped in
  [13Xpanels[0m,  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 [10Xncurses[0m library to [5XGAP[0m. For
  example,  there  are many pairs of functions with the same name except for a
  leading  [10Xw[0m (like [10Xmove[0m and [10Xwmove[0m for moving the cursor in a window). Here, we
  only  import  the versions with [10Xw[0m, which get a window as first argument. The
  functions  without [10Xw[0m are for the [10Xncurses[0m standard screen window [10Xstdscr[0m which
  is  available  as  window  [10X0[0m in [5XGAP[0m. Similarly, there are functions with the
  same  name  except  for  an extra [10Xn[0m (like [10Xwaddstr[0m and [10Xwaddnstr[0m for placing a
  string into a window). Here, we only import the safer functions with [10Xn[0m which
  get  the  number  of  characters  to  write  as  argument.  (More convenient
  functions are then implemented on the [5XGAP[0m level.)
  
  
  [1X2.1-1 Setting the terminal[0X
  
  We  first  list  flags  for  setting  the basic behavior of a terminal. With
  [10Xsavetty[0m/[10Xresetty[0m a setting can be stored and recovered.
  
  [8X[10Xsavetty()[0m[8X[0m
        This stores the current setting of the terminal in a buffer.
  
  [8X[10Xresetty()[0m[8X[0m
        This  resets  the  terminal  to  what  was  stored in the last call to
        [10Xsavetty[0m.
  
  [8X
  [10Xcbreak()/nocbreak()[0m[8X[0m
        In  [10Xcbreak[0m  mode  each  input  character  from  a terminal is directly
        forwarded to the application (but see [10Xkeypad[0m). With [10Xnocbreak[0m this only
        happens after a newline or return is typed.
  
  [8X[10Xkeypad(win, bool)[0m[8X[0m
        If  set  to [9Xtrue[0m 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 [14X2.1-4[0m. (The [3Xwin[0m argument is
        irrelevant.)
  
  [8X
  [10Xecho()[0m[8X/[10Xnoecho()[0m[8X[0m
        This  determines  if  input characters are automatically echoed by the
        terminal at the current cursor position.
  
  [8X[10Xcurs_set(vis)[0m[8X[0m
        This determines the visibility of the cursor. The argument [3Xvis[0m=0 makes
        the  cursor  invisible.  With [3Xvis[0m=1 it becomes visible; some terminals
        allow also higher levels of visibility.
  
  [8X[10Xwtimeout(win, delay)[0m[8X[0m
        Here [3Xdelay[0m determines a timeout in milliseconds for reading characters
        from  the  input of a window. Negative values mean infinity, that is a
        blocking read.
  
  [8X
  [10Xnl()[0m[8X/[10Xnonl()[0m[8X[0m
        With  [10Xnl[0m  a return on input is translated to a newline character and a
        newline on output is interpreted as return and linefeed.
  
  [8X[10Xintrflush(win, bool)[0m[8X[0m
        This  flag  determines  if  after  an  interrupt pending output to the
        terminal is flushed. (The [3Xwin[0m argument is irrelevant.)
  
  [8X[10Xidlok(win, bool)[0m[8X[0m
        With  [9Xtrue[0m  the  library  tries  to  use  a  hardware  line  insertion
        functionality (in particular for scrolling).
  
  [8X[10Xscrollok(win, bool)[0m[8X[0m
        If  set  to [9Xtrue[0m moving the cursor down from the last line of a window
        causes scrolling of the whole window, otherwise nothing happens.
  
  [8X[10Xleaveok(win, bool)[0m[8X[0m
        If  set  to  [9Xtrue[0m  a  refresh  of  the window leaves the cursor at its
        current location, otherwise this is not guaranteed.
  
  [8X[10Xclearok(win, bool)[0m[8X[0m
        If  set  to  [9Xtrue[0m the next refresh of the window will clear the screen
        completely and redraw everything.
  
  [8X[10Ximmedok(win, bool)[0m[8X[0m
        If  set to [9Xtrue[0m all changes of the window will automatically also call
        a [10Xwrefresh[0m.
  
  [8X
  [10Xraw()[0m[8X/[10Xnoraw()[0m[8X[0m
        Similar  to  [10Xcbreak[0m, usually not needed (see the [10Xncurses[0m documentation
        for details).
  
  
  [1X2.1-2 Manipulating windows[0X
  
  In  [10Xncurses[0m  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 [14X2.1-3[0m.
  
  For functions which involve coordinates recall that the upper left corner of
  the screen or internally of any window has the coordinates (0,0).
  
  [8X[10Xnewwin(nlines, ncols, y, x)[0m[8X[0m
        This  creates a new window whose upper left corner has the coordinates
        ([3Xy[0m,[3Xx[0m) on the screen and has [3Xnlines[0m lines and [3Xncols[0m columns, if this is
        possible.  The  arguments  [3Xnlines[0m  and  [3Xncols[0m  can be zero, then their
        maximal possible values are assumed.
  
  [8X[10Xdelwin(win)[0m[8X[0m
        Deletes a window.
  
  [8X[10Xmvwin(win, y, x)[0m[8X[0m
        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 [10Xmove_panel[0m mentioned below.
  
  [8X[10Xwrefresh(win)[0m[8X[0m
        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 [10Xupdate_panels[0m
        and [10Xdoupdate[0m instead.
  
  [8X[10Xdoupdate()[0m[8X[0m
        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.
  
  [8X[10Xendwin()[0m[8X[0m
        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 [10Xisendwin[0m first.)
  
  [8X[10Xisendwin()[0m[8X[0m
        Returns [9Xtrue[0m if called while not in visual mode and [9Xfalse[0m otherwise
  
  [8X[10Xgetbegyx(win)[0m[8X[0m
        Get  the  coordinates  of  the  upper  left  corner of a window on the
        screen.
  
  [8X[10Xgetmaxyx(win)[0m[8X[0m
        Get the number of lines and columns of a window.
  
  
  [1X2.1-3 Manipulating panels[0X
  
  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.
  
  [8X[10Xnew_panel(win)[0m[8X[0m
        Create a panel for a window.
  
  [8X[10Xdel_panel(pan)[0m[8X[0m
        Delete a panel.
  
  [8X[10Xupdate_panels()[0m[8X[0m
        Use  this  function  to copy changes of windows and panels to a screen
        buffer. Then call [10Xdoupdate()[0m to update the display screen.
  
  [8X[10Xmove_panel(pan, y, x)[0m[8X[0m
        Move top left corner of a panel wrapped window to coordinates ([3Xy[0m,[3Xx[0m) if
        possible.
  
  [8X
  [10Xhide_panel(pan)[0m[8X/[10Xshow_panel(pan)[0m[8X[0m
        Hide  or  show,  respectively,  the  content of a panel on the display
        screen.
  
  [8X
  [10Xtop_panel(pan)[0m[8X/[10Xbottom_panel(pan)[0m[8X[0m
        Move a panel to the top or bottom of all panels, respectively.
  
  [8X
  [10Xpanel_below(pan)[0m[8X/[10Xpanel_above(pan)[0m[8X[0m
        Return  the panel directly below or above the given one, respectively.
        With argument [10X0[0m the top or bottom panel are returned, respectively. If
        argument  is  the  bottom  or  top  panel, respectively, then [9Xfalse[0m is
        returned.
  
  
  [1X2.1-4 Getting keyboard input[0X
  
  If  you  want to read input from the user first adjust the terminal settings
  of [10Xcbreak[0m, [10Xkeypad[0m, [10Xecho[0m, [10Xwtimeout[0m and [10Xcurs_set[0m to your needs, see [14X2.1-1[0m. The
  basic functions are as follows.
  
  [8X[10Xwgetch(win)[0m[8X[0m
        Reads one character from user input (returned as integer). If [10Xwtimeout[0m
        was set with a positive [3Xdelay[0m then the function returns [9Xfalse[0m if there
        was  no input for [3Xdelay[0m milliseconds. Note that in [10Xnocbreak[0m mode typed
        characters  reach  the  application only after typing a return. If the
        [10Xkeypad[0m  flag  is set to [9Xtrue[0m 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.)
  
  [8X[10Xungetch(char)[0m[8X[0m
        Puts back the character [3Xchar[0m on the input queue.
  
  Some  terminals allow one to read special keys like one character, we import
  some  of  the  symbolic  names of such keys into [5XGAP[0m. You can check for such
  characters  by  comparing  with  the  components of the record [10XNCurses.keys[0m,
  these are
  
  [8X[10XUP[0m[8X/[10XDOWN[0m[8X/[10XLEFT[0m[8X/[10XRIGHT[0m[8X[0m
        the arrow keys
  
  [8X[10XPPAGE[0m[8X/[10XNPAGE[0m[8X[0m
        the page up and page down keys
  
  [8X[10XHOME[0m[8X/[10XEND[0m[8X[0m
        the home and end keys
  
  [8X[10XBACKSPACE[0m[8X/[10XDC[0m[8X[0m
        the backspace and delete keys
  
  [8X[10XIC[0m[8X[0m
        the insert key
  
  [8X[10XENTER[0m[8X[0m
        the enter key
  
  [8X[10XF1[0m[8X/[10XF2[0m[8X/../[10XF24[0m[8X[0m
        the function keys
  
  [8X[10XMOUSE[0m[8X[0m
        a pseudo key to detect mouse events
  
  [8X[10XA1[0m[8X/[10XA3[0m[8X/[10XB2[0m[8X/[10XC1[0m[8X/[10XC3[0m[8X[0m
        the keys around the arrow keys on a num pad
  
  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
  
  [8X[10Xhas_key(key)[0m[8X[0m
        Checks if the special key [3Xkey[0m is recognized by the terminal.
  
  
  [1X2.1-5 Writing to windows[0X
  
  The  display of text in [10Xncurses[0m 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 [14X2.1-7[0m.
  
  [8X[10Xwmove(win, y, x)[0m[8X[0m
        Moves  the  cursor  to position ([3Xy[0m,[3Xx[0m), recall that the coordinates are
        zero based, (0,0) being the top left corner.
  
  [8X[10Xwaddnstr(win, str, len)[0m[8X[0m
        Writes  the  string [3Xstr[0m to the window starting from the current cursor
        position.  Writes  at  most  [3Xlen[0m 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 [10Xscrollok[0m, see [14X2.1-1[0m.
  
  [8X[10Xwaddch(win, char)[0m[8X[0m
        Writes  a  character  to the window at the current cursor position and
        moves  the  cursor  on. The character [3Xchar[0m is given as integer and can
        include attribute information.
  
  [8X[10Xwborder(win, charlist)[0m[8X[0m
        Draws a border around the window. If [3Xcharlist[0m is a plain list of eight
        [5XGAP[0m  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  [2XNCurses.WBorder[0m  ([14X2.2-9[0m) for a more user
        friendly interface.)
  
  [8X[10Xwvline(win, char, len)[0m[8X[0m
        Writes  a  vertical line of length [3Xlen[0m (or as long as fitting into the
        window) starting from the current cursor position to the bottom, using
        the character [3Xchar[0m. If [3Xchar[0m=[10X0[0m the default character is used.
  
  [8X[10Xwhline(win, char, len)[0m[8X[0m
        Same  as  [10Xwvline[0m  but  for  horizontal  lines starting from the cursor
        position to the right.
  
  [8X[10Xwerase(win)[0m[8X[0m
        Deletes all characters in the window.
  
  [8X[10Xwclear(win)[0m[8X[0m
        Like [10Xwerase[0m, but also calls [10Xclearok[0m.
  
  [8X[10Xwclrtobot(win)[0m[8X[0m
        Deletes all characters from cursor position to the right and bottom.
  
  [8X[10Xwclrtoeol(win)[0m[8X[0m
        Deletes all characters from cursor position to end of line.
  
  [8X[10Xwinch(win)[0m[8X[0m
        Returns  the  character  at  current  cursor  position, as integer and
        including color and attribute information.
  
  [8X[10Xgetyx(win)[0m[8X[0m
        Returns the current cursor position.
  
  [8X[10Xwaddstr(win, str)[0m[8X[0m
        Delegates to [10Xwaddnstr(win, str, Length(str))[0m.
  
  
  [1X2.1-6 Line drawing characters[0X
  
  For  drawing  lines  and  grids  in  a  terminal  window you should use some
  "virtual"  characters  which  are  available  as  components  of  the record
  [10XNCurses.lineDraw[0m.  On  some  terminals  these are nicely displayed as proper
  lines (on others they are simulated by ASCII characters). These are:
  
  [8X[10XBLOCK[0m[8X[0m
        solid block
  
  [8X[10XBOARD[0m[8X[0m
        board of squares
  
  [8X[10XBTEE/LTEE/RTEE/TTEE[0m[8X[0m
        bottom/left/right/top tee
  
  [8X[10XBULLET[0m[8X[0m
        bullet
  
  [8X[10XCKBOARD[0m[8X[0m
        checker board
  
  [8X[10XDARROW/LARROW/RARROW/UARROW[0m[8X[0m
        down/left/right/up arrow
  
  [8X[10XDEGREE[0m[8X[0m
        degree symbol
  
  [8X[10XDIAMOND[0m[8X[0m
        diamond
  
  [8X[10XGEQUAL[0m[8X[0m
        greater than or equal
  
  [8X[10XHLINE/VLINE[0m[8X[0m
        horizontal/vertical line
  
  [8X[10XLANTERN[0m[8X[0m
        lantern symbol
  
  [8X[10XLEQUAL[0m[8X[0m
        less than or equal
  
  [8X[10XLLCORNER/LRCORNER/ULCORNER/URCORNER[0m[8X[0m
        lower left/lower right/upper left/upper right corner
  
  [8X[10XNEQUAL[0m[8X[0m
        not equal
  
  [8X[10XPI[0m[8X[0m
        letter pi
  
  [8X[10XPLMINUS[0m[8X[0m
        plus-minus
  
  [8X[10XPLUS[0m[8X[0m
        crossing lines like a plus
  
  [8X[10XS1/S3/S7/S9[0m[8X[0m
        scan line 1/3/7/9
  
  [8X[10XSTERLING[0m[8X[0m
        pound sterling
  
  
  [1X2.1-7 Text attributes and colors[0X
  
  In  addition  to  the  actual characters to be written to the screen the way
  they are displayed can be changed by additional [13Xattributes[0m. (There should be
  no  danger  to  mix  up  this  notion  of attributes with the one introduced
  in [14X'Reference:  Attributes'[0m.)  The  available  attributes  are stored in the
  record [10XNCurses.attrs[0m, they are
  
  [8X[10XNORMAL[0m[8X[0m
        normal display with no extra attributes.
  
  [8X[10XSTANDOUT[0m[8X[0m
        displays text in the best highlighting mode of the terminal.
  
  [8X[10XUNDERLINE[0m[8X[0m
        underlines the text.
  
  [8X[10XREVERSE[0m[8X[0m
        display  in  reverse video by exchanging the foreground and background
        color.
  
  [8X[10XBLINK[0m[8X[0m
        displays the text blinking.
  
  [8X[10XDIM[0m[8X[0m
        displays the text half bright.
  
  [8X[10XBOLD[0m[8X[0m
        displays the text in a bold font.
  
  Note  that  not  all  of these work with all types of terminals, or some may
  cause  the  same  display.  Furthermore, if [10XNCurses.attrs.has_colors[0m is [9Xtrue[0m
  there is a list [10XNCurses.attrs.ColorPairs[0m of attributes to set the foreground
  and   background   color.   These   should   be   accessed  indirectly  with
  [2XNCurses.ColorAttr[0m ([14X2.2-1[0m). 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 [10Xwaddch[0m.
  
  The library functions for setting attributes are:
  
  [8X[10Xwattrset(win, attr)[0m[8X[0m
        This  sets  the  default  (combined)  attributes for a window which is
        added  to  all characters written to it; using [10XNCurses.attrs.NORMAL[0m as
        attribute is a reset.
  
  [8X
  [10Xwattron(win, attr)[0m[8X/[10Xwattroff(win, attr)[0m[8X[0m
        This  sets  or  unsets  one  or  some default attributes of the window
        without changing the others.
  
  [8X[10Xwattr_get(win)[0m[8X[0m
        This returns the current default attribute and default color pair of a
        window.
  
  [8X[10Xwbkgdset(win, attr)[0m[8X[0m
        This  is  similar to [10Xwattrset[0m but you can also add a character to [3Xattr[0m
        which is used as default instead of blanks.
  
  [8X[10Xwbkgd(win, attr)[0m[8X[0m
        This  function changes the attributes for all characters in the window
        to [3Xattr[0m, also used for further characters written to that window.
  
  
  [1X2.1-8 Low level [10Xncurses[1X mouse support[0X
  
  Many  [10Xxterm[0m  based  terminals support mouse events. The recognition of mouse
  events by the [10Xncurses[0m input queue can be switched on and off. If switched on
  and a mouse event occurs, then [10XNCurses.wgetch[0m gets [10XNCurses.keys.MOUSE[0m if the
  [10Xkeypad[0m   flag   is  [9Xtrue[0m  (see  [14X2.1-4[0m).  If  this  is  read  one  must  call
  [10XNCurses.getmouse[0m  which  reads  further  characters from the input queue and
  interprets  them  as  details on the mouse event. In most cases the function
  [2XNCurses.GetMouseEvent[0m  ([14X2.2-10[0m)  can  be  used  in  applications  (it  calls
  [10XNCurses.getmouse[0m).  The  following  low  level  functions  are  available as
  components of the record [10XNCurses[0m.
  
  The  names  of  mouse  events  which  may be possible are stored in the list
  [10XNCurses.mouseEvents[0m,  which  starts [10X[[0m [10X"BUTTON1_PRESSED",[0m [10X"BUTTON1_RELEASED",[0m
  [10X"BUTTON1_CLICKED",[0m  [10X"BUTTON1_DOUBLE_CLICKED",[0m  [10X"BUTTON1_TRIPLE_CLICKED",[0m [10X...[0m
  and contains the same for buttons number 2 to 5 and a few other events.
  
  [8X
  [10Xmousemask(intlist)[0m[8X[0m
        The argument [3Xintlist[0m is a list of integers specifying mouse events. An
        entry  [10Xi[0m refers to the event described in [10XNCurses.mouseEvents[i+1][0m. It
        returns  a  record  with components [10X.new[0m (for the current setting) and
        [10X.old[0m (for the previous setting) which are again lists of integers with
        the  same meaning. Note that [10X.new[0m may be different from [3Xintlist[0m, it is
        always  the  empty list if the terminal does not support mouse events.
        In  applications  use  [2XNCurses.UseMouse[0m  ([14X2.2-10[0m)  instead of this low
        level function.
  
  [8X
  [10Xgetmouse()[0m[8X[0m
        This  function must be called after a key [10XNCurses.keys.MOUSE[0m was read.
        It returns a list with three entries [10X[y, x, intlist][0m where [10Xy[0m and [10Xx[0m are
        the  coordinates  of  the character cell where the mouse event occured
        and  [10Xintlist[0m describes the event, it should have length one and refers
        to a position in [10XNCurses.mouseEvents[0m.
  
  [8X
  [10Xwenclose(win, y, x)[0m[8X[0m
        This  functions  returns  [9Xtrue[0m  if  the screen position [3Xy[0m, [3Xx[0m is within
        window [3Xwin[0m and [9Xfalse[0m otherwise.
  
  [8X
  [10Xmouseinterval(t)[0m[8X[0m
        Sets  the time to recognize a press and release of a mouse button as a
        click  to [3Xt[0m milliseconds. (Note that this may have no effect because a
        window manager may catch this.)
  
  
  [1X2.1-9 Miscellaneous function[0X
  
  We  also  provide  the [10Xncurses[0m function [10Xmnap(msec)[0m which is a sleep for [3Xmsec[0m
  milliseconds.
  
  
  [1X2.2 The [10Xncurses[1X [5XGAP[1X functions[0X
  
  The  functions  of the [10Xncurses[0m library are used within [5XGAP[0m very similarly to
  their  [10XC[0m  equivalents. The functions are available as components of a record
  [10XNCurses[0m with the name of the [10XC[0m function (e.g., [10XNCurses.newwin[0m).
  
  In  [5XGAP[0m  the  [10Xncurses[0m  windows  are  accessed  via  integers (as returned by
  [10XNCurses.newwin[0m).  The  standard  screen  [10Xstdscr[0m  from the [10Xncurses[0m library is
  available  as  window  number  [10X0[0m.  But  this  should  not  be used; to allow
  recursive  applications  of [10Xncurses[0m 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 [10X0[0m cannot be used with a panel.)
  
  Coordinates  in  windows  are  the  same  zero  based  integers  as  in  the
  corresponding   [10XC[0m   functions.  The  interface  of  functions  which  [13Xreturn[0m
  coordinates is slightly different from the [10XC[0m version; they just return lists
  of   integers   and   you   just   give   the   window  as  argument,  e.g.,
  [10XNCurses.getmaxyx(win)[0m returns a list [10X[nrows, ncols][0m of two integers.
  
  Characters  to  be written to a window can be given either as [5XGAP[0m characters
  like  [10X'a'[0m  or  as  integers  like [10XINT_CHAR('a') = 97[0m. If you use the integer
  version  you  can also add attributes including color settings to it for use
  with [10XNCurses.waddch[0m.
  
  When writing an application decide about an appropriate terminal setting for
  your visual mode windows, see [14X2.1-1[0m and the utility function [2XNCurses.SetTerm[0m
  ([14X2.2-2[0m)  below.  Use  [10XNCurses.savetty()[0m  and  [10XNCurses.resetty()[0m  to save and
  restore the previous setting.
  
  We  also  provide  some  higher level functionality for displaying marked up
  text, see [2XNCurses.PutLine[0m ([14X2.2-6[0m) and [2XNCurses.IsAttributeLine[0m ([14X2.2-3[0m).
  
  We  now  describe  some  utility  functions  for  putting text on a terminal
  window.
  
  [1X2.2-1 NCurses.ColorAttr[0m
  
  [2X> NCurses.ColorAttr( [0X[3Xfgcolor, bgcolor[0X[2X ) ____________________________[0Xfunction
  [6XReturns:[0X  an attribute for setting the foreground and background color to be
            used on a terminal window (it is a [5XGAP[0m integer).
  
  [2X> NCurses.attrs.has_colors___________________________________[0Xglobal variable
  
  The return value can be used like any other attribute as described in [14X2.1-7[0m.
  The arguments [3Xfgcolor[0m and [3Xbgcolor[0m can be given as strings, allowed are those
  in  [10X[  "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white"
  ][0m.  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  [2XNCurses.attrs.has_colors[0m  is  set  to  [9Xtrue[0m  or  [9Xfalse[0m if the
  terminal  supports  colors  or  not,  respectively.  If  a terminal does not
  support colors then [2XNCurses.ColorAttr[0m always returns [10XNCurses.attrs.NORMAL[0m.
  
  For  an  attribute  setting the foreground color with the default background
  color of the terminal use [10X-1[0m as [3Xbgcolor[0m or the same as [3Xfgcolor[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> win := NCurses.newwin(0,0,0,0);; pan := NCurses.new_panel(win);;[0X
    [4Xgap> defc := NCurses.defaultColors;;[0X
    [4Xgap> NCurses.wmove(win, 0, 0);;[0X
    [4Xgap> for a in defc do for b in defc do[0X
    [4X>      NCurses.wattrset(win, NCurses.ColorAttr(a, b));[0X
    [4X>      NCurses.waddstr(win, Concatenation(a,"/",b,"\t"));[0X
    [4X>    od; od;[0X
    [4Xgap> NCurses.update_panels();; NCurses.doupdate();;[0X
    [4Xgap> NCurses.napms(5000); # show for 5 seconds[0X
    [4Xgap> NCurses.endwin();; NCurses.del_panel(pan);; NCurses.delwin(win);;[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.2-2 NCurses.SetTerm[0m
  
  [2X> NCurses.SetTerm( [0X[3X[record][0X[2X ) ______________________________________[0Xfunction
  
  This  function  provides a unified interface to the various terminal setting
  functions of [10Xncurses[0m listed in [14X2.1-1[0m. The optional argument is a record with
  components  which  are assigned to [9Xtrue[0m or [9Xfalse[0m. Recognised components are:
  [10Xcbreak[0m,  [10Xecho[0m,  [10Xnl[0m,  [10Xintrflush[0m,  [10Xleaveok[0m,  [10Xscrollok[0m,  [10Xkeypad[0m,  [10Xraw[0m (with the
  obvious meaning if set to [9Xtrue[0m or [9Xfalse[0m, respectively).
  
  The  default, if no argument is given, is [10Xrec(cbreak := true, echo := false,
  nl  := false, intrflush := false, leaveok := true, scrollok := false, keypad
  :=  true)[0m.  (This is a useful setting for many applications.) If there is an
  argument  [3Xrecord[0m,  then  the  given  components  overwrite the corresponding
  defaults.
  
  [1X2.2-3 NCurses.IsAttributeLine[0m
  
  [2X> NCurses.IsAttributeLine( [0X[3Xobj[0X[2X ) ___________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0m if the argument describes a string with attributes.
  
  An  [13Xattribute  line[0m 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 [13Xnot[0m 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 [10XNCurses.attrs.STANDOUT[0m attribute.
  
  For an overview of attributes, see [14X2.1-7[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> NCurses.IsAttributeLine( "abc" );[0X
    [4Xtrue[0X
    [4Xgap> NCurses.IsAttributeLine( [ "abc", "def" ] );[0X
    [4Xfalse[0X
    [4Xgap> NCurses.IsAttributeLine( [ NCurses.attrs.UNDERLINE, true, "abc" ] );[0X
    [4Xtrue[0X
    [4Xgap> NCurses.IsAttributeLine( "" );  NCurses.IsAttributeLine( [] );[0X
    [4Xtrue[0X
    [4Xfalse[0X
  [4X------------------------------------------------------------------[0X
  
  The  [13Xempty  string[0m is an attribute line whereas the [13Xempty list[0m (which is not
  in [2XIsStringRep[0m ([14XReference: IsStringRep[0m)) is [13Xnot[0m an attribute line.
  
  [1X2.2-4 NCurses.ConcatenationAttributeLines[0m
  
  [2X> NCurses.ConcatenationAttributeLines( [0X[3Xlines[, keep][0X[2X ) _____________[0Xfunction
  [6XReturns:[0X  an attribute line.
  
  For  a  list [3Xlines[0m of attribute lines (see [2XNCurses.IsAttributeLine[0m ([14X2.2-3[0m)),
  [10XNCurses.ConcatenationAttributeLines[0m  returns  the attribute line obtained by
  concatenating the attribute lines in [3Xlines[0m.
  
  If  the  optional  argument  [3Xkeep[0m is [9Xtrue[0m then attributes set in an entry of
  [3Xlines[0m  are  valid  also  for  the  following entries of [3Xlines[0m. Otherwise (in
  particular  if  there  is  no  second  argument) the attributes are reset to
  [10XNCurses.attrs.NORMAL[0m between the entries of [3Xlines[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> plain_str:= "hello";;[0X
    [4Xgap> with_attr:= [ NCurses.attrs.BOLD, "bold" ];;[0X
    [4Xgap> NCurses.ConcatenationAttributeLines( [ plain_str, plain_str ] );[0X
    [4X"hellohello"[0X
    [4Xgap> NCurses.ConcatenationAttributeLines( [ plain_str, with_attr ] );[0X
    [4X[ "hello", 2097152, "bold" ][0X
    [4Xgap> NCurses.ConcatenationAttributeLines( [ with_attr, plain_str ] );[0X
    [4X[ 2097152, "bold", 0, "hello" ][0X
    [4Xgap> NCurses.ConcatenationAttributeLines( [ with_attr, with_attr ] );[0X
    [4X[ 2097152, "bold", 0, 2097152, "bold" ][0X
    [4Xgap> NCurses.ConcatenationAttributeLines( [ with_attr, with_attr ], true );[0X
    [4X[ 2097152, "bold", 2097152, "bold" ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.2-5 NCurses.RepeatedAttributeLine[0m
  
  [2X> NCurses.RepeatedAttributeLine( [0X[3Xline, width[0X[2X ) _____________________[0Xfunction
  [6XReturns:[0X  an attribute line.
  
  For  an  attribute  line  [3Xline[0m  (see  [2XNCurses.IsAttributeLine[0m ([14X2.2-3[0m)) and a
  positive  integer  [3Xwidth[0m, [10XNCurses.RepeatedAttributeLine[0m returns an attribute
  line   with   [3Xwidth[0m   displayed  characters  (see [2XNCurses.WidthAttributeLine[0m
  ([14X2.2-7[0m))  that is obtained by concatenating sufficiently many copies of [3Xline[0m
  and cutting off a tail if applicable.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> NCurses.RepeatedAttributeLine( "12345", 23 );[0X
    [4X"12345123451234512345123"[0X
    [4Xgap> NCurses.RepeatedAttributeLine( [ NCurses.attrs.BOLD, "12345" ], 13 );[0X
    [4X[ 2097152, "12345", 0, 2097152, "12345", 0, 2097152, "123" ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.2-6 NCurses.PutLine[0m
  
  [2X> NCurses.PutLine( [0X[3Xwin, y, x, lines[, skip][0X[2X ) ______________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0m if [3Xlines[0m were written, otherwise [9Xfalse[0m.
  
  The   argument   [3Xlines[0m   can   be   a   list   of   attribute   lines   (see
  [2XNCurses.IsAttributeLine[0m  ([14X2.2-3[0m))  or a single attribute line. This function
  writes the attribute lines to window [3Xwin[0m at and below of position [3Xy[0m, [3Xx[0m.
  
  If  the  argument  [3Xskip[0m  is given, it must be a nonnegative integer. In that
  case  the  first  [3Xskip[0m  characters of each given line are not written to the
  window (but the attributes are).
  
  [1X2.2-7 NCurses.WidthAttributeLine[0m
  
  [2X> NCurses.WidthAttributeLine( [0X[3Xline[0X[2X ) _______________________________[0Xfunction
  [6XReturns:[0X  number of displayed characters in an attribute line.
  
  For  an  attribute  line  [3Xline[0m  (see  [2XNCurses.IsAttributeLine[0m  ([14X2.2-3[0m)), the
  function returns the number of displayed characters of [3Xline[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> NCurses.WidthAttributeLine( "abcde" );[0X
    [4X5[0X
    [4Xgap> NCurses.WidthAttributeLine( [ NCurses.attrs.BOLD, "abc",[0X
    [4X>        NCurses.attrs.NORMAL, "de" ] );[0X
    [4X5[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.2-8 NCurses.Grid[0m
  
  [2X> NCurses.Grid( [0X[3Xwin, trow, brow, lcol, rcol, rowinds, colinds[0X[2X ) ____[0Xfunction
  
  This  function  draws  a grid of horizontal and vertical lines on the window
  [3Xwin[0m,  using  the  line  drawing  characters  explained  in  [14X2.1-6[0m. 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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> fun := function() local win, pan;[0X
    [4X>      win := NCurses.newwin(0,0,0,0);[0X
    [4X>      pan := NCurses.new_panel(win);[0X
    [4X>      NCurses.Grid(win, 2, 11, 5, 22, [5, 6], [13, 14]);[0X
    [4X>      NCurses.PutLine(win, 12, 0, "Press <Enter> to quit");[0X
    [4X>      NCurses.update_panels(); NCurses.doupdate();[0X
    [4X>      NCurses.wgetch(win);[0X
    [4X>      NCurses.endwin();[0X
    [4X>      NCurses.del_panel(pan); NCurses.delwin(win);[0X
    [4X> end;;[0X
    [4Xgap> fun();[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.2-9 NCurses.WBorder[0m
  
  [2X> NCurses.WBorder( [0X[3Xwin[, chars][0X[2X ) __________________________________[0Xfunction
  
  This  is  a convenient interface to the [10Xncurses[0m function [10Xwborder[0m. It draws a
  border  around  the  window  [3Xwin[0m. If no second argument is given the default
  line drawing characters are used, see [14X2.1-6[0m. Otherwise, [3Xchars[0m must be a list
  of   [5XGAP[0m   characters  or  integers  specifying  characters,  possibly  with
  attributes.  If  [3Xchars[0m  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 [3Xchars[0m contains 2 characters the first is used for the sides and
  the  second for all corners. If [3Xchars[0m contains just one character it is used
  for all sides including the corners.
  
  
  [1X2.2-10 Mouse support in [10Xncurses[1X applications[0X
  
  [2X> NCurses.UseMouse( [0X[3Xon[0X[2X ) ___________________________________________[0Xfunction
  [6XReturns:[0X  a record
  
  [2X> NCurses.GetMouseEvent( [0X[3X[0X[2X ) ________________________________________[0Xfunction
  [6XReturns:[0X  a list of records
  
  [10Xncurses[0m  allows on some terminals ([10Xxterm[0m and related) to catch mouse events.
  In  principle a subset of events can be catched, see [10Xmousemask[0m in [14X2.1-8[0m. 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 [2XNCurses.UseMouse[0m with argument [9Xtrue[0m to switch on the
  recognition of mouse events and [9Xfalse[0m to switch it off. The function returns
  a record with components [10X.new[0m and [10X.old[0m which are both set to the status [9Xtrue[0m
  or  [9Xfalse[0m from after and before the call, respectively. (There does not seem
  to   be   a   possibility   to   get  the  current  status  without  calling
  [2XNCurses.UseMouse[0m.)  If you call the function with argument [9Xtrue[0m and the [10X.new[0m
  component  of  the result is [9Xfalse[0m, then the terminal does not support mouse
  events.
  
  When the recognition of mouse events is switched on and a mouse event occurs
  then  the  key [10XNCurses.keys.MOUSE[0m is found in the input queue, see [10Xwgetch[0m in
  [14X2.1-4[0m.  If  this key is read the low level function [10XNCurses.getmouse[0m must be
  called  to  fetch  further details about the event from the input queue, see
  [14X2.1-8[0m.   In   many   cases   this  can  be  done  by  calling  the  function
  [2XNCurses.GetMouseEvent[0m  which  also  generates  additional  information.  The
  return  value  is a list of records, one for each panel over which the event
  occured,  these  panels  sorted  from top to bottom (so, often you will just
  need  the first entry if there is any). Each of these records has components
  [10X.win[0m,  the  corresponding  window  of  the  panel,  [10X.y[0m  and [10X.x[0m, the relative
  coordinates  in  window  [10X.win[0m  where the event occured, and [10X.event[0m, which is
  bound  to  one  of  the  strings  in [10XNCurses.mouseEvents[0m which describes the
  event.
  
  [13XSuggestion:[0m  Always  make the use of the mouse optional in your application.
  Allow  the  user  to switch mouse usage on and off while your application is
  running.  Some users may not like to give mouse control to your application,
  for  example  the  standard cut and paste functionality cannot be used while
  mouse events are catched.
  
  [1X2.2-11 NCurses.SaveWin[0m
  
  [2X> NCurses.SaveWin( [0X[3Xwin[0X[2X ) ___________________________________________[0Xfunction
  [2X> NCurses.StringsSaveWin( [0X[3Xcont[0X[2X ) ___________________________________[0Xfunction
  [2X> NCurses.RestoreWin( [0X[3Xwin, cont[0X[2X ) __________________________________[0Xfunction
  [2X> NCurses.ShowSaveWin( [0X[3Xcont[0X[2X ) ______________________________________[0Xfunction
  [6XReturns:[0X  a [5XGAP[0m object describing the contents of a window.
  
  These  functions  can  be  used  to save and restore the contents of [10Xncurses[0m
  windows.  [2XNCurses.SaveWin[0m  returns  a  list [10X[nrows, ncols, chars][0m giving the
  number  of  rows,  number  of columns, and a list of integers describing the
  content  of  window  [3Xwin[0m.  The  integers in the latter contain the displayed
  characters plus the attributes for the display.
  
  The  function  [2XNCurses.StringsSaveWin[0m  translates  data  [3Xcont[0m in form of the
  output  of [2XNCurses.SaveWin[0m to a list of [10Xnrows[0m strings giving the text of the
  rows  of  the  saved  window,  and ignoring the attributes. You can view the
  result with [2XNCurses.Pager[0m ([14X3.1-4[0m).
  
  The  argument  [3Xcont[0m for [2XNCurses.RestoreWin[0m must be of the same format as the
  output  of [2XNCurses.SaveWin[0m. The content of the saved window is copied to the
  window [3Xwin[0m, starting from the top-left corner as much as it fits.
  
  The  utility  [2XNCurses.ShowSaveWin[0m  can  be  used  to  display  the output of
  [2XNCurses.SaveWin[0m (as much of the top-left corner as fits on the screen).
  
