Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

--- custom:javascript:lib:ddlightbarmenu.js [2022/03/28 20:29] – Added a note about the callOnItemNavOnStartup property Nightfox
+++ custom:javascript:lib:ddlightbarmenu.js [2024/02/12 18:42] (current) – [Replacing the NumItems() and GetItem() functions] Mention textIsUTF8 nightfox
@@ Line 1: / Line 1: @@
 ====== dd_lightbar_menu.js ======
-dd_lightbar_menu.js is a loadable JavaScript file that provides a lightbar menu class for use in JavaScript scripts for Synchronet.  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.\\
+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.
-dd_lightbar_menu.js provides a class, DDLightbarMenu.  To create a new DDLightbarMenu object: new DDLightbarMenu(x, y, width, height);
+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;
 **DDLightbarMenu methods**
 ^ Name                          ^ Returns          ^ Usage                                        ^ Description^
-| 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.  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. |
+| 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 |
@@ Line 38: / Line 50: @@
 | 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**
@@ Line 57: / Line 80: @@
 | 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. |
 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):
@@ Line 62: / Line 87: @@
 | 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. |
-| 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. |
+| 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 |
@@ Line 97: / Line 123: @@
   var val = lbMenu.GetVal();
   // 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.pause();
   // 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:
@@ Line 140: / Line 166: @@
   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: "|",
@@ Line 150: / Line 188: @@
 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: "\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.
   });
@@ Line 162: / Line 200: @@
 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: "\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 ======
@@ Line 189: / Line 227: @@
     // 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 = "\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
   };
@@ Line 207: / Line 248: @@
     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;
     }
@@ Line 242: / Line 283: @@
   * 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
 ===== See Also =====

Trace:

Log In

Search

Toolbox