From 7a698310b62de5df2f1cdd540e96a85dc8875189 Mon Sep 17 00:00:00 2001 From: nick black Date: Fri, 12 Feb 2021 00:19:17 -0500 Subject: [PATCH] ncinput is not opaque --- USAGE.md | 4 ++-- doc/man/man3/notcurses_input.3.md | 2 +- doc/man/man3/notcurses_menu.3.md | 11 +++++------ doc/man/man3/notcurses_multiselector.3.md | 3 +-- doc/man/man3/notcurses_reader.3.md | 3 +-- doc/man/man3/notcurses_reel.3.md | 3 +++ doc/man/man3/notcurses_selector.3.md | 3 +-- doc/man/man3/notcurses_tree.3.md | 5 +++++ include/notcurses/notcurses.h | 19 +++++++++---------- 9 files changed, 28 insertions(+), 25 deletions(-) diff --git a/USAGE.md b/USAGE.md index 2745c2b32..fe917035c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2188,7 +2188,7 @@ int ncreel_redraw(struct ncreel* nr); // * a mouse click on a tablet (focuses tablet) // * a mouse scrollwheel event (rolls reel) // * up, down, pgup, or pgdown (navigates among items) -bool ncreel_offer_input(struct ncreel* nr, const struct ncinput* ni); +bool ncreel_offer_input(struct ncreel* nr, const ncinput* ni); // Return the focused tablet, if any tablets are present. This is not a copy; // be careful to use it only for the duration of a critical section. @@ -2446,7 +2446,7 @@ struct ncplane* ncreader_plane(struct ncreader* n); // Offer the input to the ncreader. If it's relevant, this function returns // true, and the input ought not be processed further. Almost all inputs // are relevant to an ncreader, save synthesized ones. -bool ncreader_offer_input(struct ncreader* n, const struct ncinput* ni); +bool ncreader_offer_input(struct ncreader* n, const ncinput* ni); // return a nul-terminated heap copy of the current (UTF-8) contents. char* ncreader_contents(const struct ncreader* n); diff --git a/doc/man/man3/notcurses_input.3.md b/doc/man/man3/notcurses_input.3.md index 9bf4fee40..44d2c80c2 100644 --- a/doc/man/man3/notcurses_input.3.md +++ b/doc/man/man3/notcurses_input.3.md @@ -39,7 +39,7 @@ typedef struct ncinput { **int notcurses_inputready_fd(struct notcurses* ***n***);** -**static inline bool ncinput_equal_p(const struct ncinput* ***n1***, const struct ncinput* ***n2***);** +**static inline bool ncinput_equal_p(const ncinput* ***n1***, const ncinput* ***n2***);** **int notcurses_linesigs_disable(struct notcurses* ***n***);** diff --git a/doc/man/man3/notcurses_menu.3.md b/doc/man/man3/notcurses_menu.3.md index 39ed63611..e7fac076d 100644 --- a/doc/man/man3/notcurses_menu.3.md +++ b/doc/man/man3/notcurses_menu.3.md @@ -13,7 +13,6 @@ notcurses_menu - operations on menus ```c struct ncmenu; struct ncplane; -struct ncinput; struct notcurses; struct ncmenu_section { @@ -53,13 +52,13 @@ typedef struct ncmenu_options { **int ncmenu_item_set_status(struct ncmenu* ***n***, const char* ***section***, const char* ***item***, bool ***enabled***);** -**const char* ncmenu_selected(const struct ncmenu* ***n***, struct ncinput* ***ni***);** +**const char* ncmenu_selected(const struct ncmenu* ***n***, ncinput* ***ni***);** -**const char* ncmenu_mouse_selected(const struct ncmenu* ***n***, const struct ncinput* ***click***, struct ncinput* ***ni***);** +**const char* ncmenu_mouse_selected(const struct ncmenu* ***n***, const ncinput* ***click***, ncinput* ***ni***);** **struct ncplane* ncmenu_plane(struct ncmenu* ***n***);** -**bool ncmenu_offer_input(struct ncmenu* ***n***, const struct ncinput* ***nc***);** +**bool ncmenu_offer_input(struct ncmenu* ***n***, const ncinput* ***nc***);** **int ncmenu_destroy(struct ncmenu* ***n***);** @@ -80,7 +79,7 @@ the actively unrolled section. In either case, if there is a shortcut for the item and **ni** is not **NULL**, **ni** will be filled in with the shortcut. The menu can be driven either entirely by the application, via direct calls to -**ncmenu_previtem**, **ncmenu_prevsection**, and the like, or **struct ncinput** +**ncmenu_previtem**, **ncmenu_prevsection**, and the like, or **ncinput** objects can be handed to **ncmenu_offer_input**. In the latter case, the menu will largely manage itself. The application must handle item selection (usually via the Enter key and/or mouse click) itself, since the menu cannot arbitrarily @@ -97,7 +96,7 @@ are due to invalid parameters. **ncmenu_offer_input** returns **true** if the menu "consumed" the input, i.e. found it relevant and took an action. Otherwise, **false** is returned, and the -**struct ncinput** should be considered irrelevant to the menu. +**ncinput** should be considered irrelevant to the menu. # SEE ALSO diff --git a/doc/man/man3/notcurses_multiselector.3.md b/doc/man/man3/notcurses_multiselector.3.md index 4cbb86269..cb352e795 100644 --- a/doc/man/man3/notcurses_multiselector.3.md +++ b/doc/man/man3/notcurses_multiselector.3.md @@ -11,7 +11,6 @@ notcurses_multiselector - high level widget for selecting from a set **#include ** ```c -struct ncinput; struct ncplane; struct notcurses; struct ncmultiselector; @@ -47,7 +46,7 @@ typedef struct ncmultiselector_options { **struct ncplane* ncmultiselector_plane(struct ncmultiselector* ***n***);** -**bool ncmultiselector_offer_input(struct ncmultiselector* ***n***, const struct ncinput* ***nc***);** +**bool ncmultiselector_offer_input(struct ncmultiselector* ***n***, const ncinput* ***nc***);** **void ncmultiselector_destroy(struct ncmultiselector* ***n***);** diff --git a/doc/man/man3/notcurses_reader.3.md b/doc/man/man3/notcurses_reader.3.md index b3401b48f..06e15bd93 100644 --- a/doc/man/man3/notcurses_reader.3.md +++ b/doc/man/man3/notcurses_reader.3.md @@ -11,7 +11,6 @@ notcurses_reader - high level widget for collecting input **#include ** ```c -struct ncinput; struct ncplane; struct ncreader; struct notcurses; @@ -44,7 +43,7 @@ typedef struct ncreader_options { **int ncreader_write_egc(struct ncreader* ***n***, const char* ***egc***);** -**bool ncreader_offer_input(struct ncreader* ***n***, const struct ncinput* ***ni***);** +**bool ncreader_offer_input(struct ncreader* ***n***, const ncinput* ***ni***);** **char* ncreader_contents(const struct ncreader* ***n***);** diff --git a/doc/man/man3/notcurses_reel.3.md b/doc/man/man3/notcurses_reel.3.md index 3c7445df1..4cdb88e9c 100644 --- a/doc/man/man3/notcurses_reel.3.md +++ b/doc/man/man3/notcurses_reel.3.md @@ -54,6 +54,8 @@ typedef struct ncreel_options { **struct nctablet* ncreel_prev(struct ncreel* ***nr***);** +**bool ncreel_offer_input(struct ncreel* ***nr***, const ncinput* ***ni***);** + **void ncreel_destroy(struct ncreel* ***nr***);** **void* nctablet_userptr(struct nctablet* ***t***);** @@ -139,5 +141,6 @@ things more complicated for both me and the user. # SEE ALSO **notcurses(3)**, +**notcurses_input(3)**, **notcurses_plane(3)**, **notcurses_tree(3)** diff --git a/doc/man/man3/notcurses_selector.3.md b/doc/man/man3/notcurses_selector.3.md index 43a87b7b5..c75eb70c7 100644 --- a/doc/man/man3/notcurses_selector.3.md +++ b/doc/man/man3/notcurses_selector.3.md @@ -11,7 +11,6 @@ notcurses_selector - high level widget for selecting from a set **#include ** ```c -struct ncinput; struct ncplane; struct notcurses; struct ncselector; @@ -54,7 +53,7 @@ typedef struct ncselector_options { **const char* ncselector_nextitem(struct ncselector* ***n***);** -**bool ncselector_offer_input(struct ncselector* ***n***, const struct ncinput* ***nc***);** +**bool ncselector_offer_input(struct ncselector* ***n***, const ncinput* ***nc***);** **void ncselector_destroy(struct ncselector* ***n***, char\*\* ***item***);** diff --git a/doc/man/man3/notcurses_tree.3.md b/doc/man/man3/notcurses_tree.3.md index 0c71e6315..5a6b34dc3 100644 --- a/doc/man/man3/notcurses_tree.3.md +++ b/doc/man/man3/notcurses_tree.3.md @@ -12,6 +12,11 @@ notcurses_tree - high-level hierarchical line-based data # DESCRIPTION +**nctree**s organize static hierarchical items, and allow them to be browsed. +Each item can have arbitrary subitems. Items can be collapsed and expanded. +The display supports scrolling and searching. Items cannot be added or removed, +however; they must be provided in their entirety at creation time. + # RETURN VALUES # NOTES diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index d36edcd29..16ac59ffd 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -991,7 +991,7 @@ typedef struct ncinput { // compare two ncinput structs for data equality. we can't just use memcmp() // due to potential padding in the struct (especially wrt bools) and seqnum. static inline bool -ncinput_equal_p(const struct ncinput* n1, const struct ncinput* n2){ +ncinput_equal_p(const ncinput* n1, const ncinput* n2){ if(n1->id != n2->id){ return false; } @@ -2704,7 +2704,7 @@ API int ncreel_redraw(struct ncreel* nr) // * a mouse click on a tablet (focuses tablet) // * a mouse scrollwheel event (rolls reel) // * up, down, pgup, or pgdown (navigates among items) -API bool ncreel_offer_input(struct ncreel* nr, const struct ncinput* ni) +API bool ncreel_offer_input(struct ncreel* nr, const ncinput* ni) __attribute__ ((nonnull (1))); // Return the focused tablet, if any tablets are present. This is not a copy; @@ -2921,7 +2921,7 @@ API const char* ncselector_nextitem(struct ncselector* n); // * a mouse scrollwheel event // * a mouse click on the scrolling arrows // * up, down, pgup, or pgdown on an unrolled menu (navigates among items) -API bool ncselector_offer_input(struct ncselector* n, const struct ncinput* nc); +API bool ncselector_offer_input(struct ncselector* n, const ncinput* nc); // Destroy the ncselector. If 'item' is not NULL, the last selected option will // be strdup()ed and assigned to '*item' (and must be free()d by the caller). @@ -2987,7 +2987,7 @@ API struct ncplane* ncmultiselector_plane(struct ncmultiselector* n); // * a mouse scrollwheel event // * a mouse click on the scrolling arrows // * up, down, pgup, or pgdown on an unrolled menu (navigates among items) -API bool ncmultiselector_offer_input(struct ncmultiselector* n, const struct ncinput* nc); +API bool ncmultiselector_offer_input(struct ncmultiselector* n, const ncinput* nc); // Destroy the ncmultiselector. API void ncmultiselector_destroy(struct ncmultiselector* n); @@ -3038,7 +3038,7 @@ API int nctree_redraw(struct nctree* n) // * a mouse click on an item (focuses item) // * a mouse scrollwheel event (srolls tree) // * up, down, pgup, or pgdown (navigates among items) -API bool nctree_offer_input(struct nctree* n, const struct ncinput* ni) +API bool nctree_offer_input(struct nctree* n, const ncinput* ni) __attribute__ ((nonnull (1))); /* @@ -3117,15 +3117,14 @@ API int ncmenu_item_set_status(struct ncmenu* n, const char* section, // Return the selected item description, or NULL if no section is unrolled. If // 'ni' is not NULL, and the selected item has a shortcut, 'ni' will be filled // in with that shortcut--this can allow faster matching. -API const char* ncmenu_selected(const struct ncmenu* n, struct ncinput* ni); +API const char* ncmenu_selected(const struct ncmenu* n, ncinput* ni); // Return the item description corresponding to the mouse click 'click'. The // item must be on an actively unrolled section, and the click must be in the // area of a valid item. If 'ni' is not NULL, and the selected item has a // shortcut, 'ni' will be filled in with the shortcut. API const char* ncmenu_mouse_selected(const struct ncmenu* n, - const struct ncinput* click, - struct ncinput* ni); + const ncinput* click, ncinput* ni); // Return the ncplane backing this ncmenu. API struct ncplane* ncmenu_plane(struct ncmenu* n); @@ -3139,7 +3138,7 @@ API struct ncplane* ncmenu_plane(struct ncmenu* n); // * left or right on an unrolled menu (navigates among sections) // * up or down on an unrolled menu (navigates among items) // * escape on an unrolled menu (the menu is rolled up) -API bool ncmenu_offer_input(struct ncmenu* n, const struct ncinput* nc); +API bool ncmenu_offer_input(struct ncmenu* n, const ncinput* nc); // Destroy a menu created with ncmenu_create(). API int ncmenu_destroy(struct ncmenu* n); @@ -3379,7 +3378,7 @@ API struct ncplane* ncreader_plane(struct ncreader* n) // Offer the input to the ncreader. If it's relevant, this function returns // true, and the input ought not be processed further. Almost all inputs // are relevant to an ncreader, save synthesized ones. -API bool ncreader_offer_input(struct ncreader* n, const struct ncinput* ni) +API bool ncreader_offer_input(struct ncreader* n, const ncinput* ni) __attribute__ ((nonnull (1, 2))); // Atttempt to move in the specified direction. Returns 0 if a move was