> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameUiShowMessageDialogAsync

> XGameUiShowMessageDialogAsync

# XGameUiShowMessageDialogAsync

Displays UI for a customizable message dialog. The index of the button pressed by the user is contained in the result.

## Syntax

```cpp theme={null}
HRESULT XGameUiShowMessageDialogAsync(  
         XAsyncBlock* async,  
         const char* titleText,  
         const char* contentText,  
         const char* firstButtonText,  
         const char* secondButtonText,  
         const char* thirdButtonText,  
         XGameUiMessageDialogButton defaultButton,  
         XGameUiMessageDialogButton cancelButton  
)  
```

### Parameters

*async*   \_In\_<br />Type: [XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock)

A pointer to the [XAsyncBlock](/reference/system/xasync/structs/xasyncblock) that is passed to [XAsyncRun](/reference/system/xasync/functions/xasyncrun).

*titleText*   \_In\_<br />Type: char\*

The text title of the message dialog.

*contentText*   \_In\_<br />Type: char\*

The text displayed inside of the message dialog.

*firstButtonText*   \_In\_opt\_<br />Type: char\*

The text displayed on the first button of the message dialog.

*secondButtonText*   \_In\_opt\_<br />Type: char\*

The text displayed on the second button of the message dialog.

*thirdButtonText*   \_In\_opt\_<br />Type: char\*

The text displayed on the third button of the message dialog.

*defaultButton*   \_In\_<br />Type: [XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton)

Indicates which button is selected by default when the message dialog is first displayed.

*cancelButton*   \_In\_<br />Type: [XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton)

Indicates which button represents the cancel action.

### Return value

Type: HRESULT

HRESULT success or error code of the async call.

To get the result, call [XGameUiShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult) inside the *XAsyncBlock* callback or after the *XAsyncBlock* is complete.

## Remarks

Like other **XGameUI\*** functions, **XGameUiShowMessageDialogAsync** renders it's UI outside of the title partition, and the result is composited with the title's output before each frame is sent to the display device. This means that **XGameUiShowMessageDialogAsync** can be used to present information to a user whether or not the game is even rendering.

Calling for UI will cause your game to enter *constrained mode*. In constrained mode your title will receive fewer system resources while it is in the background of the UI that has been called for. To learn more about constrained mode and other operational modes for your title read [XBOX Game Life Cycle (NDA topic)](/build/console-features/console-workflows/xbox-game-life-cycle).

The following example code illustrates using this method in a development scenario to create blocking UI waiting for input. This can be particularly useful to pause current execution at the location of a crashing failure and either reporting the crash location or prompting the developer to attach a debugger.

```cpp theme={null}
if (FAILED(XGameRuntimeInitialize()))  
    return 1;

XTaskQueueHandle queue;
DX::ThrowIfFailed(
    XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Immediate, &queue)  
);

XAsyncBlock* ab = new XAsyncBlock;
ZeroMemory(ab, sizeof(XAsyncBlock));
ab->queue = queue;

// show dialog, wait for completion, get result.

XGameUiMessageDialogButton button;
if (SUCCEEDED(XGameUiShowMessageDialogAsync(ab, u8"Title String", u8"This is content text",
                                            u8"Option #1", u8"Option #2", u8"Option #3",
                                            XGameUiMessageDialogButton::First,
                                            XGameUiMessageDialogButton::Third)) &&
    SUCCEEDED(XAsyncGetStatus(ab, true)) &&
    SUCCEEDED(XGameUiShowMessageDialogResult(ab, &button)))  
{
    DoSomethingWithResponse(button);  // set breakpoint here to investigate
}
```

## Requirements

**Header:** XGameUI.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, Steam Deck, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [Asynchronous programming design goals and improvements](/build/core-features/common/async/async-whitepaper)

## See also

[XGameUI](/reference/system/xgameui/xgameui_members)<br />[XGameUIShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult)<br />[XBOX Game Life Cycle (NDA topic)](/build/console-features/console-workflows/xbox-game-life-cycle)


## Related topics

- [XGameUiShowMessageDialogResult](/reference/system/xgameui/functions/xgameuishowmessagedialogresult.md)
- [XGameUiMessageDialogButton](/reference/system/xgameui/enums/xgameuimessagedialogbutton.md)
- [XGameUiShowMessageDialogUiCallback](/reference/system/xgameui/functions/xgameuishowmessagedialoguicallback.md)
- [XGameUiSetMessageDialogUiResponse](/reference/system/xgameui/functions/xgameuisetmessagedialoguiresponse.md)
- [XGameUiUiCallbacks](/reference/system/xgameui/structs/xgameuiuicallbacks.md)