curses 1.6.1 → 1.7.0

data/vendor/PDCursesMod/pdcurses/pad.c

@@ -0,0 +1,303 @@
+/* PDCurses */
+
+#include <curspriv.h>
+#include <assert.h>
+
+/*man-start**************************************************************
+
+pad
+---
+
+### Synopsis
+
+    WINDOW *newpad(int nlines, int ncols);
+    WINDOW *subpad(WINDOW *orig, int nlines, int ncols,
+                   int begy, int begx);
+    int prefresh(WINDOW *win, int py, int px, int sy1, int sx1,
+                 int sy2, int sx2);
+    int pnoutrefresh(WINDOW *w, int py, int px, int sy1, int sx1,
+                     int sy2, int sx2);
+    int pechochar(WINDOW *pad, chtype ch);
+    int pecho_wchar(WINDOW *pad, const cchar_t *wch);
+
+    bool is_pad(const WINDOW *pad);
+
+### Description
+
+   A pad is a special kind of window, which is not restricted by the
+   screen size, and is not necessarily associated with a particular part
+   of the screen. You can use a pad when you need a large window, and
+   only a part of the window will be on the screen at one time. Pads are
+   not refreshed automatically (e.g., from scrolling or echoing of
+   input). You can't call wrefresh() with a pad as an argument; use
+   prefresh() or pnoutrefresh() instead. Note that these routines
+   require additional parameters to specify the part of the pad to be
+   displayed, and the location to use on the screen.
+
+   newpad() creates a new pad data structure.
+
+   subpad() creates a new sub-pad within a pad, at position (begy,
+   begx), with dimensions of nlines lines and ncols columns. This
+   position is relative to the pad, and not to the screen as with
+   subwin. Changes to either the parent pad or sub-pad will affect both.
+   When using sub-pads, you may need to call touchwin() before calling
+   prefresh().
+
+   pnoutrefresh() copies the specified pad to the virtual screen.
+
+   prefresh() calls pnoutrefresh(), followed by doupdate().
+
+   These routines are analogous to wnoutrefresh() and wrefresh(). (py,
+   px) specifies the upper left corner of the part of the pad to be
+   displayed; (sy1, sx1) and (sy2, sx2) describe the screen rectangle
+   that will contain the selected part of the pad.
+
+   pechochar() is functionally equivalent to addch() followed by a call
+   to prefresh(), with the last-used coordinates and dimensions.
+   pecho_wchar() is the wide-character version.
+
+   is_pad() reports whether the specified window is a pad.
+
+### Return Value
+
+   All functions except is_pad() return OK on success and ERR on error.
+
+### Portability
+   Function              | X/Open | ncurses | NetBSD
+   :---------------------|:------:|:-------:|:------:
+   newpad                |    Y   |    Y    |   Y
+   subpad                |    Y   |    Y    |   Y
+   prefresh              |    Y   |    Y    |   Y
+   pnoutrefresh          |    Y   |    Y    |   Y
+   pechochar             |    Y   |    Y    |   Y
+   pecho_wchar           |    Y   |    Y    |   Y
+   is_pad                |    -   |    Y    |   Y
+
+**man-end****************************************************************/
+
+void PDC_add_window_to_list( WINDOW *win);
+
+#include <string.h>
+
+/* save values for pechochar() */
+
+WINDOW *newpad(int nlines, int ncols)
+{
+    WINDOW *win;
+
+    PDC_LOG(("newpad() - called: lines=%d cols=%d\n", nlines, ncols));
+
+    assert( nlines > 0 && ncols > 0);
+    win = PDC_makenew(nlines, ncols, 0, 0);
+    if (win)
+        win = PDC_makelines(win);
+
+    if (!win)
+        return (WINDOW *)NULL;
+
+    werase(win);
+
+    win->_flags = _PAD;
+
+    /* save default values in case pechochar() is the first call to
+       prefresh(). */
+
+    win->_pminrow = 0;
+    win->_pmincol = 0;
+    win->_sminrow = 0;
+    win->_smincol = 0;
+    win->_smaxrow = min(LINES, nlines) - 1;
+    win->_smaxcol = min(COLS, ncols) - 1;
+    PDC_add_window_to_list( win);
+
+    return win;
+}
+
+WINDOW *subpad(WINDOW *orig, int nlines, int ncols, int begy, int begx)
+{
+    WINDOW *win;
+    int i;
+
+    PDC_LOG(("subpad() - called: lines=%d cols=%d begy=%d begx=%d\n",
+             nlines, ncols, begy, begx));
+
+    assert( orig && (orig->_flags & _PAD));
+    if (!orig || !(orig->_flags & _PAD))
+        return (WINDOW *)NULL;
+
+    /* make sure window fits inside the original one */
+
+    if (begy < 0 || begx < 0 ||
+        (begy + nlines) > orig->_maxy ||
+        (begx + ncols)  > orig->_maxx)
+        return (WINDOW *)NULL;
+
+    if (!nlines)
+        nlines = orig->_maxy - begy;
+
+    if (!ncols)
+        ncols = orig->_maxx - begx;
+
+    assert( nlines > 0 && ncols > 0);
+    win = PDC_makenew(nlines, ncols, begy, begx);
+    if (!win)
+        return (WINDOW *)NULL;
+
+    /* initialize window variables */
+
+    win->_attrs = orig->_attrs;
+    win->_leaveit = orig->_leaveit;
+    win->_scroll = orig->_scroll;
+    win->_delayms = orig->_delayms;
+    win->_use_keypad = orig->_use_keypad;
+    win->_parent = orig;
+
+    for (i = 0; i < nlines; i++)
+        win->_y[i] = orig->_y[begy + i] + begx;
+
+    win->_flags = _SUBPAD;
+
+    /* save default values in case pechochar() is the first call
+       to prefresh(). */
+
+    win->_pminrow = 0;
+    win->_pmincol = 0;
+    win->_sminrow = 0;
+    win->_smincol = 0;
+    win->_smaxrow = min(LINES, nlines) - 1;
+    win->_smaxcol = min(COLS, ncols) - 1;
+    PDC_add_window_to_list( win);
+
+    return win;
+}
+
+int prefresh(WINDOW *win, int py, int px, int sy1, int sx1, int sy2, int sx2)
+{
+    PDC_LOG(("prefresh() - called\n"));
+
+    if (pnoutrefresh(win, py, px, sy1, sx1, sy2, sx2) == ERR)
+        return ERR;
+
+    doupdate();
+    return OK;
+}
+
+int pnoutrefresh(WINDOW *w, int py, int px, int sy1, int sx1, int sy2, int sx2)
+{
+    int num_cols;
+    int sline;
+    int pline;
+
+    PDC_LOG(("pnoutrefresh() - called\n"));
+
+    assert( w);
+
+    if (py < 0)
+        py = 0;
+    if (px < 0)
+        px = 0;
+    if (sy1 < 0)
+        sy1 = 0;
+    if (sx1 < 0)
+        sx1 = 0;
+
+    if ((!w || !(w->_flags & (_PAD|_SUBPAD)) ||
+        (sy2 >= LINES) || (sx2 >= COLS)) ||
+        (sy2 < sy1) || (sx2 < sx1))
+        return ERR;
+
+    sline = sy1;
+    pline = py;
+
+    num_cols = min((sx2 - sx1 + 1), (w->_maxx - px));
+
+    while (sline <= sy2)
+    {
+        if (pline < w->_maxy)
+        {
+            memcpy(curscr->_y[sline] + sx1, w->_y[pline] + px,
+                   num_cols * sizeof(chtype));
+
+            PDC_mark_cells_as_changed( curscr, sline, sx1, sx2);
+            PDC_set_changed_cells_range( w, pline, _NO_CHANGE, _NO_CHANGE);
+        }
+
+        sline++;
+        pline++;
+    }
+
+    if (w->_clear)
+    {
+        w->_clear = FALSE;
+        curscr->_clear = TRUE;
+    }
+
+    /* position the cursor to the pad's current position if possible --
+       is the pad current position going to end up displayed? if not,
+       then don't move the cursor; if so, move it to the correct place */
+
+    if (!w->_leaveit && w->_cury >= py && w->_curx >= px &&
+         w->_cury <= py + (sy2 - sy1) && w->_curx <= px + (sx2 - sx1))
+    {
+        curscr->_cury = (w->_cury - py) + sy1;
+        curscr->_curx = (w->_curx - px) + sx1;
+    }
+
+    w->_pminrow = py;
+    w->_pmincol = px;
+    w->_sminrow = sy1;
+    w->_smincol = sx1;
+    w->_smaxrow = sy2;
+    w->_smaxcol = sx2;
+    return OK;
+}
+
+int PDC_pnoutrefresh_with_stored_params( WINDOW *pad)
+{
+    return prefresh(pad, pad->_pminrow, pad->_pmincol, pad->_sminrow,
+                    pad->_smincol, pad->_smaxrow, pad->_smaxcol);
+}
+
+int pechochar(WINDOW *pad, chtype ch)
+{
+    int rval;
+
+    PDC_LOG(("pechochar() - called\n"));
+
+    if (waddch(pad, ch) == ERR)
+        return ERR;
+
+    rval = PDC_pnoutrefresh_with_stored_params( pad);
+    if( rval == OK)
+        doupdate( );
+    return( rval);
+}
+
+#ifdef PDC_WIDE
+int pecho_wchar(WINDOW *pad, const cchar_t *wch)
+{
+    int rval;
+
+    PDC_LOG(("pecho_wchar() - called\n"));
+
+    assert( wch);
+    if (!wch || (waddch(pad, *wch) == ERR))
+        return ERR;
+
+    rval = PDC_pnoutrefresh_with_stored_params( pad);
+    if( rval == OK)
+        doupdate( );
+    return( rval);
+}
+#endif
+
+bool is_pad(const WINDOW *pad)
+{
+    PDC_LOG(("is_pad() - called\n"));
+
+    assert( pad);
+    if (!pad)
+        return FALSE;
+
+    return (pad->_flags & _PAD) ? TRUE : FALSE;
+}

data/vendor/PDCursesMod/pdcurses/pairs.txt

@@ -0,0 +1,94 @@
+NOTES ON COLOR PAIR HANDLING
+
+   This is a description of the (slightly convoluted) methods used
+for maintaining the color pair table in 'color.c'.  It is of interest
+only if you are attempting to puzzle out some of the odder code in
+that file.  If you're simply using the PDCursesMod library,  the
+inner works are irrelevant to you.  You can safely treat color pair
+management as a black box.
+
+   In theory,  we can have up to 2^20 = 1048576 color pairs (if the
+default 64-bit chtypes are used).  This is limited to 4096 pairs with
+32-bit chtypes and narrow-character builds,  or 256 pairs with 32-bit
+chtypes and wide-character builds.  ncurses,  PDCurses,  and other
+curses implementations will support yet other numbers of pairs.
+
+  In practice,  it's rare for a curses/PDCursesMod program to use
+more than a few color pairs.  The 'mbrot',  'testcurs' and 'picsview'
+demos provide somewhat contrived examples of the use of hundreds or
+thousands of color pairs.
+
+   The color pair table (SP->pairs) is dynamically reallocated to be
+the power of two greater than or equal to the highest allocated index.
+Allocate pair 37,  and it will be reallocated to have 64 entries,  plus
+an extra 'dummy' entry.  (The color palette is similarly allocated
+dynamically;  see 'pdccolor.c' in the 'common' directory.)  For almost
+all programs,  this will result in only a small allocation.
+
+   Complexities arose when the ncurses extensions alloc_pair( ),
+find_pair( ),  and free_pair( )  were added.  If alloc_pair( ) is
+called and we don't already have a pair allocated with that foreground
+and background,  we need to find an available free pair.  If no pairs
+are free (we have used all available color pairs),  the 'oldest' pair
+allocated is used.
+
+   At first,  this was done in a simple way.  Each color pair had a
+'count' (basically an 'age') parameter.  We would find a pair by
+scanning linearly through the color table.  If we didn't find one,
+we'd scan linearly for an unused pair.  If that didn't work,  and the
+color pair table was already at its maximum size,  we'd scan linearly
+for the oldest pair and use that.  You could be looking at three
+scans of a table of a million entries.
+
+   The first improvement was to add a doubly-linked list of used
+color pairs, and another one of unused ('free') color pairs.  Pair 0
+is always used and is the head node for the 'used' list;  the dummy
+entry at the end is always free and is the head node for the 'free'
+list.  So we avoid the extra bookkeeping involved with empty lists.
+
+   With this,  the dummy entry will point us to an available free node.
+The linked list of 'used' color pairs will point us to the oldest used
+pair.  So the scan for a free pair and the scan for the 'oldest' pair
+are not needed.
+
+HASH TABLE FOR FINDING PAIRS
+
+   The remaining performance issue involves find_pair( ).  We need a
+reasonably quick way,  given a foreground and background index,  to
+locate a color pair that uses that foreground and background.  (Or to
+recognize that no such pair is currently allocated.)  ncurses uses the
+tsearch/tfind/tdelete family of functions for this purpose.  However,
+this isn't necessarily available on Windows,  DOS,  and OS/2.  And it's
+arguably overkill.  The only operations we need are "do we have this pair",
+"add this pair",  and "free this pair".  We don't need to run through
+pairs in order,  or any of the other things trees would let us do.  We
+need good speed on average,  but not an upper bound per search.
+
+   So PDCursesMod maintains a hash table for this purpose.  The
+foreground and background indices are hashed using _hash_color_pair( ),
+and we then probe the hash table looking for the color pair index (if
+we're "freeing" that pair,  possibly for re-use);  or for an available
+entry (if we're setting that pair);  or for any existing color pair that
+uses that foreground and background (if we're in find_pair( )).
+
+   Hash tables are seldom used if deletions are involved,  but they can
+be (and are here).  The code uses a 'lazy deletion' scheme,
+
+https://en.wikipedia.org/wiki/Lazy_deletion
+
+   Deleted entries are set to a 'deleted' value,  which is _not_ the
+same as saying they are 'free'.  When searching for a value,  you only
+stop when running into an actually 'free' slot. In adding a value to
+the table,  a 'deleted' slot can be used.
+
+   Changing a color pair that's already been allocated therefore involves
+deleting the old pair and then allocating the new pair.  After enough
+of this,  your table will have a mix of allocated,  'deleted',  and
+'free' slots.  When less than 20% or 25% of slots are 'free',  performance
+will start to drop a bit and the table is rebuilt,  at a doubled size if
+necessary,  and getting rid of the 'deleted' entries in the process.
+
+   Hash table collisions are handled by probing for an available entry
+using a hybrid linear/triangular numbers scheme.  This provides good
+performance and ensures that if a free entry is available,  it'll get
+found.  See https://www.projectpluto.com/hashing.htm for details.