Built-in Dialogs

SharpConsoleUI provides built-in dialog windows for common tasks like file selection and theme switching.

File Dialogs
System Dialogs
- Theme Selector

File Dialogs

All file dialogs are async methods on ConsoleWindowSystem and support optional parent windows for modal behavior.

Folder Picker

Select a directory from the file system.

// Basic usage
string? selectedFolder = await windowSystem.ShowFolderPickerDialogAsync();

if (selectedFolder != null)
{
    Console.WriteLine($"Selected: {selectedFolder}");
}

// With starting path
string? folder = await windowSystem.ShowFolderPickerDialogAsync(
    startPath: "/home/user/documents"
);

// As modal dialog with parent window
string? folder = await windowSystem.ShowFolderPickerDialogAsync(
    startPath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
    parentWindow: mainWindow
);

Parameters:

startPath (optional): Initial directory to display
parentWindow (optional): Parent window for modal behavior

Returns: Task<string?> - Selected directory path, or null if cancelled

File Picker (Open)

Select an existing file from the file system.

// Basic usage
string? selectedFile = await windowSystem.ShowFilePickerDialogAsync();

// With starting path
string? file = await windowSystem.ShowFilePickerDialogAsync(
    startPath: "/home/user/documents"
);

// With file filter (extension filter)
string? file = await windowSystem.ShowFilePickerDialogAsync(
    startPath: "/home/user/documents",
    filter: ".txt"
);

// As modal dialog
string? file = await windowSystem.ShowFilePickerDialogAsync(
    startPath: Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
    filter: ".log",
    parentWindow: mainWindow
);

Parameters:

startPath (optional): Initial directory to display
filter (optional): File extension filter (e.g., ".txt", ".log")
parentWindow (optional): Parent window for modal behavior

Returns: Task<string?> - Selected file path, or null if cancelled

Save File Dialog

Select a location and filename for saving a file.

// Basic usage
string? savePath = await windowSystem.ShowSaveFileDialogAsync();

// With starting path and default filename
string? savePath = await windowSystem.ShowSaveFileDialogAsync(
    startPath: "/home/user/documents",
    defaultFileName: "output.txt"
);

// With file filter
string? savePath = await windowSystem.ShowSaveFileDialogAsync(
    startPath: "/home/user/documents",
    filter: ".log",
    defaultFileName: "app.log"
);

// As modal dialog
string? savePath = await windowSystem.ShowSaveFileDialogAsync(
    startPath: Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
    filter: ".txt",
    defaultFileName: "document.txt",
    parentWindow: mainWindow
);

Parameters:

startPath (optional): Initial directory to display
filter (optional): File extension filter (e.g., ".txt", ".log")
defaultFileName (optional): Pre-filled filename
parentWindow (optional): Parent window for modal behavior

Returns: Task<string?> - Selected save path, or null if cancelled

System Dialogs

System dialogs provide access to settings, configuration, and application information. These dialogs are accessible through the Start Menu > System category or can be called programmatically.

Settings Dialog

Shows a dialog with links to various configuration dialogs (Theme, Performance, About).

// Show settings dialog
using SharpConsoleUI.Dialogs;

SettingsDialog.Show(windowSystem);

// Or as modal to a parent window
SettingsDialog.Show(windowSystem, parentWindow);

The settings dialog provides access to:

Change Theme... - Opens Theme Selector Dialog
Performance Settings... - Opens Performance Dialog
About... - Opens About Dialog

Navigation:

Arrow keys to navigate options
Enter or double-click to select
Escape to close

Theme Selector

Display a dialog for selecting and switching themes at runtime.

// Show theme selector dialog
using SharpConsoleUI.Dialogs;

windowSystem.ShowThemeSelectorDialog();

// Or as modal to a parent window
ThemeSelectorDialog.Show(windowSystem, parentWindow);

The theme selector dialog displays all registered themes and allows the user to switch between them. The selected theme is applied immediately to all windows.

Available Built-in Themes:

Classic - Navy blue windows with traditional styling
ModernGray - Modern dark theme with gray color scheme
DevDark - Dark developer theme (requires DeveloperTools plugin)

Navigation:

Arrow keys to select theme
Enter or double-click to apply
Escape to close

Performance Dialog

Configure performance and rendering settings.

// Show performance configuration dialog
using SharpConsoleUI.Dialogs;

PerformanceDialog.Show(windowSystem);

// Or as modal to a parent window
PerformanceDialog.Show(windowSystem, parentWindow);

The performance dialog allows runtime configuration of:

Performance Metrics Display - Toggle FPS and metrics overlay
Frame Rate Limiting - Toggle frame rate limiting on/off
Target FPS - Set target FPS (30, 60, 120, or 144)

Runtime Methods:

// Toggle performance metrics programmatically
windowSystem.SetPerformanceMetrics(true);
bool enabled = windowSystem.IsPerformanceMetricsEnabled();

// Toggle frame rate limiting
windowSystem.SetFrameRateLimiting(false);  // Unlimited FPS
bool limited = windowSystem.IsFrameRateLimitingEnabled();

// Set target FPS
windowSystem.SetTargetFPS(30);
int fps = windowSystem.GetTargetFPS();

Navigation:

Arrow keys to navigate options
Enter or double-click to toggle/configure
Escape to close

About Dialog

Display application information, version, and loaded plugins.

// Show about dialog
using SharpConsoleUI.Dialogs;

AboutDialog.Show(windowSystem);

// Or as modal to a parent window
AboutDialog.Show(windowSystem, parentWindow);

The about dialog displays:

Application name and version
Description and core features
Author and license information
List of loaded plugins (if any)

Navigation:

Enter or Escape to close

Complete Example

using SharpConsoleUI;
using SharpConsoleUI.Builders;
using SharpConsoleUI.Controls;
using SharpConsoleUI.Drivers;

var windowSystem = new ConsoleWindowSystem(new NetConsoleDriver(RenderMode.Buffer));

var mainWindow = new WindowBuilder(windowSystem)
    .WithTitle("File Dialog Example")
    .WithSize(80, 25)
    .Centered()
    .Build();

mainWindow.AddControl(
    Controls.Button("Open File")
        .OnClick(async (sender, e, window) =>
        {
            var filePath = await windowSystem.ShowFilePickerDialogAsync(
                startPath: Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
                filter: ".txt",
                parentWindow: window
            );

            if (filePath != null)
            {
                window.AddControl(new MarkupControl(new List<string>
                {
                    $"[green]Selected file:[/] {filePath}"
                }));
            }
        })
        .Build()
);

mainWindow.AddControl(
    Controls.Button("Save File")
        .OnClick(async (sender, e, window) =>
        {
            var savePath = await windowSystem.ShowSaveFileDialogAsync(
                startPath: Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
                filter: ".log",
                defaultFileName: "app.log",
                parentWindow: window
            );

            if (savePath != null)
            {
                // Save your file here
                window.AddControl(new MarkupControl(new List<string>
                {
                    $"[green]File will be saved to:[/] {savePath}"
                }));
            }
        })
        .Build()
);

mainWindow.AddControl(
    Controls.Button("Select Folder")
        .OnClick(async (sender, e, window) =>
        {
            var folderPath = await windowSystem.ShowFolderPickerDialogAsync(
                startPath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
                parentWindow: window
            );

            if (folderPath != null)
            {
                window.AddControl(new MarkupControl(new List<string>
                {
                    $"[green]Selected folder:[/] {folderPath}"
                }));
            }
        })
        .Build()
);

mainWindow.AddControl(
    Controls.Button("Change Theme")
        .OnClick((sender, e, window) =>
        {
            windowSystem.ShowThemeSelectorDialog();
        })
        .Build()
);

windowSystem.AddWindow(mainWindow);
windowSystem.Run();

Best Practices

Always use await: File dialogs are asynchronous operations
Check for null: User can cancel the dialog, always check return value
Use parentWindow: Pass parent window for proper modal behavior
Provide startPath: Help users by starting in a relevant directory
Use filters: When appropriate, filter files by extension
Handle exceptions: Wrap dialog calls in try-catch for file system errors

All file dialogs support these keyboard shortcuts:

Arrow Keys: Navigate files/folders
Enter: Select current item / Open folder
Backspace: Go to parent directory
Escape: Cancel dialog
Type: Quick search by typing filename

Back to Main Documentation

Built-in Dialogs

Table of Contents

File Dialogs

Folder Picker

File Picker (Open)

Save File Dialog

System Dialogs

Settings Dialog

Theme Selector

Performance Dialog

About Dialog

Complete Example

Best Practices

Navigation Keys