BeepFileDialog

Overview

BeepFileDialog provides a modern, user-friendly interface for file and folder selection that integrates seamlessly with the Beep Controls theming system. It offers advanced filtering capabilities, multi-select options, and customizable UI elements for a professional file selection experience.

Built on the BeepControl foundation, BeepFileDialog features theme integration, advanced file filtering, preview capabilities, recent files support, bookmark functionality, and comprehensive file type support. Perfect for document management applications, image editors, data import tools, and any application requiring sophisticated file selection.

Key Features

Visual Preview

File Selection Dialog

Basic Usage

// Create and configure a BeepFileDialog
var fileDialog = new BeepFileDialog();
fileDialog.Title = "Select a file";
fileDialog.Filter = "Text Files (*.txt)|*.txt|All Files (*.*)|*.*";
fileDialog.InitialDirectory = Environment.GetFolderPath(Environment.SpecialFolder.Documents);

// Show dialog and handle result
if (fileDialog.ShowDialog() == DialogResult.OK)
{
    string selectedFile = fileDialog.FileName;
    // Process the selected file
    ProcessFile(selectedFile);
}

// Configure for multiple file selection
var fileDialog = new BeepFileDialog
{
    Title = "Select multiple files",
    Filter = "Image Files (*.jpg;*.png;*.gif)|*.jpg;*.png;*.gif|All Files (*.*)|*.*",
    MultiSelect = true,
    InitialDirectory = Environment.GetFolderPath(Environment.SpecialFolder.MyPictures)
};

// Handle multiple files
if (fileDialog.ShowDialog() == DialogResult.OK)
{
    string[] selectedFiles = fileDialog.FileNames;
    foreach (string file in selectedFiles)
    {
      //  Console.WriteLine($"Selected: {Path.GetFileName(file)}");
    }
    
    // Process all selected files
    ProcessMultipleFiles(selectedFiles);
}

Properties

Core Properties

Navigation Properties

UI Properties

Methods

Examples

public class DocumentManager
{
    private BeepFileDialog fileDialog;

    public DocumentManager()
    {
        SetupFileDialog();
    }

    private void SetupFileDialog()
    {
        fileDialog = new BeepFileDialog
        {
            Title = "Open Document",
            Filter = CreateDocumentFilter(),
            MultiSelect = true,
            ShowPreview = true,
            ShowBookmarks = true,
            CheckFileExists = true,
            InitialDirectory = GetDocumentsPath()
        };

        // Add custom bookmarks
        fileDialog.AddBookmark(GetProjectPath(), "Current Project");
        fileDialog.AddBookmark(GetTemplatesPath(), "Templates");
        fileDialog.AddBookmark(GetArchivePath(), "Archive");
    }

    private string CreateDocumentFilter()
    {
        return "All Documents|*.txt;*.doc;*.docx;*.pdf;*.rtf|" +
               "Text Files (*.txt)|*.txt|" +
               "Word Documents (*.doc;*.docx)|*.doc;*.docx|" +
               "PDF Files (*.pdf)|*.pdf|" +
               "Rich Text (*.rtf)|*.rtf|" +
               "All Files (*.*)|*.*";
    }

    public List OpenDocuments()
    {
        var selectedFiles = new List();

        try
        {
            if (fileDialog.ShowDialog() == DialogResult.OK)
            {
                selectedFiles.AddRange(fileDialog.FileNames);
                
                // Update recent files
                UpdateRecentFiles(selectedFiles);
                
                // Validate files before processing
                var validFiles = ValidateFiles(selectedFiles);
                return validFiles;
            }
        }
        catch (Exception ex)
        {
            MessageBox.Show($"Error opening files: {ex.Message}", 
                "File Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }

        return selectedFiles;
    }

    private List ValidateFiles(List files)
    {
        var validFiles = new List();

        foreach (var file in files)
        {
            if (File.Exists(file))
            {
                // Check file size (limit to 50MB for this example)
                var fileInfo = new FileInfo(file);
                if (fileInfo.Length <= 50 * 1024 * 1024)
                {
                    validFiles.Add(file);
                }
                else
                {
                    MessageBox.Show($"File too large: {Path.GetFileName(file)}", 
                        "File Size Warning", MessageBoxButtons.OK, MessageBoxIcon.Warning);
                }
            }
        }

        return validFiles;
    }

    private void UpdateRecentFiles(List files)
    {
        // Implementation for recent files management
        foreach (var file in files)
        {
            // Add to recent files list (implementation depends on your app)
            RecentFilesManager.AddRecentFile(file);
        }
    }

    private string GetDocumentsPath() => 
        Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
    
    private string GetProjectPath() => 
        Path.Combine(GetDocumentsPath(), "Current Project");
    
    private string GetTemplatesPath() => 
        Path.Combine(GetDocumentsPath(), "Templates");
    
    private string GetArchivePath() => 
        Path.Combine(GetDocumentsPath(), "Archive");
}

public bool SaveDocument(string content, string suggestedName = "")
{
    var saveDialog = new BeepFileDialog
    {
        Title = "Save Document",
        Filter = "Text Files (*.txt)|*.txt|JSON Files (*.json)|*.json|XML Files (*.xml)|*.xml",
        DefaultExt = "txt",
        AddExtension = true,
        OverwritePrompt = true,
        ValidateNames = true,
        FileName = suggestedName
    };

    if (saveDialog.ShowDialog() == DialogResult.OK)
    {
        try
        {
            string filePath = saveDialog.FileName;
            
            // Validate the save location
            if (!IsValidSaveLocation(filePath))
            {
                MessageBox.Show("Cannot save to this location. Please choose a different folder.",
                    "Save Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
                return false;
            }

            // Create backup if file exists
            if (File.Exists(filePath))
            {
                CreateBackup(filePath);
            }

            // Save the file
            File.WriteAllText(filePath, content);
            
            // Update UI and recent files
            OnDocumentSaved(filePath);
            
            MessageBox.Show($"Document saved successfully to:\n{filePath}",
                "Save Complete", MessageBoxButtons.OK, MessageBoxIcon.Information);
            
            return true;
        }
        catch (Exception ex)
        {
            MessageBox.Show($"Error saving file: {ex.Message}",
                "Save Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }

    return false;
}

private bool IsValidSaveLocation(string filePath)
{
    try
    {
        string directory = Path.GetDirectoryName(filePath);
        
        // Check if directory exists and is writable
        if (!Directory.Exists(directory))
        {
            Directory.CreateDirectory(directory);
        }

        // Test write permissions
        string testFile = Path.Combine(directory, "write_test.tmp");
        File.WriteAllText(testFile, "test");
        File.Delete(testFile);
        
        return true;
    }
    catch
    {
        return false;
    }
}

private void CreateBackup(string filePath)
{
    try
    {
        string backupPath = filePath + ".backup";
        File.Copy(filePath, backupPath, true);
    }
    catch (Exception ex)
    {
        // Log backup failure but don't prevent save
      //  Console.WriteLine($"Failed to create backup: {ex.Message}");
    }
}

private void OnDocumentSaved(string filePath)
{
    // Update application state
    CurrentFilePath = filePath;
    HasUnsavedChanges = false;
    
    // Update recent files
    RecentFilesManager.AddRecentFile(filePath);
    
    // Update window title
    UpdateWindowTitle();
}

Theming

BeepFileDialog provides comprehensive theming support with automatic application of theme colors:

var fileDialog = new BeepFileDialog
{
    Theme = "DarkTheme",
    UseThemeColors = true
};

// Theme automatically applies:
// - DialogBackColor: Main dialog background
// - DialogForeColor: Text colors
// - ButtonColors: Action button styling
// - BorderColors: Panel and control borders
// - SelectionColors: File selection highlighting

Dialog-Specific Theming

• Panel backgrounds - Sidebar, preview, and main panel theming
• File list styling - Selection colors and hover effects
• Button theming - Action buttons with theme colors
• Toolbar styling - Navigation and view controls

Best Practices

🎯 User Experience

• Appropriate filters: Set meaningful file type filters to guide user selection
• Initial directory: Start in the most relevant folder for the user's context
• Preview panel: Enable preview for better file identification
• Bookmarks: Add frequently used locations as bookmarks

🔧 Implementation

• File validation: Always validate selected files before processing
• Error handling: Implement proper error handling for file operations
• Performance: Consider file size limits for preview and processing
• Permissions: Check file access permissions before operations

🛡️ Security

• Path validation: Validate file paths to prevent directory traversal
• File type checking: Verify file types beyond extension checking
• Sandbox operations: Consider sandboxing file operations