1notcurses_reel(3) notcurses_reel(3)
2
6 notcurses_reel - high-level widget for hierarchical data
7
9 #include <notcurses/notcurses.h>
10 #define NCREEL_OPTION_INFINITESCROLL 0x0001
12 #define NCREEL_OPTION_CIRCULAR 0x0002
13 struct ncreel;
15 struct ncplane;
16 struct nctablet;
17 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 struct ncreel* ncreel_create(struct ncplane* nc, const ncreel_options*
35 popts);
36 struct ncplane* ncreel_plane(struct ncreel* nr);
38 typedef int (tabletcb)(struct nctablet t, bool cliptop);
40 struct nctablet* ncreel_add(struct ncreel* nr, struct nctablet* after,
42 struct nctablet* before, tabletcb cb, void* opaque);
43 int ncreel_tabletcount(const struct ncreel* nr);
45 int ncreel_del(struct ncreel* nr, struct nctablet* t);
47 int ncreel_redraw(struct ncreel* nr);
49 struct nctablet* ncreel_focused(struct ncreel* nr);
51 struct nctablet* ncreel_next(struct ncreel* nr);
53 struct nctablet* ncreel_prev(struct ncreel* nr);
55 bool ncreel_offer_input(struct ncreel* nr, const ncinput* ni);
57 void ncreel_destroy(struct ncreel* nr);
59 void* nctablet_userptr(struct nctablet* t);
61 struct ncplane* nctablet_plane(struct nctablet* t);
63
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 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 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 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 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 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 In general, if the reel is not full, tablets will be drawn towards the
105 top, but this ought not be relied on.
106 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 Returning more rows than the plane has available is an error.
119
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 ncreel_add returns the newly-added nctablet.
125
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
133 notcurses(3), notcurses_input(3), notcurses_plane(3)
134
136 nick black <nickblack@linux.com>.
137 v2.3.1 notcurses_reel(3)