| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| custom:javascript:lib:ddlightbarmenu.js [2023/04/06 13:02] – Mentioned the fact that DDLightbarMenu can now work in non-lightbar mode if the user's terminal doesn't support ANSI (and has a property, allowANSI, that can be set false if you want to force it to do so). Added a link to DDMsgReader.js at the bottom for Nightfox | custom:javascript:lib:ddlightbarmenu.js [2024/02/12 18:42] (current) – [Replacing the NumItems() and GetItem() functions] Mention textIsUTF8 nightfox |
|---|
| **DDLightbarMenu methods** | **DDLightbarMenu methods** |
| ^ Name ^ Returns ^ Usage ^ Description^ | ^ Name ^ Returns ^ Usage ^ Description^ |
| | Add | void | DDLightbarMenu.Add(text, retval, hotkey, selectable) | Adds an item to the menu with a given item text, return value, and hotkey for the item. If the ampersandHotkeysInItems property is set to true before this method is called, then a & can be used in the item text just before the hotkey you want to enable for the item. For example, "Item &1" would display the text "Item 1" with "1" being the hotkey for the item. The 3rd parameter, selectable, is an optional boolean that specifies whether or not the item is selectable. Non-selectable items will be skipped when scrolling through the menu. | | | Add | void | DDLightbarMenu.Add(text, retval, hotkey, selectable, isUTF8) | Adds an item to the menu with a given item text, return value, and hotkey for the item. The isUTF8 parameter specifies whether the item text is UTF-8 (if so, then it will be displayed with the P_UTF8 mode bit to look correct on UTF-8 capable terminals, or converted to cp437 for non-UTF-8 terminals). If the ampersandHotkeysInItems property is set to true before this method is called, then a & can be used in the item text just before the hotkey you want to enable for the item. For example, "Item &1" would display the text "Item 1" with "1" being the hotkey for the item. The 3rd parameter, selectable, is an optional boolean that specifies whether or not the item is selectable. Non-selectable items will be skipped when scrolling through the menu. | |
| | Remove | void | DDLightbarMenu.Remove(idx) | Removes an item from the menu by its index | | | Remove | void | DDLightbarMenu.Remove(idx) | Removes an item from the menu by its index | |
| | RemoveAllItems | void | DDLightbarMenu.RemoveAllItems() | Removes all items from the menu | | | RemoveAllItems | void | DDLightbarMenu.RemoveAllItems() | Removes all items from the menu | |
| | ScreenRowForItem | number | DDLightbarMenu.ScreenRowForItem(itemIdx) | Returns the screen row number (in absolute screen coordinates) of an item on the menu, if it is visible. If the item is not visible, this will return -1. | | | ScreenRowForItem | number | DDLightbarMenu.ScreenRowForItem(itemIdx) | Returns the screen row number (in absolute screen coordinates) of an item on the menu, if it is visible. If the item is not visible, this will return -1. | |
| | ToggleItemSelectable | void | DDLightbarMenu.ToggleItemSelectable(itemIdx, selectable) | Toggles whether an item should be selectable. Parameters are the item index and a boolean specifying whether the item should be selectable. | | | ToggleItemSelectable | void | DDLightbarMenu.ToggleItemSelectable(itemIdx, selectable) | Toggles whether an item should be selectable. Parameters are the item index and a boolean specifying whether the item should be selectable. | |
| | | AddAdditionalQuitKeys | void | DDLightbarMenu.AddAdditionalPageUpKeys(additionalKeysStr) | Adds a list of keys to use as quit keys in addition to ESC. additionalKeysStr is a string | |
| | | ClearAdditionalQuitKeys | void | DDLightbarMenu.ClearAdditionalQuitKeys() | Clears the list of additional quit keys | |
| | | AddAdditionalPageUpKeys | void | DDLightbarMenu.AddAdditionalPageUpKeys(additionalKeysStr) | Adds a list of keys to use as page-up keys in addition to PageUp. additionalKeysStr is a string | |
| | | ClearAdditionalPageUpKeys | void | DDLightbarMenu.ClearAdditionalPageUpKeys() | Clears the list of additional page-up keys | |
| | | AddAdditionalPageDownKeys | void | DDLightbarMenu.AddAdditionalPageDownKeys(additionalKeysStr) | Adds a list of keys to use as page-down keys in addition to PageDown. additionalKeysStr is a string | |
| | | ClearAdditionalPageDownKeys | void | DDLightbarMenu.ClearAdditionalPageDownKeys() | Clears the list of additional page-down keys | |
| | | AddAdditionalFirstPageKeys | void | DDLightbarMenu.AddAdditionalFirstPageKeys(additionalKeysStr) | Adds a list of keys to use as additional first-page keys in addition to HOME. additionalKeysStr is a string | |
| | | ClearAdditionalFirstPageKeys | void | DDLightbarMenu.ClearAdditionalFirstPageKeys() | Clears the list of additional first-page keys | |
| | | AddAdditionalLastPageKeys | void | DDLightbarMenu.AddAdditionalLastPageKeys(additionalKeysStr) | Adds a list of keys to use as additional last-page keys in addition to END. additionalKeysStr is a string | |
| | | ClearAdditionalLastPageKeys | void | DDLightbarMenu.ClearAdditionalLastPageKeys() | Clears the list of additional last-page keys | |
| |
| **DDLightbarMenu properties** | **DDLightbarMenu properties** |
| | selectedItemColor | The color to use for selected items (current default is blue on white). This can be either a string (with Synchronet color/attribute codes for the item text) or an array with objects specifying color/attribute codes for different parts of an item's text string displayed on the menu. See the "Item color arrays" section below for more information. | | | selectedItemColor | The color to use for selected items (current default is blue on white). This can be either a string (with Synchronet color/attribute codes for the item text) or an array with objects specifying color/attribute codes for different parts of an item's text string displayed on the menu. See the "Item color arrays" section below for more information. | |
| | unselectableItemColor | The color to use for unselectable items (current default is bright blue). This can be either a string (with Synchronet color/attribute codes for the item text) or an array with objects specifying color/attribute codes for different parts of an item's text string displayed on the menu. If this is an empty string, then color codes can be embedded in the item text to color the (unselectable) item. | | | unselectableItemColor | The color to use for unselectable items (current default is bright blue). This can be either a string (with Synchronet color/attribute codes for the item text) or an array with objects specifying color/attribute codes for different parts of an item's text string displayed on the menu. If this is an empty string, then color codes can be embedded in the item text to color the (unselectable) item. | |
| | itemTextCharHighlightColor | The color of a highlighted non-space character in an item text (specified by having a & in the item text). It's important not to specify a "\1n" in here in case the item text should have a background color. | | | itemTextCharHighlightColor | The color of a highlighted non-space character in an item text (specified by having a & in the item text). It's important not to specify a "\x01n" in here in case the item text should have a background color. | |
| | borderColor | The color for the borders (if borders are enabled) | | | borderColor | The color for the borders (if borders are enabled) | |
| | scrollbarScrollBlockColor | The color for the scrollbar blocks | | | scrollbarScrollBlockColor | The color for the scrollbar blocks | |
| var val = lbMenu.GetVal(); | var val = lbMenu.GetVal(); |
| // Output the chosen menu item | // Output the chosen menu item |
| console.print("\1n\r\n"); | console.print("\x01n\r\n"); |
| console.print("Value:" + val + ":, type: " + typeof(val) + "\r\n"); | console.print("Value:" + val + ":, type: " + typeof(val) + "\r\n"); |
| console.pause(); | console.pause(); |
| | |
| // Changing the normal item color to green & selected item color to bright green: | // Changing the normal item color to green & selected item color to bright green: |
| lbMenu.colors.itemColor = "\1n\1g"; | lbMenu.colors.itemColor = "\x01n\x01g"; |
| lbMenu.colors.selectedItemColor = "\1n\1h\1g"; | lbMenu.colors.selectedItemColor = "\x01n\x01h\x01g"; |
| | |
| // Disabling the navigation wrap behavior: | // Disabling the navigation wrap behavior: |
| lbMenu.borderChars.upperLeft = "\xDA"; // Single-line upper-left character | lbMenu.borderChars.upperLeft = "\xDA"; // Single-line upper-left character |
| To set/change any of the border characters, you can also call the SetBorderChars() function and pass an object containing any or all of the above properties to set the border characters in the object. For example (assuming lbMenu is the menu object): | To set/change any of the border characters, you can also call the SetBorderChars() function and pass an object containing any or all of the above properties to set the border characters in the object. For example (assuming lbMenu is the menu object): |
| | lbMenu.SetBorderChars({ |
| | left: "|", |
| | right: "|", |
| | top: "-", |
| | bottom: "-", |
| | upperLeft: "/", |
| | upperRight: "\", |
| | lowerLeft: "\", |
| | lowerRight: "/" |
| | }); |
| | |
| | Not all border characters need to be specified. For instance, perhaps you've set some border characters already and only want to change some of them: |
| lbMenu.SetBorderChars({ | lbMenu.SetBorderChars({ |
| left: "|", | left: "|", |
| To change the colors, you can directly change the properties of the color object within the DDLightbarMenu, or you can call the SetColors() function to set any or all of the color properties in the colors object in the DDLightbarMenu object. For example (assuming lbMenu is the menu object): | To change the colors, you can directly change the properties of the color object within the DDLightbarMenu, or you can call the SetColors() function to set any or all of the color properties in the colors object in the DDLightbarMenu object. For example (assuming lbMenu is the menu object): |
| lbMenu.SetColors({ | lbMenu.SetColors({ |
| itemColor: "\1b", | itemColor: "\x01b", |
| selectedItemColor: "\1r\1" + "7" // Red with a grey background - This uses 2 strings concatenated because "\17" would be interpreted incorrectly. | selectedItemColor: "\x01r\x01" + "7" // Red with a grey background - This uses 2 strings concatenated because "\x017" would be interpreted incorrectly. |
| }); | }); |
| |
| For the last item, the 'end' property can be -1, 0, or greater than the length of the item to apply the color/attribute codes to the rest of the string.\\ | For the last item, the 'end' property can be -1, 0, or greater than the length of the item to apply the color/attribute codes to the rest of the string.\\ |
| For example, for a menu with items that are simply titled "Item 1" and so on, this specifies indexes to color the item text with "Item" and the number colored separately:\\ | For example, for a menu with items that are simply titled "Item 1" and so on, this specifies indexes to color the item text with "Item" and the number colored separately:\\ |
| lbMenu.colors.itemColor = [{start: 0, end: 5, attrs: "\1h\1g\1" + "4"}, {start: 5, end: 0, attrs: "\1h\1y\1" + "4"}]; | lbMenu.colors.itemColor = [{start: 0, end: 5, attrs: "\x01h\x01g\x01" + "4"}, {start: 5, end: 0, attrs: "\x01h\x01y\x01" + "4"}]; |
| lbMenu.colors.selectedItemColor = [{start: 0, end: 5, attrs: "\1r\1" + "7"}, {start: 5, end: 0, attrs: "\1b\1" + "7"}]; | lbMenu.colors.selectedItemColor = [{start: 0, end: 5, attrs: "\x01r\x01" + "7"}, {start: 5, end: 0, attrs: "\x01b\x01" + "7"}]; |
| |
| ====== Replacing the NumItems() and GetItem() functions ====== | ====== Replacing the NumItems() and GetItem() functions ====== |
| // object). To do so, uncomment the line below. | // object). To do so, uncomment the line below. |
| //menuItemObj.useAltColors = true; | //menuItemObj.useAltColors = true; |
| | |
| // You might also opt to give this item specific colors for normal and highlighted | // You might also opt to give this item specific colors for normal and highlighted |
| // if you want to make this item appear different for whatever reason. | // if you want to make this item appear different for whatever reason. |
| //menuItemObj.itemColor = "\1r"; // Red | //menuItemObj.itemColor = "\x01r"; // Red |
| //menuItemObj.itemSelectedColor = "\1r\1" + "7"; // Red with grey background | //menuItemObj.itemSelectedColor = "\x01r\x01" + "7"; // Red with grey background |
| | |
| | // If you know the text is in UTF-8 format, you must specify so as follows: |
| | menuItemObj.textIsUTF8 = true; |
| | |
| return menuItemObj; // The DDLightbarMenu object will use this when displaying the menu | return menuItemObj; // The DDLightbarMenu object will use this when displaying the menu |
| }; | }; |
| else | else |
| { | { |
| console.print("* Can't choose " + pItemRetval + " because blah blah blah!\r\n\1p"); | console.print("* Can't choose " + pItemRetval + " because blah blah blah!\r\n\x01p"); |
| return false; | return false; |
| } | } |
