Lumacs/documentation/GUI_ROADMAP.md

GUI Frontend Roadmap: Lumacs with GTK4 (gtkmm)

This document outlines the phased approach to integrate a graphical frontend into Lumacs, utilizing GTK4 with its C++ bindings (gtkmm). The goal is to provide a rich, native user experience while leveraging the existing C++ core and Lua extensibility.

Phase 0: Preparation (Current State)

• Status: Complete
• Description: Core editor logic (EditorCore, Buffer) is decoupled from the UI. An abstract Face system is implemented, allowing for UI-agnostic styling definitions.
• Key Achievements:
  • Abstract Face system in include/lumacs/face.hpp
  • Theme system refactored to manage Face definitions
  • Buffer stores face_name for styling ranges
  • NcursesEditor renders Faces to best of its ability (colors, bold, italic)

Phase 1: Abstract UI Interface Extraction

• Goal: Define a clean separation between EditorCore and any UI frontend.
• Tasks:
  1. Define IEditorView Interface: Create an abstract base class (e.g., IEditorView or EditorFrontend) in include/lumacs/ui_interface.hpp that EditorCore will interact with. This interface will declare methods for:
     • Receiving buffer content updates.
     • Receiving cursor position changes.
     • Receiving messages.
     • Requesting input (e.g., for minibuffer).
     • Triggering UI mode changes (Command, FindFile, etc.).
     • Rendering updates.
  2. Refactor NcursesEditor:
     • Rename NcursesEditor to TuiEditor.
     • Make TuiEditor implement IEditorView.
     • Modify EditorCore to hold a pointer/reference to IEditorView instead of tightly coupled NcursesEditor logic.
     • Update main.cpp (or main_ncurses.cpp) to instantiate TuiEditor and pass it to EditorCore.
  3. Refine EditorEvent Usage: Ensure EditorCore communicates solely via IEditorView or its existing event system (EditorEvent).
• Output: A decoupled EditorCore that can interact with any IEditorView implementation.
• Dependencies: Existing C++ codebase.

Phase 2: GTK4 Environment Setup & Basic Window

• Goal: Integrate GTK4 into the build system and display a minimal window.
• Tasks:
  1. Update CMakeLists.txt: Add find_package(PkgConfig REQUIRED) and pkg_check_modules(GTKMM REQUIRED gtkmm-4.0). Add GTKMM include directories and link libraries.
  2. Create main_gtk.cpp: A new entry point for the GTK frontend.
  3. Implement GtkEditor Stub: Create a placeholder class GtkEditor that inherits from IEditorView.
  4. Basic GTK Window: In main_gtk.cpp, initialize GTK, create a simple Gtk::Application and Gtk::Window, and show it.
  5. Conditional Build: Configure CMake to allow building either lumacs (TUI) or lumacs-gtk (GUI) executables based on a flag (e.g., -DBUILD_GUI=ON).
• Output: A separate lumacs-gtk executable that opens an empty GTK window.
• Dependencies: gtkmm-4.0 development libraries.

Phase 3: Displaying Buffer Content

• Goal: Render the active buffer's text content within the GTK window.
• Tasks:
  1. Gtk::DrawingArea: Use a Gtk::DrawingArea to draw text.
  2. Pango/Cairo Integration: Learn how to use Pango for text layout and Cairo for drawing on the DrawingArea.
  3. Text Display: Get the current buffer content from EditorCore and render it.
  4. Scrolling: Implement basic vertical scrolling.
• Output: A GTK window displaying the text of the active buffer.
• Dependencies: Pango, Cairo.

Phase 4: Styling with Faces

• Goal: Implement the Face system within GtkEditor to render styled text.
• Tasks:
  1. Pango Attributes: Map Lumacs FaceAttributes to Pango attributes (foreground, background, weight, slant, underline, font family, font size).
  2. Styled Text Rendering: Iterate through StyledRange objects from the Buffer and apply the corresponding Pango attributes before drawing text segments.
  3. Theme Integration: Ensure the active theme's face definitions are applied to the rendered text.
• Output: A GTK window displaying syntax-highlighted and styled text according to the active theme.

Phase 5: Input Handling & Minibuffer

• Goal: Capture keyboard input and integrate with the minibuffer and other interactive UI elements.
• Tasks:
  1. Keyboard Input: Connect GTK keyboard events to EditorCore's key processing.
  2. Cursor Display: Render a blinking cursor in the DrawingArea.
  3. Minibuffer Input: Implement a Gtk::Entry for the minibuffer (command input, find file, etc.).
  4. Completion Popup: Implement a GTK popup for minibuffer completion suggestions.
• Output: Fully interactive text editor with working cursor and minibuffer.

Phase 6: Full UI Feature Parity

• Goal: Implement all existing features of TuiEditor (window splits, status lines, messages, marks, regions) in GtkEditor.
• Tasks:
  1. Status Line/Modelines: Render status bars for each window.
  2. Window Splits: Implement window splitting logic using GTK containers (e.g., Gtk::Paned or Gtk::Grid).
  3. Selection/Regions: Visually render active text selections.
  4. Context Menus/Dialogs: Implement GTK equivalents for any UI popups.
• Output: A fully functional GUI frontend with feature parity to the TUI.

Future Considerations

• High-DPI Support: Ensure crisp rendering on high-resolution displays.
• Accessibility: Integrate with GTK's accessibility features.
• Native File Dialogs: Use Gtk::FileChooserDialog for find-file and save-as.