CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-01-10 02:17:09 +01:00
Code Issues Packages Projects Releases Wiki Activity

fix: JSDoc generation for modules without classes

Browse Source
This commit is contained in:
Aaron Dodson
2021-09-22 14:37:36 -07:00
parent e1defd8e5c
commit e1310b6464
24 changed files with 303 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
core/blockly.js
View File

@@ -75,6 +75,7 @@ goog.require('Blockly.Xml');
* For local builds, you can pass --define='Blockly.VERSION=X.Y.Z' to the
* compiler to override this constant.
* @define {string}
* @alias Blockly.VERSION
*/
exports.VERSION = 'uncompiled';
@@ -152,6 +153,7 @@ Object.defineProperties(exports, {
* @param {!SVGElement} svg SVG image.
* @return {!Size} Contains width and height properties.
* @deprecated Use workspace.setCachedParentSvgSize. (2021 March 5)
* @alias Blockly.svgSize
*/
const svgSize = function(svg) {
// When removing this function, remove svg.cachedWidth_ and svg.cachedHeight_
@@ -168,6 +170,7 @@ exports.svgSize = svgSize;
* Size the workspace when the contents change. This also updates
* scrollbars accordingly.
* @param {!WorkspaceSvg} workspace The workspace to resize.
* @alias Blockly.resizeSvgContents
*/
const resizeSvgContents = function(workspace) {
workspace.resizeContents();
@@ -178,6 +181,7 @@ exports.resizeSvgContents = resizeSvgContents;
* Copy a block or workspace comment onto the local clipboard.
* @param {!ICopyable} toCopy Block or Workspace Comment to be copied.
* @package
* @alias Blockly.copy
*/
exports.copy = clipboard.copy;
@@ -185,6 +189,7 @@ exports.copy = clipboard.copy;
* Paste a block or workspace comment on to the main workspace.
* @return {boolean} True if the paste was successful, false otherwise.
* @package
* @alias Blockly.paste
*/
exports.paste = clipboard.paste;
@@ -193,6 +198,7 @@ exports.paste = clipboard.paste;
* @param {!ICopyable} toDuplicate Block or Workspace Comment to be
* copied.
* @package
* @alias Blockly.duplicate
*/
exports.duplicate = clipboard.duplicate;
@@ -200,6 +206,7 @@ exports.duplicate = clipboard.duplicate;
* Close tooltips, context menus, dropdown selections, etc.
* @deprecated Use Blockly.common.getMainWorkspace().hideChaff()
* @param {boolean=} opt_onlyClosePopups Whether only popups should be closed.
* @alias Blockly.hideChaff
*/
const hideChaff = function(opt_onlyClosePopups) {
deprecation.warn('Blockly.hideChaff', 'September 2021', 'September 2022');
@@ -212,6 +219,7 @@ exports.hideChaff = hideChaff;
* focus). Try not to use this function, particularly if there are multiple
* Blockly instances on a page.
* @return {!Workspace} The main workspace.
* @alias Blockly.getMainWorkspace
*/
exports.getMainWorkspace = common.getMainWorkspace;
@@ -232,6 +240,7 @@ const jsonInitFactory = function(jsonDef) {
* Define blocks from an array of JSON block definitions, as might be generated
* by the Blockly Developer Tools.
* @param {!Array<!Object>} jsonArray An array of JSON block definitions.
* @alias Blockly.defineBlocksWithJsonArray
*/
const defineBlocksWithJsonArray = function(jsonArray) {
for (let i = 0; i < jsonArray.length; i++) {
@@ -263,6 +272,7 @@ exports.defineBlocksWithJsonArray = defineBlocksWithJsonArray;
* Is the given string a number (includes negative and decimals).
* @param {string} str Input string.
* @return {boolean} True if number, false otherwise.
* @alias Blockly.isNumber
*/
const isNumber = function(str) {
return /^\s*-?\d+(\.\d+)?\s*$/.test(str);
@@ -276,6 +286,7 @@ exports.isNumber = isNumber;
* is called.
* This method is a NOP if called after the first ``Blockly.inject``.
* @param {!Element} container The container element.
* @alias Blockly.setParentContainer
*/
exports.setParentContainer = common.setParentContainer;
@@ -284,6 +295,7 @@ exports.setParentContainer = common.setParentContainer;
/**
* @see colour.hueToHex
* @deprecated Use Blockly.utils.colour.hueToHex (September 2021).
* @alias Blockly.hueToHex
*/
exports.hueToHex = colour.hueToHex;

3
core/css.js
View File

@@ -30,6 +30,7 @@ let injected = false;
* components such as fields and the toolbox to store separate CSS.
* The provided array of CSS will be destroyed by this function.
* @param {!Array<string>} cssArray Array of CSS strings.
* @alias Blockly.Css.register
*/
const register = function(cssArray) {
if (injected) {
@@ -50,6 +51,7 @@ exports.register = register;
* @param {boolean} hasCss If false, don't inject CSS
* (providing CSS becomes the document's responsibility).
* @param {string} pathToMedia Path from page to the Blockly media directory.
* @alias Blockly.Css.inject
*/
const inject = function(hasCss, pathToMedia) {
// Only inject the CSS once.
@@ -77,6 +79,7 @@ exports.inject = inject;
/**
* Array making up the CSS content for Blockly.
* @alias Blockly.Css.CONTENT
*/
const CONTENT = [
`.blocklySvg {

43
core/events/events.js
View File

@@ -45,6 +45,7 @@ let group = '';
/**
* Sets whether the next event should be added to the undo stack.
* @type {boolean}
* @alias Blockly.Events.recordUndo
*/
let recordUndo = true;
/** @deprecated September 2021 */
@@ -53,6 +54,7 @@ exports.recordUndo = recordUndo;
/**
* Sets whether events should be added to the undo stack.
* @param {boolean} newValue True if events should be added to the undo stack.
* @alias Blockly.Events.setRecordUndo
*/
const setRecordUndo = function(newValue) {
recordUndo = newValue;
@@ -62,6 +64,7 @@ exports.setRecordUndo = setRecordUndo;
/**
* Returns whether or not events will be added to the undo stack.
* @returns {boolean} True if events will be added to the undo stack.
* @alias Blockly.Events.getRecordUndo
*/
const getRecordUndo = function() {
return recordUndo;
@@ -94,6 +97,7 @@ let disabled = 0;
/**
* Name of event that creates a block. Will be deprecated for BLOCK_CREATE.
* @const
* @alias Blockly.Events.CREATE
*/
const CREATE = 'create';
exports.CREATE = CREATE;
@@ -101,6 +105,7 @@ exports.CREATE = CREATE;
/**
* Name of event that creates a block.
* @const
* @alias Blockly.Events.BLOCK_CREATE
*/
const BLOCK_CREATE = CREATE;
exports.BLOCK_CREATE = BLOCK_CREATE;
@@ -108,6 +113,7 @@ exports.BLOCK_CREATE = BLOCK_CREATE;
/**
* Name of event that deletes a block. Will be deprecated for BLOCK_DELETE.
* @const
* @alias Blockly.Events.DELETE
*/
const DELETE = 'delete';
exports.DELETE = DELETE;
@@ -115,6 +121,7 @@ exports.DELETE = DELETE;
/**
* Name of event that deletes a block.
* @const
* @alias Blockly.Events.BLOCK_DELETE
*/
const BLOCK_DELETE = DELETE;
exports.BLOCK_DELETE = BLOCK_DELETE;
@@ -122,6 +129,7 @@ exports.BLOCK_DELETE = BLOCK_DELETE;
/**
* Name of event that changes a block. Will be deprecated for BLOCK_CHANGE.
* @const
* @alias Blockly.Events.CHANGE
*/
const CHANGE = 'change';
exports.CHANGE = CHANGE;
@@ -129,6 +137,7 @@ exports.CHANGE = CHANGE;
/**
* Name of event that changes a block.
* @const
* @alias Blockly.Events.BLOCK_CHANGE
*/
const BLOCK_CHANGE = CHANGE;
exports.BLOCK_CHANGE = BLOCK_CHANGE;
@@ -136,6 +145,7 @@ exports.BLOCK_CHANGE = BLOCK_CHANGE;
/**
* Name of event that moves a block. Will be deprecated for BLOCK_MOVE.
* @const
* @alias Blockly.Events.MOVE
*/
const MOVE = 'move';
exports.MOVE = MOVE;
@@ -143,6 +153,7 @@ exports.MOVE = MOVE;
/**
* Name of event that moves a block.
* @const
* @alias Blockly.Events.BLOCK_MOVE
*/
const BLOCK_MOVE = MOVE;
exports.BLOCK_MOVE = BLOCK_MOVE;
@@ -150,6 +161,7 @@ exports.BLOCK_MOVE = BLOCK_MOVE;
/**
* Name of event that creates a variable.
* @const
* @alias Blockly.Events.VAR_CREATE
*/
const VAR_CREATE = 'var_create';
exports.VAR_CREATE = VAR_CREATE;
@@ -157,6 +169,7 @@ exports.VAR_CREATE = VAR_CREATE;
/**
* Name of event that deletes a variable.
* @const
* @alias Blockly.Events.VAR_DELETE
*/
const VAR_DELETE = 'var_delete';
exports.VAR_DELETE = VAR_DELETE;
@@ -164,6 +177,7 @@ exports.VAR_DELETE = VAR_DELETE;
/**
* Name of event that renames a variable.
* @const
* @alias Blockly.Events.VAR_RENAME
*/
const VAR_RENAME = 'var_rename';
exports.VAR_RENAME = VAR_RENAME;
@@ -171,6 +185,7 @@ exports.VAR_RENAME = VAR_RENAME;
/**
* Name of generic event that records a UI change.
* @const
* @alias Blockly.Events.UI
*/
const UI = 'ui';
exports.UI = UI;
@@ -178,6 +193,7 @@ exports.UI = UI;
/**
* Name of event that record a block drags a block.
* @const
* @alias Blockly.Events.BLOCK_DRAG
*/
const BLOCK_DRAG = 'drag';
exports.BLOCK_DRAG = BLOCK_DRAG;
@@ -185,6 +201,7 @@ exports.BLOCK_DRAG = BLOCK_DRAG;
/**
* Name of event that records a change in selected element.
* @const
* @alias Blockly.Events.SELECTED
*/
const SELECTED = 'selected';
exports.SELECTED = SELECTED;
@@ -192,6 +209,7 @@ exports.SELECTED = SELECTED;
/**
* Name of event that records a click.
* @const
* @alias Blockly.Events.CLICK
*/
const CLICK = 'click';
exports.CLICK = CLICK;
@@ -199,6 +217,7 @@ exports.CLICK = CLICK;
/**
* Name of event that records a marker move.
* @const
* @alias Blockly.Events.MARKER_MOVE
*/
const MARKER_MOVE = 'marker_move';
exports.MARKER_MOVE = MARKER_MOVE;
@@ -206,6 +225,7 @@ exports.MARKER_MOVE = MARKER_MOVE;
/**
* Name of event that records a bubble open.
* @const
* @alias Blockly.Events.BUBBLE_OPEN
*/
const BUBBLE_OPEN = 'bubble_open';
exports.BUBBLE_OPEN = BUBBLE_OPEN;
@@ -213,6 +233,7 @@ exports.BUBBLE_OPEN = BUBBLE_OPEN;
/**
* Name of event that records a trashcan open.
* @const
* @alias Blockly.Events.TRASHCAN_OPEN
*/
const TRASHCAN_OPEN = 'trashcan_open';
exports.TRASHCAN_OPEN = TRASHCAN_OPEN;
@@ -220,6 +241,7 @@ exports.TRASHCAN_OPEN = TRASHCAN_OPEN;
/**
* Name of event that records a toolbox item select.
* @const
* @alias Blockly.Events.TOOLBOX_ITEM_SELECT
*/
const TOOLBOX_ITEM_SELECT = 'toolbox_item_select';
exports.TOOLBOX_ITEM_SELECT = TOOLBOX_ITEM_SELECT;
@@ -227,6 +249,7 @@ exports.TOOLBOX_ITEM_SELECT = TOOLBOX_ITEM_SELECT;
/**
* Name of event that records a theme change.
* @const
* @alias Blockly.Events.THEME_CHANGE
*/
const THEME_CHANGE = 'theme_change';
exports.THEME_CHANGE = THEME_CHANGE;
@@ -234,6 +257,7 @@ exports.THEME_CHANGE = THEME_CHANGE;
/**
* Name of event that records a viewport change.
* @const
* @alias Blockly.Events.VIEWPORT_CHANGE
*/
const VIEWPORT_CHANGE = 'viewport_change';
exports.VIEWPORT_CHANGE = VIEWPORT_CHANGE;
@@ -241,6 +265,7 @@ exports.VIEWPORT_CHANGE = VIEWPORT_CHANGE;
/**
* Name of event that creates a comment.
* @const
* @alias Blockly.Events.COMMENT_CREATE
*/
const COMMENT_CREATE = 'comment_create';
exports.COMMENT_CREATE = COMMENT_CREATE;
@@ -248,6 +273,7 @@ exports.COMMENT_CREATE = COMMENT_CREATE;
/**
* Name of event that deletes a comment.
* @const
* @alias Blockly.Events.COMMENT_DELETE
*/
const COMMENT_DELETE = 'comment_delete';
exports.COMMENT_DELETE = COMMENT_DELETE;
@@ -255,6 +281,7 @@ exports.COMMENT_DELETE = COMMENT_DELETE;
/**
* Name of event that changes a comment.
* @const
* @alias Blockly.Events.COMMENT_CHANGE
*/
const COMMENT_CHANGE = 'comment_change';
exports.COMMENT_CHANGE = COMMENT_CHANGE;
@@ -262,12 +289,14 @@ exports.COMMENT_CHANGE = COMMENT_CHANGE;
/**
* Name of event that moves a comment.
* @const
* @alias Blockly.Events.COMMENT_MOVE
*/
const COMMENT_MOVE = 'comment_move';
exports.COMMENT_MOVE = COMMENT_MOVE;
/**
* Name of event that records a workspace load.
* @alias Blockly.Events.FINISHED_LOADING
*/
const FINISHED_LOADING = 'finished_loading';
exports.FINISHED_LOADING = FINISHED_LOADING;
@@ -280,6 +309,7 @@ exports.FINISHED_LOADING = FINISHED_LOADING;
* appear connected.
* @typedef {!BlockCreate|!BlockMove|
* !CommentCreate|!CommentMove}
* @alias Blockly.Events.BumpEvent
*/
let BumpEvent;
exports.BumpEvent = BumpEvent;
@@ -291,6 +321,7 @@ exports.BumpEvent = BumpEvent;
* Not to be confused with bumping so that disconnected connections do not
* appear connected.
* @const
* @alias Blockly.Events.BUMP_EVENTS
*/
const BUMP_EVENTS = [BLOCK_CREATE, BLOCK_MOVE, COMMENT_CREATE, COMMENT_MOVE];
exports.BUMP_EVENTS = BUMP_EVENTS;
@@ -303,6 +334,7 @@ const FIRE_QUEUE = [];
/**
* Create a custom event and fire it.
* @param {!Abstract} event Custom data for event.
* @alias Blockly.Events.fire
*/
const fire = function(event) {
if (!isEnabled()) {
@@ -339,6 +371,7 @@ const fireNow = function() {
* @param {!Array<!Abstract>} queueIn Array of events.
* @param {boolean} forward True if forward (redo), false if backward (undo).
* @return {!Array<!Abstract>} Array of filtered events.
* @alias Blockly.Events.filter
*/
const filter = function(queueIn, forward) {
let queue = queueIn.slice(); // Shallow copy of queue.
@@ -412,6 +445,7 @@ exports.filter = filter;
/**
* Modify pending undo events so that when they are fired they don't land
* in the undo stack. Called by Workspace.clearUndo.
* @alias Blockly.Events.clearPendingUndo
*/
const clearPendingUndo = function() {
for (let i = 0, event; (event = FIRE_QUEUE[i]); i++) {
@@ -422,6 +456,7 @@ exports.clearPendingUndo = clearPendingUndo;
/**
* Stop sending events. Every call to this function MUST also call enable.
* @alias Blockly.Events.disable
*/
const disable = function() {
disabled++;
@@ -431,6 +466,7 @@ exports.disable = disable;
/**
* Start sending events. Unless events were already disabled when the
* corresponding call to disable was made.
* @alias Blockly.Events.enable
*/
const enable = function() {
disabled--;
@@ -440,6 +476,7 @@ exports.enable = enable;
/**
* Returns whether events may be fired or not.
* @return {boolean} True if enabled.
* @alias Blockly.Events.isEnabled
*/
const isEnabled = function() {
return disabled == 0;
@@ -449,6 +486,7 @@ exports.isEnabled = isEnabled;
/**
* Current group.
* @return {string} ID string.
* @alias Blockly.Events.getGroup
*/
const getGroup = function() {
return group;
@@ -459,6 +497,7 @@ exports.getGroup = getGroup;
* Start or stop a group.
* @param {boolean|string} state True to start new group, false to end group.
* String to set group explicitly.
* @alias Blockly.Events.setGroup
*/
const setGroup = function(state) {
if (typeof state == 'boolean') {
@@ -473,6 +512,7 @@ exports.setGroup = setGroup;
* Compute a list of the IDs of the specified block and all its descendants.
* @param {!Block} block The root block.
* @return {!Array<string>} List of block IDs.
* @alias Blockly.Events.getDescendantIds
*/
const getDescendantIds = function(block) {
const ids = [];
@@ -491,6 +531,7 @@ exports.getDescendantIds = getDescendantIds;
* @param {!Workspace} workspace Target workspace for event.
* @return {!Abstract} The event represented by the JSON.
* @throws {Error} if an event type is not found in the registry.
* @alias Blockly.Events.fromJson
*/
const fromJson = function(json, workspace) {
const eventClass = get(json.type);
@@ -509,6 +550,7 @@ exports.fromJson = fromJson;
* @param {string} eventType The type of the event to get.
* @return {?function(new:Abstract, ...?)} The event class with
* the given type or null if none exists.
* @alias Blockly.Events.get
*/
const get = function(eventType) {
return registry.getClass(registry.Type.EVENT, eventType);
@@ -521,6 +563,7 @@ exports.get = get;
* Recommend setting the 'disable' option to 'false' in the config so that
* users don't try to re-enable disabled orphan blocks.
* @param {!Abstract} event Custom data for event.
* @alias Blockly.Events.disableOrphans
*/
const disableOrphans = function(event) {
if (event.type == MOVE || event.type == CREATE) {

7
core/extensions.js
View File

@@ -42,6 +42,7 @@ exports.TEST_ONLY = {allExtensions};
* @param {Function} initFn The function to initialize an extended block.
* @throws {Error} if the extension name is empty, the extension is already
* registered, or extensionFn is not a function.
* @alias Blockly.Extensions.register
*/
const register = function(name, initFn) {
if ((typeof name != 'string') || (name.trim() == '')) {
@@ -63,6 +64,7 @@ exports.register = register;
* @param {!Object} mixinObj The values to mix in.
* @throws {Error} if the extension name is empty or the extension is already
* registered.
* @alias Blockly.Extensions.registerMixin
*/
const registerMixin = function(name, mixinObj) {
if (!mixinObj || typeof mixinObj != 'object') {
@@ -86,6 +88,7 @@ exports.registerMixin = registerMixin;
* @param {!Array<string>=} opt_blockList A list of blocks to appear in the
* flyout of the mutator dialog.
* @throws {Error} if the mutation is invalid or can't be applied to the block.
* @alias Blockly.Extensions.registerMutator
*/
const registerMutator = function(name, mixinObj, opt_helperFn, opt_blockList) {
const errorPrefix = 'Error when registering mutator "' + name + '": ';
@@ -119,6 +122,7 @@ exports.registerMutator = registerMutator;
/**
* Unregisters the extension registered with the given name.
* @param {string} name The name of the extension to unregister.
* @alias Blockly.Extensions.unregister
*/
const unregister = function(name) {
if (allExtensions[name]) {
@@ -137,6 +141,7 @@ exports.unregister = unregister;
* @param {!Block} block The block to apply the named extension to.
* @param {boolean} isMutator True if this extension defines a mutator.
* @throws {Error} if the extension is not found.
* @alias Blockly.Extensions.apply
*/
const apply = function(name, block, isMutator) {
const extensionFn = allExtensions[name];
@@ -348,6 +353,7 @@ const mutatorPropertiesMatch = function(oldProperties, block) {
* @param {!Object<string, string>} lookupTable The table of field values to
* tooltip text.
* @return {!Function} The extension function.
* @alias Blockly.Extensions.buildTooltipForDropdown
*/
const buildTooltipForDropdown = function(dropdownName, lookupTable) {
// List of block types already validated, to minimize duplicate warnings.
@@ -430,6 +436,7 @@ const checkDropdownOptionsInTable = function(block, dropdownName, lookupTable) {
* %1 placeholder.
* @param {string} fieldName The field with the replacement text.
* @return {!Function} The extension function.
* @alias Blockly.Extensions.buildTooltipWithFieldText
*/
const buildTooltipWithFieldText = function(msgTemplate, fieldName) {
// Check the tooltip string messages for invalid references.

11
core/procedures.js
View File

@@ -40,6 +40,7 @@ goog.require('Blockly.Events.BlockChange');
/**
* The default argument for a procedures_mutatorarg block.
* @type {string}
* @alias Blockly.Procedures.DEFAULT_ARG
*/
const DEFAULT_ARG = 'x';
exports.DEFAULT_ARG = DEFAULT_ARG;
@@ -51,6 +52,7 @@ exports.DEFAULT_ARG = DEFAULT_ARG;
* renameProcedure: function(string,string),
* getProcedureDef: function():!Array
* }}
* @alias Blockly.Procedures.ProcedureBlock
*/
let ProcedureBlock;
exports.ProcedureBlock = ProcedureBlock;
@@ -62,6 +64,7 @@ exports.ProcedureBlock = ProcedureBlock;
* first contains procedures without return variables, the second with.
* Each procedure is defined by a three-element list of name, parameter
* list, and return value boolean.
* @alias Blockly.Procedures.allProcedures
*/
const allProcedures = function(root) {
const proceduresNoReturn =
@@ -97,6 +100,7 @@ const procTupleComparator = function(ta, tb) {
* @param {string} name Proposed procedure name.
* @param {!Block} block Block to disambiguate.
* @return {string} Non-colliding name.
* @alias Blockly.Procedures.findLegalName
*/
const findLegalName = function(name, block) {
if (block.isInFlyout) {
@@ -137,6 +141,7 @@ const isLegalName = function(name, workspace, opt_exclude) {
* @param {Block=} opt_exclude Optional block to exclude from
* comparisons (one doesn't want to collide with oneself).
* @return {boolean} True if the name is used, otherwise return false.
* @alias Blockly.Procedures.isNameUsed
*/
const isNameUsed = function(name, workspace, opt_exclude) {
const blocks = workspace.getAllBlocks(false);
@@ -162,6 +167,7 @@ exports.isNameUsed = isNameUsed;
* @param {string} name The proposed new name.
* @return {string} The accepted name.
* @this {Field}
* @alias Blockly.Procedures.rename
*/
const rename = function(name) {
// Strip leading and trailing whitespace. Beyond this, all names are legal.
@@ -190,6 +196,7 @@ exports.rename = rename;
* Construct the blocks required by the flyout for the procedure category.
* @param {!Workspace} workspace The workspace containing procedures.
* @return {!Array<!Element>} Array of XML block elements.
* @alias Blockly.Procedures.flyoutCategory
*/
const flyoutCategory = function(workspace) {
const xmlList = [];
@@ -297,6 +304,7 @@ const updateMutatorFlyout = function(workspace) {
* Listens for when a procedure mutator is opened. Then it triggers a flyout
* update and adds a mutator change listener to the mutator workspace.
* @param {!Abstract} e The event that triggered this listener.
* @alias Blockly.Procedures.mutatorOpenListener
*/
const mutatorOpenListener = function(e) {
if (!(e.type == Events.BUBBLE_OPEN && e.bubbleType === 'mutator' &&
@@ -337,6 +345,7 @@ const mutatorChangeListener = function(e) {
* @param {string} name Name of procedure.
* @param {!Workspace} workspace The workspace to find callers in.
* @return {!Array<!Block>} Array of caller blocks.
* @alias Blockly.Procedures.getCallers
*/
const getCallers = function(name, workspace) {
const callers = [];
@@ -360,6 +369,7 @@ exports.getCallers = getCallers;
* When a procedure definition changes its parameters, find and edit all its
* callers.
* @param {!Block} defBlock Procedure definition block.
* @alias Blockly.Procedures.mutateCallers
*/
const mutateCallers = function(defBlock) {
const oldRecordUndo = Events.getRecordUndo();
@@ -391,6 +401,7 @@ exports.mutateCallers = mutateCallers;
* @param {string} name Name of procedure.
* @param {!Workspace} workspace The workspace to search.
* @return {?Block} The procedure definition block, or null not found.
* @alias Blockly.Procedures.getDefinition
*/
const getDefinition = function(name, workspace) {
// Do not assume procedure is a top block. Some languages allow nested

2
core/serialization/priorities.js
View File

@@ -23,6 +23,7 @@ goog.module.declareLegacyNamespace();
* The priority for deserializing variables.
* @type {number}
* @const
* @alias Blockly.serialization.priorities.VARIABLES
*/
exports.VARIABLES = 100;
@@ -30,5 +31,6 @@ exports.VARIABLES = 100;
* The priority for deserializing blocks.
* @type {number}
* @const
* @alias Blockly.serialization.priorities.BLOCKS
*/
exports.BLOCKS = 50;

27
core/tooltip.js
View File

@@ -34,6 +34,7 @@ const deprecation = goog.require('Blockly.utils.deprecation');
* returns either a string, or another arbitrarily nested function which
* eventually unwinds to a string.
* @typedef {string|{tooltip}|function(): (string|!Function)}
* @alias Blockly.Tooltip.TipInfo
*/
let TipInfo;
exports.TipInfo = TipInfo;
@@ -41,11 +42,17 @@ exports.TipInfo = TipInfo;
/**
* Is a tooltip currently showing?
* @type {boolean}
* @alias Blockly.Tooltip.visible
*/
let visible = false;
/** @deprecated September 2021 */
exports.visible;
/**
* Returns whether or not a tooltip is showing
* @returns {boolean} True if a tooltip is showing
* @alias Blockly.Tooltip.isVisible
*/
const isVisible = function() {
return visible;
};
@@ -70,6 +77,7 @@ let blocked = false;
/**
* Maximum width (in characters) of a tooltip.
* @alias Blockly.Tooltip.LIMIT
*/
const LIMIT = 50;
exports.LIMIT = LIMIT;
@@ -109,30 +117,35 @@ let poisonedElement = null;
/**
* Horizontal offset between mouse cursor and tooltip.
* @alias Blockly.Tooltip.OFFSET_X
*/
const OFFSET_X = 0;
exports.OFFSET_X = OFFSET_X;
/**
* Vertical offset between mouse cursor and tooltip.
* @alias Blockly.Tooltip.OFFSET_Y
*/
const OFFSET_Y = 10;
exports.OFFSET_Y = OFFSET_Y;
/**
* Radius mouse can move before killing tooltip.
* @alias Blockly.Tooltip.RADIUS_OK
*/
const RADIUS_OK = 10;
exports.RADIUS_OK = RADIUS_OK;
/**
* Delay before tooltip appears.
* @alias Blockly.Tooltip.HOVER_MS
*/
const HOVER_MS = 750;
exports.HOVER_MS = HOVER_MS;
/**
* Horizontal padding between tooltip and screen edge.
* @alias Blockly.Tooltip.MARGINS
*/
const MARGINS = 5;
exports.MARGINS = MARGINS;
@@ -140,11 +153,17 @@ exports.MARGINS = MARGINS;
/**
* The HTML container. Set once by createDom.
* @type {Element}
* @alias Blockly.Tooltip.DIV
*/
let DIV = null;
/** @deprecated September 2021 */
exports.DIV = DIV;
/**
* Returns the HTML tooltip container.
* @returns {Element} The HTML tooltip container.
* @alias Blockly.Tooltip.getDiv
*/
const getDiv = function() {
return DIV;
};
@@ -165,6 +184,7 @@ Object.defineProperties(exports, {
* Returns the tooltip text for the given element.
* @param {?Object} object The object to get the tooltip text of.
* @return {string} The tooltip text of the element.
* @alias Blockly.Tooltip.getTooltipOfObject
*/
const getTooltipOfObject = function(object) {
const obj = getTargetObject(object);
@@ -202,6 +222,7 @@ const getTargetObject = function(obj) {
/**
* Create the tooltip div and inject it onto the page.
* @alias Blockly.Tooltip.createDom
*/
const createDom = function() {
if (DIV) {
@@ -218,6 +239,7 @@ exports.createDom = createDom;
/**
* Binds the required mouse events onto an SVG element.
* @param {!Element} element SVG element onto which tooltip is to be bound.
* @alias Blockly.Tooltip.bindMouseEvents
*/
const bindMouseEvents = function(element) {
element.mouseOverWrapper_ =
@@ -235,6 +257,7 @@ exports.bindMouseEvents = bindMouseEvents;
/**
* Unbinds tooltip mouse events from the SVG element.
* @param {!Element} element SVG element onto which tooltip is bound.
* @alias Blockly.Tooltip.unbindMouseEvents
*/
const unbindMouseEvents = function(element) {
if (!element) {
@@ -323,6 +346,7 @@ const onMouseMove = function(e) {
/**
* Dispose of the tooltip.
* @alias Blockly.Tooltip.dispose
*/
const dispose = function() {
element = null;
@@ -334,6 +358,7 @@ exports.dispose = dispose;
/**
* Hide the tooltip.
* @alias Blockly.Tooltip.hide
*/
const hide = function() {
if (visible) {
@@ -351,6 +376,7 @@ exports.hide = hide;
/**
* Hide any in-progress tooltips and block showing new tooltips until the next
* call to unblock().
* @alias Blockly.Tooltip.block
*/
const block = function() {
hide();
@@ -362,6 +388,7 @@ exports.block = block;
/**
* Unblock tooltips: allow them to be scheduled and shown according to their own
* logic.
* @alias Blockly.Tooltip.unblock
*/
const unblock = function() {
blocked = false;

19
core/utils.js
View File

@@ -73,6 +73,7 @@ exports.xml = xmlUtils;
* Halts the propagation of the event without doing anything else.
* @param {!Event} e An event.
* @deprecated
* @alias Blockly.utils.noEvent
*/
const noEvent = function(e) {
deprecation.warn(
@@ -88,6 +89,7 @@ exports.noEvent = noEvent;
* @param {!Event} e An event.
* @return {boolean} True if text input.
* @deprecated Use Blockly.browserEvents.isTargetInput instead.
* @alias Blockly.utils.isTargetInput
*/
const isTargetInput = function(e) {
deprecation.warn(
@@ -102,6 +104,7 @@ exports.isTargetInput = isTargetInput;
* its parent. Only for SVG elements and children (e.g. rect, g, path).
* @param {!Element} element SVG element to find the coordinates of.
* @return {!Coordinate} Object with .x and .y properties.
* @alias Blockly.utils.getRelativeXY
*/
const getRelativeXY = function(element) {
const xy = new Coordinate(0, 0);
@@ -146,6 +149,7 @@ exports.getRelativeXY = getRelativeXY;
* not a child of the div Blockly was injected into, the behaviour is
* undefined.
* @return {!Coordinate} Object with .x and .y properties.
* @alias Blockly.utils.getInjectionDivXY_
*/
const getInjectionDivXY = function(element) {
let x = 0;
@@ -190,6 +194,7 @@ getRelativeXY.XY_STYLE_REGEX_ =
* @param {!Event} e Mouse event.
* @return {boolean} True if right-click.
* @deprecated Use Blockly.browserEvents.isRightButton instead.
* @alias Blockly.utils.isRightButton
*/
const isRightButton = function(e) {
deprecation.warn(
@@ -207,6 +212,7 @@ exports.isRightButton = isRightButton;
* @param {?SVGMatrix} matrix Inverted screen CTM to use.
* @return {!SVGPoint} Object with .x and .y properties.
* @deprecated Use Blockly.browserEvents.mouseToSvg instead;
* @alias Blockly.utils.mouseToSvg
*/
const mouseToSvg = function(e, svg, matrix) {
deprecation.warn(
@@ -222,6 +228,7 @@ exports.mouseToSvg = mouseToSvg;
* @return {{x: number, y: number}} Scroll delta object with .x and .y
* properties.
* @deprecated Use Blockly.browserEvents.getScrollDeltaPixels instead.
* @alias Blockly.utils.getScrollDeltaPixels
*/
const getScrollDeltaPixels = function(e) {
deprecation.warn(
@@ -240,6 +247,7 @@ exports.getScrollDeltaPixels = getScrollDeltaPixels;
* @param {string} message Text which might contain string table references and
* interpolation tokens.
* @return {!Array<string|number>} Array of strings and numbers.
* @alias Blockly.utils.tokenizeInterpolation
*/
const tokenizeInterpolation = function(message) {
return tokenizeInterpolation_(message, true);
@@ -253,6 +261,7 @@ exports.tokenizeInterpolation = tokenizeInterpolation;
* @param {string|?} message Message, which may be a string that contains
* string table references.
* @return {string} String with message references replaced.
* @alias Blockly.utils.replaceMessageReferences
*/
const replaceMessageReferences = function(message) {
if (typeof message != 'string') {
@@ -271,6 +280,7 @@ exports.replaceMessageReferences = replaceMessageReferences;
* @param {string} message Text which might contain string table references.
* @return {boolean} True if all message references have matching values.
* Otherwise, false.
* @alias Blockly.utils.checkMessageReferences
*/
const checkMessageReferences = function(message) {
let validSoFar = true;
@@ -434,6 +444,7 @@ const tokenizeInterpolation_ = function(message, parseInterpolationTokens) {
* Generate a unique ID.
* @return {string} A globally unique ID string.
* @deprecated Use Blockly.utils.idGenerator.genUid instead.
* @alias Blockly.utils.genUid
*/
const genUid = function() {
deprecation.warn(
@@ -447,6 +458,7 @@ exports.genUid = genUid;
* Check if 3D transforms are supported by adding an element
* and attempting to set the property.
* @return {boolean} True if 3D transforms are supported.
* @alias Blockly.utils.is3dSupported
*/
const is3dSupported = function() {
if (is3dSupported.cached_ !== undefined) {
@@ -498,6 +510,7 @@ exports.is3dSupported = is3dSupported;
* Calls a function after the page has loaded, possibly immediately.
* @param {function()} fn Function to run.
* @throws Error Will throw if no global document can be found (e.g., Node.js).
* @alias Blockly.utils.runAfterPageLoad
*/
const runAfterPageLoad = function(fn) {
if (typeof document != 'object') {
@@ -522,6 +535,7 @@ exports.runAfterPageLoad = runAfterPageLoad;
* scroll into account.
* @return {!Rect} An object containing window width, height, and
* scroll position in window coordinates.
* @alias Blockly.utils.getViewportBBox
*/
const getViewportBBox = function() {
// Pixels, in window coordinates.
@@ -538,6 +552,7 @@ exports.getViewportBBox = getViewportBBox;
* @param {!Array} arr Array from which to remove value.
* @param {*} value Value to remove.
* @return {boolean} True if an element was removed.
* @alias Blockly.utils.arrayRemove
*/
const arrayRemove = function(arr, value) {
const i = arr.indexOf(value);
@@ -554,6 +569,7 @@ exports.arrayRemove = arrayRemove;
* Gets the document scroll distance as a coordinate object.
* Copied from Closure's goog.dom.getDocumentScroll.
* @return {!Coordinate} Object with values 'x' and 'y'.
* @alias Blockly.utils.getDocumentScroll
*/
const getDocumentScroll = function() {
const el = document.documentElement;
@@ -577,6 +593,7 @@ exports.getDocumentScroll = getDocumentScroll;
* statements (blocks that are not inside a value or statement input
* of the block).
* @return {!Object} Map of types to type counts for descendants of the bock.
* @alias Blockly.utils.getBlockTypeCounts
*/
const getBlockTypeCounts = function(block, opt_stripFollowing) {
const typeCountsMap = Object.create(null);
@@ -605,6 +622,7 @@ exports.getBlockTypeCounts = getBlockTypeCounts;
* @param {!Coordinate} screenCoordinates The screen coordinates to
* be converted to workspace coordinates
* @return {!Coordinate} The workspace coordinates.
* @alias Blockly.utils.screenToWsCoordinates
*/
const screenToWsCoordinates = function(ws, screenCoordinates) {
const screenX = screenCoordinates.x;
@@ -644,6 +662,7 @@ exports.screenToWsCoordinates = screenToWsCoordinates;
* @return {{hue: ?number, hex: string}} An object containing the colour as
* a #RRGGBB string, and the hue if the input was an HSV hue value.
* @throws {Error} If the colour cannot be parsed.
* @alias Blockly.utils.parseBlockColour
*/
const parseBlockColour = function(colour) {
const dereferenced =

4
core/utils/aria.js
View File

@@ -29,6 +29,7 @@ const ROLE_ATTRIBUTE = 'role';
* ARIA role values.
* Copied from Closure's goog.a11y.aria.Role
* @enum {string}
* @alias Blockly.utils.aria.Role
*/
const Role = {
// ARIA role for an interactive control of tabular data.
@@ -74,6 +75,7 @@ exports.Role = Role;
* ARIA states and properties.
* Copied from Closure's goog.a11y.aria.State
* @enum {string}
* @alias Blockly.utils.aria.State
*/
const State = {
// ARIA property for setting the currently active descendant of an element,
@@ -143,6 +145,7 @@ exports.State = State;
*
* @param {!Element} element DOM node to set role of.
* @param {!Blockly.utils.aria.Role} roleName Role name.
* @alias Blockly.utils.aria.setRole
*/
const setRole = function(element, roleName) {
element.setAttribute(ROLE_ATTRIBUTE, roleName);
@@ -158,6 +161,7 @@ exports.setRole = setRole;
* not an extra attribute.
* @param {string|boolean|number|!Array<string>} value Value
* for the state attribute.
* @alias Blockly.utils.aria.setState
*/
const setState = function(element, stateName, value) {
if (Array.isArray(value)) {

7
core/utils/colour.js
View File

@@ -31,6 +31,7 @@ const internalConstants = goog.require('Blockly.internalConstants');
* @param {string|number} str Colour in some CSS format.
* @return {?string} A string containing a hex representation of the colour,
* or null if can't be parsed.
* @alias Blockly.utils.colour.parse
*/
const parse = function(str) {
str = String(str).toLowerCase().trim();
@@ -69,6 +70,7 @@ exports.parse = parse;
* @param {number} g Amount of green, int between 0 and 255.
* @param {number} b Amount of blue, int between 0 and 255.
* @return {string} Hex representation of the colour.
* @alias Blockly.utils.colour.rgbToHex
*/
const rgbToHex = function(r, g, b) {
const rgb = (r << 16) | (g << 8) | b;
@@ -84,6 +86,7 @@ exports.rgbToHex = rgbToHex;
* @param {string} colour String representing colour in any
* colour format ('#ff0000', 'red', '0xff000', etc).
* @return {!Array<number>} RGB representation of the colour.
* @alias Blockly.utils.colour.hexToRgb
*/
const hexToRgb = function(colour) {
const hex = parse(colour);
@@ -106,6 +109,7 @@ exports.hexToRgb = hexToRgb;
* @param {number} s Saturation value in [0, 1].
* @param {number} v Brightness in [0, 255].
* @return {string} Hex representation of the colour.
* @alias Blockly.utils.colour.hsvToHex
*/
const hsvToHex = function(h, s, v) {
let red = 0;
@@ -167,6 +171,7 @@ exports.hsvToHex = hsvToHex;
* @param {number} factor The weight to be given to colour1 over colour2.
* Values should be in the range [0, 1].
* @return {?string} Combined colour represented in hex.
* @alias Blockly.utils.colour.blend
*/
const blend = function(colour1, colour2, factor) {
const hex1 = parse(colour1);
@@ -193,6 +198,7 @@ exports.blend = blend;
* while the values are the "hex" values.
*
* @type {!Object<string, string>}
* @alias Blockly.utils.colour.names
*/
const names = {
'aqua': '#00ffff',
@@ -218,6 +224,7 @@ exports.names = names;
* Convert a hue (HSV model) into an RGB hex triplet.
* @param {number} hue Hue on a colour wheel (0-360).
* @return {string} RGB code, e.g. '#5ba65b'.
* @alias Blockly.utils.colour.hueToHex
*/
const hueToHex = function(hue) {
return hsvToHex(

1
core/utils/deprecation.js
View File

@@ -27,6 +27,7 @@ goog.module('Blockly.utils.deprecation');
* deprecation date.
* @param {string=} opt_use The name of a function or property to use instead,
* if any.
* @alias Blockly.utils.deprecation.warn
*/
const warn = function(name, deprecationDate, deletionDate, opt_use) {
let msg = name + ' was deprecated on ' + deprecationDate +

60
core/utils/dom.js
View File

@@ -26,25 +26,32 @@ const userAgent = goog.require('Blockly.utils.userAgent');
/**
* Required name space for SVG elements.
* @const
* @alias Blockly.utils.dom.SVG_NS
*/
const SVG_NS = 'http://www.w3.org/2000/svg';
exports.SVG_NS = SVG_NS;
/**
* Required name space for HTML elements.
* @const
* @alias Blockly.utils.dom.HTML_NS
*/
const HTML_NS = 'http://www.w3.org/1999/xhtml';
exports.HTML_NS = HTML_NS;
/**
* Required name space for XLINK elements.
* @const
* @alias Blockly.utils.dom.XLINK_NS
*/
const XLINK_NS = 'http://www.w3.org/1999/xlink';
exports.XLINK_NS = XLINK_NS;
/**
* Node type constants.
* https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
* @enum {number}
* @alias Blockly.utils.dom.NodeType
*/
const NodeType = {
ELEMENT_NODE: 1,
@@ -52,6 +59,7 @@ const NodeType = {
COMMENT_NODE: 8,
DOCUMENT_POSITION_CONTAINED_BY: 16
};
exports.NodeType = NodeType;
/**
* Temporary cache of text widths.
@@ -82,6 +90,7 @@ let canvasContext = null;
* @return {T} Newly created SVG element. The return type is {!SVGElement} if
* name is a string or a more specific type if it a member of Svg.
* @template T
* @alias Blockly.utils.dom.createSvgElement
*/
const createSvgElement = function(name, attrs, opt_parent) {
const e = /** @type {T} */
@@ -100,6 +109,7 @@ const createSvgElement = function(name, attrs, opt_parent) {
}
return e;
};
exports.createSvgElement = createSvgElement;
/**
* Add a CSS class to a element.
@@ -107,6 +117,7 @@ const createSvgElement = function(name, attrs, opt_parent) {
* @param {!Element} element DOM element to add class to.
* @param {string} className Name of class to add.
* @return {boolean} True if class was added, false if already present.
* @alias Blockly.utils.dom.addClass
*/
const addClass = function(element, className) {
let classes = element.getAttribute('class') || '';
@@ -119,12 +130,14 @@ const addClass = function(element, className) {
element.setAttribute('class', classes + className);
return true;
};
exports.addClass = addClass;
/**
* Removes multiple calsses from an element.
* @param {!Element} element DOM element to remove classes from.
* @param {string} classNames A string of one or multiple class names for an
* element.
* @alias Blockly.utils.dom.removeClasses
*/
const removeClasses = function(element, classNames) {
const classList = classNames.split(' ');
@@ -132,6 +145,7 @@ const removeClasses = function(element, classNames) {
removeClass(element, classList[i]);
}
};
exports.removeClasses = removeClasses;
/**
* Remove a CSS class from a element.
@@ -139,6 +153,7 @@ const removeClasses = function(element, classNames) {
* @param {!Element} element DOM element to remove class from.
* @param {string} className Name of class to remove.
* @return {boolean} True if class was removed, false if never present.
* @alias Blockly.utils.dom.removeClass
*/
const removeClass = function(element, className) {
const classes = element.getAttribute('class');
@@ -159,6 +174,7 @@ const removeClass = function(element, className) {
}
return true;
};
exports.removeClass = removeClass;
/**
* Checks if an element has the specified CSS class.
@@ -166,27 +182,32 @@ const removeClass = function(element, className) {
* @param {!Element} element DOM element to check.
* @param {string} className Name of class to check.
* @return {boolean} True if class exists, false otherwise.
* @alias Blockly.utils.dom.hasClass
*/
const hasClass = function(element, className) {
const classes = element.getAttribute('class');
return (' ' + classes + ' ').indexOf(' ' + className + ' ') != -1;
};
exports.hasClass = hasClass;
/**
* Removes a node from its parent. No-op if not attached to a parent.
* @param {?Node} node The node to remove.
* @return {?Node} The node removed if removed; else, null.
* @alias Blockly.utils.dom.removeNode
*/
// Copied from Closure goog.dom.removeNode
const removeNode = function(node) {
return node && node.parentNode ? node.parentNode.removeChild(node) : null;
};
exports.removeNode = removeNode;
/**
* Insert a node after a reference node.
* Contrast with node.insertBefore function.
* @param {!Element} newNode New element to insert.
* @param {!Element} refNode Existing element to precede new node.
* @alias Blockly.utils.dom.insertAfter
*/
const insertAfter = function(newNode, refNode) {
const siblingNode = refNode.nextSibling;
@@ -200,18 +221,21 @@ const insertAfter = function(newNode, refNode) {
parentNode.appendChild(newNode);
}
};
exports.insertAfter = insertAfter;
/**
* Whether a node contains another node.
* @param {!Node} parent The node that should contain the other node.
* @param {!Node} descendant The node to test presence of.
* @return {boolean} Whether the parent node contains the descendant node.
* @alias Blockly.utils.dom.containsNode
*/
const containsNode = function(parent, descendant) {
return !!(
parent.compareDocumentPosition(descendant) &
NodeType.DOCUMENT_POSITION_CONTAINED_BY);
};
exports.containsNode = containsNode;
/**
* Sets the CSS transform property on an element. This function sets the
@@ -219,15 +243,18 @@ const containsNode = function(parent, descendant) {
* with older browsers. See https://caniuse.com/#feat=transforms2d
* @param {!Element} element Element to which the CSS transform will be applied.
* @param {string} transform The value of the CSS `transform` property.
* @alias Blockly.utils.dom.setCssTransform
*/
const setCssTransform = function(element, transform) {
element.style['transform'] = transform;
element.style['-webkit-transform'] = transform;
};
exports.setCssTransform = setCssTransform;
/**
* Start caching text widths. Every call to this function MUST also call
* stopTextWidthCache. Caches must not survive between execution threads.
* @alias Blockly.utils.dom.startTextWidthCache
*/
const startTextWidthCache = function() {
cacheReference++;
@@ -235,10 +262,12 @@ const startTextWidthCache = function() {
cacheWidths = Object.create(null);
}
};
exports.startTextWidthCache = startTextWidthCache;
/**
* Stop caching field widths. Unless caching was already on when the
* corresponding call to startTextWidthCache was made.
* @alias Blockly.utils.dom.stopTextWidthCache
*/
const stopTextWidthCache = function() {
cacheReference--;
@@ -246,11 +275,13 @@ const stopTextWidthCache = function() {
cacheWidths = null;
}
};
exports.stopTextWidthCache = stopTextWidthCache;
/**
* Gets the width of a text element, caching it in the process.
* @param {!Element} textElement An SVG 'text' element.
* @return {number} Width of element.
* @alias Blockly.utils.dom.getTextWidth
*/
const getTextWidth = function(textElement) {
const key = textElement.textContent + '\n' + textElement.className.baseVal;
@@ -285,6 +316,7 @@ const getTextWidth = function(textElement) {
}
return width;
};
exports.getTextWidth = getTextWidth;
/**
* Gets the width of a text element using a faster method than `getTextWidth`.
@@ -295,12 +327,14 @@ const getTextWidth = function(textElement) {
* @param {string} fontWeight The font weight to use.
* @param {string} fontFamily The font family to use.
* @return {number} Width of element.
* @alias Blockly.utils.dom.getFastTextWidth
*/
const getFastTextWidth = function(
textElement, fontSize, fontWeight, fontFamily) {
return getFastTextWidthWithSizeString(
textElement, fontSize + 'pt', fontWeight, fontFamily);
};
exports.getFastTextWidth = getFastTextWidth;
/**
* Gets the width of a text element using a faster method than `getTextWidth`.
@@ -313,6 +347,7 @@ const getFastTextWidth = function(
* @param {string} fontWeight The font weight to use.
* @param {string} fontFamily The font family to use.
* @return {number} Width of element.
* @alias Blockly.utils.dom.getFastTextWidthWithSizeString
*/
const getFastTextWidthWithSizeString = function(
textElement, fontSize, fontWeight, fontFamily) {
@@ -351,6 +386,7 @@ const getFastTextWidthWithSizeString = function(
}
return width;
};
exports.getFastTextWidthWithSizeString = getFastTextWidthWithSizeString;
/**
* Measure a font's metrics. The height and baseline values.
@@ -359,6 +395,7 @@ const getFastTextWidthWithSizeString = function(
* @param {string} fontWeight The font weight to use.
* @param {string} fontFamily The font family to use.
* @return {{height: number, baseline: number}} Font measurements.
* @alias Blockly.utils.dom.measureFontMetrics
*/
const measureFontMetrics = function(text, fontSize, fontWeight, fontFamily) {
const span = document.createElement('span');
@@ -386,25 +423,4 @@ const measureFontMetrics = function(text, fontSize, fontWeight, fontFamily) {
}
return result;
};
exports = {
SVG_NS,
HTML_NS,
XLINK_NS,
NodeType,
createSvgElement,
addClass,
removeClasses,
removeClass,
hasClass,
removeNode,
insertAfter,
containsNode,
setCssTransform,
startTextWidthCache,
stopTextWidthCache,
getTextWidth,
getFastTextWidth,
getFastTextWidthWithSizeString,
measureFontMetrics,
};
exports.measureFontMetrics = measureFontMetrics;

2
core/utils/idgenerator.js
View File

@@ -39,6 +39,7 @@ let nextId = 0;
* primarily be used for IDs that end up in the DOM.
*
* @return {string} The next unique identifier.
* @alias Blockly.utils.idGenerator.getNextUniqueId
*/
const getNextUniqueId = function() {
return 'blockly-' + (nextId++).toString(36);
@@ -74,6 +75,7 @@ internal.genUid = function() {
* Generate a random unique ID.
* @see internal.genUid
* @return {string} A globally unique ID string.
* @alias Blockly.utils.idGenerator.genUid
*/
const genUid = function() {
return internal.genUid();

1
core/utils/keycodes.js
View File

@@ -28,6 +28,7 @@ goog.module('Blockly.utils.KeyCodes');
* correct for non US keyboard layouts. See comments below.
*
* @enum {number}
* @alias Blockly.utils.KeyCodes
*/
const KeyCodes = {
WIN_KEY_FF_LINUX: 0,

3
core/utils/math.js
View File

@@ -24,6 +24,7 @@ goog.module('Blockly.utils.math');
* Copied from Closure's goog.math.toRadians.
* @param {number} angleDegrees Angle in degrees.
* @return {number} Angle in radians.
* @alias Blockly.utils.math.toRadians
*/
const toRadians = function(angleDegrees) {
return angleDegrees * Math.PI / 180;
@@ -35,6 +36,7 @@ exports.toRadians = toRadians;
* Copied from Closure's goog.math.toDegrees.
* @param {number} angleRadians Angle in radians.
* @return {number} Angle in degrees.
* @alias Blockly.utils.math.toDegrees
*/
const toDegrees = function(angleRadians) {
return angleRadians * 180 / Math.PI;
@@ -47,6 +49,7 @@ exports.toDegrees = toDegrees;
* @param {number} number The number to clamp.
* @param {number} upperBound The desired upper bound.
* @return {number} The clamped number.
* @alias Blockly.utils.math.clamp
*/
const clamp = function(lowerBound, number, upperBound) {
if (upperBound < lowerBound) {

4
core/utils/object.js
View File

@@ -22,6 +22,7 @@ goog.module('Blockly.utils.object');
* @param {!Function} childCtor Child class.
* @param {!Function} parentCtor Parent class.
* @suppress {strictMissingProperties} superClass_ is not defined on Function.
* @alias Blockly.utils.object.inherits
*/
const inherits = function(childCtor, parentCtor) {
// Set a .superClass_ property so that methods can call parent methods
@@ -45,6 +46,7 @@ exports.inherits = inherits;
* Copies all the members of a source object to a target object.
* @param {!Object} target Target.
* @param {!Object} source Source.
* @alias Blockly.utils.object.mixin
*/
const mixin = function(target, source) {
for (const x in source) {
@@ -58,6 +60,7 @@ exports.mixin = mixin;
* @param {!Object} target Target.
* @param {!Object} source Source.
* @return {!Object} The resulting object.
* @alias Blockly.utils.object.deepMerge
*/
const deepMerge = function(target, source) {
for (const x in source) {
@@ -75,6 +78,7 @@ exports.deepMerge = deepMerge;
* Returns an array of a given object's own enumerable property values.
* @param {!Object} obj Object containing values.
* @return {!Array} Array of values.
* @alias Blockly.utils.object.values
*/
const values = function(obj) {
if (Object.values) {

5
core/utils/string.js
View File

@@ -25,6 +25,7 @@ goog.module('Blockly.utils.string');
* @param {string} str The string to check.
* @param {string} prefix A string to look for at the start of `str`.
* @return {boolean} True if `str` begins with `prefix`.
* @alias Blockly.utils.string.startsWith
*/
const startsWith = function(str, prefix) {
return str.lastIndexOf(prefix, 0) == 0;
@@ -35,6 +36,7 @@ exports.startsWith = startsWith;
* Given an array of strings, return the length of the shortest one.
* @param {!Array<string>} array Array of strings.
* @return {number} Length of shortest string.
* @alias Blockly.utils.string.shortestStringLength
*/
const shortestStringLength = function(array) {
if (!array.length) {
@@ -54,6 +56,7 @@ exports.shortestStringLength = shortestStringLength;
* @param {!Array<string>} array Array of strings.
* @param {number=} opt_shortest Length of shortest string.
* @return {number} Length of common prefix.
* @alias Blockly.utils.string.commonWordPrefix
*/
const commonWordPrefix = function(array, opt_shortest) {
if (!array.length) {
@@ -91,6 +94,7 @@ exports.commonWordPrefix = commonWordPrefix;
* @param {!Array<string>} array Array of strings.
* @param {number=} opt_shortest Length of shortest string.
* @return {number} Length of common suffix.
* @alias Blockly.utils.string.commonWordSuffix
*/
const commonWordSuffix = function(array, opt_shortest) {
if (!array.length) {
@@ -127,6 +131,7 @@ exports.commonWordSuffix = commonWordSuffix;
* @param {string} text Text to wrap.
* @param {number} limit Width to wrap each line.
* @return {string} Wrapped text.
* @alias Blockly.utils.string.wrap
*/
const wrap = function(text, limit) {
const lines = text.split('\n');

10
core/utils/style.js
View File

@@ -27,6 +27,7 @@ const Size = goog.require('Blockly.utils.Size');
* Similar to Closure's goog.style.getSize
* @param {!Element} element Element to get size of.
* @return {!Size} Object with width/height properties.
* @alias Blockly.utils.style.getSize
*/
const getSize = function(element) {
if (getStyle(element, 'display') != 'none') {
@@ -94,6 +95,7 @@ const getStyle = function(element, style) {
* @param {!Element} element Element to get style of.
* @param {string} property Property to get (camel-case).
* @return {string} Style value.
* @alias Blockly.utils.style.getComputedStyle
*/
const getComputedStyle = function(element, property) {
if (document.defaultView && document.defaultView.getComputedStyle) {
@@ -118,6 +120,7 @@ exports.getComputedStyle = getComputedStyle;
* @param {!Element} element Element to get style of.
* @param {string} style Property to get (camel-case).
* @return {string} Style value.
* @alias Blockly.utils.style.getCascadedStyle
*/
const getCascadedStyle = function(element, style) {
return /** @type {string} */ (
@@ -130,6 +133,7 @@ exports.getCascadedStyle = getCascadedStyle;
* Similar to Closure's goog.style.getPageOffset
* @param {!Element} el Element to get the page offset for.
* @return {!Coordinate} The page offset.
* @alias Blockly.utils.style.getPageOffset
*/
const getPageOffset = function(el) {
const pos = new Coordinate(0, 0);
@@ -152,6 +156,7 @@ exports.getPageOffset = getPageOffset;
* Calculates the viewport coordinates relative to the document.
* Similar to Closure's goog.style.getViewportPageOffset
* @return {!Coordinate} The page offset of the viewport.
* @alias Blockly.utils.style.getViewportPageOffset
*/
const getViewportPageOffset = function() {
const body = document.body;
@@ -173,6 +178,7 @@ exports.getViewportPageOffset = getViewportPageOffset;
* @param {!Element} el Element to show or hide.
* @param {*} isShown True to render the element in its default style,
* false to disable rendering the element.
* @alias Blockly.utils.style.setElementShown
*/
const setElementShown = function(el, isShown) {
el.style.display = isShown ? '' : 'none';
@@ -185,6 +191,7 @@ exports.setElementShown = setElementShown;
*
* @param {!Element} el The element to test.
* @return {boolean} True for right to left, false for left to right.
* @alias Blockly.utils.style.isRightToLeft
*/
const isRightToLeft = function(el) {
return 'rtl' == getStyle(el, 'direction');
@@ -196,6 +203,7 @@ exports.isRightToLeft = isRightToLeft;
* Copied from Closure's goog.style.getBorderBox
* @param {!Element} element The element to get the border widths for.
* @return {!Object} The computed border widths.
* @alias Blockly.utils.style.getBorderBox
*/
const getBorderBox = function(element) {
const left = getComputedStyle(element, 'borderLeftWidth');
@@ -224,6 +232,7 @@ exports.getBorderBox = getBorderBox;
* document scroll element will be used.
* @param {boolean=} opt_center Whether to center the element in the container.
* Defaults to false.
* @alias Blockly.utils.style.scrollIntoContainerView
*/
const scrollIntoContainerView = function(element, container, opt_center) {
const offset = getContainerOffsetToScrollInto(element, container, opt_center);
@@ -246,6 +255,7 @@ exports.scrollIntoContainerView = scrollIntoContainerView;
* Defaults to false.
* @return {!Coordinate} The new scroll position of the container,
* in form of goog.math.Coordinate(scrollLeft, scrollTop).
* @alias Blockly.utils.style.getContainerOffsetToScrollInto
*/
const getContainerOffsetToScrollInto = function(element, container, opt_center) {
// Absolute position of the element's border's top left corner.

8
core/utils/svg_paths.js
View File

@@ -26,6 +26,7 @@ goog.module('Blockly.utils.svgPaths');
* @param {number} x The x coordinate.
* @param {number} y The y coordinate.
* @return {string} A string of the format ' x,y '
* @alias Blockly.utils.svgPaths.point
*/
const point = function(x, y) {
return ' ' + x + ',' + y + ' ';
@@ -43,6 +44,7 @@ exports.point = point;
* the format ' x, y '.
* @return {string} A string defining one or more Bezier curves. See the MDN
* documentation for exact format.
* @alias Blockly.utils.svgPaths.curve
*/
const curve = function(command, points) {
return ' ' + command + points.join('');
@@ -57,6 +59,7 @@ exports.curve = curve;
* @param {number} x The absolute x coordinate.
* @param {number} y The absolute y coordinate.
* @return {string} A string of the format ' M x,y '
* @alias Blockly.utils.svgPaths.moveTo
*/
const moveTo = function(x, y) {
return ' M ' + x + ',' + y + ' ';
@@ -71,6 +74,7 @@ exports.moveTo = moveTo;
* @param {number} dx The relative x coordinate.
* @param {number} dy The relative y coordinate.
* @return {string} A string of the format ' m dx,dy '
* @alias Blockly.utils.svgPaths.moveBy
*/
const moveBy = function(dx, dy) {
return ' m ' + dx + ',' + dy + ' ';
@@ -85,6 +89,7 @@ exports.moveBy = moveBy;
* @param {number} dx The relative x coordinate.
* @param {number} dy The relative y coordinate.
* @return {string} A string of the format ' l dx,dy '
* @alias Blockly.utils.svgPaths.lineTo
*/
const lineTo = function(dx, dy) {
return ' l ' + dx + ',' + dy + ' ';
@@ -100,6 +105,7 @@ exports.lineTo = lineTo;
* draw lines to, in order. The points are represented as strings of the
* format ' dx,dy '.
* @return {string} A string of the format ' l (dx,dy)+ '
* @alias Blockly.utils.svgPaths.line
*/
const line = function(points) {
return ' l' + points.join('');
@@ -117,6 +123,7 @@ exports.line = line;
* @param {number} val The coordinate to pass to the command. It may be
* absolute or relative.
* @return {string} A string of the format ' command val '
* @alias Blockly.utils.svgPaths.lineOnAxis
*/
const lineOnAxis = function(command, val) {
return ' ' + command + ' ' + val + ' ';
@@ -135,6 +142,7 @@ exports.lineOnAxis = lineOnAxis;
* specified either in absolute or relative coordinates depending on the
* command.
* @return {string} A string of the format 'command radius radius flags point'
* @alias Blockly.utils.svgPaths.arc
*/
const arc = function(command, flags, radius, point) {
return command + ' ' + radius + ' ' + radius + ' ' + flags + point;

20
core/utils/toolbox.js
View File

@@ -47,6 +47,7 @@ const userAgent = goog.require('Blockly.utils.userAgent');
* inputs: (!Object<string, !ConnectionState>|undefined),
* next: (!ConnectionState|undefined)
* }}
* @alias Blockly.utils.toolbox.BlockInfo
*/
let BlockInfo;
exports.BlockInfo = BlockInfo;
@@ -59,6 +60,7 @@ exports.BlockInfo = BlockInfo;
* gap:(number|undefined),
* cssconfig:(!ToolboxSeparator.CssConfig|undefined)
* }}
* @alias Blockly.utils.toolbox.SeparatorInfo
*/
let SeparatorInfo;
exports.SeparatorInfo = SeparatorInfo;
@@ -70,6 +72,7 @@ exports.SeparatorInfo = SeparatorInfo;
* text:string,
* callbackkey:string
* }}
* @alias Blockly.utils.toolbox.ButtonInfo
*/
let ButtonInfo;
exports.ButtonInfo = ButtonInfo;
@@ -81,6 +84,7 @@ exports.ButtonInfo = ButtonInfo;
* text:string,
* id:(string|undefined)
* }}
* @alias Blockly.utils.toolbox.LabelInfo
*/
let LabelInfo;
exports.LabelInfo = LabelInfo;
@@ -89,6 +93,7 @@ exports.LabelInfo = LabelInfo;
* The information needed to create either a button or a label in the flyout.
* @typedef {ButtonInfo|
* LabelInfo}
* @alias Blockly.utils.toolbox.ButtonOrLabelInfo
*/
let ButtonOrLabelInfo;
exports.ButtonOrLabelInfo = ButtonOrLabelInfo;
@@ -105,6 +110,7 @@ exports.ButtonOrLabelInfo = ButtonOrLabelInfo;
* cssconfig:(!ToolboxCategory.CssConfig|undefined),
* hidden:(string|undefined)
* }}
* @alias Blockly.utils.toolbox.StaticCategoryInfo
*/
let StaticCategoryInfo;
exports.StaticCategoryInfo = StaticCategoryInfo;
@@ -120,6 +126,7 @@ exports.StaticCategoryInfo = StaticCategoryInfo;
* cssconfig:(!ToolboxCategory.CssConfig|undefined),
* hidden:(string|undefined)
* }}
* @alias Blockly.utils.toolbox.DynamicCategoryInfo
*/
let DynamicCategoryInfo;
exports.DynamicCategoryInfo = DynamicCategoryInfo;
@@ -128,6 +135,7 @@ exports.DynamicCategoryInfo = DynamicCategoryInfo;
* The information needed to create either a dynamic or static category.
* @typedef {StaticCategoryInfo|
* DynamicCategoryInfo}
* @alias Blockly.utils.toolbox.CategoryInfo
*/
let CategoryInfo;
exports.CategoryInfo = CategoryInfo;
@@ -136,6 +144,7 @@ exports.CategoryInfo = CategoryInfo;
* Any information that can be used to create an item in the toolbox.
* @typedef {FlyoutItemInfo|
* StaticCategoryInfo}
* @alias Blockly.utils.toolbox.ToolboxItemInfo
*/
let ToolboxItemInfo;
exports.ToolboxItemInfo = ToolboxItemInfo;
@@ -147,6 +156,7 @@ exports.ToolboxItemInfo = ToolboxItemInfo;
* ButtonInfo|
* LabelInfo|
* DynamicCategoryInfo}
* @alias Blockly.utils.toolbox.FlyoutItemInfo
*/
let FlyoutItemInfo;
exports.FlyoutItemInfo = FlyoutItemInfo;
@@ -157,6 +167,7 @@ exports.FlyoutItemInfo = FlyoutItemInfo;
* kind:(string|undefined),
* contents:!Array<!ToolboxItemInfo>
* }}
* @alias Blockly.utils.toolbox.ToolboxInfo
*/
let ToolboxInfo;
exports.ToolboxInfo = ToolboxInfo;
@@ -166,6 +177,7 @@ exports.ToolboxInfo = ToolboxInfo;
* @typedef {
* Array<!FlyoutItemInfo>
* }
* @alias Blockly.utils.toolbox.FlyoutItemInfoArray
*/
let FlyoutItemInfoArray;
exports.FlyoutItemInfoArray = FlyoutItemInfoArray;
@@ -175,6 +187,7 @@ exports.FlyoutItemInfoArray = FlyoutItemInfoArray;
* @typedef {Node|
* ToolboxInfo|
* string}
* @alias Blockly.utils.toolbox.ToolboxDefinition
*/
let ToolboxDefinition;
exports.ToolboxDefinition = ToolboxDefinition;
@@ -185,6 +198,7 @@ exports.ToolboxDefinition = ToolboxDefinition;
* NodeList|
* ToolboxInfo|
* Array<!Node>}
* @alias Blockly.utils.toolbox.FlyoutDefinition
*/
let FlyoutDefinition;
exports.FlyoutDefinition = FlyoutDefinition;
@@ -208,6 +222,7 @@ const FLYOUT_TOOLBOX_KIND = 'flyoutToolbox';
/**
* Position of the toolbox and/or flyout relative to the workspace.
* @enum {number}
* @alias Blockly.utils.toolbox.Position
*/
const Position = {
TOP: 0,
@@ -223,6 +238,7 @@ exports.Position = Position;
* of the toolbox in one of its many forms.
* @return {?ToolboxInfo} Object holding information
* for creating a toolbox.
* @alias Blockly.utils.toolbox.convertToolboxDefToJson
*/
const convertToolboxDefToJson = function(toolboxDef) {
if (!toolboxDef) {
@@ -270,6 +286,7 @@ const validateToolbox = function(toolboxJson) {
* @param {?FlyoutDefinition} flyoutDef The definition of
* the flyout in one of its many forms.
* @return {!FlyoutItemInfoArray} A list of flyout items.
* @alias Blockly.utils.toolbox.convertFlyoutDefToJsonArray
*/
const convertFlyoutDefToJsonArray = function(flyoutDef) {
if (!flyoutDef) {
@@ -296,6 +313,7 @@ exports.convertFlyoutDefToJsonArray = convertFlyoutDefToJsonArray;
* @param {?ToolboxInfo} toolboxJson Object holding
* information for creating a toolbox.
* @return {boolean} True if the toolbox has categories.
* @alias Blockly.utils.toolbox.hasCategories
*/
const hasCategories = function(toolboxJson) {
if (!toolboxJson) {
@@ -320,6 +338,7 @@ exports.hasCategories = hasCategories;
* @param {!CategoryInfo} categoryInfo Object holing
* information for creating a category.
* @return {boolean} True if the category has subcategories.
* @alias Blockly.utils.toolbox.isCategoryCollapsible
*/
const isCategoryCollapsible = function(categoryInfo) {
if (!categoryInfo || !categoryInfo['contents']) {
@@ -412,6 +431,7 @@ const addAttributes = function(node, obj) {
* @param {?Node|?string} toolboxDef DOM tree of blocks, or text representation
* of same.
* @return {?Node} DOM tree of blocks, or null.
* @alias Blockly.utils.toolbox.parseToolboxTree
*/
const parseToolboxTree = function(toolboxDef) {
if (toolboxDef) {

56
core/utils/useragent.js
View File

@@ -111,44 +111,72 @@ isTablet = isIPad || (isAndroid && !has('Mobile')) || has('Silk');
isMobile = !isTablet && (isIPod || isIPhone || isAndroid || has('IEMobile'));
})((globalThis['navigator'] && globalThis['navigator']['userAgent']) || '');
/** @const {string} */
/** @const {string}
* @alias Blockly.utils.userAgent.raw
*/
exports.raw = rawUserAgent;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.IE
*/
exports.IE = isIe;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.EDGE
*/
exports.EDGE = isEdge;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.JavaFx
*/
exports.JavaFx = isJavaFx;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.CHROME
*/
exports.CHROME = isChrome;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.WEBKIT
*/
exports.WEBKIT = isWebKit;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.GECKO
*/
exports.GECKO = isGecko;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.ANDROID
*/
exports.ANDROID = isAndroid;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.IPAD
*/
exports.IPAD = isIPad;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.IPOD
*/
exports.IPOD = isIPod;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.IPHONE
*/
exports.IPHONE = isIPhone;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.MAC
*/
exports.MAC = isMac;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.TABLET
*/
exports.TABLET = isTablet;
/** @const {boolean} */
/** @const {boolean}
* @alias Blockly.utils.userAgent.MOBILE
*/
exports.MOBILE = isMobile;

7
core/utils/xml.js
View File

@@ -23,6 +23,7 @@ const {globalThis} = goog.require('Blockly.utils.global');
/**
* Namespace for Blockly's XML.
* @alias Blockly.utils.xml.NAME_SPACE
*/
const NAME_SPACE = 'https://developers.google.com/blockly/xml';
exports.NAME_SPACE = NAME_SPACE;
@@ -39,6 +40,7 @@ let xmlDocument = globalThis.document;
/**
* Get the document object to use for XML serialization.
* @return {!Document} The document object.
* @alias Blockly.utils.xml.getDocument
*/
const getDocument = function() {
return xmlDocument;
@@ -48,6 +50,7 @@ exports.getDocument = getDocument;
/**
* Get the document object to use for XML serialization.
* @param {!Document} document The document object to use.
* @alias Blockly.utils.xml.setDocument
*/
const setDocument = function(document) {
xmlDocument = document;
@@ -58,6 +61,7 @@ exports.setDocument = setDocument;
* Create DOM element for XML.
* @param {string} tagName Name of DOM element.
* @return {!Element} New DOM element.
* @alias Blockly.utils.xml.createElement
*/
const createElement = function(tagName) {
return xmlDocument.createElementNS(NAME_SPACE, tagName);
@@ -68,6 +72,7 @@ exports.createElement = createElement;
* Create text element for XML.
* @param {string} text Text content.
* @return {!Text} New DOM text node.
* @alias Blockly.utils.xml.createTextNode
*/
const createTextNode = function(text) {
return xmlDocument.createTextNode(text);
@@ -79,6 +84,7 @@ exports.createTextNode = createTextNode;
* @param {string} text XML string.
* @return {Document} The DOM document.
* @throws if XML doesn't parse.
* @alias Blockly.utils.xml.textToDomDocument
*/
const textToDomDocument = function(text) {
const oParser = new DOMParser();
@@ -91,6 +97,7 @@ exports.textToDomDocument = textToDomDocument;
* Currently the text format is fairly ugly: all one line with no whitespace.
* @param {!Node} dom A tree of XML nodes.
* @return {string} Text representation.
* @alias Blockly.utils.xml.domToText
*/
const domToText = function(dom) {
const oSerializer = new XMLSerializer();

20
core/variables.js
View File

@@ -34,6 +34,7 @@ const utilsXml = goog.require('Blockly.utils.xml');
* call Workspace.getAllVariables.
* @param {!Workspace} ws The workspace to search for variables.
* @return {!Array<!VariableModel>} Array of variable models.
* @alias Blockly.Variables.allUsedVarModels
*/
const allUsedVarModels = function(ws) {
const blocks = ws.getAllBlocks(false);
@@ -74,6 +75,7 @@ const ALL_DEVELOPER_VARS_WARNINGS_BY_BLOCK_TYPE = {};
* For use by generators.
* @param {!Workspace} workspace The workspace to search.
* @return {!Array<string>} A list of non-duplicated variable names.
* @alias Blockly.Variables.allDeveloperVariables
*/
const allDeveloperVariables = function(workspace) {
const blocks = workspace.getAllBlocks(false);
@@ -109,6 +111,7 @@ exports.allDeveloperVariables = allDeveloperVariables;
* variable category.
* @param {!Workspace} workspace The workspace containing variables.
* @return {!Array<!Element>} Array of XML elements.
* @alias Blockly.Variables.flyoutCategory
*/
const flyoutCategory = function(workspace) {
let xmlList = [];
@@ -132,6 +135,7 @@ exports.flyoutCategory = flyoutCategory;
* Construct the blocks required by the flyout for the variable category.
* @param {!Workspace} workspace The workspace containing variables.
* @return {!Array<!Element>} Array of XML block elements.
* @alias Blockly.Variables.flyoutCategoryBlocks
*/
const flyoutCategoryBlocks = function(workspace) {
const variableModelList = workspace.getVariablesOfType('');
@@ -177,6 +181,9 @@ const flyoutCategoryBlocks = function(workspace) {
};
exports.flyoutCategoryBlocks = flyoutCategoryBlocks;
/**
* @alias Blockly.Variables.VAR_LETTER_OPTIONS
*/
const VAR_LETTER_OPTIONS = 'ijkmnopqrstuvwxyzabcdefgh'; // No 'l'.
exports.VAR_LETTER_OPTIONS = VAR_LETTER_OPTIONS;
@@ -187,11 +194,13 @@ exports.VAR_LETTER_OPTIONS = VAR_LETTER_OPTIONS;
* then 'i2' to 'z2' etc. Skip 'l'.
* @param {!Workspace} workspace The workspace to be unique in.
* @return {string} New variable name.
* @alias Blockly.Variables.generateUniqueName
*/
exports.generateUniqueName = function(workspace) {
const generateUniqueName = function(workspace) {
return generateUniqueNameFromOptions(
VAR_LETTER_OPTIONS.charAt(0), workspace.getAllVariableNames());
};
exports.generateUniqueName = generateUniqueName;
/**
* Returns a unique name that is not present in the usedNames array. This
@@ -200,6 +209,7 @@ exports.generateUniqueName = function(workspace) {
* @param {string} startChar The character to start the search at.
* @param {!Array<string>} usedNames A list of all of the used names.
* @return {string} A unique name that is not present in the usedNames array.
* @alias Blockly.Variables.generateUniqueNameFromOptions
*/
const generateUniqueNameFromOptions = function(startChar, usedNames) {
if (!usedNames.length) {
@@ -251,6 +261,7 @@ exports.generateUniqueNameFromOptions = generateUniqueNameFromOptions;
* button), or undefined if an existing variable was chosen.
* @param {string=} opt_type The type of the variable like 'int', 'string', or
* ''. This will default to '', which is a specific type.
* @alias Blockly.Variables.createVariableButtonHandler
*/
const createVariableButtonHandler = function(
workspace, opt_callback, opt_type) {
@@ -300,6 +311,7 @@ exports.createVariableButtonHandler = createVariableButtonHandler;
* @param {function(?string=)=} opt_callback A callback. It will
* be passed an acceptable new variable name, or null if change is to be
* aborted (cancel button), or undefined if an existing variable was chosen.
* @alias Blockly.Variables.renameVariable
*/
const renameVariable = function(workspace, variable, opt_callback) {
// This function needs to be named so it can be called recursively.
@@ -341,6 +353,7 @@ exports.renameVariable = renameVariable;
* @param {string} defaultText The default value to show in the prompt's field.
* @param {function(?string)} callback A callback. It will return the new
* variable name, or null if the user picked something illegal.
* @alias Blockly.Variables.promptName
*/
const promptName = function(promptText, defaultText, callback) {
dialog.prompt(promptText, defaultText, function(newVar) {
@@ -387,6 +400,7 @@ const nameUsedWithOtherType = function(name, type, workspace) {
* variable.
* @return {?VariableModel} The variable with the given name,
* or null if none was found.
* @alias Blockly.Variables.nameUsedWithAnyType
*/
const nameUsedWithAnyType = function(name, workspace) {
const allVariables = workspace.getVariableMap().getAllVariables();
@@ -406,6 +420,7 @@ exports.nameUsedWithAnyType = nameUsedWithAnyType;
* @param {!VariableModel} variableModel The variable model to
* represent.
* @return {?Element} The generated DOM.
* @alias Blockly.Variables.generateVariableFieldDom
*/
const generateVariableFieldDom = function(variableModel) {
/* Generates the following XML:
@@ -432,6 +447,7 @@ exports.generateVariableFieldDom = generateVariableFieldDom;
* @param {string=} opt_type The type to use to look up or create the variable.
* @return {!VariableModel} The variable corresponding to the given ID
* or name + type combination.
* @alias Blockly.Variables.getOrCreateVariablePackage
*/
const getOrCreateVariablePackage = function(workspace, id, opt_name, opt_type) {
let variable = getVariable(workspace, id, opt_name, opt_type);
@@ -455,6 +471,7 @@ exports.getOrCreateVariablePackage = getOrCreateVariablePackage;
* Only used if lookup by ID fails.
* @return {?VariableModel} The variable corresponding to the given ID
* or name + type combination, or null if not found.
* @alias Blockly.Variables.getVariable
*/
const getVariable = function(workspace, id, opt_name, opt_type) {
const potentialVariableMap = workspace.getPotentialVariableMap();
@@ -524,6 +541,7 @@ const createVariable = function(workspace, id, opt_name, opt_type) {
* @return {!Array<!VariableModel>} The new array of variables that
* were freshly added to the workspace after creating the new block,
* or [] if no new variables were added to the workspace.
* @alias Blockly.Variables.getAddedVariables
*/
const getAddedVariables = function(workspace, originalVariables) {
const allCurrentVariables = workspace.getAllVariables();

8
core/widgetdiv.js
View File

@@ -57,6 +57,7 @@ let themeClassName = '';
/**
* The HTML container for popup overlays (e.g. editor widgets).
* @type {?Element}
* @alias Blockly.WidgetDiv.DIV
*/
let DIV;
/** @deprecated September 2021 */
@@ -65,6 +66,7 @@ exports.DIV = DIV;
/**
* Returns the HTML container for editor widgets.
* @return {?Element} The editor widget container.
* @alias Blockly.WidgetDiv.getDiv
*/
const getDiv = function() {
return DIV;
@@ -93,6 +95,7 @@ Object.defineProperties(exports, {
/**
* Create the widget div and inject it onto the page.
* @alias Blockly.WidgetDiv.createDom
*/
const createDom = function() {
if (DIV) {
@@ -112,6 +115,7 @@ exports.createDom = createDom;
* @param {boolean} rtl Right-to-left (true) or left-to-right (false).
* @param {Function} newDispose Optional cleanup function to be run when the
* widget is closed.
* @alias Blocky.WidgetDiv.show
*/
const show = function(newOwner, rtl, newDispose) {
hide();
@@ -131,6 +135,7 @@ exports.show = show;
/**
* Destroy the widget and hide the div.
* @alias Blockly.WidgetDiv.hide
*/
const hide = function() {
if (!isVisible()) {
@@ -161,6 +166,7 @@ exports.hide = hide;
/**
* Is the container visible?
* @return {boolean} True if visible.
* @alias Blockly.WidgetDiv.isVisible
*/
const isVisible = function() {
return !!owner;
@@ -171,6 +177,7 @@ exports.isVisible = isVisible;
* Destroy the widget and hide the div if it is being used by the specified
* object.
* @param {!Object} oldOwner The object that was using this container.
* @alias Blockly.WidgetDiv.hideIfOwner
*/
const hideIfOwner = function(oldOwner) {
if (owner == oldOwner) {
@@ -205,6 +212,7 @@ const positionInternal = function(x, y, height) {
* the widget div, in window coordinates.
* @param {boolean} rtl Whether the workspace is in RTL mode. This determines
* horizontal alignment.
* @alias Blockly.WidgetDiv.positionWithAnchor
*/
const positionWithAnchor = function(viewportBBox, anchorBBox, widgetSize, rtl) {
const y = calculateY(viewportBBox, anchorBBox, widgetSize);