Skip to content

DIALOGS.md

Latest commit

 

History

History
352 lines (269 loc) · 9.58 KB

DIALOGS.md

File metadata and controls

352 lines (269 loc) · 9.58 KB

Built-in Dialogs

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

Table of Contents

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

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

Navigation Keys

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