common/ui

Utilities for simple terminal-style dialogs in Sigma-based JavaScript environments.

The common/ui module provides three primary functions:

  1. winInputText(message) – Shows a short-text input dialog (up to ~100 chars).
  2. prompt(message) – Shows an unlimited-length input dialog.
  3. winSelectButtons(message, buttonNameArray) – Shows a multi-button chooser.

All functions are modal and return immediately with the user’s choice:

  • Confirmed text returns a string; cancellation returns null.
  • Button selection returns a 1-based index; dialog close (X) returns 0.

Core Features

  • HTML/line-break support: Message strings accept HTML and \n for layout.
  • Predictable return contracts: string | null for text, number for selections.
  • Lightweight & portable: Thin wrapper over Sigma runtime UI primitives.
  • Error signaling: Missing/invalid parameters call setError(...) and return safe defaults.

Usage Overview

  1. Ask for a short piece of text:

    var text = winInputText("Enter what you want to say:\nwhisper");
if (text !== null) print(text);

  2. Ask for longer text (no length limit):

    var notes = prompt("Paste your notes below:");
if (notes !== null) print(notes);

  3. Offer a set of actions via buttons:

    var idx = winSelectButtons(
  "Select what you need to do :<br/>Guess it",
  ["but01", "but02", "but03"]
);
if (idx === 0) {
  print("The popup button selection window has been canceled");
} else {
  print("The button number selected in the popup window is: " + idx);
}

API Highlights

  • winInputText(message: string): string | null
    • Opens a short-text input dialog (max ~100 chars). Returns entered text, or null on Cancel/invalid.
  • prompt(message: string): string | null
    • Opens an unlimited-length input dialog. Returns entered text, or null on Cancel.
  • winSelectButtons(message: string, buttonNameArray: string[]): number
    • Opens a button selector. Returns 0 if closed/canceled; otherwise a 1-based index of the clicked button.

(inner) prompt(message) → {string|null}

A window for inputting characters will pop up, the length of the input string is unlimited, and the current input information will be returned.

Example
// The title displayed in the pop-up window has an HTML format, that is, a newline character, and the title will automatically wrap.
var text = prompt("Enter what you want to say:\nwhisper");

// In the pop-up window, enter the content 'Hello, sigma!', click OK, get the input text information
print(text);

// If it executes successfully, it will return:
// Hello, sigma!


// If the user clicks "Cancel"
// Output: null
Parameters:
string message

The title information displayed in the pop-up window supports HTML format.
Returns:
string | null

Enter the text information in the pop-up window, click "OK", and return to the text information entered in the pop-up box. Enter text information in the pop-up window or do not enter any text information. Click "Cancel" to return null.

(inner) winInputText(message) → {string|null}

A window for entering characters is displayed, and the input information does not exceed 100 characters of text fields.

Example
// The title displayed in the pop-up window has an HTML format, that is, a newline character, and the title will automatically wrap.
var text = winInputText("Enter what you want to say:\nwhisper");

// In the pop-up window, enter the content 'Hello, sigma!', click OK, get the input text information
print(text);

// If it executes successfully, it will return:
// Hello, sigma!


// If the user clicks "Cancel"
// Output: null
Parameters:
string message

The title information displayed in the pop-up window supports HTML format.
Returns:
string | null

Enter the text information in the pop-up window, click "OK", and return to the text information entered in the pop-up box. Enter text information in the pop-up window or do not enter any text information. Click "Cancel" to return null.

(inner) winSelectButtons(message, buttonNameArray) → {number}

The pop-up button selects the window and the pop-up box disappears when the button is clicked.

Parameters:
string message

The title information displayed in the pop-up window supports HTML format.
Array buttonNameArray

A collection of button names that need to be displayed in the pop-up window.
Returns:
number

If the popup window is canceled (click the X in the upper right corner), the return value is 0. Otherwise it will return the sequence number of the selection button in the popup window.

Example:
// Define the message shown in the popup window
var message = 'Select what you need to do :\n Guess it';

// Define the button in the pop-up window, here define 3 buttons 'but01', 'but02', 'but03'
var buttonNameArray = ['but01', 'but02', 'but03'];

// Call the function and capture the selected button index
var index = winSelectButtons(message, buttonNameArray);

if (index != 0) {
print("The button number selected in the popup window is: " + index);
} else {
print("The popup button selection window has been canceled");
}

// Operation Result:
// If "but02" is clicked, the output will be:
The button number selected in the popup window is: 2