FileOpenPickerUI FileOpenPickerUI FileOpenPickerUI FileOpenPickerUI Class

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

Syntax

Declaration

public sealed class FileOpenPickerUIpublic sealed class FileOpenPickerUIPublic NotInheritable Class FileOpenPickerUI

Remarks

If your app participates in the File Open Picker contract, you can retrieve this object using a FileOpenPickerUI property while you handle a ActivationKind 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 Guidelines and checklist for contracts.

Examples

The File picker sample demonstrates how to respond to a ActivationKind 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.

Properties summary

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

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

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

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

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

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

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

Events summary

Fires when the user closes the file picker.

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.

Properties

  • AllowedFileTypes
    AllowedFileTypes
    AllowedFileTypes
    AllowedFileTypes

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

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

    Property Value

    • The list of allowed file types.

    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.

  • SelectionMode
    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

    Property Value

    Remarks

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

  • 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 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.

  • 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

  • AddFile(System.String,Windows.Storage.IStorageFile)
    AddFile(System.String,Windows.Storage.IStorageFile)
    AddFile(System.String,Windows.Storage.IStorageFile)
    AddFile(System.String,Windows.Storage.IStorageFile)

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

    public AddFileResult AddFile(System.String,Windows.Storage.IStorageFile)public AddFileResult AddFile(System.String,Windows.Storage.IStorageFile)Public Function AddFile(System.String,Windows.Storage.IStorageFile) As AddFileResult

    Parameters

    Returns

  • CanAddFile(Windows.Storage.IStorageFile)
    CanAddFile(Windows.Storage.IStorageFile)
    CanAddFile(Windows.Storage.IStorageFile)
    CanAddFile(Windows.Storage.IStorageFile)

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

    public bool CanAddFile(Windows.Storage.IStorageFile)public bool CanAddFile(Windows.Storage.IStorageFile)Public Function CanAddFile(Windows.Storage.IStorageFile) As bool

    Parameters

    Returns

    • bool
      bool
      bool
      bool

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

  • ContainsFile(System.String)
    ContainsFile(System.String)
    ContainsFile(System.String)
    ContainsFile(System.String)

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

    public bool ContainsFile(System.String)public bool ContainsFile(System.String)Public Function ContainsFile(System.String) As bool

    Parameters

    • id
      System.String
      System.String
      System.String
      System.String

      The identifier of the file.

    Returns

    • bool
      bool
      bool
      bool

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

    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.

  • RemoveFile(System.String)
    RemoveFile(System.String)
    RemoveFile(System.String)
    RemoveFile(System.String)

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

    public void RemoveFile(System.String)public void RemoveFile(System.String)Public Function RemoveFile(System.String) As void

    Parameters

    • id
      System.String
      System.String
      System.String
      System.String

      The identifier of the file to remove.

    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.

Events

  • Closing
    Closing
    Closing
    Closing

    Fires when the user closes the file picker.

    public event TypedEventHandler Closingpublic event TypedEventHandler ClosingPublic Event Closing

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

    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.

    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.

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