[widget audit] ImageView

.github/workflows/ci.yml

@@ -240,8 +240,10 @@ jobs:
       uses: actions/setup-python@v4.6.1
       if: ${{ matrix.setup-python }}
       with:
-        # We're not using 3.11 yet, because the testbed's ProxyEventLoop isn't
-        # compatible with it (https://github.com/beeware/toga/issues/1982).
+        # We're not using Python 3.11 yet, because:
+        # * The testbed's ProxyEventLoop has some problems with it
+        #   (https://github.com/beeware/toga/issues/1982).
+        # * It doesn't have an Android build of Pillow yet.
         python-version: "3.10"
     - name: Install dependencies
       run: |

android/src/toga_android/images.py

@@ -1,19 +1,38 @@
-from .libs.android.graphics import BitmapFactory
+from pathlib import Path
+
+from java.io import FileOutputStream
+
+from .libs.android.graphics import Bitmap, BitmapFactory
 
 
 class Image:
-    def __init__(self, interface, path=None, url=None, data=None):
+    def __init__(self, interface, path=None, data=None):
         self.interface = interface
-        self.path = path
-        self.url = url
 
         if path:
             self.native = BitmapFactory.decodeFile(str(path))
-        elif url:
-            # Android BitmapFactory nor ImageView provide a convenient async way to fetch images by URL
-            self.native = None
-        elif data:
+        else:
             self.native = BitmapFactory.decodeByteArray(data, 0, len(data))
 
+    def get_width(self):
+        return self.native.getWidth()
+
+    def get_height(self):
+        return self.native.getHeight()
+
     def save(self, path):
-        self.interface.factory.not_implemented("Image.save()")
+        path = Path(path)
+        try:
+            format = {
+                ".jpg": Bitmap.CompressFormat.JPEG,
+                ".jpeg": Bitmap.CompressFormat.JPEG,
+                ".png": Bitmap.CompressFormat.PNG,
+            }[path.suffix.lower()]
+            str_path = str(path)
+        except KeyError:
+            raise ValueError(f"Don't know how to save image of type {path.suffix!r}")
+
+        out = FileOutputStream(str_path)
+        self.native.compress(format, 90, out)
+        out.flush()
+        out.close()

android/src/toga_android/libs/android/graphics/__init__.py

@@ -1,5 +1,6 @@
 from rubicon.java import JavaClass
 
+Bitmap = JavaClass("android/graphics/Bitmap")
 BitmapFactory = JavaClass("android/graphics/BitmapFactory")
 Color = JavaClass("android/graphics/Color")
 DashPathEffect = JavaClass("android/graphics/DashPathEffect")

android/src/toga_android/widgets/imageview.py

@@ -1,11 +1,37 @@
+from toga.widgets.imageview import rehint_imageview
+
 from ..libs.android.widget import ImageView as A_ImageView
 from .base import Widget
 
 
 class ImageView(Widget):
     def create(self):
         self.native = A_ImageView(self._native_activity)
+        self.native.setAdjustViewBounds(True)
+
+    def set_background_color(self, value):
+        self.set_background_simple(value)
 
     def set_image(self, image):
-        if image and image._impl.native:
+        if image:
             self.native.setImageBitmap(image._impl.native)
+        else:
+            self.native.setImageDrawable(None)
+
+    def rehint(self):
+        # User specified sizes are in "pixels", which is DP;
+        # we need to convert all sizes into SP.
+        dpi = self.native.getContext().getResources().getDisplayMetrics().densityDpi
+        # Toga needs to know how the current DPI compares to the platform default,
+        # which is 160: https://developer.android.com/training/multiscreen/screendensities
+        scale = float(dpi) / 160
+
+        width, height, aspect_ratio = rehint_imageview(
+            image=self.interface.image, style=self.interface.style, scale=scale
+        )
+        self.interface.intrinsic.width = width
+        self.interface.intrinsic.height = height
+        if aspect_ratio is not None:
+            self.native.setScaleType(A_ImageView.ScaleType.FIT_CENTER)
+        else:
+            self.native.setScaleType(A_ImageView.ScaleType.FIT_XY)

android/tests_backend/images.py

@@ -0,0 +1,14 @@
+from android.graphics import Bitmap
+
+from .probe import BaseProbe
+
+
+class ImageProbe(BaseProbe):
+    def __init__(self, app, image):
+        super().__init__()
+        self.app = app
+        self.image = image
+        assert isinstance(self.image._impl.native, Bitmap)
+
+    def supports_extension(self, extension):
+        return extension.lower() in {".jpg", ".jpeg", ".png"}

android/tests_backend/widgets/imageview.py

@@ -0,0 +1,11 @@
+from android.widget import ImageView
+
+from .base import SimpleProbe
+
+
+class ImageViewProbe(SimpleProbe):
+    native_class = ImageView
+
+    @property
+    def preserve_aspect_ratio(self):
+        return self.native.getScaleType() == ImageView.ScaleType.FIT_CENTER

changes/1956.feature.rst

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

changes/1956.removal.rst

@@ -0,0 +1 @@
+Images and ImageViews now longer support loading images from URLs. If you need to display an image from a URL, use a background task to obtain the image data asynchronously, then create the Image and/or set the ImageView on the completion of the asychronous load.

cocoa/src/toga_cocoa/images.py

@@ -1,7 +1,6 @@
 from pathlib import Path
 
 from toga_cocoa.libs import (
-    NSURL,
     NSBitmapImageFileType,
     NSBitmapImageRep,
     NSData,
@@ -10,45 +9,35 @@
 
 
 class Image:
-    def __init__(self, interface, path=None, url=None, data=None):
+    def __init__(self, interface, path=None, data=None):
         self.interface = interface
-        self.path = path
-        self.url = url
 
         if path:
             self.native = NSImage.alloc().initWithContentsOfFile(str(path))
-        elif url:
-            self.native = NSImage.alloc().initByReferencingURL(
-                NSURL.URLWithString_(url)
-            )
-        elif data:
-            if isinstance(data, NSData):
-                nsdata = data
-            else:
-                nsdata = NSData.dataWithBytes(data, length=len(data))
-
+        else:
+            nsdata = NSData.dataWithBytes(data, length=len(data))
             self.native = NSImage.alloc().initWithData(nsdata)
 
+    def get_width(self):
+        return self.native.size.width
+
+    def get_height(self):
+        return self.native.size.height
+
     def save(self, path):
         path = Path(path)
         try:
-            if path.suffix == "":
-                # If no suffix is provided in the filename, default to PNG,
-                # and append that suffix to the filename.
-                str_path = str(path) + ".png"
-                filetype = NSBitmapImageFileType.PNG
-            else:
-                filetype = {
-                    ".jpg": NSBitmapImageFileType.JPEG,
-                    ".jpeg": NSBitmapImageFileType.JPEG,
-                    ".png": NSBitmapImageFileType.PNG,
-                    ".gif": NSBitmapImageFileType.GIF,
-                    ".bmp": NSBitmapImageFileType.BMP,
-                    ".tiff": NSBitmapImageFileType.TIFF,
-                }[path.suffix.lower()]
-                str_path = str(path)
+            filetype = {
+                ".jpg": NSBitmapImageFileType.JPEG,
+                ".jpeg": NSBitmapImageFileType.JPEG,
+                ".png": NSBitmapImageFileType.PNG,
+                ".gif": NSBitmapImageFileType.GIF,
+                ".bmp": NSBitmapImageFileType.BMP,
+                ".tiff": NSBitmapImageFileType.TIFF,
+            }[path.suffix.lower()]
+            str_path = str(path)
         except KeyError:
-            raise ValueError(f"Don't know how to save image of type {path.suffix}")
+            raise ValueError(f"Don't know how to save image of type {path.suffix!r}")
 
         bitmapData = NSBitmapImageRep.representationOfImageRepsInArray(
             self.native.representations,

cocoa/src/toga_cocoa/widgets/base.py

@@ -68,7 +68,7 @@ def set_enabled(self, value):
     # APPLICATOR
 
     def set_bounds(self, x, y, width, height):
-        # print("SET BOUNDS ON", self.interface, x, y, width, height)
+        # print(f"SET BOUNDS ON {self.interface} {width}x{height} @ ({x},{y})")
         self.constraints.update(x, y, width, height)
 
     def set_alignment(self, alignment):

cocoa/src/toga_cocoa/widgets/imageview.py

@@ -1,10 +1,10 @@
+from toga.widgets.imageview import rehint_imageview
 from toga_cocoa.libs import (
-    NSImage,
     NSImageAlignment,
     NSImageFrameNone,
+    NSImageScaleAxesIndependently,
     NSImageScaleProportionallyUpOrDown,
     NSImageView,
-    NSSize,
 )
 
 from .base import Widget
@@ -14,26 +14,28 @@ class ImageView(Widget):
     def create(self):
         self.native = NSImageView.alloc().init()
 
-        # self._impl.imageFrameStyle = NSImageFrameGrayBezel
+        # self.native.imageFrameStyle = NSImageFrameGrayBezel
         self.native.imageFrameStyle = NSImageFrameNone
         self.native.imageAlignment = NSImageAlignment.Center.value
-        self.native.imageScaling = NSImageScaleProportionallyUpOrDown
+        self.native.imageScaling = NSImageScaleAxesIndependently
 
         # Add the layout constraints
         self.add_constraints()
 
     def set_image(self, image):
         if image:
-            self.native.image = self.interface._image._impl.native
+            self.native.image = self.interface.image._impl.native
         else:
-            width = 0
-            height = 0
-            if self.interface.style.width:
-                width = self.interface.style.width
-            if self.interface.style.height:
-                height = self.interface.style.height
-
-            self.native.image = NSImage.alloc().initWithSize(NSSize(width, height))
+            self.native.image = None
 
     def rehint(self):
-        pass
+        width, height, aspect_ratio = rehint_imageview(
+            image=self.interface.image,
+            style=self.interface.style,
+        )
+        self.interface.intrinsic.width = width
+        self.interface.intrinsic.height = height
+        if aspect_ratio is not None:
+            self.native.imageScaling = NSImageScaleProportionallyUpOrDown
+        else:
+            self.native.imageScaling = NSImageScaleAxesIndependently

cocoa/tests_backend/images.py

@@ -0,0 +1,14 @@
+from toga_cocoa.libs import NSImage
+
+from .probe import BaseProbe
+
+
+class ImageProbe(BaseProbe):
+    def __init__(self, app, image):
+        super().__init__()
+        self.app = app
+        self.image = image
+        assert isinstance(self.image._impl.native, NSImage)
+
+    def supports_extension(self, extension):
+        return extension.lower() in {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".tiff"}

cocoa/tests_backend/widgets/imageview.py

@@ -0,0 +1,11 @@
+from toga_cocoa.libs import NSImageScaleProportionallyUpOrDown, NSImageView
+
+from .base import SimpleProbe
+
+
+class ImageViewProbe(SimpleProbe):
+    native_class = NSImageView
+
+    @property
+    def preserve_aspect_ratio(self):
+        return self.native.imageScaling == NSImageScaleProportionallyUpOrDown

core/src/toga/images.py

@@ -1,57 +1,61 @@
-import pathlib
-import warnings
+from __future__ import annotations
+
+from pathlib import Path
 
 import toga
 from toga.platform import get_platform_factory
 
 
 class Image:
-    """A representation of graphical content.
+    def __init__(
+        self,
+        path: str | None | Path = None,
+        *,
+        data: bytes | None = None,
+    ):
+        """Create a new image.
 
-    :param path: Path to the image. Allowed values can be local file
-        (relative or absolute path) or URL (HTTP or HTTPS). Relative paths
-        will be interpreted relative to the application module directory.
-    :param data: A bytes object with the contents of an image in a supported
-        format.
-    """
+        An image must be provided either a ``path`` or ``data``, but not both.
 
-    def __init__(self, path=None, *, data=None):
+        :param path: Path to the image. This can be an absolute path to an image
+            file, or a path relative to the file that describes the App class.
+            Can be specified as a string, or as a :any:`pathlib.Path` object.
+        :param data: A bytes object with the contents of an image in a supported
+            format.
+        """
         if path is None and data is None:
             raise ValueError("Either path or data must be set.")
         if path is not None and data is not None:
             raise ValueError("Only either path or data can be set.")
 
-        if path:
-            if isinstance(path, pathlib.Path):
-                self.path = path
-            elif path.startswith("http://") or path.startswith("https://"):
+        if path is not None:
+            if isinstance(path, Path):
                 self.path = path
             else:
-                self.path = pathlib.Path(path)
+                self.path = Path(path)
+            self.data = None
         else:
             self.path = None
-        self.data = data
+            self.data = data
 
         self.factory = get_platform_factory()
         if self.data is not None:
             self._impl = self.factory.Image(interface=self, data=self.data)
-        elif isinstance(self.path, pathlib.Path):
-            full_path = toga.App.app.paths.app / self.path
-            if not full_path.exists():
-                raise FileNotFoundError(
-                    "Image file {full_path!r} does not exist".format(
-                        full_path=full_path
-                    )
-                )
-            self._impl = self.factory.Image(interface=self, path=full_path)
         else:
-            self._impl = self.factory.Image(interface=self, url=self.path)
+            self.path = toga.App.app.paths.app / self.path
+            if not self.path.is_file():
+                raise FileNotFoundError(f"Image file {self.path} does not exist")
+            self._impl = self.factory.Image(interface=self, path=self.path)
+
+    @property
+    def width(self) -> int:
+        """The width of the image, in pixels."""
+        return self._impl.get_width()
 
-    def bind(self, factory=None):
-        warnings.warn(
-            "Icons no longer need to be explicitly bound.", DeprecationWarning
-        )
-        return self._impl
+    @property
+    def height(self) -> int:
+        """The height of the image, in pixels."""
+        return self._impl.get_height()
 
     def save(self, path):
         """Save image to given path.