toga-code-editor 0.1.1__py3-none-any.whl

toga_code_editor/__init__.py

@@ -0,0 +1,16 @@
+from importlib.metadata import version
+
+from .code_editor import CodeEditor
+from .highlighting import DEFAULT_THEME, Span, Style, TokenKind, language_for_filename
+
+__version__ = version("toga-code-editor")
+
+__all__ = [
+    "DEFAULT_THEME",
+    "CodeEditor",
+    "Span",
+    "Style",
+    "TokenKind",
+    "__version__",
+    "language_for_filename",
+]

toga_code_editor/code_editor.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import asyncio
+import warnings
+from functools import cached_property
+from typing import Any
+
+import toga
+from toga.fonts import MONOSPACE
+from toga.platform import get_factory
+from toga.widgets.base import StyleT
+from toga.widgets.multilinetextinput import OnChangeHandler
+
+from .highlighting import (
+    DEFAULT_THEME,
+    Highlighter,
+    NullHighlighter,
+    PygmentsHighlighter,
+    Theme,
+)
+
+REHIGHLIGHT_DELAY = 0.15
+"""Seconds to wait after the last native edit before re-highlighting."""
+
+
+class CodeEditor(toga.MultilineTextInput):
+    def __init__(
+        self,
+        id: str | None = None,
+        style: StyleT | None = None,
+        value: str | None = None,
+        readonly: bool = False,
+        placeholder: str | None = None,
+        on_change: OnChangeHandler | None = None,
+        language: str | None = None,
+        show_line_numbers: bool = True,
+        theme: Theme | None = None,
+        **kwargs,
+    ):
+        """Create a new code editor.
+
+        :param id: The ID for the widget.
+        :param style: A style object. If no style is provided, a default style will
+            be applied to the widget.
+        :param value: The initial content to display in the widget.
+        :param readonly: Can the value of the widget be modified by the user?
+        :param placeholder: The content to display as a placeholder when there is no
+            user content to display.
+        :param on_change: A handler that will be invoked when the value of the widget
+            changes.
+        :param language: A Pygments lexer alias such as ``"python"``, or ``None`` for
+            no highlighting.
+        :param show_line_numbers: Whether to show the line-number gutter.
+        :param theme: A mapping from :class:`TokenKind` to :class:`Style`, or ``None``
+            for the default theme.
+        :param kwargs: Initial style properties. Unless a font family is given here or
+            on ``style``, the editor uses a monospace font.
+        """
+        if "font_family" not in kwargs and (
+            style is None or "font_family" not in style
+        ):
+            kwargs["font_family"] = MONOSPACE
+
+        # State the inherited value setter needs before super().__init__() runs.
+        self._highlighter: Highlighter = NullHighlighter()
+        self._language: str | None = None
+        self._theme: Theme = DEFAULT_THEME
+        self._show_line_numbers = True
+        self._pending_rehighlight = None
+
+        super().__init__(
+            id=id,
+            style=style,
+            value=value,
+            readonly=readonly,
+            placeholder=placeholder,
+            on_change=on_change,
+            **kwargs,
+        )
+
+        self.theme = theme
+        self.language = language
+        self.show_line_numbers = show_line_numbers
+
+    @cached_property
+    def factory(self):
+        # This is an official BeeWare external widget, so its interface group uses the
+        # "toga_" prefix. Toga currently warns about any "toga_" interface it does not
+        # know. Until Toga provides a way to register external widgets, swallow that
+        # one warning here rather than letting every app print it at startup.
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="Unrecognized official Toga interface",
+                category=RuntimeWarning,
+            )
+            return get_factory("toga_code_editor")
+
+    def _create(self) -> Any:
+        return self.factory.CodeEditor(interface=self)
+
+    @toga.MultilineTextInput.value.setter
+    def value(self, value: object) -> None:
+        toga.MultilineTextInput.value.fset(self, value)
+        self._rehighlight()
+
+    @property
+    def language(self) -> str | None:
+        """The Pygments lexer alias used for highlighting, or ``None`` for none.
+
+        Setting an alias Pygments does not know raises :exc:`ValueError` and leaves
+        the previous language in place.
+        """
+        return self._language
+
+    @language.setter
+    def language(self, value: str | None) -> None:
+        highlighter = NullHighlighter() if value is None else PygmentsHighlighter(value)
+        self._language = value
+        self._highlighter = highlighter
+        self._rehighlight()
+
+    @property
+    def theme(self) -> Theme:
+        """The mapping from token kind to style; ``None`` restores the default."""
+        return self._theme
+
+    @theme.setter
+    def theme(self, value: Theme | None) -> None:
+        self._theme = DEFAULT_THEME if value is None else value
+        self._impl.set_theme(self._theme)
+        self._rehighlight()
+
+    @property
+    def show_line_numbers(self) -> bool:
+        """Whether the line-number gutter is shown."""
+        return self._show_line_numbers
+
+    @show_line_numbers.setter
+    def show_line_numbers(self, value: object) -> None:
+        self._show_line_numbers = bool(value)
+        self._impl.set_show_line_numbers(self._show_line_numbers)
+
+    def _rehighlight(self) -> None:
+        self._cancel_pending_rehighlight()
+        self._impl.set_highlights(self._highlighter.highlight(self.value))
+
+    def _schedule_rehighlight(self) -> None:
+        """Called by the backend when the user edits the text.
+
+        Re-lexing on every keystroke would be wasteful, so wait for a short pause.
+        This is a task rather than a bare ``call_later`` because Toga's Android event
+        loop only arms its next wakeup for work scheduled through ``call_soon``; a
+        timer added from a native callback would otherwise never fire.
+        """
+        self._cancel_pending_rehighlight()
+        self._pending_rehighlight = toga.App.app.loop.create_task(
+            self._rehighlight_after_delay()
+        )
+
+    async def _rehighlight_after_delay(self) -> None:
+        await asyncio.sleep(REHIGHLIGHT_DELAY)
+        self._pending_rehighlight = None
+        self._rehighlight()
+
+    def _cancel_pending_rehighlight(self) -> None:
+        if self._pending_rehighlight is not None:
+            self._pending_rehighlight.cancel()
+            self._pending_rehighlight = None

toga_code_editor/highlighting.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from os import PathLike
+from typing import Protocol
+
+from pygments.lexers import find_lexer_class_for_filename, get_lexer_by_name
+from pygments.token import (
+    Comment,
+    Keyword,
+    Name,
+    Number,
+    Operator,
+    Punctuation,
+    String,
+)
+from pygments.util import ClassNotFound
+from toga.colors import Color
+
+
+class TokenKind(StrEnum):
+    """The flat vocabulary of token kinds a theme can style."""
+
+    TEXT = "text"
+    KEYWORD = "keyword"
+    BUILTIN = "builtin"
+    DEFINITION = "definition"
+    DECORATOR = "decorator"
+    STRING = "string"
+    NUMBER = "number"
+    COMMENT = "comment"
+    OPERATOR = "operator"
+    PUNCTUATION = "punctuation"
+    TAG = "tag"
+    ATTRIBUTE = "attribute"
+    VARIABLE = "variable"
+
+
+@dataclass(frozen=True)
+class Span:
+    """A run of text with one token kind.
+
+    Offsets are Python string indices: ``start`` inclusive, ``end`` exclusive.
+    """
+
+    start: int
+    end: int
+    kind: TokenKind
+
+
+@dataclass(frozen=True)
+class Style:
+    """How a token kind is drawn. ``color`` accepts any Toga color value."""
+
+    color: Color | str
+    bold: bool = False
+    italic: bool = False
+
+    def __post_init__(self):
+        object.__setattr__(self, "color", Color.parse(self.color))
+
+
+Theme = Mapping[TokenKind, Style]
+"""A mapping from token kind to style. Kinds absent from the theme are left unstyled."""
+
+DEFAULT_THEME: Theme = {
+    TokenKind.KEYWORD: Style("#a626a4"),
+    TokenKind.BUILTIN: Style("#0184bc"),
+    TokenKind.DEFINITION: Style("#4078f2", bold=True),
+    TokenKind.DECORATOR: Style("#986801"),
+    TokenKind.STRING: Style("#50a14f"),
+    TokenKind.NUMBER: Style("#986801"),
+    TokenKind.COMMENT: Style("#8a8a8a", italic=True),
+    TokenKind.TAG: Style("#e45649"),
+    TokenKind.ATTRIBUTE: Style("#986801"),
+    TokenKind.VARIABLE: Style("#e45649"),
+}
+
+# Ordered most-specific first. The first row whose Pygments type contains the token
+# wins, so Operator.Word must precede Operator, and the Name.* rows precede nothing
+# more general because bare Name falls through to TEXT.
+_TOKEN_TABLE = [
+    (Comment, TokenKind.COMMENT),
+    (String, TokenKind.STRING),
+    (Number, TokenKind.NUMBER),
+    (Keyword, TokenKind.KEYWORD),
+    (Operator.Word, TokenKind.KEYWORD),
+    (Operator, TokenKind.OPERATOR),
+    (Punctuation, TokenKind.PUNCTUATION),
+    (Name.Builtin, TokenKind.BUILTIN),
+    (Name.Function, TokenKind.DEFINITION),
+    (Name.Class, TokenKind.DEFINITION),
+    (Name.Decorator, TokenKind.DECORATOR),
+    (Name.Tag, TokenKind.TAG),
+    (Name.Attribute, TokenKind.ATTRIBUTE),
+    (Name.Variable, TokenKind.VARIABLE),
+]
+
+
+def token_kind(token_type) -> TokenKind:
+    """Map a Pygments token type onto the flat vocabulary."""
+    for pygments_type, kind in _TOKEN_TABLE:
+        if token_type in pygments_type:
+            return kind
+    return TokenKind.TEXT
+
+
+def merge_spans(spans: Iterable[Span]) -> list[Span]:
+    """Drop TEXT spans and merge adjacent spans of the same kind."""
+    merged: list[Span] = []
+    for span in spans:
+        if span.kind is TokenKind.TEXT:
+            continue
+        if merged and merged[-1].kind is span.kind and merged[-1].end == span.start:
+            merged[-1] = Span(merged[-1].start, span.end, span.kind)
+        else:
+            merged.append(span)
+    return merged
+
+
+class Highlighter(Protocol):
+    def highlight(self, text: str) -> list[Span]: ...
+
+
+class NullHighlighter:
+    """The highlighter used when no language is set."""
+
+    def highlight(self, text: str) -> list[Span]:
+        return []
+
+
+class PygmentsHighlighter:
+    """Tokenize text with a Pygments lexer.
+
+    :param language: A Pygments lexer alias, such as ``"python"``.
+    :raises ValueError: If Pygments has no lexer for the alias.
+    """
+
+    def __init__(self, language: str):
+        try:
+            # Pygments trims and appends newlines by default, which shifts every
+            # offset. Turn all of that off.
+            self.lexer = get_lexer_by_name(
+                language, stripnl=False, stripall=False, ensurenl=False
+            )
+        except ClassNotFound:
+            raise ValueError(f"Unknown language {language!r}") from None
+
+    def highlight(self, text: str) -> list[Span]:
+        return merge_spans(
+            Span(index, index + len(value), token_kind(token_type))
+            for index, token_type, value in self.lexer.get_tokens_unprocessed(text)
+        )
+
+
+def language_for_filename(path: str | PathLike) -> str | None:
+    """Return the Pygments lexer alias for a filename, or ``None`` if there is none.
+
+    The whole filename is matched, so names such as ``Makefile`` resolve.
+    """
+    lexer_class = find_lexer_class_for_filename(str(path))
+    return None if lexer_class is None else lexer_class.aliases[0]
+
+
+def to_utf16_spans(text: str, spans: list[Span]) -> list[Span]:
+    """Convert span offsets from code points to UTF-16 code units.
+
+    Native text views on macOS, iOS, and Android index by UTF-16 code unit, so every
+    character outside the Basic Multilingual Plane shifts later offsets by one. Spans
+    must be in document order, which is how the highlighters produce them.
+    """
+    converted = []
+    scanned = 0  # code-point index already accounted for
+    extra = 0  # extra UTF-16 units contributed by astral characters before `scanned`
+
+    def utf16(index: int) -> int:
+        nonlocal scanned, extra
+        extra += sum(1 for ch in text[scanned:index] if ord(ch) > 0xFFFF)
+        scanned = index
+        return index + extra
+
+    for span in spans:
+        start = utf16(span.start)
+        end = utf16(span.end)
+        converted.append(Span(start, end, span.kind))
+    return converted
+
+
+def utf16_line_starts(text: str) -> list[int]:
+    """Return the UTF-16 offset of the first character of each logical line."""
+    starts = [0]
+    offset = 0
+    for ch in text:
+        offset += 2 if ord(ch) > 0xFFFF else 1
+        if ch == "\n":
+            starts.append(offset)
+    return starts

toga_code_editor/platforms/android.py

@@ -0,0 +1,217 @@
+import weakref
+
+from android.graphics import Typeface
+from android.text import InputType, Spanned
+from android.text.method import ScrollingMovementMethod
+from android.text.style import ForegroundColorSpan, StyleSpan
+from android.util import TypedValue
+from android.view import Gravity, View, WindowManager
+from android.widget import RelativeLayout, TextView
+from java import dynamic_proxy
+from java.lang import Runnable
+from toga_android.colors import native_color
+from toga_android.widgets.base import suppress_reference_error
+from toga_android.widgets.multilinetextinput import MultilineTextInput
+
+from ..highlighting import to_utf16_spans
+
+GUTTER_PADDING = 6  # CSS pixels; scaled to physical pixels at creation
+
+
+class TogaGutterScrollListener(dynamic_proxy(View.OnScrollChangeListener)):
+    def __init__(self, impl):
+        super().__init__()
+        self.impl = weakref.proxy(impl)
+
+    def onScrollChange(self, view, new_x, new_y, old_x, old_y):
+        with suppress_reference_error():
+            self.impl.gutter.setScrollY(new_y)
+
+
+class TogaGutterLayoutListener(dynamic_proxy(View.OnLayoutChangeListener)):
+    def __init__(self, impl):
+        super().__init__()
+        self.impl = weakref.proxy(impl)
+
+    def onLayoutChange(
+        self, view, left, top, right, bottom, o_left, o_top, o_right, o_bottom
+    ):
+        # A new width re-wraps the text, which changes which visual lines start a
+        # logical line. Defer the rebuild until this layout pass has finished.
+        with suppress_reference_error():
+            if (right - left, bottom - top) != (o_right - o_left, o_bottom - o_top):
+                self.impl.native.post(self.impl.gutter_updater)
+
+
+class TogaGutterTouchListener(dynamic_proxy(View.OnTouchListener)):
+    def onTouch(self, view, event):
+        # The gutter follows the editor; it must not scroll on its own.
+        return True
+
+
+class TogaGutterUpdater(dynamic_proxy(Runnable)):
+    def __init__(self, impl):
+        super().__init__()
+        self.impl = weakref.proxy(impl)
+
+    def run(self):
+        with suppress_reference_error():
+            self.impl.update_gutter()
+
+
+class CodeEditor(MultilineTextInput):
+    def __init__(self, interface):
+        super().__init__(interface)
+        # ContainedWidget wraps self.native in a RelativeLayout *after* create()
+        # returns, so the gutter can only be added here.
+        padding = self.scale_in(GUTTER_PADDING)
+        self.gutter = TextView(self._native_activity)
+        self.gutter.setId(View.generateViewId())
+        self.gutter.setGravity(Gravity.END | Gravity.TOP)
+        self.gutter.setTextColor(self.native.getCurrentHintTextColor())
+        # Without a movement method, a TextView scrolls back to its start on the
+        # first draw after setText(), which would undo the scroll sync every time
+        # the numbers are rebuilt. The movement method also makes the view
+        # focusable and clickable, so undo that and swallow touches.
+        self.gutter.setMovementMethod(ScrollingMovementMethod.getInstance())
+        self.gutter.setFocusable(False)
+        self.gutter.setClickable(False)
+        self.gutter.setLongClickable(False)
+        self.gutter.setOnTouchListener(TogaGutterTouchListener())
+        self.gutter.setPadding(
+            padding,
+            self.native.getPaddingTop(),
+            padding,
+            self.native.getPaddingBottom(),
+        )
+        self.sync_gutter_font()
+
+        gutter_params = RelativeLayout.LayoutParams(
+            RelativeLayout.LayoutParams.WRAP_CONTENT,
+            RelativeLayout.LayoutParams.MATCH_PARENT,
+        )
+        gutter_params.addRule(RelativeLayout.ALIGN_PARENT_START)
+        self.native_toplevel.addView(self.gutter, gutter_params)
+
+        text_params = RelativeLayout.LayoutParams(
+            RelativeLayout.LayoutParams.MATCH_PARENT,
+            RelativeLayout.LayoutParams.MATCH_PARENT,
+        )
+        text_params.addRule(RelativeLayout.END_OF, self.gutter.getId())
+        self.native.setLayoutParams(text_params)
+
+        self.native.setOnScrollChangeListener(TogaGutterScrollListener(self))
+        self.native.addOnLayoutChangeListener(TogaGutterLayoutListener(self))
+        self.gutter_updater = TogaGutterUpdater(self)
+        self.gutter_numbers = None
+        self.update_gutter()
+
+    def create(self):
+        super().create()
+        self.disable_suggestions()
+        self.prefer_keyboard_resize()
+        self.theme = {}
+        self.spans = []
+        self.active_spans = []
+
+    def prefer_keyboard_resize(self):
+        # By default Android pans the whole window to keep the cursor above the soft
+        # keyboard, which scrolls everything above the editor off the screen. Ask for
+        # the content area to shrink instead, so the editor scrolls internally, but
+        # only when the app has not chosen a mode itself.
+        params = WindowManager.LayoutParams
+        window = self._native_activity.getWindow()
+        mode = window.getAttributes().softInputMode
+        if mode & params.SOFT_INPUT_MASK_ADJUST == params.SOFT_INPUT_ADJUST_UNSPECIFIED:
+            mode = (
+                mode & ~params.SOFT_INPUT_MASK_ADJUST
+            ) | params.SOFT_INPUT_ADJUST_RESIZE
+            window.setSoftInputMode(mode)
+
+    def disable_suggestions(self):
+        # NO_SUGGESTIONS turns off autocorrect on most keyboards. Some third-party
+        # keyboards ignore it; that is a known rough edge.
+        self.native.setInputType(
+            self.native.getInputType() | InputType.TYPE_TEXT_FLAG_NO_SUGGESTIONS
+        )
+
+    # Inherited TextInput methods that must keep the gutter and flags in sync
+
+    def set_readonly(self, readonly):
+        # The parent toggles NO_SUGGESTIONS with readonly; keep it on regardless.
+        super().set_readonly(readonly)
+        self.disable_suggestions()
+
+    def set_font(self, font):
+        super().set_font(font)
+        self.sync_gutter_font()
+        self.native.post(self.gutter_updater)
+
+    def _on_change(self):
+        self.interface._schedule_rehighlight()
+        self.interface.on_change()
+        # The text layout is rebuilt after this callback returns; update the
+        # gutter once that has happened.
+        self.native.post(self.gutter_updater)
+
+    # CodeEditor backend contract
+
+    def set_theme(self, theme):
+        self.theme = theme
+
+    def set_highlights(self, spans):
+        self.spans = spans
+        editable = self.native.getText()
+        for span in self.active_spans:
+            editable.removeSpan(span)
+        self.active_spans = []
+
+        for span in to_utf16_spans(str(editable), spans):
+            style = self.theme.get(span.kind)
+            if style is None:
+                continue
+            native_spans = [ForegroundColorSpan(native_color(style.color))]
+            if style.bold or style.italic:
+                typeface_style = (Typeface.BOLD if style.bold else Typeface.NORMAL) | (
+                    Typeface.ITALIC if style.italic else Typeface.NORMAL
+                )
+                native_spans.append(StyleSpan(typeface_style))
+            for native_span in native_spans:
+                editable.setSpan(
+                    native_span, span.start, span.end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
+                )
+                self.active_spans.append(native_span)
+
+    def set_show_line_numbers(self, value):
+        # A GONE anchor collapses to zero width, so the editor fills the row.
+        self.gutter.setVisibility(View.VISIBLE if value else View.GONE)
+
+    # Gutter
+
+    def sync_gutter_font(self):
+        self.gutter.setTypeface(self.native.getTypeface())
+        self.gutter.setTextSize(TypedValue.COMPLEX_UNIT_PX, self.native.getTextSize())
+        self.gutter.setLineSpacing(
+            self.native.getLineSpacingExtra(), self.native.getLineSpacingMultiplier()
+        )
+        self.gutter.setIncludeFontPadding(self.native.getIncludeFontPadding())
+
+    def update_gutter(self):
+        layout = self.native.getLayout()
+        if layout is None:
+            # No layout pass has happened yet; the next change will post again.
+            return
+        text = self.native.getText()
+        numbers = []
+        line = 0
+        for i in range(layout.getLineCount()):
+            start = layout.getLineStart(i)
+            if start == 0 or text.charAt(start - 1) == "\n":
+                line += 1
+                numbers.append(str(line))
+            else:
+                numbers.append("")  # a wrapped continuation line
+        gutter_numbers = "\n".join(numbers)
+        if gutter_numbers != self.gutter_numbers:
+            self.gutter_numbers = gutter_numbers
+            self.gutter.setText(gutter_numbers)