BlocklyActivityHelper

public class BlocklyActivityHelper extends Object

Class to facilitate Blockly setup on an Activity. onCreateFragments() looks for the WorkspaceFragment, the toolbox's BlockListUI, and the trash's BlockListUI via fragment ids blockly_workspace, blockly_toolbox_ui, and blockly_trash_ui, respectively.

The activity can also contain a few buttons to control the workspace. blockly_zoom_in_button and blockly_zoom_out_button control the workspace zoom scale, and blockly_center_view_button will reset it. blockly_trash_icon will toggle a closeable blockly_trash_ui BlockListUI (such as FlyoutFragment), and also act as a block drop target to delete blocks. The methods onConfigureTrashIcon(), onConfigureZoomInButton(), onConfigureZoomOutButton(), and onConfigureCenterViewButton() will search for these views and set the respective behavior.

Field Summary

protected AppCompatActivity mActivity
protected BlockViewFactory mBlockViewFactory
protected CategorySelectorFragment mCategoryFragment
protected BlockClipDataHelper mClipDataHelper
protected CodeGeneratorManager mCodeGeneratorManager
protected BlocklyController mController
protected Mutator mCurrMutator
protected DialogFragment mDialogFragment
protected MutatorFragment.DismissListener mMutatorDismissListener
protected BlockListUI mToolboxBlockList
protected BlockListUI mTrashBlockList
protected WorkspaceFragment mWorkspaceFragment
protected WorkspaceHelper mWorkspaceHelper

Public Constructor Summary

BlocklyActivityHelper(AppCompatActivity activity)
Creates the activity helper and initializes Blockly.

Public Method Summary

boolean
closeDialogFragment()
Closes the currently open ERROR(/DialogFragment) if there is one.
void
configureCategoryFactories()
This method provides a hook to register custom CustomCategorys that support toolboxes in this activity.
void
configureExtensions()
Default implementation for configureBlockExtensions().
void
configureMutators()
Default implementation for configureMutators().
BlocklyController
void
loadWorkspaceFromAppDir(String filename)
Loads the workspace from the given file in the application's private data directory.
boolean
loadWorkspaceFromAppDirSafely(String filename)
Loads the workspace from the given file in the application's private data directory.
boolean
BlockViewFactory
onCreateBlockViewFactory(WorkspaceHelper helper)
Constructs the BlockViewFactory used by all fragments in this activity.
void
onDestroy()
Lifecycle hook that must be called from onDestroy().
void
onPause()
Lifecycle hook that must be called from onPause().
void
onRestart()
Lifecycle hook that must be called from onRestart().
void
onResume()
Lifecycle hook that must be called from onResume().
void
onStart()
Lifecycle hook that must be called from onStart().
void
onStop()
Lifecycle hook that must be called from onStop().
void
reloadToolbox(String toolboxContentsXmlPath)
Reloads the toolbox from assets.
void
requestCodeGeneration(LanguageDefinition codeGeneratorLanguage, List<String> blockDefinitionsJsonPaths, List<String> generatorsJsPaths, CodeGenerationRequest.CodeGeneratorCallback codeGenerationCallback)
Requests code generation using the blocks in the Workspace/WorkspaceFragment.
void
resetBlockFactory(List<String> blockDefinitionsJsonPaths)
Resets the BlockFactory with the provided block definitions and extensions.
void
saveWorkspaceToAppDir(String filename)
Save the workspace to the given file in the application's private data directory, and show a status toast.
boolean
saveWorkspaceToAppDirSafely(String filename)
Save the workspace to the given file in the application's private data directory, and show a status toast.
void
showDialogFragment(DialogFragment fragment)
Shows a dialog UI to the user.

Protected Method Summary

void
onConfigureCenterViewButton()
This method finds and configures blockly_center_view_button from the view hierarchy as the button to reset the workspace view.
void
onConfigureTrashIcon()
This method finds and configures blockly_trash_icon from the view hierarchy as the button to open and close the trash, and a drop location for deleting blocks.
void
onConfigureZoomInButton()
This method finds and configures blockly_zoom_in_button from the view hierarchy as the button to zoom in (e.g., enlarge) the workspace view.
void
onConfigureZoomOutButton()
This method finds and configures blockly_zoom_out_button from the view hierarchy as the button to zoom out (e.g., shrink) the workspace view.
BlockClipDataHelper
onCreateClipDataHelper()
Constructs the BlockClipDataHelper for use by all Blockly components of mActivity.
void
onCreateFragments()
Creates the Views and Fragments before the BlocklyController is constructed.
void
onCreateMutatorListener()
Constructs a BlockViewFactory.MutatorToggleListener for handling user requests to show/hide a mutator for a block.
void
onCreateVariableCallback()
Constructs a BlocklyController.VariableCallback for handling user requests to change the list of variables (create, rename, delete).

Inherited Method Summary

Fields

protected AppCompatActivity mActivity

protected BlockViewFactory mBlockViewFactory

protected CategorySelectorFragment mCategoryFragment

protected BlockClipDataHelper mClipDataHelper

protected CodeGeneratorManager mCodeGeneratorManager

protected BlocklyController mController

protected Mutator mCurrMutator

protected DialogFragment mDialogFragment

protected MutatorFragment.DismissListener mMutatorDismissListener

protected BlockListUI mToolboxBlockList

protected BlockListUI mTrashBlockList

protected WorkspaceFragment mWorkspaceFragment

protected WorkspaceHelper mWorkspaceHelper

Public Constructors

public BlocklyActivityHelper (AppCompatActivity activity)

Creates the activity helper and initializes Blockly. Must be called during onCreate(Bundle). Executes the following sequence of calls during initialization:

Subclasses should override those methods to configure the Blockly environment.

Parameters
activity
Throws
IllegalStateException If error occurs during initialization. Assumes all initial compile-time assets are known to be valid.

Public Methods

public boolean closeDialogFragment ()

Closes the currently open ERROR(/DialogFragment) if there is one.

Returns
  • True if there was a dialog and it was closed, false otherwise.

public void configureCategoryFactories ()

This method provides a hook to register custom CustomCategorys that support toolboxes in this activity. The default implementation registers the categories in DefaultBlocks.

Most subclasses will want to include these default custom categories, calling super.configureCategoryFactories() if overridden. Category factories with the same custom key will replace existing CustomCategorys, so it is safe to call super and then update specific categories.

public void configureExtensions ()

Default implementation for configureBlockExtensions(). This adds all extensions in DefaultBlocks to the BlockFactory.

Extensions with the same key will replace existing extensions, so it is safe to call super and then update specific extensions.

public void configureMutators ()

Default implementation for configureMutators(). This adds all mutators in DefaultBlocks and their UIs to the BlockFactory and BlockViewFactory.

Mutators with the same key will replace existing mutators, so it is safe to call super and then update specific mutators.

public BlocklyController getController ()

Returns

public void loadWorkspaceFromAppDir (String filename)

Loads the workspace from the given file in the application's private data directory.

Parameters
filename The path to the file, in the application's local storage.
Throws
IOException If there is a underlying problem with the input.
BlockLoadingException If there is a error with the workspace XML format or blocks.

public boolean loadWorkspaceFromAppDirSafely (String filename)

Loads the workspace from the given file in the application's private data directory. If it fails to load, a toast will be shown and the error will be logged.

Parameters
filename The path to the file, in the application's local storage.
Returns
  • True if loading the workspace succeeds. Otherwise, false and the error will be logged.

public boolean onBackToCloseFlyouts ()

Returns
  • True if the action was handled to close a previously open (and closable) toolbox, trash UI, or dialog. Otherwise false.

public BlockViewFactory onCreateBlockViewFactory (WorkspaceHelper helper)

Constructs the BlockViewFactory used by all fragments in this activity. The Blockly core library does not include a factory implementation, and the app developer will need to include blockly vertical or another block rendering implementation.

The default implementation attempts to instantiates a VerticalBlockViewFactory, which is included in the blocklylib-vertical library. An error will be thrown unless blocklylib-vertical is included or this method is overridden to provide a custom BlockViewFactory.

Parameters
helper The Workspace helper for this activity.
Returns

public void onDestroy ()

Lifecycle hook that must be called from onDestroy(). Does nothing yet, but required for future compatibility.

public void onPause ()

Lifecycle hook that must be called from onPause().

public void onRestart ()

Lifecycle hook that must be called from onRestart(). Does nothing yet, but required for future compatibility.

public void onResume ()

Lifecycle hook that must be called from onResume().

public void onStart ()

Lifecycle hook that must be called from onStart(). Does nothing yet, but required for future compatibility.

public void onStop ()

Lifecycle hook that must be called from onStop(). Does nothing yet, but required for future compatibility.

public void reloadToolbox (String toolboxContentsXmlPath)

Reloads the toolbox from assets.

Parameters
toolboxContentsXmlPath The asset path to the toolbox XML
Throws
IllegalStateException If error occurs during loading.

public void requestCodeGeneration (LanguageDefinition codeGeneratorLanguage, List<String> blockDefinitionsJsonPaths, List<String> generatorsJsPaths, CodeGenerationRequest.CodeGeneratorCallback codeGenerationCallback)

Requests code generation using the blocks in the Workspace/WorkspaceFragment.

Parameters
codeGeneratorLanguage The language definition for the generators.
blockDefinitionsJsonPaths The asset path to the JSON block definitions.
generatorsJsPaths The asset paths to the JavaScript generators, and optionally the JavaScript block extension/mutator sources.
codeGenerationCallback The CodeGenerationRequest.CodeGeneratorCallback to use upon completion.

public void resetBlockFactory (List<String> blockDefinitionsJsonPaths)

Resets the BlockFactory with the provided block definitions and extensions.

Parameters
blockDefinitionsJsonPaths The list of definition asset paths.
Throws
IllegalStateException On any issues with the input.

public void saveWorkspaceToAppDir (String filename)

Save the workspace to the given file in the application's private data directory, and show a status toast. If the save fails, the error is logged.

Parameters
filename
Throws
FileNotFoundException
BlocklySerializerException

public boolean saveWorkspaceToAppDirSafely (String filename)

Save the workspace to the given file in the application's private data directory, and show a status toast. If the save fails, the error is logged.

Parameters
filename
Returns
  • True if the save was successful. Otherwise false.

public void showDialogFragment (DialogFragment fragment)

Shows a dialog UI to the user. Only one dialog will be shown at a time and if there is already an existing one it will be replaced. This can be used for showing application or block specific UIs, such as a mutator UI. When the user finishes using the fragment closeDialogFragment() should be called.

Parameters
fragment The fragment to show.

Protected Methods

protected void onConfigureCenterViewButton ()

This method finds and configures blockly_center_view_button from the view hierarchy as the button to reset the workspace view. If blockly_center_view_button is not found, it does nothing.

This is called from the constructor after mController is initialized.

protected void onConfigureTrashIcon ()

This method finds and configures blockly_trash_icon from the view hierarchy as the button to open and close the trash, and a drop location for deleting blocks. If blockly_trash_icon is not found, it does nothing.

This is called from the constructor after mController is initialized.

protected void onConfigureZoomInButton ()

This method finds and configures blockly_zoom_in_button from the view hierarchy as the button to zoom in (e.g., enlarge) the workspace view. If blockly_zoom_in_button is not found, it does nothing.

This is called from the constructor after mController is initialized.

protected void onConfigureZoomOutButton ()

This method finds and configures blockly_zoom_out_button from the view hierarchy as the button to zoom out (e.g., shrink) the workspace view. If blockly_zoom_out_button is not found, it does nothing.

This is called from the constructor after mController is initialized.

protected BlockClipDataHelper onCreateClipDataHelper ()

Constructs the BlockClipDataHelper for use by all Blockly components of mActivity. The instance will be passed to the controller and available via getClipDataHelper().

By default, it constructs a SingleMimeTypeClipDataHelper with a MIME type derived from the application's package name. This assumes all Blockly workspaces in an app work with the same shared set of blocks, and blocks can be dragged/copied/pasted between them, even if they are in different Activities. It also ensures blocks from other applications will be rejected.

If your app uses different block sets for different workspaces, or you intend to interoperate with other applications, you will need to override this method with your own implementation.

Returns

protected void onCreateFragments ()

Creates the Views and Fragments before the BlocklyController is constructed. Override to load a custom View hierarchy. Responsible for assigning mWorkspaceFragment, and optionally, mToolboxBlockList and mTrashBlockList. This base implementation attempts to acquire references to:

Only the workspace fragment is required. The activity layout can choose not to include the other fragments, and subclasses that override this method can leave the field null if that are not used.

This methods is always called once from the constructor before mController is instantiated.

protected void onCreateMutatorListener ()

Constructs a BlockViewFactory.MutatorToggleListener for handling user requests to show/hide a mutator for a block.

By default, this method will remove the open dialog fragment if there is one and show the mutator's fragment if it wasn't just removed.

This method is responsible for calling setMutatorToggleListener(BlockViewFactory.MutatorToggleListener).

protected void onCreateVariableCallback ()

Constructs a BlocklyController.VariableCallback for handling user requests to change the list of variables (create, rename, delete). This can be used to provide UI for confirming a deletion or renaming a variable.

By default, this method constructs a DefaultVariableCallback. Apps can override this to provide an alternative implementation, or optionally override the method to do nothing (no confirmation UI).

This method is responsible for calling setVariableCallback(BlocklyController.VariableCallback).

Returns