Spec: `MediaGallery`

[MartinZikmund]

What would you like to be added:

The MediaGallery class is a static class designed for interaction with the device's media gallery on iOS and Android platforms. It provides functionality to check user permissions for accessing the gallery and saving media files to the gallery.

Why is this needed:

User requirement to efficiently save files into storage.

Public API

Uno.Toolkit.UI.MediaFileType enum

Represents a media file type.

Members

• Image - Image media file type.
• Video - Video media file type

Uno.Toolkit.UI.MediaGallery class

Allows interaction with the device's media gallery.

This class is available only on Android and iOS targets, where media gallery requires a specific API.

CheckAccessAsync method

/// <summary>
/// Checks the user's permission to access the device's gallery.
/// Will trigger the permission request if not already granted.
/// </summary>
/// <returns>A Task that represents a boolean indicating whether the user has access.</returns>
public static async Task<bool> CheckAccessAsync()

• Description: Asynchronously checks if the application has permission to access the media gallery. If permission is not already granted, it will prompt the user for permission.
• Returns: A Task<bool> that completes with true if access is granted, and false otherwise.

SaveAsync (stream)

/// <summary>
/// Saves a media file to the device's gallery.
/// </summary>
/// <param name="type">The type of the media file.</param>
/// <param name="stream">A stream representing the media file.</param>
/// <param name="targetFileName">The name to save the file as.</param>
/// <returns>A Task that represents the progress of the save operation.</returns>
public static async Task SaveAsync(MediaFileType type, Stream stream, string targetFileName)

• Description: Asynchronously saves a media file to the device's gallery using a stream.
• Parameters:
  • MediaFileType type: The type of the media file (image or video).
  • Stream stream: The media file data in a stream.
  • string targetFileName: The desired file name for the saved media.
• Returns: A Task that completes when the save operation is finished.

SaveAsync (byte array)

/// <summary>
/// Saves a media file to the device's gallery.
/// </summary>
/// <param name="type">The type of the media file.</param>
/// <param name="data">A byte array representing the media file.</param>
/// <param name="targetFileName">The name to save the file as.</param>
/// <returns>A Task that represents the progress of the save operation.</returns>
public static async Task SaveAsync(MediaFileType type, byte[] data, string targetFileName)

• Description: Asynchronously saves a media file to the device's gallery provided a byte array.
• Parameters:
  • MediaFileType type: The type of the media file (image or video).
  • byte[] data: The media file data in a byte array.
  • string targetFileName: The desired file name for the saved media.
• Returns: A Task that completes when the save operation is finished.

Usage

// Check for gallery access
bool hasAccess = await MediaGallery.CheckAccessAsync();

if (hasAccess)
{
    // Save a video to the gallery using stream
    using Stream videoStream = ...; // Video stream
    await MediaGallery.SaveAsync(MediaFileType.Video, videoStream, "MyVideo.mp4");
}

[francoistanguay]

So there's no WinUI/WinRT-equivalent API for this? even at lower level (Storage/...)?

If there's really nothing, shouldnt this be in a Toolkit (non-UI) package vs a Toolkit.UI has it's more of a WinRT api and not a XAML/View component?

[kazo0]

I'll let @MartinZikmund expand on it but I believe it's in .UI because of the need for launching the Android/iOS native UI. The non-UI Toolkit lib is just a netstandard2.0 library

[jeromelaban]

So there's no WinUI/WinRT-equivalent API for this? even at lower level (Storage/...)?

It would be StorageFile, but its API is too large for what we need to support. We could end up adding support for it in the future, if that becomes necessary.

[francoistanguay]

Dont we already have StorageFile support? Can we just add what is needed?

Maybe easier to discuss.

[MartinZikmund]

@francoistanguay unfortunately not easily possible - for example on iOS one can save the file, but not retrieve it back (unless another permission is added). The API is just so specific, that mapping it onto StorageFile is close to impossible. If we could get it to work, it would be very specific and most operations would just result in NotSupportedException. In this case having separate API feels more user friendly.

For why Uno.Toolkit.UI and not non UI - I needed access to Uno.UI. I could move it to Uno.Toolkit, but then we would have to add Uno.UI reference to Uno.Toolkit as well (it does not have it currently)