notcurses_multiselector(3)

📦
version 3.0.17 · 8 versions
, in alpine 3.24, ubuntu resolute, ubuntu stonking

💅 NAME 💅

okay so bestie, welcome to notcurses_multiselector(3) from the notcurses manual ✨ — this page is all about the high level widget for selecting from a set. that's it, that's the whole vibe. multiple things, you pick some, iconic. 🎀

🦋 SYNOPSIS 🦋

like, here's the whole cast of characters, copy-pasted exactly because we do NOT mess with the code, no cap:

#include <notcurses/notcurses.h>

       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;

struct ncmultiselector* ncmultiselector_create(struct ncplane* n, const
ncmultiselector_options* opts);

int ncmultiselector_selected(bool* selected, unsigned n);

struct ncplane* ncmultiselector_plane(struct ncmultiselector* n);

bool ncmultiselector_offer_input(struct ncmultiselector* n, const
ncinput* nc);

void ncmultiselector_destroy(struct ncmultiselector* n);

yes bestie, ncmselector_item really is spelled like that (it's not a typo on my end, promise, that's literally what the header says 🙈) and yes, the flags bitfield is documented as being over NCMULTISELECTOR_OPTION_* 💫.

🌸 DESCRIPTION 🌸

so a multiselector widget is literally just a list of items — and when we say list, we mean it might have more items than can fit on screen at once, no biggie 🫶. it's here to help you make a choice of zero, one, or multiple items from that list. zero! that's allowed! the bar is on the floor and honestly good for it 💜.

the main character energy here is that you can select and deselect items as many times as your little heart wants before the final choice gets made. toggle toggle toggle, go off queen 👑.

✨ NOTES ✨

  • the ncplane n you hand to ncmultiselector_create must not be NULL — fr fr, that's a hard requirement. and just so you know, the new ncmultiselector will freely resize it. it's not being rude, it's just living its truth 💅.
  • ncmultiselector_selected returns the index of the option that's currently highlighted, and it stores into the n-ary bitmap pointed to by selected based on the currently-selected options 🎀.
  • ncmultiselector_plane will return the ncplane that the widget is drawn on. that's the canvas, bestie 🖼️.
  • input should be run through ncmultiselector_offer_input so you get the common controls for free — it handles the up and down arrows, plus PageUp and PageDown ⬆️⬇️. and if the mouse is enabled, the mouse scrollwheel and mouse clicks on the scroll arrows will be handled too 🖱️✨.
  • ncmultiselector_destroy destroys the backing ncplane — and ngl, so does ncmultiselector_create if any error happens along the way 💀.
  • as no flags exist, the flags option ought always be 0. that's the whole assignment, it's giving minimalist 🌈.

🔥 RETURN VALUES 🔥

  • ncmultiselector_create returns NULL on an error, and in that case the ncplane you passed in is destroyed 😭.
  • ncmultiselector_selected returns -1 if there are no items, or if n is not equal to the number of items. otherwise it returns the index of the currently highlighted option, and writes a bitmap to selected based off the selected items 💖.

🧚 SEE ALSO 🧚

go read these next, i'm obsessed:

👑 AUTHORS 👑

nick black — nickblack@linux.com ⭐

okay that's the whole page bestie, you ate it up, periodt 💅🫶. this lil love letter shipped as v3.0.17 of notcurses_multiselector(3) — go forth and select multiple things, the multiselector believes in you 🌈💖🍓

📦 where this page comes from