Differences

This shows you the differences between two versions of the page.

--- manual:chapter7:custmenu [2021/10/12 07:02]
jojo1973 Done
+++ manual:chapter7:custmenu [2021/10/12 15:26]
jojo1973 [The menu structure]
@@ Line 62: / Line 62: @@
 === The ACTION object ===
-The ''<Action>'' object can be either a single object, a three or a five elements list; if it is a single object:
+The ''<Action>'' object is optional and can be either a single object, a three or a five elements list; if it is a single object:
   * A **command** or **operator** will be ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]'''ted or its name will be inserted in the editor if the command line is active;
@@ Line 103: / Line 103: @@
 ==== Menus and sub-menus ====
-**newRPL** has two menu areas available to the user which can be exploited to create a two-level menu structure. Since **newRPL** allows the user to choose either **MENU 1** or **MENU 2** as active area, it is more convenient to refer to the two menus not in absolute terms but in __chronological__ terms; in other words, three commands are available to display a custom menu:
+**newRPL** has two menu areas available to the user which can be exploited to create a multilevel menu structure. Since **newRPL** allows the user to choose either **MENU 1** or **MENU 2** as active area, it is more convenient to refer to the two menus not in absolute terms but in __chronological__ terms; in other words, three commands are available to display a custom menu:
   * the already mentioned ''[[manual:chapter6:flags:cmd_tmenu|TMENU]]'' which displays the menu on the [[manual:chapter2:menus#using-the-menus-main-active-and-secondary-menus|active menu]] area as controlled by flag [[manual:appendix:flags#flag-11|-11]];
@@ Line 109: / Line 109: @@
   * ''[[manual:chapter6:flags:cmd_tmenuothr|TMENUOTHR]]'' which displays the menu on the area that was **not** used last, be it the active or the secondary area.
-In this way an application can easily create a two-level menu hierarchy and have both levels displayed on the screen at once. Of course, such a structure must be traversed also backwards, therefore three suitable commands are provided:
+In this way an application can easily create a multilevel menu hierarchy and have both levels displayed on the screen at once. Of course, such a structure must be traversed also backwards, therefore three suitable commands are provided:
   * ''[[manual:chapter6:flags:cmd_menubk|MENUBK]]'' which displays the previous menu on the [[manual:chapter2:menus#using-the-menus-main-active-and-secondary-menus|active menu]] area;
@@ Line 121: / Line 121: @@
   * ''[[manual:chapter6:flags:cmd_rclmenuothr|RCLMENUOTHR]]'' to recall the menu that was **not** used last.
+----
+==== Example: a 3-levels menu template ====
+The following programs build a 3-levels menu: the resulting program is just an empty shell, but demonstrates effectively the following techniques:
+  * menu concatenation;
+  * use of decorations;
+  * folding and unfolding of third level menu in the secondary area;
+  * works correctly whether the active area is in **MENU 1** or **MENU 2**.
+----
+**__Program__** ''L1'' -- //The top level menu//
+<code>
+{
+  { { "File" 1 } :: L2 TMENULST ; "File operations" }
+  { { "Edit" 0 } :: ; "Edit file" }
+  { { "Search" 0 } :: ; "Search text" }
+  { "" }
+  { "" }
+  { { "Quit" 0 } :: #00040000h TMENUOTHR #04402000h TMENU ; "Quit application" }
+}
+</code>
+  * The ''File'' menu recalls the second level menu, which will be displayed in the same area occupied by the top level menu;
+  * ''Edit'' and ''Search'' are dummy entries;
+  * filler softkeys have neither ''<Action>'' nor ''<Help>'' object;
+  * ''Quit'' restores **MAIN** and ''Vars'' menus.
+----
+**__Program__** ''L2'' -- //The second level menu//
+<code>
+{
+  { { "New" 0 } :: ; "Create new file" }
+  { { "Open" 0 } :: ; "Open existing file" }
+  { { "Save" 1 } :: L3 TMENUOTHR ; "Save file" }
+  { "" }
+  { "" }
+  { "Back" :: { } TMENUOTHR MENUBKLST ; "Back to Main menu" }
+}
+</code>
+  * ''Save'' opens the third level menu in the other area, leaving the second level menu still on the screen;
+  * ''Back'' cleans any third level menu that could have been displayed and restores the top level menu in the same area.
+----
+**__Program__** ''L3'' -- //The third level menu//
+<code>
+{
+  { "Save" :: ; "Save file" }
+  { "As..." :: ; "Save with another name" }
+  { "Copy" :: ; "Save a duplicate" }
+  { "" }
+  { "" }
+  { "Back" :: { } TMENULST MENUBKOTHR ; "Back to Main menu" }
+}
+</code>
+  * ''Back'' clears the third level menu and restores the previous menu in the other area which incidentally is the top level menu.
+----
+**__Program__** ''MAIN'' -- //Putting everything together//
+<code>
+«
+  { } TMENULST
+  { } TMENUOTHR
+  L1 TMENU
+»
+</code>
+  * The first two lines clean both menus and the third displays the top level menu on the active area. From now on all the execution happens between the menus;
+  * If flag [[manual:appendix:flags#flag-11|-11]] is toggled the top level menu is displayed in a different area, but the application keeps working in the same way: the first two levels are displayed in one area, the third level is displayed in the other area and when the menus are closed the menu areas are redrawn correctly.