diff --git a/doc/api/hubs_ev3brick.inc b/doc/api/hubs_ev3brick.inc index dbade4d..8ce6824 100644 --- a/doc/api/hubs_ev3brick.inc +++ b/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 diff --git a/doc/api/media.rst b/doc/api/media.rst index 192b6c4..21752c4 100644 --- a/doc/api/media.rst +++ b/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 diff --git a/doc/common/conf.py b/doc/common/conf.py index 56407c9..f5c4f24 100644 --- a/doc/common/conf.py +++ b/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 diff --git a/pybricks-projects b/pybricks-projects index 8d9bb6e..fcc8af3 160000 --- a/pybricks-projects +++ b/pybricks-projects @@ -1 +1 @@ -Subproject commit 8d9bb6e11a4f0e59f8af0eea3777ea8eaec86e65 +Subproject commit fcc8af3381a13625c829a5e043ac48761f1f67ed diff --git a/pybricks/media/ev3dev.py b/pybricks/media/ev3dev.py index 8c684d3..b435649 100644 --- a/pybricks/media/ev3dev.py +++ b/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 + `. + + 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."""