ExtendedAcceleratorKeyPressed.md

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.

Examples

C++

    EventRegistrationToken m_acceleratorKeyPressedToken = {};

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

  {
        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.
                        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) 
                            {
                                if (key == VK_F7)
                                {
                                    // Allow the browser to process F7 key
                                    CHECK_FAILURE(args2->put_AllowBrowserAcceleratorHandling(TRUE));
                                }
                            }
                        }
                        return S_OK;
                    })
                    .Get(),
                &m_acceleratorKeyPressedToken));

        }
    }

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. 
    // 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 
  /// 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.
  [propget] HRESULT AllowBrowserAcceleratorHandling([out, retval] BOOL* value);

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

C#

namespace Microsoft.Web.WebView2.Core
{
    runtimeclass CoreWebView2AcceleratorKeyPressedEventArgs
    {
        Boolean AllowBrowserAcceleratorHandling { get; set; };
    }

}