refactor based on feedback

Author: feich-ms

specs/APIReview_AllowExternalDrop.md

@@ -1,63 +1,83 @@
 # Background
-Currently the functionality of dragging and dropping external objects(e.g. files, hyperlinks) into webview2 is default enabled in webview2 and there is no way to disable it. Some developers may want to disbale this functionality in their applications based upon their scenarios. According to such feature requirements, we add the new API to provide developers with the capability to configure the external drag&drop functionality.
+Currently dragging and dropping external objects (e.g. files, hyperlinks) into webview2 is by default enabled and there is no way to disable it. Some developers may want to disable this functionality in their applications. To allow for this, we add a new API to provide developers with the capability to disable the external drag & drop functionality.
 
 # Description
 We add a new `AllowExternalDrop` property in `CoreWebView2Controller`. 
-This API allows end developers to toggle the external drag&drop functionality easily.
-If it's disabled, drag&drop objects from outside into current webview2 will be forbidden.
+This API allows end developers to toggle the external drag & drop functionality easily.
+If it's disabled, dragging objects from outside the bounds of the WebView and dropping into the WebView will be disallowed.
 To be more specific, some behaviors listed below will be impacted by the toggle of this property.
 
 * Drag&Drop files on disk to webview2  
 * Drag&Drop hyperlinks from browser to webview2
 * Drag&Drop hyperlinks from one webview2 to another webview2
 
-Some behaviors are not impacted by the toggle of this property like drag&drop selected text to webview2. That means toggle of this property has no impact on the expected behavior of this action.
+Some behaviors are not impacted by the toggle of this property like dragging and dropping selected text to webview2. That means toggle of this property has no impact on the expected behavior of this action.
 
 By default, AllowExternalDrop is enabled to keep consistent with the behavior we had before the API is added.
 
-Please note that drag&drop anything from webview2 to external(outside current webview2) will not be impacted by this property.
+Please note that drag and drop anything from webview2 to external(outside the bounds of the WebView) will not be impacted by this property.
 
 # Examples
 ## C++
 
 ```cpp
-wil::com_ptr<ICoreWebView2Controller4> m_controller4;
-void ToggleAllowDrop()
+// This hypothetical app allows dropping external content
+// only on the AttachReceipts page.
+wil::com_ptr<ICoreWebView2Controller> m_controller;
+BOOL m_allowExternalDropOnNavigationCompleted;
+HRESULT OnNavigationStarting(ICoreWebView2* sender, ICoreWebView2NavigationStartingEventArgs* args)
 {
-    if (m_controller4)
+    // Disable external drop while navigating.
+    auto controller4 = m_controller.try_query<ICoreWebView2Controller4>();
+    if (controller4)
     {
-        BOOL allowDrop;
-        CHECK_FAILURE(m_controller4->get_AllowDrop(&allowDrop));
-        if (allowDrop)
-        {
-            CHECK_FAILURE(m_controller4->put_AllowDrop(FALSE));
-        }
-        else
-        {
-            CHECK_FAILURE(m_controller4->put_AllowDrop(TRUE));
-        }
+        CHECK_FAILURE(controller4->put_AllowExternalDrop(FALSE));
+    }
+
+    // Decide whether to enable external drop when we finish navigating.
+    // Enable it only when AttachReceipts page is navigated.
+    wil::unique_cotaskmem_string uri;
+    CHECK_FAILURE(args->get_Uri(&uri));
+    m_allowExternalDropOnNavigationCompleted =  uri_equal(uri.get(), L"myapp://AttachReceipts.html");
+}
+
+HRESULT OnNavigationCompleted(ICoreWebView2* sender, ICoreWebView2NavigationCompletedEventArgs* args)
+{
+    auto controller4 = m_controller.try_query<ICoreWebView2Controller4>();
+    if (controller4)
+    {
+        CHECK_FAILURE(controller4->put_AllowExternalDrop(m_allowExternalDropOnNavigationCompleted));
     }
 }
 ```
 
 ## C#
 ```c#
-private CoreWebView2Controller controller
-void ToggleAllowDrop(object target, ExecutedRoutedEventArgs e)
+// This hypothetical app allows dropping external content
+// only on the AttachReceipts page.
+private CoreWebView2Controller controller;
+private bool allowExternalDropOnNavigationCompleted;
+void OnNavigationStarting(object sender, CoreWebView2NavigationStartingEventArgs args)
 {
-    if (controller)
+    // Disable external drop while navigating.
+    if (controller != null)
     {
-        controller.AllowDrop = !controller.AllowDrop;
+        controller.AllowExternalDrop = false;
     }
+
+    // Decide whether to enable external drop when we finish navigating.
+    // Enable it only when AttachReceipts page is navigated.
+    string uri = args.Uri;
+    allowExternalDropOnNavigationCompleted = uri.Equals("myapp://AttachReceipts.html");
+}
+
+void OnNavigationCompleted(object sender, CoreWebView2NavigationCompletedEventArgs args)
+{
+    controller.AllowExternalDrop = allowExternalDropOnNavigationCompleted;
 }
 ```
 
 # Remarks
-The `AllowDrop` property already exists in some controls of .net UI framework like WPF and WinForms. 
-The .net control wrapper for webview2 natively inherits this property. 
-But actually it doesn't really take effect until this new API is added.
-When the new API is promoted to public, we will adjust the WPF/WinForms webview2 control to consume the new API accordingly.
-
 
 # API Notes
 See [API Details](#api-details) section below for API reference.
@@ -66,18 +86,18 @@ See [API Details](#api-details) section below for API reference.
 
 ## Win32 C++
 ```c#
-// This is the ICoreWebView2Controller interface.
+// This is the ICoreWebView2Controller4 interface.
 [uuid(320613e2-990f-4272-bf90-d243a4ff1b8a), object, pointer_default(unique)]
 interface ICoreWebView2Controller4 : ICoreWebView2Controller3 {
-  /// Gets the `AllowDrop` property which is used to configure the capability
-  /// that dropping files into webview2 is allowed or permitted.
-  /// The default value is TRUE.
-  ///
-  /// \snippet SettingsComponent.cpp ToggleAllowDrop
-  [propget] HRESULT AllowDrop([out, retval] BOOL* value);
-  /// Sets the `AllowDrop` property which is used to configure the capability
-  /// that dropping files into webview2 is allowed or permitted.
-  [propput] HRESULT AllowDrop([in] BOOL value);
+  /// Gets the `AllowExternalDrop` property which is used to configure the
+  /// capability that dragging objects from outside the bounds of webview2 and
+  /// dropping into webview2 is allowed or disallowed. The default value is
+  /// TRUE.
+  [propget] HRESULT AllowExternalDrop([ out, retval ] BOOL * value);
+  /// Sets the `AllowExternalDrop` property which is used to configure the
+  /// capability that dragging objects from outside the bounds of webview2 and
+  /// dropping into webview2 is allowed or disallowed.
+  [propput] HRESULT AllowExternalDrop([in] BOOL value);
 }
 ```
 
@@ -89,12 +109,13 @@ namespace Microsoft.Web.WebView2.Core
     {
         //
         // Summary:
-        //     Gets or sets the WebView allow drop property.
+        //     Gets or sets the WebView AllowExternalDrop property.
         //
         // Remarks:
-        //     The AllowDrop is to configure the capability that dropping files into webview2
-        //     is allowed or permitted. The default value is true.
-        public bool AllowDrop { get; set; }
+        //     The AllowExternalDrop is to configure the capability that dragging objects from
+        //     outside the bounds of webview2 and dropping into webview2 is allowed or disallowed.
+        //     The default value is true.
+        public bool AllowExternalDrop { get; set; }
     }
 }
 ```