.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "notcurses_selector" "3" "v3.0.7" "" ""
.hy
.SH NAME
.PP
notcurses_selector - high level widget for selecting from a set
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
struct ncplane;
struct notcurses;
struct ncselector;

struct ncselector_item {
  const char* option;
  const char* desc;
};

typedef struct ncselector_options {
  const char* title; // title may be NULL, inhibiting riser
  const char* secondary; // secondary may be NULL
  const char* footer; // footer may be NULL
  struct ncselector_item* items; // initial items and descriptions
  // default item (selected at start)
  unsigned defidx;
  // maximum number of options to display at once
  unsigned maxdisplay;
  // exhaustive styling options
  uint64_t opchannels;   // option channels
  uint64_t descchannels; // description channels
  uint64_t titlechannels;// title channels
  uint64_t footchannels; // secondary and footer channels
  uint64_t boxchannels;  // border channels
  uint64_t flags;        // bitfield over NCSELECTOR_OPTION_*
} ncselector_options;
\f[R]
.fi
.PP
\f[B]struct ncselector* ncselector_create(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncselector_options*
\f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncselector_additem(struct ncselector* \f[R]\f[I]n\f[R]\f[B],
const struct ncselector_item* \f[R]\f[I]item\f[R]\f[B]);\f[R]
.PP
\f[B]int ncselector_delitem(struct ncselector* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]item\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncselector_selected(const struct ncselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncselector_plane(struct ncselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncselector_previtem(struct ncselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncselector_nextitem(struct ncselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncselector_offer_input(struct ncselector*
\f[R]\f[I]n\f[R]\f[B], const ncinput* \f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]void ncselector_destroy(struct ncselector* \f[R]\f[I]n\f[R]\f[B],
char\f[R] \f[B]\f[BI]item\f[B]\f[R]);**
.SH DESCRIPTION
.PP
A selector widget presents a list of items (possibly more than can be
displayed at once).
It facilitates a choice of zero or one item from the list.
.SH NOTES
.PP
The \f[B]ncplane\f[R] \f[B]n\f[R] provided to
\f[B]ncselector_create\f[R] must not be \f[B]NULL\f[R].
It will be freely resized by the new \f[B]ncselector\f[R], and thus
cannot be the standard plane.
\f[B]ncselector_selected\f[R] returns the currently-selected option.
\f[B]ncselector_additem\f[R] and \f[B]ncselector_delitem\f[R] allow
items to be added and deleted on the fly (a static set of items can all
be provided in the \f[B]ncselector_create\f[R] call).
The backing plane will be resized as necessary for item changes.
.PP
\f[B]ncselector_nextitem\f[R] and \f[B]ncselector_previtem\f[R] select
the next (down) or previous (up) option, scrolling if necessary.
It is safe to call these functions even if no options are present.
.PP
\f[B]ncselector_plane\f[R] will return the \f[B]ncplane\f[R] on which
the widget is drawn.
.PP
While the \f[B]ncselector\f[R] can be driven entirely by client code,
input can be run through \f[B]ncselector_offer_input\f[R] to take
advantage of common controls.
It will handle the up and down arrows, along with PageUp and PageDown.
If the mouse is enabled, the mouse scrollwheel and mouse clicks on the
scroll arrows will be handled.
.PP
\f[B]ncselector_destroy\f[R] destroys the backing \f[B]ncplane\f[R], as
does \f[B]ncselector_create\f[R] in the event of any error.
.SH RETURN VALUES
.PP
\f[B]ncselector_create\f[R] returns \f[B]NULL\f[R] on an error, in which
case the passed \f[B]ncplane\f[R] is destroyed.
.PP
\f[B]ncselector_selected\f[R] returns a reference to the
\f[B]option\f[R] part of the selected \f[B]ncselector_item\f[R].
If there are no items, it returns \f[B]NULL\f[R].
.PP
\f[B]ncselector_previtem\f[R] and \f[B]ncselector_nextitem\f[R] return
references to the \f[B]option\f[R] part of the newly-selected
\f[B]ncselector_item\f[R].
If there are no items, they return \f[B]NULL\f[R].
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_multiselector(3)\f[R], \f[B]notcurses_plane(3)\f[R],
\f[B]notcurses_stdplane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.