.\" 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_multiselector" "3" "v3.0.7" "" ""
.hy
.SH NAME
.PP
notcurses_multiselector - 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 ncmultiselector;

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

typedef struct ncmultiselector_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 ncmselector_item* items; // initial items, statuses
  // 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 NCMULTISELECTOR_OPTION_*
} ncmultiselector_options;
\f[R]
.fi
.PP
\f[B]struct ncmultiselector* ncmultiselector_create(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncmultiselector_options*
\f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmultiselector_selected(bool* \f[R]\f[I]selected\f[R]\f[B],
unsigned \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncmultiselector_plane(struct ncmultiselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncmultiselector_offer_input(struct ncmultiselector*
\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 ncmultiselector_destroy(struct ncmultiselector*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
A multiselector widget presents a list of items (possibly more than can
be displayed at once).
It facilitates a choice of zero, one, or multiple items from the list.
Items can be selected and deselected before a final choice is made.
.SH NOTES
.PP
The \f[B]ncplane\f[R] \f[B]n\f[R] provided to
\f[B]ncmultiselector_create\f[R] must not be \f[B]NULL\f[R].
It will be freely resized by the new \f[B]ncmultiselector\f[R].
.PP
\f[B]ncmultiselector_selected\f[R] returns the index of the option
currently highlighted.
It stores to the \f[B]n\f[R]-ary bitmap pointed to by \f[B]selected\f[R]
based on the currently-selected options.
.PP
\f[B]ncmultiselector_plane\f[R] will return the \f[B]ncplane\f[R] on
which the widget is drawn.
.PP
Input should be run through \f[B]ncmultiselector_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]ncmultiselector_destroy\f[R] destroys the backing
\f[B]ncplane\f[R], as does \f[B]ncmultiselector_create\f[R] in the event
of any error.
.SH RETURN VALUES
.PP
\f[B]ncmultiselector_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]ncmultiselector_selected\f[R] returns -1 if there are no items, or
if \f[B]n\f[R] is not equal to the number of items.
It otherwise returns the index of the currently highlighted option, and
writes a bitmap to \f[B]selected\f[R] based off the selected items.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_plane(3)\f[R] \f[B]notcurses_selector(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.