.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_reel" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_reel - high-level widget for hierarchical data
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
#define NCREEL_OPTION_INFINITESCROLL 0x0001
#define NCREEL_OPTION_CIRCULAR       0x0002

struct ncreel;
struct nctablet;

typedef struct ncreel_options {
  // notcurses can draw a border around the ncreel, and also
  // around the component tablets. inhibit borders by setting all
  // valid bits in the masks. partially inhibit borders by setting
  // individual bits in the masks. the appropriate attr and pair
  // values will be used to style the borders. focused and
  // non-focused tablets can have different styles. you can instead
  // draw your own borders, or forgo borders entirely.
  unsigned bordermask; // bitfield; 1s will not be drawn
  uint64_t borderchan; // attributes used for ncreel border
  unsigned tabletmask; // bitfield for tablet borders
  uint64_t tabletchan; // tablet border styling channel
  uint64_t focusedchan;// focused tablet border styling channel
  uint64_t flags;      // bitfield over NCREEL_OPTION_*
} ncreel_options;
\f[R]
.fi
.PP
\f[B]struct ncreel* ncreel_create(struct ncplane*
\f[R]\f[I]nc\f[R]\f[B], const ncreel_options*
\f[R]\f[I]popts\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncreel_plane(struct ncreel*
\f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]typedef int (\f[BI]tabletcb)(struct nctablet\f[B]
\f[R]\f[I]t\f[R]\f[B], bool \f[R]\f[I]cliptop\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctablet* ncreel_add(struct ncreel* \f[R]\f[I]nr\f[R]\f[B],
struct nctablet* \f[R]\f[I]after\f[R]\f[B], struct nctablet*
\f[R]\f[I]before\f[R]\f[B], tabletcb \f[R]\f[I]cb\f[R]\f[B], void*
\f[R]\f[I]opaque\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreel_tabletcount(const struct ncreel*
\f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreel_del(struct ncreel* \f[R]\f[I]nr\f[R]\f[B], struct
nctablet* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreel_redraw(struct ncreel* \f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctablet* ncreel_focused(struct ncreel*
\f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctablet* ncreel_next(struct ncreel*
\f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctablet* ncreel_prev(struct ncreel*
\f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]void ncreel_destroy(struct ncreel* \f[R]\f[I]nr\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctablet_userptr(struct nctablet*
\f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* nctablet_plane(struct nctablet*
\f[R]\f[I]t\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
An \f[B]ncreel\f[R] is a widget for display and manipulation of
hierarchal data, intended to make effective use of the display area
while supporting keyboards, mice, and haptic interfaces.
A series of \f[B]nctablet\f[R]s are ordered on a virtual cylinder; the
tablets can grow and shrink freely, while moving among the tablets
\[lq]spins\[rq] the cylinder.
\f[B]ncreel\f[R]s support optional borders around the reel and/or
tablets.
.PP
\f[B]ncreel_redraw\f[R] arranges the tablets, invoking the
\f[B]tabletcb\f[R] defined by each.
It will invoke the callbacks of only those tablets currently visible.
This function ought be called whenever the data within a tablet need be
refreshed.
The return value of this callback is the number of lines drawn into the
\f[B]ncplane\f[R].
The tablet will be grown or shrunk as necessary to reflect this return
value.
.PP
Unless the reel is devoid of tablets, there is always a
\[lq]focused\[rq] tablet (the first tablet added to an empty reel
becomes focused).
The focused tablet can change via \f[B]ncreel_next\f[R] and
\f[B]ncreel_prev\f[R].
If \f[B]ncreel_del\f[R] is called on the focused tablet, and at least
one other tablet remains, some tablet receives the focus.
.SH RETURN VALUES
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_plane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.