document_editor.py Chromium-Based WYSIWYG Rich Text Editor for PySide6

📄 4,317 lines  |  📦 PySideAbdhUI Package  |  ⚙ Python 3.10+ / PySide6

document_editor.py implements a fully-featured WYSIWYG (What You See Is What You Get) rich text editor widget for desktop applications built with the PySide6 (Qt for Python) framework. The editor is built on top of QWebEngineView, which embeds a Chromium rendering engine inside a native Qt widget. This hybrid architecture leverages the power of modern web technologies — HTML, CSS, and JavaScript — for the editing surface, while the surrounding Qt infrastructure handles desktop integration concerns such as native file dialogs, context menus, colour pickers, and window management.

The editor presents itself as a multi-page document layout, where each page is a <div class="page"> element with fixed CSS dimensions that correspond to a real paper size (A4, Letter, B5, or a custom "Edu-Item" format). Content overflow is automatically managed by a JavaScript pagination engine that pushes overflowing blocks onto subsequent pages and pulls underflowing content back when space becomes available. This approach gives users a real-time preview of how their document will look when printed or exported to PDF.

Key capabilities of the editor include: KaTeX-based mathematical formula rendering with inline and display modes, image insertion with drag-and-drop repositioning and 8-directional resize handles, table editing with column resizing and row/column insertion, PDF import via Mozilla's pdf.js library, PDF export using Chromium's built-in renderer, and DOCX/ODT import/export via pypandoc. The editor also supports zoom, page navigation, margin control, text formatting (bold, italic, underline, strikethrough, font family, font size, text and background colours), paragraph alignment, and bidirectional text support.

Architecture

The system follows a layered architecture where the Python RichTextEditor class acts as the controller, the Chromium QWebEngineView as the rendering engine, and an embedded HTML document as the editing surface. The following diagram illustrates the high-level component relationships and data flow between the layers.

Python → JavaScript Communication

The primary channel for Python-to-JavaScript communication is the QWebEnginePage.runJavaScript() method. This is an asynchronous API — Python submits a JavaScript string for execution, and an optional callback receives the result. The RichTextEditor class uses this mechanism extensively: every formatting command, content manipulation, page size change, and zoom operation is implemented as a JavaScript fragment dispatched through runJavaScript().

For operations that require a synchronous result (such as reading the editor's HTML content before a Pandoc export), the class employs a QEventLoop to block the calling thread until the asynchronous JavaScript callback fires. This pattern is visible in methods like getHtmlContentSync() and getPlainTextSync().

JavaScript → Python Communication

The reverse direction uses a creative "document title" bridge. When the user edits content in the browser, the JavaScript input event listener sets document.title to a string starting with "__edit__" followed by a timestamp. On the Python side, the page().titleChanged signal is connected to _on_title_changed(), which interprets this prefix as a notification that the document has been modified and sets the _is_dirty flag accordingly.

Dependencies

Standard Library

PySide6 (Qt for Python)

Package-Internal

Class: DebugPage

DebugPage is a lightweight subclass of QWebEnginePage that overrides the javaScriptConsoleMessage() virtual method. By default, Chromium silently discards JavaScript console output when running inside a QWebEngineView. This class intercepts every message written to the browser console (via console.log(), console.warn(), console.error(), etc.) and mirrors it to the Python standard output, prefixed with the source line number. This makes debugging of the embedded JavaScript significantly easier during development and testing.

Class: RichTextEditor

RichTextEditor is the main public widget and the heart of the module. It inherits from QWebEngineView and provides a complete WYSIWYG editing experience inside a Chromium-based web view. The class exposes a rich public API for text formatting, content management, page layout control, file import/export, and more, while delegating all visual editing operations to JavaScript running inside the embedded HTML document.

Constructor & Initialization

Dirty Tracking

The editor tracks whether the document contains unsaved modifications through the _is_dirty boolean flag. When the user types, deletes, or otherwise modifies content, the JavaScript input event listener sets document.title to "__edit__<timestamp>", which triggers the _on_title_changed() slot on the Python side and sets _is_dirty = True. The flag can also be set manually via _mark_dirty(), and is cleared when the document is saved via setClean(). The current state is queryable through isModified().

Print Preparation

Before generating a PDF or initiating a print operation, the editor must ensure that its internal page structure is consistent and that no blank trailing pages will appear in the output. The _preparePrintBreaks() method executes JavaScript that removes empty trailing pages and sets a temporary data-print-ready attribute on every remaining page element. After the export completes, _cleanupPrintBreaks() removes these markers and triggers a full page-consistency check.

Image Export (Page-by-Page PNG Capture)

The extractAsImages() method provides a mechanism to capture each logical editor page as a separate PNG image file. The capture process is multi-step and asynchronous, using a callback chain that processes pages one at a time:

For each page, the widget is temporarily resized to match the page dimensions exactly at zoom 1.0, the viewport is scrolled to the correct position, and after a 200 ms rendering delay, self.grab() captures the widget contents as a QPixmap. After all pages are captured, the original widget size, zoom, and size constraints are restored, and the user is prompted to select an output directory. Each image is saved as page_1.png, page_2.png, etc.

Context Menus

The editor disables Chromium's default right-click context menu and replaces it with custom Qt menus that are context-aware. When the user right-clicks inside a table cell (<td> or <th>), a table-specific menu appears with options to insert rows and columns. For all other locations, the standard editing menu is shown.

Default Menu Actions

Table Menu Actions

When right-clicking inside a table cell, the menu adds the following actions above a "Text Format" submenu containing all the default actions:

• Insert Row Above — adds a new empty row above the current row
• Insert Row Below — adds a new empty row below the current row
• Insert Column Left — adds a new empty column to the left of the current column
• Insert Column Right — adds a new empty column to the right of the current column

KaTeX Resource Loader

The _load_katex_resource() method reads KaTeX library files (CSS and JavaScript) from the application's packaged resources and converts them into base64 data-URI strings that can be embedded directly in the <link> and <script> tags of the editor HTML. This approach avoids filesystem path issues and makes the editor self-contained regardless of the installation directory.

If a KaTeX resource file is not found, the method returns an empty string, and the corresponding tag is replaced with an HTML comment in _build_initial_html(). This graceful degradation ensures the editor still loads and functions even when KaTeX is unavailable — math formulas simply won't be rendered.

PDF Library Lazy Loading

The PDF-related JavaScript libraries (pdf.js, pdf.worker, and pdf-lib) are not embedded in the initial HTML document to keep page load times fast and avoid errors when the files are missing. Instead, they are loaded on-demand when the user first opens a PDF file. Once loaded, the base64 data is cached in instance variables to prevent repeated disk reads.

Page Margins

Page margins are stored as a dictionary of four float values (top, right, bottom, left) in millimetres. They are applied as CSS padding on each .page div, determining the printable content area. Margins can be changed programmatically via setPageMargins() or interactively through the showMarginDialog() modal dialog, which provides four QDoubleSpinBox controls (range 0–50 mm, step 1 mm). When margins change, a full pagination recalculation is triggered via checkAllPages().

File Open/Save Dialogs

PDF Import

PDF import is handled by Mozilla's pdf.js library, which is lazily injected into the editor page only when a PDF file is first opened. The import pipeline works as follows:

1. The raw PDF bytes are read from disk and encoded as base64.
2. _ensurePdfJsLoaded() checks whether pdf.js has already been injected; if not, it loads the base64-encoded pdf.min.js and pdf.worker.min.js from cached resources and injects them into the Chromium page via runJavaScript().
3. Once the library is available, _buildPdfRenderJs() generates JavaScript that decodes the base64 PDF data and renders each page sequentially.
4. Each PDF page is rendered to an off-screen canvas at 2× display scale for sharpness, converted to a PNG data-URL, and inserted into the editor as an <div class="img-wrapper"> element with eight resize handles.
5. The display width of each page image matches the editor page content width, with proportional height scaling.

PDF Export

PDF export uses Chromium's built-in QWebEnginePage.printToPdf() method, which renders the HTML document to a PDF file using the same Chromium rendering engine that displays it on screen. This ensures high fidelity between the on-screen preview and the exported document.

A QPageLayout object is constructed with the page size matching the editor's current setting and zero Qt margins — the CSS padding on the .page divs already provides the visual margins, and adding Qt margins on top would double the margin space. The print CSS media query ensures each page fills the printed page width exactly with width:100%; height:auto and uses page-break-after: always for correct page splitting.

Pandoc Export (DOCX / ODT)

The saveWithPandoc() method enables export to DOCX, ODT, and other formats supported by Pandoc. It first checks the HAS_PANDOC flag to ensure pypandoc is available, then retrieves the current document HTML synchronously via getHtmlContentSync(), writes it to a temporary file, and passes it to pypandoc.convert_file() for conversion. The output format is automatically determined from the file extension. The temporary file is deleted after conversion regardless of success or failure.

Math Preprocessing & Formula Preparation

The editor provides two complementary methods for handling LaTeX math content in imported HTML:

_preprocess_math_html() — MathJax Script Conversion

When importing HTML documents that were originally authored for MathJax, the <script type="math/tex"> elements would be stripped by the browser's innerHTML parser before KaTeX could see them. This static method converts MathJax script tags to plain-text LaTeX delimiters before the HTML reaches the browser:

• <script type="math/tex; mode=display">...</script> → $$...$$
• <script type="math/tex">...</script> → \(...\)

prepare_math_formulas() — LaTeX Delimiter to Placeholder Conversion

After MathJax scripts have been converted (or for HTML that already uses standard LaTeX delimiters), this method scans the HTML and replaces all recognised delimiter patterns with lightweight placeholder <span> elements that the editor's KaTeX rendering pipeline understands:

Structure Synchronization

The structure_synchronization() method is a critical import pipeline component that merges an external HTML document into the editor's template without breaking the editor's internal structure. It performs the following steps in order:

1. Native document check: If the imported HTML already contains the <meta name="abdh-editor"> marker, it is a native editor document and needs no synchronization.
2. Extract styles: All <style> blocks are extracted from the imported document.
3. Extract body: The <body> content is extracted, or the entire document is used if no body tag exists.
4. Remove external scripts: All <script> tags are stripped from the body to prevent external JavaScript from executing inside the editor.
5. Rename conflicting classes: Any CSS class that matches an editor-reserved name (such as page, katex, img-wrapper, etc.) is renamed by prepending EXT (e.g., .page becomes .EXTpage).
6. Convert math formulas: LaTeX delimiters in the body are converted to math-formula placeholder spans via prepare_math_formulas().
7. Inject into template: A fresh editor HTML template is built, the synchronized external styles are injected before </head>, and the body content is inserted into the first .page div.

Page Size & Navigation

Editability Toggle

Text Formatting

The editor provides a comprehensive set of text formatting methods that all delegate to the applyTextStyle() helper, which in turn executes the corresponding document.execCommand() call inside Chromium. The following table summarizes the available formatting operations:

Alignment & Text Direction

Insert Formula / Table / Image

Image Insertion

insertImage() opens a native file dialog filtered to common raster formats (PNG, JPG, JPEG, BMP, GIF), reads the selected file, encodes it as base64, and inserts a draggable img-wrapper element at the current cursor position. The wrapper includes eight directional resize handles (nw, n, ne, e, se, s, sw, w) that allow the user to resize the image by dragging from any corner or edge.

Math Formula Insertion

insertMath(latex, display=False) inserts a KaTeX-rendered formula span at the cursor. The formula is created via the JavaScript createMathFormula() function, which produces a <span class="math-formula"> element with contentEditable='false'. Double-clicking on a rendered formula replaces it with a text input for live editing; pressing Enter or blurring the input re-renders the formula with the updated LaTeX source.

insertMathDialog() provides a convenience dialog (QInputDialog) for entering LaTeX text, then calls insertMath() with the result.

Table Insertion

insertTable(rows, cols) builds an HTML table with the specified dimensions and inserts it at the cursor. Column resize handles are automatically attached via setupColumnResize(). insertTableDialog() provides a dialog with spin boxes for choosing the dimensions (rows: 1–30, columns: 1–15, both defaulting to 3).

Private helpers _insert_row(where) and _insert_col(where) insert a new row or column relative to the current cursor position, used by the table context menu.

Content Get / Set / Clear

Zoom Controls

HTML Template Builder

The _build_initial_html() method assembles the complete HTML document that serves as the editor's editing surface. This is the largest single method in the file, spanning approximately 1,400 lines and containing the full CSS stylesheet, seven JavaScript engines, and the initial page structure. The template is parameterised by the current page size (width and height in mm) and page margins.

The HTML structure consists of:

• A <head> section with a meta tag identifying the document as an editor file, embedded KaTeX tags (or fallback HTML comments), and the full CSS stylesheet.
• A <body> containing a <div class="pages-wrapper"> with one initial <div class="page" contenteditable="true"> and a <div id="readonly-overlay">.
• A <script> section containing all seven JavaScript engines.

CSS Overview

Embedded JavaScript Engines

The editor HTML template contains seven self-contained JavaScript modules that handle all interactive editing behaviour inside the Chromium document. Each module is wrapped in an IIFE (Immediately Invoked Function Expression) or attached to the document/window object as appropriate.

Engine 1: Drag & Resize Engine

Manages drag-and-drop repositioning and 8-directional resizing of .img-wrapper elements. Uses margin-based positioning (marginLeft / marginTop) for overlap-free image movement within the content flow. When the user clicks on a resize handle, the engine tracks the mouse delta from the initial click position and applies proportional width/height changes while adjusting margins to keep opposite corners anchored. Resize handles are shown/hidden via CSS class toggling on mouseenter/mouseleave events, since CSS :hover is unreliable inside contenteditable regions.

Engine 2: Table Column Resize

The setupColumnResize(table) function adds invisible .col-resize-handle divs to each cell in the first row of a table. These handles capture mousedown events and track horizontal mouse movement to adjust column widths across all rows simultaneously. Tables are set to table-layout: fixed to ensure consistent column widths. The resize state is tracked via the resizingColumn flag and associated variables.

Engine 3: Table Tab Navigation

A keydown listener intercepts the Tab key when the cursor is inside a table cell and moves focus to the next cell (or previous cell with Shift+Tab). This provides natural spreadsheet-like navigation within tables. When the last cell is reached, focus wraps around to the first cell, and vice versa.

Engine 4: Multi-Page Engine

This is the most complex JavaScript module and the backbone of the editor's multi-page layout. It manages the creation, overflow handling, and deletion of .page divs:

• getPageGeometry() — Returns the CSS pixel dimensions and padding of a page element.
• createNewPage() — Creates a new empty .page div with contentEditable='true'.
• pushOverflow(pageEl) — Moves overflowing block-level children from a page to the next page (or creates a new page if none exists). Preserves cursor position when the cursor's containing block is moved.
• pullUnderflow(pageEl) — Pulls content from the next page into the current page when there is available space. Never pulls from the currently focused page to avoid stealing the user's cursor.
• removeEmptyPagesAndFixFocus() — Removes empty trailing pages (never the first page) and restores cursor focus to the nearest remaining page.
• isPageEmpty(page) — Checks if a page contains only whitespace (excluding images, tables, and math formulas which are never considered empty).
• checkAllPages() — The main orchestration function: pushes overflow on all pages, pulls underflow in reverse order, removes empty pages, updates page count and page-number attributes, and restores focus. Includes a re-entrancy guard (_pageCheckRunning) and scroll-position preservation.
• schedulePageCheck() — Debounced version using requestAnimationFrame().
• setupPageObserver(pageEl) — Attaches a MutationObserver to each page that triggers schedulePageCheck() on DOM changes.

Engine 5: Advanced Keyboard Handler

Overrides several key behaviours inside the contenteditable to handle non-editable elements (math formulas, images), multi-page navigation, and edge cases that Chromium's default contenteditable handling does not address:

Engine 6: KaTeX Rendering Engine

Provides three key functions for mathematical formula handling:

• renderMathFormula(element) — Renders a single .math-formula span using KaTeX, reading the LaTeX source from data-latex and the display mode from data-display.
• renderAllMathFormulas() — Iterates over all .math-formula elements and renders each one.
• createMathFormula(latex, displayMode) — Creates a new .math-formula span, renders it with KaTeX, and returns the DOM element.

Double-click editing is implemented via a dblclick event listener that replaces the rendered span with a <input class="math-editor"> element. Pressing Enter or blurring the input creates a new formula span with the updated LaTeX and re-renders it.

Engine 7: Dirty Flag Bridge

A JavaScript input event listener on the document body detects all user edits (typing, deleting, formatting changes) and sets document.title to "__edit__" + Date.now(). This communicates the modification to Python via the titleChanged signal, which is connected to the _on_title_changed() slot that sets _is_dirty = True. The timestamp ensures that even rapid successive edits trigger distinct title changes.

Shortcut File Loaders

The editor provides four convenience methods that combine a file dialog with the appropriate loading logic for each supported format:

Complete API Reference

The following table lists every public method exposed by the RichTextEditor class, grouped by functional category. Private methods (prefixed with _) are documented in the sections above but are omitted here as they are not part of the stable public interface.

Document State

Page Layout

Content

Text Formatting

Alignment & Direction

Insert

Zoom

File Operations

Import Helpers