1notcurses_tabbed(3) notcurses_tabbed(3)
2
6 notcurses_tabbed – tabbed interface widget
7
9 #include <notcurses/notcurses.h>
10 #define NCTABBED_OPTION_BOTTOM 0x0001
12 struct nctabbed;
14 struct ncplane;
15 struct nctab;
16 typedef struct nctabbed_options {
18 uint64_t selchan; // channel for the selected tab header
19 uint64_t hdrchan; // channel for unselected tab headers
20 uint64_t sepchan; // channel for the tab separator
21 const char* separator; // separator string (copied by nctabbed_create())
22 uint64_t flags; // bitmask of NCTABBED_OPTION_*
23 } nctabbed_options;
24 typedef void (*tabcb)(struct nctab* t, struct ncplane* ncp, void* userptr);
26 struct nctabbed* nctabbed_create(struct ncplane* ncp, const
28 nctabbed_options* opts);
29 void nctabbed_destroy(struct nctabbed* nt);
31 void nctabbed_redraw(struct nctabbed* nt);
33 void nctabbed_ensure_selected_header_visible(struct nctabbed* nt);
35 struct nctab* nctabbed_selected(struct nctabbed* nt);
37 struct nctab* nctabbed_leftmost(struct nctabbed* nt);
39 int nctabbed_tabcount(struct nctabbed* nt);
41 struct ncplane* nctabbed_plane(struct nctabbed* nt);
43 struct ncplane* nctabbed_content_plane(struct nctabbed* nt);
45 tabcb nctab_cb(struct nctab* t);
47 const char* nctab_name(struct nctab* t);
49 int nctab_name_width(struct nctab* t);
51 void* nctab_userptr(struct nctab* t);
53 struct nctab* nctab_next(struct nctab* t);
55 struct nctab* nctab_prev(struct nctab* t);
57 struct nctab* nctabbed_add(struct nctabbed* nt, struct nctab* after,
59 struct nctab* before, tabcb tcb, const char* name, void* opaque**);
60 int nctabbed_del(struct nctabbed* nt, struct nctab* t);
62 int nctab_move(struct nctabbed* nt, struct nctab* t, struct nctab* af‐
64 ter, struct nctab* before);
65 void nctab_move_right(struct nctabbed* nt, struct nctab* t);
67 void nctab_move_left(struct nctabbed* nt, struct nctab* t);
69 void nctabbed_rotate(struct nctabbed* nt, int amt);
71 struct nctab* nctabbed_next(struct nctabbed* nt);
73 struct nctab* nctabbed_prev(struct nctabbed* nt);
75 struct nctab* nctabbed_select(struct nctabbed* nt, struct nctab* t);
77 void nctabbed_channels(struct nctabbed* nt, uint64_t* RESTRICT hdrchan,
79 uint64_t* RESTRICT selchan, uint64_t* RESTRICT sepchan);
80 uint64_t nctabbed_hdrchan(struct nctabbed* nt);
82 uint64_t nctabbed_selchan(struct nctabbed* nt);
84 uint64_t nctabbed_sepchan(struct nctabbed* nt);
86 const char* nctabbed_separator(struct nctabbed* nt);
88 int nctabbed_separator_width(struct nctabbed* nt);
90 void nctabbed_set_hdrchan(struct nctabbed* nt, uint64_t chan);
92 void nctabbed_set_selchan(struct nctabbed* nt, uint64_t chan);
94 void nctabbed_set_sepchan(struct nctabbed* nt, uint64_t chan);
96 tabcb nctab_set_cb(struct nctab* t, tabcb newcb);
98 int nctab_set_name(struct nctab* t, const char* newname);
100 void* nctab_set_userptr(struct nctab* t, void* newopaque);
102 int nctabbed_set_separator(struct nctabbed* nt, const char* separator);
104
106 An nctabbed is a widget with one area for data display and a bar with
107 names of tabs. Unless there are no tabs, exactly one tab is "select‐
108 ed", and exactly one tab is "leftmost". The selected tab is the one
109 that controls the tab content plane. The leftmost tab is the one of
110 which the header is visible furthest to the left. Any tab can be moved
111 to and from anywhere in the list. The tabs can be "rotated", which re‐
112 ally means the leftmost tab gets shifted. The widget is drawn only
113 when nctabbed_redraw or ntabbed_create are called.
114 LAYOUT
116 The widget has a tab list either on the top or the bottom, 1 row thick.
117 The tab list contains tab headers (i.e. their names), separated with
118 the separator specified in nctabbed_create or nctabbed_set_separator.
119 The channels for the selected tab's header, other tab headers and the
120 separator can be set independently of each other. The tab separator
121 can be 0-length, or NULL, in which case there is no visible separator
122 between tab headers. The selected tab can be made sure to be visible
123 when drawn (by changing the leftmost tab) by calling the very long-
124 named nctabbed_ensure_selected_header_visible. The rest of the widget
125 is an ncplane housing the selected tab content. (if any)
126 THE TAB CALLBACK
128 The tab callback (of type tabcb) takes a tab, the tab content plane,
129 and the opaque pointer given to nctabbed_add or nctabbed_set_userptr.
130 It is called when the tab content is supposed to be drawn, that is when
131 the whole widget is redrawn. It should draw the tab content and possi‐
132 bly make other actions, but it should not assume anything about the
133 current state of the tab content plane, nor should it modify the wid‐
134 get's or the tab's state.
135
137 nctabbed_create returns the newly created widget, or NULL when the wid‐
138 get failed to be created. This destroys the ncplane given to it even
139 if it fails.
140 nctabbed_selected and nctabbed_leftmost return the selected and left‐
142 most tabs, respectively. If there are no tabs, these return NULL.
143 nctab_name returns the tab's name. This is not a copy, and it should
145 not be stored, since it is freed when the tab's name is changed or the
146 tab is deleted.
147 nctabbed_next, nctabbed_prev and nctabbed_select return the newly se‐
149 lected tab.
150 nctabbed_separator returns the tab separator. This is not a copy, and
152 it should not be stored, since it is freed when the separator is
153 changed or the widget is deleted.
154 Functions returning int return -1 on failure.
156
158 notcurses(3), notcurses_channels(3), notcurses_plane(3)
159
161 v2.4.9.
162 notcurses_tabbed(3)