diff --git a/core/blockly.js b/core/blockly.js index fe0c3021ab0..ffb8fa47dd4 100644 --- a/core/blockly.js +++ b/core/blockly.js @@ -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} 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; diff --git a/core/css.js b/core/css.js index 6f34e6c0d83..519feac0925 100644 --- a/core/css.js +++ b/core/css.js @@ -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} 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 { diff --git a/core/events/events.js b/core/events/events.js index 996391ee8ad..4c88f1c0356 100644 --- a/core/events/events.js +++ b/core/events/events.js @@ -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} queueIn Array of events. * @param {boolean} forward True if forward (redo), false if backward (undo). * @return {!Array} 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} 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) { diff --git a/core/extensions.js b/core/extensions.js index ef4e59bf440..f956bfed56f 100644 --- a/core/extensions.js +++ b/core/extensions.js @@ -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=} 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} 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. diff --git a/core/procedures.js b/core/procedures.js index dbde96688cb..eec3484fd3b 100644 --- a/core/procedures.js +++ b/core/procedures.js @@ -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} 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} 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 diff --git a/core/serialization/priorities.js b/core/serialization/priorities.js index 3535d518577..66efb03fd0b 100644 --- a/core/serialization/priorities.js +++ b/core/serialization/priorities.js @@ -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; diff --git a/core/tooltip.js b/core/tooltip.js index b4f99de32ae..d0335556b24 100644 --- a/core/tooltip.js +++ b/core/tooltip.js @@ -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; diff --git a/core/utils.js b/core/utils.js index d618a90e4d7..2c80c6b0811 100644 --- a/core/utils.js +++ b/core/utils.js @@ -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} 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 = diff --git a/core/utils/aria.js b/core/utils/aria.js index 6d927411704..583f517866b 100644 --- a/core/utils/aria.js +++ b/core/utils/aria.js @@ -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} value Value * for the state attribute. + * @alias Blockly.utils.aria.setState */ const setState = function(element, stateName, value) { if (Array.isArray(value)) { diff --git a/core/utils/colour.js b/core/utils/colour.js index acdc18a8c26..b1269031643 100644 --- a/core/utils/colour.js +++ b/core/utils/colour.js @@ -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} 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} + * @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( diff --git a/core/utils/deprecation.js b/core/utils/deprecation.js index 4edfef9a439..a6dc9b85145 100644 --- a/core/utils/deprecation.js +++ b/core/utils/deprecation.js @@ -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 + diff --git a/core/utils/dom.js b/core/utils/dom.js index f22a1a45865..f9e5f409f23 100644 --- a/core/utils/dom.js +++ b/core/utils/dom.js @@ -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; diff --git a/core/utils/idgenerator.js b/core/utils/idgenerator.js index 5c8c61b0803..fcd04abc13c 100644 --- a/core/utils/idgenerator.js +++ b/core/utils/idgenerator.js @@ -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(); diff --git a/core/utils/keycodes.js b/core/utils/keycodes.js index 1501fa2ac88..ce7beed2925 100644 --- a/core/utils/keycodes.js +++ b/core/utils/keycodes.js @@ -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, diff --git a/core/utils/math.js b/core/utils/math.js index c54f6fb0f0b..7140ae89356 100644 --- a/core/utils/math.js +++ b/core/utils/math.js @@ -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) { diff --git a/core/utils/object.js b/core/utils/object.js index bb56d11fd70..3e179583960 100644 --- a/core/utils/object.js +++ b/core/utils/object.js @@ -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) { diff --git a/core/utils/string.js b/core/utils/string.js index f65673f098e..f283b982f9a 100644 --- a/core/utils/string.js +++ b/core/utils/string.js @@ -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} 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} 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} 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'); diff --git a/core/utils/style.js b/core/utils/style.js index 13d05e752f4..fac432edba8 100644 --- a/core/utils/style.js +++ b/core/utils/style.js @@ -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. diff --git a/core/utils/svg_paths.js b/core/utils/svg_paths.js index a1f9bf2e855..bf4c1b2ca2f 100644 --- a/core/utils/svg_paths.js +++ b/core/utils/svg_paths.js @@ -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; diff --git a/core/utils/toolbox.js b/core/utils/toolbox.js index 3c26205b865..0be8b17154b 100644 --- a/core/utils/toolbox.js +++ b/core/utils/toolbox.js @@ -47,6 +47,7 @@ const userAgent = goog.require('Blockly.utils.userAgent'); * inputs: (!Object|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 * }} + * @alias Blockly.utils.toolbox.ToolboxInfo */ let ToolboxInfo; exports.ToolboxInfo = ToolboxInfo; @@ -166,6 +177,7 @@ exports.ToolboxInfo = ToolboxInfo; * @typedef { * Array * } + * @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} + * @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) { diff --git a/core/utils/useragent.js b/core/utils/useragent.js index ab7cf1480cd..ca78461eb5e 100644 --- a/core/utils/useragent.js +++ b/core/utils/useragent.js @@ -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; diff --git a/core/utils/xml.js b/core/utils/xml.js index af3043de2a9..b43ac093017 100644 --- a/core/utils/xml.js +++ b/core/utils/xml.js @@ -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(); diff --git a/core/variables.js b/core/variables.js index 311ea8ea9eb..575793105ad 100644 --- a/core/variables.js +++ b/core/variables.js @@ -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} 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} 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} 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} 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} 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} 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(); diff --git a/core/widgetdiv.js b/core/widgetdiv.js index c3bd46ccaf1..fabd521afce 100644 --- a/core/widgetdiv.js +++ b/core/widgetdiv.js @@ -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);