DialogBox

The DialogBox control is used to display dialog to the screen. It provides a number of common dialog functionality including:

• Typewriter (letter by letter) display of the text

• Multi-page display using an IEnumerable

• Task (async) support for logic after

• Force display of entire page and page advance input

• Input support using keyboard, mouse, and gamepads

Implementation Example

Like other FlatRedBall.Forms controls, the easiest way to create a DialogBox is to add a DialogBox instance into your screen. By default dialog boxes are visible, but you may want to mark yours as invisible in your Gum screen so it doesn't display in game until you need it to display. For most games only a single DialogBox instance is needed unless you intend to have multiple dialog boxes displayed at the same time.

To display a dialog box, use one of the Show methods. The simplest is to call Show with a string, as shown in the following code:

void CustomActivity(bool firstTimeCalled)
{
    if(InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.Enter))
    {
        var dialogBox = Forms.DialogBoxInstance;
        dialogBox.Show("Hello, I am a dialog box. Let's make same games!");
    }
}

Alternatively, multiple pages can be displayed using an IEnumerable such as a string array as shown in the following code snippet:

var dialogBox = Forms.DialogBoxInstance;

var pages = new string[]
{

    "Let me tell you why FlatRedBall.Forms is so great:",
    "It has tons of functionality out-of-the-box.",
    "You can do all of your layouts visually in Gum.",
    "It has MVVM support.",
    "Its appearance can be fully customized too!"
};

dialogBox.Show(pages);

Automatic Paging

DialogBox can display multiple pages through the Show and ShowAsync methods. Each string is treated as an entire page if it fits. A single string will be be broken up into multiple pages if it is too large.

The following code results in multiple pages automatically being set.

string textToDisplay = string.Empty;
for(int i = 0; i < 20; i++)
{
    textToDisplay += $"This is sentence number {i+1}. ";
}

dialog.ShowAsync(textToDisplay);

Automatic paging only applies if the number of lines is limited on the backing Text object. The default implementation of the DialogBox should automatically limit the number of lines.

The default implementation's Text property has the following relevant properties:

Note that if the Text property can extend indefinitely - either by allowing it through a Text Overflow Vertical Mode of Spill or by having a Height Units of Relative to Children.

ShowAsync for async Programming

The ShowAsync method returns a task which can be used to await for all pages to be shown and for the final page to be dismissed. A common usage of ShowAsync is in a scripted sequence. For example, a scripted sequence may combine dialog and player movement. Since the player can choose when to advance text, the amount of time that a DialogBox is displayed must be awaited. The following shows how code might be used to implement a scripted sequence which combines dialog being displayed and player movement.

var dialogBox = Forms.DialogBoxInstance;
await dialogBox.ShowAsync("Hello? Who is there?");
await MovePlayerTo(100, 50);
await dialogBox.ShowAsync("Oh, the room is empty, but I thought I heard a noise.");
await MovePlayerTo(300, 80);
await dialogBox.ShowAsync("No one is here either. Am I hearing things?");

Note that if your game requires advancing the dialog with the Keyboard or Xbox360GamePad, then the DialogBox must have its IsFocused property set to true. See the section on IsFocused for more information.

Multiple Pages Using ShowAsync

The DialogBox control provides a few approaches for showing multiple pages. As shown above, the Show method can take an array of strings. Alternatively, the ShowAsync method can be used to show one page at a time.

private async void ShowMultiplePages()
{
    var dialogBox = Forms.DialogBoxInstance;

    await dialogBox.ShowAsync("This is the first page of dialog.");
    await dialogBox.ShowAsync("This is a second page.");
    await dialogBox.ShowAsync("And a third page.");
    await dialogBox.ShowAsync("Finally a fourth page.");
}

This approach is useful if your DialogBox implementation has additional properties for each page of dialog. For example, a DialogBox can be modified in Gum to have a Text instance displaying the name of the person speaking.

Since the Show method exists on the standard DialogBox, it does not have a way to specify the speaker. We can access the visual on the DialogBox to modify the SpeakerTextInstance directly through the Visual property.

var dialogBox = Forms.DialogBoxInstance;
var dialogBoxVisual = dialogBox.Visual as DialogBoxRuntime;

dialogBoxVisual.SpeakerTextInstance.Text = "Captain";
await dialogBox.ShowAsync("Which way should we go?");

dialogBoxVisual.SpeakerTextInstance.Text = "Soldier";
await dialogBox.ShowAsync("...");

dialogBoxVisual.SpeakerTextInstance.Text = "Captain";
await dialogBox.ShowAsync("I know you are afraid to speak up, but don't worry! " +
    "We're a team, we need to work together to get through this.");

dialogBoxVisual.SpeakerTextInstance.Text = "Soldier";