BlockFactory

public class BlockFactory extends Object

The BlockFactory is responsible for managing the set of BlockDefinitions, and instantiating Blocks from those definitions. Add new definitions to the factory via addJsonDefinitions(InputStream). Create new Blocks by calling obtainBlockFrom(BlockTemplate). Using BlockTemplate's chaining methods, this can look like:

// Add definition.
 factory.addJsonDefinitions(getAssets().open("default/math_blocks.json"));
 // Create blocks.
 Block pi = factory.obtainBlockFrom(new BlockTemplate().ofType("math_number").withId("PI"));
 factory.obtainBlockFrom(new BlockTemplate().copyOf(pi).shadow().withId("PI-shadow"));
 

Field Summary

protected BlocklyController mController
protected final HashMap<BlockTypeFieldName, WeakReference<FieldDropdown.Options>> mDropdownOptions The global list of dropdown options available to each field matching the BlockTypeFieldName key.

Public Constructor Summary

BlockFactory()
Default constructor.

Public Method Summary

void
addDefinition(BlockDefinition definition)
Registers a new BlockDefinition with the factory.
int
addJsonDefinitions(String jsonString)
Loads and adds block definition from a JSON array string.
int
addJsonDefinitions(InputStream jsonStream)
Loads and adds block definitions from a JSON array in an input stream.
void
applyExtension(String extensionId, Block block)
Applies the named extension to the provided block.
void
applyMutator(String mutatorId, Block block)
Applies the named mutator to the provided block.
void
clear()
Removes all blocks from the factory.
void
clearWorkspaceBlockReferences(String workspaceId)
Removes references to previous blocks.
Block
fromXml(XmlPullParser parser)
Load a block and all of its children from XML.
List<BlockDefinition>
boolean
isBlockIdInUse(String id)
boolean
isDefined(String definitionId)
Field
loadFieldFromJson(String blockType, JSONObject json)
Create a new Field instance from JSON.
Block
obtainBlockFrom(BlockTemplate template)
Creates the Block described by the template.
void
registerExtension(String extensionId, BlockExtension extension)
Registers a BlockExtension for Blocks.
void
registerMutator(String mutatorId, Factory mutatorFactory)
Registers a Mutator.Factory for the named mutator type.
boolean
removeDefinition(String definitionName)
Removes a block type definition from this factory.
boolean
removeExtension(String extensionName)
Removes a BlockExtension from this block factory.
void
void
updateDropdownOptions(String blockType, String fieldName, List<FieldDropdown.Option> optionList)
Updates the list of options used by dropdowns in select block types.

Inherited Method Summary

Fields

protected BlocklyController mController

protected final HashMap<BlockTypeFieldName, WeakReference<FieldDropdown.Options>> mDropdownOptions

The global list of dropdown options available to each field matching the BlockTypeFieldName key.

Public Constructors

public BlockFactory ()

Default constructor.

Public Methods

public void addDefinition (BlockDefinition definition)

Registers a new BlockDefinition with the factory.

Parameters
definition The new definition.
Throws
IllegalArgumentException If type name is already defined.

public int addJsonDefinitions (String jsonString)

Loads and adds block definition from a JSON array string. These definitions will replace existing definitions, if the type names conflict.

Parameters
jsonString The InputStream containing the JSON block definitions.
Returns
  • A count of definitions added.
Throws
IOException If there is a fundamental problem with the input.
BlockLoadingException If the definition is malformed.

public int addJsonDefinitions (InputStream jsonStream)

Loads and adds block definitions from a JSON array in an input stream.

Parameters
jsonStream The stream containing the JSON block definitions.
Returns
  • A count of definitions added.
Throws
IOException If there is a fundamental problem with the input.
BlockLoadingException If the definition is malformed.

public void applyExtension (String extensionId, Block block)

Applies the named extension to the provided block.

Parameters
extensionId The name / id of the extension, as seen in the JSON extensions attribute.
block The block to apply it to.

public void applyMutator (String mutatorId, Block block)

Applies the named mutator to the provided block.

Parameters
mutatorId
block

public void clear ()

Removes all blocks from the factory.

public void clearWorkspaceBlockReferences (String workspaceId)

Removes references to previous blocks. This can be used when resetting a workspace to force a cleanup of known block instances.

Parameters
workspaceId

public Block fromXml (XmlPullParser parser)

Load a block and all of its children from XML.

Parameters
parser An XmlPullParser pointed at the start tag of this block.
Returns
  • The loaded block.
Throws
BlockLoadingException If unable to load the block or child. May contain a XmlPullParserException or IOException as a root cause.

public List<BlockDefinition> getAllBlockDefinitions ()

Returns
  • The list of known blocks types.

public boolean isBlockIdInUse (String id)

Parameters
id The id to check.

public boolean isDefined (String definitionId)

Parameters
definitionId

public Field loadFieldFromJson (String blockType, JSONObject json)

Create a new Field instance from JSON. If the type is not recognized null will be returned. If the JSON is invalid or there is an error reading the data a RuntimeException will be thrown.

Parameters
blockType The type id of the block within this field will be contained.
json The JSON to generate the Field from.
Returns
  • A Field of the appropriate type.
Throws
RuntimeException
BlockLoadingException

public Block obtainBlockFrom (BlockTemplate template)

Creates the Block described by the template.

blockFactory.obtainBlockFrom(new BlockTemplate().shadow().ofType("math_number"));
 

Parameters
template A template of the block to create.
Returns
  • A new block, or null if not able to construct it.

public void registerExtension (String extensionId, BlockExtension extension)

Registers a BlockExtension for Blocks.

Parameters
extensionId The identifier used in BlockDefinition and JSON references.
extension The new extension.

public void registerMutator (String mutatorId, Factory mutatorFactory)

Registers a Mutator.Factory for the named mutator type.

Parameters
mutatorId The name / id of this mutator type.
mutatorFactory The factory for this mutator type.

public boolean removeDefinition (String definitionName)

Removes a block type definition from this factory. If any block of this type is still in use, this may cause a crash if the user tries to load a new block of this type, including copies.

Parameters
definitionName The name of the block definition to remove.
Returns
  • True if the block definition was found and removed. Otherwise, false.

public boolean removeExtension (String extensionName)

Removes a BlockExtension from this block factory. If any block of this type is still in use, this may cause a crash if the user tries to load a new block of this type, including copies.

Parameters
extensionName The name of the extension to remove.
Returns
  • True if the extension was found and removed. Otherwise, false.

public void setController (BlocklyController controller)

Parameters
controller

public void updateDropdownOptions (String blockType, String fieldName, List<FieldDropdown.Option> optionList)

Updates the list of options used by dropdowns in select block types. These fields must be derived from the prototype blocks loaded via JSON (via ERROR(/#obtainBlock)), and where setOptions(FieldDropdown.Options) has not been called. An instance of the block must already exist, usually the prototype loaded via JSON.

Parameters
blockType The name for the type of block containing such fields
fieldName The name of the field within the block.
optionList The list of FieldDropdown.Options used to to set for the referenced dropdowns.