Makecode Block Annotations
This is a slowly growing list of annotations for blocks in Makecode, mostly to document these for myself whenever I need to write another extensions.
Working Annotations
These are annotations that I have seen work in practice.
Namespace Properties
//% color="#BC986A" icon="\uf0ea"
Change the colour and icon for the namespace - the icon appears to be most valid unicode characters…
Basic Block Properties
Block Body Text
//% block="block text here"
This will replace the default generated block text with the supplied text.
Menu Groups
//% group="Buttons"
This does not require that the groups be predefined in the namespace.
Place Parameters in the Body Text
//% block="on ClipBit button $button pressed"
Replace $-prefix words with their parameter from the function.
Note that enums will be rendered as their names, rather than their values.
Advanced Blocks - Menu UI
//% advanced="true"
Move the block to the more section below the main section in the extension menu.
Parameter Render Options
Boolean Switches
//% on.shadow="toggleOnOff"
Sets the parameter ‘on’ to use the toggle on/off UI rather an a variable slot
Expandable Blocks (Hidden Parameters)
//% block="set ClipBit $display display to $value || as $style"
The double-bar || indicates the point that the block UI will be split, and replaced with an expander + icon.
Properties for Event Handlers
Allow Dragging of Parameters
//% draggableParameters="reporter"
Moving Between Languages
Shims
//% shim=ClipBit::sendLogViaSerial
Map the exported function annotated with this to the C++ call defined in the shim. Note that this doesn’t make a block by itself, and just exposes the call to Typescript.
If the function in Typescript has a body, this will be used in the sim.
Non-working Annotations
These are annotations that don’t seem to work correctly for Makecode extensions
Grid Picker
//% name.fieldEditor="gridpicker"
//% name.fieldOptions.columns=4
//% name.fieldOptions.tooltips="false"
//% name.fieldOptions.width="250"This (as seen in pxt-microbit here) seems to enumerate enum values and generate a grid of buttons rather than the usual dropdown, except that it doesn’t work for extensions? Specifying these paramters will result in the block not having any parameter for the user to select at all!
Updated 5/2/2024
If you don’t actually want to have a block show up, but need the c++ shim to be generated, the correct way now seems to be to include //% as a comment before the methods you want to export.
With no directives, this just generates the shims and makes the compiler happy again.