partey_workadventure/docs/maps/api-ui.md

{.section-title.accent.text-primary}
# API UI functions Reference

### Opening a popup

In order to open a popup window, you must first define the position of the popup on your map.

You can position this popup by using a "rectangle" object in Tiled that you will place on an "object" layer.

<div class="row">
    <div class="col">
        <img src="images/screen_popup_tiled.png" class="figure-img img-fluid rounded" alt="" />
    </div>
    <div class="col">
        <img src="images/screen_popup_in_game.png" class="figure-img img-fluid rounded" alt="" />
    </div>
</div>

```
WA.ui.openPopup(targetObject: string, message: string, buttons: ButtonDescriptor[]): Popup
```

*   **targetObject**: the name of the rectangle object defined in Tiled.
*   **message**: the message to display in the popup.
*   **buttons**: an array of action buttons defined underneath the popup.

Action buttons are `ButtonDescriptor` objects containing these properties.

*   **label (_string_)**: The label of the button.
*   **className (_string_)**: The visual type of the button. Can be one of "normal", "primary", "success", "warning", "error", "disabled".
*   **callback (_(popup: Popup)=>void_)**: Callback called when the button is pressed.

Please note that `openPopup` returns an object of the `Popup` class. Also, the callback called when a button is clicked is passed a `Popup` object.

The `Popup` class that represents an open popup contains a single method: `close()`. This will obviously close the popup when called.

```javascript
class Popup {
    /**
     * Closes the popup
     */
    close() {};
}
```

Example:

```javascript
let helloWorldPopup;

// Open the popup when we enter a given zone
helloWorldPopup = WA.room.onEnterZone('myZone', () => {
    WA.ui.openPopup("popupRectangle", 'Hello world!', [{
        label: "Close",
        className: "primary",
        callback: (popup) => {
            // Close the popup when the "Close" button is pressed.
            popup.close();
        }
    });
}]);

// Close the popup when we leave the zone.
WA.room.onLeaveZone('myZone', () => {
    helloWorldPopup.close();
});
```

### Add custom menu

```
WA.ui.registerMenuCommand(commandDescriptor: string, options: MenuOptions | ((commandDescriptor: string) => void)): Menu
```
Add a custom menu item containing the text `commandDescriptor` in the navbar of the menu.
`options` attributes can have three values :
- `(commandDescriptor: string) => void` : That value is deprecated. But will work like the second value.
- `{callback : (commandDescriptor: string) => void, allowApi?: boolean = true}` : A click on the custom menu will trigger the `callback`. The `allowApi` attribute is not used with the `callback`.
- `{iframe: string, allowApi?: boolean = true}` : A click on the custom menu will open the `iframe` inside the menu. The `allowApi` attribute allow the `iframe` to use the Scripting API.

Custom menu exist only until the map is unloaded, or you leave the iframe zone of the script.

<div class="row">
    <div class="col">
        <img src="images/custom-menu-navbar.png" class="figure-img img-fluid rounded" alt="" />
    </div>
    <div class="col">
        <img src="images/custom-menu-iframe.png" class="figure-img img-fluid rounded" alt="" />
    </div>
</div>

Example: 
```javascript
//Add a callback menu in a zone
let menu: undefined;
WA.room.onEnterZone('myZone', () => {
	menu = WA.ui.registerMenuCommand('menu test', {callback: () => {
	    WA.chat.sendChatMessage('test');
        }})
})
//Remove the callback menu when the player leave the zone
WA.room.onLeaveZone('myZone', () => {
    menu.remove();
})

//Add an iframe in the menu
WA.ui.registerMenuCommand('iframe', {iframe: 'myIframe.html', allowApi: true});
```

Please note that `registerMenuCommand` returns an object of the `Menu` class.

The `Menu` class contains a single method: `remove(): void`. This will obviously remove the menu when called.

```javascript
class Menu {
	/**
	* Remove the menu
	*/
	remove() {};
}
```



### Awaiting User Confirmation (with space bar)

```
WA.ui.displayActionMessage({
    message: string,
    callback: () => void,
    type?: "message"|"warning",
}): ActionMessage
```

Displays a message at the bottom of the screen (that will disappear when space bar is pressed).

<div class="col">
    <img src="images/trigger_message.png" class="figure-img img-fluid rounded" alt="" />
</div>

Example:

```javascript
const triggerMessage = WA.ui.displayActionMessage({
    message: "press 'space' to confirm",
    callback: () => {
        WA.chat.sendChatMessage("confirmed", "trigger message logic")
    }
});

setTimeout(() => {
    // later
    triggerMessage.remove();
}, 1000)
```

Please note that `displayActionMessage` returns an object of the `ActionMessage` class.

The `ActionMessage` class contains a single method: `remove(): Promise<void>`. This will obviously remove the message when called.

```javascript
class ActionMessage {
    /**
     * Hides the message
     */
    remove() {};
}
```