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 [2018/04/05 09:43] – created nightfox
+++ custom:javascript:lib:ddlightbarmenu.js [2020/04/04 15:42] – Added information about colors.itemColor and colors.selectedItemColor being able to be a string or an array. Also added information about the NumItems() and GetItem() functions, which can be replaced for a speed optimization. nightfox
@@ Line 1: / Line 1: @@
-====== DDLightbarMenu.js ======
+====== dd_lightbar_menu.js ======
-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]]''.\\
+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]]''.\\
 \\
-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.
+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.
-This script provides a class, DDLightbarMenu.  To create a new DDLightbarMenu object: new DDLightbarMenu(x, y, width, height);
+dd_lightbar_menu.js provides a class, DDLightbarMenu.  To create a new DDLightbarMenu object: new DDLightbarMenu(x, y, width, height);
 **DDLightbarMenu methods**
@@ Line 27: / Line 27: @@
 | 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() function" example 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.  See the "replacing the GetItem() function" example below. |
 **DDLightbarMenu properties**
@@ Line 32: / Line 34: @@
 | colors                       | object | An object that contains color codes (as strings) for various things.  Contains the following properties: itemColor, selectedItemColor, itemTextCharHighlightColor, borderColor |
 | 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. |
 | 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. |
@@ Line 42: / Line 45: @@
 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) |
+| itemColor                  | The color to use for non-selected items (current default is white on 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.  See the "Item color arrays" section below for more information. |
-| selectedItemColor          | The color to use for selected items (current default is blue on white) |
+| 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. |
 | borderColor                | The color for the borders (if borders are enabled) |
+| topBorderText              | Text to write in the top border (if borders are enabled).  This defaults to an empty string.  Synchronet color/attribute codes are supported. |
+| bottomBorderText           | Text to write in the bottom border (if borders are enabled).  This defaults to an empty string.  Synchronet color/attribute codes are supported. |
 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.
@@ Line 64: / Line 69: @@
 Example usage:
-  load("DDLightbarMenu.js");
+  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);
@@ Line 90: / Line 95: @@
   // 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:
@@ Line 105: / Line 122: @@
 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: "|"
+  });
-If you want hotkeys to be case-sensitive, you can set the hotkeyCaseSensitive property to true (it is false by default).  For example:
+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: "\1b",
+    selectedItemColor: "\1r\1" + "7" // Red with a grey background - This uses 2 strings concatenated because "\17" 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.
+** Replacing the NumItems() function **\\
+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 (either replace both of them, or neither of them).\\
+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;
+  };
+** Replacing the GetItem() function **\\
+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 GetItems() and NumItems()functions need to replaced together (either replace both of them, or neither of them).\\
+The GetItem() function needs to take a parameter for the item index (0-based), and it needs to return an item object compatible with DDLightbarMenu.  You can get a default item object by calling MakeItemWithRetval() or MakeItemWithTextAndRetval(), then change its text and retval properties as needed, then return the item object.  In the item object, the 'text' property is the text to display in the menu, and the 'retval' proprety is the value to return when the user chooses that item.\\
+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;
+    return menuItemObj; // The DDLightbarMenu object will use this when displaying the menu
+  };
 ===== See Also =====

Trace:

Log In

Search

Toolbox