FileSavePickerUI FileSavePickerUI FileSavePickerUI FileSavePickerUI Class

Used to interact with the file picker when your app provides a save location with the File Save Picker contract.

Syntax

Declaration

public sealed class FileSavePickerUIpublic sealed class FileSavePickerUIPublic NotInheritable Class FileSavePickerUI

Remarks

If your app participates in the File Save Picker contract, you can access this object using a fileSavePickerUI property while you handle a ActivationKind activated event.

Use one of the following properties to retrieve a FileSavePickerUI object:

To learn about creating a good experience for users when they use your app as a save location, see Open files and folders with a picker.

Examples

The File picker sample demonstrates how to respond to a ActivationKind activated event.


// fileSavePicker activated event handler
protected override void OnFileSavePickerActivated(FileSavePickerActivatedEventArgs args)
{
    var FileSavePickerPage = new SDKTemplate.FileSavePickerPage();
    FileSavePickerPage.Activate(args);
}

// Overloaded method to respond to fileSavePicker events
internal void Activate(FileSavePickerActivatedEventArgs args)
{
    // Perform tasks to prepare your app to display its file picker page

    // Get file picker UI
    fileSavePickerUI = args.FileSavePickerUI;

    Window.Current.Content = this;
    this.OnNavigatedTo(null);
    Window.Current.Activate();
}

// fileSavePicker activated event handler
function activated(eventObject) {
    // Identify whether app is launched for fileSavePicker
    if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.fileOpenPicker) {
        // Perform tasks to prepare your app to display its file picker page

        // Get file picker UI
        fileOpenPickerUI = eventObject.detail.fileOpenPickerUI;

        eventObject.setPromise(WinJS.UI.processAll().then(function () {
            // Navigate to either the first scenario or to the last running scenario
            // before suspension or termination.
            var url = scenarios[0].url;
            return WinJS.Navigation.navigate(url, fileOpenPickerUI);
        }));
    }
}

// Register the activated event handler
WinJS.Application.addEventListener("activated", activated, false);

For JavaScript, eventObject contains a WebUIFileSavePickerActivatedEventArgs object.

For C#, args contains a FileSavePickerActivatedEventArgs object. Additionally, the OnFileSavePickerActivated is in the App.xaml.cs file and the Activate method is in the FileSavePickerPage.xaml.cs file of the File picker sample.

Properties summary

Gets a list of file types (extensions) that can be saved to the app that is providing the save location.

Gets the full file name of the file to save, including the file type extension. The file name and extension are specified by the user.

Gets an identifier for the current context of the file picker.

Gets or sets a title to display in the file picker UI that identifies the location that the file picker is displaying to the user.

Methods summary

Tries to set the file name and extension in the file picker UI.

Events summary

Fired when the user changes the file name in the file name text box or changes the extension in the file type drop-down menu.

Fires when the user commits a file to be saved in the file picker.

Properties

  • AllowedFileTypes
    AllowedFileTypes
    AllowedFileTypes
    AllowedFileTypes

    Gets a list of file types (extensions) that can be saved to the app that is providing the save location.

    public IVectorView<string> AllowedFileTypes { get; }public IVectorView<string> AllowedFileTypes { get; }Public ReadOnly Property AllowedFileTypes As IVectorView<string>

    Property Value

    • The list of file types that can be saved.

    Remarks

    As the app that provides the save location, you should use this information to filter the page your app displays and to constrain the extensions of the file names it generates.

  • FileName
    FileName
    FileName
    FileName

    Gets the full file name of the file to save, including the file type extension. The file name and extension are specified by the user.

    public string FileName { get; }public string FileName { get; }Public ReadOnly Property FileName As string

    Property Value

    • string
      string
      string
      string

      The full file name, including the file type extension.

  • SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier

    Gets an identifier for the current context of the file picker.

    public string SettingsIdentifier { get; }public string SettingsIdentifier { get; }Public ReadOnly Property SettingsIdentifier As string

    Property Value

    • string
      string
      string
      string

      The identifier for the current context of the file picker.

    Remarks

    As the provider of a save location, your app can use this identifier to restore the state your app was in the last time it was used in this context.

    The context depends on various factors including the calling app and file types being chosen.

  • Title
    Title
    Title
    Title

    Gets or sets a title to display in the file picker UI that identifies the location that the file picker is displaying to the user.

    public string Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As string

    Property Value

    • string
      string
      string
      string

      The title to display in the file picker UI. This title should identify the location and type of files that the user can see on the app page (which is hosted by the file picker) of the app that is providing files.

    Remarks

    As a provider of files, you should consider updating the title if the user navigates to another location or if the AllowedFileTypes change.

Methods

  • TrySetFileName(System.String)
    TrySetFileName(System.String)
    TrySetFileName(System.String)
    TrySetFileName(System.String)

    Tries to set the file name and extension in the file picker UI.

    public SetFileNameResult TrySetFileName(System.String value)public SetFileNameResult TrySetFileName(System.String value)Public Function TrySetFileName(value As System.String) As SetFileNameResult

    Parameters

    • value
      System.String
      System.String
      System.String
      System.String

      The file name and extension that are used to update the file name text box and file type drop-down menu in the file picker UI.

    Returns

    Remarks

    As the provider of a save location, your app should call this method when the user selects a file that is displayed on your app page (which is hosted in the file picker).

    This method fails if:

    • The extension specified for the file in value isn't one of the AllowedFileTypes.
    • The file picker UI isn't visible to the user.
    • The user is interacting with the file name text box in the file picker UI.

Events

  • FileNameChanged
    FileNameChanged
    FileNameChanged
    FileNameChanged

    Fired when the user changes the file name in the file name text box or changes the extension in the file type drop-down menu.

    public event TypedEventHandler FileNameChangedpublic event TypedEventHandler FileNameChangedPublic Event FileNameChanged

    Remarks

    In response to this event, your app should get the new file name from the FileName property and check the AllowedFileTypes as these also could have changed.

    Register for this event by adding an event listener to the FileSavePickerUI object and assigning a handler function for the event.

  • TargetFileRequested
    TargetFileRequested
    TargetFileRequested
    TargetFileRequested

    Fires when the user commits a file to be saved in the file picker.

    public event TypedEventHandler TargetFileRequestedpublic event TypedEventHandler TargetFileRequestedPublic Event TargetFileRequested

    Remarks

    If your app participates in the File Save Picker contract and a TargetFileRequested event fires, your app should create a new StorageFile that represents the file the user wants to save. The name of the StorageFile you create must match the name of the file specified by the FileName property. The StorageFile you create is returned to the app that called the file picker (the calling app) so that the calling app can write content to the file. Learn more about responding to this event in TargetFileRequestedEventArgs.

    Note

    file picker UI is disabled until the providing app has finished responding to this event.

    Examples

    The File picker sample demonstrates how to respond to a TargetFileRequested event handler.

    
    // Event handler
    private async void OnTargetFileRequested(FileSavePickerUI sender, TargetFileRequestedEventArgs e)
    {
        // Respond to TargetFileRequested event on the background thread on which it was raised
    
        // Requesting a deferral allows the app to call another asynchronous method and complete the request at a later time
        var deferral = e.Request.GetDeferral();
    
        // Create file and assign to TargetFile property
        e.Request.TargetFile = await ApplicationData.Current.LocalFolder.CreateFileAsync(sender.FileName, CreationCollisionOption.GenerateUniqueName);
    
        // Complete the deferral to let the Picker know the request is finished
        deferral.Complete();
    }
    
    // Register for the event
    fileSavePickerUI.TargetFileRequested += new TypedEventHandler<FileSavePickerUI, TargetFileRequestedEventArgs>(OnTargetFileRequested);
    
    
    // Event handler
    function onTargetFileRequested(e) {
        var deferral;
        deferral = e.request.getDeferral();
    
        // Create a file to pass to the file picker which then gives it to the calling app
        Windows.Storage.ApplicationData.current.localFolder.createFileAsync(fileSavePickerUI.fileName).done(function (file) {
                // Assign the resulting file to the targetFile property and complete the deferral to indicate success
            e.request.targetFile = file;
            deferral.complete();
        }, function () {
            // Set the targetFile property to null and complete the deferral to indicate failure
            e.request.targetFile = null;
            deferral.complete();
        });
    };
    
    // Register for the event
    fileSavePickerUI.addEventListener("targetfilerequested", onTargetFileRequested, false);
    

    In the example, e contains a TargetFileRequestedEventArgs object.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.Storage.Pickers.Provider.dll