Description

pjs.messageBox() displays a message box on the user's screen, waits for the user to click a button, and returns the text of the button that was clicked. The box can show an icon and up to five buttons, each with an optional keyboard shortcut. The message box is removed from the screen after the user responds, so it does not affect the screens displayed afterward.

The method accepts either a string, which is shown with a single centered OK button, or a configuration object that controls the title, icon, buttons, and styling.

Requires Profound.js 4.11.1 or later and Profound UI Version 6 Fix Pack 3.2 or later.

Syntax

pjs.messageBox(message)
pjs.messageBox(configuration)

Parameters

String Parameter

Message (String) - The text to display. A single centered button labeled OK, with the Enter key as its shortcut, is shown below the message.

Configuration Object

All properties are optional unless otherwise noted.

message (required) - The content of the message. This can be plain text or include HTML tags such as <br>. 1000 character limit.
title - The title of the message box. Defaults to Profound.js when omitted. 100 character limit.
icon - An icon displayed to the left of the message. By default no icon is displayed and the message spans the width of the box. Available icons: info, error, warning, question.
buttonAlign - How the buttons are aligned in the message box: left, center, or right. By default, multiple buttons are aligned to the right and a single button is centered.
cssclass - A CSS class name added to each button. Defaults to blueprint-button-secondary blueprint-defaults. 100 character limit.
bgcolor - The background color of each button, as a CSS color value. By default this is empty and the CSS class determines the color. 25 character limit. CSS classes and style sheets should be used in production code rather than hard-coded colors.
fgcolor - The text (foreground) color of each button, as a CSS color value. By default this is empty and the CSS class determines the color. 25 character limit.
width - The CSS width of each button. Defaults to 90px. 5 character limit.
buttons - An array of objects that configure the buttons. A maximum of 5 buttons can be specified. If omitted, a single OK button with the Enter shortcut is shown. Each button object can have the following properties:
- value (required) - The text displayed on the button, and the value returned by pjs.messageBox() when the user clicks it. 25 character limit.
- shortcut - The name of a keyboard key that acts as a shortcut for the button, such as Enter or Escape. Each button must have a unique shortcut.
- cssclass - Overrides the cssclass property above for this button.
- bgcolor - Overrides the bgcolor property above for this button.
- fgcolor - Overrides the fgcolor property above for this button.
- width - Overrides the width property above for this button.

Return Value

String - The value of the button the user clicked. When the string form or the default button is used, "OK" is returned.

Examples

Example 1: Show a Basic Message

Displays a message with a title and the default OK button. The module waits until the user clicks the button, then continues.

pjs.messageBox({
  title: "Message Box Example",
  message: "This is a basic message box."
});

// The module continues here after the user clicks OK

Example 2: Ask a Yes/No Question

Shows an error icon with two buttons and captures the user's choice. The Enter key selects Yes and the Escape key selects No. The choice variable is "Yes" or "No" depending on the button clicked.

var choice = pjs.messageBox({
  message: "This is an error message box with multiple choices. Do you want to continue?",
  icon: "error",
  buttonAlign: "center",
  buttons: [
    { value: "Yes", shortcut: "Enter" },
    { value: "No", bgcolor: "#b22222", shortcut: "Escape" }     // bgcolor overrides the default for this button only
  ]
});

if (choice === "Yes") {
  // Continue processing...
}

Example 3: Offer Three Choices

A question icon with three buttons. The buttons use the default right alignment.

var choice = pjs.messageBox({
  message: "This is a prompt with three buttons.",
  icon: "question",
  buttons: [
    { value: "One" },
    { value: "Two" },
    { value: "Three" }
  ]
});

console.log("The user clicked " + choice);

Example 4: Confirm a Destructive Action

A warning icon with OK and Cancel buttons, where the Cancel button is highlighted with a background color.

var choice = pjs.messageBox({
  message: "This is a warning. Are you sure?",
  icon: "warning",
  buttons: [
    { value: "OK", shortcut: "Enter" },
    { value: "Cancel", shortcut: "Escape", bgcolor: "darkred" }
  ]
});

if (choice === "OK") {
  // Perform the action...
}

Example 5: Show an Information Icon

A simple information box with the default title and button.

pjs.messageBox({
  message: "A simple information box.",
  icon: "info"
});

Example 6: Use the String Form

The simplest call: the string is displayed with the default title, Profound.js, and a centered OK button.

pjs.messageBox("This is a basic message box with the default title, Profound.js.");

RPG Equivalent

None.

pjs.messageBox()