blockly 7.20211209.2 → 8.0.0

package/core/options.js

@@ -31,163 +31,318 @@ const {WorkspaceSvg} = goog.requireType('Blockly.WorkspaceSvg');
 /**
  * Parse the user-specified options, using reasonable defaults where behaviour
  * is unspecified.
- * @param {!BlocklyOptions} options Dictionary of options.
- *     Specification:
- * https://developers.google.com/blockly/guides/get-started/web#configuration
- * @constructor
  * @alias Blockly.Options
  */
-const Options = function(options) {
-  let toolboxJsonDef = null;
-  let hasCategories = false;
-  let hasTrashcan = false;
-  let hasCollapse = false;
-  let hasComments = false;
-  let hasDisable = false;
-  let hasSounds = false;
-  const readOnly = !!options['readOnly'];
-  if (!readOnly) {
-    toolboxJsonDef = toolbox.convertToolboxDefToJson(options['toolbox']);
-    hasCategories = toolbox.hasCategories(toolboxJsonDef);
-    hasTrashcan = options['trashcan'];
-    if (hasTrashcan === undefined) {
-      hasTrashcan = hasCategories;
-    }
-    hasCollapse = options['collapse'];
-    if (hasCollapse === undefined) {
-      hasCollapse = hasCategories;
+class Options {
+  /**
+   * @param {!BlocklyOptions} options Dictionary of options.
+   *     Specification:
+   * https://developers.google.com/blockly/guides/get-started/web#configuration
+   */
+  constructor(options) {
+    let toolboxJsonDef = null;
+    let hasCategories = false;
+    let hasTrashcan = false;
+    let hasCollapse = false;
+    let hasComments = false;
+    let hasDisable = false;
+    let hasSounds = false;
+    const readOnly = !!options['readOnly'];
+    if (!readOnly) {
+      toolboxJsonDef = toolbox.convertToolboxDefToJson(options['toolbox']);
+      hasCategories = toolbox.hasCategories(toolboxJsonDef);
+      hasTrashcan = options['trashcan'];
+      if (hasTrashcan === undefined) {
+        hasTrashcan = hasCategories;
+      }
+      hasCollapse = options['collapse'];
+      if (hasCollapse === undefined) {
+        hasCollapse = hasCategories;
+      }
+      hasComments = options['comments'];
+      if (hasComments === undefined) {
+        hasComments = hasCategories;
+      }
+      hasDisable = options['disable'];
+      if (hasDisable === undefined) {
+        hasDisable = hasCategories;
+      }
+      hasSounds = options['sounds'];
+      if (hasSounds === undefined) {
+        hasSounds = true;
+      }
     }
-    hasComments = options['comments'];
-    if (hasComments === undefined) {
-      hasComments = hasCategories;
+
+    let maxTrashcanContents = options['maxTrashcanContents'];
+    if (hasTrashcan) {
+      if (maxTrashcanContents === undefined) {
+        maxTrashcanContents = 32;
+      }
+    } else {
+      maxTrashcanContents = 0;
     }
-    hasDisable = options['disable'];
-    if (hasDisable === undefined) {
-      hasDisable = hasCategories;
+    const rtl = !!options['rtl'];
+    let horizontalLayout = options['horizontalLayout'];
+    if (horizontalLayout === undefined) {
+      horizontalLayout = false;
     }
-    hasSounds = options['sounds'];
-    if (hasSounds === undefined) {
-      hasSounds = true;
+    let toolboxAtStart = options['toolboxPosition'];
+    toolboxAtStart = toolboxAtStart !== 'end';
+
+    /** @type {!toolbox.Position} */
+    let toolboxPosition;
+    if (horizontalLayout) {
+      toolboxPosition =
+          toolboxAtStart ? toolbox.Position.TOP : toolbox.Position.BOTTOM;
+    } else {
+      toolboxPosition = (toolboxAtStart === rtl) ? toolbox.Position.RIGHT :
+                                                   toolbox.Position.LEFT;
     }
-  }
 
-  let maxTrashcanContents = options['maxTrashcanContents'];
-  if (hasTrashcan) {
-    if (maxTrashcanContents === undefined) {
-      maxTrashcanContents = 32;
+    let hasCss = options['css'];
+    if (hasCss === undefined) {
+      hasCss = true;
     }
-  } else {
-    maxTrashcanContents = 0;
-  }
-  const rtl = !!options['rtl'];
-  let horizontalLayout = options['horizontalLayout'];
-  if (horizontalLayout === undefined) {
-    horizontalLayout = false;
-  }
-  let toolboxAtStart = options['toolboxPosition'];
-  toolboxAtStart = toolboxAtStart !== 'end';
+    let pathToMedia = 'https://blockly-demo.appspot.com/static/media/';
+    if (options['media']) {
+      pathToMedia = options['media'];
+    } else if (options['path']) {
+      // 'path' is a deprecated option which has been replaced by 'media'.
+      pathToMedia = options['path'] + 'media/';
+    }
+    let oneBasedIndex;
+    if (options['oneBasedIndex'] === undefined) {
+      oneBasedIndex = true;
+    } else {
+      oneBasedIndex = !!options['oneBasedIndex'];
+    }
+    const renderer = options['renderer'] || 'geras';
 
-  /** @type {!toolbox.Position} */
-  let toolboxPosition;
-  if (horizontalLayout) {
-    toolboxPosition =
-        toolboxAtStart ? toolbox.Position.TOP : toolbox.Position.BOTTOM;
-  } else {
-    toolboxPosition = (toolboxAtStart === rtl) ? toolbox.Position.RIGHT :
-                                                 toolbox.Position.LEFT;
-  }
+    const plugins = options['plugins'] || {};
 
-  let hasCss = options['css'];
-  if (hasCss === undefined) {
-    hasCss = true;
-  }
-  let pathToMedia = 'https://blockly-demo.appspot.com/static/media/';
-  if (options['media']) {
-    pathToMedia = options['media'];
-  } else if (options['path']) {
-    // 'path' is a deprecated option which has been replaced by 'media'.
-    pathToMedia = options['path'] + 'media/';
-  }
-  let oneBasedIndex;
-  if (options['oneBasedIndex'] === undefined) {
-    oneBasedIndex = true;
-  } else {
-    oneBasedIndex = !!options['oneBasedIndex'];
+    /** @type {boolean} */
+    this.RTL = rtl;
+    /** @type {boolean} */
+    this.oneBasedIndex = oneBasedIndex;
+    /** @type {boolean} */
+    this.collapse = hasCollapse;
+    /** @type {boolean} */
+    this.comments = hasComments;
+    /** @type {boolean} */
+    this.disable = hasDisable;
+    /** @type {boolean} */
+    this.readOnly = readOnly;
+    /** @type {number} */
+    this.maxBlocks = options['maxBlocks'] || Infinity;
+    /** @type {?Object<string, number>} */
+    this.maxInstances = options['maxInstances'];
+    /** @type {string} */
+    this.pathToMedia = pathToMedia;
+    /** @type {boolean} */
+    this.hasCategories = hasCategories;
+    /** @type {!Options.MoveOptions} */
+    this.moveOptions = Options.parseMoveOptions_(options, hasCategories);
+    /** @deprecated  January 2019 */
+    this.hasScrollbars = !!this.moveOptions.scrollbars;
+    /** @type {boolean} */
+    this.hasTrashcan = hasTrashcan;
+    /** @type {number} */
+    this.maxTrashcanContents = maxTrashcanContents;
+    /** @type {boolean} */
+    this.hasSounds = hasSounds;
+    /** @type {boolean} */
+    this.hasCss = hasCss;
+    /** @type {boolean} */
+    this.horizontalLayout = horizontalLayout;
+    /** @type {?toolbox.ToolboxInfo} */
+    this.languageTree = toolboxJsonDef;
+    /** @type {!Options.GridOptions} */
+    this.gridOptions = Options.parseGridOptions_(options);
+    /** @type {!Options.ZoomOptions} */
+    this.zoomOptions = Options.parseZoomOptions_(options);
+    /** @type {!toolbox.Position} */
+    this.toolboxPosition = toolboxPosition;
+    /** @type {!Theme} */
+    this.theme = Options.parseThemeOptions_(options);
+    /** @type {string} */
+    this.renderer = renderer;
+    /** @type {?Object} */
+    this.rendererOverrides = options['rendererOverrides'];
+
+    /**
+     * The SVG element for the grid pattern.
+     * Created during injection.
+     * @type {?SVGElement}
+     */
+    this.gridPattern = null;
+
+    /**
+     * The parent of the current workspace, or null if there is no parent
+     * workspace.  We can assert that this is of type WorkspaceSvg as opposed to
+     * Workspace as this is only used in a rendered workspace.
+     * @type {?WorkspaceSvg}
+     */
+    this.parentWorkspace = options['parentWorkspace'];
+
+    /**
+     * Map of plugin type to name of registered plugin or plugin class.
+     * @type {!Object<string, (function(new:?, ...?)|string)>}
+     */
+    this.plugins = plugins;
+
+    /**
+     * If set, sets the translation of the workspace to match the scrollbars.
+     * @type {undefined|function(!{x:number,y:number}):void} A function that
+     *     sets the translation of the workspace to match the scrollbars. The
+     *     argument Contains an x and/or y property which is a float between 0
+     *     and 1 specifying the degree of scrolling.
+     */
+    this.setMetrics = undefined;
+
+    /**
+     * @type {undefined|function():!Metrics} A function that returns a metrics
+     *     object that describes the current workspace.
+     */
+    this.getMetrics = undefined;
   }
-  const renderer = options['renderer'] || 'geras';
 
-  const plugins = options['plugins'] || {};
+  /**
+   * Parse the user-specified move options, using reasonable defaults where
+   *    behaviour is unspecified.
+   * @param {!Object} options Dictionary of options.
+   * @param {boolean} hasCategories Whether the workspace has categories or not.
+   * @return {!Options.MoveOptions} Normalized move options.
+   * @private
+   */
+  static parseMoveOptions_(options, hasCategories) {
+    const move = options['move'] || {};
+    const moveOptions = {};
+    if (move['scrollbars'] === undefined &&
+        options['scrollbars'] === undefined) {
+      moveOptions.scrollbars = hasCategories;
+    } else if (typeof move['scrollbars'] === 'object') {
+      moveOptions.scrollbars = {};
+      moveOptions.scrollbars.horizontal = !!move['scrollbars']['horizontal'];
+      moveOptions.scrollbars.vertical = !!move['scrollbars']['vertical'];
+      // Convert scrollbars object to boolean if they have the same value.
+      // This allows us to easily check for whether any scrollbars exist using
+      // !!moveOptions.scrollbars.
+      if (moveOptions.scrollbars.horizontal &&
+          moveOptions.scrollbars.vertical) {
+        moveOptions.scrollbars = true;
+      } else if (
+          !moveOptions.scrollbars.horizontal &&
+          !moveOptions.scrollbars.vertical) {
+        moveOptions.scrollbars = false;
+      }
+    } else {
+      moveOptions.scrollbars = !!move['scrollbars'] || !!options['scrollbars'];
+    }
 
-  /** @type {boolean} */
-  this.RTL = rtl;
-  /** @type {boolean} */
-  this.oneBasedIndex = oneBasedIndex;
-  /** @type {boolean} */
-  this.collapse = hasCollapse;
-  /** @type {boolean} */
-  this.comments = hasComments;
-  /** @type {boolean} */
-  this.disable = hasDisable;
-  /** @type {boolean} */
-  this.readOnly = readOnly;
-  /** @type {number} */
-  this.maxBlocks = options['maxBlocks'] || Infinity;
-  /** @type {?Object<string, number>} */
-  this.maxInstances = options['maxInstances'];
-  /** @type {string} */
-  this.pathToMedia = pathToMedia;
-  /** @type {boolean} */
-  this.hasCategories = hasCategories;
-  /** @type {!Options.MoveOptions} */
-  this.moveOptions = Options.parseMoveOptions_(options, hasCategories);
-  /** @deprecated  January 2019 */
-  this.hasScrollbars = !!this.moveOptions.scrollbars;
-  /** @type {boolean} */
-  this.hasTrashcan = hasTrashcan;
-  /** @type {number} */
-  this.maxTrashcanContents = maxTrashcanContents;
-  /** @type {boolean} */
-  this.hasSounds = hasSounds;
-  /** @type {boolean} */
-  this.hasCss = hasCss;
-  /** @type {boolean} */
-  this.horizontalLayout = horizontalLayout;
-  /** @type {?toolbox.ToolboxInfo} */
-  this.languageTree = toolboxJsonDef;
-  /** @type {!Options.GridOptions} */
-  this.gridOptions = Options.parseGridOptions_(options);
-  /** @type {!Options.ZoomOptions} */
-  this.zoomOptions = Options.parseZoomOptions_(options);
-  /** @type {!toolbox.Position} */
-  this.toolboxPosition = toolboxPosition;
-  /** @type {!Theme} */
-  this.theme = Options.parseThemeOptions_(options);
-  /** @type {string} */
-  this.renderer = renderer;
-  /** @type {?Object} */
-  this.rendererOverrides = options['rendererOverrides'];
+    if (!moveOptions.scrollbars || move['wheel'] === undefined) {
+      // Defaults to true if single-direction scroll is enabled.
+      moveOptions.wheel = typeof moveOptions.scrollbars === 'object';
+    } else {
+      moveOptions.wheel = !!move['wheel'];
+    }
+    if (!moveOptions.scrollbars) {
+      moveOptions.drag = false;
+    } else if (move['drag'] === undefined) {
+      // Defaults to true if scrollbars is true.
+      moveOptions.drag = true;
+    } else {
+      moveOptions.drag = !!move['drag'];
+    }
+    return moveOptions;
+  }
 
   /**
-   * The SVG element for the grid pattern.
-   * Created during injection.
-   * @type {?SVGElement}
+   * Parse the user-specified zoom options, using reasonable defaults where
+   * behaviour is unspecified.  See zoom documentation:
+   *   https://developers.google.com/blockly/guides/configure/web/zoom
+   * @param {!Object} options Dictionary of options.
+   * @return {!Options.ZoomOptions} Normalized zoom options.
+   * @private
    */
-  this.gridPattern = null;
+  static parseZoomOptions_(options) {
+    const zoom = options['zoom'] || {};
+    const zoomOptions = {};
+    if (zoom['controls'] === undefined) {
+      zoomOptions.controls = false;
+    } else {
+      zoomOptions.controls = !!zoom['controls'];
+    }
+    if (zoom['wheel'] === undefined) {
+      zoomOptions.wheel = false;
+    } else {
+      zoomOptions.wheel = !!zoom['wheel'];
+    }
+    if (zoom['startScale'] === undefined) {
+      zoomOptions.startScale = 1;
+    } else {
+      zoomOptions.startScale = Number(zoom['startScale']);
+    }
+    if (zoom['maxScale'] === undefined) {
+      zoomOptions.maxScale = 3;
+    } else {
+      zoomOptions.maxScale = Number(zoom['maxScale']);
+    }
+    if (zoom['minScale'] === undefined) {
+      zoomOptions.minScale = 0.3;
+    } else {
+      zoomOptions.minScale = Number(zoom['minScale']);
+    }
+    if (zoom['scaleSpeed'] === undefined) {
+      zoomOptions.scaleSpeed = 1.2;
+    } else {
+      zoomOptions.scaleSpeed = Number(zoom['scaleSpeed']);
+    }
+    if (zoom['pinch'] === undefined) {
+      zoomOptions.pinch = zoomOptions.wheel || zoomOptions.controls;
+    } else {
+      zoomOptions.pinch = !!zoom['pinch'];
+    }
+    return zoomOptions;
+  }
 
   /**
-   * The parent of the current workspace, or null if there is no parent
-   * workspace.  We can assert that this is of type WorkspaceSvg as opposed to
-   * Workspace as this is only used in a rendered workspace.
-   * @type {WorkspaceSvg}
+   * Parse the user-specified grid options, using reasonable defaults where
+   * behaviour is unspecified. See grid documentation:
+   *   https://developers.google.com/blockly/guides/configure/web/grid
+   * @param {!Object} options Dictionary of options.
+   * @return {!Options.GridOptions} Normalized grid options.
+   * @private
    */
-  this.parentWorkspace = options['parentWorkspace'];
+  static parseGridOptions_(options) {
+    const grid = options['grid'] || {};
+    const gridOptions = {};
+    gridOptions.spacing = Number(grid['spacing']) || 0;
+    gridOptions.colour = grid['colour'] || '#888';
+    gridOptions.length =
+        (grid['length'] === undefined) ? 1 : Number(grid['length']);
+    gridOptions.snap = gridOptions.spacing > 0 && !!grid['snap'];
+    return gridOptions;
+  }
 
   /**
-   * Map of plugin type to name of registered plugin or plugin class.
-   * @type {!Object<string, (function(new:?, ...?)|string)>}
+   * Parse the user-specified theme options, using the classic theme as a
+   * default. https://developers.google.com/blockly/guides/configure/web/themes
+   * @param {!Object} options Dictionary of options.
+   * @return {!Theme} A Blockly Theme.
+   * @private
    */
-  this.plugins = plugins;
-};
+  static parseThemeOptions_(options) {
+    const theme = options['theme'] || Classic;
+    if (typeof theme === 'string') {
+      return /** @type {!Theme} */ (
+          registry.getObject(registry.Type.THEME, theme));
+    } else if (theme instanceof Theme) {
+      return /** @type {!Theme} */ (theme);
+    }
+    return Theme.defineTheme(
+        theme.name || ('builtin' + idGenerator.getNextUniqueId()), theme);
+  }
+}
 
 /**
  * Grid Options.
@@ -233,153 +388,4 @@ Options.ScrollbarOptions;
  */
 Options.ZoomOptions;
 
-/**
- * If set, sets the translation of the workspace to match the scrollbars.
- * @param {!{x:number,y:number}} xyRatio Contains an x and/or y property which
- *     is a float between 0 and 1 specifying the degree of scrolling.
- * @return {void}
- */
-Options.prototype.setMetrics;
-
-/**
- * Return an object with the metrics required to size the workspace.
- * @return {!Metrics} Contains size and position metrics.
- */
-Options.prototype.getMetrics;
-
-/**
- * Parse the user-specified move options, using reasonable defaults where
- *    behaviour is unspecified.
- * @param {!Object} options Dictionary of options.
- * @param {boolean} hasCategories Whether the workspace has categories or not.
- * @return {!Options.MoveOptions} Normalized move options.
- * @private
- */
-Options.parseMoveOptions_ = function(options, hasCategories) {
-  const move = options['move'] || {};
-  const moveOptions = {};
-  if (move['scrollbars'] === undefined && options['scrollbars'] === undefined) {
-    moveOptions.scrollbars = hasCategories;
-  } else if (typeof move['scrollbars'] === 'object') {
-    moveOptions.scrollbars = {};
-    moveOptions.scrollbars.horizontal = !!move['scrollbars']['horizontal'];
-    moveOptions.scrollbars.vertical = !!move['scrollbars']['vertical'];
-    // Convert scrollbars object to boolean if they have the same value.
-    // This allows us to easily check for whether any scrollbars exist using
-    // !!moveOptions.scrollbars.
-    if (moveOptions.scrollbars.horizontal && moveOptions.scrollbars.vertical) {
-      moveOptions.scrollbars = true;
-    } else if (
-        !moveOptions.scrollbars.horizontal &&
-        !moveOptions.scrollbars.vertical) {
-      moveOptions.scrollbars = false;
-    }
-  } else {
-    moveOptions.scrollbars = !!move['scrollbars'] || !!options['scrollbars'];
-  }
-
-  if (!moveOptions.scrollbars || move['wheel'] === undefined) {
-    // Defaults to true if single-direction scroll is enabled.
-    moveOptions.wheel = typeof moveOptions.scrollbars === 'object';
-  } else {
-    moveOptions.wheel = !!move['wheel'];
-  }
-  if (!moveOptions.scrollbars) {
-    moveOptions.drag = false;
-  } else if (move['drag'] === undefined) {
-    // Defaults to true if scrollbars is true.
-    moveOptions.drag = true;
-  } else {
-    moveOptions.drag = !!move['drag'];
-  }
-  return moveOptions;
-};
-
-/**
- * Parse the user-specified zoom options, using reasonable defaults where
- * behaviour is unspecified.  See zoom documentation:
- *   https://developers.google.com/blockly/guides/configure/web/zoom
- * @param {!Object} options Dictionary of options.
- * @return {!Options.ZoomOptions} Normalized zoom options.
- * @private
- */
-Options.parseZoomOptions_ = function(options) {
-  const zoom = options['zoom'] || {};
-  const zoomOptions = {};
-  if (zoom['controls'] === undefined) {
-    zoomOptions.controls = false;
-  } else {
-    zoomOptions.controls = !!zoom['controls'];
-  }
-  if (zoom['wheel'] === undefined) {
-    zoomOptions.wheel = false;
-  } else {
-    zoomOptions.wheel = !!zoom['wheel'];
-  }
-  if (zoom['startScale'] === undefined) {
-    zoomOptions.startScale = 1;
-  } else {
-    zoomOptions.startScale = Number(zoom['startScale']);
-  }
-  if (zoom['maxScale'] === undefined) {
-    zoomOptions.maxScale = 3;
-  } else {
-    zoomOptions.maxScale = Number(zoom['maxScale']);
-  }
-  if (zoom['minScale'] === undefined) {
-    zoomOptions.minScale = 0.3;
-  } else {
-    zoomOptions.minScale = Number(zoom['minScale']);
-  }
-  if (zoom['scaleSpeed'] === undefined) {
-    zoomOptions.scaleSpeed = 1.2;
-  } else {
-    zoomOptions.scaleSpeed = Number(zoom['scaleSpeed']);
-  }
-  if (zoom['pinch'] === undefined) {
-    zoomOptions.pinch = zoomOptions.wheel || zoomOptions.controls;
-  } else {
-    zoomOptions.pinch = !!zoom['pinch'];
-  }
-  return zoomOptions;
-};
-
-/**
- * Parse the user-specified grid options, using reasonable defaults where
- * behaviour is unspecified. See grid documentation:
- *   https://developers.google.com/blockly/guides/configure/web/grid
- * @param {!Object} options Dictionary of options.
- * @return {!Options.GridOptions} Normalized grid options.
- * @private
- */
-Options.parseGridOptions_ = function(options) {
-  const grid = options['grid'] || {};
-  const gridOptions = {};
-  gridOptions.spacing = Number(grid['spacing']) || 0;
-  gridOptions.colour = grid['colour'] || '#888';
-  gridOptions.length =
-      (grid['length'] === undefined) ? 1 : Number(grid['length']);
-  gridOptions.snap = gridOptions.spacing > 0 && !!grid['snap'];
-  return gridOptions;
-};
-
-/**
- * Parse the user-specified theme options, using the classic theme as a default.
- *   https://developers.google.com/blockly/guides/configure/web/themes
- * @param {!Object} options Dictionary of options.
- * @return {!Theme} A Blockly Theme.
- * @private
- */
-Options.parseThemeOptions_ = function(options) {
-  const theme = options['theme'] || Classic;
-  if (typeof theme === 'string') {
-    return /** @type {!Theme} */ (
-        registry.getObject(registry.Type.THEME, theme));
-  } else if (theme instanceof Theme) {
-    return /** @type {!Theme} */ (theme);
-  }
-  return Theme.defineTheme(
-      theme.name || ('builtin' + idGenerator.getNextUniqueId()), theme);
-};
-
 exports.Options = Options;