NAME

       notcurses_reel - high-level widget for hierarchical data

SYNOPSIS

       #include <notcurses/notcurses.h>

              #define NCREEL_OPTION_INFINITESCROLL 0x0001
              #define NCREEL_OPTION_CIRCULAR       0x0002

              struct ncreel;
              struct ncplane;
              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;

       struct ncreel* ncreel_create(struct ncplane* nc, const ncreel_options* popts);

       struct ncplane* ncreel_plane(struct ncreel* nr);

       typedef int (tabletcb)(struct nctablet t, bool cliptop);

       struct  nctablet*  ncreel_add(struct  ncreel* nr, struct nctablet* after, struct nctablet*
       before, tabletcb cb, void* opaque);

       int ncreel_tabletcount(const struct ncreel* nr);

       int ncreel_del(struct ncreel* nr, struct nctablet* t);

       int ncreel_redraw(struct ncreel* nr);

       struct nctablet* ncreel_focused(struct ncreel* nr);

       struct nctablet* ncreel_next(struct ncreel* nr);

       struct nctablet* ncreel_prev(struct ncreel* nr);

       bool ncreel_offer_input(struct ncreel* nr, const ncinput* ni);

       void ncreel_destroy(struct ncreel* nr);

       void* nctablet_userptr(struct nctablet* t);

       struct ncplane* nctablet_plane(struct nctablet* t);

DESCRIPTION

       An ncreel is a widget for display and manipulation of hierarchical data, intended to  make
       effective use of the display area while supporting keyboards, mice, and haptic interfaces.
       A series of nctablets are ordered on a virtual cylinder; the tablets can grow  and  shrink
       freely.   Moving among the tablets "spins" the cylinder.  ncreels support optional borders
       around the reel and/or tablets.

       ncreel_redraw arranges the tablets, invoking the tabletcb 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  ncplane.   The tablet will be grown or shrunk as
       necessary to reflect this return value.

       Unless the reel is devoid of tablets, there is always a "focused" tablet (the first tablet
       added  to  an  empty reel becomes focused).  The focused tablet can change via ncreel_next
       and ncreel_prev.  If ncreel_del is called on the focused tablet, and at  least  one  other
       tablet remains, some tablet receives the focus.

       Calling  functions  which change the reel, including ncreel_next, ncreel_prev, ncreel_del,
       and ncreel_add, implicitly calls ncreel_redraw.  This behavior must not be relied upon, as
       it is likely to go away.

   LAYOUT
       When  the  user  invokes  ncreel_redraw,  Notcurses  can't assume it knows the size of any
       tablets--one or more might have changed since the last draw.  Only after a  callback  does
       ncreel_redraw know how many rows a tablet will occupy.

       A  redraw  operation starts with the focused tablet.  Its callback is invoked with a plane
       as large as the reel, i.e.  the  focused  tablet  can  occupy  the  entire  reel,  to  the
       exclusion  of  any  other  tablets.   The  focused  tablet  will  be kept where it was, if
       possible; growth might force it to move.  There is now one tablet locked into  place,  and
       zero, one, or two areas of empty space.  Tablets are successively lain out in these spaces
       until the reel is filled.

       In general, if the reel is not full, tablets will be drawn towards the top, but this ought
       not be relied on.

   THE TABLET CALLBACK
       The tablet callback (of type tabletcb) is called with an ncplane and a bool.  The callback
       function ought not rely on the absolute position of the plane, as it might be moved.   The
       bool indicates whether the plane ought be filled in from the bottom, or from the top (this
       is only meaningful if the plane is  insufficiently  large  to  contain  all  the  tablet's
       available  data).   The  callback ought not resize the plane (it will be resized following
       return).  The callback must return the number of rows used (it is perfectly valid  to  use
       zero rows), or a negative number if there was an error.

       Returning more rows than the plane has available is an error.

RETURN VALUES

       ncreel_focused,  ncreel_prev,  and  ncreel_next  all  return the focused tablet, unless no
       tablets exist, in which case they return NULL.

       ncreel_add returns the newly-added nctablet.

BUGS

       I can't decide whether to require the user to explicitly  call  ncreel_redraw.   Doing  so
       means  changes  can  be  batched  up  without  a  redraw,  but  it  also makes things more
       complicated for both me and the user.

SEE ALSO

       notcurses(3), notcurses_input(3), notcurses_plane(3)

AUTHORS

       nick black <nickblack@linux.com>.

                                              v3.0.7                            notcurses_reel(3)