api/media/ev3dev: update for Image API changes

doc/api/hubs_ev3brick.inc

@@ -158,7 +158,7 @@
 
     .. automethod:: pybricks.hubs::EV3Brick.screen.set_font
 
-    .. automethod:: pybricks.hubs::EV3Brick.screen.show_image
+    .. automethod:: pybricks.hubs::EV3Brick.screen.load_image
 
     .. automethod:: pybricks.hubs::EV3Brick.screen.draw_image
 

doc/api/media.rst

@@ -14,8 +14,8 @@ ev3dev
 .. automodule:: pybricks.media.ev3dev
     :no-members:
 
-Images
-^^^^^^
+Image Files
+^^^^^^^^^^^
 
 .. autoclass:: pybricks.media.ev3dev.ImageFile
     :no-members:
@@ -74,8 +74,8 @@ Images
         .. data:: TIRED_LEFT
         .. data:: ANGRY
 
-Sounds
-^^^^^^
+Sound Files
+^^^^^^^^^^^
 
 .. autoclass:: pybricks.media.ev3dev.SoundFile
     :no-members:
@@ -243,14 +243,18 @@ Fonts
 
     .. automethod:: pybricks.media.ev3dev.Font.text_height
 
-Making Your Own Images
-^^^^^^^^^^^^^^^^^^^^^^
+
+Image Manipulation
+^^^^^^^^^^^^^^^^^^
+
 Instead of drawing directly on the EV3 screen, you can make and interact
 with image files using the ``Image`` class given below.
 
 .. autoclass:: pybricks.media.ev3dev.Image
     :no-members:
 
+    .. automethod:: pybricks.media.ev3dev.Image.empty
+
     .. rubric:: Drawing text
 
     There are two ways to draw text on images. :meth:`draw_text` lets text be
@@ -297,7 +301,7 @@ with image files using the ``Image`` class given below.
 
     .. automethod:: pybricks.media.ev3dev.Image.clear
 
-    .. automethod:: pybricks.media.ev3dev.Image.show_image
+    .. automethod:: pybricks.media.ev3dev.Image.load_image
 
 
 

doc/common/conf.py

@@ -116,6 +116,9 @@ nitpick_ignore = [
     ('py:class', 'object'),
     ('py:class', 'str'),
     ('py:class', 'tuple'),
+    ('py:exc', 'RuntimeError'),
+    ('py:exc', 'TypeError'),
+    ('py:exc', 'ValueError'),
 ]
 
 # -- Autodoc options ------------------------------------------------------
@@ -267,11 +270,17 @@ texinfo_documents = [
 
 # -- Python domain hacks ---------------------------------------------------
 
-def get_signature_prefix_none(self, sig):
-    return ''
+real_get_signature_prefix = PyClassmember.get_signature_prefix
 
 
-PyClassmember.get_signature_prefix = get_signature_prefix_none
+def get_signature_prefix(self, sig):
+    # hacks for battery and light
+    if sig.count('.') >= 2:
+        return ''
+    return real_get_signature_prefix(self, sig)
+
+
+PyClassmember.get_signature_prefix = get_signature_prefix
 
 
 # HACK: For certain hub attributes, we list the class members of the attributes

pybricks/media/ev3dev.py

@@ -59,7 +59,7 @@ class Image:
         """
         pass
 
-    def draw_line(self, x1, y1, x2, y2, color=Color.BLACK):
+    def draw_line(self, x1, y1, x2, y2, width=1, color=Color.BLACK):
         """Draws a line on the image.
 
         Arguments:
@@ -67,6 +67,7 @@ class Image:
             y1 (int): The y coordinate of the starting point of the line.
             x2 (int): The x coordinate of the ending point of the line.
             y2 (int): The y coordinate of the ending point of the line.
+            width (int): The width of the line in pixels.
             color (Color): The color of the line.
         """
         pass
@@ -99,23 +100,25 @@ class Image:
         """
         pass
 
-    def draw_image(self, x, y, image, color=None):
-        """Draws a copy of another image on this image.
+    def draw_image(self, x, y, source, transparent=None):
+        """Draws the ``source`` image on this image.
 
         Arguments:
             x (int):
                 The x-axis value where the left side of the image will start.
             y (int):
                 The y-axis value where the top of the image will start.
-            image (Image):
-                The image to copy.
-            color (Color):
+            source (Image or str):
+                The source :class:`Image`. If the argument is a string, then
+                the ``source`` image is loaded from file.
+            transparent (Color):
                 The color of ``image`` to treat as transparent or ``None`` for
                 no transparency.
         """
 
-    def show_image(self, source):
-        """Clears this image, then draws ``source`` centered in this image.
+    def load_image(self, source):
+        """Clears this image, then draws the ``source`` image centered in
+        this image.
 
         Arguments:
             source (Image or str):
@@ -123,7 +126,7 @@ class Image:
                 the ``source`` image is loaded from file.
         """
 
-    def draw_text(self, x, y, text, color=Color.BLACK):
+    def draw_text(self, x, y, text, text_color=Color.BLACK, background_color=None):
         """Draws text on the image.
 
         The most recent font set using :meth:`set_font` will be used or
@@ -135,22 +138,29 @@ class Image:
             y (int):
                 The y-axis value where the top of the text will start.
             text (str):
-                The text to display.
-            color (Color):
+                The text to draw.
+            text_color (Color):
                 The color used for drawing the text.
+            background_color (Color):
+                The color used to fill the rectangle behind the text or ``None``
+                for transparent background.
         """
         pass
 
     def print(self, *args, sep=' ', end='\n'):
         """Prints a line of text.
 
-        This method works like the built-in ``print()`` function, but
-        it writes on the screen/image instead.
+        This method works like the builtin ``print()`` function, but it writes
+        on the image instead.
 
-        You can set the font using :meth:`set_font`. If no font has been
-        set, :data:`Font.DEFAULT` will be used.
+        You can set the font using :meth:`set_font`. If no font has been set,
+        :data:`Font.DEFAULT` will be used. The text is always printed used
+        black text with a white background.
 
-        If no new line is available, all text scrolls up automatically.
+        Unlike the builtin ``print()``, the text does not wrap if it is too
+        wide to fit on the image. It just gets cut off. But if the text would
+        go off of the bottom of the image, the entire image is scrolled up and
+        the text is printed in the new blank area at the bottom of the image.
 
         Arguments:
             * (object):
@@ -174,6 +184,30 @@ class Image:
         """
         pass
 
+    @staticmethod
+    def empty(width, height):
+        """Creates a new empty :class:`Image` object.
+
+        Arguments:
+            width (int):
+                The width of the image in pixels.
+            height (int):
+                The height of the image in pixels.
+
+        Returns:
+            Image:
+                A new image with all pixels set to :attr:`Color.WHITE
+                <pybricks.parameters.Color.WHITE>`.
+
+        Raises:
+            TypeError:
+                ``width`` or ``height`` is not a number.
+            ValueError:
+                ``width`` or ``height`` is less than 1.
+            RuntimeError:
+                There was a problem allocating a new image.
+        """
+
 
 class Font:
     """Object that represents a font for writing text."""