Message boxes

To display a message box to the user, use the MessageBox function. This function takes an object with a title, message and others. Here's the properties you'll have to specify:

• title: the title of the message box

• message: the message below the title

• buttons: an array of MessageBoxButtons (see below)

• image: the path to an image to display (optional).

• sound: a sound ID to play using the SoundBus kernel module

Besides the initial object, you specify two other arguments, the first being the parent PID, and the second deciding if the dialog is displayed as an overlay (or modal) on top of the parent. Here's the type of the MessageBox function and its interfaces:

interface MessageBoxData {
  title: string;
  message?: string;
  buttons: MessageBoxButton[];
  image?: string;
  sound?: string;
}

interface MessageBoxButton {
  caption: string;
  action: () => void;
  suggested?: boolean;
}

function MessageBox(data: MessageBoxData, parentPid: number, overlay?: boolean): Promise<void>;

The MessageBox function is asynchronous, you might want to await it.

Message box buttons

A button object has its own set of properties. Here they are:

• caption: the text to display on the button

• action: a function to call when the button is clicked. This callback can safely be asynchronous if necessary: ArcOS will await it.

• suggested: set it to true to make the button suggested (bold and accented)

ArcOS Sounds

These sounds can be used in the sound property of a message box:

• arcos.dialog.error - Error sound,

• arcos.dialog.warning - Warning sound,

• arcos.dialog.info - Info sound,

• arcos.notification - The ArcOS notification sound,

• arcos.system.logoff - Logoff sound,

• arcos.system.logon - Login sound,

• arcos.click - Navigation sound — not used anywhere in v7

Examples

Warning the user

await MessageBox({
  title: "Warning!",
  message: "The cache is out of date. Please re-run the caching program to revalidate them.",
  image: icons.WarningIcon,
  sound: "arcos.dialog.warning",
  buttons: [
    { caption: "Okay", action: () => {}, suggested: true },
  ],
}, this.pid, true);

Confirming a note deletion

await MessageBox({
  title: "Delete this note?",
  message: "Are you sure you want to delete this note? This cannot be undone.",
  image: icon,
  sound: "arcos.dialog.info",
  buttons: [
    { caption: "Cancel", action: () => {} },
    { caption: "Delete", action: () => {
      // do something here
    },
  ],
}, this.pid, true);