Interface: CharlotteAPI

addons/api/api.CharlotteAPI

Table of contents

Methods

• appendToSharedSpace
• createBlockContextMenu
• getBlockly
• getPlatform
• getReactInternalPrefix
• getRedux
• getVM
• hashedScratchClass
• pendingReduxState
• waitForElement
• xmlEscape

Methods

appendToSharedSpace

appendToSharedSpace(element, space, order?): boolean

Append a element to a specific position in Scratch editor.

Parameters

Name	Type	Description
element	HTMLElement	The element you want to append to
space	SharedSpace	Where do you want to append
order?	number	The the order of the added element.

Returns

boolean

Whether element is applied successfully.

Example

const button = document.createElement('button');
button.className = 'charlotteButton';
button.innerHTML = '🌠 Charlotte';
button.addEventListener('click', () => {
    addon.app.openFrontend();
});

addon.api.appendToSharedSpace(button, 'afterSoundTab');

---

createBlockContextMenu

createBlockContextMenu(callback, options): any

Creates an item in the editor Blockly context menu by callback. Available only when Blockly exists.

Parameters

Name	Type	Description
callback	ContextMenuCallback	A function to modify context menu.
options	Partial<BaseContextMenuOptions>	Specify the callback's scope.

Returns

any

Example

Here's a example to modify context menu in Blockly:

addon.api.createBlockContextMenu((items: ContextMenuItem[], block: Blockly.Block, event: Blockly.Event) => {
    items.push({
        {
            enabled: true, // Whether the option is available
            text: '🌠 Meteor shower begins', // The display text of the option
            callback: () => console.log('🌠🌠🌠🌠'), // Triggers when option clicked
            separator: false // Whether displays a separator at the bottom of current option
        }
    });
}, {blocks: true}); // Only display in block's context menu

---

getBlockly

getBlockly(): Promise<RealBlockly>

Get Scratch's Blockly instance asynchronously. This won't available if you're in project page.

Returns

Promise<RealBlockly>

a promise that returns Blockly instance

---

getPlatform

getPlatform(): string

Get current platform.

Returns

string

platform alias, such as cc, cocrea

---

getReactInternalPrefix

getReactInternalPrefix(): string

Get current page's most likely react internal key. This method does not mean that react exists in this interface. This method is just a simple inference based on the platform.

Returns

string

React's internal prefix

---

getRedux

getRedux(): Promise<CharlotteRedux>

Get Charlotte's redux instance asynchronously. This won't available if current page doesn't have redux or hide it (Eg: Codingclip)

Returns

Promise<CharlotteRedux>

a promise that returns Charlotte's redux instance

---

getVM

getVM(): Promise<VM>

Get Scratch's VM instance asynchronously.

Returns

Promise<VM>

a promise that returns VM instance

---

hashedScratchClass

hashedScratchClass(...possibleClassNames): string

Get hashed className from unhashed className.

Parameters

Name	Type	Description
...possibleClassNames	string[]	all possible classNames

Returns

string

hashed className

---

pendingReduxState

pendingReduxState(condition, scope?): Promise<void>

Waiting until redux state marches condition.

Parameters

Name	Type	Description
condition	StatePendingCondition	The function to judge whether current state matches condition.
scope?	string[]	Which actions will trigger condition function.

Returns

Promise<void>

Example

await addon.api.pendingReduxState((state) => state.scratchGui?.mode?.isFullScreen);
console.log('The stage is full-screen!');

---

waitForElement

waitForElement(selector, options?): Promise<Element>

Waiting until selected element rendered.

Parameters

Name	Type	Description
selector	string	Selector string, syntax is same as querySelector.
options?	WaitForElementOptions	-

Returns

Promise<Element>

a promise that resolves requested element.

---

xmlEscape

xmlEscape(unsafe): string

Escape a string to be safe to use in XML content. CC-BY-SA: hgoebl https://stackoverflow.com/questions/7918868/ how-to-escape-xml-entities-in-javascript

Parameters

Name	Type	Description
unsafe	string	Unsafe string.

Returns

string

XML-escaped string, for use within an XML tag.