Nextpad++ Developer Guide & Resources

Linux Compatibility

Nextpad++ for Linux is a native GTK 4 application built per-architecture — no Electron, no emulation layers. It ships as .deb, .rpm and Arch packages plus a Snap, for both x86_64 and ARM machines.

Plugin Development Guide

Applies to Nextpad++ for Mac 1.1.1. Version notes below mark messages that need a newer host; everything unmarked has been supported since the plugin system shipped.

Nextpad++ for Mac loads plugins as native .dylib dynamic libraries from ~/Library/Application Support/Nextpad++/plugins/PluginName/PluginName.dylib. The plugin contract lives in one header, NppPluginInterfaceMac.h, which mirrors the Windows PluginInterface.h + Notepad_plus_msgs.h. All NPPM_* and NPPN_* constants use the same integer values as Windows Notepad++, so plugin sources can share constants — and often whole files — between the two platforms.

Threading: messages may be sent from any thread; the host marshals UI work to the main thread. Messages that return a value block until that work completes; a few fire-and-forget messages (noted below) complete asynchronously. Graceful degradation: a message the host doesn't know falls through to a default handler and returns 0 — probe the result to stay compatible with older hosts.

Required Exports

Every plugin must export these 5 functions with C linkage and NPP_EXPORT visibility:

extern "C" NPP_EXPORT void        setInfo(NppData nppData);
extern "C" NPP_EXPORT const char*  getName(void);
extern "C" NPP_EXPORT FuncItem*    getFuncsArray(int *nbF);
extern "C" NPP_EXPORT void        beNotified(SCNotification *notifyCode);
extern "C" NPP_EXPORT intptr_t    messageProc(uint32_t msg, uintptr_t wParam, intptr_t lParam);

Core Data Structures

NppData — passed to setInfo():

struct NppData {
    NppHandle _nppHandle;              // routes NPPM_* messages
    NppHandle _scintillaMainHandle;    // primary editor (SCI_* messages)
    NppHandle _scintillaSecondHandle;  // secondary editor
    NppSendMessageFunc _sendMessage;   // function pointer (replaces Win32 SendMessage)
};

FuncItem — menu command descriptor:

struct FuncItem {
    char _itemName[64];        // UTF-8 menu text (NPP_MENU_ITEM_SIZE)
    PFUNCPLUGINCMD _pFunc;     // command callback (nullptr = separator)
    int _cmdID;                // host-assigned command ID
    bool _init2Check;          // initial checkmark state
    ShortcutKey *_pShKey;      // optional keyboard shortcut
};

ShortcutKey — includes macOS _isCmd modifier:

struct ShortcutKey {
    bool _isCtrl;   // Control key
    bool _isAlt;    // Option key
    bool _isShift;  // Shift key
    bool _isCmd;    // Command key (macOS-specific)
    UCHAR _key;     // virtual key code
};

A SendMessage(h, m, w, l) compatibility macro is provided by the header, so existing Windows plugin code like SendMessage(nppData._nppHandle, NPPM_*, w, l) compiles unchanged. Every plugin exports five C functions (no isUnicode — macOS plugins are always Unicode).

Key Differences from Windows

Implemented NPPM Messages

62 NPPM messages are handled by the macOS host (1.1.1), grouped below. Buffer IDs are opaque uintptr_t values, exactly as on Windows — compare, store, and pass them back, never dereference them. The host validates every buffer ID it receives, so a stale ID fails cleanly (0/-1) instead of crashing.

Editor & view

Buffers & documents

File operations

Language / lexer — the host maps its language names to the canonical Windows L_* enum, so language-aware Windows code ports unchanged. A buffer using a loaded User Defined Language reports L_USER (15); unknown/plain text reports L_TEXT (0).

Sessions

Paths & environment — each fills a caller-provided char* buffer (allocate ≥1024 bytes) with UTF-8; empty string when there is no current file.

UI: status bar, toolbar, menus, dark mode

There is no theme-change notification in the message system — observe NSApp.effectiveAppearance (KVO) or your view's viewDidChangeEffectiveAppearance for live dark-mode reactions.

ID allocation — cooperative allocators so plugins never collide on Scintilla resources. All three: wParam=count, lParam=int* receiving the first allocated ID.

Inter-plugin communication & subscriptions

Host / compatibility queries

Any other NPPM constant from the header is defined for source compatibility but not yet implemented: it returns 0 (and is logged once per session to the console). The full list of defines is in NppPluginInterfaceMac.h on GitHub.

Docking Panels — Windows-Named Surface (1.1.1+)

The classic Windows docking registration with mac types: docking code ports from a Windows plugin with a typedef swap and UTF-8 strings. Field names and order match the Windows tTbData (Docking.h).

typedef struct tTbData {
    void        *hClient;        // your NSView* (Windows: HWND)
    const char  *pszName;        // panel title, UTF-8
    int          dlgID;          // FuncItem index of your open/toggle command
    unsigned int uMask;          // DWS_DF_* docking style flags
    void        *hIconTab;       // accepted, ignored
    const char  *pszAddInfo;     // accepted, ignored
    struct { int32_t left, top, right, bottom; } rcFloat;  // ignored
    int          iPrevCont;      // ignored
    const char  *pszModuleName;  // your plugin module name
} tTbData;

uMask semantics:

• DWS_DF_CONT_LEFT / DWS_DF_CONT_RIGHT / DWS_DF_CONT_BOTTOM pick the default dock region. DWS_DF_CONT_TOP maps to the bottom (there is no top dock on macOS). Left/right panels stack vertically; bottom panels stack side-by-side.
• The user's remembered side for your panel always wins over the mask — Windows' "default docking values for first call of plugin" semantics. Users can move any panel between left / right / bottom with the dock buttons in its title bar.
• DWS_DF_FLOATING floats the panel on its first show.
• DWS_ICONTAB / DWS_ICONBAR / DWS_ADDINFO are accepted and ignored.

pszModuleName + dlgID double as session-restore metadata (the same declaration NPPM_DMM_SETPANELINFO makes): a panel visible at quit is reopened at the next launch by invoking your FuncItem at dlgID — so that command must be a plain open/toggle action with no other side effects.

Docking Panels — macOS-Native Surface (1.0.3+)

The original macOS registration, kept fully supported. The two surfaces share one registry: a view registered through either can be driven through both. All docking messages are safe to call from any thread.

Notifications Emitted by the Host

Delivered through your beNotified(SCNotification *scn) export with scn->nmhdr.code set to the notification and, where noted, scn->nmhdr.idFrom set to the buffer ID. The macOS host currently emits these nine:

The remaining Windows NPPN constants (NPPN_FILEBEFORESAVE, NPPN_FILEBEFORECLOSE, NPPN_DARKMODECHANGED, …) are defined in the header for source compatibility but are not currently emitted — code listening for them simply never fires, exactly as on an older Windows host.

Forwarded Scintilla (SCN_*) Notifications

The host forwards these editor notifications to beNotified, from whichever view generated them:

• SCN_CHARADDED
• SCN_MODIFIED — filtered to actual text/style modifications relevant to plugins
• SCN_UPDATEUI and SCN_PAINTED — opt-out available via NPPM_SETPLUGINSUBSCRIPTIONS
• SCN_AUTOCSELECTION and SCN_AUTOCCANCELLED
• SCN_DWELLSTART / SCN_DWELLEND — only raised after your plugin arms the dwell timer itself (SCI_SETMOUSEDWELLTIME); the host leaves it unset, so hover-calltip plugins pay for what they use and nobody else pays anything

During macro recording and playback SCN forwarding is suppressed (during recording your plugin is still notified, but with Scintilla's recorder paused) so plugin-initiated editor calls never leak into a user's macro as phantom actions. Forwarding is reentrancy-guarded: notifications your own handler provokes are not re-delivered. Everything else is available directly — send any SCI_* message through _scintillaMainHandle / _scintillaSecondHandle.

Quick Lifecycle Example

NPP_EXPORT void beNotified(struct SCNotification *scn) {
    switch (scn->nmhdr.code) {
        case NPPN_READY: {
            /* Register a docked panel, Windows-style */
            tTbData d = {0};
            d.hClient       = (__bridge void *)myPanelView;
            d.pszName       = "My Panel";
            d.dlgID         = 0;                  /* FuncItem 0 = "Show My Panel" */
            d.uMask         = DWS_DF_CONT_BOTTOM; /* default region; user's choice wins */
            d.pszModuleName = "MyPlugin";
            gPanelHandle = SendMessage(nppData._nppHandle,
                                       NPPM_DMMREGASDCKDLG, 0, (LPARAM)&d);
            break;
        }
        case NPPN_TBMODIFICATION:
            SendMessage(nppData._nppHandle, NPPM_ADDTOOLBARICON_FORDARKMODE,
                        funcItems[0]._cmdID, (LPARAM)"icon.png");
            break;
        case NPPN_BUFFERACTIVATED:
            /* scn->nmhdr.idFrom is the new buffer ID */
            break;
        case NPPN_SHUTDOWN:
            SendMessage(nppData._nppHandle, NPPM_DMM_UNREGISTERPANEL,
                        gPanelHandle, 0);
            break;
    }
}

Building a Plugin

Minimal CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(MyPlugin LANGUAGES CXX OBJCXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_OBJCXX_STANDARD 17)
set(CMAKE_CXX_VISIBILITY_PRESET hidden)
set(CMAKE_OSX_DEPLOYMENT_TARGET "12.0")
set(CMAKE_OSX_ARCHITECTURES "arm64;x86_64")

set(NPP_MACOS_DIR "/path/to/nextpad-plus-plus-macos")
set(SCINTILLA_INCLUDE "/path/to/scintilla/include")

add_library(MyPlugin SHARED src/MyPlugin.mm)
target_include_directories(MyPlugin PRIVATE
    ${NPP_MACOS_DIR}/src ${SCINTILLA_INCLUDE})
target_link_libraries(MyPlugin PRIVATE "-framework Cocoa")
set_target_properties(MyPlugin PROPERTIES PREFIX "" SUFFIX ".dylib")

Build — always as Release (a Debug build of a text-processing plugin can run 20–30× slower):

mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release .. && make -j$(sysctl -n hw.ncpu)

Install: copy MyPlugin.dylib to ~/Library/Application Support/Nextpad++/plugins/MyPlugin/ (the loader rule is <folder>/<folder>.dylib — folder name and dylib name must match) and restart Nextpad++. Reloading a plugin requires a full quit of the app, not just closing the window.

Submitting to the Plugin Registry

1. Create a GitHub repo, create a Release with a ZIP containing PluginName/PluginName.dylib
2. Compute SHA256: shasum -a 256 PluginName.zip
3. Add an entry to nppPluginList/pl.macos-arm64.json
4. Open a pull request — once merged, the plugin appears in Plugin Admin automatically

Configuration & Data Directory

All configuration lives under ~/.nextpad++/. To back up or migrate your setup, copy the entire directory.

Plugins should store config in plugins/Config/ by calling NPPM_GETPLUGINSCONFIGDIR in setInfo(). Do not hardcode ~/.nextpad++/ directly.

Contribute

Nextpad++ for Mac is open source under GPL v3. Contributions are welcome:

• Port a plugin — adapt to NppPluginInterfaceMac.h, build as universal dylib, submit to the plugin registry
• Report a bug — open an issue on GitHub
• Fix a bug or add a feature — fork the main repo, open a pull request
• Improve docs — PRs welcome on the website repo

Read more on the About page or meet the authors.