Make Blockly options an interface (#3312)

* Make workspace options an interface so it can be extended in the d.ts.

core/flyout_horizontal.js

@@ -34,12 +34,14 @@ goog.require('Blockly.WidgetDiv');
 
 /**
  * Class for a flyout.
- * @param {!Object} workspaceOptions Dictionary of options for the workspace.
+ * @param {!Blockly.Options} workspaceOptions Dictionary of options for the
+ *     workspace.
  * @extends {Blockly.Flyout}
  * @constructor
  */
 Blockly.HorizontalFlyout = function(workspaceOptions) {
-  workspaceOptions.getMetrics = this.getMetrics_.bind(this);
+  workspaceOptions.getMetrics = /** @type {function():!Object} */ (
+    this.getMetrics_.bind(this));
   workspaceOptions.setMetrics = this.setMetrics_.bind(this);
 
   Blockly.HorizontalFlyout.superClass_.constructor.call(this, workspaceOptions);

core/flyout_vertical.js

@@ -35,12 +35,14 @@ goog.require('Blockly.WidgetDiv');
 
 /**
  * Class for a flyout.
- * @param {!Object} workspaceOptions Dictionary of options for the workspace.
+ * @param {!Blockly.Options} workspaceOptions Dictionary of options for the
+ *     workspace.
  * @extends {Blockly.Flyout}
  * @constructor
  */
 Blockly.VerticalFlyout = function(workspaceOptions) {
-  workspaceOptions.getMetrics = this.getMetrics_.bind(this);
+  workspaceOptions.getMetrics = /** @type {function():!Object} */ (
+    this.getMetrics_.bind(this));
   workspaceOptions.setMetrics = this.setMetrics_.bind(this);
 
   Blockly.VerticalFlyout.superClass_.constructor.call(this, workspaceOptions);

core/inject.js

@@ -43,7 +43,7 @@ goog.require('Blockly.WorkspaceSvg');
  * Inject a Blockly editor into the specified container element (usually a div).
  * @param {Element|string} container Containing element, or its ID,
  *     or a CSS selector.
- * @param {Object=} opt_options Optional dictionary of options.
+ * @param {Blockly.BlocklyOptions=} opt_options Optional dictionary of options.
  * @return {!Blockly.WorkspaceSvg} Newly created main workspace.
  */
 Blockly.inject = function(container, opt_options) {
@@ -57,7 +57,8 @@ Blockly.inject = function(container, opt_options) {
   if (!container || !Blockly.utils.dom.containsNode(document, container)) {
     throw Error('Error: container is not in current document.');
   }
-  var options = new Blockly.Options(opt_options || {});
+  var options = new Blockly.Options(opt_options ||
+    (/** @type {!Blockly.BlocklyOptions} */ ({})));
   var subContainer = document.createElement('div');
   subContainer.className = 'injectionDiv';
   container.appendChild(subContainer);

core/options.js

@@ -30,8 +30,8 @@ goog.require('Blockly.Xml');
 /**
  * Parse the user-specified options, using reasonable defaults where behaviour
  * is unspecified.
- * @param {!Object} options Dictionary of options.  Specification:
- *   https://developers.google.com/blockly/guides/get-started/web#configuration
+ * @param {!Blockly.BlocklyOptions} options Dictionary of options.
+ *     Specification: https://developers.google.com/blockly/guides/get-started/web#configuration
  * @constructor
  */
 Blockly.Options = function(options) {
@@ -146,6 +146,13 @@ Blockly.Options = function(options) {
   this.renderer = renderer;
 };
 
+/**
+ * Blockly options.
+ * This interface is further described in `typings/blockly-interfaces.d.ts`.
+ * @interface
+ */
+Blockly.BlocklyOptions = function() {};
+
 /**
  * The parent of the current workspace, or null if there is no parent workspace.
  * @type {Blockly.Workspace}
@@ -154,6 +161,8 @@ Blockly.Options.prototype.parentWorkspace = null;
 
 /**
  * If set, sets the translation of the workspace to match the scrollbars.
+ * @param {!Object} xyRatio Contains an x and/or y property which is a float
+ *     between 0 and 1 specifying the degree of scrolling.
  * @return {void}
  */
 Blockly.Options.prototype.setMetrics;

core/toolbox.js

@@ -178,7 +178,7 @@ Blockly.Toolbox.prototype.init = function() {
         }
         Blockly.Touch.clearTouchIdentifier();  // Don't block future drags.
       }, /* opt_noCaptureIdentifier */ false, /* opt_noPreventDefault */ true);
-  var workspaceOptions = {
+  var workspaceOptions = /** @type {!Blockly.Options} */ ({
     disabledPatternId: workspace.options.disabledPatternId,
     parentWorkspace: workspace,
     RTL: workspace.RTL,
@@ -186,7 +186,7 @@ Blockly.Toolbox.prototype.init = function() {
     horizontalLayout: workspace.horizontalLayout,
     toolboxPosition: workspace.options.toolboxPosition,
     renderer: workspace.options.renderer
-  };
+  });
   if (workspace.horizontalLayout) {
     if (!Blockly.HorizontalFlyout) {
       throw Error('Missing require for Blockly.HorizontalFlyout');

core/trashcan.js

@@ -60,14 +60,14 @@ Blockly.Trashcan = function(workspace) {
     return;
   }
   // Create flyout options.
-  var flyoutWorkspaceOptions = {
+  var flyoutWorkspaceOptions = /** @type {!Blockly.Options} */ ({
     scrollbars: true,
     disabledPatternId: this.workspace_.options.disabledPatternId,
     parentWorkspace: this.workspace_,
     RTL: this.workspace_.RTL,
     oneBasedIndex: this.workspace_.options.oneBasedIndex,
     renderer: this.workspace_.options.renderer
-  };
+  });
   // Create vertical or horizontal flyout.
   if (this.workspace_.horizontalLayout) {
     flyoutWorkspaceOptions.toolboxPosition =

core/workspace_svg.js

@@ -62,7 +62,7 @@ Blockly.WorkspaceSvg = function(options,
   /** @type {function():!Object} */
   this.getMetrics =
       options.getMetrics || Blockly.WorkspaceSvg.getTopLevelWorkspaceMetrics_;
-  /** @type {function(!Object)} */
+  /** @type {function(!Object):void} */
   this.setMetrics =
       options.setMetrics || Blockly.WorkspaceSvg.setTopLevelWorkspaceMetrics_;
 
@@ -804,7 +804,7 @@ Blockly.WorkspaceSvg.prototype.addZoomControls = function() {
  * @package
  */
 Blockly.WorkspaceSvg.prototype.addFlyout = function(tagName) {
-  var workspaceOptions = {
+  var workspaceOptions = /** @type {!Blockly.Options} */ ({
     disabledPatternId: this.options.disabledPatternId,
     parentWorkspace: this,
     RTL: this.RTL,
@@ -812,7 +812,7 @@ Blockly.WorkspaceSvg.prototype.addFlyout = function(tagName) {
     horizontalLayout: this.horizontalLayout,
     toolboxPosition: this.options.toolboxPosition,
     renderer: this.options.renderer
-  };
+  });
   if (this.horizontalLayout) {
     if (!Blockly.HorizontalFlyout) {
       throw Error('Missing require for Blockly.HorizontalFlyout');