Blockly之工具Block模块的加入流程

一.Block小模块的加入过程：

在Blockly中侧边栏中的ToolBox是的加入经过assets目录下的json文件数据进行转化成Block的小模块。json中的数据标签通过BlockDefinition类解析一个个的具有属性Block模块，之后把Block模块加入到BlockFactory的工厂中。在需要的地方绘制到Fragment中去。



二.添加自定义的模块的流程：

1.在DefaultBlocks.java中添加要加入模块的json路径如：

添加路径的常量值：

public static final String WANGYONGYAO_BLOCKS_PATH = "default/wangyongyao_blocks.json";

在getAllBlockDefinitions方法中添加定义的路径常量值，在这里加入是通过一系列的方法进行json数据的解析成Block中的属性值：



2.在assets目录中的toolbox.xml中添加自己定义的block的category种类：

<toolbox>
<category name="王永耀" colour="200">
<block type="wangyongyao_type"></block>
</category>
</toolbox>

3.自己定义的json文件wangyongyao.json格式如下，如是图片转化成base64码的网站：

[
{
"type": "wangyongyao_type",     //自定的type模式在toolbox.xml中进行定义
"message0": "%1 王永耀 %2",      //%后的是type数量值如有两个就是这种模式，如是三个就在后面加上%3以此类推
"args0": [
{
"type": "field_image",      //添加图片模式，src后添加的是图片转成的base64的值
"src": "data:image/gif;base64,R0lGODlhDwAPAMQfAF9h4RYVnZeQJC0u0lRQU42R6P/7Fv74L05NrRkZxi4tW52XXv71D8nAIWxnjnRxr3NuMJKOluXbBe7kCa2x7UFD1vPoB77D8Jqe6n6B5tvTUr62BMrP8lJPh1xbuv///yH5BAEAAB8ALAAAAAAPAA8AAAWD4CeOWQKMaDpESepi3tFlLgpExlK9RT9ohkYi08N8KhWP8nEwMBwIDyJRSTgO2CaDYcBOCAlMgtDYmhmTDSFQ+HAqgbLZIlAMLqiKw7m1EAYuFQsGEhITEwItKBc/EgIEAhINAUYkCBIQAQMBEGonIwAKa21iCgo7IxQDFRQjF1VtHyEAOw==",
"width": 15,
"height": 15,
"alt": "*"
},
{
"type": "input_value",
"name": "yuan_text",
"check": "String"
}
],
"colour": 330,
"tooltip": "",
"helpUrl": ""
}
]

这样就简单添加了一个自定义模块的block。

三.json及xml数据加入的源码分析：

1.在assets资产目录下的json文件，通过AbstractBlockActivity抽象类中的抽象方法getBlockDedinitionJsonPaths（）：

private static final List<String> BLOCK_DEFINITIONS = DefaultBlocks.getAllBlockDefinitions();

@NonNull
@Override
protected List<String> getBlockDefinitionsJsonPaths() {             //获取模块中默认assets的json数据
return BLOCK_DEFINITIONS;
}

2.接下来传给BlockActivityHelper类的resetBlockFactory()：

protected void resetBlockFactory() {
mBlocklyActivityHelper.resetBlockFactory(               //将获取到的assets中的路径信息交给BlockActivityHelper处理
getBlockDefinitionsJsonPaths());

configureBlockExtensions();
configureMutators();
configureCategoryFactories();

// Reload the toolbox?
}

3.在resetBlockFactort()方法中获取到DefaltBlock中定义的json的路径常量。

public void resetBlockFactory(
@Nullable List<String> blockDefinitionsJsonPaths) {
AssetManager assets = mActivity.getAssets();
BlockFactory factory = mController.getBlockFactory();
factory.clear();

String assetPath = null;
try {
if (blockDefinitionsJsonPaths != null) {
Log.i("everb","blockDefinitionsJsonPaths:"+blockDefinitionsJsonPaths);
for (String path : blockDefinitionsJsonPaths) {
assetPath = path;
factory.addJsonDefinitions(assets.open(path));  //传给BlockFactory工厂进行Block成型的处理
}
}
} catch (IOException | BlockLoadingException e) {
throw new IllegalStateException(
"Failed to load block definition asset file: " + assetPath, e);
}
}

4.之后交给BlockFactory进行InputStream输入流的的处理:

public int addJsonDefinitions(InputStream jsonStream)
throws IOException, BlockLoadingException {
// Read stream as single string.
String inString = new Scanner( jsonStream ).useDelimiter("\\A").next();
Log.i("everb","inString:"+inString);
return addJsonDefinitions(inString);//返回block的数量
}

public void addDefinition(BlockDefinition definition) {
String typeName = definition.getTypeName();
if (mDefinitions.containsKey(ty
1750a
peName)) {
throw new IllegalArgumentException(
"Definition \"" + typeName + "\" already defined. Prior must remove first.");
}
mDefinitions.put(typeName, definition);    //添加到mDefinitions的map中放在BlockFatoryTest去检测是否合法
}

5.在BlockDefinition类中解析在assets中的json文件，通过CreateInputList（）方法生成Input的集合提供给block类调用生成一个模块：Field的bean类包涵着json数据中的所有type对应的标签.BlockDefinition对块block之间的输入输出关系进行了解析和check检查。Input是每个在工具栏中能拖动的block块的数据块，在Input中包涵着Filed最基础的模块，相当于一条语句的模块如：一个if语句就代表着一个Filed。

一个json块对等的关系：

Filed对等于json中的：

"args0": [
{
"type": "field_image",      //添加图片模式，src后添加的是图片转成的base64的值
"src": "data:image/gif;base64,R0lGODlhDwAPAMQfAF9h4RYVnZeQJC0u0lRQU42R6P/7Fv74L05NrRkZxi4tW52XXv71D8nAIWxnjnRxr3NuMJKOluXbBe7kCa2x7UFD1vPoB77D8Jqe6n6B5tvTUr62BMrP8lJPh1xbuv///yH5BAEAAB8ALAAAAAAPAA8AAAWD4CeOWQKMaDpESepi3tFlLgpExlK9RT9ohkYi08N8KhWP8nEwMBwIDyJRSTgO2CaDYcBOCAlMgtDYmhmTDSFQ+HAqgbLZIlAMLqiKw7m1EAYuFQsGEhITEwItKBc/EgIEAhINAUYkCBIQAQMBEGonIwAKa21iCgo7IxQDFRQjF1VtHyEAOw==",
"width": 15,
"height": 15,
"alt": "*"
},
{
"type": "input_value",
"name": "yuan_text",
"check": "String"
}
],

Input对等于json中的：

{
"type": "wangyongyao_type",     //自定的type模式在toolbox.xml中进行定义
"message0": "%1 王永耀 %2",      //%后的是type数量值如有两个就是这种模式，如是三个就在后面加上%3以此类推
"args0": [
{
"type": "field_image",      //添加图片模式，src后添加的是图片转成的base64的值
"src": "data:image/gif;base64,R0lGODlhDwAPAMQfAF9h4RYVnZeQJC0u0lRQU42R6P/7Fv74L05NrRkZxi4tW52XXv71D8nAIWxnjnRxr3NuMJKOluXbBe7kCa2x7UFD1vPoB77D8Jqe6n6B5tvTUr62BMrP8lJPh1xbuv///yH5BAEAAB8ALAAAAAAPAA8AAAWD4CeOWQKMaDpESepi3tFlLgpExlK9RT9ohkYi08N8KhWP8nEwMBwIDyJRSTgO2CaDYcBOCAlMgtDYmhmTDSFQ+HAqgbLZIlAMLqiKw7m1EAYuFQsGEhITEwItKBc/EgIEAhINAUYkCBIQAQMBEGonIwAKa21iCgo7IxQDFRQjF1VtHyEAOw==",
"width": 15,
"height": 15,
"alt": "*"
},
{
"type": "input_value",
"name": "yuan_text",
"check": "String"
}
],
"colour": 330,
"tooltip": "",
"helpUrl": ""
}

以下是createInputList方法将所有的json文件数据转成Input的过程：

/**
* @return A new list of {@link Input} objects for a new block of this type, complete with
*         fields.
*/
protected ArrayList<Input> createInputList(BlockFactory factory) throws BlockLoadingException {
ArrayList<Input> inputs = new ArrayList<>();
ArrayList<Field> fields = new ArrayList<>();
for (int i = 0; ; i++) {
String messageKey = "message" + i;
String argsKey = "args" + i;
String lastDummyAlignKey = "lastDummyAlign" + i;
if (!mJson.has(messageKey)) {
break;
}
String message = mJson.optString(messageKey);
JSONArray args = mJson.optJSONArray(argsKey);
if (args == null) {
// If there's no args for this message use an empty array.
args = new JSONArray();
}

if (message.matches("^%[a-zA-Z][a-zA-Z_0-9]*$")) {
// TODO(#83): load the message from resources.
}
// Split on all argument indices of the form "%N" where N is a number from 1 to
// the number of args. Arguments indices are returned as "%N" strings.
List<String> tokens = Block.tokenizeMessage(message);     //将json数据中的"message+index"标签后的属性进行切割取出，如：“if %1 do %2”把if和do取出赋值给tokens
// Indices start at 1, make the array 1 bigger so we don't have to offset things
boolean[] seenIndices = new boolean[args.length() + 1];

for (String token : tokens) {
// Check if this token is an argument index of the form "%N"
Log.i("everb","token:"+token);
if (token.matches("^%\\d+$")) {
int index = Integer.parseInt(token.substring(1));
if (index < 1 || index > args.length()) {
throw new BlockLoadingException("Message index " + index
+ " is out of range.");
}
if (seenIndices[index]) {
throw new BlockLoadingException(("Message index " + index
+ " is duplicated"));
}
seenIndices[index] = true;

JSONObject element;
try {
element = args.getJSONObject(index - 1);      //取出每个Input中的参数args相对于Field
Log.i("everb","element:"+element);
} catch (JSONException e) {
throw new BlockLoadingException("Error reading arg %" + index, e);
}
while (element != null) {
String elementType = element.optString("type");
if (TextUtils.isEmpty(elementType)) {
throw new BlockLoadingException("No type for arg %" + index);
}

if (Field.isFieldType(elementType)) {       //判断Filed中的type类型是否为空
fields.add(factory.loadFieldFromJson(mTypeName, element));
break;
} else if (Input.isInputType(elementType)) {
Input input = Input.fromJson(element, fields);
fields.clear();
inputs.add(input);
break;
} else {
// Try getting the fallback block if it exists
Log.w(TAG, "Unknown element type: " + elementType);
element = element.optJSONObject("alt");
}
}
} else {
token = token.replace("%%", "%").trim();
if (!TextUtils.isEmpty(token)) {
fields.add(new FieldLabel(null, token));  //添加Filed的Label标签名
}
}
}

// Verify every argument was used
for (int j = 1; j < seenIndices.length; j++) {
if (!seenIndices[j]) {
throw new BlockLoadingException("Argument " + j + " was never used.");
}
}
// If there were leftover fields we need to add a dummy input to hold them.
if (fields.size() != 0) {
String align = mJson.optString(lastDummyAlignKey, Input.ALIGN_LEFT_STRING);
Input input = new Input.InputDummy(null, fields, align);
inputs.add(input);
fields.clear();
}
Log.i("everb","input:"+inputs.get(i).getType());
}

return  inputs;
}

6.BlockFactory中的ObtainBlockFrom(BlockTemplate template)方法里获取BlockTemlate获取对应的样板：

public Block obtainBlockFrom(BlockTemplate template) throws BlockLoadingException {
if (mController == null) {
throw new IllegalStateException("Must set BlockController before creating block.");
}

String id = getCheckedId(template.mId);

// Existing instance not found. Constructing a new Block.
BlockDefinition definition;
boolean isShadow = (template.mIsShadow == null) ? false : template.mIsShadow;
Block block;
if (template.mCopySource != null) {
try {
// TODO: Improve copy overhead. Template from copy to avoid XML I/O?
String xml = BlocklyXmlHelper.writeBlockToXml(template.mCopySource,       //通过BlockTemplate获取对应的样板Block
IOOptions.WRITE_ROOT_ONLY_WITHOUT_ID);
String escapedId = BlocklyXmlHelper.escape(id);
xml = xml.replace("<block", "<block id=\"" + escapedId + "\"");
block = BlocklyXmlHelper.loadOneBlockFromXml(xml, this);
} catch (BlocklySerializerException e) {
throw new BlockLoadingException(
"Failed to serialize original " + template.mCopySource, e);
}
} else {
// Start a new block from a block definition.
if (template.mDefinition != null) {
if (template.mTypeName != null
&& !template.mTypeName.equals(template.mDefinition.getTypeName())) {
throw new BlockLoadingException("Conflicting block definitions referenced.");
}
definition = template.mDefinition;
} else if (template.mTypeName != null) {
definition = mDefinitions.get(template.mTypeName.trim());
if (definition == null) {
throw new BlockLoadingException("Block definition named \""
+ template.mTypeName + "\" not found.");
}
} else {
throw new BlockLoadingException(template.toString() + " missing block definition.");
}

block = new Block(mController, this, definition, id, isShadow);
}

// Apply mutable state last.
template.applyMutableState(block);
mBlockRefs.put(block.getId(), new WeakReference<>(block));

return block;
}

7.BlocklyCategory提供解析出toolbox.xml文件的种类及子种类。给BlockActivityHelper中的reloadToolbox调用：

调用过程是：将AbstractBlocklyAcitity获取到的toolbox的文件路径一步步地交给BlockActivityHelper->BlocklyController->Workspace->BlockXmlHelper进行解析XML中的数据类型及属性。

在BlockActivityHelper中：

public void reloadToolbox(String toolboxContentsXmlPath) {
AssetManager assetManager = mActivity.getAssets();
BlocklyController controller = getController();
try {
controller.loadToolboxContents(assetManager.open(toolboxContentsXmlPath));          //加载出toolbox.xml文件中的BlocklyCategory的种类
} catch (IOException | BlockLoadingException e) {
// compile time assets such as assets are assumed to be good.
throw new IllegalStateException("Failed to load toolbox XML.", e);
}
}

在BlocklyController中：

public void loadToolboxContents(InputStream toolboxJsonStream)
throws IOException, BlockLoadingException {
mWorkspace.loadToolboxContents(toolboxJsonStream);
updateToolbox();
}

在Workspace中：

public void loadToolboxContents(InputStream source) throws BlockLoadingException {
mFlyoutCategory = BlocklyXmlHelper.loadToolboxFromXml(source, mBlockFactory, BlocklyEvent.WORKSPACE_ID_TOOLBOX);
}

在BlockXmlHelper中：

public static BlocklyCategory loadToolboxFromXml(InputStream is, BlockFactory blockFactory,
String workspaceId)
throws BlockLoadingException {
try {
XmlPullParser parser = PARSER_FACTORY.newPullParser();
parser.setInput(is, null);
return BlocklyCategory.fromXml(parser, blockFactory, workspaceId);//BlocklyCategory进行toolbox.xml的种类解析

} catch (XmlPullParserException e) {
throw new BlockLoadingException(e);
}
}

四、FlyoutFragment中的Block的加入的流程：

1.AbstractBlocklyAcitity中onCreate()方法中初始化来自assets下的json文件之后，在进行Category种类的的设置：

protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

onCreateActivityRootView();
mBlocklyActivityHelper = onCreateActivityHelper();
if (mBlocklyActivityHelper == null) {
throw new IllegalStateException("BlocklyActivityHelper is null. "
+ "onCreateActivityHelper must return a instance.");
}
resetBlockFactory();  // Initial load of block definitions, extensions, and mutators.
configureCategoryFactories();  // After BlockFactory; before Toolbox
reloadToolbox();

// Load the workspace.
boolean loadedPriorInstance = checkAllowRestoreBlocklyState(savedInstanceState)
&& (getController().onRestoreSnapshot(savedInstanceState) || onAutoload());
if (!loadedPriorInstance) {
onLoadInitialWorkspace();
}
}

2.AbstractBlocklyAcitity交给BlockActivityHelper中的configureCategoryFactories方法里对默认的category种类获取及登记：

protected void configureCategoryFactories() {
mBlocklyActivityHelper.configureCategoryFactories();
}

public void configureCategoryFactories() {
Map <String, CustomCategory> factoryMap =
DefaultBlocks.getToolboxCustomCategories(mController);  //在默认的DefaultBlocks获取到toolbox中Categories种类
for (String key : factoryMap.keySet()) {
mController.registerCategoryFactory(key, factoryMap.get(key));//在BlocklyController对toolbox中Categories种类进行登记
}
}

3.接下来DefaultBlocks中对block参数及种类进行对应的生成：

public static Map<String, CustomCategory> getToolboxCustomCategories(
BlocklyController controller) {
// Don't store this map, because of the reference to the controller.
Map<String, CustomCategory> map = new ArrayMap<>(2);
map.put(VARIABLE_CATEGORY_NAME, new VariableCustomCategory(controller));//参数Category种类的添加
map.put(PROCEDURE_CATEGORY_NAME, new ProcedureCustomCategory(controller));//block的Category种类在ProcedureCustomCategory生成器中生成
return Collections.unmodifiableMap(map);
}

4.ProcedurCustomCategory种类生成器初始化时对BlockTemlate检查和categorry的item的数据设置：

public void initializeCategory(BlocklyCategory category) throws BlockLoadingException {
checkRequiredBlocksAreDefined();  //检查Block的定义是否在BlockFactory对BlockTemplate进行了生成
rebuildItems(category);         //把category种类的item通过一系列的回调中添加最终设置到FlyoutFragment布局RecyclerView的adapter中

private void rebuildItems(BlocklyCategory category) throws BlockLoadingException {
category.clear();

Block block = mBlockFactory.obtainBlockFrom(DEFINE_NO_RETURN_BLOCK_TEMPLATE);//从BlockFactory工厂中获取ProcedureManager中的block的模板
((FieldInput)block.getFieldByName(NAME_FIELD)).setText(mDefaultProcedureName);//设置名字和do something
category.addItem(new BlocklyCategory.BlockItem(block));//添加到BlocklyCategory中的item中

block = mBlockFactory.obtainBlockFrom(DEFINE_WITH_RETURN_BLOCK_TEMPLATE);
((FieldInput)block.getFieldByName(NAME_FIELD)).setText(mDefaultProcedureName);
category.addItem(new BlocklyCategory.BlockItem(block));

if (!mProcedureManager.hasProcedureDefinitionWithReturn()) {
block = mBlockFactory.obtainBlockFrom(IF_RETURN_TEMPLATE);
category.addItem(new BlocklyCategory.BlockItem(block));
}

// Create a call block for each definition.
final Map<String, Block> definitions = mProcedureManager.getDefinitionBlocks();
SortedSet<String> sortedProcNames = new TreeSet<>(new Comparator<String>() {
@Override
public int compare(String procName1, String procName2) {
Block def1 = definitions.get(procName1);
Block def2 = definitions.get(procName2);
String type1 = def1.getType();
String type2 = def2.getType();

// procedures_defnoreturn < procedures_defreturn
int typeComp = type1.compareTo(type2);
if (typeComp != 0) {
return typeComp;
}
// Otherwise sort by procedure name, alphabetically
int nameComp = procName1.compareToIgnoreCase(procName2);
if (nameComp != 0) {
return nameComp;
}
return def1.getId().compareTo(def2.getId()); // Last resort, by block id
}
});
sortedProcNames.addAll(definitions.keySet());
for (String procName : sortedProcNames) {
Block defBlock = definitions.get(procName);
ProcedureInfo procedureInfo = ((AbstractProcedureMutator) defBlock.getMutator())
.getProcedureInfo();
BlockTemplate callBlockTemplate;
if (defBlock.getType().equals(ProcedureManager.DEFINE_NO_RETURN_BLOCK_TYPE)) {
callBlockTemplate = CALL_NO_RETURN_BLOCK_TEMPLATE;  // without return value
} else {
callBlockTemplate = CALL_WITH_RETURN_BLOCK_TEMPLATE;  // with return value
}
Block callBlock = mBlockFactory.obtainBlockFrom(callBlockTemplate);
((ProcedureCallMutator) callBlock.getMutator()).mutate(procedureInfo);
category.addItem(new BlocklyCategory.BlockItem(callBlock));
}
}

5.BlocklyCateory的addItem方法把item通过回调通知刷新的方式添加到BlcokRecyclerViewHelper的adapter中，并最终的设置到Recycler中。实现了FlyoutFragment中关于toolbox所有的block的显示：

/**
* Add a {@link Block} to the blocks displayed in this category.
*
* @param item The {@link Block} to add.
*/
public void addItem(CategoryItem item) {
mItems.add(item);
if (mCallback != null) {
mCallback.onItemAdded(mItems.size() - 1, item);//通过Callback回调的形式把item添加到BlockRecyclerViewHelper中的adapter中去
}
}

6.BlcokRecyclerViewHelper中的设置CategoryCallback回调来监听item的事件变化：

protected class CategoryCallback extends BlocklyCategory.Callback {

@Override
public void onItemAdded(int index, BlocklyCategory.CategoryItem item) {
mAdapter.notifyItemInserted(index);
}

@Override
public void onItemRemoved(int index, BlocklyCategory.CategoryItem block) {
mAdapter.notifyItemRemoved(index);
}

@Override
public void onCategoryCleared() {
mAdapter.notifyDataSetChanged();
}
}