Public Spec for Microsoft.Windows.Storage.Pickers

specs/StoragePickers/FileOpenPicker.md

@@ -0,0 +1,183 @@
+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
+
+## Definition
+
+```C#
+runtimeclass FileOpenPicker
+{
+    FileOpenPicker(Microsoft.UI.WindowId windowId);
+
+    string CommitButtonText;
+    string SettingsIdentifier;
+    IVector<string> FileTypeFilter{ get; };
+    PickerLocationId SuggestedStartLocation;
+    PickerViewMode ViewMode;
+
+    Windows.Foundation.IAsyncOperation<PickFileResult> PickSingleFileAsync();
+    Windows.Foundation.IAsyncOperation<IVectorView<PickFileResult>> PickMultipleFilesAsync();
+}
+```
+
+## Constructor
+
+### Examples
+C#
+
+```C#
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id)
+{
+    // (Optional) specify the initial location.
+    //     If not specified, using PickerLocationId.Unspecified by 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++
+
+```C++
+#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, using PickerLocationId.Unspecified by 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.PickSingleFileAsync
+
+Displays a UI element that allows user to choose and open one file.
+
+Returns a light weight object that has the path of the picked file.
+
+Return null if the file dialog was cancelled or closed without selection.
+
+### Examples
+
+C#
+
+```C#
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id);
+
+var result = await openPicker.PickSingleFileAsync();
+if (result is not null)
+{
+    var content = System.IO.File.ReadAllText(result.Path);
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+```C++
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileOpenPicker openPicker(AppWindow().Id());
+auto& result{ co_await openPicker.PickSingleFileAsync() };
+if (result)
+{
+    std::ifstream fileReader(result.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.
+
+Returns a collection of light weight objects that has the path of picked files.
+
+Return an empty list (Count = 0) if the file dialog's cancelled or closed without selection.
+
+### Examples
+
+C#
+
+```C#
+using Microsoft.Windows.Storage.Pickers;
+
+var openPicker = new FileOpenPicker(this.AppWindow.Id);
+
+var results = await openPicker.PickMultipleFilesAsync();
+if (results.Count > 0)
+{
+    var pickedFilePaths = results.Select(f => f.Path);
+    foreach (var path in pickedFilePaths)
+    {
+        var content = System.IO.File.ReadAllText(path);
+    }
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+```C++
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileOpenPicker openPicker(AppWindow().Id());
+auto& results{ co_await openPicker.PickMultipleFilesAsync() };
+if (results.Size() > 0)
+{
+    for (auto const& result : results)
+    {
+        std::ifstream fileReader(result.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.
+}
+```
+
+# See Also
+
+[PickFileResult](./PickFileResult.md)

specs/StoragePickers/FileSavePicker.md

@@ -0,0 +1,138 @@
+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
+
+## Definition
+
+```C#
+runtimeclass FileSavePicker
+{
+    FileSavePicker(Microsoft.UI.WindowId windowId);
+
+    string CommitButtonText;
+
+    string SettingsIdentifier;
+    string DefaultFileExtension;
+    string SuggestedFileName;
+    Windows.Storage.StorageFile SuggestedSaveFile;
+    IMap<string, IVector<string>> FileTypeChoices{ get; };
+
+    PickerLocationId SuggestedStartLocation;
+
+    Windows.Foundation.IAsyncOperation<PickFileResult> PickSaveFileAsync()
+}
+```
+
+## Constructor
+
+### Examples
+C#
+
+```C#
+using Microsoft.Windows.Storage.Pickers;
+
+var savePicker = new FileSavePicker(this.AppWindow.Id)
+{
+    // (Optional) specify the initial location.
+    //     If not specified, using PickerLocationId.Unspecified by 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++
+
+```C++
+#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, using PickerLocationId.Unspecified by defaultl
+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.
+
+Returns a light weight object that has the path of the saved file.
+
+Returns null if the file dialog was cancelled or closed without saved file.
+
+### Examples
+
+C#
+
+```C#
+using Microsoft.Windows.Storage.Pickers;
+
+var savePicker = new FileSavePicker(this.AppWindow.Id);
+var result = await savePicker.PickSaveFileAsync();
+if (result is not null)
+{
+    System.IO.File.WriteAllText(result.Path, "Hello world.");
+}
+else
+{
+    // error handling.
+}
+```
+
+C++
+
+```C++
+#include <winrt/Microsoft.Windows.Storage.Pickers.h>
+#include <fstream>
+#include <string>
+using namespace winrt::Microsoft::Windows::Storage::Pickers;
+
+FileSavePicker savePicker(AppWindow().Id());
+auto& result{ co_await savePicker.PickSaveFileAsync() };
+if (result)
+{
+    std::ofstream outFile(result.Path().c_str());
+    outFile << "Hello world.";
+    outFile.close();
+}
+else
+{
+    // error handling.
+}
+```
+
+# See Also
+
+[PickFileResult](./PickFileResult.md)