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                char* option;
17                char* desc;
18              };
19
20              typedef struct ncselector_options {
21                char* title; // title may be NULL, inhibiting riser
22                char* secondary; // secondary may be NULL
23                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

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

RETURN VALUES
83       ncselector_create  returns  NULL  on an error, in which case the passed
84       ncplane is destroyed.
85
86       ncselector_selected returns a reference to the option part of  the  se‐
87       lected ncselector_item.  If there are no items, it returns NULL.
88
89       ncselector_previtem  and  ncselector_nextitem  return references to the
90       option part of the newly-selected ncselector_item.   If  there  are  no
91       items, they return NULL.
92

SEE ALSO
94       notcurses(3),  notcurses_input(3),  notcurses_multiselector(3) notcurs‐
95       es_plane(3)
96

AUTHORS
98       nick black <nickblack@linux.com>.
99
100
101
102                                    v2.3.1               notcurses_selector(3)



        

    


            
        

        

            Impressum