Modals

Modal

Modals are the base class for dialogs, that are overlayed over the form.

Example

To create a custom modal, derive from abstract class Modal and set its properties.

var modal = new CustomModal();
await modal.ShowAsync();

// ...

class CustomModal : Modal
{
    public CustomModal()
    {
        Caption = "Title";

        Content = new Label("Content");
        Size = new Size(SizeValue.Relative(.2f), SizeValue.Relative(.1f));

        Result = DialogResult.Cancel;
    }
}

Properties

• Caption: The localizable text in the header of the dialog
• Content: The content component of the dialog
• BlockFormClosing: If the dialog cancels closing the application and has to be closed first
• OkAction: The KeyCommand to set Result to DialogResult.Ok and closes the dialog
• CancelAction: The KeyCommand to set Result to DialogResult.Cancel and closes the dialog
• Result: Protected; Is the DialogResult returned by method ShowAsync, when the dialog was closed
• Size: The size of the dialog

Methods

• ShowAsync: Opens and renders the dialog asynchronously and returns the Result when it was closed; Can set BlockFormClosing directly
• Close: Closes the dialog programmatically; Optionally sets a different Result
• ShowInternal: Virtual; Protected; Is called directly after the dialog was opened
• CloseInternal: Virtual; Protected; Is called directly after the dialog was closed
• ShouldCancelClose: Virtual; Protected; Is called directly before the dialog closes; Can cancel the operation

MessageBox

A messagebox with a caption, text, type, and selectable buttons.

Usage

Show an error messagebox:

await MessageBox.ShowErrorAsync("Error", "An error occurred.");

Show an information messagebox:

await MessageBox.ShowInformationAsync("Info", "This is an information.");

Show a messagebox with Yes and No buttons:

await MessageBox.ShowYesNoAsync("Question", "Do you want to continue?");

Show a messagebox with Yes, No, and Cancel buttons:

await MessageBox.ShowYesNoCancelAsync("Question", "Do you want to continue?");

Show a custom messagebox:

var messagebox = new MessageBox("Custom", "A messagebox appeared.",
    MessageBoxType.Warning, MessageBoxButton.No | MessageBoxButton.Cancel);
await messagebox.ShowAsync();

Localizations

The button captions are localizable with localization IDs:

• ImGui.Button.Ok: The localization ID for the Ok button; Falls back to english localization "Ok"
• ImGui.Button.Yes: The localization ID for the Yes button; Falls back to english localization "Yes"
• ImGui.Button.No: The localization ID for the No button; Falls back to english localization "No"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"

ComboInputBox

A simple modal with a combobox to select an item.

Usage

To show a combobox input:

await ComboInputBox.ShowAsync("Choice", "Choose an item from the list below.",
    new LocalizedString[] { "Item1", "Item2" }, "Item1");

Localizations

• ImGui.Button.Ok: The localization ID for the Ok button; Falls back to english localization "Ok"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"

InputBox

A simple modal with a textbox.

Usage

To show an inputbox:

await InputBox.ShowAsync("Input", "Input your text:", "Preset", "No value");

Localizations

• ImGui.Button.Ok: The localization ID for the Ok button; Falls back to english localization "Ok"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"

OpenFileDialog

A modal to select a file on the host's filesystem to open.

The native Windows OpenFileDialog can be accessed with WindowsOpenFileDialog.
If the host does not run Windows, it falls back to OpenFileDialog.

Usage

To retrieve a file selected by the user:

var ofd = new OpenFileDialog();

var result = await ofd.ShowAsync();
if (result != DialogResult.Ok)
    return;

var selectedPath = ofd.SelectedPath;

Properties

• InitialDirectory: The initial directory, from which the user starts navigating
• InitialFileName: The pre-selected file in InitialDirectory to allow for selection shortcuts
• FileFilters: A list of file filters to filter the file view by extensions; See "FileFilter" for more information
• SelectedPath: The path selected by the user, after they successfully closed the modal

Localizations

• ImGui.Button.Ok: The localization ID for the Ok button; Falls back to english localization "Ok"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"
• ImGui.FileDialog.Search: The localization ID for the search bar placeholder; Falls back to english localization "Search..."
• ImGui.FileDialog.Name: The localization ID for file name table header; Falls back to english localization "Name"
• ImGui.FileDialog.Type: The localization ID for file type table header; Falls back to english localization "Type"
• ImGui.FileDialog.DateModified: The localization ID for modified date table header; Falls back to english localization "Date Modified"
• ImGui.FileDialog.SelectedFile: The localization ID for selected file label; Falls back to english localization "File Name:"

FileFilter

A single file filter use in file dialogs.

Usage

To create single file filter:

var filter = new FileFilter("Image Files", "png", "jpg", "bin.image");

Properties

• Name: The localizable name of the filter
• Extensions: A list of extensions for this filter

SaveFileDialog

A modal to select a file on the host's filesystem to save.

The native Windows SaveFileDialog can be accessed with WindowsSaveFileDialog.
If the host does not run Windows, it falls back to SaveFileDialog.

Usage

To retrieve a file selected by the user:

var sfd = new SaveFileDialog();

var result = await sfd.ShowAsync();
if (result != DialogResult.Ok)
    return;

var selectedPath = sfd.SelectedPath;

Properties

• InitialDirectory: The initial directory, from which the user starts navigating
• SelectedPath: The path selected by the user, after they successfully closed the modal

Localizations

• ImGui.Button.Save: The localization ID for the Save button; Falls back to english localization "Save"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"
• ImGui.FileDialog.Search: The localization ID for the search bar placeholder; Falls back to english localization "Search..."
• ImGui.FileDialog.Name: The localization ID for file name table header; Falls back to english localization "Name"
• ImGui.FileDialog.Type: The localization ID for file type table header; Falls back to english localization "Type"
• ImGui.FileDialog.DateModified: The localization ID for modified date table header; Falls back to english localization "Date Modified"
• ImGui.FileDialog.SelectedFile: The localization ID for selected file label; Falls back to english localization "File Name:"
• ImGui.FileDialog.ReplaceFile.Caption: The localization ID for the replace file caption; Falls back to english localization "File exists"
• ImGui.FileDialog.ReplaceFile.Text: The localization ID for the replace file text; Falls back to english localization "Do you want to overwrite file {0}?"

SelectFolderDialog

A modal to select a folder on the host's filesystem.

Usage

To retrieve a folder selected by the user:

var sfd = new SelectFolderDialog();

var result = await sfd.ShowAsync();
if (result != DialogResult.Ok)
    return;

var selectedDirectory = sfd.Directory;

Localizations

• ImGui.Button.Ok: The localization ID for the Ok button; Falls back to english localization "Ok"
• ImGui.Button.Cancel: The localization ID for the Cancel button; Falls back to english localization "Cancel"
• ImGui.FileDialog.CreateFolder.Caption: The localization ID for create folder button and inputbox caption; Falls back to english localization "Create folder"
• ImGui.FileDialog.CreateFolder.Text: The localization ID for create folder inputbox text; Falls back to english localization "New folder name:"