1notcurses_selector(3)                                    notcurses_selector(3)
2
3
4

NAME

6       notcurses_selector - high level widget for selecting from a set
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct ncplane;
12              struct notcurses;
13              struct ncselector;
14
15              struct ncselector_item {
16                const char* option;
17                const char* desc;
18              };
19
20              typedef struct ncselector_options {
21                const char* title; // title may be NULL, inhibiting riser
22                const char* secondary; // secondary may be NULL
23                const char* footer; // footer may be NULL
24                struct ncselector_item* items; // initial items and descriptions
25                // default item (selected at start)
26                unsigned defidx;
27                // maximum number of options to display at once
28                unsigned maxdisplay;
29                // exhaustive styling options
30                uint64_t opchannels;   // option channels
31                uint64_t descchannels; // description channels
32                uint64_t titlechannels;// title channels
33                uint64_t footchannels; // secondary and footer channels
34                uint64_t boxchannels;  // border channels
35                uint64_t flags;        // bitfield over NCSELECTOR_OPTION_*
36              } ncselector_options;
37
38       struct  ncselector* ncselector_create(struct ncplane* n, const ncselec‐
39       tor_options* opts);
40
41       int ncselector_additem(struct  ncselector*  n,  const  struct  ncselec‐
42       tor_item* item);
43
44       int ncselector_delitem(struct ncselector* n, const char* item);
45
46       const char* ncselector_selected(const struct ncselector* n);
47
48       struct ncplane* ncselector_plane(struct ncselector* n);
49
50       const char* ncselector_previtem(struct ncselector* n);
51
52       const char* ncselector_nextitem(struct ncselector* n);
53
54       bool ncselector_offer_input(struct ncselector* n, const ncinput* nc);
55
56       void ncselector_destroy(struct ncselector* n, char item);**
57

DESCRIPTION

59       A  selector  widget presents a list of items (possibly more than can be
60       displayed at once).  It facilitates a choice of zero or one  item  from
61       the list.
62

NOTES

64       The  ncplane n provided to ncselector_create must not be NULL.  It will
65       be freely resized by the new ncselector, and thus cannot be  the  stan‐
66       dard plane.  ncselector_selected returns the currently-selected option.
67       ncselector_additem and ncselector_delitem allow items to be  added  and
68       deleted  on  the  fly (a static set of items can all be provided in the
69       ncselector_create call).  The backing plane will be resized  as  neces‐
70       sary for item changes.
71
72       ncselector_nextitem  and  ncselector_previtem select the next (down) or
73       previous (up) option, scrolling if necessary.  It is safe to call these
74       functions even if no options are present.
75
76       ncselector_plane will return the ncplane on which the widget is drawn.
77
78       While  the  ncselector can be driven entirely by client code, input can
79       be run through ncselector_offer_input to take advantage of common  con‐
80       trols.   It  will  handle the up and down arrows, along with PageUp and
81       PageDown.  If the mouse is enabled, the  mouse  scrollwheel  and  mouse
82       clicks on the scroll arrows will be handled.
83
84       ncselector_destroy  destroys  the  backing  ncplane,  as  does ncselec‐
85       tor_create in the event of any error.
86

RETURN VALUES

88       ncselector_create returns NULL on an error, in which  case  the  passed
89       ncplane is destroyed.
90
91       ncselector_selected  returns  a reference to the option part of the se‐
92       lected ncselector_item.  If there are no items, it returns NULL.
93
94       ncselector_previtem and ncselector_nextitem return  references  to  the
95       option  part  of  the  newly-selected ncselector_item.  If there are no
96       items, they return NULL.
97

SEE ALSO

99       notcurses(3), notcurses_input(3), notcurses_multiselector(3),  notcurs‐
100       es_plane(3), notcurses_stdplane(3)
101

AUTHORS

103       nick black <nickblack@linux.com>.
104
105
106
107                                    v3.0.8               notcurses_selector(3)
Impressum