1notcurses_reel(3)                                            notcurses_reel(3)
2
3
4

NAME

6       notcurses_reel - high-level widget for hierarchical data
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              #define NCREEL_OPTION_INFINITESCROLL 0x0001
12              #define NCREEL_OPTION_CIRCULAR       0x0002
13
14              struct ncreel;
15              struct ncplane;
16              struct nctablet;
17
18              typedef struct ncreel_options {
19                // notcurses can draw a border around the ncreel, and also
20                // around the component tablets. inhibit borders by setting all
21                // valid bits in the masks. partially inhibit borders by setting
22                // individual bits in the masks. the appropriate attr and pair
23                // values will be used to style the borders. focused and
24                // non-focused tablets can have different styles. you can instead
25                // draw your own borders, or forgo borders entirely.
26                unsigned bordermask; // bitfield; 1s will not be drawn
27                uint64_t borderchan; // attributes used for ncreel border
28                unsigned tabletmask; // bitfield for tablet borders
29                uint64_t tabletchan; // tablet border styling channel
30                uint64_t focusedchan;// focused tablet border styling channel
31                uint64_t flags;      // bitfield over NCREEL_OPTION_*
32              } ncreel_options;
33
34       struct  ncreel* ncreel_create(struct ncplane* nc, const ncreel_options*
35       popts);
36
37       struct ncplane* ncreel_plane(struct ncreel* nr);
38
39       typedef int (tabletcb)(struct nctablet t, bool cliptop);
40
41       struct nctablet* ncreel_add(struct ncreel* nr, struct nctablet*  after,
42       struct nctablet* before, tabletcb cb, void* opaque);
43
44       int ncreel_tabletcount(const struct ncreel* nr);
45
46       int ncreel_del(struct ncreel* nr, struct nctablet* t);
47
48       int ncreel_redraw(struct ncreel* nr);
49
50       struct nctablet* ncreel_focused(struct ncreel* nr);
51
52       struct nctablet* ncreel_next(struct ncreel* nr);
53
54       struct nctablet* ncreel_prev(struct ncreel* nr);
55
56       bool ncreel_offer_input(struct ncreel* nr, const ncinput* ni);
57
58       void ncreel_destroy(struct ncreel* nr);
59
60       void* nctablet_userptr(struct nctablet* t);
61
62       struct ncplane* nctablet_plane(struct nctablet* t);
63

DESCRIPTION

65       An  ncreel is a widget for display and manipulation of hierarchical da‐
66       ta, intended to make effective use of the display area while supporting
67       keyboards,  mice, and haptic interfaces.  A series of nctablets are or‐
68       dered on a virtual cylinder; the tablets can grow  and  shrink  freely.
69       Moving among the tablets "spins" the cylinder.  ncreels support option‐
70       al borders around the reel and/or tablets.
71
72       ncreel_redraw arranges the tablets, invoking the  tabletcb  defined  by
73       each.   It  will  invoke  the callbacks of only those tablets currently
74       visible.  This function ought be called  whenever  the  data  within  a
75       tablet  need  be  refreshed.   The return value of this callback is the
76       number of lines drawn into the ncplane.  The tablet will  be  grown  or
77       shrunk as necessary to reflect this return value.
78
79       Unless  the  reel  is  devoid  of  tablets, there is always a "focused"
80       tablet (the first tablet added to an empty reel becomes focused).   The
81       focused   tablet  can  change  via  ncreel_next  and  ncreel_prev.   If
82       ncreel_del is called on the focused tablet,  and  at  least  one  other
83       tablet remains, some tablet receives the focus.
84
85       Calling   functions  which  change  the  reel,  including  ncreel_next,
86       ncreel_prev, ncreel_del, and ncreel_add,  implicitly  calls  ncreel_re‐
87       draw.   This  behavior  must  not be relied upon, as it is likely to go
88       away.
89
90   LAYOUT
91       When the user invokes ncreel_redraw, Notcurses can't  assume  it  knows
92       the  size of any tablets--one or more might have changed since the last
93       draw.  Only after a callback does ncreel_redraw know how  many  rows  a
94       tablet will occupy.
95
96       A redraw operation starts with the focused tablet.  Its callback is in‐
97       voked with a plane as large as the reel, i.e.  the focused  tablet  can
98       occupy the entire reel, to the exclusion of any other tablets.  The fo‐
99       cused tablet will be kept where it was, if possible; growth might force
100       it  to move.  There is now one tablet locked into place, and zero, one,
101       or two areas of empty space.  Tablets  are  successively  lain  out  in
102       these spaces until the reel is filled.
103
104       In  general, if the reel is not full, tablets will be drawn towards the
105       top, but this ought not be relied on.
106
107   THE TABLET CALLBACK
108       The tablet callback (of type tabletcb) is called with an ncplane and  a
109       bool.  The callback function ought not rely on the absolute position of
110       the plane, as it might be moved.  The bool indicates whether the  plane
111       ought be filled in from the bottom, or from the top (this is only mean‐
112       ingful if the plane is insufficiently large to contain all the tablet's
113       available  data).   The callback ought not resize the plane (it will be
114       resized following return).  The callback must return the number of rows
115       used  (it is perfectly valid to use zero rows), or a negative number if
116       there was an error.
117
118       Returning more rows than the plane has available is an error.
119

RETURN VALUES

121       ncreel_focused, ncreel_prev, and ncreel_next  all  return  the  focused
122       tablet, unless no tablets exist, in which case they return NULL.
123
124       ncreel_add returns the newly-added nctablet.
125

BUGS

127       I  can't  decide  whether  to  require  the  user  to  explicitly  call
128       ncreel_redraw.  Doing so means changes can be batched up without a  re‐
129       draw, but it also makes things more complicated for both me and the us‐
130       er.
131

SEE ALSO

133       notcurses(3), notcurses_input(3), notcurses_plane(3)
134

AUTHORS

136       nick black <nickblack@linux.com>.
137
138
139
140                                    v2.3.1                   notcurses_reel(3)
Impressum