Official API Review for new functionalities of Storage.Pickers: SettingsIdentifier; FileTypeIndex; Title; PickMultipleFoldersAsync; ShowOverwritePrompt

specs/Storage.Pickers/FileOpenPicker.md

@@ -13,15 +13,18 @@ Supports specifying the initial location, extension filters, and text on commit
 
 ## Definition
 
-```C#
+```idl
 runtimeclass FileOpenPicker
 {
     FileOpenPicker(Microsoft.UI.WindowId windowId);
 
     string CommitButtonText;
+    string Title;
+    string SettingsIdentifier;
 
     IMap<String, IVector<String>> FileTypeChoices{ get; };
     IVector<string> FileTypeFilter{ get; };
+    Int32 InitialFileTypeIndex;
 
     string SuggestedFolder;
     String SuggestedStartFolder;
@@ -65,15 +68,26 @@ var openPicker = new FileOpenPicker(this.AppWindow.Id)
     //     If not specified, the system uses a default label of "Open" (suitably translated).
     CommitButtonText = "Choose selected files",
 
+    // (Optional) specify the title of the picker.
+    //     If not specified, the system uses a default title.
+    Title = "Open File",
+
+    // (Optional) allows customization of the settings name, to distinguish picker instances.
+    //     Without the SettingsIdentifier specified, pickers in one app share the state together.
+    //     Only specify this when a picker needs to track its own state (e.g. size, location, etc).
+    SettingsIdentifier = "BookContents",
+
     // (Optional) group file types into labeled choices
     //     FileTypeChoices takes precedence over FileTypeFilter when both defined.
     FileTypeChoices = {
         { "Documents", new List<string> { ".txt", ".doc", ".docx" } },
         { "Pictures", new List<string> { ".png", ".jpg", ".jpeg", ".bmp" } }
     },
 
-    // (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
-    FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },
+    // (Optional) specify which file type to be automatically selected on dialog launch.
+    //     The index is 0-based. 
+    //     When not specified, its value is -1 and the dialog follows default behavior.
+    InitialFileTypeIndex = 1,  // auto select Pictures
 
     // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
     ViewMode = PickerViewMode.List,
@@ -109,28 +123,60 @@ openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
 //     If not specified, the system uses a default label of "Open" (suitably translated).
 openPicker.CommitButtonText(L"Choose selected files");
 
+// (Optional) specify the title of the picker.
+//     If not specified, the system uses a default title.
+openPicker.Title(L"Open File");
+
+// (Optional) allows customization of the settings name, to distinguish picker instances.
+//     Without the SettingsIdentifier specified, pickers in one app share the state together.
+//     Only specify this when a picker needs to track its own state (e.g. size, location, etc).
+openPicker.SettingsIdentifier(L"BookContents");
+
 // (Optional) group file types into labeled choices
 //     FileTypeChoices takes precedence over FileTypeFilter when both defined.
 auto choices = openPicker.FileTypeChoices();
 choices.Insert(L"Documents", winrt::single_threaded_vector<winrt::hstring>({ L".txt", L".doc", L".docx" }));
 choices.Insert(L"Pictures", winrt::single_threaded_vector<winrt::hstring>({ L".png", L".jpg", L".jpeg", L".bmp" }));
 
-// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
-openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });
+// (Optional) specify which file type to be automatically selected on dialog launch.
+//     The index is 0-based. 
+//     When not specified, its value is -1 and the dialog follows default behavior.
+openPicker.InitialFileTypeIndex(1);  // auto select Pictures
 
 // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
 openPicker.ViewMode(PickerViewMode::List);
 ```
 
-## FileOpenPicker.PickSingleFileAsync
+## New Properties
+
+### FileOpenPicker.Title
+
+Allow customizing the title of file dialog. It's based on the 
+[IFileDialog::SetTitle method](https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-ifiledialog-settitle)
+
+### FileOpenPicker.SettingsIdentifier
+
+The SettingsIdentifier property allows the picker object to remember its own states.
+
+See the examples in [Note 2: The use case and implementation of SettingsIdentifier (Microsoft.Windows.Storage.Pickers.md)](./Microsoft.Windows.Storage.Pickers.md#note-2-the-use-case-and-implementation-of-settingsidentifier)
+
+### FileOpenPicker.InitialFileTypeIndex
+
+The InitialFileTypeIndex is a 0-based value deciding the auto-selected file type on dialog launch. 
+
+See the examples in [Note 3: Properties for File Types and The Initial Index (Microsoft.Windows.Storage.Pickers.md)](./Microsoft.Windows.Storage.Pickers.md#note-3-properties-for-file-types-and-its-auto-selection-on-launch)
+
+## Methods
+
+### FileOpenPicker.PickSingleFileAsync
 
 Displays a UI element that allows the user to choose and open one file.
 
 Returns a lightweight object that has the path of the picked file.
 
 Returns `null` if the file dialog was cancelled or closed without a selection.
 
-### Examples
+**Examples**
 
 C#
 
@@ -171,15 +217,15 @@ else
 }
 ```
 
-## FileOpenPicker.PickMultipleFilesAsync
+### FileOpenPicker.PickMultipleFilesAsync
 
 Displays a UI element that allows the user to choose and open multiple files.
 
 Returns a collection of lightweight objects that have the path of the picked files.
 
 Returns an empty list (`Count` = 0) if the file dialog was cancelled or closed without a selection.
 
-### Examples
+**Examples**
 
 C#
 

specs/Storage.Pickers/FileSavePicker.md

@@ -11,16 +11,22 @@ Represents a UI element that lets the user choose a file to save.
 
 ## Definition
 
-```C#
+```idl
 runtimeclass FileSavePicker
 {
     FileSavePicker(Microsoft.UI.WindowId windowId);
 
     string CommitButtonText;
+    string Title;
+    string SettingsIdentifier;
+
     string DefaultFileExtension;
     string SuggestedFileName;
 
     IMap<string, IVector<string>> FileTypeChoices{ get; };
+    Int32 InitialFileTypeIndex;
+
+    Boolean ShowOverwritePrompt;
 
     string SuggestedFolder;
     String SuggestedStartFolder;
@@ -64,14 +70,35 @@ var savePicker = new FileSavePicker(this.AppWindow.Id)
     //     If not specified, the system uses a default label of "Save" (suitably translated).
     CommitButtonText = "Save Document",
 
+    // (Optional) specify the title of the picker.
+    //     If not specified, the system uses a default title.
+    Title = "Save File",
+
+    // (Optional) allows customization of the settings name, to distinguish picker instances.
+    //     Without the SettingsIdentifier specified, pickers in one app share the state together.
+    //     Only specify this when a picker needs to track its own state (e.g. size, location, etc).
+    SettingsIdentifier = "BookContents",
+
     // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
     //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
     FileTypeChoices = {
-        { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
+        { "Text", new List<string> {".txt"} },
+        { "Documents", new List<string> { ".doc", ".docx" } }
     },
 
+    // (Optional) specify the index of the file type filter to be selected by default.
+    //     The index is 0-based. 
+    //     When not specified, its value is -1.
+    InitialFileTypeIndex = 1,  // this will auto-select Documents
+
+    // (Optional) Show a warning prompt of file overwrite when the user tries to pick an existing file.
+    //      Set to true by default.
+    ShowOverwritePrompt = true,
+
     // (Optional) specify the default file extension (will be appended to SuggestedFileName).
-    //      If not specified, no extension will be appended.
+    //     Note: the default extension applies when the active filter is "All Files (*)" 
+    //         or includes multiple extensions, and the default extension is one of them.
+    //     If not applied, no extension will be appended.
     DefaultFileExtension = ".txt",
 };
 ```
@@ -108,24 +135,73 @@ savePicker.SuggestedFileName(L"NewDocument");
 //     If not specified, the system uses a default label of "Save" (suitably translated).
 savePicker.CommitButtonText(L"Save Document");
 
+// (Optional) specify the title of the picker.
+//     If not specified, the system uses a default title.
+savePicker.Title(L"Save File");
+
+// (Optional) allows customization of the settings name, to distinguish picker instances.
+//     Without the SettingsIdentifier specified, pickers in one app share the state together.
+//     Only specify this when a picker needs to track its own state (e.g. size, location, etc).
+savePicker.SettingsIdentifier(L"BookContents");
+
 // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
 //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
-savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
+savePicker.FileTypeChoices().Insert(L"Texts", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
+savePicker.FileTypeChoices().Insert(L"Documents", winrt::single_threaded_vector<winrt::hstring>({ L".doc", L".docx" }));
+
+// (Optional) specify the index of the file type filter to be selected by default.
+//     The index is 0-based. 
+//     When not specified, its value is -1.
+savePicker.InitialFileTypeIndex(1);    // this will auto-select Documents
+
+// (Optional) Show a warning prompt of file overwrite when the user tries to pick an existing file.
+//      Set to true by default.
+savePicker.ShowOverwritePrompt(true);
 
 // (Optional) specify the default file extension (will be appended to SuggestedFileName).
-//      If not specified, no extension will be appended.
+//     Note: the default extension applies when the selected filter is "All Files (*)" 
+//        or includes multiple extensions, and the default extension is one of them.
+//     If not applied, no extension will be appended.
 savePicker.DefaultFileExtension(L".txt");
 ```
 
-## FileSavePicker.PickSaveFileAsync
+## New properties
+
+### FileSavePicker.Title
+
+Allow customizing the title of file dialog. It's based on the 
+[IFileDialog::SetTitle method](https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-ifiledialog-settitle)
+
+### FileSavePicker.SettingsIdentifier
+
+The `SettingsIdentifier` property allows the picker object to remember its own states.
+
+See the examples in [Note 2: The use case and implementation of SettingsIdentifier (Microsoft.Windows.Storage.Pickers.md)](./Microsoft.Windows.Storage.Pickers.md#note-2-the-use-case-and-implementation-of-settingsidentifier)
+
+### FileSavePicker.InitialFileTypeIndex
+
+The `InitialFileTypeIndex` property is 0-based. It decides the auto-selected file type on dialog launch.
+
+See the examples in [Note 3: Properties for File Types and The Initial Index (Microsoft.Windows.Storage.Pickers.md)](./Microsoft.Windows.Storage.Pickers.md#note-3-properties-for-file-types-and-its-auto-selection-on-launch)
+
+### FileSavePicker.ShowOverwritePrompt
+
+This property is `true` by default. It indicates whether the dialog prompts the user before picking
+an existing file via `FileSavePicker`. 
+
+It has the same behavior as of [SaveFileDialog.OverwritePrompt Property](https://learn.microsoft.com/en-us/dotnet/api/system.windows.forms.savefiledialog.overwriteprompt)
+
+## Methods
+
+### FileSavePicker.PickSaveFileAsync
 
 Displays a UI element that allows the user to configure the file path to save.
 
 Returns a lightweight object that has the path of the saved file.
 
 Returns `null` if the file dialog was cancelled or closed without saving a file.
 
-### Examples
+**Examples**
 
 C#