.\" Automatically generated by Pandoc 3.1.8 .\" .TH "notcurses_reel" "3" "v3.0.9" "" "" .SH NAME notcurses_reel - high-level widget for hierarchical data .SH SYNOPSIS \f[B]#include \f[R] .IP .EX #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; .EE .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]bool ncreel_offer_input(struct ncreel* \f[R]\f[I]nr\f[R]\f[B], const ncinput* \f[R]\f[I]ni\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 An \f[B]ncreel\f[R] 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 \f[B]nctablet\f[R]s are ordered on a virtual cylinder; the tablets can grow and shrink freely. Moving among the tablets \[dq]spins\[dq] 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 \[dq]focused\[dq] 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. .PP Calling functions which change the reel, including \f[B]ncreel_next\f[R], \f[B]ncreel_prev\f[R], \f[B]ncreel_del\f[R], and \f[B]ncreel_add\f[R], implicitly calls \f[B]ncreel_redraw\f[R]. This behavior \f[B]must not be relied upon\f[R], as it is likely to go away. .SS LAYOUT When the user invokes \f[B]ncreel_redraw\f[R], Notcurses can\[aq]t assume it knows the size of any tablets--one or more might have changed since the last draw. Only after a callback does \f[B]ncreel_redraw\f[R] know how many rows a tablet will occupy. .PP 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. .PP In general, if the reel is not full, tablets will be drawn towards the top, but this ought not be relied on. .SS THE TABLET CALLBACK The tablet callback (of type \f[B]tabletcb\f[R]) is called with an \f[B]ncplane\f[R] and a \f[B]bool\f[R]. The callback function ought not rely on the absolute position of the plane, as it might be moved. The \f[B]bool\f[R] 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\[aq]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. .PP Returning more rows than the plane has available is an error. .SH RETURN VALUES \f[B]ncreel_focused\f[R], \f[B]ncreel_prev\f[R], and \f[B]ncreel_next\f[R] all return the focused tablet, unless no tablets exist, in which case they return \f[B]NULL\f[R]. .PP \f[B]ncreel_add\f[R] returns the newly-added \f[B]nctablet\f[R]. .SH BUGS I can\[aq]t decide whether to require the user to explicitly call \f[B]ncreel_redraw\f[R]. Doing so means changes can be batched up without a redraw, but it also makes things more complicated for both me and the user. .SH SEE ALSO \f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R], \f[B]notcurses_plane(3)\f[R] .SH AUTHORS nick black .