/** * @license * Visual Blocks Editor * * Copyright 2012 Google Inc. * https://developers.google.com/blockly/ * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @fileoverview Utility functions for handling variables. * @author fraser@google.com (Neil Fraser) */ 'use strict'; /** * @name Blockly.Variables * @namespace **/ goog.provide('Blockly.Variables'); goog.require('Blockly.Blocks'); goog.require('Blockly.constants'); goog.require('Blockly.VariableModel'); goog.require('Blockly.Workspace'); goog.require('goog.string'); /** * Constant to separate variable names from procedures and generated functions * when running generators. * @deprecated Use Blockly.VARIABLE_CATEGORY_NAME */ Blockly.Variables.NAME_TYPE = Blockly.VARIABLE_CATEGORY_NAME; /** * Find all user-created variables that are in use in the workspace. * For use by generators. * @param {!Blockly.Block|!Blockly.Workspace} root Root block or workspace. * @return {!Array.<string>} Array of variable names. */ Blockly.Variables.allUsedVariables = function(root) { var blocks; if (root instanceof Blockly.Block) { // Root is Block. blocks = root.getDescendants(); } else if (root instanceof Blockly.Workspace || root instanceof Blockly.WorkspaceSvg) { // Root is Workspace. blocks = root.getAllBlocks(); } else { throw 'Not Block or Workspace: ' + root; } var ignorableName = Blockly.Variables.noVariableText(); var variableHash = Object.create(null); // Iterate through every block and add each variable to the hash. for (var x = 0; x < blocks.length; x++) { var blockVariables = blocks[x].getVars(); if (blockVariables) { for (var y = 0; y < blockVariables.length; y++) { var varName = blockVariables[y]; // Variable name may be null if the block is only half-built. if (varName && varName.toLowerCase() != ignorableName) { variableHash[varName.toLowerCase()] = varName; } } } } // Flatten the hash into a list. var variableList = []; for (var name in variableHash) { variableList.push(variableHash[name]); } return variableList; }; /** * Find all variables that the user has created through the workspace or * toolbox. For use by generators. * @param {!Blockly.Workspace} root The workspace to inspect. * @return {!Array.<Blockly.VariableModel>} Array of variable models. */ Blockly.Variables.allVariables = function(root) { if (root instanceof Blockly.Block) { // Root is Block. console.warn('Deprecated call to Blockly.Variables.allVariables ' + 'with a block instead of a workspace. You may want ' + 'Blockly.Variables.allUsedVariables'); return {}; } return root.getAllVariables(); }; /** * Return the text that should be used in a field_variable or * field_variable_getter when no variable exists. * TODO: #572 * @return {string} The text to display. */ Blockly.Variables.noVariableText = function() { return "No variable selected"; }; /** * Return a new variable name that is not yet being used. This will try to * generate single letter variable names in the range 'i' to 'z' to start with. * If no unique name is located it will try 'i' to 'z', 'a' to 'h', * then 'i2' to 'z2' etc. Skip 'l'. * @param {!Blockly.Workspace} workspace The workspace to be unique in. * @return {string} New variable name. */ Blockly.Variables.generateUniqueName = function(workspace) { var variableList = workspace.getAllVariables(); var newName = ''; if (variableList.length) { var nameSuffix = 1; var letters = 'ijkmnopqrstuvwxyzabcdefgh'; // No 'l'. var letterIndex = 0; var potName = letters.charAt(letterIndex); while (!newName) { var inUse = false; for (var i = 0; i < variableList.length; i++) { if (variableList[i].name.toLowerCase() == potName) { // This potential name is already used. inUse = true; break; } } if (inUse) { // Try the next potential name. letterIndex++; if (letterIndex == letters.length) { // Reached the end of the character sequence so back to 'i'. // a new suffix. letterIndex = 0; nameSuffix++; } potName = letters.charAt(letterIndex); if (nameSuffix > 1) { potName += nameSuffix; } } else { // We can use the current potential name. newName = potName; } } } else { newName = 'i'; } return newName; }; /** * Create a new variable on the given workspace. * @param {!Blockly.Workspace} workspace The workspace on which to create the * variable. * @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. * @param {string} opt_type Optional type of variable, like 'string' or 'list'. */ Blockly.Variables.createVariable = function(workspace, opt_callback, opt_type) { // Decide on a modal message based on the opt_type. If opt_type was not // provided, default to the original message for scalar variables. var newMsg = ''; var modalTitle = ''; if (opt_type === Blockly.LIST_VARIABLE_TYPE) { newMsg = Blockly.Msg.NEW_LIST_TITLE; modalTitle = Blockly.Msg.LIST_MODAL_TITLE; } else if (opt_type === Blockly.BROADCAST_MESSAGE_VARIABLE_TYPE) { newMsg = Blockly.Msg.NEW_BROADCAST_MESSAGE_TITLE; modalTitle = Blockly.Msg.BROADCAST_MODAL_TITLE; } else { newMsg = Blockly.Msg.NEW_VARIABLE_TITLE; modalTitle = Blockly.Msg.VARIABLE_MODAL_TITLE; } // This function needs to be named so it can be called recursively. var promptAndCheckWithAlert = function(defaultName) { Blockly.Variables.promptName(newMsg, defaultName, function(text) { if (text) { // TODO (#1245) use separate namespaces for lists, variables, and // broadcast messages if (workspace.getVariable(text)) { Blockly.alert(Blockly.Msg.VARIABLE_ALREADY_EXISTS.replace('%1', text.toLowerCase()), function() { promptAndCheckWithAlert(text); // Recurse }); } else if (!Blockly.Procedures.isNameUsed(text, workspace)) { Blockly.alert(Blockly.Msg.PROCEDURE_ALREADY_EXISTS.replace('%1', text.toLowerCase()), function() { promptAndCheckWithAlert(text); // Recurse }); } else { var variable = workspace.createVariable(text, opt_type); var flyout = workspace.getFlyout(); var variableBlockId = variable.getId(); if (flyout.setCheckboxState) { flyout.setCheckboxState(variableBlockId, true); } if (opt_callback) { opt_callback(text); } } } else { // User canceled prompt without a value. if (opt_callback) { opt_callback(null); } } }, opt_type, modalTitle); }; promptAndCheckWithAlert(''); }; /** * Rename a variable with the given workspace, variableType, and oldName. * @param {!Blockly.Workspace} workspace The workspace on which to rename the * variable. * @param {?Blockly.VariableModel} variable Variable to rename. * @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. */ Blockly.Variables.renameVariable = function(workspace, variable, opt_callback) { // (karishma) TODO (#1244) Modal message should change depending on what type // of variable is getting renamed. // This function needs to be named so it can be called recursively. var promptAndCheckWithAlert = function(defaultName) { Blockly.Variables.promptName( Blockly.Msg.RENAME_VARIABLE_TITLE.replace('%1', variable.name), defaultName, function(newName) { if (newName) { var newVariable = workspace.getVariable(newName); // TODO (#1245) use separate namespaces for lists, variables, and // broadcast messages if (newVariable && newVariable.type != variable.type) { Blockly.alert(Blockly.Msg.VARIABLE_ALREADY_EXISTS_FOR_ANOTHER_TYPE.replace('%1', newName.toLowerCase()).replace('%2', newVariable.type), function() { promptAndCheckWithAlert(newName); // Recurse }); } else if (!Blockly.Procedures.isNameUsed(newName, workspace)) { Blockly.alert(Blockly.Msg.PROCEDURE_ALREADY_EXISTS.replace('%1', newName.toLowerCase()), function() { promptAndCheckWithAlert(newName); // Recurse }); } else { workspace.renameVariable(variable.name, newName); if (opt_callback) { opt_callback(newName); } } } else { // User canceled prompt without a value. if (opt_callback) { opt_callback(null); } } }, null); }; promptAndCheckWithAlert(''); }; /** * Prompt the user for a new variable name. * @param {string} promptText The string of the prompt. * @param {string} defaultText The default value to show in the prompt's field. * @param {function(?string)} callback A callback. It will be passed the new * variable name, or null if the user picked something illegal. * @param {string} opt_type Optional type of variable, like 'string' or 'list'. * @param {string} opt_modal_title Optional title for the prompt. */ Blockly.Variables.promptName = function(promptText, defaultText, callback, opt_type, opt_modal_title) { var modalTitle = opt_modal_title ? opt_modal_title : Blockly.Msg.VARIABLE_MODAL_TITLE; Blockly.prompt(promptText, defaultText, function(newVar) { // Merge runs of whitespace. Strip leading and trailing whitespace. // Beyond this, all names are legal. if (newVar) { newVar = Blockly.Variables.validateName_(newVar, opt_type); } callback(newVar); }, modalTitle); }; /** * Validate the variable name provided by the user. * @param {string} name The user-provided name of the variable. * @param {string} opt_type Optional type of variable, like 'string' or 'list'. * @return {string} The validated and possibly transformed name of the variable. */ Blockly.Variables.validateName_ = function(name, opt_type) { if (!opt_type || opt_type != Blockly.BROADCAST_MESSAGE_VARIABLE_TYPE) { name = name.replace(/[\s\xa0]+/g, ' ').replace(/^ | $/g, ''); if (name == Blockly.Msg.RENAME_VARIABLE || name == Blockly.Msg.NEW_VARIABLE) { // Ok, not ALL names are legal... name = null; } } return name; }; /** * Generate XML string for variable field. * @param {!Blockly.VariableModel} variableModel The variable model to generate * an XML string from. * @param {?string} opt_name The optional name of the field, such as "VARIABLE" * or "LIST". Defaults to "VARIABLE". * @return {string} The generated XML. * @private */ Blockly.Variables.generateVariableFieldXml_ = function(variableModel, opt_name) { // The variable name may be user input, so it may contain characters that need // to be escaped to create valid XML. var element = goog.dom.createDom('field'); element.setAttribute('name', opt_name || 'VARIABLE'); element.setAttribute('variabletype', variableModel.type); element.setAttribute('id', variableModel.getId()); element.textContent = variableModel.name; var xmlString = Blockly.Xml.domToText(element); return xmlString; };