Merge pull request #10518 from yonzmeer/configurable-blur-active-element

Configurable blur active element

CHANGES.md

@@ -5,6 +5,7 @@
 ##### Additions :tada:
 
 - Models and tilesets that use the `CESIUM_primitive_outline` extension can now toggle outlines at runtime with the `showOutline` property. Furthermore, the color of the outlines can now be controlled by the `outlineColor` property. [#10506](https://github.com/CesiumGS/cesium/pull/10506)
+- Added optional `blurActiveElementOnCanvasFocus` option to set the behavior of blurring the active element when interacting with the canvas. [#10518](https://github.com/CesiumGS/cesium/pull/10518)
 
 ##### Fixes :wrench:
 

CONTRIBUTORS.md

@@ -328,3 +328,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
 - [Yuri Chen](https://github.com/yurichen17)
 - [David Ferguson](https://github.com/jdfwarrior)
 - [Karthik Vaithin](https://github.com/kvaithin)
+- [Jonathan Meerson](https://github.com/yonzmeer)

Source/Widgets/CesiumWidget/CesiumWidget.js

@@ -144,6 +144,7 @@ function configureCameraFrustum(widget) {
  * @param {Boolean} [options.shadows=false] Determines if shadows are cast by light sources.
  * @param {ShadowMode} [options.terrainShadows=ShadowMode.RECEIVE_ONLY] Determines if the terrain casts or receives shadows from light sources.
  * @param {MapMode2D} [options.mapMode2D=MapMode2D.INFINITE_SCROLL] Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
+ * @param {Boolean} [options.blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the viewer's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
  * @param {Boolean} [options.requestRenderMode=false] If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using {@link Scene#requestRender} to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {Number} [options.maximumRenderTimeChange=0.0] If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {Number} [options.msaaSamples=1] If provided, this value controls the rate of multisample antialiasing. Typical multisampling rates are 2, 4, and sometimes 8 samples per pixel. Higher sampling rates of MSAA may impact performance in exchange for improved visual quality. This value only applies to WebGL2 contexts that support multisample render targets.
@@ -212,13 +213,25 @@ function CesiumWidget(container, options) {
   // This leads to unexpected interaction if the last element was an input field.
   // For example, clicking the mouse wheel could lead to the value in  the field changing
   // unexpectedly. The solution is to blur whatever has focus as soon as canvas interaction begins.
+  // Although in some cases the active element needs to stay active even after interacting with the canvas,
+  // for example when clicking on it only for getting the data of a clicked position or an entity.
+  // For this case, the `blurActiveElementOnCanvasFocus` can be passed with false to avoid blurring
+  // the active element after interacting with the canvas.
   function blurActiveElement() {
     if (canvas !== canvas.ownerDocument.activeElement) {
       canvas.ownerDocument.activeElement.blur();
     }
   }
-  canvas.addEventListener("mousedown", blurActiveElement);
-  canvas.addEventListener("pointerdown", blurActiveElement);
+
+  const blurActiveElementOnCanvasFocus = defaultValue(
+    options.blurActiveElementOnCanvasFocus,
+    true
+  );
+
+  if (blurActiveElementOnCanvasFocus) {
+    canvas.addEventListener("mousedown", blurActiveElement);
+    canvas.addEventListener("pointerdown", blurActiveElement);
+  }
 
   element.appendChild(canvas);
 
@@ -546,7 +559,7 @@ Object.defineProperties(CesiumWidget.prototype, {
 
   /**
    * Gets or sets whether or not this widget should control the render loop.
-   * If set to true the widget will use {@link requestAnimationFrame} to
+   * If true the widget will use {@link requestAnimationFrame} to
    * perform rendering and resizing of the widget, as well as drive the
    * simulation clock. If set to false, you must manually call the
    * <code>resize</code>, <code>render</code> methods as part of a custom

Source/Widgets/Viewer/Viewer.js

@@ -334,6 +334,7 @@ function enableVRUI(viewer, enabled) {
  * @property {ShadowMode} [terrainShadows=ShadowMode.RECEIVE_ONLY] Determines if the terrain casts or receives shadows from light sources.
  * @property {MapMode2D} [mapMode2D=MapMode2D.INFINITE_SCROLL] Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
  * @property {Boolean} [projectionPicker=false] If set to true, the ProjectionPicker widget will be created.
+ * @property {Boolean} [blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the viewer's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
  * @property {Boolean} [requestRenderMode=false] If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling reduces the CPU/GPU usage of your application and uses less battery on mobile, but requires using {@link Scene#requestRender} to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @property {Number} [maximumRenderTimeChange=0.0] If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @property {Number} [depthPlaneEllipsoidOffset=0.0] Adjust the DepthPlane to address rendering artefacts below ellipsoid zero elevation.
@@ -500,6 +501,7 @@ Either specify options.terrainProvider instead or set options.baseLayerPicker to
     shadows: options.shadows,
     terrainShadows: options.terrainShadows,
     mapMode2D: options.mapMode2D,
+    blurActiveElementOnCanvasFocus: options.blurActiveElementOnCanvasFocus,
     requestRenderMode: options.requestRenderMode,
     maximumRenderTimeChange: options.maximumRenderTimeChange,
     depthPlaneEllipsoidOffset: options.depthPlaneEllipsoidOffset,
@@ -1321,7 +1323,7 @@ Object.defineProperties(Viewer.prototype, {
 
   /**
    * Gets or sets whether or not this widget should control the render loop.
-   * If set to true the widget will use {@link requestAnimationFrame} to
+   * If true the widget will use {@link requestAnimationFrame} to
    * perform rendering and resizing of the widget, as well as drive the
    * simulation clock. If set to false, you must manually call the
    * <code>resize</code>, <code>render</code> methods