rip_lightbar_menu.js is a loadable JavaScript file that provides a class, RIPLightbarMenu, which is a lightbar menu class for use in JavaScript scripts for Synchronet on RIP-capable terminals. It uses pixel-based RIP graphics commands rather than ANSI text, drawing the menu and scrollbar using RIPScrip vector drawing primitives.

Some functionality of the RIPLightbarMenu class was modeled after DDLightbarMenu (in dd_lightbar_menu.js) so that it supports many of the same features and is at least somewhat API-compatible with DDLightbarMenu. This means callers can often use the same code to drive either menu class (for example, Digital Distortion File Lister uses DDLightbarMenu for ANSI terminals and RIPLightbarMenu for RIP terminals, sharing much of the same callback and configuration logic). Shared features include the callback functions (OnItemSelect, ValidateSelectItem, OnItemNav), hotkey management, multi-select mode, the exitOnItemSelect flag, and overrideable NumItems()/GetItem() for dynamic item lists.

To create a new RIPLightbarMenu object:

var ripMenu = new RIPLightbarMenu(x, y, width, height, useRIPBorder);

The x, y, width, and height parameters are in RIP pixel coordinates (the RIP graphics viewport is 640×350 pixels). The useRIPBorder parameter is an optional boolean that controls whether a stylized 3D bevel border is drawn around the menu (defaults to true).

The RIPLightbarMenu class requires a RIP-capable terminal (such as SyncTerm). It uses the RIPScrollbar class (in rip_scrollbar.js) for scrollbar widgets:

• A vertical scrollbar appears automatically on the right side when the number of items exceeds the visible area (i.e., more items than can fit vertically).
• A horizontal scrollbar appears automatically at the bottom when any item's text is wider than the visible menu area. This allows the user to scroll left/right to see the full text of wide items. When horizontal scrolling is not needed (all items fit within the menu width), no horizontal scrollbar is shown and no space is reserved for it.

Both scrollbars are only shown when needed. When both are present, the menu correctly accounts for the space each scrollbar occupies (the vertical scrollbar narrows the item area, and the horizontal scrollbar reduces the number of visible item rows by one).

The menu supports keyboard navigation (Up, Down, PageUp, PageDown, Home, End, Enter, ESC) as well as Left/Right arrow keys for horizontal scrolling when items are wider than the menu. Mouse interaction is also supported: clicking on menu items to select them, and clicking on either scrollbar's arrow buttons, track areas, and thumb for vertical or horizontal scrolling.

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 exits the menu and returns null. When a scrollbar is needed, users can click the scrollbar's arrow buttons to scroll one item, click the track above/below the thumb for page up/down, or drag the thumb to a new position.

Menu items can have hotkeys set (via Add(), SetItemHotkey(), or AddItemHotkey()) that select the item immediately when the corresponding key is pressed. Hotkeys are case-insensitive by default (controlled by the hotkeyCaseSensitive property).

After showing the menu and getting a value from the user (using the GetVal() function), the lastUserInput property will have the user's last keypress.

rip_lightbar_menu.js requires the following loadable modules:

• sbbsdefs.js
• key_defs.js
• rip_lib.js — for generating RIPScrip command strings
• rip_scrollbar.js — for the scrollbar widget

RIPLightbarMenu methods

RIPLightbarMenu properties

To change the colors used for the menu items and border, modify the properties of the colors object:

ripMenu.colors.itemBg = RIP_COLOR_BLACK;
ripMenu.colors.itemFg = RIP_COLOR_WHITE;
ripMenu.colors.selectedBg = RIP_COLOR_BLUE;
ripMenu.colors.selectedFg = RIP_COLOR_WHITE;
ripMenu.colors.borderSurface = RIP_COLOR_LT_GRAY;

load("rip_lightbar_menu.js");
// Create a menu at pixel position (15, 64) with width 611 and height 286, with border
var ripMenu = new RIPLightbarMenu(15, 64, 611, 286, true);
// Add 20 items to the menu
for (var i = 0; i < 20; ++i)
  ripMenu.Add("Item " + +(i+1), i+1);
// Set up hotkey "s" for the 2nd item
ripMenu.SetItemHotkey(1, "s");
// Show the menu and get the chosen item from the user
var val = ripMenu.GetVal();
// val contains the return value of the selected item, or null if the user aborted

// Disabling auto-exit on selection (to use with OnItemSelect callback):
ripMenu.exitOnItemSelect = false;
ripMenu.OnItemSelect = function(pRetval, pSelected) {
  // Do something when an item is selected without leaving the menu
};

For large or dynamic lists, you can replace NumItems() and GetItem() so the menu references external data without copying it into the menu's internal array. This is the same pattern used by DDLightbarMenu.

Example (assuming ripMenu is a RIPLightbarMenu object and myList is an external data array):

ripMenu.NumItems = function() {
  return myList.length;
};
ripMenu.GetItem = function(pIdx) {
  var item = this.MakeItemWithRetval(pIdx);
  item.text = myList[pIdx].displayText;
  return item;
};

Override ValidateSelectItem() to control whether a user can select a given item:

ripMenu.ValidateSelectItem = function(pItemRetval) {
  if (someCondition(pItemRetval))
    return true;
  else
    return false;
};

Override OnItemSelect() to perform an action when an item is selected or toggled:

ripMenu.OnItemSelect = function(pItemRetval, pSelected) {
  // pSelected is true when the item is selected, false when de-selected
  // (de-selection only occurs in multi-select mode)
};

Override OnItemNav() to react when the user navigates to a different item (e.g., to update a detail pane):

ripMenu.OnItemNav = function(pOldItemIdx, pNewItemIdx) {
  // Update a description area based on the newly highlighted item
};

While RIPLightbarMenu is API-compatible with DDLightbarMenu for many common operations, there are some differences due to the fundamentally different display technology:

• Coordinates are in RIP pixels (640×350 viewport), not ANSI text cells.
• No numbered mode — RIPLightbarMenu always uses lightbar-style navigation (since it requires a RIP terminal).
• No ANSI fallback — DDLightbarMenu can fall back to numbered text input for non-ANSI terminals; RIPLightbarMenu requires RIP.
• Border is a 3D bevel rendered with RIP graphics, not ANSI box-drawing characters.
• Scrollbar is a graphical widget using RIPScrollbar, with arrow buttons, a proportional thumb, and mouse support — not a text-based scrollbar.
• Mouse support is always enabled — RIP mouse regions are always registered for menu items and the scrollbar.
• DDLightbarMenu features such as Draw(), Erase(), DrawPartial(), DrawPartialAbs(), SetBorderChars(), item color arrays, altItemColor/altSelectedItemColor, borderChars, borderEnabled, scrollbarEnabled, numberedMode, allowANSI, wrapNavigation, and ampersandHotkeysInItems are not present in RIPLightbarMenu.

For a real-world example where RIPLightbarMenu is used, see:

• Digital Distortion File Lister (ddfilelister.js): Uses RIPLightbarMenu when the terminal supports RIP, with NumItems/GetItem replacement, OnItemNav for updating the file description pane, additional quit keys for menu bar integration, and hotkey support.
• uselect_rip.js (uselect_rip.js): Synchronet's “Select Item” loadable module for RIP terminals, demonstrating basic RIPLightbarMenu usage with hotkeys.

• dd_lightbar_menu.js — the ANSI counterpart
• rip_scrollbar.js — the scrollbar widget used by RIPLightbarMenu
• custom:javascript:lib index