js-cpp-protocol

JS Editor / C++ UI Communication Protocol

Overview

Notepadqq's editor uses Qt WebEngine (QWebEngineView) with Qt WebChannel (QWebChannel) for bi-directional communication between the native C++ UI and the JavaScript editor engine (either CodeMirror or Monaco). The C++ side is unaware of which engine is running — both engines implement the identical message protocol.

Architecture

┌───────────────────────────┐          QWebChannel           ┌──────────────────────────┐
│        C++ / Qt           │  ◄─────────────────────────►   │   JavaScript Editor      │
│                           │                                │                          │
│  Editor (editor.cpp)      │  signal: messageReceivedByJs   │  UiDriver.js             │
│    ├─ JsToCppProxy (QObject)│  ──────────────────────────►  │    ├─ QWebChannel bridge │
│    └─ CustomQWebView      │  ◄──────────────────────────  │    └─ messageReceived()   │
│                           │  slot: receiveMessage()        │                          │
│  EditorTabWidget          │                                │  app.js / app_monaco.js  │
│  MainWindow               │                                │    └─ event handlers     │
└───────────────────────────┘                                └──────────────────────────┘

Key Files

Communication Mechanism

Setup

1. C++ (editor.cpp:47-70): Creates a JsToCppProxy QObject (registered as "cpp_ui_driver"), creates a QWebChannel, sets it on the WebEngine page, and registers the proxy: channel->registerObject("cpp_ui_driver", m_jsToCppProxy).

2. JS (index.html:7 / index_monaco.html:7): Includes <script src="qrc:///qtwebchannel/qwebchannel.js"></script> (Qt's built-in WebChannel JS library).

3. JS (UiDriver.js:8-26): On DOMContentLoaded, creates new QWebChannel(qt.webChannelTransport, callback), obtains cpp_ui_driver = channel.objects.cpp_ui_driver, and connects to the messageReceivedByJs signal.

C++ → JS (Commands and Function Calls)

Two modes exist:

Synchronous (legacy/deprecated): sendMessage(msg, data)

• editor.cpp:374-382: Emits messageReceivedByJs signal, which Qt WebChannel delivers to JS.
• JS receives it via cpp_ui_driver.messageReceivedByJs.connect(...) and processes it immediately.

Asynchronous (preferred): asyncSendMessageWithResultP(msg, data)

• editor.cpp:389-430: Generates a unique message ID, wraps the message in [ASYNC_REQUEST] prefix + [ID=N] suffix.
• JS receives it, dispatches to registered handlers, then sends back [ASYNC_REPLY] with the same ID.
• C++ resolves the QtPromise::QPromise<QVariant> on receipt.

Message format for async:

C++ sends:  [ASYNC_REQUEST]C_CMD_GET_VALUE[ID=42]
JS replies: [ASYNC_REPLY]C_CMD_GET_VALUE[ID=42]

JS → C++ (Events)

JS calls UiDriver.sendMessage("J_EVT_*", data) which invokes cpp_ui_driver.receiveMessage(msg, data) (UiDriver.js:36).

C++ receives it in JsToCppProxy::receiveMessage() (editor.h:44), which emits messageReceived signal → Editor::on_proxyMessageReceived() (editor.cpp:143).

Message Naming Convention

Complete Message Reference

C_CMD_* — Commands (C++ → JS, no return value)

C_FUN_* — Function Calls (C++ → JS, return value via async reply)

J_EVT_* — Events (JS → C++, no return value)

Handler Registration Pattern (JS)

Handlers are registered in app.js or app_monaco.js:

UiDriver.registerEventHandler("C_CMD_SET_VALUE", function(msg, data, prevReturn) {
    editor.setValue(data);
});

Multiple handlers can be registered for the same message. They are called in registration order; each handler receives the previous handler's return value as prevReturn.

Async Flow in Detail

1. C++ generates a unique ID (messageIdentifier counter, editor.cpp:387).
2. C++ creates a promise and stores an AsyncReply{id, message, value, callback} in the asyncReplies list (editor.cpp:407-412).
3. C++ sends [ASYNC_REQUEST]C_FUN_GET_CURSOR[ID=42] via messageReceivedByJs signal (editor.cpp:414-418).
4. JS receives in UiDriver.messageReceived() (UiDriver.js:52-75), parses the real message and ID via regex /^\[ASYNC_REQUEST\](.*)\[ID=(\d+)\]$/, dispatches to handler(s), then sends back [ASYNC_REPLY]C_FUN_GET_CURSOR[ID=42] with the return value.
5. C++ receives in Editor::on_proxyMessageReceived() (editor.cpp:148-176), parses the ID via regex \\[ID=(\\d+)\\]$, looks up the matching AsyncReply, resolves the promise and/or calls the callback, then emits asyncReplyReceived.

C++ API for Sending Messages

// Legacy synchronous (deprecated — blocks event loop)
void sendMessage(const QString msg, const QVariant data);

// Modern async with QtPromise (preferred)
QtPromise::QPromise<QVariant> asyncSendMessageWithResultP(const QString msg, const QVariant data);

// Legacy future-based (deprecated — spins event loop in while())
std::shared_future<QVariant> asyncSendMessageWithResult(
    const QString msg, const QVariant data,
    std::function<void(QVariant)> callback = nullptr);

Adding a New Message

1. Choose the prefix: C_CMD_* if no return value, C_FUN_* if a return value is needed, J_EVT_* for JS-initiated notifications.
2. JS side: Register a handler via UiDriver.registerEventHandler("C_CMD_YOUR_MSG", handler) in both app.js and app_monaco.js.
3. C++ side: Call asyncSendMessageWithResultP("C_FUN_YOUR_MSG", data) (or the legacy API) from editor.cpp or a higher-level wrapper method in editor.h.
4. Handle the reply: If async, .then() on the returned promise or connect to asyncReplyReceived signal.
5. JS→C++ events: Just call UiDriver.sendMessage("J_EVT_YOUR_MSG", data) from JS and handle the parsed message in Editor::on_proxyMessageReceived().

Dual Editor Engine

Notepadqq ships two editor engines:

• CodeMirror (default): index.html + app.js
• Monaco (VS Code's editor): index_monaco.html + app_monaco.js

Both implement the identical message protocol. The C++ side selects the engine via Editor::useMonaco() (editor.cpp:33). Any new message must be implemented in both app.js and app_monaco.js.

Key Architecture Notes

• QWebChannel serialises all values as QVariant (C++) ↔ plain JS values (JSON-compatible types).
• JS-to-C++ messages use a callback parameter function(ret) {} even when the return value is unused — the QWebChannel bridge requires this for the method call to work.
• The UiDriver maintains a msgQueue for messages sent before the WebChannel is ready; they are flushed once QWebChannel initialises.
• C++ messages sent before the editor fires J_EVT_READY are queued and delivered once editorReady signal fires (editor.cpp:419-426).