Differences

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

--- manual:chapter7:custmenu [2021/10/12 14:34]
jojo1973
+++ manual:chapter7:custmenu [2022/01/18 07:29] (current)
claudio [Creating customized menus]
@@ Line 1: / Line 1: @@
 ===== Creating customized menus =====
-The menu engine in **newRPL** retains the basic concepts of the one used in **userRPL** but provides new features such as help messages and dynamical menu appearance.
+The menu engine in **newRPL** retains the basic concepts of the one used in **userRPL** but provides new features such as help messages and dynamic menu appearance.
-The most important command used to display a custom menu is ''[[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. It accepts either an integer or a list: the former is used to display a preset [[manual:appendix:menus|system menu]] but here we will discuss about the latter, which allows to display a full customized menu.
+The most important command used to display a custom menu is ''[[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. It accepts either an integer or a list: the former is used to display a preset [[manual:appendix:menus|system menu]] but here we will discuss about the latter, which allows to display a fully customized menu.
 ==== 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 123: / Line 123: @@
 ----
-==== An example: 3-levels menu template ====
+==== 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.