Add Spec for IsWindowControlsOverlayEnabled.md #4613
Conversation
tochukwuIbeEkeocha
added
the
API Proposal Review
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
2038eac to
e886ba5
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
2 times, most recently
from
657def7 to
d395730
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
7 times, most recently
from
3866c89 to
bce67e9
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
bce67e9 to
700ec3a
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
700ec3a to
654b176
Compare
|
Is there any ETA on when this update might come to webview2? |
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
654b176 to
5a4eb5f
Compare
Co-authored-by: David Risney <dave@deletethis.net>
Co-authored-by: David Risney <dave@deletethis.net>
Co-authored-by: Viktoria Zlatinova <vizlatin@microsoft.com>
Co-authored-by: Viktoria Zlatinova <vizlatin@microsoft.com>
Co-authored-by: Viktoria Zlatinova <vizlatin@microsoft.com>
Co-authored-by: David Risney <dave@deletethis.net>
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
2f02f47 to
b38a178
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
b38a178 to
a6cc969
Compare
tochukwuIbeEkeocha
force-pushed
the
api-isWindowControlsOverlayEnabled-draft
branch
from
a6cc969 to
01a2caf
Compare
| # Background | ||
| This API allows you to enable and configure the Webview2 Window Controls Overlay. | ||
| The Overlay is a region on the top right/left of the webview window which contains | ||
| the caption buttons (minimize, maximize, restore, close). Enabing the Overlay allows |
There was a problem hiding this comment.
nit:
| the caption buttons (minimize, maximize, restore, close). Enabing the Overlay allows | |
| the caption buttons (minimize, maximize, restore, close). Enabling the Overlay allows |
| CHECK_FAILURE(coreWebView2->QueryInterface(&coreWebView2_28)); | ||
|
|
||
| wil::com_ptr<ICoreWebView2WindowControlsOverlaySettings> windowControlsOverlaySettings; | ||
| CHECK_FAILURE(coreWebView2_28->get_WindowControlsOverlaySettings(&wco_config)); |
There was a problem hiding this comment.
different variable names, wco_config & windowControlsOverlaySettings
There was a problem hiding this comment.
Sample bug. Please make sure sample code compiles.
| /// title bar area. Defaults to 48px. There is no minimum height restriction for this API, | ||
| /// so it is up to the developer to make sure that the height of your window controls overlay | ||
| /// is enough that users can see and interact with it. We recommend using GetSystemMetrics(SM_CYCAPTION) | ||
| // as you minimum height. |
There was a problem hiding this comment.
| // as you minimum height. | |
| // as your minimum height. |
| /// The Overlay buttons will sit on top of the HTML content, and will prevent mouse interactions | ||
| /// with any elements directly below it, so you should avoid placing content there. | ||
| /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) | ||
| /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you |
| /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) | ||
| /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you | ||
| /// get the dimensions of the available titlebar area to the left of the overlay. | ||
| /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) |
There was a problem hiding this comment.
| /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) | |
| /// Similarly the navigator object will contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) |
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will |
There was a problem hiding this comment.
| ///will automatically calculate a foreground and hover color that will | |
| /// will automatically calculate a foreground and hover color that will |
|
|
||
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; | ||
| config.IsEnabled = true; | ||
| config.color = Color.FromARGB(0, 0, 255); |
There was a problem hiding this comment.
Does the order of setting these properties matter? If I set enabled=true before setting .color might there be a frame rendered of the overlay with the default color?
There was a problem hiding this comment.
Please update docs to say when does the IsEnabled change take affect - immediate or batched once the UI thread has a chance to work.
Prefer: the order shouldn't matter. If order matters we'll follow up.
| [propget] HRESULT TitleBarBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); | ||
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 |
There was a problem hiding this comment.
This is the overlay, so why is it called TitleBarBackgroundColor? https://wicg.github.io/window-controls-overlay/#concepts suggests this color will apply to the controls overlay, not the "title bar area". Based on the API comments for IsEnabled "You are responsible for creating a title bar for your app" I understand us to have removed the title bar from being system-controlled UI.
Property name can be just "BackgroundColor" if it refers to the background color of the WindowControlsOverlay, since it's in the context of being a CoreWebView2WindowControlsOverlaySettings property.
There was a problem hiding this comment.
Please rename BackgroundColor
| /// | ||
| /// When using this you should configure your app window to not display its default | ||
| /// window control buttons. You are responsible for creating a title bar for your app | ||
| /// by using the available space to the left of the controls overlay. In doing so, |
There was a problem hiding this comment.
Is this right or left conditional on the reading direction of the UI root?
There was a problem hiding this comment.
Please document what happens for RTL locales - does the controls overlay render on the left instead of right?
In the text here say 'before' instead of 'left'
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will |
There was a problem hiding this comment.
Is foreground color necessarily black or white? We might be leaving this undocumented to reserve the right to choose colors based on the hosting app?
There was a problem hiding this comment.
They won't be white/black it will be based on the background color.
It would be helpful to include some screenshots of examples.
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. |
There was a problem hiding this comment.
"best" is subjective. I suggest documenting just which guarantees WebView2 is making regarding color and contrast. I suspect this is something like e.g. "WebView2 will use a foreground color that maintains at least 3:1 contrast radio with your chosen color."
There was a problem hiding this comment.
End sentence just before 'that will provide you...' so we don't have to make statements about our contrast and so on.
Note to us implementing: Ensure we're picking colors as described above by Frank.
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. | ||
| /// Defaults to #f3f3f3. This API supports transparency. |
There was a problem hiding this comment.
What does it mean to "maintain accessibility" if the background color is transparent. I expect at that point we can't make any guarantee about the foreground color relative to the webview content. Is it in scope to consider that?
There was a problem hiding this comment.
No change. We removed the text above making a claim about contrast/accessibility above.
| /// | ||
| /// The Overlay buttons will sit on top of the HTML content, and will prevent mouse interactions | ||
| /// with any elements directly below it, so you should avoid placing content there. | ||
| /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) |
| # Background | ||
| This API allows you to enable and configure the Webview2 Window Controls Overlay. | ||
| The Overlay is a region on the top right/left of the webview window which contains | ||
| the caption buttons (minimize, maximize, restore, close). Enabing the Overlay allows |
| CHECK_FAILURE(coreWebView2->QueryInterface(&coreWebView2_28)); | ||
|
|
||
| wil::com_ptr<ICoreWebView2WindowControlsOverlaySettings> windowControlsOverlaySettings; | ||
| CHECK_FAILURE(coreWebView2_28->get_WindowControlsOverlaySettings(&wco_config)); |
There was a problem hiding this comment.
Sample bug. Please make sure sample code compiles.
| InitializeComponent(); | ||
| m_AppWindow.TitleBar.ExtendsContentIntoTitleBar = true; | ||
|
|
||
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; |
There was a problem hiding this comment.
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; | |
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebView2.WindowControlsOverlaySettings; |
|
|
||
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; | ||
| config.IsEnabled = true; | ||
| config.color = Color.FromARGB(0, 0, 255); |
There was a problem hiding this comment.
| config.color = Color.FromARGB(0, 0, 255); | |
| config.Color = Color.FromARGB(0, 0, 255); |
|
|
||
| CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; | ||
| config.IsEnabled = true; | ||
| config.color = Color.FromARGB(0, 0, 255); |
There was a problem hiding this comment.
Please update docs to say when does the IsEnabled change take affect - immediate or batched once the UI thread has a chance to work.
Prefer: the order shouldn't matter. If order matters we'll follow up.
| [propget] HRESULT Height([out, retval] UINT32* value); | ||
|
|
||
|
|
||
| /// The `Height` property in raw screen pixels, allows you to set the height of the overlay and |
There was a problem hiding this comment.
@bradp0721 Does it make sense to use raw screen pixels here vs view pixels?
Also, we should ensure that different DPI awareness doesn't create bugs with real raw pixels vs virtual DPI scaled raw pixels.
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. | ||
| /// Defaults to #f3f3f3. This API supports transparency. |
There was a problem hiding this comment.
Document that it does not support changing the default color or default height for OS theming (dark/light mode and high contrast) and height.
|
|
||
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will |
There was a problem hiding this comment.
They won't be white/black it will be based on the background color.
It would be helpful to include some screenshots of examples.
| /// The `TitleBarBackgroundColor` property allows you to set a background color | ||
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. |
There was a problem hiding this comment.
End sentence just before 'that will provide you...' so we don't have to make statements about our contrast and so on.
Note to us implementing: Ensure we're picking colors as described above by Frank.
| /// for the overlay. Based on the background color you choose, Webview2 | ||
| ///will automatically calculate a foreground and hover color that will | ||
| /// provide you the best contrast while maintaining accessibility. | ||
| /// Defaults to #f3f3f3. This API supports transparency. |
There was a problem hiding this comment.
No change. We removed the text above making a claim about contrast/accessibility above.
What
These new APIs introduce support for a Webview2 Window Controls Overlay. The Window Controls Overlay will allow developers to build apps in webview2 with 100% of the UI controlled by the browser process. Devs will be able to create their apps as borderless & caption-less windows, and have the Webview draw its own window control buttons (minimize,maximize, close, restore).