[widget audit] toga.MultilineTextInput

.github/workflows/ci.yml

@@ -205,9 +205,21 @@ jobs:
           - backend: linux
             runs-on: ubuntu-22.04
             # The package list should be the same as in tutorial-0.rst, and the BeeWare
-            # tutorial.
-            pre-command: "sudo apt-get update -y && sudo apt-get install -y python3-dev python3-cairo-dev python3-gi-cairo libgirepository1.0-dev libcairo2-dev libpango1.0-dev gir1.2-webkit2-4.0 pkg-config"
-            briefcase-run-prefix: 'xvfb-run -a -s "-screen 0 2048x1536x24"'
+            # tutorial, plus flwm to provide a window manager
+            pre-command: |
+                sudo apt-get update -y && sudo apt-get install -y python3-dev python3-cairo-dev python3-gi-cairo libgirepository1.0-dev libcairo2-dev libpango1.0-dev gir1.2-webkit2-4.0 pkg-config flwm
+
+                # Start Virtual X server
+                echo "Start X server..."
+                Xvfb :99 -screen 0 2048x1536x24 &
+                sleep 1
+
+                # Start Window manager
+                echo "Start window manager..."
+                DISPLAY=:99 flwm &
+                sleep 1
+
+            briefcase-run-prefix: 'DISPLAY=:99'
             setup-python: false  # Use the system Python packages.
 
           - backend: windows

changes/1938.feature.rst

@@ -0,0 +1 @@
+The MultilineTextInput widget now has 100% test coverage, and complete API documentation.

cocoa/src/toga_cocoa/libs/appkit.py

@@ -379,6 +379,9 @@ class NSEventType(IntEnum):
     RightMouseDragged = 7
     MouseEntered = 8
 
+    KeyDown = 10
+    KeyUp = 11
+
 
 ######################################################################
 # NSFont.h

cocoa/src/toga_cocoa/widgets/multilinetextinput.py

@@ -1,10 +1,13 @@
 from travertino.size import at_least
 
+from toga.colors import TRANSPARENT
 from toga_cocoa.colors import native_color
 from toga_cocoa.libs import (
     NSBezelBorder,
     NSScrollView,
+    NSTextAlignment,
     NSTextView,
+    NSViewHeightSizable,
     NSViewWidthSizable,
     objc_method,
 )
@@ -14,9 +17,8 @@
 
 class TogaTextView(NSTextView):
     @objc_method
-    def touchBar(self):
-        # Disable the touchbar.
-        return None
+    def textDidChange_(self, notification) -> None:
+        self.interface.on_change(None)
 
 
 class MultilineTextInput(Widget):
@@ -33,49 +35,69 @@ def create(self):
         self.native.translatesAutoresizingMaskIntoConstraints = False
 
         # Create the actual text widget
-        self.text = TogaTextView.alloc().init()
-        self.text.editable = True
-        self.text.selectable = True
-        self.text.verticallyResizable = True
-        self.text.horizontallyResizable = False
-        self.text.usesAdaptiveColorMappingForDarkAppearance = True
+        self.native_text = TogaTextView.alloc().init()
+        self.native_text.interface = self.interface
+        self.native_text.delegate = self.native_text
 
-        self.text.autoresizingMask = NSViewWidthSizable
+        self.native_text.editable = True
+        self.native_text.selectable = True
+        self.native_text.verticallyResizable = True
+        self.native_text.horizontallyResizable = False
+        self.native_text.usesAdaptiveColorMappingForDarkAppearance = True
+
+        self.native_text.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable
 
         # Put the text view in the scroll window.
-        self.native.documentView = self.text
+        self.native.documentView = self.native_text
 
         # Add the layout constraints
         self.add_constraints()
 
+    def get_placeholder(self):
+        return self.native_text.placeholderString
+
     def set_placeholder(self, value):
-        self.text.placeholderString = self.interface.placeholder
+        self.native_text.placeholderString = value
+
+    def get_readonly(self):
+        return not self.native_text.isEditable()
 
     def set_readonly(self, value):
-        self.text.editable = not self.interface.readonly
+        self.native_text.editable = not value
 
     def get_value(self):
-        return self.text.string
+        return self.native_text.string
 
     def set_value(self, value):
-        self.text.string = value
+        self.native_text.string = value
 
     def set_color(self, value):
-        self.text.textColor = native_color(value)
+        self.native_text.textColor = native_color(value)
+
+    def set_background_color(self, color):
+        if color is TRANSPARENT:
+            # Both the text view and the scroll view need to be made transparent
+            self.native.drawsBackground = False
+            self.native_text.drawsBackground = False
+        else:
+            # Both the text view and the scroll view need to be opaque,
+            # but only the text view needs a color.
+            self.native.drawsBackground = True
+            self.native_text.drawsBackground = True
+            self.native_text.backgroundColor = native_color(color)
+
+    def set_alignment(self, value):
+        self.native_text.alignment = NSTextAlignment(value)
 
     def set_font(self, font):
-        if font:
-            self.text.font = font._impl.native
+        self.native_text.font = font._impl.native
 
     def rehint(self):
         self.interface.intrinsic.width = at_least(self.interface._MIN_WIDTH)
         self.interface.intrinsic.height = at_least(self.interface._MIN_HEIGHT)
 
-    def set_on_change(self, handler):
-        self.interface.factory.not_implemented("MultilineTextInput.set_on_change()")
-
     def scroll_to_bottom(self):
-        self.text.scrollToEndOfDocument(None)
+        self.native_text.scrollToEndOfDocument(None)
 
     def scroll_to_top(self):
-        self.text.scrollToBeginningOfDocument(None)
+        self.native_text.scrollToBeginningOfDocument(None)

cocoa/tests_backend/widgets/base.py

@@ -1,11 +1,12 @@
 import asyncio
 from ctypes import c_void_p
 
-from rubicon.objc import SEL, NSArray, NSObject, ObjCClass, objc_method
+from rubicon.objc import SEL, NSArray, NSObject, NSPoint, ObjCClass, objc_method
 from rubicon.objc.api import NSString
 
 from toga.colors import TRANSPARENT
 from toga.fonts import CURSIVE, FANTASY, MONOSPACE, SANS_SERIF, SERIF, SYSTEM
+from toga_cocoa.libs import NSEvent, NSEventType
 from toga_cocoa.libs.appkit import appkit
 
 from .properties import toga_color
@@ -80,10 +81,14 @@ async def redraw(self, message=None):
         # Force a repaint
         self.widget.window.content._impl.native.displayIfNeeded()
 
-        # If we're running slow, wait for a second
         if self.widget.app.run_slow:
+            # If we're running slow, wait for a second
             print("Waiting for redraw" if message is None else message)
             await asyncio.sleep(1)
+        else:
+            # Running at "normal" speed, we need to release to the event loop
+            # for at least one iteration. `runUntilDate:None` does this.
+            NSRunLoop.currentRunLoop.runUntilDate(None)
 
     @property
     def enabled(self):
@@ -141,3 +146,67 @@ def is_hidden(self):
     @property
     def has_focus(self):
         return self.native.window.firstResponder == self.native
+
+    async def type_character(self, char):
+        # Convert the requested character into a Cocoa keycode.
+        # This table is incomplete, but covers all the basics.
+        key_code = {
+            " ": 49,
+            "\n": 36,
+            "a": 0,
+            "b": 11,
+            "c": 8,
+            "d": 2,
+            "e": 14,
+            "f": 3,
+            "g": 5,
+            "h": 4,
+            "i": 34,
+            "j": 38,
+            "k": 40,
+            "l": 37,
+            "m": 46,
+            "n": 45,
+            "o": 31,
+            "p": 35,
+            "q": 12,
+            "r": 15,
+            "s": 1,
+            "t": 17,
+            "u": 32,
+            "v": 9,
+            "w": 13,
+            "x": 7,
+            "y": 16,
+            "z": 6,
+        }.get(char.lower(), 0)
+
+        # This posts a single keyDown followed by a keyUp, matching "normal" keyboard operation.
+        await self.post_event(
+            NSEvent.keyEventWithType(
+                NSEventType.KeyDown,
+                location=NSPoint(0, 0),  # key presses don't have a location.
+                modifierFlags=0,
+                timestamp=0,
+                windowNumber=self.native.window.windowNumber,
+                context=None,
+                characters=char,
+                charactersIgnoringModifiers=char,
+                isARepeat=False,
+                keyCode=key_code,
+            ),
+        )
+        await self.post_event(
+            NSEvent.keyEventWithType(
+                NSEventType.KeyUp,
+                location=NSPoint(0, 0),  # key presses don't have a location.
+                modifierFlags=0,
+                timestamp=0,
+                windowNumber=self.native.window.windowNumber,
+                context=None,
+                characters=char,
+                charactersIgnoringModifiers=char,
+                isARepeat=False,
+                keyCode=key_code,
+            ),
+        )

cocoa/tests_backend/widgets/multilinetextinput.py

@@ -1,11 +1,97 @@
+from toga.colors import TRANSPARENT
 from toga_cocoa.libs import NSScrollView
 
 from .base import SimpleProbe
+from .properties import toga_alignment, toga_color, toga_font
 
 
 class MultilineTextInputProbe(SimpleProbe):
     native_class = NSScrollView
 
+    def __init__(self, widget):
+        super().__init__(widget)
+        self.native_text = widget._impl.native_text
+
+    @property
+    def value(self):
+        return str(self.native_text.string)
+
+    @property
+    def placeholder(self):
+        return str(self.native_text.placeholderString)
+
+    def placeholder_visible(self):
+        # macOS manages it's own placeholder visibility.
+        # We can use the existence of widget text as a proxy.
+        return not bool(self.native_text.string)
+
+    @property
+    def placeholder_hides_on_focus(self):
+        return False
+
+    @property
+    def color(self):
+        return toga_color(self.native_text.textColor)
+
+    @property
+    def background_color(self):
+        if self.native_text.drawsBackground:
+            # Confirm the scroll container is also opaque
+            assert self.native.drawsBackground
+            if self.native_text.backgroundColor:
+                return toga_color(self.native_text.backgroundColor)
+            else:
+                return None
+        else:
+            # Confirm the scroll container is also transparent
+            assert not self.native.drawsBackground
+            return TRANSPARENT
+
+    @property
+    def font(self):
+        return toga_font(self.native_text.font)
+
+    @property
+    def alignment(self):
+        return toga_alignment(self.native_text.alignment)
+
+    @property
+    def enabled(self):
+        # Enabled is proxied onto readonly on the text view
+        return self.native_text.isEditable()
+
     @property
     def readonly(self):
-        return not self.native.documentView.isEditable()
+        return not self.native_text.isEditable()
+
+    @property
+    def has_focus(self):
+        return self.native.window.firstResponder == self.native_text
+
+    @property
+    def visible_height(self):
+        return self.native.contentView.bounds.size.height
+
+    @property
+    def visible_width(self):
+        return self.native.contentView.bounds.size.width
+
+    @property
+    def document_height(self):
+        return self.native_text.bounds.size.height
+
+    @property
+    def document_width(self):
+        return self.native_text.bounds.size.width
+
+    @property
+    def horizontal_scroll_position(self):
+        return self.native.contentView.bounds.origin.x
+
+    @property
+    def vertical_scroll_position(self):
+        return self.native.contentView.bounds.origin.y
+
+    async def wait_for_scroll_completion(self):
+        # No animation associated with scroll, so this is a no-op
+        pass