P1-06: Multiple selection / multi-cursor (Cmd+click)

[hybridmachine]

Description

Enable multiple cursors for simultaneous editing.

Implementation

• SCI_SETMULTIPLESELECTION(1) to enable
• SCI_SETADDITIONALSELECTIONTYPING(1) for typing at all cursors
• Cmd+click to add additional cursor
• Cmd+D to select next occurrence of current selection (add cursor)
• SCI_SETMULTIPASTE(SC_MULTIPASTE_EACH) for paste at each cursor
• Visual styling for additional carets and selections

Dependencies

• P1-05 (rectangular selection foundation)

Key Files

• macos/platform/main_phase7.mm

Sprint

Sprint 6 - Selection & Editing

[hybridmachine]

Implementation Plan

Overview

Multiple selection / multi-cursor support is partially enabled in the macOS port. scintilla_config.mm already sends SCI_SETMULTIPLESELECTION(1) and SCI_SETADDITIONALSELECTIONTYPING(1), which means Scintilla's internal multi-selection data structures are active. What is missing:

1. Cmd+click to add cursors — Scintilla on macOS/Cocoa uses a modifier key to signal "add selection." We need to configure which modifier that is.
2. Cmd+D to select next occurrence — This is NOT a built-in Scintilla feature. It requires custom logic: read the current selection, search forward, and call SCI_ADDSELECTION to create an additional selection at the found range.
3. Multi-paste behavior — SCI_SETMULTIPASTE(SC_MULTIPASTE_EACH) must be sent so paste inserts text at every cursor, not just the primary one.
4. Visual styling — Additional carets and selections need distinct colors/alpha so the user can see them.
5. Missing SCI message constants in npp_constants.h.

---

Step-by-step Implementation

Step 1: Add missing SCI message constants to npp_constants.h

• File: macos/platform/npp_constants.h
• Changes: Add the following Scintilla message and constant enums that are not yet defined:

// Multi-cursor / multi-selection messages
SCI_SETMULTIPASTE = 2614,
SCI_GETMULTIPASTE = 2615,
SCI_ADDSELECTION = 2573,
SCI_GETSELECTIONS = 2570,
SCI_SETADDITIONALCARETSVISIBLE = 2608,
SCI_GETADDITIONALCARETSVISIBLE = 2609,
SCI_SETADDITIONALCARETFORE = 2604,
SCI_SETADDITIONALSELFORE = 2600,
SCI_SETADDITIONALSELBACK = 2602,
SCI_SETADDITIONALSELALPHA = 2603,
SCI_GETSELECTIONNSTART = 2585,
SCI_GETSELECTIONNEND = 2587,
SCI_GETSELECTIONNCARET = 2583,
SCI_GETSELECTIONNANCHOR = 2584,
SCI_SETSELECTIONNCARET = 2582,
SCI_SETSELECTIONNANCHOR = 2583,
SCI_SETTARGETSTART = 2190,
SCI_SETTARGETEND = 2192,
SCI_SETTARGETRANGE = 2686,
SCI_SEARCHINTARGET = 2197,
SCI_SETSEARCHFLAGS = 2198,
SCI_GETLENGTH = 2006,
SCI_GETSELTEXT = 2161,
SCI_GETCURRENTPOS = 2008,
SCI_GETANCHOR = 2009,
SCI_SETMAINSELECTION = 2574,

// Multi-paste constants
SC_MULTIPASTE_ONCE = 0,
SC_MULTIPASTE_EACH = 1,

// Search flags
SCFIND_MATCHCASE = 0x4,

Note: Some of these may already exist. Only add the ones not already present. Verify against the existing enum entries before adding.

---

Step 2: Create multi_cursor.h / multi_cursor.mm module

• File (new): macos/platform/multi_cursor.h
• File (new): macos/platform/multi_cursor.mm
• Changes: Encapsulate all multi-cursor logic in a dedicated module, following the project pattern of one-concern-per-file.

multi_cursor.h:

#pragma once

#include "ScintillaBridge.h"

// Configure multi-cursor behavior on the given Scintilla view.
// Call once after Scintilla is created/configured.
void multiCursor_configure(ScintillaView* sci);

// Select the next occurrence of the current selection (Cmd+D behavior).
// If nothing is selected, selects the word under the caret first.
void multiCursor_selectNextOccurrence(ScintillaView* sci);

multi_cursor.mm — multiCursor_configure:

#include "multi_cursor.h"
#include "npp_constants.h"

void multiCursor_configure(ScintillaView* sci)
{
    // Multi-paste: insert at every cursor
    ScintillaBridge_sendMessage(sci, SCI_SETMULTIPASTE, SC_MULTIPASTE_EACH, 0);

    // Make additional carets visible
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALCARETSVISIBLE, 1, 0);

    // Style additional carets — use a distinct but visible color (orange-ish)
    // RGB packed as 0x00BBGGRR for Scintilla
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALCARETFORE, 0x0060C0FF, 0);

    // Style additional selections — light blue foreground, semi-transparent
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELFORE, 0, 0x00FF8040);
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELBACK, 1, 0x00FFD0A0);
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELALPHA, 70, 0);
}

multi_cursor.mm — multiCursor_selectNextOccurrence:

void multiCursor_selectNextOccurrence(ScintillaView* sci)
{
    // 1. Get current selection text
    sptr_t selLen = ScintillaBridge_sendMessage(sci, SCI_GETSELTEXT, 0, 0);
    if (selLen <= 1)
    {
        // Nothing selected — select the word under the caret first
        // (SCI_WORDSTARTPOSITION / SCI_WORDENDPOSITION approach,
        //  or simply send SCI_SELECTWORD = 2491 if available)
        // Then return so the user sees the first selection before adding more.
        ScintillaBridge_sendMessage(sci, 2491 /* SCI_SELECTWORD */, 0, 0);
        return;
    }

    // 2. Copy selection text into buffer
    std::vector<char> buf(selLen);
    ScintillaBridge_sendMessage(sci, SCI_GETSELTEXT, 0, reinterpret_cast<sptr_t>(buf.data()));

    // 3. Determine search start: end of the last added selection
    sptr_t numSel = ScintillaBridge_sendMessage(sci, SCI_GETSELECTIONS, 0, 0);
    sptr_t lastSelEnd = ScintillaBridge_sendMessage(sci, SCI_GETSELECTIONNEND, numSel - 1, 0);

    // 4. Search forward from lastSelEnd, wrapping around
    sptr_t docLen = ScintillaBridge_sendMessage(sci, SCI_GETLENGTH, 0, 0);

    ScintillaBridge_sendMessage(sci, SCI_SETSEARCHFLAGS, SCFIND_MATCHCASE, 0);
    ScintillaBridge_sendMessage(sci, SCI_SETTARGETRANGE, lastSelEnd, docLen);

    sptr_t found = ScintillaBridge_sendMessage(sci, SCI_SEARCHINTARGET,
        selLen - 1, reinterpret_cast<sptr_t>(buf.data()));

    if (found < 0)
    {
        // Wrap around: search from document start to the original search start
        ScintillaBridge_sendMessage(sci, SCI_SETTARGETRANGE, 0, lastSelEnd);
        found = ScintillaBridge_sendMessage(sci, SCI_SEARCHINTARGET,
            selLen - 1, reinterpret_cast<sptr_t>(buf.data()));
    }

    if (found < 0)
    {
        // No more occurrences
        return;
    }

    // 5. Add the found range as an additional selection
    sptr_t matchEnd = found + selLen - 1; // -1 for null terminator in selLen
    ScintillaBridge_sendMessage(sci, SCI_ADDSELECTION, matchEnd, found);

    // 6. Scroll the new selection into view
    ScintillaBridge_sendMessage(sci, SCI_SCROLLCARET, 0, 0);
}

---

Step 3: Enable Cmd+click for adding cursors in scintilla_config.mm

• File: macos/platform/scintilla_config.mm
• Changes: Scintilla on macOS/Cocoa checks the rectangular-selection modifier to determine which key adds cursors on click. On macOS, the Super (Cmd) key corresponds to modifier value SCMOD_SUPER (typically 8). We need to call SCI_SETRECTANGULARSELECTIONMODIFIER with the correct value. However, for adding individual cursors (not rectangular selection), Cocoa Scintilla uses the Ctrl modifier by default on macOS. Since macOS convention is Cmd+click, and Cocoa Scintilla already translates Cmd to the "additional selection" modifier internally, we should verify behavior and only intervene if the default doesn't work.

Add after the existing multi-selection setup calls:

// Tell Scintilla that the Cmd key (SCMOD_SUPER = 8) is used
// for rectangular / additional selection on macOS
ScintillaBridge_sendMessage(sci, SCI_SETRECTANGULARSELECTIONMODIFIER, 8 /* SCMOD_SUPER */, 0);

Important validation: The Cocoa Scintilla port may already handle Cmd+click natively for multi-cursor. If testing reveals Cmd+click already works after Step 1's SCI_SETMULTIPLESELECTION(1), this message may be unnecessary. Test before finalizing.

---

Step 4: Call multiCursor_configure from initialization

• File: macos/platform/scintilla_config.mm
• Changes: After the existing SCI_SETMULTIPLESELECTION / SCI_SETADDITIONALSELECTIONTYPING calls, invoke multiCursor_configure(sci) to set multi-paste and visual styling.

#include "multi_cursor.h"

// ... existing code ...
ScintillaBridge_sendMessage(sci, SCI_SETMULTIPLESELECTION, 1, 0);
ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELECTIONTYPING, 1, 0);
ScintillaBridge_sendMessage(sci, SCI_SETVIRTUALSPACEOPTIONS, SCVS_RECTANGULARSELECTION, 0);

// Configure multi-cursor paste behavior and visual styling
multiCursor_configure(sci);

---

Step 5: Wire up Cmd+D keyboard shortcut

• File: macos/platform/keyboard_shortcuts.mm
• Changes: Add a Cmd+D binding that triggers the "Select Next Occurrence" action. There are two approaches — choose based on existing pattern in the codebase:

Option A — Scintilla key binding to a command ID:
Map Cmd+D to a custom WM_COMMAND ID (e.g., IDM_EDIT_SELECT_NEXT_OCCURRENCE) and handle it in the command dispatcher.

// In keyboard_shortcuts.mm, add to the shortcut configuration:
// Cmd+D -> Select Next Occurrence
// 'D' = 68, SCMOD_META (Cmd on macOS) = 16 (or SCMOD_SUPER = 8, verify)

Option B — NSMenuItem with key equivalent:
Add a menu item under the Edit menu with key equivalent Cmd+D. This is likely the cleaner approach since menu_builder.mm already constructs menus.

---

Step 6: Add Cmd+D menu item and command dispatch

• File: macos/platform/menu_builder.mm
• Changes: Under the Edit menu, add a "Select Next Occurrence" item with Cmd+D shortcut, mapped to a new command ID.

// Add to Edit menu section:
AppendMenuW(hEditMenu, MF_STRING, IDM_EDIT_SELECT_NEXT_OCCURRENCE,
    L"Select Next Occurrence\tCmd+D");

• File: macos/platform/npp_constants.h
• Changes: Add command constant:

IDM_EDIT_SELECT_NEXT_OCCURRENCE = 42080, // Pick an unused ID in the IDM_EDIT range

• File: macos/platform/wndproc.mm
• Changes: Handle the command in the WM_COMMAND dispatcher:

case IDM_EDIT_SELECT_NEXT_OCCURRENCE:
{
    ScintillaView* sci = ctx().activeScintillaView();
    if (sci)
    {
        multiCursor_selectNextOccurrence(sci);
    }
    return 0;
}

---

Step 7: Register new source files in CMakeLists.txt

• File: macos/CMakeLists.txt
• Changes: Add multi_cursor.h and multi_cursor.mm to the source file list, following the existing pattern for platform source files.

macos/platform/multi_cursor.h
macos/platform/multi_cursor.mm

---

Step 8: Handle Dark Mode styling for additional carets/selections

• File: macos/platform/multi_cursor.mm
• Changes: If the project has dark mode support (check AppContext or theme state), adjust the additional caret and selection colors accordingly. Provide a second set of colors for dark backgrounds:

void multiCursor_configure(ScintillaView* sci)
{
    ScintillaBridge_sendMessage(sci, SCI_SETMULTIPASTE, SC_MULTIPASTE_EACH, 0);
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALCARETSVISIBLE, 1, 0);

    // TODO: Query current theme (dark vs light) from AppContext
    // and select appropriate colors.
    // Light theme:
    //   caret: 0x0060C0FF (orange), sel back: 0x00FFD0A0, alpha: 70
    // Dark theme:
    //   caret: 0x0000AAFF (bright orange), sel back: 0x00804020, alpha: 90

    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALCARETFORE, 0x0060C0FF, 0);
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELBACK, 1, 0x00FFD0A0);
    ScintillaBridge_sendMessage(sci, SCI_SETADDITIONALSELALPHA, 70, 0);
}

---

Design Decisions

Decision	Choice	Rationale
Separate multi_cursor.h/.mm module	New files	Follows project pattern of one-concern-per-file. Keeps scintilla_config.mm focused on initial setup. Multi-cursor logic (especially Cmd+D) is non-trivial and deserves its own module.
Cmd+D as menu item (not raw key handler)	Menu item in Edit menu	Consistent with how other shortcuts work in the port (via menu_builder.mm + wndproc.mm). Provides discoverability. Menu items with key equivalents are the standard macOS pattern.
Case-sensitive search for Cmd+D	SCFIND_MATCHCASE	Matches VS Code / Sublime behavior. If the user selected "Foo", they want to multi-select other "Foo" instances, not "foo".
Wrap-around search for Cmd+D	Search from end of last selection, wrap to document start	Standard behavior in all editors with this feature. Ensures all occurrences can be reached.
Select word first if nothing selected	SCI_SELECTWORD on first Cmd+D	Matches VS Code/Sublime UX: first Cmd+D selects word under caret, subsequent presses add next occurrence.
SCMOD_SUPER for Cmd+click	SCI_SETRECTANGULARSELECTIONMODIFIER(8)	On macOS, Cmd maps to SCMOD_SUPER. This tells Scintilla that Cmd+click should add cursors, matching macOS conventions. Needs testing — Cocoa Scintilla may handle this automatically.
Colors for additional carets	Orange caret, light blue selection background	High visibility on both light and dark backgrounds. Distinct from primary caret (usually black/white).

---

Edge Cases

Scenario	Expected Behavior
Cmd+D with no selection and caret on whitespace	Select the whitespace "word" (spaces/tabs). Scintilla's SCI_SELECTWORD handles this. Subsequent Cmd+D searches for that whitespace sequence.
Cmd+D when all occurrences are already selected	No-op. SCI_SEARCHINTARGET returns -1 after wrap-around finds only already-selected ranges. The function returns without adding a duplicate.
Cmd+D wraps around past beginning of document	After searching to end-of-doc fails, search wraps from position 0 to the start of the first search. Prevents infinite loop.
Paste with multiple cursors	Text is inserted at each cursor independently (SC_MULTIPASTE_EACH). If clipboard has N lines and there are N cursors, each line goes to each cursor (Scintilla built-in behavior).
Cmd+click on existing cursor position	Scintilla handles this — clicking on an existing additional selection removes it (toggle behavior).
Undo after multi-cursor edit	Scintilla groups multi-cursor edits as a single undo action automatically. One Cmd+Z undoes the edit at all cursor positions.
Split view: Cmd+D in secondary view	ctx().activeScintillaView() ensures the command targets whichever Scintilla view is focused. No special handling needed.
Cmd+D finding an occurrence that overlaps with an existing selection	Skip it and continue searching. Need to check if found position falls within any existing selection range before adding.
Very large file with many occurrences	Performance is bounded by Scintilla's SCI_SEARCHINTARGET which is efficient (linear scan). Each Cmd+D press adds one selection — no risk of selecting thousands at once.
Dark mode toggle while additional carets are visible	If theme-change notification exists, re-call multiCursor_configure to update colors. Otherwise, colors persist until next editor creation.

---

Testing Plan

• Cmd+click adds cursor: Open a file, Cmd+click at 3 different positions. Verify 3 carets are visible. Type a character — it appears at all 3 positions.
• Cmd+click removes cursor: With multiple cursors active, Cmd+click on an existing cursor. Verify it is removed.
• Cmd+D selects word: Place caret inside a word with no selection. Press Cmd+D. Verify the word is selected.
• Cmd+D adds next occurrence: Select a word, press Cmd+D multiple times. Verify each press highlights the next occurrence in the document.
• Cmd+D wraps around: With caret near end of file, select a word that also appears near the beginning. Press Cmd+D until it wraps. Verify the occurrence near the top is found.
• Cmd+D no more occurrences: Select a unique string. Press Cmd+D. Verify no additional selection is added (no-op).
• Multi-cursor typing: Add 3 cursors. Type "hello". Verify "hello" appears at all 3 locations.
• Multi-cursor backspace: Add 3 cursors. Press backspace. Verify one character is deleted at each cursor position.
• Multi-cursor paste (single line): Copy "test", add 3 cursors, paste. Verify "test" is inserted at all 3 positions.
• Multi-cursor paste (multi-line to matching cursors): Copy 3 lines, create 3 cursors, paste. Verify each line goes to its corresponding cursor.
• Escape clears additional cursors: Add multiple cursors, press Escape. Verify only the primary cursor remains.
• Undo groups multi-cursor edit: Type with 3 cursors, then Cmd+Z. Verify all 3 insertions are undone in one step.
• Split view isolation: Open split view. Add cursors in left view. Verify right view is unaffected. Cmd+D in right view targets right view only.
• Additional caret visibility: Verify additional carets are visually distinct (orange or configured color) from the primary caret.
• Additional selection highlighting: Verify additional selections have a visible background highlight with appropriate transparency.
• Menu item present: Open Edit menu. Verify "Select Next Occurrence" appears with Cmd+D shortcut shown.

---

File Change Summary

File	Action
macos/platform/npp_constants.h	Modify — add missing SCI message constants and command ID
macos/platform/multi_cursor.h	Create — header for multi-cursor module
macos/platform/multi_cursor.mm	Create — implementation: configure + selectNextOccurrence
macos/platform/scintilla_config.mm	Modify — add multiCursor_configure() call and SCI_SETRECTANGULARSELECTIONMODIFIER
macos/platform/keyboard_shortcuts.mm	Modify — potentially add Cmd+D binding (if not handled via menu item)
macos/platform/menu_builder.mm	Modify — add "Select Next Occurrence" menu item under Edit
macos/platform/wndproc.mm	Modify — handle IDM_EDIT_SELECT_NEXT_OCCURRENCE command
macos/CMakeLists.txt	Modify — add new source files

---

Estimated Size

Medium (M) — 2 new files (~120 lines total), 5 existing files modified with small targeted changes. The core complexity is in multiCursor_selectNextOccurrence (~50 lines of logic). All other changes are configuration calls and wiring.

[hybridmachine]

Important concerns before this moves forward:

1. Cmd+D conflicts with the current Duplicate Line shortcut (IDM_EDIT_DUP_LINE) and likely with other planned shortcuts.
2. Several proposed SCI constants look unverified (some are likely incorrect/duplicated). Please source values from Scintilla headers and add only truly missing constants.
3. Don’t repurpose SCI_SETRECTANGULARSELECTIONMODIFIER from Alt to Cmd unless testing proves it’s required — that risks regressing rectangular selection UX.
4. Please follow this repo’s macOS color-int convention when setting selection/caret colors.

I recommend an incremental MVP: validate Cmd+click behavior first, then add “select next occurrence” with a non-conflicting shortcut.

[hybridmachine]

Amended Implementation Plan

This amends the original implementation plan based on review feedback. Only changes and clarifications are listed below.

Feedback Acknowledgment & Responses

1. Cmd+D Conflict with Duplicate Line
Agreed — Cmd+D is already bound to IDM_EDIT_DUP_LINE (42034). The "Select Next Occurrence" shortcut is changed to Cmd+Shift+D to avoid the conflict.

2. SCI Constants Must Be Verified
Agreed — all SCI constants will be sourced directly from the vendored scintilla/include/Scintilla.h header. No constants will be assumed or duplicated. A verification checklist is included below.

3. Do NOT Repurpose SCI_SETRECTANGULARSELECTIONMODIFIER
Agreed — we will not change the rectangular selection modifier from Alt/Option. On macOS Cocoa, Scintilla already defaults to Cmd+click for multi-cursor/multi-selection (the Cocoa platform layer sets this). We just need to verify this works with the existing configuration and enable SCI_SETMULTIPLESELECTION, SCI_SETADDITIONALSELECTIONTYPING, and SCI_SETMULTIPASTE. No modifier reassignment needed.

4. macOS BGR Color-Int Convention
Agreed — all color values will use BGR format consistent with the rest of the codebase (e.g., 0xFF8000 for orange in BGR, not RGB).

5. Incremental MVP Approach
Agreed — splitting into two phases as recommended.

---

Updated Plan

Phase 1 — Multi-Cursor Core (MVP)

Enable Cmd+click multi-cursor with proper visual feedback and multi-paste.

Changes in ScintillaEditView.cpp (init method):

• Call SCI_SETMULTIPLESELECTION(1) — enable multiple selections
• Call SCI_SETADDITIONALSELECTIONTYPING(1) — typing applies to all cursors
• Call SCI_SETMULTIPASTE(SC_MULTIPASTE_EACH) — paste into each selection
• Call SCI_SETADDITIONALCARETFORE(color) — set additional caret color (BGR format)
• Call SCI_SETADDITIONALSELALPHA(alpha) — set additional selection transparency
• Do not call SCI_SETRECTANGULARSELECTIONMODIFIER — leave default behavior

No shortcut changes in Phase 1. Cmd+click should work out of the box on Cocoa Scintilla.

Phase 2 — Select Next Occurrence

Add "Select Next Occurrence" command bound to Cmd+Shift+D.

Changes:

• Add command handler in NppBigSwitch.cpp / NppCommands.cpp that uses SCI_SEARCHINTARGET + SCI_ADDSELECTION to find and select the next occurrence of the current selection
• Bind to Cmd+Shift+D in the macOS menu/shortcut system
• Ensure no conflict with existing shortcuts

---

SCI Constant Verification Checklist

Before implementation, each constant must be verified against scintilla/include/Scintilla.h:

• SCI_SETMULTIPLESELECTION — verify message ID
• SCI_SETADDITIONALSELECTIONTYPING — verify message ID
• SCI_SETMULTIPASTE — verify message ID
• SC_MULTIPASTE_EACH — verify enum value
• SCI_SETADDITIONALCARETFORE — verify message ID
• SCI_SETADDITIONALSELALPHA — verify message ID
• SCI_GETSELECTIONS — verify message ID (Phase 2)
• SCI_GETSELECTIONSTART / SCI_GETSELECTIONEND — verify message IDs (Phase 2)
• SCI_SETTARGETRANGE — verify message ID (Phase 2)
• SCI_SEARCHINTARGET — verify message ID (Phase 2)
• SCI_ADDSELECTION — verify message ID (Phase 2)

Any constant not found in the vendored header will not be used.

---

Updated File Change Summary

File	Phase	Change
scintilla/include/Scintilla.h	—	Reference only, no modifications
PowerEditor/src/ScintillaComponent/ScintillaEditView.cpp	1	Add multi-selection init calls
PowerEditor/src/NppCommands.cpp	2	Add Select Next Occurrence command
PowerEditor/src/NppBigSwitch.cpp	2	Wire up Cmd+Shift+D to new command
macOS menu/shortcut config	2	Add Cmd+Shift+D binding

---

Testing Plan

Phase 1:

• Cmd+click places multiple cursors at clicked positions
• Typing with multiple cursors inserts at all positions simultaneously
• Paste with multiple cursors pastes into each selection
• Additional carets/selections are visually distinguishable (color, alpha)
• Alt/Option+drag still performs rectangular selection (no regression)
• Single-click still clears all selections and places one cursor

Phase 2:

• Select a word, press Cmd+Shift+D — next occurrence is added to selection
• Repeated Cmd+Shift+D adds subsequent occurrences
• Cmd+D still duplicates the current line (no regression)
• Works correctly across wrapped lines and with various encodings