Workspace comments! (microsoft#4067)

* Integrate workspace comments with PXT.

Author: samelhusseini

localtypings/blockly.d.ts

@@ -752,6 +752,7 @@ declare namespace Blockly {
         setTooltip(newTip: string | (() => void)): void;
         // Passing null will delete current text
         setWarningText(text: string): void;
+        setHighlightWarning(isHighlightingWarning: boolean): void;
         isEditable(): boolean;
         isInsertionMarker(): boolean;
         isShadow(): boolean;
@@ -764,6 +765,18 @@ declare namespace Blockly {
         getSvgRoot(): Element;
     }
 
+    class WorkspaceComment {
+        getContent(): string;
+
+        getRelativeToSurfaceXY(): goog.math.Coordinate;
+        moveBy(x: number, y: number): void;
+        getHeightWidth(): { width: number; height: number; };
+        getBoundingRectangle(): {
+            topLeft: goog.math.Coordinate;
+            bottomRight: goog.math.Coordinate;
+        }
+    }
+
     class Comment extends Icon {
         constructor(b: Block);
 
@@ -893,6 +906,7 @@ declare namespace Blockly {
         clear(): void;
         dispose(): void;
         getTopBlocks(ordered: boolean): Block[];
+        getTopComments(ordered: boolean): WorkspaceComment[];
         getBlockById(id: string): Block;
         getAllBlocks(): Block[];
         traceOn(armed: boolean): void;
@@ -905,6 +919,7 @@ declare namespace Blockly {
         zoomCenter(type: number): void;
         scrollCenter(): void;
         highlightBlock(id: string): void;
+        centerOnBlock(id: string): void;
         glowBlock(id: string, state: boolean): void;
         glowStack(id: string, state: boolean): void;
         undo(redo?: boolean): void;

pxtblocks/blocklycompiler.ts

@@ -156,7 +156,7 @@ namespace pxt.blocks {
             return find((<any>b).p);
 
         if (b.type == "variables_get")
-            return find(lookup(e, escapeVarName(b.getFieldValue("VAR"), e)).type);
+            return find(lookup(e, escapeVarName(b.getField("VAR").getText(), e)).type);
 
         if (!b.outputConnection) {
             return ground(pUnit.type);
@@ -346,12 +346,12 @@ namespace pxt.blocks {
                     case "controls_for_of":
                         unionParam(e, b, "LIST", ground("Array"));
                         const listTp = returnType(e, getInputTargetBlock(b, "LIST"));
-                        const elementTp = lookup(e, escapeVarName(b.getFieldValue("VAR"), e)).type;
+                        const elementTp = lookup(e, escapeVarName(b.getField("VAR").getText(), e)).type;
                         genericLink(listTp, elementTp);
                         break;
                     case "variables_set":
                     case "variables_change":
-                        let x = escapeVarName(b.getFieldValue("VAR"), e);
+                        let x = escapeVarName(b.getField("VAR").getText(), e);
                         let p1 = lookup(e, x).type;
                         attachPlaceholderIf(e, b, "VALUE");
                         let rhs = getInputTargetBlock(b, "VALUE");
@@ -685,6 +685,11 @@ namespace pxt.blocks {
         return mkStmt(mkText(name + "()"));
     }
 
+    function compileWorkspaceComment(c: B.WorkspaceComment): JsNode {
+        const content = c.getContent();
+        return Helpers.mkMultiComment(content);
+    }
+
     function defaultValueForType(t: Point): JsNode {
         if (t.type == null) {
             union(t, ground(pNumber.type));
@@ -906,7 +911,7 @@ namespace pxt.blocks {
     }
 
     function compileControlsFor(e: Environment, b: B.Block, comments: string[]): JsNode[] {
-        let bVar = escapeVarName(b.getFieldValue("VAR"), e);
+        let bVar = escapeVarName(b.getField("VAR").getText(), e);
         let bTo = getInputTargetBlock(b, "TO");
         let bDo = getInputTargetBlock(b, "DO");
         let bBy = getInputTargetBlock(b, "BY");
@@ -955,7 +960,7 @@ namespace pxt.blocks {
     }
 
     function compileControlsForOf(e: Environment, b: B.Block, comments: string[]) {
-        let bVar = escapeVarName(b.getFieldValue("VAR"), e);
+        let bVar = escapeVarName(b.getField("VAR").getText(), e);
         let bOf = getInputTargetBlock(b, "LIST");
         let bDo = getInputTargetBlock(b, "DO");
 
@@ -1012,7 +1017,7 @@ namespace pxt.blocks {
     }
 
     function compileVariableGet(e: Environment, b: B.Block): JsNode {
-        let name = escapeVarName(b.getFieldValue("VAR"), e);
+        let name = escapeVarName(b.getField("VAR").getText(), e);
         let binding = lookup(e, name);
         if (!binding.assigned)
             binding.assigned = VarUsage.Read;
@@ -1021,7 +1026,7 @@ namespace pxt.blocks {
     }
 
     function compileSet(e: Environment, b: B.Block, comments: string[]): JsNode {
-        let bVar = escapeVarName(b.getFieldValue("VAR"), e);
+        let bVar = escapeVarName(b.getField("VAR").getText(), e);
         let bExpr = getInputTargetBlock(b, "VALUE");
         let binding = lookup(e, bVar);
         let isDef = false
@@ -1041,7 +1046,7 @@ namespace pxt.blocks {
     }
 
     function compileChange(e: Environment, b: B.Block, comments: string[]): JsNode {
-        let bVar = escapeVarName(b.getFieldValue("VAR"), e);
+        let bVar = escapeVarName(b.getField("VAR").getText(), e);
         let bExpr = getInputTargetBlock(b, "VALUE");
         let binding = lookup(e, bVar);
         if (!binding.assigned)
@@ -1447,7 +1452,7 @@ namespace pxt.blocks {
             if (!b)
                 return false;
             else if ((b.type == "controls_for" || b.type == "controls_simple_for" || b.type == "controls_for_of")
-                && escapeVarName(b.getFieldValue("VAR"), e) == name)
+                && escapeVarName(b.getField("VAR").getText(), e) == name)
                 return true;
             else if (isMutatingBlock(b) && b.mutation.isDeclaredByMutation(name))
                 return true;
@@ -1486,7 +1491,7 @@ namespace pxt.blocks {
         // collect local variables.
         if (w) w.getAllBlocks().filter(b => !b.disabled).forEach(b => {
             if (b.type == "controls_for" || b.type == "controls_simple_for" || b.type == "controls_for_of") {
-                let x = escapeVarName(b.getFieldValue("VAR"), e);
+                let x = escapeVarName(b.getField("VAR").getText(), e);
                 if (b.type == "controls_for_of") {
                     trackLocalDeclaration(x, null);
                 }
@@ -1518,7 +1523,7 @@ namespace pxt.blocks {
         // set block, 1) make sure that the variable is bound, then 2) mark the variable if needed.
         if (w) w.getAllBlocks().filter(b => !b.disabled).forEach(b => {
             if (b.type == "variables_get" || b.type == "variables_set" || b.type == "variables_change") {
-                let x = escapeVarName(b.getFieldValue("VAR"), e);
+                let x = escapeVarName(b.getField("VAR").getText(), e);
                 if (lookup(e, x) == null)
                     e = extend(e, x, null);
 
@@ -1608,7 +1613,16 @@ namespace pxt.blocks {
                     return mkStmt(mkText("let " + b.name + tp + " = "), defl)
                 });
 
-            return stmtsVariables.concat(stmtsMain)
+            const allStmts = stmtsVariables.concat(stmtsMain);
+
+            // compile workspace comments, add them to the top
+            const commentStmts: JsNode[] = [];
+            const topComments = w.getTopComments(true)
+            topComments.forEach(c => {
+                append(commentStmts, compileWorkspaceComment(c).children);
+            })
+
+            return commentStmts.concat(allStmts);
         } catch (err) {
             let be: B.Block = (err as any).block;
             if (be) {

pxtblocks/blocklylayout.ts

@@ -19,7 +19,7 @@ namespace pxt.blocks.layout {
         Util.toArray(oldDom.childNodes)
             .filter(n => n.nodeType == Node.ELEMENT_NODE && n.localName == "block" && (<Element>n).getAttribute("disabled") == "true")
             .forEach(n => newDom.appendChild(newDom.ownerDocument.importNode(n, true)));
-        const updatedXml = Blockly.Xml.domToPrettyText(newDom);
+        const updatedXml = Blockly.Xml.domToText(newDom);
         return updatedXml;
     }
 
@@ -51,8 +51,14 @@ namespace pxt.blocks.layout {
     declare function unescape(escapeUri: string): string;
 
     export function verticalAlign(ws: B.Workspace, emPixels: number) {
-        let blocks = ws.getTopBlocks(true);
         let y = 0
+        let comments = ws.getTopComments(true);
+        comments.forEach(comment => {
+            comment.moveBy(0, y)
+            y += comment.getHeightWidth().height
+            y += emPixels; //buffer
+        })
+        let blocks = ws.getTopBlocks(true);
         blocks.forEach(block => {
             block.moveBy(0, y)
             y += block.getHeightWidth().height
@@ -67,14 +73,14 @@ namespace pxt.blocks.layout {
 
                 // Only use the width if in portrait, otherwise the blocks are too spread out
                 if (metrics.viewHeight > metrics.viewWidth) {
-                    flowBlocks(ws.getTopBlocks(true), undefined, metrics.viewWidth)
+                    flowBlocks(ws.getTopComments(true), ws.getTopBlocks(true), undefined, metrics.viewWidth)
                     return;
                 }
             }
-            flowBlocks(ws.getTopBlocks(true), opts.ratio);
+            flowBlocks(ws.getTopComments(true), ws.getTopBlocks(true), opts.ratio);
         }
         else {
-            flowBlocks(ws.getTopBlocks(true));
+            flowBlocks(ws.getTopComments(true), ws.getTopBlocks(true));
         }
     }
 
@@ -221,7 +227,7 @@ namespace pxt.blocks.layout {
         return Promise.all(p).then(() => { })
     }
 
-    function flowBlocks(blocks: Blockly.Block[], ratio: number = 1.62, maxWidth?: number) {
+    function flowBlocks(comments: Blockly.WorkspaceComment[], blocks: Blockly.Block[], ratio: number = 1.62, maxWidth?: number) {
         const gap = 16;
         const marginx = 20;
         const marginy = 20;
@@ -232,28 +238,39 @@ namespace pxt.blocks.layout {
         }
         else {
             // compute total block surface and infer width
-            let surface = 0;
+            let commentSurface = 0;
+            let blockSurface = 0;
+            for (let comment of comments) {
+                let s = comment.getHeightWidth();
+                commentSurface += s.width * s.height;
+            }
             for (let block of blocks) {
                 let s = block.getHeightWidth();
-                surface += s.width * s.height;
+                blockSurface += s.width * s.height;
             }
-            maxx = Math.sqrt(surface) * ratio;
+            maxx = Math.sqrt(Math.max(commentSurface, blockSurface)) * ratio;
         }
 
         let insertx = marginx;
         let inserty = marginy;
         let endy = 0;
-        for (let block of blocks) {
-            let r = block.getBoundingRectangle();
-            let s = block.getHeightWidth();
-            // move block to insertion point
-            block.moveBy(insertx - r.topLeft.x, inserty - r.topLeft.y);
-            insertx += s.width + gap;
-            endy = Math.max(endy, inserty + s.height + gap);
-            if (insertx > maxx) { // start new line
-                insertx = marginx;
-                inserty = endy;
+        function flowBlocksInternal(blocks: Blockly.Block[] | Blockly.WorkspaceComment[]) {
+            for (let block of blocks) {
+                let r = block.getBoundingRectangle();
+                let s = block.getHeightWidth();
+                // move block to insertion point
+                block.moveBy(insertx - r.topLeft.x, inserty - r.topLeft.y);
+                insertx += s.width + gap;
+                endy = Math.max(endy, inserty + s.height + gap);
+                if (insertx > maxx) { // start new line
+                    insertx = marginx;
+                    inserty = endy;
+                }
             }
         }
+        flowBlocksInternal(comments);
+        insertx = marginx;
+        inserty = endy || marginy;
+        flowBlocksInternal(blocks);
     }
 }

pxtblocks/blocklyloader.ts

@@ -1914,6 +1914,7 @@ namespace pxt.blocks {
         initLogic();
         initText();
         initDrag();
+        initComments();
     }
 
     function setBuiltinHelpInfo(block: any, id: string) {
@@ -2216,6 +2217,12 @@ namespace pxt.blocks {
             let menuOptions: Blockly.ContextMenu.MenuItem[] = [];
             let topBlocks = this.getTopBlocks(true);
             let eventGroup = Blockly.utils.genUid();
+            let ws = this;
+
+            // Option to add a workspace comment.
+            if (this.options.comments) {
+                menuOptions.push((Blockly.ContextMenu as any).workspaceCommentOption(ws, e));
+            }
 
             // Add a little animation to collapsing and expanding.
             const DELAY = 10;
@@ -3012,6 +3019,7 @@ namespace pxt.blocks {
                 .appendField('', 'PARAMS');
             this.setColour(getNamespaceColor('functions'));
             this.arguments_ = [];
+            this.argumentVarModels_ = [];
             this.setStartHat(true);
             this.setStatements_(true);
             this.statementConnection_ = null;
@@ -3580,4 +3588,8 @@ namespace pxt.blocks {
             (filters.blocks[blockId] === FilterState.Disabled || filters.blocks[blockId] === FilterState.Hidden);
         return !isNamespaceFiltered && !isBlockFiltered;
     }
+
+    function initComments() {
+        (Blockly.Msg as any).WORKSPACE_COMMENT_DEFAULT_TEXT = '';
+    }
 }