File​Save​Picker​UI File​Save​Picker​UI File​Save​Picker​UI Class

Definition

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

public sealed class FileSavePickerUI : IFileSavePickerUIpublic sealed class FileSavePickerUI : IFileSavePickerUIPublic NotInheritable Class FileSavePickerUI Implements IFileSavePickerUI
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If your app participates in the File Save Picker contract, you can access this object using a fileSavePickerUI property while you handle a filesavepicker 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 filesavepicker 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

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>
Value

The list of file types that can be saved.

Attributes

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

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 PlatForm::String FileName { get; }public string FileName { get; }Public ReadOnly Property FileName As string
Value
string string string

The full file name, including the file type extension.

Attributes

SettingsIdentifier SettingsIdentifier SettingsIdentifier

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

public PlatForm::String SettingsIdentifier { get; }public string SettingsIdentifier { get; }Public ReadOnly Property SettingsIdentifier As string
Value
string string string

The identifier for the current context of the file picker.

Attributes

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

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 PlatForm::String Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As string
Value
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.

Attributes

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(String) TrySetFileName(String) TrySetFileName(String)

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

public SetFileNameResult TrySetFileName(String value)public SetFileNameResult TrySetFileName(String value)Public Function TrySetFileName(value As String) As SetFileNameResult
Parameters
value
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

The enumeration value that indicates whether the file name and extension were updated in the file picker UI.

Attributes

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

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
Attributes

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

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

public event TypedEventHandler TargetFileRequestedpublic event TypedEventHandler TargetFileRequestedPublic Event TargetFileRequested
Attributes

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.

See Also