ncplane_reparent: new stacks #1078

doc/man/man3/notcurses_plane.3.md

@@ -197,9 +197,10 @@ another, x and y coordinates are relative to the plane to which it is bound,
 and if this latter plane moves, all its bound planes move along with it. When a
 plane is destroyed, all planes bound to it (directly or transitively) are
 destroyed. **ncplane_reparent** detaches the plane **n** from any plane to
-which it is bound, and binds it to **newparent** if **newparent** is not
-**NULL**. All planes bound to **n** move along with it during a reparenting
-operation.
+which it is bound, and binds it to **newparent**. The standard plane cannot be
+reparented. If **newparent** is **NULL**, the plane becomes the root plane of a
+new, unrendered stack. All planes bound to **n** move along with it during a
+reparenting operation.
 
 **ncplane_destroy** destroys a particular ncplane, after which it must not be
 used again. **notcurses_drop_planes** destroys all ncplanes other than the

doc/man/man3/notcurses_render.3.md

@@ -28,8 +28,10 @@ render (see notcurses_stats(3)), and screen geometry is refreshed (similarly to
 **notcurses_refresh**) *following* the render.
 
 While **notcurses_render** is called, you **must not call any other functions
-on the same notcurses context**, with the one exception of **notcurses_getc**
-(and its input-related helpers; see **notcurses_input(3)**.).
+modifying the same notcurses context**, with the exceptions of:
+
+* **notcurses_getc** (and its input-related helpers; see **notcurses_input(3)**)
+* Functions operating only on off-stack **ncplane**s
 
 **notcurses_render_to_buffer** performs the render and raster processes of
 **notcurses_render**, but does not write the resulting buffer to the

src/lib/notcurses.c

@@ -2047,11 +2047,18 @@ int ncplane_resize_realign(ncplane* n){
   return ncplane_move_yx(n, ncplane_y(n), xpos);
 }
 
+// The standard plane cannot be reparented; we return NULL in that case.
+// If provided a NULL |newparent|, we are moving |n| to its own stack. If |n|
+// is already root of its own stack in this case, we return NULL. If |n| is
+// already bound to |newparent|, this is a no-op, and we return |n|.
 ncplane* ncplane_reparent(ncplane* n, ncplane* newparent){
   if(n == n->nc->stdplane){
     return NULL; // can't reparent standard plane
   }
-  if(newparent == NULL){
+  if(n->boundto == n && newparent == NULL){
+    return NULL; // can't make new stack out of a stack's root
+  }
+  if(newparent == NULL){ // FIXME make a new stack
     newparent = n->nc->stdplane;
   }
   if(n->boundto == newparent){