diff --git a/blocks/procedures.ts b/blocks/procedures.ts index 1214eb55e..e2b7ba18f 100644 --- a/blocks/procedures.ts +++ b/blocks/procedures.ts @@ -1206,7 +1206,7 @@ blocks['procedures_callreturn'] = { this.appendDummyInput('TOPROW').appendField('', 'NAME'); this.setOutput(true); this.setStyle('procedure_blocks'); - // Tooltip is set in domToMutation. + // Tooltip is set in renameProcedure. this.setHelpUrl(Msg['PROCEDURES_CALLRETURN_HELPURL']); this.arguments_ = []; this.argumentVarModels_ = []; diff --git a/blocks/text.ts b/blocks/text.ts index 91a27005a..450e30087 100644 --- a/blocks/text.ts +++ b/blocks/text.ts @@ -438,6 +438,11 @@ const PROMPT_COMMON = { domToMutation: function (this: PromptCommonBlock, xmlElement: Element) { this.updateType_(xmlElement.getAttribute('type')!); }, + + // These blocks do not need JSO serialization hooks (saveExtraState + // and loadExtraState) because the state of this object is already + // encoded in the dropdown values. + // XML hooks are kept for backwards compatibility. }; blocks['text_prompt_ext'] = { @@ -468,16 +473,11 @@ blocks['text_prompt_ext'] = { : Msg['TEXT_PROMPT_TOOLTIP_NUMBER']; }); }, - - // This block does not need JSO serialization hooks (saveExtraState and - // loadExtraState) because the state of this object is already encoded in the - // dropdown values. - // XML hooks are kept for backwards compatibility. }; type PromptBlock = Block & PromptCommonMixin & QuoteImageMixin; -const TEXT_PROMPT_BLOCK = { +blocks['text_prompt'] = { ...PROMPT_COMMON, /** * Block for prompt function (internal message). @@ -520,8 +520,6 @@ const TEXT_PROMPT_BLOCK = { }, }; -blocks['text_prompt'] = TEXT_PROMPT_BLOCK; - blocks['text_count'] = { /** * Block for counting how many times one string appears within another string. @@ -666,7 +664,7 @@ const QUOTE_IMAGE_MIXIN = { * closing double quote. The selected quote will be adapted for RTL blocks. * * @param open If the image should be open quote (“ in LTR). - * Otherwise, a closing quote is used (” in LTR). + * Otherwise, a closing quote is used (” in LTR). * @returns The new field. */ newQuote_: function (this: QuoteImageBlock, open: boolean): FieldImage { diff --git a/core/block.ts b/core/block.ts index 6a911d557..6db948e48 100644 --- a/core/block.ts +++ b/core/block.ts @@ -143,24 +143,31 @@ export class Block implements IASTNodeLocation { suppressPrefixSuffix: boolean | null = false; /** - * An optional property for declaring developer variables. Return a list of - * variable names for use by generators. Developer variables are never - * shown to the user, but are declared as global variables in the generated - * code. + * An optional method for declaring developer variables, to be used + * by generators. Developer variables are never shown to the user, + * but are declared as global variables in the generated code. + * + * @returns a list of developer variable names. */ getDeveloperVariables?: () => string[]; /** - * An optional function that reconfigures the block based on the contents of - * the mutator dialog. + * An optional method that reconfigures the block based on the + * contents of the mutator dialog. + * + * @param rootBlock The root block in the mutator flyout. */ - compose?: (p1: Block) => void; + compose?: (rootBlock: Block) => void; /** - * An optional function that populates the mutator's dialog with - * this block's components. + * An optional function that populates the mutator flyout with + * blocks representing this block's configuration. + * + * @param workspace The mutator flyout's workspace. + * @returns The root block created in the flyout's workspace. */ - decompose?: (p1: Workspace) => Block; + decompose?: (workspace: Workspace) => Block; + id: string; outputConnection: Connection | null = null; nextConnection: Connection | null = null; @@ -716,7 +723,7 @@ export class Block implements IASTNodeLocation { } // Check that block is connected to new parent if new parent is not null and - // that block is not connected to superior one if new parent is null. + // that block is not connected to superior one if new parent is null. const targetBlock = (this.previousConnection && this.previousConnection.targetBlock()) || (this.outputConnection && this.outputConnection.targetBlock()); @@ -734,14 +741,13 @@ export class Block implements IASTNodeLocation { } // This block hasn't actually moved on-screen, so there's no need to - // update - // its connection locations. + // update its connection locations. if (this.parentBlock_) { // Remove this block from the old parent's child list. arrayUtils.removeElem(this.parentBlock_.childBlocks_, this); } else { - // New parent must be non-null so remove this block from the workspace's - // list of top-most blocks. + // New parent must be non-null so remove this block from the + // workspace's list of top-most blocks. this.workspace.removeTopBlock(this); } diff --git a/core/block_svg.ts b/core/block_svg.ts index 79f548caf..1a96d166a 100644 --- a/core/block_svg.ts +++ b/core/block_svg.ts @@ -92,7 +92,25 @@ export class BlockSvg static readonly COLLAPSED_WARNING_ID = 'TEMP_COLLAPSED_WARNING_'; override decompose?: (p1: Workspace) => BlockSvg; // override compose?: ((p1: BlockSvg) => void)|null; - saveConnections?: (p1: BlockSvg) => void; + + /** + * An optional method which saves a record of blocks connected to + * this block so they can be later restored after this block is + * recoomposed (reconfigured). Typically records the connected + * blocks on properties on blocks in the mutator flyout, so that + * rearranging those component blocks will automatically rearrange + * the corresponding connected blocks on this block after this block + * is recomposed. + * + * To keep the saved connection information up-to-date, MutatorIcon + * arranges for an event listener to call this method any time the + * mutator flyout is open and a change occurs on this block's + * workspace. + * + * @param rootBlock The root block in the mutator flyout. + */ + saveConnections?: (rootBlock: BlockSvg) => void; + customContextMenu?: ( p1: Array, ) => void;