Add support for Android native file dialogs

[llama-nl]

Describe the project you are working on

I am working on enhancing the mobile usability of applications developed with Godot Engine 4.4+ by improving the file handling experience. While Godot provides a FileDialog that works well on desktop platforms, its design and functionality are less intuitive for mobile devices like Android and iOS. On mobile, users expect interactions to be more streamlined and native, such as using the system's file manager for file access.

The goal of this project is to integrate native file access functionality into Godot for Android and iOS platforms. This would allow developers to leverage the platform-specific file managers, resulting in a more seamless and familiar experience for users.

Describe the problem or limitation you are having in your project

The current FileDialog in Godot is designed primarily for desktop platforms and does not translate well to mobile devices. On mobile platforms, the FileDialog is non-intuitive, aesthetically unappealing, and lacks features users expect from a mobile file manager. Additionally, it does not integrate with native mobile file managers, limiting the user's ability to browse and manage files through the OS-standard file system interface.

Key limitations include:

1. The FileDialog does not follow native UI conventions for Android and iOS, making it look and feel out of place.
2. Lack of integration with mobile-specific features like permission handling, cloud storage access (e.g., Google Drive, iCloud), and external storage.
3. User experience issues like difficulty in navigation and selecting files compared to a mobile file manager.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The feature I am proposing is to integrate native file access for Android and iOS platforms within Godot 4.4+. This means the ability for Godot-based applications to invoke the native file manager on mobile devices, allowing users to browse and select files through a system-native interface.

Benefits of this enhancement:

1. Native User Experience: Provides a familiar and intuitive file access interface that adheres to platform-specific UI/UX guidelines, offering a more polished and cohesive experience.
2. Mobile-Specific Features: Allows access to mobile-specific file management features, such as cloud storage integration (Google Drive, iCloud), external storage, and handling permissions efficiently.
3. Consistency with Other Mobile Apps: Users will be able to interact with files in a way they are used to in other mobile applications, increasing overall satisfaction and reducing the learning curve.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

The proposal involves implementing platform-specific code that hooks into Android's Storage Access Framework and iOS's UIDocumentPickerViewController. Below is a breakdown of how the implementation could work:

Android Implementation (Java + Godot GDExtension)
On Android, the Storage Access Framework (SAF) can be invoked to present the system file picker.

public void openFileManager() {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("*/*");
    startActivityForResult(intent, FILE_REQUEST_CODE);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == FILE_REQUEST_CODE && resultCode == Activity.RESULT_OK) {
        Uri uri = data.getData();
        // Pass the selected file's URI back to Godot
        GodotLib.calldeferred(instance_id, "_on_file_selected", new Object[] { uri.toString() });
    }
}

In Godot, we can write a simple GDExtension that will invoke the file picker and return the selected file URI back to the script.

Also see: https://developer.android.com/guide/topics/providers/document-provider

iOS Implementation (Objective-C + GDExtension)

On iOS, we can use UIDocumentPickerViewController to access the system file picker.

- (void)openFileManager {
    UIDocumentPickerViewController *picker = [[UIDocumentPickerViewController alloc] initWithDocumentTypes:@[@"public.data"] inMode:UIDocumentPickerModeImport];
    picker.delegate = self;
    [self presentViewController:picker animated:YES completion:nil];
}

- (void)documentPicker:(UIDocumentPickerViewController *)controller didPickDocumentAtURL:(NSURL *)url {
    // Pass the selected file's URL back to Godot
    godot::Dictionary dict;
    dict["path"] = [url path];
    _on_file_selected(dict);
}

Also see: https://developer.apple.com/documentation/uikit/uidocumentpickerviewcontroller

In GDScript, developers will have access to a new method open_native_file_dialog():

extends Node

func open_native_file_dialog():
    if OS.has_feature("mobile"):
        # Invoke platform-specific file manager
        NativeFileAccess.open()
    else:
        # Fallback to Godot's built-in FileDialog for desktop platforms
        var dialog = FileDialog.new()
        dialog.popup_centered()

func _on_file_selected(file_path: String):
    print("Selected file:", file_path)

1. User presses a "Browse" button.
2. The system-native file picker appears (either Android’s SAF or iOS’s Document Picker).
3. After the user selects a file, the file path or URI is passed back to Godot for further processing.

If this enhancement will not be used often, can it be worked around with a few lines of script?

No, this enhancement cannot be worked around easily with a few lines of script. While it may be possible to create platform-specific plugins, integrating native file access directly into the Godot core is the only reliable solution for a seamless user experience. Platform-specific features like permission handling, file URI management, and OS-specific quirks require a deeper level of integration that would be difficult to achieve efficiently through scripts or addons.

Is there a reason why this should be core and not an add-on in the asset library?

Yes, this feature should be integrated into the core of Godot, as it deals with fundamental file access on mobile platforms. Integrating it into the core provides the following advantages:

• Cross-platform Consistency: Ensures that file access works consistently across both Android and iOS, without requiring developers to maintain separate plugins.

• Native Integration: Core-level integration ensures full access to native APIs, streamlining permissions and handling OS-level file access features, which are critical for modern mobile applications.

• Improved Maintenance: As mobile platforms evolve, core integration ensures that file access features can be updated and maintained by the Godot development team, keeping up with platform changes and new APIs.

[sockeye-d]

I don't see a reason why it should be a separate class, this would be better implemented with the existing FileDialog.use_native_dialog property and DisplayServer.file_dialog_show method

[llama-nl]

Dese it work for Android or iOS?

[syntaxerror247]

Dese it work for Android or iOS?

Currently it only work on desktop platform.

I am working on it to implement it for android :)

[llama-nl]

Dese it work for Android or iOS?

Currently it only work on desktop platform.

I am working on it to implement it for android :)

Oh, really thanks 🎉

[sockeye-d]

Dese it work for Android or iOS?

The docs say it only works on Linux, Windows, and macOS:

Note: This method is implemented if the display server has the FEATURE_NATIVE_DIALOG_FILE feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS.

[llama-nl]

Dese it work for Android or iOS?

The docs say it only works on Linux, Windows, and macOS:

Note: This method is implemented if the display server has the FEATURE_NATIVE_DIALOG_FILE feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS.

I hope it will add soon.

[syntaxerror247]

It is now supported for Android. For iOS see #1123