.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_tabbed" "3" "" "" ""
.hy
.SH NAME
.PP
notcurses_tabbed \[en] tabbed interface widget
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
#define NCTABBED_OPTION_BOTTOM 0x0001

struct nctabbed;
struct ncplane;
struct nctab;

typedef struct nctabbed_options {
  uint64_t selchan; // channel for the selected tab header
  uint64_t hdrchan; // channel for unselected tab headers
  uint64_t sepchan; // channel for the tab separator
  const char* separator; // separator string (copied by nctabbed_create())
  uint64_t flags;   // bitmask of NCTABBED_OPTION_*
} nctabbed_options;

typedef void (*tabcb)(struct nctab* t, struct ncplane* ncp, void* userptr);
\f[R]
.fi
.PP
\f[B]struct nctabbed* nctabbed_create(struct ncplane*
\f[R]\f[I]ncp\f[R]\f[B], const nctabbed_options*
\f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_destroy(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_redraw(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_ensure_selected_header_visible(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_selected(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_leftmost(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]int nctabbed_tabcount(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* nctabbed_plane(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* nctabbed_content_plane(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]tabcb nctab_cb(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]const char* nctab_name(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]int nctab_name_width(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctab_userptr(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctab_next(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctab_prev(struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_add(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
struct nctab* \f[R]\f[I]after\f[R]\f[B], struct nctab*
\f[R]\f[I]before\f[R]\f[B], tabcb \f[R]\f[I]tcb\f[R]\f[B], const char*
\f[R]\f[I]name\f[R]\f[B], void* \f[R]\f[I]opaque\f[R]**);
.PP
\f[B]int nctabbed_del(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B], struct
nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]int nctab_move(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B], struct
nctab* \f[R]\f[I]t\f[R]\f[B], struct nctab* \f[R]\f[I]after\f[R]\f[B],
struct nctab* \f[R]\f[I]before\f[R]\f[B]);\f[R]
.PP
\f[B]void nctab_move_right(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]void nctab_move_left(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_rotate(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B], int
\f[R]\f[I]amt\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_next(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_prev(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]struct nctab* nctabbed_select(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B], struct nctab* \f[R]\f[I]t\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_channels(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
uint64_t* RESTRICT \f[R]\f[I]hdrchan\f[R]\f[B], uint64_t* RESTRICT
\f[R]\f[I]selchan\f[R]\f[B], uint64_t* RESTRICT
\f[R]\f[I]sepchan\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t nctabbed_hdrchan(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t nctabbed_selchan(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]uint64_t nctabbed_sepchan(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]const char* nctabbed_separator(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]int nctabbed_separator_width(struct nctabbed*
\f[R]\f[I]nt\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_set_hdrchan(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
uint64_t \f[R]\f[I]chan\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_set_selchan(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
uint64_t \f[R]\f[I]chan\f[R]\f[B]);\f[R]
.PP
\f[B]void nctabbed_set_sepchan(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
uint64_t \f[R]\f[I]chan\f[R]\f[B]);\f[R]
.PP
\f[B]tabcb nctab_set_cb(struct nctab* \f[R]\f[I]t\f[R]\f[B], tabcb
\f[R]\f[I]newcb\f[R]\f[B]);\f[R]
.PP
\f[B]int nctab_set_name(struct nctab* \f[R]\f[I]t\f[R]\f[B], const char*
\f[R]\f[I]newname\f[R]\f[B]);\f[R]
.PP
\f[B]void* nctab_set_userptr(struct nctab* \f[R]\f[I]t\f[R]\f[B], void*
\f[R]\f[I]newopaque\f[R]\f[B]);\f[R]
.PP
\f[B]int nctabbed_set_separator(struct nctabbed* \f[R]\f[I]nt\f[R]\f[B],
const char* \f[R]\f[I]separator\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
An \f[B]nctabbed\f[R] is a widget with one area for data display and a
bar with names of tabs.
Unless there are no tabs, exactly one tab is \[dq]selected\[dq], and
exactly one tab is \[dq]leftmost\[dq].
The selected tab is the one that controls the tab content plane.
The leftmost tab is the one of which the header is visible furthest to
the left.
Any tab can be moved to and from anywhere in the list.
The tabs can be \[dq]rotated\[dq], which really means the leftmost tab
gets shifted.
The widget is drawn only when \f[B]nctabbed_redraw\f[R] or
\f[B]ntabbed_create\f[R] are called.
.SS LAYOUT
.PP
The widget has a tab list either on the top or the bottom, 1 row thick.
The tab list contains tab headers (i.e.
their names), separated with the separator specified in
\f[B]nctabbed_create\f[R] or \f[B]nctabbed_set_separator\f[R].
The channels for the selected tab\[aq]s header, other tab headers and
the separator can be set independently of each other.
The tab separator can be 0-length, or NULL, in which case there is no
visible separator between tab headers.
The selected tab can be made sure to be visible when drawn (by changing
the leftmost tab) by calling the very long-named
\f[B]nctabbed_ensure_selected_header_visible\f[R].
The rest of the widget is an \f[B]ncplane\f[R] housing the selected tab
content.
(if any)
.SS THE TAB CALLBACK
.PP
The tab callback (of type \f[B]tabcb\f[R]) takes a tab, the tab content
plane, and the opaque pointer given to \f[B]nctabbed_add\f[R] or
\f[B]nctabbed_set_userptr\f[R].
It is called when the tab content is supposed to be drawn, that is when
the whole widget is redrawn.
It should draw the tab content and possibly make other actions, but it
should not assume anything about the current state of the tab content
plane, nor should it modify the widget\[aq]s or the tab\[aq]s state.
.SH RETURN VALUES
.PP
\f[B]nctabbed_create\f[R] returns the newly created widget, or
\f[B]NULL\f[R] when the widget failed to be created.
This destroys the \f[B]ncplane\f[R] given to it even if it fails.
.PP
\f[B]nctabbed_selected\f[R] and \f[B]nctabbed_leftmost\f[R] return the
selected and leftmost tabs, respectively.
If there are no tabs, these return \f[B]NULL\f[R].
.PP
\f[B]nctab_name\f[R] returns the tab\[aq]s name.
This is not a copy, and it should not be stored, since it is freed when
the tab\[aq]s name is changed or the tab is deleted.
.PP
\f[B]nctabbed_next\f[R], \f[B]nctabbed_prev\f[R] and
\f[B]nctabbed_select\f[R] return the newly selected tab.
.PP
\f[B]nctabbed_separator\f[R] returns the tab separator.
This is not a copy, and it should not be stored, since it is freed when
the separator is changed or the widget is deleted.
.PP
Functions returning \f[B]int\f[R] return \f[B]-1\f[R] on failure.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_channels(3)\f[R],
\f[B]notcurses_plane(3)\f[R]
.SH AUTHORS
v3.0.0.