Skip to content

Commit d9069a9

Browse files
ambikakunnathambikakunnath
authored
Template md file
1 parent 325c907 commit d9069a9

1 file changed

Lines changed: 254 additions & 0 deletions

File tree

‎specs/WindowsRecall.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,255 @@
1+
<!--
2+
Before submitting, delete all "<!-- TEMPLATE" marked comments in this file,
3+
and the following quote banner:
4+
-->
5+
> See comments in Markdown for how to use this spec template
16
7+
<!-- TEMPLATE
8+
The purpose of this spec is to describe new APIs, in a way
9+
that will transfer to learn.microsoft.com (https://learn.microsoft.com/microsoft-edge/webview2/).
10+
11+
There are two audiences for the spec. The first are people that want to evaluate and
12+
give feedback on the API, as part of the submission process.
13+
So the second audience is everyone that reads there to learn how and why to use this API.
14+
Some of this text also shows up in Visual Studio Intellisense.
15+
When the PR is complete, the content within the 'Conceptual Pages' section of the review spec will be incorporated into the public documentation at
16+
http://learn.microsoft.com (LMC).
17+
18+
For example, much of the examples and descriptions in the `RadialGradientBrush` API spec
19+
(https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/RadialGradientBrush/RadialGradientBrush.md)
20+
were carried over to the public API page on LMC
21+
(https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.media.radialgradientbrush?view=winui-2.5)
22+
23+
Once the API is on LMC, that becomes the official copy, and this spec becomes an archive.
24+
For example if the description is updated, that only needs to happen on LMC and needn't
25+
be duplicated here.
26+
27+
Examples:
28+
* New set of classes and APIs (Custom Downloads):
29+
https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md
30+
* New member on an existing class (BackgroundColor):
31+
https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/BackgroundColor.md
32+
33+
Style guide:
34+
* Use second person; speak to the developer who will be learning/using this API.
35+
(For example "you use this to..." rather than "the developer uses this to...")
36+
* Use hard returns to keep the page width within ~100 columns.
37+
(Otherwise it's more difficult to leave comments in a GitHub PR.)
38+
* Talk about an API's behavior, not its implementation.
39+
(Speak to the developer using this API, not to the team implementing it.)
40+
* A picture is worth a thousand words.
41+
* An example is worth a million words.
42+
* Keep examples realistic but simple; don't add unrelated complications.
43+
(An example that passes a stream needn't show the process of launching the File-Open dialog.)
44+
* Use GitHub flavored Markdown: https://guides.github.com/features/mastering-markdown/
45+
46+
-->
47+
48+
Title
49+
===
50+
51+
# Background
52+
<!-- TEMPLATE
53+
Use this section to provide background context for the new API(s)
54+
in this spec. Try to briefly provide enough information to be able to read
55+
the rest of the document.
56+
57+
This section and the appendix are the only sections that likely
58+
do not get copied into any official documentation, they're just an aid
59+
to reading this spec. If you find useful information in the background
60+
or appendix consider moving it to documentation.
61+
62+
If you're modifying an existing API, included a link here to the
63+
existing page(s) or spec documentation.
64+
65+
For example, this section is a place to explain why you're adding this
66+
API rather than modifying an existing API.
67+
68+
For example, this is a place to provide a brief explanation of some dependent
69+
area, just explanation enough to understand this new API, rather than telling
70+
the reader "go read 100 pages of background information posted at ...".
71+
-->
72+
73+
# Conceptual pages (How To)
74+
75+
_(This is conceptual documentation that will go to learn.microsoft.com "how to" page)_
76+
77+
<!-- TEMPLATE
78+
(Optional)
79+
80+
All APIs have reference docs, but some APIs or groups of APIs have an additional high level,
81+
conceptual page (called a "how-to" page). This section can be used for that content.
82+
83+
For example, there are several navigation events each with their own reference doc, but then
84+
there's also a concept doc on navigation
85+
(https://learn.microsoft.com/microsoft-edge/webview2/concepts/navigation-events).
86+
87+
Sometimes it's difficult to decide if text belongs on a how-to page or an API page.
88+
Because our API reference documentation is automatically turned into reference docs you can
89+
lean towards including text in the API documentation below instead of in this conceptual
90+
section.
91+
-->
92+
93+
94+
# Examples
95+
<!-- TEMPLATE
96+
Use this section to explain the features of the API, showing
97+
example code with each description in both C# (for our WinRT API or .NET API) and
98+
in C++ for our COM API. Use snippets of the sample code you wrote for the sample apps.
99+
The sample code for C++ and C# should demonstrate the same thing.
100+
If you are introducing a JavaScript API or otherwise the sample relies on HTML or JS
101+
include that and consider including it in its own HTML or JS sample code.
102+
103+
As an example of this section, see the Examples section for the Custom Downloads
104+
APIs (https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md).
105+
106+
The general format is:
107+
108+
## FirstFeatureName
109+
110+
Feature explanation text goes here, including why an app would use it, how it
111+
replaces or supplements existing functionality.
112+
113+
```c#
114+
void SampleMethod()
115+
{
116+
var show = new AnExampleOf();
117+
show.SomeMembers = AndWhyItMight(be, interesting)
118+
}
119+
```
120+
121+
```cpp
122+
void SampleClass::SampleMethod()
123+
{
124+
winrt::com_ptr<ICoreWebView2> webview2 = ...
125+
}
126+
```
127+
128+
If the sample code requires JS or HTML include that as well
129+
130+
```html
131+
<script>
132+
chrome.webview.postMessage(...);
133+
</script>
134+
```
135+
136+
## SecondFeatureName
137+
138+
Feature explanation text goes here, including why an app would use it, how it
139+
replaces or supplements existing functionality.
140+
141+
```c#
142+
void SampleMethod()
143+
{
144+
var show = new AnExampleOf();
145+
show.SomeMembers = AndWhyItMight(be, interesting)
146+
}
147+
```
148+
149+
```cpp
150+
void SampleClass::SampleMethod()
151+
{
152+
winrt::com_ptr<ICoreWebView2> webview2 = ...
153+
}
154+
```
155+
156+
157+
If the sample code requires JS or HTML include that as well
158+
159+
```html
160+
<script>
161+
chrome.webview.postMessage(...);
162+
</script>
163+
```
164+
165+
-->
166+
167+
# API Details
168+
<!-- TEMPLATE
169+
The exact API, in IDL format for our COM API and
170+
in MIDL3 format (https://learn.microsoft.com/uwp/midl-3/)
171+
when possible.
172+
173+
Include every new or modified type but use // ... to remove any methods,
174+
properties, or events that are unchanged.
175+
176+
For the MIDL3 parts, after running build-apiwriter, open the generated
177+
`Microsoft.Web.WebView2.Core.idl` and find the new or modified portions
178+
generated from your modifications to the COM IDL.
179+
180+
(GitHub's markdown syntax formatter does not (yet) know about MIDL3, so
181+
use ```c# instead even when writing MIDL3.)
182+
183+
Example:
184+
185+
```
186+
[uuid(B625A89E-368F-43F5-BCBA-39AA6234CCF8), object, pointer_default(unique)]
187+
interface ICoreWebView2Settings4 : ICoreWebView2Settings3 {
188+
/// The IsPinchZoomEnabled property enables or disables the ability of
189+
/// the end user to use a pinching motion on touch input enabled devices
190+
/// to scale the web content in the WebView2. It defaults to TRUE.
191+
/// When set to FALSE, the end user cannot pinch zoom.
192+
/// This API only affects the Page Scale zoom and has no effect on the
193+
/// existing browser zoom properties (IsZoomControlEnabled and ZoomFactor)
194+
/// or other end user mechanisms for zooming.
195+
///
196+
/// \snippet SettingsComponent.cpp TogglePinchZooomEnabled
197+
[propget] HRESULT IsPinchZoomEnabled([out, retval] BOOL* enabled);
198+
/// Set the IsPinchZoomEnabled property
199+
[propput] HRESULT IsPinchZoomEnabled([in] BOOL enabled);
200+
}
201+
```
202+
203+
```c# (but really MIDL3)
204+
namespace Microsoft.Web.WebView2.Core
205+
{
206+
runtimeclass CoreWebView2Settings
207+
{
208+
// ...
209+
210+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings5")]
211+
{
212+
Boolean IsPinchZoomEnabled { get; set; };
213+
}
214+
}
215+
}
216+
```
217+
218+
If you are introducing a WebView2 JavaScript API include the TypeScript
219+
definition of that API and reference documentation for it as well.
220+
You can use https://www.typescriptlang.org/play to verify your TypeScript
221+
222+
```ts
223+
interface WebView extends EventTarget {
224+
postMessage(message: any) : void;
225+
hostObjects: HostObjectsAsyncRoot;
226+
// ...
227+
}
228+
229+
interface HostObjectsAsyncRoot {
230+
cleanupSome() : void;
231+
options: HostObjectsOptions;
232+
}
233+
234+
interface HostObjectsOptions {
235+
forceLocalProperties: string[];
236+
log: (...data: any[]) => void;
237+
shouldSerializeDates: boolean;
238+
defaultSyncProxy: boolean;
239+
forceAsyncMethodMatches: RegExp[];
240+
ignoreMemberNotFoundError: boolean;
241+
}
242+
```
243+
244+
-->
245+
246+
247+
# Appendix
248+
<!-- TEMPLATE
249+
Anything else that you want to write down about implementation notes and for posterity,
250+
but that isn't necessary to understand the purpose and usage of the API.
251+
252+
This or the Background section are a good place to describe alternative designs
253+
and why they were rejected, any relevant implementation details, or links to other
254+
resources.
255+
-->

0 commit comments

Comments
 (0)