.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "notcurses_tree" "3" "v3.0.9" "" ""
.SH NAME
notcurses_tree - high-level hierarchical line-based data
.SH SYNOPSIS
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.EX
struct nctree;
struct ncplane;

typedef struct nctree_item {
  void* curry;
  struct nctree_item* subs;
  unsigned subcount;
} nctree_item;

typedef struct nctree_options {
  const nctree_item* items; // top-level nctree_item array
  unsigned count;           // size of |items|
  int (*nctreecb)(struct ncplane*, void*, int); // item callback
  int indentcols;           // columns to indent per hierarchy
  uint64_t flags;           // bitfield of NCTREE_OPTION_*
} nctree_options;
.EE
.PP
\f[B]struct nctree* nctree_create(struct ncplane* \f[R]\f[I]n\f[R]\f[B],
const nctree_options* \f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* nctree_plane(struct nctree*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int nctree_redraw(struct nctree* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]bool nctree_offer_input(struct nctree* \f[R]\f[I]n\f[R]\f[B], const
ncinput* \f[R]\f[I]ni\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctree_focused(struct nctree* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctree_next(struct nctree* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctree_prev(struct nctree* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctree_goto(struct nctree* \f[R]\f[I]n\f[R]\f[B], const int*
\f[R]\f[I]path\f[R]\f[B], int* \f[R]\f[I]failpath\f[R]\f[B]);\f[R]
.PP
\f[B]int nctree_add(struct nctree* \f[R]\f[I]n\f[R]\f[B], const
unsigned* \f[R]\f[I]path\f[R]\f[B], const nctree_item*
\f[R]\f[I]add\f[R]\f[B]);\f[R]
.PP
\f[B]int nctree_del(struct nctree* \f[R]\f[I]n\f[R]\f[B], const
unsigned* \f[R]\f[I]path\f[R]\f[B]);\f[R]
.PP
\f[B]void nctree_destroy(struct nctree* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.SH DESCRIPTION
\f[B]nctree\f[R]s organize hierarchical items, and allow them to be
browsed.
Each item can have arbitrary subitems.
Items can be collapsed and expanded.
The display supports scrolling and searching.
.PP
An \f[B]nctree\f[R] cannot be empty.
\f[B]count\f[R] must be non-zero, and \f[B]items\f[R] must not be
\f[B]NULL\f[R].
The callback function \f[B]nctreecb\f[R] must also be
non-\f[B]NULL\f[R].
.PP
The callback function \f[B]nctreecb\f[R] 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 \f[B]ncplane\f[R] argument will be
\f[B]NULL\f[R].
If the item is newly visible, the \f[B]ncplane\f[R] argument will be an
empty plane.
If the item was already visible, the \f[B]ncplane\f[R] 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 \f[B]ncplane_resize\f[R].
If the plane is expanded in the callback, it will be shrunk back down by
the widget.
The \f[B]int\f[R] 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.
.PP
\f[B]nctree_goto\f[R], \f[B]nctree_add\f[R], and \f[B]nctree_del\f[R]
all use the concept of a \f[B]\f[BI]path\f[B]\f[R].
A path is an array of \f[B]unsigned\f[R] values, terminated by
\f[B]UINT_MAX\f[R], with each successive value indexing into the
hierarchy thus far.
The root node of the \f[B]nctree\f[R] thus always has a 2-element path
of [0, \f[B]UINT_MAX\f[R]].
.SH RETURN VALUES
\f[B]nctree_create\f[R] returns \f[B]NULL\f[R] for invalid options.
This includes a \f[B]NULL\f[R] \f[B]items\f[R] or \f[B]nctreecb\f[R]
field, or a zero \f[B]count\f[R] field.
.PP
\f[B]nctree_next\f[R] and \f[B]nctree_prev\f[R] both return the
\f[B]curry\f[R] pointer from the newly-focused item.
\f[B]nctree_focused\f[R] returns the \f[B]curry\f[R] pointer from the
already-focused item.
.PP
\f[B]nctree_goto\f[R] returns the \f[B]curry\f[R] pointer from the
newly-focused item.
If \f[B]\f[BI]path\f[B]\f[R] is invalid, the first invalid hierarchy
level is written to \f[B]\f[BI]failpath\f[B]\f[R], and \f[B]NULL\f[R] is
returned.
If \f[B]\f[BI]path\f[B]\f[R] is valid, the value -1 is written to
\f[B]\f[BI]failpath\f[B]\f[R].
Since it is possible for a \f[B]\f[BI]curry\f[B]\f[R] pointer to be
\f[B]NULL\f[R], one should check \f[B]\f[BI]failpath\f[B]\f[R] before
assuming the operation failed.
.PP
\f[B]nctree_add\f[R] and \f[B]nctree_del\f[R] both return -1 for an
invalid \f[B]\f[BI]path\f[B]\f[R], and 0 otherwise.
.SH NOTES
\f[B]nctree\f[R] shares many properties with \f[B]notcurses_reel\f[R].
Unlike the latter, \f[B]nctree\f[R]s support arbitrary hierarchical
levels.
.PP
\f[B]nctree\f[R] used to only handle static data, but
\f[B]nctree_add\f[R] and \f[B]nctree_del\f[R] were added in Notcurses
3.0.1.
.SH SEE ALSO
\f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]notcurses_reel(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.