Official API Review for new functionalities of Storage.Pickers: SettingsIdentifier; FileTypeIndex; Title; PickMultipleFoldersAsync; ShowOverwritePrompt; CreateNewFileIfNotExists #6051
Conversation
…ickMultipleFoldersAsync
DinahK-2SO
added
the
area-File access
DinahK-2SO
force-pushed
the
user/DinahK-2SO/spec_settingsidentifier_filetypefilterindex_title
branch
from
e8f4450 to
7af6a89
Compare
|
@DinahK-2SO |
DinahK-2SO
changed the title
…ndex_title' of github.com:microsoft/WindowsAppSDK into user/DinahK-2SO/spec_settingsidentifier_filetypefilterindex_title
| string SettingsIdentifier; | ||
|
|
||
| IMap<string, IVector<string>> FileTypeChoices{ get; }; | ||
| IVector<string> FileTypeFilter{ get; }; |
There was a problem hiding this comment.
Why do we have both FileTypeChoices and FileTypeFilter?
Why does FileSavePicker only have FileTypeChoices?
Since FileSavePicker does not have FileTypeFilter, how does DefaultFileTypeFilterIndex work?
There was a problem hiding this comment.
Hi @kmahone , thanks for bringing up this topic! I have added a note for the file type related properties.
In short:
- We can see FileTypeChoices is an more customizable version of FileTypeFilter.
- The FileTypeFilter of open picker is retained for backward compatibility.
- The index property applies to both.
I also renamed the index property to be DefaultFileTypeIndex, as it applies to both FileTypeFilter and FileTypeChoices.
Please let me know your thoughts!
There was a problem hiding this comment.
Interesting. I think it is confusing to have a single property be the index into two different collections.
I think the best way forward is:
- Consider 'FileTypeFilter' as the old way of doing things and 'FileTypeChoices' as the new and improved way of doing things.
- New functionality should target FileTypeChoices.
So, we should have the index be named something like 'DefaultFileTypeChoicesIndex' and it should only apply to FileTypeChoices.
Another question:
What happens if someone sets BOTH of these properties? I assume that is an error?
There was a problem hiding this comment.
Hi @kmahone, thanks for the thoughtful feedback!
I’d like to post a perspective on why keeping one single index property (i.e., DefaultFileTypeIndex) is actually the cleaner and more internally consistent design.
FileTypeFilter and FileTypeChoices conceptually control the same UI element. Both APIs populate the same UX surface:
the “File types” dropdown at the bottom-right of the picker dialog.
From the end user’s perspective, that dropdown is a single list.
Whether items come from FileTypeFilter or FileTypeChoices does not change the conceptual model.
So from the app developer’s perspective, the “default index” is simply:
Which entry in that dropdown should be focused initially?
This is one single question, so one index property is a natural representation.
Lastly, answer to the last question:
What happens if someone sets BOTH of these properties? I assume that is an error?
NO, there won't be an error, FileTypeChoices simply takes precedence over the FileTypeFilter. In other words, when they're both specified, only the FileTypeChoices takes effects.
Please find details in Note 3
There was a problem hiding this comment.
Following an offline discussion with @kmahone, we’d like to gather additional suggestions from the API review team on this open question:
Should we add separate index properties for FileTypeChoices and FileTypeFilter, or keep the current design?
-
The current design using a single property (DefaultFileTypeIndex) since these three properties interact with the same file type UI element.
-
The alternative way is to add 2 properties:
DefaultFileTypeFilterIndexworks only forFileTypeFilterand comes to effect whenFileTypeFiltercomes to effect.DefaultFileTypeChoicesIndexworks only forFileTypeChoicesand comes to effect whenFileTypeChoicescomes to effect.
|
|
||
| // (Optional) create an empty file when the picked file does not yet exist. | ||
| // set to true by default. | ||
| CreateNewFileIfNotExists = true, |
There was a problem hiding this comment.
CreateNewFileIfNotExists = true by default means the picker may create files as a side effect of a UI operation?
Combined with ShowOverwritePrompt = false, this could lead to accidental data creation or replacement.
Whether true is the safest default here?
There was a problem hiding this comment.
Hi @Saharsh979 , thanks for raising up this topic!
CreateNewFileIfnotExists = true is already the default behavior of FileSavePicker. This default behavior is consistent with that of the UWP FileSavePicker. Here we're making it customizable so that developers can choose to disable it.
Please note the FileSavePicker should only create a new file when the picked file doesn't exists ( #6023 and #6024 ensured this check ). Therefore, ShowOverwritePrompt doesn't conflict with CreateNewFileIfnotExists in any combination, for the former takes effects when the picked file exists, and the latter works when the picked file doesn't exist.
With the 2 properties, developers will have the flexibility in showing their own warning prompts. Kindly find more details here: #5976
| string SettingsIdentifier; | ||
|
|
||
| IMap<string, IVector<string>> FileTypeChoices{ get; }; | ||
| IVector<string> FileTypeFilter{ get; }; |
There was a problem hiding this comment.
Hi @kmahone, thanks for the thoughtful feedback!
I’d like to post a perspective on why keeping one single index property (i.e., DefaultFileTypeIndex) is actually the cleaner and more internally consistent design.
FileTypeFilter and FileTypeChoices conceptually control the same UI element. Both APIs populate the same UX surface:
the “File types” dropdown at the bottom-right of the picker dialog.
From the end user’s perspective, that dropdown is a single list.
Whether items come from FileTypeFilter or FileTypeChoices does not change the conceptual model.
So from the app developer’s perspective, the “default index” is simply:
Which entry in that dropdown should be focused initially?
This is one single question, so one index property is a natural representation.
Lastly, answer to the last question:
What happens if someone sets BOTH of these properties? I assume that is an error?
NO, there won't be an error, FileTypeChoices simply takes precedence over the FileTypeFilter. In other words, when they're both specified, only the FileTypeChoices takes effects.
Please find details in Note 3
| selects the `Documents` group. | ||
|
|
||
| Additionally, if the index falls outside the available range, we treat it as `-1`, meaning the | ||
| picker ignores this setting and follows its built-in default. |
There was a problem hiding this comment.
@kmahone Please find the note of file types related properties here.
| string SettingsIdentifier; | ||
|
|
||
| IMap<string, IVector<string>> FileTypeChoices{ get; }; | ||
| IVector<string> FileTypeFilter{ get; }; |
There was a problem hiding this comment.
Following an offline discussion with @kmahone, we’d like to gather additional suggestions from the API review team on this open question:
Should we add separate index properties for FileTypeChoices and FileTypeFilter, or keep the current design?
-
The current design using a single property (DefaultFileTypeIndex) since these three properties interact with the same file type UI element.
-
The alternative way is to add 2 properties:
DefaultFileTypeFilterIndexworks only forFileTypeFilterand comes to effect whenFileTypeFiltercomes to effect.DefaultFileTypeChoicesIndexworks only forFileTypeChoicesand comes to effect whenFileTypeChoicescomes to effect.
|
|
||
| // (Optional) create an empty file when the picked file does not yet exist. | ||
| // set to true by default. | ||
| CreateNewFileIfNotExists = true, |
There was a problem hiding this comment.
Hi @Saharsh979 , thanks for raising up this topic!
CreateNewFileIfnotExists = true is already the default behavior of FileSavePicker. This default behavior is consistent with that of the UWP FileSavePicker. Here we're making it customizable so that developers can choose to disable it.
Please note the FileSavePicker should only create a new file when the picked file doesn't exists ( #6023 and #6024 ensured this check ). Therefore, ShowOverwritePrompt doesn't conflict with CreateNewFileIfnotExists in any combination, for the former takes effects when the picked file exists, and the latter works when the picked file doesn't exist.
With the 2 properties, developers will have the flexibility in showing their own warning prompts. Kindly find more details here: #5976
This pull request updates the Storage.Pickers API specifications to add new customization and usability features to the
FileOpenPicker,FileSavePicker, andFolderPickerclasses. The changes introduce properties for dialog title and persistent settings, allow specifying the default file type filter, and add support for picking multiple folders. These enhancements are reflected in both the API definitions and usage examples.Adds properties:
Title
Titleproperties toFileOpenPicker,FileSavePicker, andFolderPicker, enabling custom dialog titles and persistent picker state across sessions. ([1], [2], [3], [4], [5], [6])Related:
SettingsIdentifier
SettingsIdentifierproperties toFileOpenPicker,FileSavePicker, andFolderPicker, enabling custom dialog titles and persistent picker state across sessions. ([1], [2], [3], [4], [5], [6])Related:
FileTypeIndex
FileTypeIndexproperty toFileOpenPickerandFileSavePicker, allowing developers to set the default selected file type filter by index (1-based). This is documented and shown in usage examples. ([1], [2], [3], [4], [5], [6], [7], [8])Related:
FileSavePicker.ShowOverwritePrompt & FileSavePicker.CreateNewFileIfNotExists
FileSavePicker:ShowOverwritePromptandCreateNewFileIfNotExists.ShowOverwritePromptdefault totrueand control whether the picker warns about overwriting when user picked an existing file via FileSavePicker.CreateNewFileIfNotExistsdefault totrueand control whether to auto-create an empty file when the picked file doesn't exists.Related:
Adds method:
FolderPicker.PickMultipleFoldersAsync
PickMultipleFoldersAsyncmethod toFolderPicker, enabling selection of multiple folders in a single operation. API definitions, documentation, and code samples have been updated to reflect this feature. ([1], [2], [3]`)Related: