Skip to content

Commit e9048aa

Browse files
DinahK-2SODinah Gao (from Dev Box)DinahK-2SO
authored
Public Spec for Microsoft.Windows.Storage.Pickers (#5155)
* public spec for Microsoft.Windows.Storage.Pickers * add API definition; fix errors; graceful * PickFileResult and PickFolderResult * resolve comments * add Windows.Storage.StorageFile SuggestedSaveFile for backward compatability * add comment about HomeGroup may be removed in future. --------- Co-authored-by: Dinah Gao (from Dev Box) <[email protected]> Co-authored-by: DinahK-2SO <[email protected]>
1 parent b75d74e commit e9048aa

8 files changed

+818
-0
lines changed

‎specs/StoragePickers/FileOpenPicker.md

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

‎specs/StoragePickers/FileSavePicker.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
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+
21+
string SettingsIdentifier;
22+
string DefaultFileExtension;
23+
string SuggestedFileName;
24+
Windows.Storage.StorageFile SuggestedSaveFile;
25+
IMap<string, IVector<string>> FileTypeChoices{ get; };
26+
27+
PickerLocationId SuggestedStartLocation;
28+
29+
Windows.Foundation.IAsyncOperation<PickFileResult> PickSaveFileAsync()
30+
}
31+
```
32+
33+
## Constructor
34+
35+
### Examples
36+
C#
37+
38+
```C#
39+
using Microsoft.Windows.Storage.Pickers;
40+
41+
var savePicker = new FileSavePicker(this.AppWindow.Id)
42+
{
43+
// (Optional) specify the initial location.
44+
// If not specified, using PickerLocationId.Unspecified by default.
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) specify the text displayed on commit button. If not specified, use system default.
51+
CommitButtonText = "Save Document",
52+
53+
// (Optional) categorized extensions types. If not specified, use system default: All Files (*.*)
54+
FileTypeChoices = {
55+
{ "Documents", new List<string> { ".txt", ".doc", ".docx" } }
56+
},
57+
58+
// (Optional) specify the default file extension (will be appended after the default file name).
59+
// If not specified, will not appended after the default extension.
60+
DefaultFileExtension = ".txt",
61+
};
62+
```
63+
64+
C++
65+
66+
```C++
67+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
68+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
69+
70+
FileSavePicker savePicker(AppWindow().Id());
71+
72+
// (Optional) specify the initial location.
73+
// If not specified, using PickerLocationId.Unspecified by default
74+
savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
75+
76+
// (Optional) specify the default file name. If not specified, use system default.
77+
savePicker.SuggestedFileName(L"NewDocument");
78+
79+
// (Optional) categorized extensions types. If not specified, use system default: All Files (*.*)
80+
savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
81+
82+
// (Optional) specify the default file extension (will be appended after the default file name).
83+
// If not specified, will not appended after the default extension.
84+
savePicker.DefaultFileExtension(L".txt");
85+
```
86+
87+
## FileSavePicker.PickSaveFileAsync
88+
89+
Displays a UI element that allows the user to configure the file path to save.
90+
91+
Returns a light weight object that has the path of the saved file.
92+
93+
Returns null if the file dialog was cancelled or closed without saved file.
94+
95+
### Examples
96+
97+
C#
98+
99+
```C#
100+
using Microsoft.Windows.Storage.Pickers;
101+
102+
var savePicker = new FileSavePicker(this.AppWindow.Id);
103+
var result = await savePicker.PickSaveFileAsync();
104+
if (result is not null)
105+
{
106+
System.IO.File.WriteAllText(result.Path, "Hello world.");
107+
}
108+
else
109+
{
110+
// error handling.
111+
}
112+
```
113+
114+
C++
115+
116+
```C++
117+
#include <winrt/Microsoft.Windows.Storage.Pickers.h>
118+
#include <fstream>
119+
#include <string>
120+
using namespace winrt::Microsoft::Windows::Storage::Pickers;
121+
122+
FileSavePicker savePicker(AppWindow().Id());
123+
auto& result{ co_await savePicker.PickSaveFileAsync() };
124+
if (result)
125+
{
126+
std::ofstream outFile(result.Path().c_str());
127+
outFile << "Hello world.";
128+
outFile.close();
129+
}
130+
else
131+
{
132+
// error handling.
133+
}
134+
```
135+
136+
# See Also
137+
138+
[PickFileResult](./PickFileResult.md)

0 commit comments

Comments
 (0)