CodeEditSourceEditor Documentation

For complex features that require direct access to the underlying text view or text storage, use the TextViewCoordinator API. By implementing the TextViewCoordinator protocol, you can inject custom behavior into the editor as events occur (e.g., when text changes) without manually managing state or bindings. This is useful for implementing features like custom autocompletion or specialized text transformations.

To use a coordinator:

1. Create a class conforming to TextViewCoordinator.
2. Implement necessary methods like prepareCoordinator(controller:) or textViewDidChangeText(controller:).
3. Pass an instance of your coordinator into the coordinators array of the SourceEditor view.

final class AutoCompleteCoordinator: TextViewCoordinator {
    func prepareCoordinator(controller: TextViewController) { }

    func textViewDidChangeText(controller: TextViewController) {
        // Access controller.textView or controller.text to perform custom logic
        for cursorPosition in controller.cursorPositions where cursorPosition.range.location >= 5 {
            let location = cursorPosition.range.location
            let previousRange = NSRange(start: location - 5, end: location)
            let string = (controller.text as NSString).substring(with: previousRange)

            if string.lowercased() == "hello" {
                controller.textView.replaceCharacters(in: NSRange(location: location, length: 0), with: " world!")
            }
        }
    }
}

If you need to access the underlying NSTextView or NSTextStorage directly to implement complex features (like custom autocompletion or text manipulation), use the TextViewCoordinator API.

By implementing TextViewCoordinator and passing the instance into the coordinators array of SourceEditor (SwiftUI) or TextViewController (AppKit), you can intercept editor events.

Commonly used methods include:

• prepareCoordinator(controller:): Setup logic when the coordinator is initialized.
• textViewDidChangeText(controller:): Triggered when the text content changes. You can access the controller.textView and controller.text to perform manipulations.

class AutoCompleteCoordinator: TextViewCoordinator {
    func prepareCoordinator(controller: TextViewController) { }

    func textViewDidChangeText(controller: TextViewController) {
        for cursorPosition in controller.cursorPositions.reversed() where cursorPosition.range.location >= 5 {
            let location = cursorPosition.range.location
            let previousRange = NSRange(start: location - 5, end: location)
            let string = (controller.text as NSString).substring(with: previousRange)

            if string.lowercased() == "hello" {
                controller.textView.replaceCharacters(in: NSRange(location: location, length: 0), with: " world!")
            }
        }
    }
}

The SwiftUI API allows you to embed the editor into your views using the SourceEditor component. It supports two-way bindings for text, editor state (cursor position, scroll position, find panel text), and configuration (theme, font, indentation).

Key components for SwiftUI integration:

• $text: A binding to the editor's content.
• language: The language definition for the editor.
• configuration: A SourceEditorConfiguration object to set appearance (theme and font) and behavior (indentation options).
• state: A binding to a SourceEditorState object for tracking cursor and scroll positions.
• coordinators: An array of TextViewCoordinator instances for injecting custom logic.

import CodeEditSourceEditor

struct ContentView: View {
    @State var text = "let x = 1.0"
    @State var editorState = SourceEditorState()
    @State var theme = EditorTheme(...)
    @State var font = NSFont.monospacedSystemFont(ofSize: 11, weight: .regular)
    @State var indentOption = .spaces(count: 4)

    var body: some View {
        SourceEditor(
            $text,
            language: language,
            configuration: SourceEditorConfiguration(
                appearance: .init(theme: theme, font: font),
                behavior: .init(indentOption: indentOption)
            ),
            state: $editorState,
            coordinators: []
        )
    }
}

For SwiftUI applications, use the SourceEditor view. It provides a fast, efficient API with two-way bindings for state management.

Key features include:

• State Management: Use SourceEditorState to automatically track and control cursor positions, scroll positions, and find panel text via two-way bindings.
• Performance: For large documents, use an NSTextStorage object instead of a String to avoid unnecessary SwiftUI view updates.
• Configuration: Customize appearance (theme, font), behavior (indentation), layout (overscroll), and peripherals (minimap) using SourceEditorConfiguration.
• Extensibility: Inject custom behavior using TextViewCoordinator objects passed into the coordinators parameter.

import CodeEditSourceEditor

struct ContentView: View {
    @State var text = "let x = 1.0"
    @State var editorState = SourceEditorState()
    @State var theme = EditorTheme(...)
    @State var font = NSFont.monospacedSystemFont(ofSize: 11, weight: .regular)
    @State var indentOption = .spaces(count: 4)
    @State var editorOverscroll = 0.3
    @State var showMinimap = true
    @State var autoCompleteCoordinator = AutoCompleteCoordinator()

    var body: some View {
        SourceEditor(
            $text,
            language: .swift,
            configuration: SourceEditorConfiguration(
                appearance: .init(theme: theme, font: font),
                behavior: .init(indentOption: indentOption),
                layout: .init(editorOverscroll: editorOverscroll),
                peripherals: .init(showMinimap: showMinimap)
            ),
            state: $editorState,
            coordinators: [autoCompleteCoordinator]
        )
    }

    class AutoCompleteCoordinator: TextViewCoordinator {
        func prepareCoordinator(controller: TextViewController) { }

        func textViewDidChangeText(controller: TextViewController) {
            // Custom logic here
        }
    }
}

For AppKit applications, use TextViewController to manage the editor. You can initialize it with content, language settings, and a SourceEditorConfiguration.

To display the editor:

1. Initialize a TextViewController.
2. Add it as a child view controller to your parent controller.
3. Add the editorController.view to your view hierarchy.
4. Call editorController.view.viewDidMoveToSuperview() to ensure proper setup.

TextViewController supports advanced features like custom highlightProviders, undoManager integration, completionDelegate for code suggestions, and jumpToDefinitionDelegate.

// 1. Initialize the controller
let editorController = TextViewController(
    string: "let x = 10;",
    language: .swift,
    config: SourceEditorConfiguration(
        appearance: .init(theme: theme, font: font),
        behavior: .init(indentOption: .spaces(count: 4)),
        layout: .init(editorOverscroll: 0.3),
        peripherals: .init(showMinimap: true)
    ),
    cursorPositions: [CursorPosition(line: 0, column: 0)],
    highlightProviders: [],
    undoManager: nil,
    coordinators: [],
    completionDelegate: nil,
    jumpToDefinitionDelegate: nil
)

// 2. Add to view hierarchy
final class MyController: NSViewController {
    override func loadView() {
        super.loadView()
        addChild(editorController)
        view.addSubview(editorController.view)
        editorController.view.viewDidMoveToSuperview()
    }
}