Public Spec for Microsoft.Windows.Storage.Pickers [Milestone 1]

specs/StoragePickers/FileOpenPicker.md

@@ -0,0 +1,172 @@
+FileOpenPicker Class
+===
+
+# Background
+
+Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md)
+
+Represents a UI element that lets the user choose and open files.
+
+Supports specifying the initial location, extension filters, and text on commit button.
+
+# API Pages
+
+## Constructor
+
+### Attributes
+
+| **Attribute**            | **Type**                                                | **Description**                                                          |
+|--------------------------|---------------------------------------------------------|--------------------------------------------------------------------------|
+| `ViewMode`               | [Microsoft::Windows::Storage::Pickers::PickerViewMode](./PickerViewMode.md)  | Gets or sets the view mode that the file picker is using to present items. |
+| `SuggestedStartLocation` | [Microsoft::Windows::Storage::Pickers::PickerLocationId](./PickerLocationId.md)| Gets or sets the initial location where the file picker looks for files. |
+| `CommitButtonText`       | `winrt::hstring`                                        | Gets or sets the text displayed on the commit button of the file picker. |
+| `FileTypeFilter`         | `Windows::Foundation::Collections::IVector<hstring>`    | Gets the collection of file types that the file picker displays.         |
+
+### Examples
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id)
+{
+    // (Optional) specify the initial location. If not specified, use system default:
+    SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
+
+    // (Optional) specify the text displayed on commit button. If not specified, use system default:
+    CommitButtonText = "Choose selected files",
+
+    // (Optional) specify file extensions filters. If not specified, default to all (*.*)
+    FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },
+};
+```
+
+C++
+
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileOpenPicker openPicker(AppWindow().Id());
+
+// (Optional) specify the initial location. If not specified, use system default:
+openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
+
+// (Optional) specify the text displayed on commit button. If not specified, use system default:
+openPicker.CommitButtonText(L"Choose selected files");
+
+// (Optional) specify file extensions filters. If not specified, default to all (*.*)
+openPicker.FileTypeFilter().Append(L".txt");
+openPicker.FileTypeFilter().Append(L".pdf");
+openPicker.FileTypeFilter().Append(L".doc");
+openPicker.FileTypeFilter().Append(L".docx");
+```
+
+## FileOpenPicker.PickSingleFilesAsync
+
+Displays a UI element that allows user to choose and open one file.
+
+### Definition
+```cpp
+winrt::Windows::Foundation::IAsyncOperation<winrt::Windows::Storage::StorageFile> PickSingleFileAsync();
+```
+Return null if the file dialog was cancelled or closed without selection.
+
+### Examples
+
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id);
+
+var file = await openPicker.PickSingleFileAsync();
+if (file is not null)
+{
+    var content = System.IO.File.ReadAllText(file.Path);
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileOpenPicker openPicker(AppWindow().Id());
+auto& file = co_await openPicker.PickSingleFileAsync();
+if (file != nullptr)
+{
+    std::ifstream fileReader(file.Path().c_str());
+    std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
+    winrt::hstring hText = winrt::to_hstring(text);
+}
+else
+{
+    // error handling.
+}
+```
+
+## FileOpenPicker.PickMultipleFilesAsync
+
+Displays a UI element that allows user to choose and open multiple files.
+
+### Definition
+```cpp
+winrt::Windows::Foundation::IAsyncOperation<winrt::Windows::Foundation::Collections::IVectorView<winrt::Windows::Storage::StorageFile>> PickMultipleFilesAsync();
+```
+Return an empty list (Count = 0) if the file dialog's cancelled or closed.
+
+### Examples
+
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id);
+
+var files = await openPicker.PickMultipleFilesAsync();
+if (files is not null)
+{
+    var pickedFilePaths = files.Select(f => f.Path);
+    foreach (var path in pickedFilePaths)
+    {
+        var content = System.IO.File.ReadAllText(path);
+    }
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileOpenPicker openPicker(AppWindow().Id());
+auto& files = co_await openPicker.PickMultipleFilesAsync();
+if (files.Size() > 0)
+{
+    for (auto const& file : files)
+    {
+        std::ifstream fileReader(file.Path().c_str());
+        std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
+        winrt::hstring hText = winrt::to_hstring(text);
+    }
+}
+else
+{
+    // error handling.
+}
+```

specs/StoragePickers/FileSavePicker.md

@@ -0,0 +1,125 @@
+FileSavePicker Class
+===
+
+# Background
+
+Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md)
+
+Represents a UI element that lets the user choose a file to save.
+
+# API Pages
+
+## Constructor
+
+### Attributes
+
+| **Attribute**              | **Type**           | **Description**   |
+|----------------------------|--------------------|-------------------|
+| `ViewMode`                 | [Microsoft::Windows::Storage::Pickers::PickerViewMode](./PickerViewMode.md)    | Gets or sets the view mode that the file picker is using to present items.         |
+| `SuggestedStartLocation`   | [Microsoft::Windows::Storage::Pickers::PickerLocationId](./PickerLocationId.md)| Gets or sets the initial location where the file picker looks for files.           |
+| `SuggestedFileName`        | `winrt::hstring`                       | Gets or sets the file name displayed in the file name input box on launching the dialog.                                   |
+| `DefaultFileExtension`     | `winrt::hstring`                       | Gets or sets the file extension tailing the suggested file name in the file name input box on launching the dialog.        |
+| `CommitButtonText`         | `winrt::hstring`                       | Gets or sets the text displayed on the commit button of the file picker.                                                   |
+| `FileTypeChoices`          | `winrt::Windows::Foundation::Collections::IMap<hstring, winrt::Windows::Foundation::Collections::IVector<hstring>>`    | The file extensions categorized by purpose.|
+
+
+### Examples
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var savePicker = new FileSavePicker(this.AppWindow.Id)
+{
+    // (Optional) specify the initial location. If not specified, use system default:
+    SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
+
+    // (Optional) specify the default file name. If not specified, use system default:
+    SuggestedFileName = "My Document",
+
+    // (Optional) specify the text displayed on commit button. If not specified, use system default:
+    CommitButtonText = "Save Document",
+
+    // (Optional) categorized extensions types. If not specified, use system default: All Files (*.*)
+    FileTypeChoices = {
+        { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
+    },
+
+    // (Optional) specify the default file extension (will be appended after the default file name).
+    //      If not specified, will not appended after the default extension.
+    DefaultFileExtension = ".txt",
+};
+```
+
+C++
+
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileSavePicker savePicker(AppWindow().Id());
+
+// (Optional) specify the initial location. If not specified, use system default:
+savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
+
+// (Optional) specify the default file name. If not specified, use system default:
+savePicker.SuggestedFileName(L"NewDocument");
+
+// (Optional) categorized extensions types. If not specified, use system default: All Files (*.*)
+savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
+
+// (Optional) specify the default file extension (will be appended after the default file name).
+//      If not specified, will not appended after the default extension.
+savePicker.DefaultFileExtension(L".txt");
+```
+
+## FileSavePicker.PickSaveFileAsync
+
+Displays a UI element that allows the user to configure the file path to save.
+
+### Definition
+```cpp
+winrt::Windows::Foundation::IAsyncOperation<winrt::Windows::Storage::StorageFile> PickSaveFileAsync();
+```
+Return null if the file dialog was cancelled or closed without selection.
+
+### Examples
+
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var savePicker = new FileSavePicker(this.AppWindow.Id);
+var file = await savePicker.PickSaveFileAsync();
+if (file is not null)
+{
+    System.IO.File.WriteAllText(file.Path, "Hello world.");
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileSavePicker savePicker(AppWindow().Id());
+StorageFile file& = co_await savePicker.PickSaveFileAsync();
+if (file != nullptr)
+{
+    std::ofstream outFile(file.Path().c_str());
+    outFile << "Hello world.";
+    outFile.close();
+}
+else
+{
+    // error handling.
+}
+```

specs/StoragePickers/FolderPicker.md

@@ -0,0 +1,100 @@
+FolderPicker Class
+===
+
+# Background
+
+Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md)
+
+Represents a UI element that lets the user choose a folder.
+
+Supports specifying the initial location and text on commit button.
+
+# API Pages
+
+## Constructor
+
+### Attributes
+
+| **Attribute**              | **Type**           | **Description**   |
+|----------------------------|--------------------|-------------------|
+| `ViewMode`                 | [Microsoft::Windows::Storage::Pickers::PickerViewMode](./PickerViewMode.md)    | Gets or sets the view mode that the file picker is using to present items.         |
+| `SuggestedStartLocation`   | [Microsoft::Windows::Storage::Pickers::PickerLocationId](./PickerLocationId.md)| Gets or sets the initial location where the file picker looks for files.           |
+| `CommitButtonText`         | `winrt::hstring`                       | Gets or sets the text displayed on the commit button of the file picker.                                                   |
+
+### Examples
+
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var folderPicker = new FolderPicker(this.AppWindow.Id)
+{
+    // (Optional) specify the initial location. If not specified, use system default:
+    SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
+
+    // (Optional) specify the text displayed on commit button. If not specified, use system default:
+    CommitButtonText = "Select Folder",
+};
+```
+
+C++
+
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FolderPicker folderPicker(AppWindow().Id());
+
+// (Optional) specify the initial location. If not specified, use system default:
+folderPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
+
+// (Optional) specify the text displayed on commit button. If not specified, use system default:
+folderPicker.CommitButtonText(L"Select Folder");
+```
+
+## FolderPicker.PickSingleFolderAsync
+
+Displays a UI element that allows the user to choose a folder.
+
+### Definition
+```cpp
+winrt::Windows::Foundation::IAsyncOperation<winrt::Windows::Storage::StorageFolder> PickSingleFolderAsync();
+```
+Return null if the file dialog was cancelled or closed without selection.
+
+### Examples
+
+C#
+
+```csharp
+using Microsoft.Windows.Storage.Pickers;
+
+var folderPicker = new FolderPicker(this.AppWindow.Id);
+var folder = await folderPicker.PickSingleFolderAsync();
+if (folder is not null)
+{
+    var path = folder.Path;
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+```cpp
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FolderPicker folderPicker(AppWindow().Id());
+auto& folder = co_await folderPicker.PickSingleFolderAsync();
+if (folder != nullptr)
+{
+    auto path = folder.Path();
+}
+else
+{
+    // error handling.
+}
+```