Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add specs for AcceleratorKeyPressed event args extension APIs #3861

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 182 additions & 0 deletions specs/ExtendedAcceleratorKeyPressed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
# Background
WebView2 has `ICoreWebView2AcceleratorKeyPressedEventArgs` for the `AcceleratorKeyPressed`
event. We have been asked to extend this API so that developers can indicate that they
would like an existing browser accelerator key to be disabled as a browser accelerator.

In this document we describe the updated API. We'd appreciate your feedback.

# Description
We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow developers
to enable/disable the browser from handling accelerator keys with `AllowBrowserAcceleratorHandling`
property.
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved

# Examples
## C++

``` cpp
EventRegistrationToken m_acceleratorKeyPressedToken = {};

wil::com_ptr<ICoreWebView2Controller> m_controller;
wil::com_ptr<ICoreWebView2> m_webView;
wil::com_ptr<ICoreWebView2Settings3> m_settings3;

{
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
wil::com_ptr<ICoreWebView2Settings> settings;
CHECK_FAILURE(m_webView->get_Settings(&settings));
m_settings3 = settings.try_query<ICoreWebView2Settings3>();
if (m_setting3)
{
// Disable all browser accelerator keys. The default value for the
// `AllowBrowserAcceleratorHandling` property is set to the current value of this
// setting. Changing this setting to `false` will change the default setting for
// AllowBrowserAcceleratorHandling to `false`.
CHECK_FAILURE(m_settings3->put_AreBrowserAcceleratorKeysEnabled(FALSE));
// Register a handler for the AcceleratorKeyPressed event.
CHECK_FAILURE(m_controller->add_AcceleratorKeyPressed(
Callback<ICoreWebView2AcceleratorKeyPressedEventHandler>(
[this](
ICoreWebView2Controller* sender,
ICoreWebView2AcceleratorKeyPressedEventArgs* args) -> HRESULT
{
COREWEBVIEW2_KEY_EVENT_KIND kind;
CHECK_FAILURE(args->get_KeyEventKind(&kind));
// We only care about key down events.
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
if (kind == COREWEBVIEW2_KEY_EVENT_KIND_KEY_DOWN ||
kind == COREWEBVIEW2_KEY_EVENT_KIND_SYSTEM_KEY_DOWN)
{
UINT key;
CHECK_FAILURE(args->get_VirtualKey(&key));

wil::com_ptr<ICoreWebView2AcceleratorKeyPressedEventArgs2>
args2;

args->QueryInterface(IID_PPV_ARGS(&args2));
if (args)
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
{
if (key == VK_F7)
{
// Allow the browser to process F7 key
CHECK_FAILURE(args2->put_AllowBrowserAcceleratorHandling(TRUE));
}
}
}
return S_OK;
})
.Get(),
&m_acceleratorKeyPressedToken));

}
}
```

## C#
```c#
CoreWebView2Settings _webViewSettings = webView.CoreWebView2.Settings;
// All browser accelerator keys are disabled with this setting. The default value for the
// `AllowBrowserAcceleratorHandling`property is set to the current value of this setting.
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
// Changing this setting to `false` will change the default setting for
// AllowBrowserAcceleratorHandling to `false`
_webViewSettings.AreBrowserAcceleratorKeysEnabled = false;

webView.CoreWebView2.AcceleratorKeyPressed += WebView2Controller_AcceleratorKeyPressed;

void WebView2Controller_AcceleratorKeyPressed(object sender, CoreWebView2AcceleratorKeyPressedEventArgs e)
{
switch (e.KeyEventKind)
{
case CoreWebView2KeyEventKind.KeyDown:
case CoreWebView2KeyEventKind.SystemKeyDown:
{
// Allow the browser to process F7 key
if (e.VirtualKey == Key.F7)
{
e.AllowBrowserAcceleratorHandling = true;
}
break;
}

}
}

```

# Remarks
By default, `AreBrowserAcceleratorKeysEnabled` is `TRUE` and default value for `AllowBrowserAcceleratorHandling`
is `TRUE`. When developers set `AreBrowserAcceleratorKeysEnabled` to `FALSE` this will also change the default
value for `AllowBrowserAcceleratorHandling` to `FALSE`. If developers want specific keys to be handled by the
browser after changing the `AreBrowserAcceleratorKeysEnabled` settings to `FALSE`, they need to enable them by
setting `event_args->put_ AllowBrowserAcceleratorHandling(TRUE)`. This option will give the event arg higher
priority over the settings when the browser decide whether to handle the keys.

# API Details
## C++
```
/// This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface.
[uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)]
interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs {
/// Browser accelerator keys are the keys/key combinations that access features specific to
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// a web browser, including but not limited to:
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// - Ctrl-F and F3 for Find on Page
/// - Ctrl-P for Print
/// - Ctrl-R and F5 for Reload
/// - Ctrl-Plus and Ctrl-Minus for zooming
/// - Ctrl-Shift-C and F12 for DevTools
/// - Special keys for browser functions, such as Back, Forward, and Search
///
/// These APIs allow developers to enable/disable the browser from handling a specific browser
/// accelerator key. These APIs do not disable accelerator keys related to movement and text
/// editing, such as:
/// - Home, End, Page Up, and Page Down
/// - Ctrl-X, Ctrl-C, Ctrl-V
/// - Ctrl-A for Select All
/// - Ctrl-Z for Undo
///
/// The exsiting `AreBrowserAcceleratorKeysEnabled` API is a convenience setting for developers
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// to disable all the browser accelerator keys together. This setting sets the default value
/// for the `AllowBrowserAcceleratorHandling` property.
/// By default, `AreBrowserAcceleratorKeysEnabled` is `TRUE` and `AllowBrowserAcceleratorHandling`
/// is `TRUE`.
/// When developers change `AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, this will
/// change default value for `AllowBrowserAcceleratorHandling` to `FALSE`.
/// If developers want specific keys to be handled by the browser after changing the
/// `AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, they need to enable these keys by
/// setting `AllowBrowserAcceleratorHandling` to `TRUE`.
/// This API will give the event arg higher priority over the `AreBrowserAcceleratorKeysEnabled`
/// setting when we handle the keys.
///
/// For browser accelerator keys, when an accelerator key is pressed, the propagation and
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// processing order is:
/// - An AcceleratorKeyPressed event is generated
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// - Browser level handling
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// - Web Content Handling: If the key combination isn't reserved for browser actions,
/// the key event propagates to the web content, where JavaScript event listeners can
/// capture and respond to it.
///
/// Currently, `ICoreWebView2AcceleratorKeyPressedEventArgs` has a `Handled` property,
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// that developers can use to marked a key as handled. When the key is marked as handled
/// anywhere along the path, the propagtion stops, and web content will not receive the key.
/// With `AllowBrowserAcceleratorHandling` property, when developers mark
/// `AllowBrowserAcceleratorHandling` as `FALSE`, the browser will skip the browser level
/// handling process, but the propagation continue, web content will receive the key
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
/// combination.

/// \snippet ScenarioAcceleratorKeyPressed.cpp
/// Gets the `AllowBrowserAcceleratorHandling` property.
[propget] HRESULT AllowBrowserAcceleratorHandling([out, retval] BOOL* value);

/// Sets the `AllowBrowserAcceleratorHandling` property.
[propput] HRESULT AllowBrowserAcceleratorHandling([in] BOOL value);
}
```

## C#
```c#
namespace Microsoft.Web.WebView2.Core
{
runtimeclass CoreWebView2AcceleratorKeyPressedEventArgs
{
Boolean AllowBrowserAcceleratorHandling { get; set; };
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
tofuandeve marked this conversation as resolved.
Show resolved Hide resolved
}

}
```