> For the complete documentation index, see [llms.txt](https://docs.sacruda.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sacruda.nl/developers/sacruda-apis/message-boxes.md).

# 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:

```typescript
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>;
```

{% hint style="info" %}
The `MessageBox` function is asynchronous, you might want to await it.
{% endhint %}

### 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: Sacruda will await it.
* `suggested`: set it to true to make the button suggested (bold and accented)

### Sacruda 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

{% tabs %}
{% tab title="Warning the user" %}

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

{% endtab %}

{% tab title="Confirming a note deletion" %}

```javascript
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);
```

{% endtab %}
{% endtabs %}
