add nctree movement api #1164

doc/man/man3/notcurses_reel.3.md

@@ -15,6 +15,7 @@ notcurses_reel - high-level widget for hierarchical data
 #define NCREEL_OPTION_CIRCULAR       0x0002
 
 struct ncreel;
+struct ncplane;
 struct nctablet;
 
 typedef struct ncreel_options {

doc/man/man3/notcurses_tree.3.md

@@ -11,6 +11,9 @@ notcurses_tree - high-level hierarchical line-based data
 **#include <notcurses/notcurses.h>**
 
 ```c
+struct nctree;
+struct ncplane;
+
 typedef struct nctree_item {
   void* curry;
   struct nctree_item* subs;
@@ -21,7 +24,7 @@ typedef struct nctree_options {
   const nctree_item* items; // top-level nctree_item array
   unsigned count;           // size of |items|
   uint64_t bchannels;       // base channels
-  int (*nctreecb)(struct ncplane*, void*); // item callback function
+  int (*nctreecb)(struct ncplane*, void*, int); // item callback
   uint64_t flags;           // bitfield of NCTREE_OPTION_*
 } nctree_options;
 ```
@@ -34,6 +37,14 @@ typedef struct nctree_options {
 
 **bool nctree_offer_input(struct nctree* ***n***, const ncinput* ***ni***);**
 
+**void* nctree_focused(struct nctree* ***n***);**
+
+**void* nctree_next(struct nctree* ***n***);**
+
+**void* nctree_prev(struct nctree* ***n***);**
+
+**void* nctree_goto(struct nctree* ***n***, const int* ***spec***, size_t ***specdepth***, int* ***failspec***);**
+
 **void nctree_destroy(struct nctree* ***n***);**
 
 # DESCRIPTION
@@ -43,8 +54,32 @@ Each item can have arbitrary subitems. Items can be collapsed and expanded.
 The display supports scrolling and searching. Items cannot be added or removed,
 however; they must be provided in their entirety at creation time.
 
+An **nctree** cannot be empty. **count** must be non-zero, and **items** must
+not be **NULL**. The callback function **nctreecb** must also be non-**NULL**.
+
+The callback function **nctreecb** is called on tree items when the tree is
+redrawn. It will be called on each visible item, and any item which has become
+hidden. If the item is newly hidden, the **ncplane** argument will be **NULL**.
+If the item is newly visible, the **ncplane** argument will be an empty plane.
+If the item was already visible, the **ncplane** argument will be the same
+plane passed before. If the item has not changed since the last time the
+callback was invoked, there is no need to change the plane, and the callback
+can return immediately. Otherwise, the plane ought be drawn by the callback.
+Any unused rows ought be trimmed away using **ncplane_resize**. If the plane
+is expanded in the callback, it will be shrunk back down by the widget. The
+**int** parameter indicates distance from the focused item. If the parameter
+is negative, the item is before the focused item; a positive parameter implies
+that the item follows the focused item; the focused item itself is passed zero.
+
 # RETURN VALUES
 
+**nctree_create** returns **NULL** for invalid options. This includes a **NULL**
+**items** or **nctreecb** field, or a zero **count** field.
+
+**nctree_next** and **nctree_prev** both return the **curry** pointer from the
+newly-focused item. **nctree_focused** returns the **curry** pointer from the
+already-focused item.
+
 # NOTES
 
 **nctree** shares many properties with **notcurses_reel**. Unlike the latter,

include/notcurses/notcurses.h

@@ -823,7 +823,7 @@ typedef enum {
 // that locale is "C" or "POSIX", it will call setlocale(LC_ALL, "") to set
 // the locale according to the LANG environment variable. Ideally, this will
 // result in UTF8 being enabled, even if the client app didn't call
-// setlocale() itself. Unless you're certain that you're invoking setlocale() 
+// setlocale() itself. Unless you're certain that you're invoking setlocale()
 // prior to notcurses_init(), you should not set this bit. Even if you are
 // invoking setlocale(), this behavior shouldn't be an issue unless you're
 // doing something weird (setting a locale not based on LANG).
@@ -3012,7 +3012,7 @@ typedef struct nctree_options {
   const nctree_item* items; // top-level nctree_item array
   unsigned count;           // size of |items|
   uint64_t bchannels;       // base channels
-  int (*nctreecb)(struct ncplane*, void*); // item callback function
+  int (*nctreecb)(struct ncplane*, void*, int); // item callback function
   uint64_t flags;           // bitfield of NCTREE_OPTION_*
 } nctree_options;
 
@@ -3040,20 +3040,22 @@ API int nctree_redraw(struct nctree* n)
 API bool nctree_offer_input(struct nctree* n, const ncinput* ni)
   __attribute__ ((nonnull (1, 2)));
 
-  /*
 // Return the focused item, if any items are present. This is not a copy;
 // be careful to use it only for the duration of a critical section.
-API struct nctablet* nctree_focused(struct nctree* n)
-  __attribute__ ((nonnull (1)));
+API void* nctree_focused(struct nctree* n) __attribute__ ((nonnull (1)));
 
-// Change focus to the next item, if one exists
-API struct nctablet* nctree_next(struct nctree* n)
-  __attribute__ ((nonnull (1)));
+// Change focus to the next item.
+API void* nctree_next(struct nctree* n) __attribute__ ((nonnull (1)));
 
-// Change focus to the previous item, if one exists
-API struct nctablet* nctree_prev(struct nctree* n)
-  __attribute__ ((nonnull (1)));
-  */
+// Change focus to the previous item.
+API void* nctree_prev(struct nctree* n) __attribute__ ((nonnull (1)));
+
+// Go to the item specified by the array |spec| having |specdepth| elements. If
+// the spec is invalid, NULL is returned, and the depth of the first invalid
+// spec is written to *|failspec|. Otherwise, |specdepth| is written to
+// *|failspec|, and the curry is returned (|failspec| is necessary because the
+// curry could itself be NULL).
+API void* nctree_goto(struct nctree* n, const int* spec, size_t specdepth, int* failspec);
 
 // Destroy the nctree.
 API void nctree_destroy(struct nctree* n);

src/lib/tree.c

@@ -8,7 +8,7 @@ typedef struct nctree_int_item {
 } nctree_int_item;
 
 typedef struct nctree {
-  int (*cbfxn)(ncplane*, void*);
+  int (*cbfxn)(ncplane*, void*, int);
   nctree_int_item* items;
   unsigned itemcount;
   uint64_t bchannels;

src/tests/tree.cpp

@@ -1,9 +1,9 @@
 #include "main.h"
 #include <iostream>
 
-int treecb(struct ncplane* n, void* curry){
-  // FIXME do something better
-  fprintf(stderr, "n: %p curry: %p", n, curry);
+int treecb(struct ncplane* n, void* curry, int pos){
+  // FIXME draw to the ncplane
+  fprintf(stderr, "n: %p curry: %p pos: %d", n, curry, pos);
   return 0;
 }