====== dd_lightbar_menu.js ======
dd_lightbar_menu.js is a loadable JavaScript file that provides a class, DDLightbarMenu, which is a lightbar menu class for use in JavaScript scripts for Synchronet.

To create a new DDLightbarMenu object:
  var lbMenu = new DDLightbarMenu(x, y, width, height);

The DDLightbarMenu class supports single item selection and multiple item selection.  For one example of how to use DDLightbarMenu, you can look at the code for ''[[howto:door:slyvote]]''.  ''[[howto:editor:slyedit]]'' is another example of a JavaScript script that uses DDLightbarMenu. [[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/DDMsgReader/DDMsgReader.js|Digital Distortion Message Reader]] is another example of a JavaScript mod that uses DDLightbarMenu, including unselectable items (for its 'Indexed' reader mode).\\
\\
The user can navigate the list using the up & down arrows, PageUp, PageDown, Home, and End keys.  The enter key selects an item.  The ESC key will exit the menu and return null.  This menu library requires the use of an ANSI terminal.  By default, this menu library does not display a border around the menu.  If you want this library to draw a border around the menu, you can set the borderEnabled property to true.  Without a border, the menu gains 2 characters of width and 2 lines of height.  Also, a scrollbar can be optionally displayed, which provides a visual indicator for how far the user is through the list of items.  The scrollbar is disabled by default.

Menu items can be marked as selectable or not (via the isSelectable property on the item, which is a boolean and is true by default).  The Add() function has a parameter for whether the item should be selectable. Also, the ToggleItemSelectable can be used to toggle whether an item should be selectable or not. If the color specified for unselectable items is an empty string, then you can embed attribute/color codes within the item text for non-selectable items to color them how you wish.
There is also a property, allowUnselectableItems, which is a boolean that specifies whether or not to allow unselectable items.  If that is false (default), then all items will be treated as selectable, including items with their isSelectable property set to false. If you want to have items that are unselectable, you must set the menu's allowUnselectableItems property to true.

In addition, if the user's terminal doesn't support ANSI, DDLightbarMenu will still work for the user by simply listing all menu items in 'numbered' mode so that the user can choose an item by entering its corresponding number.  This way, you can write JavaScript mods that use DDLightbarMenu that should work for both ANSI and non-ANSI terminals.

Also, DDLightbarMenu has a property, allowANSI, which can be used to force non-lightbar operation as if ANSI isn't available (for instance, if you want to have a more traditional non-lightbar user interface).  allowANSI is true by default, but if you want to force non-lightbar operation, you can set it to false:
  lbMenu.allowANSI = false;

For non-lightbar operation, you can customize the prompt text that is used, by changing the nonANSIPromptText property. For instance:
  lbMenu.nonANSIPromptText = "Type a number to choose an item: ";

Also, after showing the menu & getting a value from the user (using the GetVal() function), the lastUserInput property will have the user's last keypress. If lastUserInput is an empty string, then it's likely that the inactivity timeout was reached.

**DDLightbarMenu methods**
^ Name                          ^ Returns          ^ Usage                                        ^ Description^
| 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 |
| RemoveAllItems                | void    | DDLightbarMenu.RemoveAllItems()              | Removes all items from the menu |
| SetItemHotkey                 | void    | DDLightbarMenu.SetItemHotkey(idx, hotkey)    | Sets a hotkey for a menu item, by index |
| AddItemHotkey                 | void    | DDLightbarMenu.AddItemHotkey(idx, hotkey)    | Adds a hotkey for a menu item (in addition to the item's other hotkeys) |
| RemoveItemHotkey              | void    | DDLightbarMenu.RemoveItemHotkey(idx, hotkey) | Removes a specific hotkey from a menu item |
| RemoveItemHotkeys             | void    | DDLightbarMenu.RemoveItemHotkeys(idx)        | Removes all hotkeys from a menu item |
| RemoveAllItemHotkeys          | void    | DDLightbarMenu.RemoveAllItemHotkeys()        | Removes all hotkeys from all menu items |
| GetVal                        | various | DDLightbarMenu.GetVal(draw)                  | Waits for user input, then gets the value of the item selected by the user.  The 'draw' parameter is a boolean that specifies whether or not to draw the menu first (defaults to true).  The return value type will be as follows:\\  * If in multi-select mode, this method will return an array of the chosen values.\\  * If in single-select mode, this method will return the single value selected by the user.\\  * If the user exited the menu without choosing (i.e., with ESC), this method will return null. |
| SetPos                        | void    | DDLightbarMenu.SetPos(x, y)                  | Sets the menu's position, by the upper-left corner X and Y coordinates |
| SetSize                       | void    | DDLightbarMenu.SetSize(size)                 | Sets the menu's size.  The 'size' parameter is an object with the properties 'width' and 'height', specifying the menu's width and height. |
| SetWidth                      | void    | DDLightbarMenu.SetWidth(width)               | Sets the menu's width |
| SetHeight                     | void    | DDLightbarMenu.SetHeight(height)             | Sets the menu's height |
| Draw                          | void    | DDLightbarMenu.Draw(selectedItemIndexes)     | Draws the menu with all (visible) menu items.  The selected items will be highlighted.  The 'selectedItemIndexes' is an object that can contain multiple indexes of selected items (as properties of the object) - This is only for multi-select mode.  These are used for drawing a marking character in the item text.  |
| Erase                         | void    | DDLightbarMenu.Erase()                       | Erases the menu - Draws black (normal color) where the menu was |
| SetBorderChars                | void    | DDLightbarMenu.SetBorderChars(borderChars)   | Sets the characters to use for drawing the menu border.  The 'borderChars' parameter is an object that contains the following properties: upperLeft, upperRight, lowerLeft, lowerRight, top, bottom, left, right |
| GetNumItemsPerPage            | number  | DDLightbarMenu.GetNumItemsPerPage()          | Returns the number of (possible) items per page |
| GetTopItemIdxToTopOfLastPage  | number  | DDLightbarMenu.GetTopItemIdxToTopOfLastPage() | Gets the top item index of the last page of items |
| SetTopItemIdxToTopOfLastPage  | number  | DDLightbarMenu.SetTopItemIdxToTopOfLastPage() | Sets the top item index to the top item of the last page of items |
| NumItems                      | number  | To be used internally                         | Returns the number of items in the list.  This function can be replaced if you want to allow the menu object to access a different list of items rather than add a large list of items to the menu, for a speed optimization.  See the "Replacing the NumItems() and GetItem() functions" section below. |
| GetItem                       | object  | To be used internally                         | Returns an item object compatible with DDLightbarMenu.  This function can be replaced if you want to allow the menu object to access a different list of items rather than add a large list of items to the menu, for a speed optimization.  You might also choose to have it specify to use the alternate item colors (specified by colors.altItemColor and colors.altSelectedItemColor) with the returned object.  See the "Replacing the NumItems() and GetItem() functions" section below. |
| ValidateSelectItem            | boolean | See comments at the top of the file | Takes an item's return value and validates that the user can select it.  By default, this returns true.  See the "Replacing the ValidateSelectItem() function" section below. |
| OnItemSelect                  | void    | See the "Replacing the OnItemSelect() function" section below or comments at the top of the file | This is called when an item is selected and is meant to provide a way for the calling script to do something when an item is selected.  This function takes an item's return value and a boolean for whether or not it was selected, and performs some action with it.  By default, this does nothing.  See the "Replacing the OnItemSelect() function" section below. |
| OnItemNav                     | void    | See the "Replacing the OnItemNav() function" section below or comments at the top of the file | This is called when the user navigates to another item in the menu and is meant to provide a way for the calling script to do something when this occurs.  This function takes 2 parameters: The old item index and the new current item index.  See the "Replacing the OnItemNav() function" section below. |
| DrawPartial                   | void    | DrawPartial(pStartX, pStartY, pWidth, pHeight, pSelectedItemIndexes) | Redraws only a portion of the menu, specified by starting X & Y coordinates, width, and height.  The starting X & Y coordinates are relative to the upper-left corner of the menu (not absolute screen coordinates) and start at (1, 1). |
| DrawPartialAbs                | void    | DrawPartialAbs(pStartX, pStartY, pWidth, pHeight, pSelectedItemIndexes) | Redraws only a portion of the menu, specified by starting X & Y coordinates, width, and height.  The starting X & Y coordinates are absolute screen coordinates, starting at (1, 1) in the upper-left corner of the terminal window. |
| GetBottomItemIdx              | number  | DDLightbarMenu.GetBottomItemIdx()   | Returns the index of the bottommost item currently visible on the menu. |
| GetTopDisplayedItemPos        | object  | DDLightbarMenu.GetTopDisplayedItemPos() | Returns an object with x and y properties representing the location (in absolute screen coordinates) of the topmost item currently visible on the menu. |
| GetBottomDisplayedItemPos     | object | DDLightbarMenu.GetBottomDisplayedItemPos() | Returns an object with x and y properties representing the location (in absolute screen coordinates) of the bottommost item currently visible on 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. |
| 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**
^ Name                          ^ Type    ^ Description^
| colors                       | object | An object that contains color codes (as strings) for various things.  Contains the following properties: itemColor, selectedItemColor, altItemColor, altSelectedItemColor, itemTextCharHighlightColor, borderColor.  altItemColor and altSelectedItemColor are alternate colors that can be used for the items.  Currently, those would only be used if you have replaced the GetItem() function and return an item object with its useAltColors property set to true. |
| borderEnabled                | boolean | Whether or not to draw a border around the menu items |
| scrollbarEnabled             | boolean | Whether or not to enable the scrollbar.  Defaults to false. |
| mouseEnabled                 | boolean | Whether or not mouse support is enabled.  Defaults to false. |
| wrapNavigation               | boolean | Whether or not to wrap around to the beginning/end when using the down/up arrows.  Defaults to true. |
| hotkeyCaseSensitive          | boolean | Whether or not hotkeys are case-sensitive.  Defaults to false. |
| ampersandHotkeysInItems      | boolean | Whether or not to allow ampersands (&) to declare hotkeys in item text.  Defaults to true. |
| multiSelect                  | boolean | Whether or not to allow multi-select mode (selection of multiple items).  Defaults to false. |
| maxNumSelections             | number  | The maximum number of item selections.  -1 or 0 means no limit on the number of selections. |
| multiSelectItemChar          | string  | The character to use for displaying which items are selected (for multi-select mode).  Defaults to the check-mark character. |
| enterAndSelectKeysAddsMultiSelectItem | boolean | When in multi-select mode, this property specifies whether the Enter key (or another 'select' key) will add the current highlighted item to the list of highlighted items. By default, if multi-select is enabled and GetVal() is called, the 'enter' key (or other selection keys) will exit the menu selection without adding the current highlighted item to the multi-select items. The user can still select items (i.e., using the spacebar) and the enter key will basically confirm their selection.  However, when using multi-select, if you want the enter key to select the current highlighted item before exiting GetVal(), you can set this property to true (it's default is false). When you set this to true, then when the user presses Enter (or another configured select-item key), the current highlighted menu item will be toggled on before exiting the menu input loop (i.e., GetVal()). \\ The reason it's called enterAndSelectKeysAddsMultiSelectItem is because Enter normally returns from choosing an item, and there can be additional select-item keys if you call AddAdditionalSelectItemKeys(). |
| numberedMode                 | boolean | Whether or not to use 'numbered mode'.  Defaults to false.  If true, the menu will automatically use number input from the user for selecting the items. |
| exitOnItemSelect             | boolean | Whether or not to automatically exit menu input when an item is selected.  Defaults to true. |
| topBorderText                | string  | Text to write in the top border (if borders are enabled).  This defaults to an empty string.  Synchronet color/attribute codes are supported. |
| bottomBorderText             | string  | Text to write in the bottom border (if borders are enabled).  This defaults to an empty string.  Synchronet color/attribute codes are supported. |
| callOnItemNavOnStartup       | boolean | Whether or not to call OnItemNav() when the menu is initially displayed to get the user's choice. Defaults to false. |
| allowUnselectableItems       | boolean | Whether or not to enable unselectable items. This defaults to false (in which case all items will be treated as selectable, even if their isSelectable property is false). |
| allowANSI                    | boolean | Whether or not to allow lightbar operation (which requires ANSI). Defaults to true. If false, DDLightbarMenu will simply list the menu items in 'numbered' mode and prompt the user to choose an item via its corressponding number. |
| nonANSIPromptText            | string  | The text to use when prompting the user for a choice in non-lightbar operation |
| lastUserInput                | string  | The user's last keypress. If lastUserInput is an empty string, then it's likely that the inactivity timeout was reached. |

To change the colors used for displaying the items, you can change the values in the colors object within the DDLightbarMenu object.  These are the current supported colors (in the 'colors' property of the object):
^ color property             ^ Description ^
| itemColor                  | The color to use for non-selected items (current default is white on blue).  Note that if numbered mode is enabled, this does not include the item number; this is for the actual item text itself.  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. |
| 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) |
| scrollbarScrollBlockColor  | The color for the scrollbar blocks |
| scrollbarBGColor           | The color for the scrollbar background |
| itemNumColor               | The color for item numbers in numbered mode (for non-highlighted items) |
| highlightedItemNumColor    | The color for item numbers in numbered mode for the current highlighted/selected item |

By default, the menu selection will wrap around to the beginning/end when using the down/up arrows.  That behavior can be disabled by setting the wrapNavigation property to false.

This menu object supports adding multiple hotkeys to each menu item.  A hotkey can be specified in the Add() method a couple of different ways - By specifying a hotkey as the 3rd parameter and/or by putting a & in the menu item text just before a key you want to use as the hotkey.  For example, in the text "E&xit", "x" would be used as the hotkey for the item.  If you want to disable the use of ampersands for hotkeys in menu items (for instance, if you want an item to literally display an ampersand before a character), set the ampersandHotkeysInItems property to false.  For instance:
  lbMenu.ampersandHotkeysInItems = false;
Note that ampersandHotkeysInItems must be set before adding menu items.

You can call the SetItemHotkey() method to set a single hotkey to be used for a menu item or AddItemHotkey() to add an additional hotkey for an item in addition to any existing hotkeys it might already have.

This menu class also supports an optional "numbered mode", where each option is displayed with a number to the left (starting at 1), and the user is allowed to choose an option by typing the number of the item.  Numbered mode is disabled by default and can be enabled by setting the numberedMode property to true.  For example:
  lbMenu.numberedMode = true;
When numbered mode is enabled and the user starts typing a number, the menu will prompt the user for an item number.  Note that the prompt will be located on the line below the menu, so in addition to the menu's height, you'll also need an extra line on the screen to account for the item prompt.  In addition, when the user presses the enter key after the item number, a carriage return/line feed will be outputted, so in numbered mode, the menu's height should not go further than 2 lines below the console height.  Otherwise, the display of the menu will not be correct if the user decides not to enter a number.

This menu also supports multiple options selected (by default, that is not enabled).  To enable that, set the multiSelect property to true.  When enabled, the GetVal() method will return an array of the user's selections rather than a string (or null if the user aborted).  You can also set a limit on the number of items selected in multi-select mode by setting the maxNumSelections property.  The default value is -1, which means no limit (0 also means no limit).  Example, with a limit:
  lbMenu.multiSelect = true;
  lbMenu.maxNumSelections = 5;

====== Example usage ======
  load("dd_lightbar_menu.js");
  // Create a menu at position 1, 3 with width 45 and height of 10
  var lbMenu = new DDLightbarMenu(1, 3, 45, 10);
  // Add 12 items to the menu, each of which will return the text of the item
  for (var i = 0; i < 12; ++i)
    lbMenu.Add("Item " + +(i+1), "Item " + +(i+1));
  // Set up the hotkey "s" to select the 2nd item
  lbMenu.SetItemHotkey(1, "s");
  // Show the menu and get the chosen item from the user
  var val = lbMenu.GetVal();
  // Output the chosen menu item
  console.print("\x01n\r\n");
  console.print("Value:" + val + ":, type: " + typeof(val) + "\r\n");
  console.pause();
  
  // Changing the normal item color to green & selected item color to bright green:
  lbMenu.colors.itemColor = "\x01n\x01g";
  lbMenu.colors.selectedItemColor = "\x01n\x01h\x01g";
  
  // Disabling the navigation wrap behavior:
  lbMenu.wrapNavigation = false;
  
  // If you want a particular character in an item's text highlighted with
  // a different color, you can put a & character immediately before it, as
  // long as it's not a space.  For instance, to highlight the "x" in "Exit":
  lbMenu.Add("E&xit", -1);
  
  // To enable borders and set text to display in the top & bottom borders:
  lbMenu.borderEnabled = true;
  lbMenu.topBorderText = "Options";
  lbMenu.bottomBorderText = "ESC: Quit";

To enable the scrollbar, set the scrollbarEnabled property to true.  Example:
  lbMenu.scrollbarEnabled = true;

To enable borders, set the borderEnabled property to true.  Example:
  lbMenu.borderEnabled = true;

If borders are enabled, the scrollbar will appear just inside the right border. Also, if the scrollbar is enabled but all the items would fit in a single "page" in the menu, then the scrollbar won't be displayed.\\ 
The scrollbar uses block characters to draw the scrollbar: ASCII character 176 for the background and ASCII 177 for the block that moves on the scrollbar.  If you want to change those characters, you can change the scrollbarInfo.BGChar and scrollbarInfo.blockChar properties in the menu object.\\ 
By default, the scrollbar colors are high (bright) black for the background and high (bright) white for the moving block character.  If desired, those can be changed with the colors.scrollbarBGColor and colors.scrollbarScrollBlockColor properties in the menu object.

The menu object has an object called borderChars, which stores the characters used to draw the border.  you can change the characters used to draw the border by setting the following properties of the borderChars object:
  * upperLeft: The character to use for the upper-left corner
  * upperRight: The character to use for the upper-right corner
  * lowerLeft: The character to use for the lower-left corner
  * lowerRight: The character to use for the lower-right corner
  * top: The character to use for the top border
  * bottom: The character to use for the bottom border
  * left: The character to use for the left border
  * right: The character to use for the right border
For example:
  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):
  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({
    left: "|",
    right: "|"
  });

If you want hotkeys to be case-sensitive, you can set the hotkeyCaseSensitive property to true (it is false by default).  For example (assuming lbMenu is the menu object):
  lbMenu.hotkeyCaseSensitive = true;

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({
    itemColor: "\x01b",
    selectedItemColor: "\x01r\x01" + "7" // Red with a grey background - This uses 2 strings concatenated because "\x017" would be interpreted incorrectly.
  });

\\
===== Item color arrays (for the colors.itemColor and colors.selectedItemColor properties) =====
The colors.itemColor and colors.selectedItemColor properties can be either a string (containing Synchronet color/attribute codes for the normal & highlighted item text), or they can be an array with objects specifying color/attribute codes for different parts of an item's text string displayed on the menu.\\
Item color arrays: Currently, colors.itemColor and colors.seletedItemColor within a DDLightbarMenu object can be either a string (containing color/attribute codes) or an array with color/attribute codes for different sections of the item strings to display in the menu.  The array is to contain objects with the following properties:
  * start: The index of the first character in the item string to apply the colors to
  * end: One past the last character index in the string to apply the colors to
  *  attrs: The Synchronet attribute codes to apply to the section of the item 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:\\
  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: "\x01r\x01" + "7"}, {start: 5, end: 0, attrs: "\x01b\x01" + "7"}];

Note that the objects in the colors array **must** be in order, the first one *must* have a 'start' of 0, and all objects in the colors array must not specify any gaps in the 'start' and 'end' indexes.  For instance, if the first object does not start with 0, anything before a non-zero 'start' in the first object will be removed from the menu item string.

====== Replacing the NumItems() and GetItem() functions ======
For a speed optimization, it may be desirable to have the menu reference some items that already exist, rather than add a large list of items to the menu object.  One instance would be if your script is working with a Synchronet messagebase and already has a list of message headers you want to list in a menu.  The NumItems() and GetItems() functions need to replaced together.\\
The NumItems() function needs to return the number of items in the menu, as a number.  This is an example of replacing the NumItems() function, assuming the lbMenu is the menu object:\\
  lbMenu.NumItems = function() {
    // Do your own thing to get the number of items in your list.
    // ...
    // Assuming myNumItems is the number of items in your list:
    return myNumItems;
  };

This is an example of replacing the GetItem() function, assuming the lbMenu is the menu object:\\
  lbMenu.GetItem = function(pItemIndex) {
    // Get a default item object from the menu with an initial return value of -1
    var menuItemObj = this.MakeItemWithRetval(-1);
    // Do your own thing to get the item text and return value for the menu.
    // ...
    // Assuming itemText is the text to display in the menu and itemRetval is
    // the return value to return from the menu:
    menuItemObj.text = itemText;
    menuItemObj.retval = itemRetval;
    // You can also choose to have the returned object specify to use the alternate item colors
    // if desired (specified by colors.altItemCor and colors.altSelectedItemColor in the DDLightbarMenu
    // object).  To do so, uncomment the line below.
    //menuItemObj.useAltColors = true;
    // 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.
    //menuItemObj.itemColor = "\x01r"; // Red
    //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
  };

====== Replacing the ValidateSelectItem() function ======
When selecting an item, it may be desirable to validate whether a user should be allowed to select the item.  DDLightbarMenu has a member function it calls, ValidateSelectItem(), to do just that.  It takes the selected item's return value and returns a boolean to signify whether the user can select it.   By default, it just returns true (allowing the user to select any item).  When the user can't choose a value, your code should output why.\\
To change its behavior, you can overwrite it as follows (assuming lbMenu is a DDLightbarMenu object):\\
  lbMenu.ValidateSelectItem = function(pItemRetval) {
    // Should the user be able to select the item with the return val indicated
    // by pItemRetval?
    if (yourValidationCode(pItemRetval))
      return true;
    else
    {
      console.print("* Can't choose " + pItemRetval + " because blah blah blah!\r\n\x01p");
      return false;
    }
  }

====== Replacing the OnItemSelect() function ======
Sometimes it can be desirable to do something when a user selects an item.  OnItemSelect is a function that is called when an item is selected, or toggled if multi-select is enabled.
Parameters:\\
- pItemRetval: The return value of the item selected\\
- pSelected: Boolean - Whether the item was selected or de-selected.  De-selection is possible when multi-select is enabled.\\
\\
Overwriting this function:\\
  lbMenu.OnItemSelect = function(pItemRetval, pSelected)
  {
    // Do something with pItemRetval.  pSelected tells whether the item was selected,
    // or de-selected if multi-select is enabled.
  }

====== Replacing the OnItemNav() function ======
Sometimes it can be desirable to do something when the user navigates to another item in the menu.  This can happen when the user presses one of the arrow buttons, PageUp, PageDown, Home, End, etc.
Parameters:\\
- pOldItemIdx: The index of the old (previous) item (numeric, 0-based)
- pNewItemIdx: The index of the new current item (numeric, 0-based)\\
\\
Overwriting this function:\\
  lbMenu.OnItemNav = function(pOldItemIdx, pNewItemIdx) {
    // Do something based on the new or old item
  }

====== Example code ======
For real-world examples where DDLightbarMenu is used, you can look at the following:\\
  * [[module:slyedit|SlyEdit]] ([[https://gitlab.synchro.net/main/sbbs/-/blob/master/exec/SlyEdit.js|SlyEdit.js]]): Creating a DDLightbarMenu for quote line selection in the function createQuoteLineMenu (replacing the NumItems and GetItem function); for cross-posting in other sub-boards in the createCrossPostMsgGrpMenu and createCrossPostSubBoardMenu functions (SetColors to set colors for various sections of the items, and replacing the NumItems and GetItem functions); in the doUserDictionaryLanguageSelection function for dictionary files; in the doTaglineSelection function for selecting a tag line
  * [[howto:door:slyvote|SlyVote]] ([[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/slyvote/slyvote.js|slyvote.js]]): Creating a DDLightbarMenu in the functions CreateMsgGrpMenu, CreateSubBoardMenu, DoMainMenu, ChooseVotePoll, DisplayPollOptionsAndVote (also enables the multiSelect property for polls that allow multiple answers)
  * Digital Distortion File Lister ([[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/ddfilelister/ddfilelister.js|ddfilelister.js]]): Creating a DDLightbarMenu in the createFileListMenu function (specifies additional keys for quitting out of the menu, item coloring, and replacing the NumItems and GetItem functions); in the createFileLibMenu function; in the createFileDirMenu function
  * Digital Distortion [[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/DDAreaChoosers/DDMsgAreaChooser.js|Message Area Chooser]], [[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/DDAreaChoosers/DDFileAreaChooser.js|File Area Chooser]], and [[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/DDMsgReader/DDMsgReader.js|Message Reader]]: Search for "new DDLightbarMenu"
  * Digital Distortion [[https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/DDMsgReader/DDMsgReader.js|Message Reader]]: Used for listing messages, changing the message area, and 'indexed' reader mode - including using unselectable items in the indexed reader menu for message group headers

====== Screenshots ======
{{:custom:javascript:lib:ddlightbarmenu1.png?400|}}
{{:custom:javascript:lib:ddlightbarmenu2.png?400|}}

===== See Also =====
  * [[:custom:javascript:lib:|custom:javascript:lib index]]

{{tag>}}
