Show pageDiscussionOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ===== 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: <code> { Item_1 ... Item_n } </code> 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: <code> { <Display> <Action> <Help> } </code> ---- === The DISPLAY object === The ''<Display>'' 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 ''<Display>'' object is a two elements list: <code> { <Display> <Decoration> } </code> the ''<Display>'' part works exactly as above while the ''<Decoration>'' 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 ''<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; * 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 ''<Action>'' object is a three elements list: <code> { <Normal_Action> <Left-Shift_Action> <Right-Shift_Action> } </code> the user can define three separate actions for unshifted and shifted softkeys. If the ''<Action>'' object is a five elements list: <code> { <Normal_Action> <Left-Shift_Action> <Right-Shift_Action> <Left-Shift-Hold_Action> <Right-Shift-Hold_Action> } </code> the user can define five separate actions for unshifted, shifted and hold-shifted softkeys. ---- === The HELP object === The ''<Help>'' 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// <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. manual/chapter7/custmenu.txt Last modified: 2022/01/18 07:29by claudio