From 46e650dbe2bfd6a375ff7fa9c65fb304dafc045c Mon Sep 17 00:00:00 2001 From: Dinah Xiaoman G Date: Fri, 14 Feb 2025 19:09:06 +0800 Subject: [PATCH] public spec for Microsoft.Windows.Storage.Pickers --- specs/StoragePickers/FileOpenPicker.md | 172 ++++++++++++++++++ specs/StoragePickers/FileSavePicker.md | 125 +++++++++++++ specs/StoragePickers/FolderPicker.md | 100 ++++++++++ .../Microsoft.Windows.Storage.Pickers.md | 33 ++++ specs/StoragePickers/PickerLocationId.md | 39 ++++ specs/StoragePickers/PickerViewMode.md | 23 +++ 6 files changed, 492 insertions(+) create mode 100644 specs/StoragePickers/FileOpenPicker.md create mode 100644 specs/StoragePickers/FileSavePicker.md create mode 100644 specs/StoragePickers/FolderPicker.md create mode 100644 specs/StoragePickers/Microsoft.Windows.Storage.Pickers.md create mode 100644 specs/StoragePickers/PickerLocationId.md create mode 100644 specs/StoragePickers/PickerViewMode.md diff --git a/specs/StoragePickers/FileOpenPicker.md b/specs/StoragePickers/FileOpenPicker.md new file mode 100644 index 0000000000..6aa6e3a3b2 --- /dev/null +++ b/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` | 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 +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 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 +#include +#include +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(fileReader)), std::istreambuf_iterator()); + 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> 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 +#include +#include +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(fileReader)), std::istreambuf_iterator()); + winrt::hstring hText = winrt::to_hstring(text); + } +} +else +{ + // error handling. +} +``` diff --git a/specs/StoragePickers/FileSavePicker.md b/specs/StoragePickers/FileSavePicker.md new file mode 100644 index 0000000000..2af14bad10 --- /dev/null +++ b/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>` | 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 { ".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 +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({ 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 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 +#include +#include +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. +} +``` diff --git a/specs/StoragePickers/FolderPicker.md b/specs/StoragePickers/FolderPicker.md new file mode 100644 index 0000000000..90cd84be24 --- /dev/null +++ b/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 +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 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 +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. +} +``` diff --git a/specs/StoragePickers/Microsoft.Windows.Storage.Pickers.md b/specs/StoragePickers/Microsoft.Windows.Storage.Pickers.md new file mode 100644 index 0000000000..10fd76da70 --- /dev/null +++ b/specs/StoragePickers/Microsoft.Windows.Storage.Pickers.md @@ -0,0 +1,33 @@ +Microsoft.Windows.Storage.Pickers Namespace +=== + +The `Microsoft.Windows.Storage.Pickers` API in the Windows App SDK lets desktop applications (like +WinUI3) present a streamlined UI for selecting files or folders, modifying filenames and extensions, +and accessing paths — all while integrating seamlessly across Windows desktops. + +# Background + +The standard OS file and folder picker APIs [Windows.Storage.Pickers](https://learn.microsoft.com/en-us/uwp/api/windows.storage.pickers) +do not work when running as an administrator. To address this gap, here we're introducing the new +`Microsoft.Windows.Storage.Pickers` API by enabling file and folder selection in elevated mode. +It is designed for desktop apps and uses a `WindowId` property to link the picker to its host window. + +# Conceptual pages + +## Classes + +Note: Developers should specify a window id to associate the picker with an owner window before +showing UI. + +| **Class** | **Description** | +|------------------|-----------------| +| [FileOpenPicker](./FileOpenPicker.md)| Displays a UI element that allows user to choose and open files. | +| [FileSavePicker](./FileSavePicker.md)| Displays a UI element that allows user to save a file. | +| [FolderPicker](./FolderPicker.md) | Displays a UI element that allows user to choose a folder.| + +## Enums + +| **Enum** | **Description** | +|----------|-----------------| +|[PickerLocationId](PickerLocationId.md)| Identifies the storage location that the file picker presents to the user. | +|[PickerViewMode](PickerViewMode.md) | Indicates the view mode that the file picker is using to present items. | diff --git a/specs/StoragePickers/PickerLocationId.md b/specs/StoragePickers/PickerLocationId.md new file mode 100644 index 0000000000..7cb7f7fdbd --- /dev/null +++ b/specs/StoragePickers/PickerLocationId.md @@ -0,0 +1,39 @@ +PickerLocationId Enum +=== + +Specifies the default folder or library that a picker starts from or displays to the user. + +Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md) + +# Fields + +| **Name** | **Value** | **Description** | +|--------------------|-----------|----------------------------------------| +| DocumentsLibrary | 0 | The Documents library. | +| ComputerFolder | 1 | The Computer folder. | +| Desktop | 2 | The Windows desktop. | +| Downloads | 3 | The Downloads folder. | +| HomeGroup | 4 | The HomeGroup. | +| MusicLibrary | 5 | The Music library. | +| PicturesLibrary | 6 | The Pictures library. | +| VideosLibrary | 7 | The Videos library. | +| Objects3D | 8 | The Objects library. | +| Unspecified | 9 | An unspecified location. | + +# Definition + +```cpp +enum class PickerLocationId : int32_t +{ + DocumentsLibrary = 0, + ComputerFolder = 1, + Desktop = 2, + Downloads = 3, + HomeGroup = 4, + MusicLibrary = 5, + PicturesLibrary = 6, + VideosLibrary = 7, + Objects3D = 8, + Unspecified = 9, +}; +``` diff --git a/specs/StoragePickers/PickerViewMode.md b/specs/StoragePickers/PickerViewMode.md new file mode 100644 index 0000000000..59eee3e663 --- /dev/null +++ b/specs/StoragePickers/PickerViewMode.md @@ -0,0 +1,23 @@ +PickerViewMode Enum +=== + +Indicates the view mode that the file picker is using to present items. + +Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md) + +# Fields + +| **Name** | **Value** | **Description** | +|------------|-----------|--------------------------------| +| List | 0 | Displays items in a list view. | +| Thumbnail | 1 | Displays items as thumbnails. | + +# Definition + +```cpp +enum class PickerViewMode : int32_t +{ + List = 0, + Thumbnail = 1, +}; +```