| Next revision | Previous revisionNext revisionBoth sides next revision |
| module:ddlightbarmenu.js [2018/03/24 16:10] – Created a documentation page for load/DDLightbarMenu.js as a developer reference. nightfox | module:ddlightbarmenu.js [2018/03/26 10:19] – Updated the description of the GetVal() method nightfox |
|---|
| DDLightbarMenu.js is a loadable JavaScript file that provides a lightbar menu class for use in JavaScript scripts for Synchronet. DDLightbarMenu 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]]''.\\ | DDLightbarMenu.js is a loadable JavaScript file that provides a lightbar menu class for use in JavaScript scripts for Synchronet. DDLightbarMenu 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]]''.\\ |
| \\ | \\ |
| The user can naviate 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. | 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. |
| |
| This script provides an object, DDLightbarMenu. Use the DDLightbarMenu constructor to create the object. Some other notable methods: | This script provides a class, DDLightbarMenu. To create a new DDLightbarMenu object: new DDLightbarMenu(width, height); |
| * Add() | |
| * SetItemHotkey() | |
| * AddItemHotkey() | |
| * SetPos() | |
| * SetSize() | |
| * GetVal() | |
| |
| 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: | **DDLightbarMenu methods** |
| * itemColor: The color to use for non-selected items (current default is white on blue) | ^ Name ^ Returns ^ Usage ^ Description^ |
| * selectedItemColor: The color to use for selected items (current default is blue on white) | | Add | void | DDLightbarMenu.Add(text, retval, hotkey) | Adds an item to the menu with a given item text, return value, and hotkey for the 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. | | Remove | void | DDLightbarMenu.Remove(idx) | Removes an item from the menu by its index | |
| * borderColor: The color for the borders (if borders are enabled) | | 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 | |
| | |
| | **DDLightbarMenu properties** |
| | ^ Name ^ Type ^ Description^ |
| | | colors | object | An object that contains color codes (as strings) for various things. Contains the following properties: itemColor, selectedItemColor, itemTextCharHighlightColor, borderColor | |
| | | 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. | |
| | | 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. | |
| | |
| | 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) | |
| | | selectedItemColor | The color to use for selected items (current default is blue on white) | |
| | | 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. | |
| | | borderColor | The color for the borders (if borders are enabled) | |
| |
| 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. | 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. |
