File​Open​Picker​UI File​Open​Picker​UI File​Open​Picker​UI Class

Definition

Used to interact with the file picker if your app provides files with the File Open Picker contract.

public : sealed class FileOpenPickerUI : IFileOpenPickerUIpublic sealed class FileOpenPickerUI : IFileOpenPickerUIPublic NotInheritable Class FileOpenPickerUI Implements IFileOpenPickerUI
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)

Examples

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


// File open picker activated event handler
protected override void OnFileOpenPickerActivated(FileOpenPickerActivatedEventArgs args)
{
    var FileOpenPickerPage = new SDKTemplate.FileOpenPickerPage();
    FileOpenPickerPage.Activate(args);
}

// Overloaded method to respond to fileOpenPicker events
public void Activate(FileOpenPickerActivatedEventArgs args)
{
    // Perform tasks to prepare your app to display its file picker page

    // Get file picker UI
    fileOpenPickerUI = args.FileOpenPickerUI;

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

// File open picker activated event handler
function activated(eventObject) {
    // Identify whether app is launched for fileOpenPicker
    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 webUIFileOpenPickerActivatedEventArgs object.

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

Remarks

If your app participates in the File Open Picker contract, you can retrieve this object using a FileOpenPickerUI property while you handle a fileOpenPicker activated event.

Use one of the following properties to access a FileOpenPickerUI:

Learn about creating a good experience for users when they access your files through the file picker by reading the UX guidelines for providing files in Open files and folders with a picker.

Properties

AllowedFileTypes AllowedFileTypes AllowedFileTypes

Gets a list of file types (extensions) that the user can choose.

public : IVectorView<string> AllowedFileTypes { get; }public IReadOnlyList<string> AllowedFileTypes { get; }Public ReadOnly Property AllowedFileTypes As IReadOnlyList<string>
Value
IVectorView<PlatForm::String> IReadOnlyList<string> IReadOnlyList<string>

The list of allowed file types.

Attributes

Remarks

Because the app that called the file picker (the calling app) can limit the types of files that the user can choose, the app that is providing files (the providing app) can use this method to determine which file types are allowed. For example, if the calling app specifies that only picture file types can be chosen, a music file cannot be added to the file picker 's list of chosen files.

See Also

SelectionMode SelectionMode SelectionMode

Gets an enumeration value that indicates whether the file picker currently limits selection to single files, or if multiple files can be selected.

public : FileSelectionMode SelectionMode { get; }public FileSelectionMode SelectionMode { get; }Public ReadOnly Property SelectionMode As FileSelectionMode
Value
FileSelectionMode FileSelectionMode FileSelectionMode

The enumeration value that indicates the current selection mode.

Attributes

Remarks

You can use this information to alter your app's file picker view according to the current FileSelectionMode.

See Also

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
PlatForm::String string string

The identifier for the current context of the file picker.

Attributes

Remarks

As a provider of files, 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.

See Also

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
PlatForm::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.

See Also

Methods

AddFile(String, IStorageFile) AddFile(String, IStorageFile) AddFile(String, IStorageFile)

Adds the specified file to the list of files that the user has chosen.

public : AddFileResult AddFile(PlatForm::String id, IStorageFile file)public AddFileResult AddFile(String id, IStorageFile file)Public Function AddFile(id As String, file As IStorageFile) As AddFileResult
Parameters
id
PlatForm::String String String

A unique identifier of the file to add.

file
IStorageFile IStorageFile IStorageFile

The file to add to the list of files that the user has chosen.

Returns

The enumeration value that indicates the result of this addFile method.

Attributes
See Also

CanAddFile(IStorageFile) CanAddFile(IStorageFile) CanAddFile(IStorageFile)

Indicates whether the specified file can be added to the list of files the user has chosen.

public : PlatForm::Boolean CanAddFile(IStorageFile file)public bool CanAddFile(IStorageFile file)Public Function CanAddFile(file As IStorageFile) As bool
Parameters
file
IStorageFile IStorageFile IStorageFile

The file to test.

Returns
PlatForm::Boolean bool bool

True if the file can be added to the file picker UI; otherwise false.

Attributes
See Also

ContainsFile(String) ContainsFile(String) ContainsFile(String)

Determines whether the specified file is in the list of files that the user has chosen.

public : PlatForm::Boolean ContainsFile(PlatForm::String id)public bool ContainsFile(String id)Public Function ContainsFile(id As String) As bool
Parameters
id
PlatForm::String String String

The identifier of the file.

Returns
PlatForm::Boolean bool bool

True if the file is in the basket; otherwise false.

Attributes

Remarks

An app hosted in the file picker can use this method to determine whether a file that the app previously added is still in the file picker UI. The user or the app might have removed the file, or the file might not have been added in the first place.

See Also

RemoveFile(String) RemoveFile(String) RemoveFile(String)

Removes the specified file from the list of files the user has chosen.

public : void RemoveFile(PlatForm::String id)public void RemoveFile(String id)Public Function RemoveFile(id As String) As void
Parameters
id
PlatForm::String String String

The identifier of the file to remove.

Attributes

Remarks

The specified id should be the same as the one provided when the file was added to the file picker UI.

When the user deselects a file in the app's file picker view, the app calls this method to remove the item from the file picker UI.

See Also

Events

Closing Closing Closing

Fires when the user closes the file picker.

public : event TypedEventHandler Closingpublic event TypedEventHandler ClosingPublic Event Closing
Attributes

Remarks

As a provider of files, you can register for this event so that your app can execute cleanup tasks before it is closed. For example, if the user cancels the file picker, you could respond by cleaning up temporary files that were added to the file picker when the user chose them.

Register for this event by adding an event listener to the fileOpenPickerUI and assigning a handler function for the event. You can access information about the event from the pickerClosingEventArgs object that is passed to your event handler.

FileRemoved FileRemoved FileRemoved

Note

The fileremoved event is deprecated and should not be used.

Fires when the user removes a file from the list of files that the user has chosen if that file was added by the app that is providing files.

public : event TypedEventHandler FileRemovedpublic event TypedEventHandler FileRemovedPublic Event FileRemoved
Attributes

Examples

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


// Event handler
private async void OnFileRemoved(FileOpenPickerUI sender, FileRemovedEventArgs args)
{
    // Perform tasks when an item is removed from the file picker, like updating buttons or notifying the user

    // Make sure that the item was removed from the file picker matches the one we added.
    if (args.Id == id)
    {
        // The event handler may be invoked on a background thread,
        // so use the Dispatcher to run the UI-related code on the UI thread.
        await dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
        {
            OutputTextBlock.Text = Status.FileRemoved;
            UpdateButtonState(false);
        });
     }
}

// Register for the event
fileOpenPickerUI.FileRemoved += new TypedEventHandler<FileOpenPickerUI, FileRemovedEventArgs>(OnFileRemoved);

// Event handler
function onFileRemovedFromBasket(e) {
    // Perform tasks when an item is removed from the file picker, like updating buttons or notifying the user

    // Add any code to be called when an item is removed from the basket by the user
    WinJS.log && WinJS.log(SdkSample.fileRemoved, "sample", "status");

    // Adjust the add/remove buttons based on removal
    updateSelectionState(e.id, false);
};

// Register for the event
fileOpenPickerUI.addEventListener("fileremoved", onFileRemovedFromBasket, false);

Both args and e (in C# and JS respectively) contain a FileRemovedEventArgs object.

For JavaScript, SdkSample.fileRemoved is an app variable that contains a string that used to used to notify the user.

For C#, id is an app variable that gets an identifier for the file and UpdateButtonState is one of the app's helper methods.

Remarks

If your app participates in the File Open Picker contract and your app uses the app page that is hosted in the file picker to visually indicate which items the user selects, you should respond to this event. When a fileremoved event fires you should update your app's file picker page to reflect the change. Learn more about responding to this event in fileRemovedEventArgs.

See Also

See Also