[src/trunk]: src/usr.bin/menuc Document return values from menu items opt_act...

[martin <martin%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c5f2bc106941
branches:  trunk
changeset: 448967:c5f2bc106941
user:      martin <martin%NetBSD.org@localhost>
date:      Sat Feb 16 18:57:21 2019 +0000

description:
Document return values from menu items opt_action functions, add a
new variant: -1 when functions have fundamentally changed the menu
definition on the fly and the processing functions needs to restart
without looking at the old state (or stale cached pointers).

diffstat:

 usr.bin/menuc/menu_sys.def |  13 +++++++++----
 usr.bin/menuc/menuc.1      |  26 +++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 5 deletions(-)

diffs (74 lines):

diff -r b6d89a31d906 -r c5f2bc106941 usr.bin/menuc/menu_sys.def
--- a/usr.bin/menuc/menu_sys.def        Sat Feb 16 17:56:57 2019 +0000
+++ b/usr.bin/menuc/menu_sys.def        Sat Feb 16 18:57:21 2019 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: menu_sys.def,v 1.65 2019/02/06 20:08:15 martin Exp $   */
+/*     $NetBSD: menu_sys.def,v 1.66 2019/02/16 18:57:21 martin Exp $   */
 
 /*
  * Copyright 1997 Piermont Information Systems Inc.
@@ -688,7 +688,7 @@
 process_menu(int num, void *arg)
 {
        int sel = 0;
-       int req;
+       int req, rv;
        menu_ent *opt;
 
        menudesc *m;
@@ -754,8 +754,13 @@
                        continue;
                if (opt->opt_flags & OPT_ENDWIN)
                        endwin();
-               if (opt->opt_action && (*opt->opt_action)(m, arg))
-                       break;
+               if (opt->opt_action) {
+                       rv = (*opt->opt_action)(m, arg);
+                       if (rv == -1)
+                               continue;
+                       else if (rv != 0)
+                               break;
+               }
 
                if (opt->opt_menu != -1) {
                        if (!(opt->opt_flags & OPT_SUB)) {
diff -r b6d89a31d906 -r c5f2bc106941 usr.bin/menuc/menuc.1
--- a/usr.bin/menuc/menuc.1     Sat Feb 16 17:56:57 2019 +0000
+++ b/usr.bin/menuc/menuc.1     Sat Feb 16 18:57:21 2019 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: menuc.1,v 1.34 2019/01/04 15:27:19 martin Exp $
+.\"    $NetBSD: menuc.1,v 1.35 2019/02/16 18:57:21 martin Exp $
 .\"
 .\" Copyright 1997 Piermont Information Systems Inc.
 .\" All rights reserved.
@@ -539,6 +539,30 @@
 If it's null, string
 .Dq Exit
 is used.
+.Sh MENU ITEM ACTIONS
+When creating dynamic menus, the programer supplies function pointers
+for the menu items
+.Dv opt_action
+member.
+This functions return one of three possible values:
+.Bl -tag -width "-1" -compact
+.It 0
+process sub menu (if set) and continue with the current (or new) menu
+as usual.
+.It 1
+exit the current menu.
+This is equivalen to specifying
+.Dq exit
+in a non-dynamic menu specification.
+.It -1
+do not handle the current item any further and restart handling the (same)
+menu.
+This return value is used when actions modify the menu definition on the
+fly, e.g. adding or removing additional menu items.
+The action may set
+.Dq cur_sel
+to jump to an arbitrary menu item (in the modified menu).
+.El
 .Sh MENU ITEM EXPANSION
 With the
 .Ic enable expansion