Adding initial spec for Reunion Picker API.

specs/Picker-API_spec.md

@@ -0,0 +1,246 @@
+<!--
+    Before submitting, delete all <!-- TEMPLATE marked comments in this file,
+    and the following quote banner:
+-->
+> See comments in Markdown for how to use this spec template
+
+<!-- TEMPLATE
+    The purpose of this spec is to describe a new feature and
+    its APIs that make up a new feature in Project Reunion. 
+
+    There are two audiences for the spec. The first are people
+    that want to evaluate and give feedback on the API, as part of
+    the submission process.  When it's complete
+    it will be incorporated into the documentation for Project Reunion.
+    Hopefully we'll be able to copy it mostly verbatim.
+    So the second audience is everyone that reads there to learn how
+    and why to use this API. 
+-->
+
+# Background
+
+<!-- TEMPLATE
+    Use this section to provide background context for the new API(s)
+    in this spec. 
+
+    This section and the appendix are the only sections that likely
+    do not get copied into any official documentation, they're just an aid
+    to reading this spec. 
+    
+    If you're modifying an existing API, included a link here to the
+    existing page(s) or spec documentation.
+
+    For example, this section is a place to explain why you're adding this
+    API rather than modifying an existing API.
+
+    If you're writing a "converged" API add links into docs.microsoft.com
+    for the existing Win32 or WinRT APIs that are being converged.
+-->
+
+<!-- TEMPLATE
+    For example, this is a place to provide a brief explanation of some dependent
+    area, just explanation enough to understand this new API, rather than telling
+    the reader "go read 100 pages of background information posted at ...". 
+-->
+The current FilePicker API for UWP has several limitations. Some of the top limitations 
+are as described below:
+
+**1. Unable to pick files and folders in a single instance of the Picker dialog**
+
+   The Picker dialog allows developers to specify picker mode to be single file or multiple
+   files. It does not however, allow developers to specify a mode to pick both files and folders.
+   There has been feedback indicating that this behaviour is limiting, requiring developers
+   to build their own picker experience. 
+
+**2. Unable to pick multiple folders.**
+
+   The Picker dialog (FolderPicker) does not allow users to pick multiple folders. The developer
+   experience currently is to select a single folder and repeat the dialog for more folders. This 
+   is a less than ideal experience for application developers.
+
+The Reunion picker dialog is going to address the above issues. This Reunion API will be based upon the below
+APIs in the Windows SDK. The Reunion Picker API will remove the deprecated APIs and add additional methods
+for the functionality file and folder picker, multiple folder picker.
+
+- Windows.Storage.Pickers.FileOpenPicker (https://docs.microsoft.com/en-us/uwp/api/Windows.Storage.Pickers.FileOpenPicker)
+- Windows.Storage.Pickers.FileSavePicker (https://docs.microsoft.com/en-us/uwp/api/windows.storage.pickers.filesavepicker)
+- Windows.Storage.Pickers.FolderPicker (https://docs.microsoft.com/en-us/uwp/api/windows.storage.pickers.folderpicker) 
+
+# Description
+
+<!-- TEMPLATE
+    Use this section to provide a brief description of the feature.
+    For an example, see the introduction to the PasswordBox control
+    (http://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box).
+-->
+The goal of this API is to address the gaps in the existing File/Folder picker APIs. The API surface is similar to the existing
+Picker APIs in Windows SDK with additional methods to support File + Folder picker and multiple folder picker. The API removes the
+deprecated methods from Windows SDK.
+
+# Examples
+
+<!-- TEMPLATE
+
+    Use this section to explain the features of the API, showing
+    example code with each description. The general format is:
+
+    ## FirstFeatureName
+
+    Feature explanation text goes here, including why an app would use it, how it
+    replaces or supplements existing functionality.
+
+    ```c#
+    void SampleMethod() {
+        var show = new AnExampleOf();
+        show.SomeMembers = AndWhyItMight(be, interesting)
+    }
+    ```
+
+    ## SecondFeatureName
+
+    Feature explanation text goes here, including why an app would use it, how it
+    replaces or supplements existing functionality.
+
+    ```c#
+    void SampleMethod() {
+        var show = new AnExampleOf();
+        show.SomeMembers = AndWhyItMight(be, interesting)
+    }
+    ```
+
+    Code samples should be in C# and/or C++/WinRT.
+
+    As an example of this section, see the Examples section for the PasswordBox
+    control (https://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box#examples). 
+-->
+
+## Show file and folder picker
+    ```c#
+    var picker = StorageItemPicker::CreateFilePicker();
+    picker.Filters.add("*.jpg");
+    picker.Filters.add("*.png");
+    picker.StartLocation = startLocation;
+    IReadOnlyList<StorageItem> storageItems = await picker.PickStorageItemAsync();
+
+    if(0 < storageItems.Count)
+    {
+    }
+    ```
+
+## Show single folder picker
+    ```c#
+    var picker = StorageItemPicker::CreateFolderPicker();
+    Windows.Storage.StorageFolder folder = await picker.PickSingleFolderAsync();
+    ```
+
+
+## Show multi folder picker
+    ```c#
+    var picker = StorageItemPicker::CreateFolderPicker();
+    IReadOnlyList<Windows.Storage.StorageFolder> folders = picker.PickMultipleFoldersAsync();
+    ```
+
+# Remarks
+
+<!-- TEMPLATE
+
+    Explanation and guidance that doesn't fit into the Examples section.
+
+    APIs should only throw exceptions in exceptional conditions; basically,
+    only when there's a bug in the caller, such as argument exception.  But if for some
+    reason it's necessary for a caller to catch an exception from an API, call that
+    out with an explanation either here or in the Examples
+-->
+
+# API Notes
+
+<!-- TEMPLATE
+
+    Option 1: Give a one or two line description of each API (type and member),
+        or at least the ones that aren't obvious from their name. These
+        descriptions are what show up in IntelliSense. For properties, specify
+        the default value of the property if it isn't the type's default (for
+        example an int-typed property that doesn't default to zero.) 
+        
+    Option 2: Put these descriptions in the below API Details section,
+        with a "///" comment above the member or type. 
+-->
+
+# API Details
+
+<!-- TEMPLATE
+
+    The exact API, in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/)
+    when possible, or in C# if starting with an API sketch.  GitHub's markdown
+    syntax formatter does not (yet) know about MIDL3, so use ```c# instead even
+    when writing MIDL3.
+
+    Example:
+
+    ```c# (but really MIDL3)
+    namespace Microsoft.AppModel
+    {
+        /// Represents a package on the host system. See Windows.ApplicationModel.Package for more details
+        runtimeclass Package
+        {
+            /// Returns the current package, or null if the current process is not packaged
+            static Package Current { get; };
+
+            /// Returns the package from the system store with this full name or null if not found
+            static Package GetFromFullName(String fullName);
+
+            /// Returns packages in the given family, by name
+            static Package[] FindByFamilyName(String familyName);
+        }
+    }
+    ```
+-->
+    ```c#
+    namespace Microsoft.Reunion.Storage.Pickers
+    {
+        runtimeclass StorageItemPicker
+        {
+            /// Static constructor
+            static FileOpenPicker CreateFileOpenPicker();
+            static FileSaveFileAsync CreateFileSavePicker();
+            static FolderPicker CreateFolderPicker();
+
+            String StartLocation{ set; }
+            String OkButtonText { set; }
+            String CancelButtonText { set; }
+            Windows.Foundation.Collections.IVector<String> Filters{ get; }
+            PickerViewMode ViewMode{ get; set; }
+        }
+
+        runtimeclass FileOpenPicker : StorageItemPicker
+        {
+            Windows.Foundation.IAsyncOperation<Windows.Storage.StorageFile> PickSingleFileAsync();
+            Windows.Foundation.IAsyncOperation<Windows.Foundation.Collections.IVectorView<Windows.Storage.StorageFile>> PickMutipleFilesAsync();
+            Windows.Foundation.IAsyncOperation<Windows.Foundation.Collections.IVectorView<Windows.Storage.StorageItem>> PickStorageItemsAsync();
+        }
+
+        runtimeclass FileSavePicker : StorageItemPicker
+        {
+            String SuggestedSaveFile{ get; set; }
+            String DefaultFileExtension{ get; set; }
+
+            Windows.Foundation.IAsyncOperation<Windows.Storage.StorageFile> PickSaveFileAsync();
+        }
+
+        runtimeclass FolderPicker : StorageItemPicker
+        {
+            Windows.Foundation.IAsyncOperation<Windows.Storage.StorageFolder> PickSingleFolderAsync();
+            Windows.Foundation.IAsyncOperation<Windows.Foundation.Collections.IVectorView<Windows.Storage.StorageFolder>> PickMultipleFoldersAsync();
+        }
+    }
+    ```
+
+# Appendix
+
+<!-- TEMPLATE
+
+    Anything else that you want to write down for posterity, but
+    that isn't necessary to understand the purpose and usage of the API.
+    For example, implementation details.
+    
+-->