Immerse

Dialogs

A world space user interface message box

Description

The ImmerseSDK provides built-in support for displaying messages and information to a user via a 2D dialog box. Applications for this feature include error messages or 'welcome' messages when a user joins a scene.

There are a number of layout options available for arranging content inside a dialog box:

OptionDescription
SingleColumnSingle column text with an optional image
DoubleColumnDouble column text with optional image(s)
NotificationNotification (Error, Warning, etc.) message. Each type has a specific notification icon.
ProgressMessageShows a progress message. You can update the progress amount and text in code every frame.

A dialog box can be created in two different ways:

  1. By adding a component to the scene which will create the dialog when it is enabled
  2. Directly via code

When a dialog is displayed, it is rendered over the top of all content, with the background scene "faded out" to black. All other interactions are disabled.

A dialog can be dismissed by clicking the "Close" button, or if it was displayed with a timeout option, it will automatically close when the time runs out.

Examples Of Layouts And Options

Single Column Dialog Box With Text

Single Column Dialog Box With Text And An Image

Single Column Dialog Box With An image And A Timeout

Double Column Dialog With Text

Double Column Dialog With Text And A Single Image

Double Column Dialog With Two Images And Text

Progress Dialog

How To Implement

When the SDK initialises, it will automatically create a service called MessageDisplayService This service is the central hub for managing dialogs and keeps a list of all the currently active dialogs.

📘

Immerse SDK Class Library

More detail available in MessageDisplayService .

Priority

Each message has a priority when created and the service will display them, sorted by this priority (highest one first). If two messages have the same priority, then they will appear in the order they were added to the list. In general, keep the priority at the default value of -1 unless it really is important.

Displaying A Message By Using A Component In The Scene

  1. Create a new GameObject. This object's enabled state will control the visibility of the dialog - when it becomes enabled, it shows the dialog.
  • Add the OnEnabledShowSingleColumnDialog or the OnEnabledShowDoubleColumnDialog component .
  • In the Unity Inspector View, edit the text and optional image fields.
  • If the object is left enabled, the dialog will show when the scene is loaded, otherwise, disable the object and enable it when the dialog needs to be displayed.

📘

Immerse SDK Class Library

More detail available in:

OnEnabledShowSingleColumnDialog

OnEnabledShowDoubleColumnDialog

Displaying A Message Using Code

  1. Create a new instance of MessageDisplayDialogData by using one of it's overloaded Create() methods.
MessageDisplayDialogData dialogData = MessageDisplayDialogData.CreateMessageDialog(
                    title,
                    mainText,
                    mainImage,
                    mainImageText,
                    DurationInSeconds,
                    Priority,
                    null,
                    null);

📘

Immerse SDK Class Library

More detail in MessageDisplayDialogData

  1. Optionally set some properties on the new data instance:
    • Add a callback to OnClose if notification is required when the dialog is hidden
    • Set ShouldTrackCamera to true if the dialog should follow the VR user's head
    • For progress dialogs, keep a reference to this data and use it to update the current progress and/or text every frame.
    • Other options are set out below and in the class documentation
  2. Show the dialog by using the MessageDisplayService
var messageDisplayService = SingletonManager.Get<MessageDisplayService>();
messageDisplayService.Show(dialogData);
  1. Optionally, if the dialog needs to be hidden sooner, use the service.
var messageDisplayService = SingletonManager.Get<MessageDisplayService>();
messageDisplayService.Hide(dialogData);

📘

Immerse SDK Class Library

More detail in:

MessageDisplayService

ImmerseSDK.UI.MessageDisplay.MessageDisplayDialogData

Options

There are many options for configuring how a dialog looks, behaves and is closed (including which buttons to show).

Please see MessageDisplayDialogData for more information on this.

Unity iconTry out this component in the Examples project

Examples (menu) > UI > Load Dialogs Example

(Learn more about the Examples project)

Updated 4 months ago

Dialogs


A world space user interface message box

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.