BlocklyController

public class BlocklyController extends Object

Controller to coordinate the state among all the major Blockly components: Workspace, Toolbox, Trash, models, and views.

All calls are expected to be called in the main thread/looper, because they create events that are processed immediately. Several methods will throw an IllegalStateExceptions if called on a different thread.

Nested Class Summary

class BlocklyController.Builder Builder for configuring a new controller and workspace. 
interface BlocklyController.EventsCallback Callback interface for BlocklyEvents. 
class BlocklyController.VariableCallback Callback for handling requests to modify the list of variables. 

Public Method Summary

BlockGroup
addBlockFromTrash(Block previouslyTrashedBlock)
Moves a block (and the child blocks connected to it) from the trashed blocks (removing it from the deleted blocks list), back to the workspace as a root block, including the BlockGroup and other views in the trash BlockListUI.
void
addCallback(BlocklyController.EventsCallback callback)
Registers a callback for Blockly events.
void
addPendingEvent(BlocklyEvent event)
Adds event to the list of pending events.
BlockGroup
addRootBlock(Block block)
Adds the provided block to the list of root blocks.
String
addVariable(String variable)
Create a new variable with a given name.
void
bumpBlock(Connection staticConnection, Connection impingingConnection)
Offsets the root block of impingingConnection, to confusion occlusion.
void
bumpNeighbors(Block currentBlock)
Move all neighbors of the current block and its sub-blocks so that they don't appear to be connected to the current block.
boolean
closeFlyouts()
Closes any open flyouts if they are closeable.
void
connect(Connection blockConnection, Connection otherConnection)
Connects a block to a specific connection of another block.
boolean
deleteVariable(String variable)
Delete a variable from the workspace and remove all blocks using that variable.
void
extractBlockAsRoot(Block block)
Takes a block, and adds it to the root blocks, disconnecting previous or output connections, if previously connected.
BlockFactory
BlockViewFactory
int
BlockClipDataHelper
Context
Dragger
VariableInfo
getVariableInfo(String variableName)
Returns the VariableInfo metadata about a specific variable.
Workspace
WorkspaceHelper
void
groupAndFireEvents(Runnable runnable)
Runs a segment of code (immediately) such that all events caused by the changes are collected into a single event group, and the group of events generated in that code is notified to BlocklyController.EventsCallbacks at the completion of the code.
void
initBlockViews()
Recursively initialize views for all the blocks in the model and add them to the view.
void
initWorkspaceView(WorkspaceView wv)
Set up the WorkspaceView with this workspace's model.
void
loadToolboxContents(int toolboxJsonResId)
Loads the toolbox contents from an XML resource file.
void
loadToolboxContents(InputStream toolboxJsonStream)
Loads the toolbox contents from a XML input stream.
void
loadToolboxContents(String toolboxJsonString)
Loads the toolbox contents from a XML string.
void
loadWorkspaceContents(String workspaceXmlString)
Reads the workspace in from a XML stream.
void
loadWorkspaceContents(InputStream workspaceXmlStream)
Reads the workspace in from a XML stream.
boolean
onRestoreSnapshot(Bundle savedInstanceState)
Loads a Workspace state from an Android Bundle, previous saved in onSaveSnapshot(Bundle).
boolean
onSaveSnapshot(Bundle mSavedInstanceState)
Saves a snapshot of current workspace contents to a temporary cache file, and saves the filename to the instance state bundle.
void
recenterWorkspace()
Reset the view to the top-left corner of the virtual workspace (with a small margin), and reset zoom to unit scale.
void
registerCategoryFactory(String customCategoryName, CustomCategory factory)
void
removeBlockTree(Block block)
Removes the given block from its parent, removes the block from the model, and then unlinks all views.
boolean
removeCallback(BlocklyController.EventsCallback callback)
Removes an events callback.
String
renameVariable(String variable, String newVariable)
Renames a variable in the workspace.
String
requestAddVariable(String variable)
Attempt to create a new variable.
boolean
requestDeleteVariable(String variable)
Attempt to delete a variable from the workspace.
String
requestRenameVariable(String variable, String newVariable)
Renames a variable in the workspace.
void
resetWorkspace()
Clears the workspace of all blocks and the respective views from the WorkspaceView, if connected.
void
setToolboxUi(BlockListUI toolbox, CategorySelectorUI categoryUi)
Connects a BlockListUI and optional CategorySelectorUI to this controller, so the user can drag new blocks into the attached WorkspaceFragment.
void
setTrashIcon(View trashIcon)
Assigns the view used for opening/closing the trash.
void
setTrashUi(BlockListUI trashUi)
Connects a BlockListUI for the trash to this controller.
void
setVariableCallback(BlocklyController.VariableCallback variableCallback)
Sets the callback to notify when the user requests a variable change, such as deleting or renaming a variable.
void
setWorkspaceFragment(WorkspaceFragment workspaceFragment)
Connects a WorkspaceFragment to this controller.
void
trashAllBlocks()
Removes all blocks from the WorkspaceView and puts them in the trash.
boolean
trashRootBlock(Block block)
Remove a block and its descendants from the workspace and put it in the trash, respecting the root block's deletable flag.
boolean
trashRootBlockIgnoringDeletable(Block block)
Remove a block and its descendants from the workspace and put it in the trash, regardless of block's deletable state.
void
unlinkViews(Block block)
Recursively unlinks models from the views, and disconnects the view tree including clearing the parent BlockGroup.
boolean
zoomIn()
Zooms into the workspace (i.e., enlarges the blocks), if the WorkspaceView has been attached.
boolean
zoomOut()
Zooms out the workspace (i.e., smaller the blocks), if the WorkspaceView has been attached.

Inherited Method Summary

Public Methods

public BlockGroup addBlockFromTrash (Block previouslyTrashedBlock)

Moves a block (and the child blocks connected to it) from the trashed blocks (removing it from the deleted blocks list), back to the workspace as a root block, including the BlockGroup and other views in the trash BlockListUI. This method does not connect the block to existing blocks, even if the block was connected before putting it in the trash.

Parameters
previouslyTrashedBlock The block in the trash to be moved back to the workspace.
Returns
  • The BlockGroup in the Workspace for the moved block.
Throws
IllegalArgumentException If trashedBlock is not found in the trashed blocks.

public void addCallback (BlocklyController.EventsCallback callback)

Registers a callback for Blockly events.

Parameters
callback The callback to add.

public void addPendingEvent (BlocklyEvent event)

Adds event to the list of pending events. If this is called outside of a call to groupAndFireEvents(Runnable), the event will be fired immediately, as its own group.

addPendingEvent() must be called from the main thread/looper.

Parameters
event The event to append.

public BlockGroup addRootBlock (Block block)

Adds the provided block to the list of root blocks. If the controller has an initialized WorkspaceView, it will also create corresponding views.

Parameters
block The Block to add to the workspace.

public String addVariable (String variable)

Create a new variable with a given name. If a variable with the same name already exists the name will be modified to be unique.

Parameters
variable The desired name of the variable to create.
Returns
  • The actual variable name that was created.

public void bumpBlock (Connection staticConnection, Connection impingingConnection)

Offsets the root block of impingingConnection, to confusion occlusion.

Parameters
staticConnection The original connection of the block.
impingingConnection The connection of the block to offset.

public void bumpNeighbors (Block currentBlock)

Move all neighbors of the current block and its sub-blocks so that they don't appear to be connected to the current block. Does not do anything in headless mode (no views attached).

Parameters
currentBlock The Block to bump others away from.

public boolean closeFlyouts ()

Closes any open flyouts if they are closeable.

Returns
  • True if any flyouts were closed.

public void connect (Connection blockConnection, Connection otherConnection)

Connects a block to a specific connection of another block. The block must not already be connected on the given connection; usually a root block. If another block is in the way of making the connection (occupies the required workspace location), that block will be bumped out of the way.

Note: The blocks involved are assumed to be in the workspace.

Parameters
blockConnection The open Connection on the block being connected.
otherConnection The target Connection to connect to. This may already be connected.

public boolean deleteVariable (String variable)

Delete a variable from the workspace and remove all blocks using that variable.

Parameters
variable The variable to delete.
Returns
  • True if the variable existed and was deleted, false otherwise.

public void extractBlockAsRoot (Block block)

Takes a block, and adds it to the root blocks, disconnecting previous or output connections, if previously connected. No action if the block was already a root block.

Parameters
block Block to extract as a root block in the workspace.

public BlockFactory getBlockFactory ()

public BlockViewFactory getBlockViewFactory ()

public int getCallbackCount ()

Returns

public BlockClipDataHelper getClipDataHelper ()

public Context getContext ()

public Dragger getDragger ()

Returns
  • The Dragger managing the drag behavior in connected views.

public VariableInfo getVariableInfo (String variableName)

Returns the VariableInfo metadata about a specific variable.

Parameters
variableName The variable queried.
Returns
  • The VariableInfo for variableName, or null if the name does not map to an existing variable.

public Workspace getWorkspace ()

public WorkspaceHelper getWorkspaceHelper ()

public void groupAndFireEvents (Runnable runnable)

Runs a segment of code (immediately) such that all events caused by the changes are collected into a single event group, and the group of events generated in that code is notified to BlocklyController.EventsCallbacks at the completion of the code. If a groupAndFireEvents() call is already in progress, the new code will integrate into that event group. This will catch side-effect changes, such as block bumps or validation updates.

groupAndFireEvents() must be called from the main thread/looper.

Parameters
runnable

public void initBlockViews ()

Recursively initialize views for all the blocks in the model and add them to the view.

public void initWorkspaceView (WorkspaceView wv)

Set up the WorkspaceView with this workspace's model. This method will perform the following steps:

  • Set the block touch handler for the view.
  • Configure the dragger for the view.
  • Recursively initialize views for all the blocks in the model and add them to the view.

Parameters
wv The root workspace view to add to.

public void loadToolboxContents (int toolboxJsonResId)

Loads the toolbox contents from an XML resource file.

Parameters
toolboxJsonResId The resource id of JSON file (should be a raw resource file).

public void loadToolboxContents (InputStream toolboxJsonStream)

Loads the toolbox contents from a XML input stream.

Parameters
toolboxJsonStream A stream of the JSON source of the set of blocks or block groups to show in the toolbox.
Throws
IOException
BlockLoadingException

public void loadToolboxContents (String toolboxJsonString)

Loads the toolbox contents from a XML string.

Parameters
toolboxJsonString The JSON source of the set of blocks or block groups to show in the toolbox.
Throws
BlockLoadingException If toolbox was not loaded. May wrap an IOException or another BlockLoadingException.

public void loadWorkspaceContents (String workspaceXmlString)

Reads the workspace in from a XML stream. This will clear the workspace and replace it with the contents of the xml.

Parameters
workspaceXmlString The XML source string to read from.
Throws
BlockLoadingException If workspace was not loaded. May wrap an IOException or another BlockLoadingException.

public void loadWorkspaceContents (InputStream workspaceXmlStream)

Reads the workspace in from a XML stream. This will clear the workspace and replace it with the contents of the xml.

Parameters
workspaceXmlStream The input stream to read from.
Returns
  • True if successful. Otherwise, false with error logged.

public boolean onRestoreSnapshot (Bundle savedInstanceState)

Loads a Workspace state from an Android Bundle, previous saved in onSaveSnapshot(Bundle).

Parameters
savedInstanceState The activity state Bundle passed into onCreate(Bundle) or onRestoreInstanceState(Bundle).
Returns
  • True if a Blockly state was found and successfully loaded into the Controller. Otherwise, false.

public boolean onSaveSnapshot (Bundle mSavedInstanceState)

Saves a snapshot of current workspace contents to a temporary cache file, and saves the filename to the instance state bundle.

Parameters
mSavedInstanceState The output Bundle to write the state to.
Returns
  • True if all values were written successfully to the bundle. Otherwise, false with errors written to log.

public void recenterWorkspace ()

Reset the view to the top-left corner of the virtual workspace (with a small margin), and reset zoom to unit scale.

public void registerCategoryFactory (String customCategoryName, CustomCategory factory)

Parameters
customCategoryName
factory

public void removeBlockTree (Block block)

Removes the given block from its parent, removes the block from the model, and then unlinks all views. All descendant of this block remain attached, and are thus also removed from the workspace.

Parameters
block The Block to look up and remove.

public boolean removeCallback (BlocklyController.EventsCallback callback)

Removes an events callback.

Parameters
callback The callback to remove.
Returns
  • True if the callback was found and removed.

public String renameVariable (String variable, String newVariable)

Renames a variable in the workspace. If a variable already exists with the new name the renamed variable will be modified to be unique. All fields that reference the renamed variable will be updated to the new name.

Parameters
variable The variable to rename.
newVariable The new name for the variable.
Returns
  • The new variable name that was saved.

public String requestAddVariable (String variable)

Attempt to create a new variable. If a BlocklyController.VariableCallback is set onCreateVariable(String) will be called to check if the creation is allowed. If a variable with the same name already exists the name will be modified to be unique.

Parameters
variable The desired name of the variable to create.
Returns
  • The variable name that was created or null if creation was not allowed.

public boolean requestDeleteVariable (String variable)

Attempt to delete a variable from the workspace. If a BlocklyController.VariableCallback is set onDeleteVariable(String, VariableInfo) will be called to check if deletion is allowed.

Parameters
variable The variable to delete.
Returns
  • True if the variable existed and was deleted, false otherwise.

public String requestRenameVariable (String variable, String newVariable)

Renames a variable in the workspace. If a BlocklyController.VariableCallback is set onRenameVariable(String, String) will be called before renaming. If a variable already exists with the new name the renamed variable will be modified to be unique.

Parameters
variable The variable to rename.
newVariable The new name for the variable.
Returns
  • The new variable name that was saved.

public void resetWorkspace ()

Clears the workspace of all blocks and the respective views from the WorkspaceView, if connected.

public void setToolboxUi (BlockListUI toolbox, CategorySelectorUI categoryUi)

Connects a BlockListUI and optional CategorySelectorUI to this controller, so the user can drag new blocks into the attached WorkspaceFragment.

Parameters
toolbox The flyout for displaying toolbox blocks.
categoryUi Optional ui for displaying toolbox categories.

public void setTrashIcon (View trashIcon)

Assigns the view used for opening/closing the trash.

Parameters
trashIcon The trash icon for dropping blocks.

public void setTrashUi (BlockListUI trashUi)

Connects a BlockListUI for the trash to this controller.

public void setVariableCallback (BlocklyController.VariableCallback variableCallback)

Sets the callback to notify when the user requests a variable change, such as deleting or renaming a variable.

Parameters
variableCallback The callback to notify when a variable is being deleted.

public void setWorkspaceFragment (WorkspaceFragment workspaceFragment)

Connects a WorkspaceFragment to this controller.

Parameters
workspaceFragment The fragment that contains the main workspace.

public void trashAllBlocks ()

Removes all blocks from the WorkspaceView and puts them in the trash.

public boolean trashRootBlock (Block block)

Remove a block and its descendants from the workspace and put it in the trash, respecting the root block's deletable flag. Use this method for user actions.

Note: Child blocks marked undeletable may be deleted, and this behavior may change in the future. See issue #370.

Parameters
block The block to remove, possibly with descendants attached.
Returns
  • True if the block was removed, false otherwise.

public boolean trashRootBlockIgnoringDeletable (Block block)

Remove a block and its descendants from the workspace and put it in the trash, regardless of block's deletable state. This method should only be used for programmatic manipulation of the workspace.

Parameters
block The block to remove, possibly with descendants attached.
Returns
  • True if the block was removed, false otherwise.

public void unlinkViews (Block block)

Recursively unlinks models from the views, and disconnects the view tree including clearing the parent BlockGroup.

Parameters
block The root block of the tree to unlink.

public boolean zoomIn ()

Zooms into the workspace (i.e., enlarges the blocks), if the WorkspaceView has been attached.

Returns
  • True if a zoom was changed. Otherwise false.

public boolean zoomOut ()

Zooms out the workspace (i.e., smaller the blocks), if the WorkspaceView has been attached.

Returns
  • True if a zoom was changed. Otherwise false.