===== 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 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 fully customized menu.
==== The menu structure ====
The menu is structured as a list of items, where each item defines a softkey:
{
Item_1
...
Item_n
}
If more than 6 items exist, the menu will be split in pages of 5 softkeys each, and the rightmost softkey of each page will turn into a ''NXT...'' key to display a new page; as usual, pressing any shift and ''NXT...'' will display the previous page.
Each item can be a single object or a three elements list: in the first case the offect depends on the type of the object:
* an **identifier** or a **directory** will have all the [[manual:chapter2:menus#the-vars-menu|properties of an entry]] in the ''Vars'' menu;
* a **unit with the numerical part equal to 1** will have all the [[manual:chapter3:units#operating-with-units|properties of an entry]] in the ''Units'' menu;
* a **command** will work as expected and will display an help message (if any) when long-pressed;
* a **string** will be displayed without quotes and returned on the stack whenthe softkey is pressed. No help is displayed when long-pressed;
* any other object will be ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]'''ted when the softkey is pressed. The label on the key is created [[manual:chapter6:string:cmd_todispstr|decompiling the object for display]]. No help is displayed when long-pressed.
In the second case, each element of the list takes care of an aspect of the softkey:
{
}
----
=== The DISPLAY object ===
The '''' object can be either a single object or a two elements list; if it is a single object:
* a **program leaving 1 object on the stack** is ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]'''ted and its output is used as label;
* a **graphic object** will be displayed as-is;
* a **string** will be displayed without quotes;
* a **unit with the numerical part equal to 1** will be stripped of the numerical part and the ''_'' delimiter and displayed;
* any other object will be [[manual:chapter6:string:cmd_todispstr|decompiled for display]] and shown on the label.
If '''' object is a two elements list:
{
}
the '''' part works exactly as above while the '''' part is an integer interpreted as a binary number:
* if **bit 0** is set, the label will be shown with its first character shaded, as directories or top-level menus;
* if **bit 1** is set, the color of the label will be inverted: the final effect cumulates with the effect of flags [[manual:appendix:flags#flag-15|-15]] and [[manual:appendix:flags#flag-16|-16]];
* other bits are ignored.
----
=== The ACTION object ===
The '''' 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;
* an **identifier** or a **directory** will have all the [[manual:chapter2:menus#the-vars-menu|properties of an entry]] in the ''Vars'' menu;
* a **unit** will have all the [[manual:chapter3:units#operating-with-units|properties of an entry]] in the ''Units'' menu;
* any other object will be ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]'''ted.
and all these actions will happen whether the softkey is pressed unshifted, shifted or hold-shifted.
If the '''' object is a three elements list:
{
}
the user can define three separate actions for unshifted and shifted softkeys.
If the '''' object is a five elements list:
{
}
the user can define five separate actions for unshifted, shifted and hold-shifted softkeys.
----
=== The HELP object ===
The '''' object is an optional string that will be displayed in the help area when the softkey is long-pressed; a line break can be inserted using the **RS-DOT** key combination in Alpha mode.
----
==== Menus and sub-menus ====
**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]];
* ''[[manual:chapter6:flags:cmd_tmenulst|TMENULST]]'' which displays the menu on the area that was used last, be it the active or the secondary area;
* ''[[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 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;
* ''[[manual:chapter6:flags:cmd_menubklst|MENUBKLST]]'' which displays the previous menu on the area that was used last;
* ''[[manual:chapter6:flags:cmd_menubkothr|MENUBKOTHR]]'' which displays the previous menu on the area that was **not** used last.
Finally, to retrieve on the stack the definitions of the custom menus the following commands are provided:
* ''[[manual:chapter6:flags:cmd_rclmenu|RCLMENU]]'' to recall the [[manual:chapter2:menus#using-the-menus-main-active-and-secondary-menus|active menu]];
* ''[[manual:chapter6:flags:cmd_rclmenulst|RCLMENULST]]'' to recall the menu that was used last;
* ''[[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//
{
{ { "File" 1 } :: L2 TMENULST ; "File operations" }
{ { "Edit" 0 } :: ; "Edit file" }
{ { "Search" 0 } :: ; "Search text" }
{ "" }
{ "" }
{ { "Quit" 0 } :: #00040000h TMENUOTHR #04402000h TMENU ; "Quit application" }
}
* 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 '''' nor '''' object;
* ''Quit'' restores **MAIN** and ''Vars'' menus.
----
**__Program__** ''L2'' -- //The second level menu//
{
{ { "New" 0 } :: ; "Create new file" }
{ { "Open" 0 } :: ; "Open existing file" }
{ { "Save" 1 } :: L3 TMENUOTHR ; "Save file" }
{ "" }
{ "" }
{ "Back" :: { } TMENUOTHR MENUBKLST ; "Back to Main menu" }
}
* ''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//
{
{ "Save" :: ; "Save file" }
{ "As..." :: ; "Save with another name" }
{ "Copy" :: ; "Save a duplicate" }
{ "" }
{ "" }
{ "Back" :: { } TMENULST MENUBKOTHR ; "Back to Main menu" }
}
* ''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//
«
{ } TMENULST
{ } TMENUOTHR
L1 TMENU
»
* 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.