JS port: let Display.execute navigate the current page instead of prompting

CodenameOne/src/com/codename1/ui/CN.java

@@ -664,6 +664,11 @@ public static Boolean canExecute(String url) {
     /// }
     /// ```
     ///
+    /// On the JavaScript port this can open a new tab, navigate the current page
+    /// or show a confirmation `Sheet`, depending on the
+    /// `javascript.execute.target` property. See [Display#execute(String)] for
+    /// the details.
+    ///
     /// #### Parameters
     ///
     /// - `url`: the url to execute

CodenameOne/src/com/codename1/ui/Display.java

@@ -4082,6 +4082,35 @@ public Boolean canExecute(String url) {
     /// `simulator-hooks.properties` format and the positional `itemN` / `labelN`
     /// conventions.
     ///
+    /// #### JavaScript port
+    ///
+    /// Browsers only let a page open a new window/tab from inside a live user
+    /// gesture, and Codename One dispatches events on its own EDT so by the time
+    /// your listener calls this method the browser no longer considers a gesture
+    /// to be in progress. The JavaScript port therefore resolves the
+    /// `javascript.execute.target` property to decide what to do:
+    ///
+    /// - `auto` (the default) opens a new tab when the page still has user
+    ///   activation and otherwise navigates the page the app is running in. No
+    ///   confirmation prompt is ever shown, but note that navigating the current
+    ///   page unloads the app.
+    /// - `_blank` only ever opens a new tab. When the browser would block it the
+    ///   port shows a confirmation `Sheet` whose OK button supplies the missing
+    ///   gesture. This was the behavior before the property existed.
+    /// - `_self` always navigates the page the app is running in.
+    ///
+    /// Set it before the call, for example in your `init` method:
+    ///
+    /// ```java
+    /// Display.getInstance().setProperty("javascript.execute.target", "_self");
+    /// ```
+    ///
+    /// The property applies to any URL carrying a URI scheme the browser can
+    /// hand off, custom deep links like the `imdb:///find` example above
+    /// included. It is ignored on every other platform, and on all targets a
+    /// `javascript:` URL, a `data:` URL, a `file:` URL or a path into local
+    /// storage keeps its existing meaning.
+    ///
     /// #### Parameters
     ///
     /// - `url`: the url to execute