YngveHestem.FileDialog.GumMonoGame 1.0.0

YngveHestem.FileDialog.GumMonoGame

A MonoGame and Gum-based file dialog implementation that provides cross-platform file and folder selection dialogs for MonoGame applications.

Features

• OpenFileDialog: Browse and select files with optional file type filtering
• OpenFolderDialog: Browse and select folders
• SaveFileDialog: Save files with custom naming
• Cross-platform: Works on any platform supported by MonoGame
• Customizable: Supports theming through Gum visual factory
• Async operations: Non-blocking folder navigation and file operations

Contents

Base Class

• FileDialog: Abstract base class for all file dialogs
  • StorageProviders: Observable collection of available storage locations
  • OpenDialog(): Display the dialog to the user
  • CloseDialog(): Programmatically close the dialog
  • FilterStorageItems(): Virtual method to override and filter displayed files/folders
  • Update(): Static method that must be called from Game.Update() to process UI updates on the game thread

Dialog Implementations

• OpenFileDialog: Browse and select a single file

  • AllowedFileTypes: Property to restrict selectable file extensions (e.g., [".txt", ".pdf"])
  • FileSelected: Event triggered when a file is selected

• OpenFolderDialog: Browse and select a single folder

  • FolderSelected: Event triggered when a folder is selected

• SaveFileDialog: Browse and save a file with a chosen name

  • FileSaved: Event triggered when a file is saved

Configuration & Support Classes

• FileDialogOptions and variants (OpenFileDialogOptions, OpenFolderDialogOptions, SaveFileDialogOptions): Configure dialog behavior and appearance
• FileDialogVisualFactory: Creates UI elements (can be subclassed for custom theming)

Getting Started

Basic Setup

1. Initialize a dialog:

   var openFileDialog = new OpenFileDialog("Select a file");
   openFileDialog.AllowedFileTypes = new List<string> { ".txt", ".png", ".jpg" };
   openFileDialog.FileSelected += (dialog, file) =>
   {
    Console.WriteLine($"Selected: {file.Name}");
   };
   

2. Add storage providers: In this example, YngveHestem.Storage.Local is used as storage provider. See below for more info.

   var localProvider = new LocalStorageProvider();
   var folder = await localProvider.TryGetFolderAsync(Environment.GetFolderPath(
    Environment.SpecialFolder.MyDocuments));
   
   if (folder != null)
   {
    openFileDialog.StorageProviders.Add(folder);
   }
   

3. Display the dialog:

   openFileDialog.OpenDialog();
   

Important: Call Update() in Game.Update()

The dialog uses a main-thread dispatcher to ensure all UI updates happen on the game thread. You must call FileDialog.Update() from your MonoGame Game class's Update() method (including neccessarry set up of Gum.MonoGame):

public class MyGame : Game
{
 protected override void Update(GameTime gameTime)
 {
 GumService.Default.Update(this, gameTime);
 
 // Process pending file dialog UI updates
 GumMonoGame.FileDialog.Update();

 base.Update(gameTime);
 }
}

Without this call, file dialogs will not function correctly and UI updates may not be processed.

More samples

See the samples in the repository for a complete example.

Customization

The file dialogs work out of the box with a default appearance and behavior—you only need to provide at least one storage location via StorageProviders. The dialogs are fully functional for basic file and folder selection tasks.

However, to make the dialogs fit seamlessly into your game's visual style, you can customize them extensively using the FileDialogOptions classes:

• FileDialogOptions: Base configuration for all dialogs

  • VisualFactory: Customize the appearance and layout of UI elements
  • DoubleClickSeconds: Adjust double-click detection timing
  • ShowAddNewFolderButton: Show/hide folder creation button
  • HideStorageProviderListIfNotMoreThan1: Auto-hide provider list when there's only one
  • Button and message box text customization

• OpenFileDialogOptions: File-specific customization (extends FileDialogOptions)

• OpenFolderDialogOptions: Folder-specific customization (extends FileDialogOptions)

• SaveFileDialogOptions: Save-specific customization (extends FileDialogOptions)

By leveraging the VisualFactory in these options, you can create custom Gum layouts and themes that match your game's aesthetic perfectly.

Dependencies used

• Gum.MonoGame: Gum integration for MonoGame (NuGet)
• YngveHestem.Storage.Abstractions: Abstract interfaces for storage operations (NuGet)

Integration with Storage Providers

This library works seamlessly with the Storage abstraction layer. You can use different storage providers (local, WebDAV, cloud, etc.) as sources for your file dialogs (or create your own):

using YngveHestem.Storage.Local;

var provider = new LocalStorageProvider();
var documentsFolder = await provider.TryGetFolderAsync("/path/to/documents");

var dialog = new OpenFileDialog("Open Document");
dialog.StorageProviders.Add(documentsFolder);
dialog.OpenDialog();

Known storage provider-implementations at the moment:

• YngveHestem.Storage.Local: Local file system provider (NuGet)
• YngveHestem.Storage.WebDAV: WebDAV storage provider (NuGet)

If you have created or know of a supported implementation of the Abstractions and want it listed. Create an issue or pull-request.

License

See LICENSE file in the repository root.