Skip to content

Commit 7388ca4

Browse files
DinahK-2SODinahK-2SO
authored
Official API Review for Microsoft.Windows.Storage.Pickers (#5634)
* create the files for official API review * add spec notes for official review * update doc * add details; graceful * update the specs * Resolve comments; Fix typos and grammer errors in doc. * FileSavePicker.SuggestedFolder
1 parent d55e2a3 commit 7388ca4

File tree

8 files changed

+883
-0
lines changed

8 files changed

+883
-0
lines changed

‎specs/Storage.Pickers/FileOpenPicker.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
FileOpenPicker Class
2+
===
3+
4+
# Background
5+
6+
Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md)
7+
8+
Represents a UI element that lets the user choose and open files.
9+
10+
Supports specifying the initial location, extension filters, and text on commit button.
11+
12+
# API Pages
13+
14+
## Definition
15+
16+
```C#
17+
runtimeclass FileOpenPicker
18+
{
19+
FileOpenPicker(Microsoft.UI.WindowId windowId);
20+
21+
string CommitButtonText;
22+
IVector<string> FileTypeFilter{ get; };
23+
PickerLocationId SuggestedStartLocation;
24+
PickerViewMode ViewMode;
25+
26+
Windows.Foundation.IAsyncOperation<PickFileResult> PickSingleFileAsync();
27+
Windows.Foundation.IAsyncOperation<IVectorView<PickFileResult>> PickMultipleFilesAsync();
28+
}
29+
```
30+
31+
## Constructor
32+
33+
### Examples
34+
C#
35+
36+
```C#
37+
using Microsoft.Windows.Storage.Pickers;
38+
39+
var openPicker = new FileOpenPicker(this.AppWindow.Id)
40+
{
41+
// (Optional) Specify the initial location for the picker.
42+
// If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
43+
// If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
44+
SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
45+
46+
// (Optional) specify the text displayed on the commit button.
47+
// If not specified, the system uses a default label of "Open" (suitably translated).
48+
CommitButtonText = "Choose selected files",
49+
50+
// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
51+
FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },
52+
53+
// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
54+
ViewMode = PickerViewMode.List,
55+
};
56+
```
57+
58+
C++
59+
60+
```C++
61+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
62+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
63+
64+
FileOpenPicker openPicker(AppWindow().Id());
65+
66+
// (Optional) Specify the initial location for the picker.
67+
// If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
68+
// If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
69+
openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
70+
71+
// (Optional) specify the text displayed on the commit button.
72+
// If not specified, the system uses a default label of "Open" (suitably translated).
73+
openPicker.CommitButtonText(L"Choose selected files");
74+
75+
// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
76+
openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });
77+
78+
// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
79+
openPicker.ViewMode(PickerViewMode::List);
80+
```
81+
82+
## FileOpenPicker.PickSingleFileAsync
83+
84+
Displays a UI element that allows the user to choose and open one file.
85+
86+
Returns a lightweight object that has the path of the picked file.
87+
88+
Returns `null` if the file dialog was cancelled or closed without a selection.
89+
90+
### Examples
91+
92+
C#
93+
94+
```C#
95+
using Microsoft.Windows.Storage.Pickers;
96+
97+
var openPicker = new FileOpenPicker(this.AppWindow.Id);
98+
99+
var result = await openPicker.PickSingleFileAsync();
100+
if (result is not null)
101+
{
102+
var content = System.IO.File.ReadAllText(result.Path);
103+
}
104+
else
105+
{
106+
// error handling.
107+
}
108+
```
109+
110+
C++
111+
```C++
112+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
113+
#include <fstream>
114+
#include <string>
115+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
116+
117+
FileOpenPicker openPicker(AppWindow().Id());
118+
auto result{ co_await openPicker.PickSingleFileAsync() };
119+
if (result)
120+
{
121+
std::ifstream fileReader(result.Path().c_str());
122+
std::string text(std::istreambuf_iterator(fileReader), {});
123+
winrt::hstring hText = winrt::to_hstring(text);
124+
}
125+
else
126+
{
127+
// error handling.
128+
}
129+
```
130+
131+
## FileOpenPicker.PickMultipleFilesAsync
132+
133+
Displays a UI element that allows the user to choose and open multiple files.
134+
135+
Returns a collection of lightweight objects that have the path of the picked files.
136+
137+
Returns an empty list (`Count` = 0) if the file dialog was cancelled or closed without a selection.
138+
139+
### Examples
140+
141+
C#
142+
143+
```C#
144+
using Microsoft.Windows.Storage.Pickers;
145+
146+
var openPicker = new FileOpenPicker(this.AppWindow.Id);
147+
148+
var results = await openPicker.PickMultipleFilesAsync();
149+
if (results.Count > 0)
150+
{
151+
var pickedFilePaths = results.Select(f => f.Path);
152+
foreach (var path in pickedFilePaths)
153+
{
154+
var content = System.IO.File.ReadAllText(path);
155+
}
156+
}
157+
else
158+
{
159+
// error handling.
160+
}
161+
```
162+
163+
C++
164+
```C++
165+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
166+
#include <fstream>
167+
#include <string>
168+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
169+
170+
FileOpenPicker openPicker(AppWindow().Id());
171+
auto results{ co_await openPicker.PickMultipleFilesAsync() };
172+
if (results.Size() > 0)
173+
{
174+
for (auto const& result : results)
175+
{
176+
std::ifstream fileReader(result.Path().c_str());
177+
std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
178+
winrt::hstring hText = winrt::to_hstring(text);
179+
}
180+
}
181+
else
182+
{
183+
// error handling.
184+
}
185+
```
186+
187+
# See Also
188+
189+
[PickFileResult](./PickFileResult.md)

‎specs/Storage.Pickers/FileSavePicker.md

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
FileSavePicker Class
2+
===
3+
4+
# Background
5+
6+
Namespace: [Microsoft.Windows.Storage.Pickers](./Microsoft.Windows.Storage.Pickers.md)
7+
8+
Represents a UI element that lets the user choose a file to save.
9+
10+
# API Pages
11+
12+
## Definition
13+
14+
```C#
15+
runtimeclass FileSavePicker
16+
{
17+
FileSavePicker(Microsoft.UI.WindowId windowId);
18+
19+
string CommitButtonText;
20+
string DefaultFileExtension;
21+
string SuggestedFileName;
22+
string SuggestedFolder;
23+
24+
IMap<string, IVector<string>> FileTypeChoices{ get; };
25+
26+
PickerLocationId SuggestedStartLocation;
27+
28+
Windows.Foundation.IAsyncOperation<PickFileResult> PickSaveFileAsync();
29+
}
30+
```
31+
32+
## Constructor
33+
34+
### Examples
35+
C#
36+
37+
```C#
38+
using Microsoft.Windows.Storage.Pickers;
39+
40+
var savePicker = new FileSavePicker(this.AppWindow.Id)
41+
{
42+
// (Optional) Specify the initial location for the picker.
43+
// If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
44+
// If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
45+
SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
46+
47+
// (Optional) specify the default file name. If not specified, use system default.
48+
SuggestedFileName = "My Document",
49+
50+
// (Optional) Sets the folder that the file save dialog displays when it opens.
51+
// If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
52+
SuggestedFolder = @"C:\MyFiles",
53+
54+
// (Optional) specify the text displayed on the commit button.
55+
// If not specified, the system uses a default label of "Save" (suitably translated).
56+
CommitButtonText = "Save Document",
57+
58+
// (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
59+
// Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
60+
FileTypeChoices = {
61+
{ "Documents", new List<string> { ".txt", ".doc", ".docx" } }
62+
},
63+
64+
// (Optional) specify the default file extension (will be appended to SuggestedFileName).
65+
// If not specified, no extension will be appended.
66+
DefaultFileExtension = ".txt",
67+
};
68+
```
69+
70+
C++
71+
72+
```C++
73+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
74+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
75+
76+
FileSavePicker savePicker(AppWindow().Id());
77+
78+
// (Optional) Specify the initial location for the picker.
79+
// If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
80+
// If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
81+
savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
82+
83+
// (Optional) specify the default file name. If not specified, use system default.
84+
savePicker.SuggestedFileName(L"NewDocument");
85+
86+
// (Optional) Sets the folder that the file save dialog displays when it opens.
87+
// If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
88+
savePicker.SuggestedFolder = L"C:\\MyFiles",
89+
90+
// (Optional) specify the text displayed on the commit button.
91+
// If not specified, the system uses a default label of "Save" (suitably translated).
92+
savePicker.CommitButtonText(L"Save Document");
93+
94+
// (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
95+
// Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
96+
savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
97+
98+
// (Optional) specify the default file extension (will be appended to SuggestedFileName).
99+
// If not specified, no extension will be appended.
100+
savePicker.DefaultFileExtension(L".txt");
101+
```
102+
103+
## FileSavePicker.PickSaveFileAsync
104+
105+
Displays a UI element that allows the user to configure the file path to save.
106+
107+
Returns a lightweight object that has the path of the saved file.
108+
109+
Returns `null` if the file dialog was cancelled or closed without saving a file.
110+
111+
### Examples
112+
113+
C#
114+
115+
```C#
116+
using Microsoft.Windows.Storage.Pickers;
117+
118+
var savePicker = new FileSavePicker(this.AppWindow.Id);
119+
var result = await savePicker.PickSaveFileAsync();
120+
if (result is not null)
121+
{
122+
System.IO.File.WriteAllText(result.Path, "Hello world.");
123+
}
124+
else
125+
{
126+
// error handling.
127+
}
128+
```
129+
130+
C++
131+
132+
```C++
133+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
134+
#include <fstream>
135+
#include <string>
136+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
137+
138+
FileSavePicker savePicker(AppWindow().Id());
139+
auto result{ co_await savePicker.PickSaveFileAsync() };
140+
if (result)
141+
{
142+
std::ofstream outFile(result.Path().c_str());
143+
outFile << "Hello world.";
144+
outFile.close();
145+
}
146+
else
147+
{
148+
// error handling.
149+
}
150+
```
151+
152+
# See Also
153+
154+
* [PickFileResult](./PickFileResult.md)

0 commit comments

Comments
 (0)