addon.tab.traps (Traps)

This page is out of date and is in need of a rewrite. If you know anything about traps, please contribute!

addon.tab.traps is a public API for userscripts that can be used to obtain objects that are not otherwise available. The actual traps are coded at prototype-handler.

They share some APIs with “Once” traps, but is very different and is documented at Fake redux state separately.

Examples

editor-stepping addon shows how to manipulate Thread object trapped.

Trap terminology

There are two types of traps, named after how many times they get trapped. Singleton instance like VM or ScratchBlocks get trapped only once per trap, so they are called “Once”. Objects like Thread can get trapped multiple times, so they are called “Many”.

Difference between Once and Many is simple: the addon only stores reference for Once.

Trappable Object

Trap nameDescriptionOnce/Many
vmScratch VM, trapped by Function.prototype.bindOnce
vm.propsVMBindScratch VM, trapped from props.vm using bindOnce
vm.propsVMAssignScratch VM, trapped from props.vm using assignOnce
threadThread object used in Scratch VMMany
ScratchBlocksScratchBlocks objectOnce
workspaceScratchBlocks workspaceOnce

addon.tab.traps.onceValues

onceValues attribute of addon.tab.traps stores references for “Once” traps. It is an prototypeless object - e.g. you cannot call onceValues.hasOwnProperty().

Keys are the “trap name” listed above, and values are the trapped values.

Example: to get VM object, use addon.tab.traps.onceValues.vm

addon.tab.traps.getBlockly

Return valuePromise<object>
Promise rejects ifThe addon isn't running on a project

Gets the instance of Blockly being used by Scratch. This is different from window.Blockly.

addon.tab.traps.getPaper

Return valuePromise<object>
Promise rejects ifThe addon isn't running on a project, or if Paper couldn't be found

Gets the instance of Paper being used by Scratch. (@scratch/paper)

addon.tab.traps.getInternalKey

ParameterTypeRequiredDescription
elementHTMLElementYesThe reference element
Return valueString

Gets the internal key for React.

Events

addon.tab.traps itself is not an EventTarget. However, it’s possible to add or remove listeners, by using some public APIs. traps.addOnceListener/removeOnceListener is for “Once” traps, and addManyListener/removeManyListener is for “Many” traps. Note that listeners for “Once” objects can fire multiple times under some conditions, and may never fire if the object is trapped before loading the userscript.

These methods work like addEventListener/removeEventListener, but third argument is not supported at all. The first argument is for trap name; for example, if it needs to be fired when thread is trapped, do addManyListener("thread", callback). The second argument is callback function that can take one argument for CustomEvent object, which contains the trapped value.

The CustomEvent object passed to callback always has value attribute for trapped value, and may have trapName if the first argument for the listener is * (see below).

Special event: if the trap name passed to these methods is *, it will fire when any object for the category is trapped. For example, callback in addOnceListener("*", callback) gets fired whenever an object in Once category is trapped. To check what is trapped, the CustomEvent passed to the callback also has trapName attribute for the trap name.


Last updated at 22 April 2022 by RedGuy12 on commit 686f6b7. Improve this page.

Comments

Make sure to follow the code of conduct. You can see this comment section on GitHub Discussions, as well as editing and removing your comment.