From: Christian Heller <c.heller@plomlompom.de>
Date: Thu, 25 Jul 2013 20:19:49 +0000 (+0200)
Subject: Applied new style and documentation rules to the "windows" library, also performing... 
X-Git-Tag: tce~1134
X-Git-Url: https://plomlompom.com/repos/%7B%7B%20web_path%20%7D%7D/cards/%7B%7B%20card_id%20%7D%7D/tasks?a=commitdiff_plain;h=566ddf894142085e3f0208a08fa36ccce6d6a6ea;p=plomrogue

Applied new style and documentation rules to the "windows" library, also performing some extremly minor code fixing / re-structuring on the way.
---

diff --git a/src/map_objects.c b/src/map_objects.c
index 9adf634..2fb6b80 100644
--- a/src/map_objects.c
+++ b/src/map_objects.c
@@ -111,8 +111,8 @@ extern void write_map_objects(void * start, FILE * file,
 
 
 
-extern void read_map_objects (void * start, FILE * file, size_t size,
-                              void (* r_typedata) (void *, FILE *) )
+extern void read_map_objects(void * start, FILE * file, size_t size,
+                             void (* r_typedata) (void *, FILE *) )
 {
     struct MapObj * map_obj;
     uint16_t test;
@@ -212,5 +212,5 @@ extern struct MapObjDef * get_map_obj_def (struct World * world, char def_id)
              d->id != def_id && 0 != d->next;
              d = d->next);
     }
-  return d;
+    return d;
 }
diff --git a/src/windows.c b/src/windows.c
index 33b9b31..b2643bf 100644
--- a/src/windows.c
+++ b/src/windows.c
@@ -1,300 +1,609 @@
+/* windows.c */
+
 #include "windows.h"
-#include <stdint.h>
-#include <ncurses.h>
-#include <stdlib.h>
-#include <string.h>
-
-struct Corners {
-  struct yx_uint16 tl;
-  struct yx_uint16 tr;
-  struct yx_uint16 bl;
-  struct yx_uint16 br; };
-
-static void refit_pad (struct WinMeta *);
-static void place_win (struct WinMeta *, struct Win *);
-static void update_wins (struct WinMeta *, struct Win *);
-static void destroy_win (struct Win *);
-static void draw_wins_borders (struct Win *, struct Win *, struct Corners *, uint16_t);
-static void draw_win_borders (struct Win *, char);
-static void draw_wins (struct Win *);
-
-extern struct WinMeta init_win_meta (WINDOW * screen) {
-// Create and populate WinMeta struct with sane default values.
-  struct WinMeta wmeta;
-  wmeta.screen = screen;
-  wmeta.pad.size.y = getmaxy(screen);
-  wmeta.pad.size.x = getmaxx(screen);
-  wmeta.chain_start = 0;
-  wmeta.chain_end = 0;
-  wmeta.pad_offset = 0;
-  wmeta.pad.curses_win = newpad(wmeta.pad.size.y, 1);
-  wmeta.active = 0;
-  return wmeta; }
-
-extern struct Win init_win (struct WinMeta * wmeta, char * title, void * data, void * func) {
-// Create and populate Win struct with sane default values.
-  struct Win w;
-  w.prev = 0;
-  w.next = 0;
-  w.frame.curses_win = 0;
-  w.title = title;
-  w.frame.size.x = 20;
-  w.frame.size.y = wmeta->pad.size.y - 1;
-  w.data = data;
-  w.draw = func;
-  return w; }
-
-extern void append_win (struct WinMeta * wmeta, struct Win * w) {
-// Append win to window chain. Set active, if first window. Update geometry of windows from new window on.
-  if (0 != wmeta->chain_start) {
-    w->prev = wmeta->chain_end;
-    wmeta->chain_end->next = w; }
-  else {
-    wmeta->active = w;
-    wmeta->chain_start = w; }
-  wmeta->chain_end = w;
-  update_wins(wmeta, w); }
-
-static void refit_pad (struct WinMeta * wmeta) {
-// Fit pad width to minimum width demanded by current windows' geometries.
-  uint16_t lastwincol = 0;
-  struct Win * w_p = wmeta->chain_start;
-  while (w_p != 0) {
-    if (w_p->start.x + w_p->frame.size.x > lastwincol + 1)
-      lastwincol = w_p->start.x + w_p->frame.size.x - 1;
-    w_p = w_p->next; }
-  if (getmaxx(wmeta->pad.curses_win) != lastwincol)
-    wresize(wmeta->pad.curses_win, getmaxy(wmeta->pad.curses_win), lastwincol + 2); }
-
-extern void suspend_win (struct WinMeta * wmeta, struct Win * w) {
-// Destroy win, suspend from chain. Update geometry of following rows and pad, as well as activity selection.
-  destroy_win(w);
-  if (wmeta->chain_start != w)         // Give win's position in the chain to element next to it in the chain.
-    w->prev->next = w->next;
-  else
-    wmeta->chain_start = w->next;
-  char pad_refitted = 0;
-  if (wmeta->chain_end != w) {                      // Let chain element next to win know its new predecessor.
-    w->next->prev = w->prev;
-    if (wmeta->active == w)                               // If win was active, shift active window pointer to
-      wmeta->active = w->next;                            // the next chain element, if that is a window ...
-    update_wins(wmeta, w->next);
-    pad_refitted = 1; }
-  else {
-    wmeta->chain_end = w->prev;
-    if (wmeta->active == w)                                            // ... or else to the previous element.
-      wmeta->active = w->prev; }
-  w->prev = 0;
-  w->next = 0;
-  if (0 == pad_refitted)                                                            // Refit pad if necessary.
-    refit_pad(wmeta); }
-
-static void place_win (struct WinMeta * wmeta, struct Win * w) {
-// Based on position and sizes of previous window, find fitting place for current window.
-  w->start.x = 0;                                  // if window is first in chain, place it on top-left corner
-  w->start.y = 1;
-  if (0 != w->prev) {
-    struct Win * w_top = w->prev;
-    while (w_top->start.y != 1)
-      w_top = w_top->prev;                                       // else, default to placing window in new top
-    w->start.x = w_top->start.x + w_top->frame.size.x + 1;       // column to the right of the last one
-    uint16_t w_prev_maxy = w->prev->start.y + getmaxy(w->prev->frame.curses_win);
-    if (w->frame.size.x <= w->prev->frame.size.x && w->frame.size.y < wmeta->pad.size.y - w_prev_maxy) {
-      w->start.x = w->prev->start.x;                       // place window below previous window if it fits
-      w->start.y = w_prev_maxy + 1; }                      // vertically and is not wider than its predecessor
-    else {
-      struct Win * w_up = w->prev;
-      struct Win * w_upup = w_up;
-      uint16_t widthdiff;
-      while (w_up != w_top) {
-        w_upup = w_up->prev;
-        while (1) {
-          if (w_up->start.y != w_upup->start.y)
-            break;
-          w_upup = w_upup->prev; }
-        w_prev_maxy = w_upup->start.y + getmaxy(w_upup->frame.curses_win);
-        widthdiff = (w_upup->start.x + w_upup->frame.size.x) - (w_up->start.x + w_up->frame.size.x);
-        if (w->frame.size.y < wmeta->pad.size.y - w_prev_maxy && w->frame.size.x < widthdiff) {
-          w->start.x = w_up->start.x + w_up->frame.size.x + 1 ; // else try to open new sub column under
-          w->start.y = w_prev_maxy + 1;                        // last window below which enough space remains
-          break; }
-        w_up = w_upup; } } } }
-
-static void update_wins (struct WinMeta * wmeta, struct Win * w) {
-// Update geometry of win and its next of kin. Destroy (if visible), (re-)build window. If need, resize pad.
-  if (0 != w->frame.curses_win)
-    destroy_win (w);
-  place_win(wmeta, w);
-  refit_pad(wmeta);
-  w->frame.curses_win=subpad(wmeta->pad.curses_win, w->frame.size.y, w->frame.size.x, w->start.y, w->start.x);
-  if (0 != w->next)
-    update_wins (wmeta, w->next); }
-
-static void destroy_win (struct Win * w) {
-// Delete window.
-  delwin(w->frame.curses_win);
-  w->frame.curses_win = 0; }
-
-static void draw_win_borders (struct Win * w, char active) {
-// Draw borders of window win, including title. Decorate in a special way if window is marked as active.
+#include <stdint.h>    /* for uint16_t, uint32_t */
+#include <ncurses.h>   /* for LOTS of stuff */
+#include <stdlib.h>    /* for malloc(), free() */
+#include <string.h>    /* for strlen(), memcpy() */
+#include "yx_uint16.h" /* for yx_uint16 coordinates */
+
+
+
+/* Stores a window's border corners. This is a helper to draw_all_wins() (and
+ * filled by its helper draw_wins_borders()) which draws the horizontal and
+ * vertical lines of all windows' borders first and the corner characters of
+ * all windows only afterwards (so that corners are not overwritten by lines).
+ * This delay of corner drawing necessitates temporarily storing their
+ * coordinates (harvested during the previous border drawing activities) in a
+ * series of such Corners structs to be released at the end.
+ *
+ * TODO: Maybe replace this complicated method by dropping the harvesting of
+ * corners from draw_wins_borders() and instead collecting them in a second
+ * border drawing cycle that repeats some cycles but works in a much more
+ * straightforward way.
+ */
+struct Corners
+{
+    struct yx_uint16 tl;
+    struct yx_uint16 tr;
+    struct yx_uint16 bl;
+    struct yx_uint16 br;
+};
+
+
+
+/* Fit virtual screen's width to minimum width demanded by current windows'
+ * geometries.
+ */
+static void refit_pad(struct WinMeta * wmeta);
+
+
+
+/* Update geometry (sizes, positions) of window "w" and its successors in the
+ * window chain. For the positioning algorithm place_win() is used.
+ */
+static void update_wins(struct WinMeta * wmeta, struct Win * w);
+static void place_win(struct WinMeta * wmeta, struct Win * w);
+
+
+
+/* Destroy window "w"'s ncurses window (and set w.Frame.curses_win to 0). */
+static void destroy_win(struct Win * w);
+
+
+
+/* Draw contents of all windows in window chain from window "w" onwards. */
+static void draw_wins(struct Win * w);
+
+
+
+/* draw_win_borders() Draws the vertical and horizontal borders of window "w"
+ * sans corners, and draws the top border line as the windows' title bar
+ * (highlighted if the window is described active by "active" being set).
+ * draw_wins_borders().
+ *
+ * draw_wins_borders() calls draw_win_borders() recursively on all windows from
+ * "w" on. It also fills "corners" with coordinates of each window's corners,
+ * iterating over its Corners structs via the "i" index incremented by 1 over
+ * each handled window. "w_active" is a pointer to the one window that
+ * draw_win_borders() is supposed to handle as the active window.
+ */
+static void draw_win_borders(struct Win * w, char active);
+static void draw_wins_borders(struct Win * w, struct Win * w_active,
+                              struct Corners * corners, uint16_t i);
+
+
+
+static void refit_pad(struct WinMeta * wmeta)
+{
+    /* Determine rightmost window column. */
+    uint16_t lastwincol = 0;
+    struct Win * w_p = wmeta->chain_start;
+    while (w_p != 0)
+    {
+        if (w_p->start.x + w_p->frame.size.x > lastwincol + 1)
+        {
+            lastwincol = w_p->start.x + w_p->frame.size.x - 1;
+        }
+        w_p = w_p->next;
+    }
+
+    /* Only resize the pad if the rightmost window column has changed. */
+    if (getmaxx(wmeta->pad.curses_win) != lastwincol)
+    {
+        wresize(wmeta->pad.curses_win,
+                getmaxy(wmeta->pad.curses_win), lastwincol + 2);
+    }
+}
+
+
+
+static void update_wins (struct WinMeta * wmeta, struct Win * w)
+{
+    if (0 != w->frame.curses_win)
+    {
+        destroy_win (w);
+    }
+    place_win(wmeta, w);
+    refit_pad(wmeta);
+    w->frame.curses_win = subpad(wmeta->pad.curses_win,
+                                 w->frame.size.y, w->frame.size.x,
+                                 w->start.y, w->start.x);
+    if (0 != w->next)
+    {
+        update_wins (wmeta, w->next);
+    }
+}
+
+
+
+static void place_win (struct WinMeta * wmeta, struct Win * w)
+{
+    /* First window goes into the upper-left corner. */
+    w->start.x = 0;
+    w->start.y = 1;                             /* Leave space for title bar. */
+    if (0 != w->prev)
+    {
+
+        /* Non-first window fallbacks to: fit rightwards of rightmost border. */
+        struct Win * w_top = w->prev;
+        while (w_top->start.y != 1)
+        {
+            w_top = w_top->prev;
+        }
+        w->start.x = w_top->start.x + w_top->frame.size.x + 1;
+
+        /* Fit window below its predecessor if that one directly thrones over
+         * empty space wide and high enough.
+         */
+        uint16_t w_prev_maxy = w->prev->start.y
+                               + getmaxy(w->prev->frame.curses_win);
+        if (   w->frame.size.x <= w->prev->frame.size.x
+            && w->frame.size.y <  wmeta->pad.size.y - w_prev_maxy)
+        {
+            w->start.x = w->prev->start.x;
+            w->start.y = w_prev_maxy + 1;
+        }
+
+        /* Failing that, try to open a new sub column below the nearest
+         * predecessor window that thrones over enough empty space.
+         */
+        else
+        {
+            struct Win * w_up = w->prev;
+            struct Win * w_upup = w_up;
+            uint16_t widthdiff;
+            while (w_up != w_top)
+            {
+                w_upup = w_up->prev;
+                while (1)
+                {
+                    if (w_up->start.y != w_upup->start.y)
+                    {
+                        break;
+                    }
+                    w_upup = w_upup->prev;
+                }
+                w_prev_maxy = w_upup->start.y
+                              + getmaxy(w_upup->frame.curses_win);
+                widthdiff = (w_upup->start.x + w_upup->frame.size.x)
+                            - (w_up->start.x + w_up->frame.size.x);
+                if (   w->frame.size.y < wmeta->pad.size.y - w_prev_maxy
+                    && w->frame.size.x < widthdiff)
+                {
+                    w->start.x = w_up->start.x + w_up->frame.size.x + 1 ;
+                    w->start.y = w_prev_maxy + 1;
+                    break;
+                }
+                w_up = w_upup;
+            }
+        }
+    }
+}
+
+
+
+static void destroy_win (struct Win * w)
+{
+    delwin(w->frame.curses_win);
+    w->frame.curses_win = 0;
+}
+
+
+
+static void draw_wins (struct Win * w)
+{
+    w->draw(w);
+    if (0 != w->next)
+    {
+        draw_wins (w->next);
+    }
+}
+
+
+
+static void draw_win_borders(struct Win * w, char active)
+{
+  /* Draw vertical and horizontal border lines. */
   uint16_t y, x;
-  for (y = w->start.y; y <= w->start.y + w->frame.size.y; y++) {
+  for (y = w->start.y; y <= w->start.y + w->frame.size.y; y++)
+  {
     mvwaddch(wgetparent(w->frame.curses_win), y, w->start.x - 1, '|');
-    mvwaddch(wgetparent(w->frame.curses_win), y, w->start.x + w->frame.size.x, '|'); }
-  for (x = w->start.x; x <= w->start.x + w->frame.size.x; x++) {
+    mvwaddch(wgetparent(w->frame.curses_win),
+             y, w->start.x + w->frame.size.x, '|');
+  }
+  for (x = w->start.x; x <= w->start.x + w->frame.size.x; x++)
+  {
     mvwaddch(wgetparent(w->frame.curses_win), w->start.y - 1, x, '-');
-    mvwaddch(wgetparent(w->frame.curses_win), w->start.y + w->frame.size.y, x, '-'); }
-  char min_title_length_visible = 3;        // 1 char minimal, plus 2 chars for decoration left/right of title
-  if (w->frame.size.x >= min_title_length_visible) {
+    mvwaddch(wgetparent(w->frame.curses_win),
+             w->start.y + w->frame.size.y, x, '-');
+  }
+
+  /* Draw as much as possible of the title into center of top border line. */
+  char min_title_length_visible = 3; /* minimum 1 char + 2 padding/decoration */
+  if (w->frame.size.x >= min_title_length_visible)
+  {
     uint16_t title_offset = 0;
     if (w->frame.size.x > strlen(w->title) + 2)
+    {
       title_offset = (w->frame.size.x - (strlen(w->title) + 2)) / 2;                  // + 2 is for decoration
+    }
     uint16_t length_visible = strnlen(w->title, w->frame.size.x - 2);
     char title[length_visible + 3];
     char decoration = ' ';
     if (1 == active)
+    {
       decoration = '$';
+    }
     memcpy(title + 1, w->title, length_visible);
     title[0] = title[length_visible + 1] = decoration;
     title[length_visible + 2] = '\0';
-    mvwaddstr(wgetparent(w->frame.curses_win), w->start.y - 1, w->start.x + title_offset, title); } }
-
-static void draw_wins_borders (struct Win * w, struct Win * w_active, struct Corners * corners, uint16_t i) {
-// Call draw_win_borders() for all windows in chain from win on. Save current window's border corners.
-  char active = 0;
-  if (w == w_active)
-    active = 1;
-  draw_win_borders(w, active);
-  corners[i].tl.y = w->start.y - 1;
-  corners[i].tl.x = w->start.x - 1;
-  corners[i].tr.y = w->start.y - 1;
-  corners[i].tr.x = w->start.x + w->frame.size.x;
-  corners[i].bl.y = w->start.y + w->frame.size.y;
-  corners[i].bl.x = w->start.x - 1;
-  corners[i].br.y = w->start.y + w->frame.size.y;
-  corners[i].br.x = w->start.x + w->frame.size.x;
-  if (0 != w->next) {
-    draw_wins_borders (w->next, w_active, corners, i + 1); } }
-
-static void draw_wins (struct Win * w) {
-// Draw contents of all windows in window chain from win on.
-  w->draw(w);
-  if (0 != w->next) {
-    draw_wins (w->next); } }
-
-extern void draw_scroll_hint (struct Frame * frame, uint16_t pos, uint32_t dist, char dir) {
-// Draw scroll hint into frame at pos (row or col dependend on dir), mark distance of dist cells into dir.
-  char more[] = "more";
-  char unit_cols[] = "columns";
-  char unit_rows[] = "lines";
-  uint16_t dsc_space = frame->size.x;
-  char * unit = unit_rows;
-  if ('<' == dir || '>' == dir) {
-    dsc_space = frame->size.y;
-    unit = unit_cols; }
-  char * scrolldsc = malloc((4 * sizeof(char)) + strlen(more) + strlen(unit) + 10);  // 10 = uint32 max strlen
-  sprintf(scrolldsc, " %d %s %s ", dist, more, unit);
-  char offset = 1, q;
-  if (dsc_space > strlen(scrolldsc) + 1)
-    offset = (dsc_space - strlen(scrolldsc)) / 2;
-  chtype symbol;
-  for (q = 0; q < dsc_space; q++) {
-    if (q >= offset && q < strlen(scrolldsc) + offset)
-      symbol = scrolldsc[q - offset] | A_REVERSE;
-    else
-      symbol = dir | A_REVERSE;
-    if ('<' == dir || '>' == dir)
-      mvwaddch(frame->curses_win, q, pos, symbol);
+    mvwaddstr(wgetparent(w->frame.curses_win),
+              w->start.y - 1, w->start.x + title_offset, title);
+  }
+}
+
+static void draw_wins_borders(struct Win * w, struct Win * w_active,
+                              struct Corners * corners, uint16_t i)
+{
+    char active = 0;
+    if (w == w_active)
+    {
+        active = 1;
+    }
+    draw_win_borders(w, active);
+    corners[i].tl.y = w->start.y - 1;
+    corners[i].tl.x = w->start.x - 1;
+    corners[i].tr.y = w->start.y - 1;
+    corners[i].tr.x = w->start.x + w->frame.size.x;
+    corners[i].bl.y = w->start.y + w->frame.size.y;
+    corners[i].bl.x = w->start.x - 1;
+    corners[i].br.y = w->start.y + w->frame.size.y;
+    corners[i].br.x = w->start.x + w->frame.size.x;
+    if (0 != w->next)
+    {
+        draw_wins_borders (w->next, w_active, corners, i + 1);
+    }
+}
+
+
+
+extern struct WinMeta init_win_meta(WINDOW * screen)
+{
+    struct WinMeta wmeta;
+    wmeta.screen         = screen;
+    wmeta.pad.size.y     = getmaxy(screen);
+    wmeta.pad.size.x     = getmaxx(screen);
+    wmeta.chain_start    = 0;
+    wmeta.chain_end      = 0;
+    wmeta.pad_offset     = 0;
+    wmeta.pad.curses_win = newpad(wmeta.pad.size.y, 1);
+    wmeta.active         = 0;
+    return wmeta;
+}
+
+
+
+extern struct Win init_win(struct WinMeta * wmeta, char * title,
+                           void * data, void * func)
+{
+    struct Win w;
+    w.prev             = 0;
+    w.next             = 0;
+    w.frame.curses_win = 0;
+    w.title            = title;
+    w.frame.size.x     = 20;
+    w.frame.size.y     = wmeta->pad.size.y - 1;
+    w.data             = data;
+    w.draw             = func;
+    return w;
+}
+
+
+
+extern void append_win(struct WinMeta * wmeta, struct Win * w)
+{
+    if (0 != wmeta->chain_start)
+    {
+        w->prev = wmeta->chain_end;
+        wmeta->chain_end->next = w;
+    }
     else
-      mvwaddch(frame->curses_win, pos, q, symbol); }
-  free(scrolldsc); }
-
-extern void draw_all_wins (struct WinMeta * wmeta) {
-// Draw pad with all windows and their borders, plus scrolling hints.
-  erase();
-  wnoutrefresh(wmeta->screen);
-  werase(wmeta->pad.curses_win);
-  if (wmeta->chain_start) {
-    uint16_t n_wins = 1, i;
-    struct Win * win_p = wmeta->chain_start;
-    while (0 != win_p->next) {
-      win_p = win_p->next;
-      n_wins++; }
-    struct Corners * all_corners = malloc(sizeof(struct Corners) * n_wins);
-    draw_wins (wmeta->chain_start);
-    draw_wins_borders (wmeta->chain_start, wmeta->active, all_corners, 0);
-    for (i = 0; i < n_wins; i++) {
-      mvwaddch(wmeta->pad.curses_win, all_corners[i].tl.y, all_corners[i].tl.x, '+');
-      mvwaddch(wmeta->pad.curses_win, all_corners[i].tr.y, all_corners[i].tr.x, '+');
-      mvwaddch(wmeta->pad.curses_win, all_corners[i].bl.y, all_corners[i].bl.x, '+');
-      mvwaddch(wmeta->pad.curses_win, all_corners[i].br.y, all_corners[i].br.x, '+'); }
-    free(all_corners);
-    if (wmeta->pad_offset > 0)
-      draw_scroll_hint(&wmeta->pad, wmeta->pad_offset, wmeta->pad_offset + 1, '<');
-    if (wmeta->pad_offset + wmeta->pad.size.x < getmaxx(wmeta->pad.curses_win) - 1)
-      draw_scroll_hint(&wmeta->pad, wmeta->pad_offset + wmeta->pad.size.x - 1,
-                       getmaxx(wmeta->pad.curses_win) - (wmeta->pad_offset + wmeta->pad.size.x), '>');
-    pnoutrefresh(wmeta->pad.curses_win, 0, wmeta->pad_offset, 0, 0, wmeta->pad.size.y, wmeta->pad.size.x-1); }
-  doupdate(); }
-
-extern void resize_active_win (struct WinMeta * wmeta, struct yx_uint16 size) {
-// Grow or shrink currently active window. Correct its geometry and that of its followers.
-  if (0 != wmeta->active && size.x > 0 && size.y > 0 && size.y < wmeta->pad.size.y) {
-    wmeta->active->frame.size = size;
-    update_wins(wmeta, wmeta->chain_start); } }
-
-extern void cycle_active_win (struct WinMeta * wmeta, char dir) {
-// Cycle active window selection forwards (dir = 'n') or backwards.
-  if (0 != wmeta->active) {
-    if ('n' == dir) {
-      if (wmeta->active->next != 0)
-        wmeta->active = wmeta->active->next;
-      else
-        wmeta->active = wmeta->chain_start; }
-    else {
-      if (wmeta->active->prev != 0)
-        wmeta->active = wmeta->active->prev;
-      else
-        wmeta->active = wmeta->chain_end; } } }
-
-extern void shift_active_win (struct WinMeta * wmeta, char dir) {
-// Move active window forward/backward in window chain. If jumping beyond start/end, move to other chain end.
-  if (0 != wmeta->active && wmeta->chain_start != wmeta->chain_end && (dir == 'f' || dir == 'b')) {
-    struct Win * w_shift = wmeta->active, * w_p, * w_p_next;
-    char wrap = 0;
-    if ((dir == 'f' && w_shift == wmeta->chain_end) || (dir == 'b' && w_shift == wmeta->chain_start))
-      wrap = 1;
-    uint16_t i, i_max;
-    for (i_max = 1, w_p = wmeta->chain_start; w_p != wmeta->chain_end; i_max++)
-      w_p = w_p->next;
-    struct Win ** wins = malloc(i_max * sizeof(struct Win *));
-    for (i = 0, w_p = wmeta->chain_start; i < i_max; i++) {
-      w_p_next = w_p->next;
-      suspend_win(wmeta, w_p);
-      wins[i] = w_p;
-      w_p = w_p_next; }
-    if (wrap)
-      if (dir == 'f') {
-        append_win(wmeta, w_shift);
-        for (i = 0; i < i_max - 1; i++)
-          append_win(wmeta, wins[i]); }
-      else {
-        for (i = 1; i < i_max; i++)
-          append_win(wmeta, wins[i]);
-        append_win(wmeta, w_shift); }
+    {
+        wmeta->active = w;
+        wmeta->chain_start = w;
+    }
+    wmeta->chain_end = w;
+    update_wins(wmeta, w);
+}
+
+
+
+extern void suspend_win(struct WinMeta * wmeta, struct Win * w)
+{
+    destroy_win(w);
+
+    if (wmeta->chain_start != w)
+    {
+        w->prev->next = w->next;
+    }
     else
-      for (i = 0; i < i_max; i++)
-        if ((dir == 'f' && w_shift == wins[i]) || (dir == 'b' && w_shift == wins[i+1])) {
-          append_win(wmeta, wins[i+1]);
-          append_win(wmeta, wins[i]);
-          i++; }
+    {
+        wmeta->chain_start = w->next;
+    }
+    char pad_refitted = 0;
+    if (wmeta->chain_end != w)
+    {
+        w->next->prev = w->prev;
+        if (wmeta->active == w)
+        {
+            wmeta->active = w->next;
+        }
+        update_wins(wmeta, w->next); /* Positioning of successor windows may  */
+        pad_refitted = 1;            /* be affected / need correction. Note   */
+    }                                /* that update_wins() already refits the */
+    else                             /* pad, voiding later need for that.     */
+    {
+        wmeta->chain_end = w->prev;
+        if (wmeta->active == w)
+        {
+            wmeta->active = w->prev;
+        }
+    }
+
+    w->prev = 0;
+    w->next = 0;
+
+    if (0 == pad_refitted)
+    {
+        refit_pad(wmeta);
+    }
+}
+
+
+
+extern void reset_pad_offset(struct WinMeta * wmeta, uint16_t new_offset)
+{
+    if (new_offset >= 0
+        && (new_offset < wmeta->pad_offset
+            || new_offset + wmeta->pad.size.x < getmaxx(wmeta->pad.curses_win)))
+    {
+        wmeta->pad_offset = new_offset;
+    }
+}
+
+
+
+extern void resize_active_win(struct WinMeta * wmeta, struct yx_uint16 size)
+{
+    if (0 != wmeta->active
+        && size.x > 0 && size.y > 0
+        && size.y < wmeta->pad.size.y)
+    {
+        wmeta->active->frame.size = size;
+        update_wins(wmeta, wmeta->chain_start);   /* Positioning of successor */
+    }                                             /* windows may be affected. */
+}
+
+
+
+extern void cycle_active_win(struct WinMeta * wmeta, char dir)
+{
+    if (0 != wmeta->active)
+    {
+        if ('n' == dir)
+        {
+            if (wmeta->active->next != 0)
+            {
+                wmeta->active = wmeta->active->next;
+            }
+            else
+            {
+                wmeta->active = wmeta->chain_start;
+            }
+        }
         else
-          append_win(wmeta, wins[i]);
-    free(wins);
-    wmeta->active = w_shift; } }
-
-extern void reset_pad_offset(struct WinMeta * wmeta, uint16_t new_offset) {
-// Apply new_offset to windows pad, if it proves to be sane.
-  if (new_offset >= 0
-      && (new_offset < wmeta->pad_offset || new_offset + wmeta->pad.size.x < getmaxx(wmeta->pad.curses_win)))
-    wmeta->pad_offset = new_offset; }
+        {
+            if (wmeta->active->prev != 0)
+            {
+                wmeta->active = wmeta->active->prev;
+            }
+            else
+            {
+                wmeta->active = wmeta->chain_end;
+            }
+        }
+    }
+}
+
+
+
+extern void shift_active_win(struct WinMeta * wmeta, char dir)
+{
+    if (0 != wmeta->active                        /* No shifting with less    */
+        && wmeta->chain_start != wmeta->chain_end /* than one window visible. */
+        && (dir == 'f' || dir == 'b'))
+    {
+        struct Win * w_shift = wmeta->active, * w_p, * w_p_next;
+
+        /* Check if shifting will lead to wrapping. */
+        char wrap = 0;
+        if (   (dir == 'f' && w_shift == wmeta->chain_end)
+            || (dir == 'b' && w_shift == wmeta->chain_start))
+        {
+            wrap = 1;
+        }
+
+        /* Suspend all visible windows. */
+        uint16_t i, i_max;
+        for (i_max = 1, w_p = wmeta->chain_start;
+             w_p != wmeta->chain_end;
+             i_max++)
+        {
+            w_p = w_p->next;
+        }
+        struct Win ** wins = malloc(i_max * sizeof(struct Win *));
+        for (i = 0, w_p = wmeta->chain_start; i < i_max; i++)
+        {
+            w_p_next = w_p->next;
+            suspend_win(wmeta, w_p);
+            wins[i] = w_p;
+            w_p = w_p_next;
+        }
+
+        /* Re-append all previously visible windows in the new order. */
+        if (wrap)
+        {
+            if (dir == 'f')
+            {
+                append_win(wmeta, w_shift);
+                for (i = 0; i < i_max - 1; i++)
+                {
+                    append_win(wmeta, wins[i]);
+                }
+            }
+            else
+            {
+                for (i = 1; i < i_max; i++)
+                {
+                    append_win(wmeta, wins[i]);
+                }
+                append_win(wmeta, w_shift);
+            }
+        }
+        else
+        {
+            for (i = 0; i < i_max; i++)
+            {
+                if (   (dir == 'f' && w_shift == wins[i])
+                    || (dir == 'b' && w_shift == wins[i+1]))
+                {
+                    append_win(wmeta, wins[i+1]);
+                    append_win(wmeta, wins[i]);
+                    i++;
+                }
+                else
+                {
+                    append_win(wmeta, wins[i]);
+                }
+            }
+        }
+        free(wins);
+
+        wmeta->active = w_shift;      /* TODO: Is this necessary? If so, why? */
+    }
+}
+
+
+
+extern void draw_all_wins(struct WinMeta * wmeta)
+{
+    /* Empty everything before filling it a-new. */
+    erase();
+    wnoutrefresh(wmeta->screen);
+    werase(wmeta->pad.curses_win);
+    if (wmeta->chain_start)
+    {
+
+        /* Only draw the windows' *contents* first. */
+        draw_wins (wmeta->chain_start);
+
+        /* Draw windows' borders. Lines first, then line crossings / corners. */
+        uint16_t n_wins = 1, i;
+        struct Win * win_p = wmeta->chain_start;
+        while (0 != win_p->next)
+        {
+            win_p = win_p->next;
+            n_wins++;
+        }
+        struct Corners * all_corners = malloc(sizeof(struct Corners) * n_wins);
+        draw_wins_borders (wmeta->chain_start, wmeta->active, all_corners, 0);
+        for (i = 0; i < n_wins; i++)
+        {
+            mvwaddch(wmeta->pad.curses_win,
+                     all_corners[i].tl.y, all_corners[i].tl.x, '+');
+            mvwaddch(wmeta->pad.curses_win,
+                     all_corners[i].tr.y, all_corners[i].tr.x, '+');
+            mvwaddch(wmeta->pad.curses_win,
+                     all_corners[i].bl.y, all_corners[i].bl.x, '+');
+            mvwaddch(wmeta->pad.curses_win,
+                     all_corners[i].br.y, all_corners[i].br.x, '+');
+        }
+        free(all_corners);
+
+        /* Draw virtual screen scroll hints. */
+        if (wmeta->pad_offset > 0)
+        {
+            draw_scroll_hint(&wmeta->pad,
+                             wmeta->pad_offset, wmeta->pad_offset + 1, '<');
+        }
+        if (wmeta->pad_offset + wmeta->pad.size.x
+            < getmaxx(wmeta->pad.curses_win) - 1)
+        {
+            draw_scroll_hint(&wmeta->pad,
+                             wmeta->pad_offset + wmeta->pad.size.x - 1,
+                             getmaxx(wmeta->pad.curses_win)
+                             - (wmeta->pad_offset + wmeta->pad.size.x), '>');
+        }
+
+        /* Write virtual screen segment to be shown on physical screen into */
+        /* ncurses screen buffer. */
+        pnoutrefresh(wmeta->pad.curses_win, 0, wmeta->pad_offset, 0, 0,
+                     wmeta->pad.size.y, wmeta->pad.size.x-1);
+    }
+
+    /* Only at the end write accumulated changes to the physical screen. */
+    doupdate();
+}
+
+
+
+extern void draw_scroll_hint(struct Frame * frame, uint16_t pos, uint32_t dist,
+                             char dir)
+{
+    /* Decide on alignment (vertical/horizontal?), thereby scroll hint text. */
+    char * more = "more";
+    char * unit_cols = "columns";
+    char * unit_rows = "lines";
+    uint16_t dsc_space = frame->size.x;
+    char * unit = unit_rows;
+    if ('<' == dir || '>' == dir)
+    {
+        dsc_space = frame->size.y;
+        unit = unit_cols;
+    }
+    char * scrolldsc = malloc((4 * sizeof(char)) + strlen(more) + strlen(unit)
+                              + 10);  /* 10 = uint32 max strlen */
+    sprintf(scrolldsc, " %d %s %s ", dist, more, unit);
+
+    /* Decide on offset of the description text inside the scroll hint line. */
+    char offset = 1, q;
+    if (dsc_space > strlen(scrolldsc) + 1)
+    {
+        offset = (dsc_space - strlen(scrolldsc)) / 2;
+    }
+
+    /* Draw scroll hint line as dir symbols bracketing description text. */
+    chtype symbol;
+    for (q = 0; q < dsc_space; q++)
+    {
+        if (q >= offset && q < strlen(scrolldsc) + offset)
+        {
+            symbol = scrolldsc[q - offset] | A_REVERSE;
+        }
+        else
+        {
+            symbol = dir | A_REVERSE;
+        }
+        if ('<' == dir || '>' == dir)
+        {
+            mvwaddch(frame->curses_win, q, pos, symbol);
+        }
+        else
+        {
+            mvwaddch(frame->curses_win, pos, q, symbol);
+        }
+    }
+
+    free(scrolldsc);
+}
diff --git a/src/windows.h b/src/windows.h
index 7714c6c..03d44b6 100644
--- a/src/windows.h
+++ b/src/windows.h
@@ -1,40 +1,169 @@
+/* windows.h
+ *
+ * A tiled window manager for the terminal.
+ *
+ * It provides a virtual screen that can be scrolled horizontally and may
+ * contain any number of windows that can be appeared, disappeared, resized and
+ * (somewhat) moved around. They have borders and a title bar and are positioned
+ * (in a bizarre fashion, see below) automatically.
+ *
+ * Windows can be almost any width (number has to fit into 16 bits); the virtual
+ * screen grows with them as needed -- but only horizontally. Their height is
+ * limited by the height of the terminal screen.
+ *
+ * Positioning of windows can only indirectly be influenced: by resizing them,
+ * and by shifting their relative position inside the (currently invisible)
+ * chain that the window manager treats their plurality as. The first window
+ * goes into the upper left corner of the virtual screen. Further visible
+ * windows are fitted left-aligned below their (chain-wise) closest predecessor
+ * that thrones over enough space to fit them in; failing that, they are placed
+ * to the right of the window with the rightmost border.
+ *
+ * TODO: Think up a more intuitive window positioning algorithm or at least make
+ * the chain that windows are positioned by visible.
+ *
+ * TODO: Ensure there are only windows as many / as big as fit into the maximum
+ * size of the virtual screen.
+ */
+
 #ifndef WINDOWS_H
 #define WINDOWS_H
 
-#include <stdint.h>
-#include <ncurses.h>
-#include "yx_uint16.h"
-
-struct Frame {
-  WINDOW * curses_win;
-  struct yx_uint16 size; };
-
-struct WinMeta {
-  WINDOW * screen;
-  uint16_t pad_offset;
-  struct Frame pad;
-  struct Win * chain_start;
-  struct Win * chain_end;
-  struct Win * active; };
-
-struct Win {
-  struct Win * prev;
-  struct Win * next;
-  struct yx_uint16 start;
-  struct Frame frame;
-  char * title;
-  void (* draw) (struct Win *);
-  void * data; };
-
-extern struct WinMeta init_win_meta (WINDOW *);
-extern struct Win init_win (struct WinMeta *, char *, void *, void *);
-extern void append_win (struct WinMeta *, struct Win *);
-extern void suspend_win (struct WinMeta *, struct Win *);
-extern void draw_scroll_hint (struct Frame *, uint16_t, uint32_t, char);
-extern void draw_all_wins (struct WinMeta *);
-extern void resize_active_win (struct WinMeta *, struct yx_uint16);
-extern void cycle_active_win (struct WinMeta *, char);
-extern void shift_active_win (struct WinMeta *, char);
-extern void reset_pad_offset (struct WinMeta *, uint16_t);
+
+
+#include <stdint.h>    /* for uint16_t, uint32_t */
+#include <ncurses.h>   /* for the WINDOW typedef */
+#include "yx_uint16.h" /* for yx_uint16 coordinates */
+
+
+/* Individual windows consist of potential (real if window is visible) ncurses
+ * WINDOWs wrapped inside Frame structs (that keep a window's designated size
+ * even when it is invisible) wrapped inside metadata-rich Win structs. Win
+ * structs are chained into a linked list of all the windows visible on the
+ * virtual screen and also contain pointers to what content is to be drawn
+ * inside the window, and by use of what method.
+ */
+
+struct Frame
+{
+    WINDOW * curses_win;
+    struct yx_uint16 size;        /* designated size of curses_win */
+};
+
+struct Win
+{
+    struct Win * prev;            /* prev=next=0 if Win is outside the chain */
+    struct Win * next;
+    struct yx_uint16 start;       /* upper left corner (of WINDOW or border?) */
+    struct Frame frame;
+    char * title;                 /* title to be shown on window border top */
+    void (* draw) (struct Win *); /* function to draw window content ("data") */
+    void * data;                  /* content to be drawn; draw() knows how */
+};
+
+
+
+/* The window manager's parent struct WinMeta provides the virtual screen and a
+ * representation of the terminal screen. It also anchors start and end of the
+ * windows chain.
+ */
+struct WinMeta
+{
+    WINDOW * screen;          /* terminal screen */
+    uint16_t pad_offset;      /* number of cells view is moved to the right */
+    struct Frame pad;         /* virtual screen */
+    struct Win * chain_start; /* first Win, whose .prev shall point to 0 */
+    struct Win * chain_end;   /* last Win, whose .next shall point to 0 */
+    struct Win * active;      /* window highlighted/selected for manipulation */
+};
+
+
+
+/* Create on the terminal "screen" an empty WinMeta whose virtual screen at the
+ * beginning is sized just like the terminal screen. Note that emptiness is
+ * marked by WinMeta.chain_start=0. Other struct values are also initialized 0.
+ *
+ * TODO: Why is an *empty* virtual screen's size that of the terminal screen?
+ */
+extern struct WinMeta init_win_meta(WINDOW * screen);
+
+
+
+/* Create a window below inside "wmeta" titled "title" and appointing "func"()
+ * to interpret and draw the content stored at "data" if the window is visible.
+ *
+ * The start size for the Frame will be a width of 20 cells and a height one
+ * less than the height of the virtual screen (so as to fit the title bar on top
+ * of the window). Other values will be initialized to 0. The window will stay
+ * invisible until appended to the chain of visible windows via append_win().
+ *
+ * TODO: Why a default start width instead of passing a start width?
+ */
+extern struct Win init_win(struct WinMeta * wmeta, char * title,
+                           void * data, void * func);
+
+
+
+/* Append/suspend window "w" to/from chain of visible windows in "wmeta".
+ * Appended windows will become active. Suspended active windows will move the
+ * active window selection to their successor in the window chain or, failing
+ * that, their predecessor; if no window remains, none will be active.
+ */
+extern void append_win(struct WinMeta * wmeta, struct Win * w);
+extern void suspend_win(struct WinMeta * wmeta, struct Win * w);
+
+
+
+/* Apply scrolling offset "new_offset" to virtual screen if it is sane, i.e.
+ * it's equal/greater zero and does not push the view (further) beyond the
+ * virtual screen's border. If the view is already beyond the virtual screen's
+ * border due to it having shrunk after suspension of windows, only allow view
+ * movement leftwards.
+ */
+extern void reset_pad_offset(struct WinMeta * wmeta, uint16_t new_offset);
+
+
+
+/* Apply new size "size" to the active window, but only if it provides for at
+ * least one cell width/height and is in height at least one cell smaller than
+ * the screen's vertical height (to provide space for the title bar).
+ */
+extern void resize_active_win(struct WinMeta * wmeta, struct yx_uint16 size);
+
+
+
+/* Cycle active window selection forwards (set dir="n") or backwards. Wrap
+ * around in the windows chain if start / end of it is met.
+ */
+extern void cycle_active_win(struct WinMeta * wmeta, char dir);
+
+
+
+/* Move active window forwards (set dir="f") or backwards (set dir="b"). Wrap
+ * around in the window chain if start / end of it is met.
+ */
+extern void shift_active_win(struct WinMeta * wmeta, char dir);
+
+
+
+/* Draw virtual screen including all windows. Also add scroll hints (a line
+ * stating that there is more to see on scrolling further into a certain
+ * direction) for where the edges of the terminal screen hit non-edges of and
+ * inside the virtual screen. Then update the terminal screen.
+ */
+extern void draw_all_wins(struct WinMeta * wmeta);
+
+
+
+/* Draw scroll hint (a line stating that there is more to see on scrolling
+ * further into a certain direction) into "frame" at position "pos" (describing
+ * a column or a row dependent on "dir" being *either* "<"/">" *or* something
+ * else). It will consist of a line of "dir" symbols bracketing a descriptive
+ * text stating the number of rows/columns further available beyond the hint.
+ */
+extern void draw_scroll_hint(struct Frame * frame, uint16_t pos, uint32_t dist,
+                             char dir);
+
+
 
 #endif