From 42cc46666a7b48d402d9787d7eb9a5e02a03e532 Mon Sep 17 00:00:00 2001 From: Eve Le Date: Mon, 2 Oct 2023 15:08:25 -0700 Subject: [PATCH 1/6] Add specs for AcceleratorKeyPressed event args extension --- specs/ExtendedAcceleratorKeyPressed.md | 126 +++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 specs/ExtendedAcceleratorKeyPressed.md diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md new file mode 100644 index 000000000..ee7563a92 --- /dev/null +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -0,0 +1,126 @@ +# Background +WebView2 has `ICoreWebView2AcceleratorKeyPressedEventArgs` for the `AcceleratorKeyPressed` event. We has been asked 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 `AllowBrowserHandle` property. + +# Examples +## C++: Get name of window + +``` cpp + EventRegistrationToken m_acceleratorKeyPressedStagingToken = {}; + + wil::com_ptr m_controller; + wil::com_ptr m_webView; + wil::com_ptr m_settings3; + + { + wil::com_ptr settings; + CHECK_FAILURE(m_webView->get_Settings(&settings)); + m_settings3 = settings.try_query(); + if (m_setting3) { + // Disable all browser accelerator keys + CHECK_FAILURE(m_settings3->put_AreBrowserAcceleratorKeysEnabled(FALSE)); + // Register a handler for the AcceleratorKeyPressed event. + CHECK_FAILURE(m_controller->add_AcceleratorKeyPressed( + Callback( + [this]( + ICoreWebView2Controller* sender, + ICoreWebView2AcceleratorKeyPressedEventArgs* args) -> HRESULT + { + COREWEBVIEW2_KEY_EVENT_KIND kind; + CHECK_FAILURE(args->get_KeyEventKind(&kind)); + // We only care about key down events. + 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 + args2; + + CHECK_FAILURE(args->QueryInterface(IID_PPV_ARGS(&args2))); + if (key == VK_F7) + { + // Allow the browser to process F7 key + CHECK_FAILURE(args2->put_AllowBrowserHandle(TRUE)); + } + } + return S_OK; + }) + .Get(), + &m_acceleratorKeyPressedStagingToken)); + + } + } +``` + +## C#: Get name of window +```c# + CoreWebView2Settings _webViewSettings = webView.CoreWebView2.Settings; + // All browser accelerator keys are disabled with this setting + _webViewSettings.AreBrowserAcceleratorKeysEnabled = false; + + webView.CoreWebView2.AcceleratorKeyPressed += WebView2Controller_AcceleratorKeyPressed; + + void WebView2Controller_AcceleratorKeyPressed(object sender, CoreWebView2AcceleratorKeyPressedEventArgs e) + { + switch (e.KeyEventKind) + { + case CoreWebView2KeyEventKind.KeyDown: + case CoreWebView2KeyEventKind.SystemKeyDown: + { + Keys keyData = (Keys)(e.VirtualKey); + // Allow the browser to process F7 key + if(e.VirtualKey == Key.F7) { + e.AllowBrowserHandle = true; + } + break; + } + + } + } + +``` + +# Remarks +By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and default value for `AllowBrowserHandle` is `TRUE`. When developers set `AreBrowserAcceleratorKeyEnabled` to `FALSE` this will also change the default value for `AllowBrowserHandle` to `FALSE`. If developers want specific keys to be handled by the browser after changing the `AreBrowserAcceleratorKeyEnabled` settings to `FALSE`, they need to enable them by setting `event_args->put_ AllowBrowserHandle(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 This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. +[uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)] +interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs { + /// These APIs allow devs to enable/disable the browser from handling specific accelerator keys. + /// By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and `AllowBrowserHandle` is `TRUE`. + /// When devs set `AreBrowserAcceleratorKeyEnabled` to `FALSE` this will override and the + /// default value for `AllowBrowserHandle` will be `FALSE` and prevent the browser to handle + /// accelerator keys. If users want specific keys to be handled by the browser after changing + /// the settings to `FALSE`, they need to enable them by setting `AllowBrowserHandle` to `TRUE`. + /// This option will give the event arg higher priority over the `AreBrowserAcceleratorKeyEnabled` + /// settings when we handle the keys. + /// + /// \snippet ScenarioAcceleratorKeyPressed.cpp + /// Gets the `AllowBrowserHandle` property. + [propget] HRESULT AllowBrowserHandle([out, retval] BOOL* allowed); + + /// Sets the `AllowBrowserHandle` property. + [propput] HRESULT AllowBrowserHandle([in] BOOL allowed); +} +``` + +## C# +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2AcceleratorKeyPressedEventArgs + { + Boolean AllowBrowserHandle { get; set; }; + } + +} +``` From 25162ea565f43bdaeeb2647cabcc2bdbee8609ad Mon Sep 17 00:00:00 2001 From: Eve Le Date: Thu, 5 Oct 2023 23:07:26 -0700 Subject: [PATCH 2/6] Address comments --- specs/ExtendedAcceleratorKeyPressed.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md index ee7563a92..024540fc9 100644 --- a/specs/ExtendedAcceleratorKeyPressed.md +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -1,5 +1,5 @@ # Background -WebView2 has `ICoreWebView2AcceleratorKeyPressedEventArgs` for the `AcceleratorKeyPressed` event. We has been asked extend this API so that developers can indicate that they would like an existing browser accelerator key to be disabled as a browser accelerator. +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. @@ -7,10 +7,10 @@ In this document we describe the updated API. We'd appreciate your feedback. We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow developers to enable/disable the browser from handling accelerator keys with `AllowBrowserHandle` property. # Examples -## C++: Get name of window +## C++ ``` cpp - EventRegistrationToken m_acceleratorKeyPressedStagingToken = {}; + EventRegistrationToken m_acceleratorKeyPressedToken = {}; wil::com_ptr m_controller; wil::com_ptr m_webView; @@ -20,7 +20,8 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow wil::com_ptr settings; CHECK_FAILURE(m_webView->get_Settings(&settings)); m_settings3 = settings.try_query(); - if (m_setting3) { + if (m_setting3) + { // Disable all browser accelerator keys CHECK_FAILURE(m_settings3->put_AreBrowserAcceleratorKeysEnabled(FALSE)); // Register a handler for the AcceleratorKeyPressed event. @@ -52,13 +53,13 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow return S_OK; }) .Get(), - &m_acceleratorKeyPressedStagingToken)); + &m_acceleratorKeyPressedToken)); } } ``` -## C#: Get name of window +## C# ```c# CoreWebView2Settings _webViewSettings = webView.CoreWebView2.Settings; // All browser accelerator keys are disabled with this setting @@ -75,7 +76,8 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow { Keys keyData = (Keys)(e.VirtualKey); // Allow the browser to process F7 key - if(e.VirtualKey == Key.F7) { + if (e.VirtualKey == Key.F7) + { e.AllowBrowserHandle = true; } break; @@ -92,7 +94,7 @@ By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and default value for `A # API Details ## C++ ``` -/// This is This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. +/// This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. [uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)] interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs { /// These APIs allow devs to enable/disable the browser from handling specific accelerator keys. @@ -106,10 +108,10 @@ interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2Accelerato /// /// \snippet ScenarioAcceleratorKeyPressed.cpp /// Gets the `AllowBrowserHandle` property. - [propget] HRESULT AllowBrowserHandle([out, retval] BOOL* allowed); + [propget] HRESULT AllowBrowserHandle([out, retval] BOOL* value); /// Sets the `AllowBrowserHandle` property. - [propput] HRESULT AllowBrowserHandle([in] BOOL allowed); + [propput] HRESULT AllowBrowserHandle([in] BOOL value); } ``` From d9641d24a4ebb7a189263259f701cfe71b9a5330 Mon Sep 17 00:00:00 2001 From: Eve Le Date: Thu, 26 Oct 2023 15:40:48 -0700 Subject: [PATCH 3/6] address comments --- specs/ExtendedAcceleratorKeyPressed.md | 104 +++++++++++++++++++------ 1 file changed, 79 insertions(+), 25 deletions(-) diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md index 024540fc9..8101b2529 100644 --- a/specs/ExtendedAcceleratorKeyPressed.md +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -1,10 +1,14 @@ # 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. +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 `AllowBrowserHandle` property. +We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow developers +to enable/disable the browser from handling accelerator keys with `AllowBrowserAcceleratorHandling` +property. # Examples ## C++ @@ -22,7 +26,10 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow m_settings3 = settings.try_query(); if (m_setting3) { - // Disable all browser accelerator keys + // 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( @@ -43,11 +50,14 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow wil::com_ptr args2; - CHECK_FAILURE(args->QueryInterface(IID_PPV_ARGS(&args2))); - if (key == VK_F7) + args->QueryInterface(IID_PPV_ARGS(&args2)); + if (args) { - // Allow the browser to process F7 key - CHECK_FAILURE(args2->put_AllowBrowserHandle(TRUE)); + if (key == VK_F7) + { + // Allow the browser to process F7 key + CHECK_FAILURE(args2->put_AllowBrowserAcceleratorHandling(TRUE)); + } } } return S_OK; @@ -62,7 +72,10 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow ## C# ```c# CoreWebView2Settings _webViewSettings = webView.CoreWebView2.Settings; - // All browser accelerator keys are disabled with this setting + // 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. + // Changing this setting to `false` will change the default setting for + // AllowBrowserAcceleratorHandling to `false` _webViewSettings.AreBrowserAcceleratorKeysEnabled = false; webView.CoreWebView2.AcceleratorKeyPressed += WebView2Controller_AcceleratorKeyPressed; @@ -74,11 +87,10 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow case CoreWebView2KeyEventKind.KeyDown: case CoreWebView2KeyEventKind.SystemKeyDown: { - Keys keyData = (Keys)(e.VirtualKey); // Allow the browser to process F7 key if (e.VirtualKey == Key.F7) { - e.AllowBrowserHandle = true; + e.AllowBrowserAcceleratorHandling = true; } break; } @@ -89,7 +101,12 @@ We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` to allow ``` # Remarks -By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and default value for `AllowBrowserHandle` is `TRUE`. When developers set `AreBrowserAcceleratorKeyEnabled` to `FALSE` this will also change the default value for `AllowBrowserHandle` to `FALSE`. If developers want specific keys to be handled by the browser after changing the `AreBrowserAcceleratorKeyEnabled` settings to `FALSE`, they need to enable them by setting `event_args->put_ AllowBrowserHandle(TRUE)`. This option will give the event arg higher priority over the settings when the browser decide whether to handle the keys. +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++ @@ -97,21 +114,58 @@ By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and default value for `A /// This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. [uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)] interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs { - /// These APIs allow devs to enable/disable the browser from handling specific accelerator keys. - /// By default, `AreBrowserAcceleratorKeyEnabled` is `TRUE` and `AllowBrowserHandle` is `TRUE`. - /// When devs set `AreBrowserAcceleratorKeyEnabled` to `FALSE` this will override and the - /// default value for `AllowBrowserHandle` will be `FALSE` and prevent the browser to handle - /// accelerator keys. If users want specific keys to be handled by the browser after changing - /// the settings to `FALSE`, they need to enable them by setting `AllowBrowserHandle` to `TRUE`. - /// This option will give the event arg higher priority over the `AreBrowserAcceleratorKeyEnabled` - /// settings when we handle the keys. - /// +/// Browser accelerator keys are the keys/key combinations that access features specific to +/// a web browser, including but not limited to: +/// - 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 +/// 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 +/// processing order is: +/// - An AcceleratorKeyPressed event is generated +/// - Browser level handling +/// - 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, +/// 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 +/// combination. + /// \snippet ScenarioAcceleratorKeyPressed.cpp - /// Gets the `AllowBrowserHandle` property. - [propget] HRESULT AllowBrowserHandle([out, retval] BOOL* value); + /// Gets the `AllowBrowserAcceleratorHandling` property. + [propget] HRESULT AllowBrowserAcceleratorHandling([out, retval] BOOL* value); - /// Sets the `AllowBrowserHandle` property. - [propput] HRESULT AllowBrowserHandle([in] BOOL value); + /// Sets the `AllowBrowserAcceleratorHandling` property. + [propput] HRESULT AllowBrowserAcceleratorHandling([in] BOOL value); } ``` @@ -121,7 +175,7 @@ namespace Microsoft.Web.WebView2.Core { runtimeclass CoreWebView2AcceleratorKeyPressedEventArgs { - Boolean AllowBrowserHandle { get; set; }; + Boolean AllowBrowserAcceleratorHandling { get; set; }; } } From 7c2596b4dff3728596e70aee86f0b550979c42eb Mon Sep 17 00:00:00 2001 From: Eve Le Date: Thu, 26 Oct 2023 15:59:37 -0700 Subject: [PATCH 4/6] indentation --- specs/ExtendedAcceleratorKeyPressed.md | 90 +++++++++++++------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md index 8101b2529..14c72998c 100644 --- a/specs/ExtendedAcceleratorKeyPressed.md +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -114,51 +114,51 @@ priority over the settings when the browser decide whether to handle the keys. /// 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 -/// a web browser, including but not limited to: -/// - 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 -/// 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 -/// processing order is: -/// - An AcceleratorKeyPressed event is generated -/// - Browser level handling -/// - 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, -/// 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 -/// combination. + /// Browser accelerator keys are the keys/key combinations that access features specific to + /// a web browser, including but not limited to: + /// - 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 + /// 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 + /// processing order is: + /// - An AcceleratorKeyPressed event is generated + /// - Browser level handling + /// - 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, + /// 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 + /// combination. /// \snippet ScenarioAcceleratorKeyPressed.cpp /// Gets the `AllowBrowserAcceleratorHandling` property. From 76b709af3cf0929cdc5ae089a6a3ac7530061a8f Mon Sep 17 00:00:00 2001 From: Eve Le Date: Mon, 30 Oct 2023 13:51:51 -0700 Subject: [PATCH 5/6] Update docs --- specs/ExtendedAcceleratorKeyPressed.md | 69 ++++++++++++++------------ 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md index 14c72998c..8c1e494d0 100644 --- a/specs/ExtendedAcceleratorKeyPressed.md +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -1,7 +1,8 @@ # 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. +WebView2 has `ICoreWebView2AcceleratorKeyPressedEventArgs` for the +`CoreWebView2Controller.AcceleratorKeyPressed` event. We have been asked to extend this API so +that developers can indicate that theywould 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. @@ -31,7 +32,7 @@ property. // 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. + // Register a handler for the CoreWebView2Controller.AcceleratorKeyPressed event. CHECK_FAILURE(m_controller->add_AcceleratorKeyPressed( Callback( [this]( @@ -101,12 +102,14 @@ property. ``` # 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. +By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and default value for +`AllowBrowserAcceleratorHandling` is `TRUE`. When developers set +`CoreWebView2Settings.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 `CoreWebView2Settings.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++ @@ -114,6 +117,9 @@ priority over the settings when the browser decide whether to handle the keys. /// This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. [uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)] interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs { + /// This property allows developers to enable or disable the browser from handling a specific + /// browser accelerator key such as Ctrl+P or F3, etc. + /// /// Browser accelerator keys are the keys/key combinations that access features specific to /// a web browser, including but not limited to: /// - Ctrl-F and F3 for Find on Page @@ -123,42 +129,41 @@ interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2Accelerato /// - 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: + /// This property does 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 - /// 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`. + /// The exsiting `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` API is a convenience setting + /// for developers to disable all the browser accelerator keys together. This setting sets the default + /// value for the `AllowBrowserAcceleratorHandling` property. + /// By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and + /// `AllowBrowserAcceleratorHandling` is `TRUE`. + /// When developers change `CoreWebView2Settings.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. + /// `CoreWebView2Settings.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 + /// `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting when we handle the keys. /// /// For browser accelerator keys, when an accelerator key is pressed, the propagation and /// processing order is: - /// - An AcceleratorKeyPressed event is generated - /// - Browser level handling + /// - A CoreWebView2Controller.AcceleratorKeyPressed event is raised + /// - WebView2 browser feature accelerator key handling /// - 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, - /// 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. + /// `ICoreWebView2AcceleratorKeyPressedEventArgs` has a `Handled` property, that developers + /// can use to marked a key as handled. When the key is marked as handled anywhere along + /// the path, the event 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 - /// combination. + /// `AllowBrowserAcceleratorHandling` as `FALSE`, the browser will skip the WebView2 + /// browser feature accelerator key handling process, but the event propagation + /// continues, and web content will receive the key combination. /// \snippet ScenarioAcceleratorKeyPressed.cpp /// Gets the `AllowBrowserAcceleratorHandling` property. From 740212401ec1416ed9f1d61231555fd50ca3b59f Mon Sep 17 00:00:00 2001 From: Eve Le Date: Thu, 2 Nov 2023 14:28:04 -0700 Subject: [PATCH 6/6] Addess comments about specs --- specs/ExtendedAcceleratorKeyPressed.md | 135 +++++++++++++++---------- 1 file changed, 83 insertions(+), 52 deletions(-) diff --git a/specs/ExtendedAcceleratorKeyPressed.md b/specs/ExtendedAcceleratorKeyPressed.md index 8c1e494d0..9a40bffea 100644 --- a/specs/ExtendedAcceleratorKeyPressed.md +++ b/specs/ExtendedAcceleratorKeyPressed.md @@ -1,15 +1,15 @@ # Background WebView2 has `ICoreWebView2AcceleratorKeyPressedEventArgs` for the `CoreWebView2Controller.AcceleratorKeyPressed` event. We have been asked to extend this API so -that developers can indicate that theywould like an existing browser accelerator key to be -disabled as a browser accelerator. +that developers can indicate that they would like the browser to handle or skip a specific +browser accelerator key. 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. +We propose extending the `ICoreWebView2AcceleratorKeyPressedEventArgs` with a new +`IsBrowserAcceleratorKeyEnabled` property to allow developers to control whether the browser +handles accelerator keys such as Ctrl+P or F3, etc. # Examples ## C++ @@ -21,16 +21,17 @@ property. wil::com_ptr m_webView; wil::com_ptr m_settings3; - { + void MyWebView::InitializeAcceleratorHandling() + { wil::com_ptr settings; CHECK_FAILURE(m_webView->get_Settings(&settings)); m_settings3 = settings.try_query(); if (m_setting3) { // Disable all browser accelerator keys. The default value for the - // `AllowBrowserAcceleratorHandling` property is set to the current value of this + // `IsBrowserAcceleratorKeyEnabled` property is set to the current value of this // setting. Changing this setting to `false` will change the default setting for - // AllowBrowserAcceleratorHandling to `false`. + // IsBrowserAcceleratorKeyEnabled to `false`. CHECK_FAILURE(m_settings3->put_AreBrowserAcceleratorKeysEnabled(FALSE)); // Register a handler for the CoreWebView2Controller.AcceleratorKeyPressed event. CHECK_FAILURE(m_controller->add_AcceleratorKeyPressed( @@ -52,12 +53,12 @@ property. args2; args->QueryInterface(IID_PPV_ARGS(&args2)); - if (args) + if (args2) { if (key == VK_F7) { // Allow the browser to process F7 key - CHECK_FAILURE(args2->put_AllowBrowserAcceleratorHandling(TRUE)); + CHECK_FAILURE(args2->put_IsBrowserAcceleratorKeyEnabled(TRUE)); } } } @@ -74,9 +75,9 @@ property. ```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. + // `IsBrowserAcceleratorKeyEnabled` property is set to the current value of this setting. // Changing this setting to `false` will change the default setting for - // AllowBrowserAcceleratorHandling to `false` + // IsBrowserAcceleratorKeyEnabled to `false` _webViewSettings.AreBrowserAcceleratorKeysEnabled = false; webView.CoreWebView2.AcceleratorKeyPressed += WebView2Controller_AcceleratorKeyPressed; @@ -91,7 +92,7 @@ property. // Allow the browser to process F7 key if (e.VirtualKey == Key.F7) { - e.AllowBrowserAcceleratorHandling = true; + e.IsBrowserAcceleratorKeyEnabled = true; } break; } @@ -102,14 +103,44 @@ property. ``` # Remarks -By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and default value for -`AllowBrowserAcceleratorHandling` is `TRUE`. When developers set -`CoreWebView2Settings.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 `CoreWebView2Settings.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. +The `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` API is a convenient setting +for developers to disable all the browser accelerator keys together. This setting also sets the +default value for the `IsBrowserAcceleratorKeyEnabled` property. +By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and +`IsBrowserAcceleratorKeyEnabled` is `TRUE`. +When developers change `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, +this will change default value for `IsBrowserAcceleratorKeyEnabled` to `FALSE`. +If developers want specific keys to be handled by the browser after changing the +`CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, they need to enable +these keys by setting `IsBrowserAcceleratorKeyEnabled` to `TRUE`. +This API will give the event arg higher priority over the +`CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting when we handle the keys. + +The `CoreWebView2Controller.AcceleratorKeyPressed` event is raised any time an accelerator key +is pressed, regardless of whether accelerator keys are enabled or not. + +For browser accelerator keys, when an accelerator key is pressed, the propagation and +processing order is: +1. A CoreWebView2Controller.AcceleratorKeyPressed event is raised +1. WebView2 browser feature accelerator key handling +1. 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. + +`ICoreWebView2AcceleratorKeyPressedEventArgs` has a `Handled` property, that developers +can use to mark a key as handled. When the key is marked as handled anywhere along +the path, the event propagation stops, and web content will not receive the key. + +With `IsBrowserAcceleratorKeyEnabled` property, if developers mark +`IsBrowserAcceleratorKeyEnabled` as `FALSE`, the browser will skip the WebView2 +browser feature accelerator key handling process, but the event propagation +continues, and web content will receive the key combination. +This property does 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 # API Details ## C++ @@ -117,10 +148,10 @@ to handle the keys. /// This is a continuation of the ICoreWebView2AcceleratorKeyPressedEventArgs interface. [uuid(45238725-3774-4cfe-931f-7985a1b5866f), object, pointer_default(unique)] interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2AcceleratorKeyPressedEventArgs { - /// This property allows developers to enable or disable the browser from handling a specific + /// This property allows developers to enable or disable the browser from handling a specific /// browser accelerator key such as Ctrl+P or F3, etc. /// - /// Browser accelerator keys are the keys/key combinations that access features specific to + /// Browser accelerator keys are the keys/key combinations that access features specific to /// a web browser, including but not limited to: /// - Ctrl-F and F3 for Find on Page /// - Ctrl-P for Print @@ -136,41 +167,41 @@ interface ICoreWebView2AcceleratorKeyPressedEventArgs2 : ICoreWebView2Accelerato /// - Ctrl-A for Select All /// - Ctrl-Z for Undo /// - /// The exsiting `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` API is a convenience setting - /// for developers to disable all the browser accelerator keys together. This setting sets the default - /// value for the `AllowBrowserAcceleratorHandling` property. - /// By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and - /// `AllowBrowserAcceleratorHandling` is `TRUE`. - /// When developers change `CoreWebView2Settings.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 - /// `CoreWebView2Settings.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 + /// The `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` API is a convenient setting + /// for developers to disable all the browser accelerator keys together, and sets the default + /// value for the `IsBrowserAcceleratorKeyEnabled` property. + /// By default, `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` is `TRUE` and + /// `IsBrowserAcceleratorKeyEnabled` is `TRUE`. + /// When developers change `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, + /// this will change default value for `IsBrowserAcceleratorKeyEnabled` to `FALSE`. + /// If developers want specific keys to be handled by the browser after changing the + /// `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting to `FALSE`, they need to enable + /// these keys by setting `IsBrowserAcceleratorKeyEnabled` to `TRUE`. + /// This API will give the event arg higher priority over the /// `CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled` setting when we handle the keys. /// - /// For browser accelerator keys, when an accelerator key is pressed, the propagation and - /// processing order is: - /// - A CoreWebView2Controller.AcceleratorKeyPressed event is raised - /// - WebView2 browser feature accelerator key handling - /// - 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 + /// For browser accelerator keys, when an accelerator key is pressed, the propagation and + /// processing order is: + /// 1. A CoreWebView2Controller.AcceleratorKeyPressed event is raised + /// 2. WebView2 browser feature accelerator key handling + /// 3. 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. - /// + /// /// `ICoreWebView2AcceleratorKeyPressedEventArgs` has a `Handled` property, that developers - /// can use to marked a key as handled. When the key is marked as handled anywhere along - /// the path, the event propagtion stops, and web content will not receive the key. - /// With `AllowBrowserAcceleratorHandling` property, when developers mark - /// `AllowBrowserAcceleratorHandling` as `FALSE`, the browser will skip the WebView2 - /// browser feature accelerator key handling process, but the event propagation - /// continues, and web content will receive the key combination. + /// can use to mark a key as handled. When the key is marked as handled anywhere along + /// the path, the event propagation stops, and web content will not receive the key. + /// With `IsBrowserAcceleratorKeyEnabled` property, if developers mark + /// `IsBrowserAcceleratorKeyEnabled` as `FALSE`, the browser will skip the WebView2 + /// browser feature accelerator key handling process, but the event propagation + /// continues, and web content will receive the key combination. /// \snippet ScenarioAcceleratorKeyPressed.cpp - /// Gets the `AllowBrowserAcceleratorHandling` property. - [propget] HRESULT AllowBrowserAcceleratorHandling([out, retval] BOOL* value); + /// Gets the `IsBrowserAcceleratorKeyEnabled` property. + [propget] HRESULT IsBrowserAcceleratorKeyEnabled([out, retval] BOOL* value); - /// Sets the `AllowBrowserAcceleratorHandling` property. - [propput] HRESULT AllowBrowserAcceleratorHandling([in] BOOL value); + /// Sets the `IsBrowserAcceleratorKeyEnabled` property. + [propput] HRESULT IsBrowserAcceleratorKeyEnabled([in] BOOL value); } ``` @@ -180,7 +211,7 @@ namespace Microsoft.Web.WebView2.Core { runtimeclass CoreWebView2AcceleratorKeyPressedEventArgs { - Boolean AllowBrowserAcceleratorHandling { get; set; }; + Boolean IsBrowserAcceleratorKeyEnabled { get; set; }; } }