diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 3dda59fb8e..501879be80 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -29,7 +29,7 @@ #include "shared-bindings/board/__init__.h" -//| :mod:`board` --- Board specific pin names +//| """:mod:`board` --- Board specific pin names //| ======================================================== //| //| .. module:: board @@ -39,11 +39,11 @@ //| board so don't expect portability when using this module. //| //| .. warning:: The board module varies by board. The APIs documented here may or may not be -//| available on a specific board. +//| available on a specific board.""" -//| .. function:: I2C() -//| -//| Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton. +//| def I2C() -> Any: +//| """Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton.""" +//| ... //| #if BOARD_I2C @@ -65,10 +65,10 @@ mp_obj_t board_i2c(void) { MP_DEFINE_CONST_FUN_OBJ_0(board_i2c_obj, board_i2c); -//| .. function:: SPI() -//| -//| Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a -//| singleton. +//| def SPI() -> Any: +//| """Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a +//| singleton.""" +//| ... //| #if BOARD_SPI mp_obj_t board_spi(void) { @@ -89,15 +89,14 @@ mp_obj_t board_spi(void) { #endif MP_DEFINE_CONST_FUN_OBJ_0(board_spi_obj, board_spi); -//| .. function:: UART() -//| -//| Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. -//| -//| The object created uses the default parameter values for `busio.UART`. If you need to set -//| parameters that are not changeable after creation, such as ``receiver_buffer_size``, -//| do not use `board.UART()`; instead create a `busio.UART` object explicitly with the -//| desired parameters. +//| def UART() -> Any: +//| """Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. //| +//| The object created uses the default parameter values for `busio.UART`. If you need to set +//| parameters that are not changeable after creation, such as ``receiver_buffer_size``, +//| do not use `board.UART()`; instead create a `busio.UART` object explicitly with the +//| desired parameters.""" +//| ... //| #if BOARD_UART mp_obj_t board_uart(void) { diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index 39da00cf71..5fffb3f653 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -43,23 +43,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: digitalio +//| class DigitalInOut: +//| """.. currentmodule:: digitalio //| -//| :class:`DigitalInOut` -- digital input and output -//| ========================================================= +//| :class:`DigitalInOut` -- digital input and output +//| ========================================================= //| -//| A DigitalInOut is used to digitally control I/O pins. For analog control of -//| a pin, see the :py:class:`analogio.AnalogIn` and -//| :py:class:`analogio.AnalogOut` classes. +//| A DigitalInOut is used to digitally control I/O pins. For analog control of +//| a pin, see the :py:class:`analogio.AnalogIn` and +//| :py:class:`analogio.AnalogOut` classes.""" //| - -//| .. class:: DigitalInOut(pin) +//| def __init__(self, pin: microcontroller.Pin): +//| """Create a new DigitalInOut object associated with the pin. Defaults to input +//| with no pull. Use :py:meth:`switch_to_input` and +//| :py:meth:`switch_to_output` to change the direction. //| -//| Create a new DigitalInOut object associated with the pin. Defaults to input -//| with no pull. Use :py:meth:`switch_to_input` and -//| :py:meth:`switch_to_output` to change the direction. -//| -//| :param ~microcontroller.Pin pin: The pin to control +//| :param ~microcontroller.Pin pin: The pin to control""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) { @@ -74,9 +74,9 @@ STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, return MP_OBJ_FROM_PTR(self); } -//| .. method:: deinit() -//| -//| Turn off the DigitalInOut and release the pin for other use. +//| def deinit(self, ) -> Any: +//| """Turn off the DigitalInOut and release the pin for other use.""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -85,16 +85,16 @@ STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit); -//| .. method:: __enter__() -//| -//| No-op used by Context Managers. +//| def __enter__(self, ) -> Any: +//| """No-op used by Context Managers.""" +//| ... //| // Provided by context manager helper. -//| .. method:: __exit__() -//| -//| Automatically deinitializes the hardware when exiting a context. See -//| :ref:`lifetime-and-contextmanagers` for more info. +//| def __exit__(self, ) -> Any: +//| """Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info.""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -109,14 +109,13 @@ STATIC void check_for_deinit(digitalio_digitalinout_obj_t *self) { } } +//| def switch_to_output(self, value: bool = False, drive_mode: digitalio.DriveMode = digitalio.DriveMode.PUSH_PULL) -> Any: +//| """Set the drive mode and value and then switch to writing out digital +//| values. //| -//| .. method:: switch_to_output(value=False, drive_mode=digitalio.DriveMode.PUSH_PULL) -//| -//| Set the drive mode and value and then switch to writing out digital -//| values. -//| -//| :param bool value: default value to set upon switching -//| :param ~digitalio.DriveMode drive_mode: drive mode for the output +//| :param bool value: default value to set upon switching +//| :param ~digitalio.DriveMode drive_mode: drive mode for the output""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_value, ARG_drive_mode }; @@ -139,22 +138,22 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digitalio_digitalinout_switch_to_output); -//| .. method:: switch_to_input(pull=None) +//| def switch_to_input(self, pull: Pull = None) -> Any: +//| """Set the pull and then switch to read in digital values. //| -//| Set the pull and then switch to read in digital values. +//| :param Pull pull: pull configuration for the input //| -//| :param Pull pull: pull configuration for the input +//| Example usage:: //| -//| Example usage:: +//| import digitalio +//| import board //| -//| import digitalio -//| import board -//| -//| switch = digitalio.DigitalInOut(board.SLIDE_SWITCH) -//| switch.switch_to_input(pull=digitalio.Pull.UP) -//| # Or, after switch_to_input -//| switch.pull = digitalio.Pull.UP -//| print(switch.value) +//| switch = digitalio.DigitalInOut(board.SLIDE_SWITCH) +//| switch.switch_to_input(pull=digitalio.Pull.UP) +//| # Or, after switch_to_input +//| switch.pull = digitalio.Pull.UP +//| print(switch.value)""" +//| ... //| STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pull }; @@ -178,14 +177,13 @@ STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_o } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_input_obj, 1, digitalio_digitalinout_switch_to_input); -//| .. attribute:: direction -//| -//| The direction of the pin. +//| direction: Any = ... +//| """The direction of the pin. //| //| Setting this will use the defaults from the corresponding //| :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If //| you want to set pull, value or drive mode prior to switching, then use -//| those methods instead. +//| those methods instead.""" //| typedef struct { mp_obj_base_t base; @@ -225,9 +223,8 @@ const mp_obj_property_t digitalio_digitalio_direction_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: value -//| -//| The digital logic level of the pin. +//| value: Any = ... +//| """The digital logic level of the pin.""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_value(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -256,12 +253,11 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: drive_mode -//| -//| The pin drive mode. One of: +//| drive_mode: Any = ... +//| """The pin drive mode. One of: //| //| - `digitalio.DriveMode.PUSH_PULL` -//| - `digitalio.DriveMode.OPEN_DRAIN` +//| - `digitalio.DriveMode.OPEN_DRAIN`""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -301,15 +297,14 @@ const mp_obj_property_t digitalio_digitalio_drive_mode_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: pull -//| -//| The pin pull direction. One of: +//| pull: Any = ... +//| """The pin pull direction. One of: //| //| - `digitalio.Pull.UP` //| - `digitalio.Pull.DOWN` //| - `None` //| -//| :raises AttributeError: if `direction` is :py:data:`~digitalio.Direction.OUTPUT`. +//| :raises AttributeError: if `direction` is :py:data:`~digitalio.Direction.OUTPUT`.""" //| STATIC mp_obj_t digitalio_digitalinout_obj_get_pull(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/digitalio/Direction.c b/shared-bindings/digitalio/Direction.c index c8188fc899..0586e95def 100644 --- a/shared-bindings/digitalio/Direction.c +++ b/shared-bindings/digitalio/Direction.c @@ -38,23 +38,22 @@ #include "shared-bindings/microcontroller/Pin.h" #include "shared-bindings/digitalio/DigitalInOut.h" -//| .. currentmodule:: digitalio +//| class Direction: +//| """.. currentmodule:: digitalio //| -//| :class:`Direction` -- defines the direction of a digital pin -//| ============================================================= +//| :class:`Direction` -- defines the direction of a digital pin +//| =============================================================""" //| -//| .. class:: Direction +//| def __init__(self, ): +//| """Enum-like class to define which direction the digital values are +//| going.""" +//| ... //| -//| Enum-like class to define which direction the digital values are -//| going. +//| INPUT: Any = ... +//| """Read digital data in""" //| -//| .. data:: INPUT -//| -//| Read digital data in -//| -//| .. data:: OUTPUT -//| -//| Write digital data out +//| OUTPUT: Any = ... +//| """Write digital data out""" //| const mp_obj_type_t digitalio_direction_type; diff --git a/shared-bindings/digitalio/DriveMode.c b/shared-bindings/digitalio/DriveMode.c index 51e1e2ee50..23745b0469 100644 --- a/shared-bindings/digitalio/DriveMode.c +++ b/shared-bindings/digitalio/DriveMode.c @@ -26,24 +26,23 @@ #include "shared-bindings/digitalio/DriveMode.h" -//| .. currentmodule:: digitalio +//| class DriveMode: +//| """.. currentmodule:: digitalio //| -//| :class:`DriveMode` -- defines the drive mode of a digital pin -//| ============================================================= +//| :class:`DriveMode` -- defines the drive mode of a digital pin +//| =============================================================""" //| -//| .. class:: DriveMode +//| def __init__(self, ): +//| """Enum-like class to define the drive mode used when outputting +//| digital values.""" +//| ... //| -//| Enum-like class to define the drive mode used when outputting -//| digital values. +//| PUSH_PULL: Any = ... +//| """Output both high and low digital values""" //| -//| .. data:: PUSH_PULL -//| -//| Output both high and low digital values -//| -//| .. data:: OPEN_DRAIN -//| -//| Output low digital values but go into high z for digital high. This is -//| useful for i2c and other protocols that share a digital line. +//| OPEN_DRAIN: Any = ... +//| """Output low digital values but go into high z for digital high. This is +//| useful for i2c and other protocols that share a digital line.""" //| const mp_obj_type_t digitalio_drive_mode_type; diff --git a/shared-bindings/digitalio/Pull.c b/shared-bindings/digitalio/Pull.c index 813268db78..1e64d07887 100644 --- a/shared-bindings/digitalio/Pull.c +++ b/shared-bindings/digitalio/Pull.c @@ -26,25 +26,24 @@ #include "shared-bindings/digitalio/Pull.h" -//| .. currentmodule:: digitalio +//| class Pull: +//| """.. currentmodule:: digitalio //| -//| :class:`Pull` -- defines the pull of a digital input pin -//| ============================================================= +//| :class:`Pull` -- defines the pull of a digital input pin +//| =============================================================""" //| -//| .. class:: Pull +//| def __init__(self, ): +//| """Enum-like class to define the pull value, if any, used while reading +//| digital values in.""" +//| ... //| -//| Enum-like class to define the pull value, if any, used while reading -//| digital values in. +//| UP: Any = ... +//| """When the input line isn't being driven the pull up can pull the state +//| of the line high so it reads as true.""" //| -//| .. data:: UP -//| -//| When the input line isn't being driven the pull up can pull the state -//| of the line high so it reads as true. -//| -//| .. data:: DOWN -//| -//| When the input line isn't being driven the pull down can pull the -//| state of the line low so it reads as false. +//| DOWN: Any = ... +//| """When the input line isn't being driven the pull down can pull the +//| state of the line low so it reads as false.""" //| const mp_obj_type_t digitalio_pull_type; diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c index 1632262d2a..5a11436a23 100644 --- a/shared-bindings/digitalio/__init__.c +++ b/shared-bindings/digitalio/__init__.c @@ -38,7 +38,7 @@ #include "py/runtime.h" -//| :mod:`digitalio` --- Basic digital pin support +//| """:mod:`digitalio` --- Basic digital pin support //| ================================================= //| //| .. module:: digitalio @@ -86,7 +86,7 @@ //| led.value = True //| time.sleep(0.1) //| led.value = False -//| time.sleep(0.1) +//| time.sleep(0.1)""" //| STATIC const mp_rom_map_elem_t digitalio_module_globals_table[] = { diff --git a/shared-bindings/displayio/Bitmap.c b/shared-bindings/displayio/Bitmap.c index 391f3e5955..d15c3b1078 100644 --- a/shared-bindings/displayio/Bitmap.c +++ b/shared-bindings/displayio/Bitmap.c @@ -36,22 +36,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Bitmap: +//| """.. currentmodule:: displayio //| -//| :class:`Bitmap` -- Stores values in a 2D array -//| ========================================================================== +//| :class:`Bitmap` -- Stores values in a 2D array +//| ========================================================================== //| -//| Stores values of a certain size in a 2D array +//| Stores values of a certain size in a 2D array""" //| -//| .. class:: Bitmap(width, height, value_count) +//| def __init__(self, width: int, height: int, value_count: int): +//| """Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to +//| index into a corresponding palette. This enables differently colored sprites to share the +//| underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap. //| -//| Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to -//| index into a corresponding palette. This enables differently colored sprites to share the -//| underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap. -//| -//| :param int width: The number of values wide -//| :param int height: The number of values high -//| :param int value_count: The number of possible pixel values. +//| :param int width: The number of values wide +//| :param int height: The number of values high +//| :param int value_count: The number of possible pixel values.""" +//| ... //| STATIC mp_obj_t displayio_bitmap_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 3, 3, false); @@ -77,9 +78,8 @@ STATIC mp_obj_t displayio_bitmap_make_new(const mp_obj_type_t *type, size_t n_ar return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: width -//| -//| Width of the bitmap. (read only) +//| width: Any = ... +//| """Width of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_bitmap_obj_get_width(mp_obj_t self_in) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -96,9 +96,8 @@ const mp_obj_property_t displayio_bitmap_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Height of the bitmap. (read only) +//| height: Any = ... +//| """Height of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_bitmap_obj_get_height(mp_obj_t self_in) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -115,23 +114,23 @@ const mp_obj_property_t displayio_bitmap_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __getitem__(index) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the value at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| Returns the value at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. +//| This allows you to:: //| -//| This allows you to:: +//| print(bitmap[0,1])""" +//| ... //| -//| print(bitmap[0,1]) +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the value at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| .. method:: __setitem__(index, value) +//| This allows you to:: //| -//| Sets the value at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. -//| -//| This allows you to:: -//| -//| bitmap[0,1] = 3 +//| bitmap[0,1] = 3""" +//| ... //| STATIC mp_obj_t bitmap_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value_obj) { if (value_obj == mp_const_none) { @@ -178,9 +177,9 @@ STATIC mp_obj_t bitmap_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t val return mp_const_none; } -//| .. method:: fill(value) -//| -//| Fills the bitmap with the supplied palette index value. +//| def fill(self, value: Any) -> Any: +//| """Fills the bitmap with the supplied palette index value.""" +//| ... //| STATIC mp_obj_t displayio_bitmap_obj_fill(mp_obj_t self_in, mp_obj_t value_obj) { displayio_bitmap_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/ColorConverter.c b/shared-bindings/displayio/ColorConverter.c index db2d1b6e29..1d6e5a0cc9 100644 --- a/shared-bindings/displayio/ColorConverter.c +++ b/shared-bindings/displayio/ColorConverter.c @@ -36,18 +36,20 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class ColorConverter: +//| """.. currentmodule:: displayio //| -//| :class:`ColorConverter` -- Converts one color format to another -//| ========================================================================================= +//| :class:`ColorConverter` -- Converts one color format to another +//| ========================================================================================= //| -//| Converts one color format to another. +//| Converts one color format to another.""" //| -//| .. class:: ColorConverter(*, dither=False) +//| def __init__(self, *, dither: bool = False): +//| """Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 +//| currently. +//| :param bool dither: Adds random noise to dither the output image""" +//| ... //| -//| Create a ColorConverter object to convert color formats. Only supports RGB888 to RGB565 -//| currently. -//| :param bool dither: Adds random noise to dither the output image // TODO(tannewt): Add support for other color formats. //| @@ -68,9 +70,9 @@ STATIC mp_obj_t displayio_colorconverter_make_new(const mp_obj_type_t *type, siz return MP_OBJ_FROM_PTR(self); } -//| .. method:: convert(color) -//| -//| Converts the given RGB888 color to RGB565 +//| def convert(self, color: Any) -> Any: +//| """Converts the given RGB888 color to RGB565""" +//| ... //| STATIC mp_obj_t displayio_colorconverter_obj_convert(mp_obj_t self_in, mp_obj_t color_obj) { displayio_colorconverter_t *self = MP_OBJ_TO_PTR(self_in); @@ -87,10 +89,9 @@ STATIC mp_obj_t displayio_colorconverter_obj_convert(mp_obj_t self_in, mp_obj_t } MP_DEFINE_CONST_FUN_OBJ_2(displayio_colorconverter_convert_obj, displayio_colorconverter_obj_convert); -//| .. attribute:: dither -//| -//| When true the color converter dithers the output by adding random noise when -//| truncating to display bitdepth +//| dither: Any = ... +//| """When true the color converter dithers the output by adding random noise when +//| truncating to display bitdepth""" //| STATIC mp_obj_t displayio_colorconverter_obj_get_dither(mp_obj_t self_in) { displayio_colorconverter_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c index a22b2add22..12abec1c83 100644 --- a/shared-bindings/displayio/Display.c +++ b/shared-bindings/displayio/Display.c @@ -39,73 +39,74 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Display: +//| """.. currentmodule:: displayio //| -//| :class:`Display` -- Manage updating a display over a display bus -//| ========================================================================== +//| :class:`Display` -- Manage updating a display over a display bus +//| ========================================================================== //| -//| This initializes a display and connects it into CircuitPython. Unlike other -//| objects in CircuitPython, Display objects live until `displayio.release_displays()` -//| is called. This is done so that CircuitPython can use the display itself. +//| This initializes a display and connects it into CircuitPython. Unlike other +//| objects in CircuitPython, Display objects live until `displayio.release_displays()` +//| is called. This is done so that CircuitPython can use the display itself. //| -//| Most people should not use this class directly. Use a specific display driver instead that will -//| contain the initialization sequence at minimum. +//| Most people should not use this class directly. Use a specific display driver instead that will +//| contain the initialization sequence at minimum.""" //| -//| .. class:: Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0, color_depth=16, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1, reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b, write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None, brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False, auto_refresh=True, native_frames_per_second=60) +//| def __init__(self, display_bus: Any, init_sequence: buffer, *, width: int, height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, color_depth: int = 16, grayscale: bool = False, pixels_in_byte_share_row: bool = True, bytes_per_cell: int = 1, reverse_pixels_in_byte: bool = False, set_column_command: int = 0x2a, set_row_command: int = 0x2b, write_ram_command: int = 0x2c, set_vertical_scroll: int = 0, backlight_pin: microcontroller.Pin = None, brightness_command: int = None, brightness: bool = 1.0, auto_brightness: bool = False, single_byte_bounds: bool = False, data_as_commands: bool = False, auto_refresh: bool = True, native_frames_per_second: int = 60): +//| """Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). //| -//| Create a Display object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). +//| The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a +//| command byte followed by a byte to determine the parameter count and if a delay is need after. +//| When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. +//| The remaining 7 bits are the parameter count excluding any delay byte. The third through final +//| bytes are the remaining command parameters. The next byte will begin a new command definition. +//| Here is a portion of ILI9341 init code: //| -//| The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a -//| command byte followed by a byte to determine the parameter count and if a delay is need after. -//| When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. -//| The remaining 7 bits are the parameter count excluding any delay byte. The third through final -//| bytes are the remaining command parameters. The next byte will begin a new command definition. -//| Here is a portion of ILI9341 init code: +//| .. code-block:: python //| -//| .. code-block:: python +//| init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma +//| b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms) +//| b"\x29\x80\x78"# Display on then delay 0x78 (120ms) +//| ) +//| display = displayio.Display(display_bus, init_sequence, width=320, height=240) //| -//| init_sequence = (b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F" # Set Gamma -//| b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms) -//| b"\x29\x80\x78"# Display on then delay 0x78 (120ms) -//| ) -//| display = displayio.Display(display_bus, init_sequence, width=320, height=240) +//| The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and +//| 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals +//| (b"") are merged together on load. The parens are needed to allow byte literals on subsequent +//| lines. //| -//| The first command is 0xe1 with 15 (0xf) parameters following. The second and third are 0x11 and -//| 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters. Multiple byte literals -//| (b"") are merged together on load. The parens are needed to allow byte literals on subsequent -//| lines. +//| The initialization sequence should always leave the display memory access inline with the scan +//| of the display to minimize tearing artifacts. //| -//| The initialization sequence should always leave the display memory access inline with the scan -//| of the display to minimize tearing artifacts. -//| -//| :param display_bus: The bus that the display is connected to -//| :type display_bus: displayio.FourWire or displayio.ParallelBus -//| :param buffer init_sequence: Byte-packed initialization sequence. -//| :param int width: Width in pixels -//| :param int height: Height in pixels -//| :param int colstart: The index if the first visible column -//| :param int rowstart: The index if the first visible row -//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) -//| :param int color_depth: The number of bits of color per pixel transmitted. (Some displays -//| support 18 bit but 16 is easier to transmit. The last bit is extrapolated.) -//| :param bool grayscale: True if the display only shows a single color. -//| :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column. -//| :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row. -//| :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.) -//| :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16 -//| :param int set_column_command: Command used to set the start and end columns to update -//| :param int set_row_command: Command used so set the start and end rows to update -//| :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set. -//| :param int set_vertical_scroll: Command used to set the first row to show -//| :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight -//| :param int brightness_command: Command to set display brightness. Usually available in OLED controllers. -//| :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True. -//| :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism. -//| :param bool single_byte_bounds: Display column and row commands use single bytes -//| :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this. -//| :param bool auto_refresh: Automatically refresh the screen -//| :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence. -//| :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on. +//| :param display_bus: The bus that the display is connected to +//| :type display_bus: displayio.FourWire or displayio.ParallelBus +//| :param buffer init_sequence: Byte-packed initialization sequence. +//| :param int width: Width in pixels +//| :param int height: Height in pixels +//| :param int colstart: The index if the first visible column +//| :param int rowstart: The index if the first visible row +//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) +//| :param int color_depth: The number of bits of color per pixel transmitted. (Some displays +//| support 18 bit but 16 is easier to transmit. The last bit is extrapolated.) +//| :param bool grayscale: True if the display only shows a single color. +//| :param bool pixels_in_byte_share_row: True when pixels are less than a byte and a byte includes pixels from the same row of the display. When False, pixels share a column. +//| :param int bytes_per_cell: Number of bytes per addressable memory location when color_depth < 8. When greater than one, bytes share a row or column according to pixels_in_byte_share_row. +//| :param bool reverse_pixels_in_byte: Reverses the pixel order within each byte when color_depth < 8. Does not apply across multiple bytes even if there is more than one byte per cell (bytes_per_cell.) +//| :param bool reverse_bytes_in_word: Reverses the order of bytes within a word when color_depth == 16 +//| :param int set_column_command: Command used to set the start and end columns to update +//| :param int set_row_command: Command used so set the start and end rows to update +//| :param int write_ram_command: Command used to write pixels values into the update region. Ignored if data_as_commands is set. +//| :param int set_vertical_scroll: Command used to set the first row to show +//| :param microcontroller.Pin backlight_pin: Pin connected to the display's backlight +//| :param int brightness_command: Command to set display brightness. Usually available in OLED controllers. +//| :param bool brightness: Initial display brightness. This value is ignored if auto_brightness is True. +//| :param bool auto_brightness: If True, brightness is controlled via an ambient light sensor or other mechanism. +//| :param bool single_byte_bounds: Display column and row commands use single bytes +//| :param bool data_as_commands: Treat all init and boundary data as SPI commands. Certain displays require this. +//| :param bool auto_refresh: Automatically refresh the screen +//| :param int native_frames_per_second: Number of display refreshes per second that occur with the given init_sequence. +//| :param bool backlight_on_high: If True, pulling the backlight pin high turns the backlight on.""" +//| ... //| STATIC mp_obj_t displayio_display_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_display_bus, ARG_init_sequence, ARG_width, ARG_height, ARG_colstart, ARG_rowstart, ARG_rotation, ARG_color_depth, ARG_grayscale, ARG_pixels_in_byte_share_row, ARG_bytes_per_cell, ARG_reverse_pixels_in_byte, ARG_reverse_bytes_in_word, ARG_set_column_command, ARG_set_row_command, ARG_write_ram_command, ARG_set_vertical_scroll, ARG_backlight_pin, ARG_brightness_command, ARG_brightness, ARG_auto_brightness, ARG_single_byte_bounds, ARG_data_as_commands, ARG_auto_refresh, ARG_native_frames_per_second, ARG_backlight_on_high }; @@ -190,12 +191,13 @@ static displayio_display_obj_t* native_display(mp_obj_t display_obj) { return MP_OBJ_TO_PTR(native_display); } -//| .. method:: show(group) +//| def show(self, group: Group) -> Any: +//| """Switches to displaying the given group of layers. When group is None, the default +//| CircuitPython terminal will be shown. //| -//| Switches to displaying the given group of layers. When group is None, the default -//| CircuitPython terminal will be shown. +//| :param Group group: The group to show.""" +//| ... //| -//| :param Group group: The group to show. STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) { displayio_display_obj_t *self = native_display(self_in); displayio_group_t* group = NULL; @@ -211,21 +213,21 @@ STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) } MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_show_obj, displayio_display_obj_show); -//| .. method:: refresh(*, target_frames_per_second=60, minimum_frames_per_second=1) +//| def refresh(self, *, target_frames_per_second: int = 60, minimum_frames_per_second: int = 1) -> Any: +//| """When auto refresh is off, waits for the target frame rate and then refreshes the display, +//| returning True. If the call has taken too long since the last refresh call for the given +//| target frame rate, then the refresh returns False immediately without updating the screen to +//| hopefully help getting caught up. //| -//| When auto refresh is off, waits for the target frame rate and then refreshes the display, -//| returning True. If the call has taken too long since the last refresh call for the given -//| target frame rate, then the refresh returns False immediately without updating the screen to -//| hopefully help getting caught up. +//| If the time since the last successful refresh is below the minimum frame rate, then an +//| exception will be raised. Set minimum_frames_per_second to 0 to disable. //| -//| If the time since the last successful refresh is below the minimum frame rate, then an -//| exception will be raised. Set minimum_frames_per_second to 0 to disable. +//| When auto refresh is on, updates the display immediately. (The display will also update +//| without calls to this.) //| -//| When auto refresh is on, updates the display immediately. (The display will also update -//| without calls to this.) -//| -//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. -//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second. +//| :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated. +//| :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second.""" +//| ... //| STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_target_frames_per_second, ARG_minimum_frames_per_second }; @@ -246,9 +248,8 @@ STATIC mp_obj_t displayio_display_obj_refresh(size_t n_args, const mp_obj_t *pos } MP_DEFINE_CONST_FUN_OBJ_KW(displayio_display_refresh_obj, 1, displayio_display_obj_refresh); -//| .. attribute:: auto_refresh -//| -//| True when the display is refreshed automatically. +//| auto_refresh: Any = ... +//| """True when the display is refreshed automatically.""" //| STATIC mp_obj_t displayio_display_obj_get_auto_refresh(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -272,11 +273,10 @@ const mp_obj_property_t displayio_display_auto_refresh_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: brightness -//| -//| The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When +//| brightness: Any = ... +//| """The brightness of the display as a float. 0.0 is off and 1.0 is full brightness. When //| `auto_brightness` is True, the value of `brightness` will change automatically. -//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False. +//| If `brightness` is set, `auto_brightness` will be disabled and will be set to False.""" //| STATIC mp_obj_t displayio_display_obj_get_brightness(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -310,12 +310,11 @@ const mp_obj_property_t displayio_display_brightness_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: auto_brightness -//| -//| True when the display brightness is adjusted automatically, based on an ambient +//| auto_brightness: Any = ... +//| """True when the display brightness is adjusted automatically, based on an ambient //| light sensor or other method. Note that some displays may have this set to True by default, //| but not actually implement automatic brightness adjustment. `auto_brightness` is set to False -//| if `brightness` is set manually. +//| if `brightness` is set manually.""" //| STATIC mp_obj_t displayio_display_obj_get_auto_brightness(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -342,9 +341,8 @@ const mp_obj_property_t displayio_display_auto_brightness_obj = { -//| .. attribute:: width -//| -//| Gets the width of the board +//| width: Any = ... +//| Gets the width of the board //| //| STATIC mp_obj_t displayio_display_obj_get_width(mp_obj_t self_in) { @@ -360,9 +358,8 @@ const mp_obj_property_t displayio_display_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Gets the height of the board +//| height: Any = ... +//| """Gets the height of the board""" //| //| STATIC mp_obj_t displayio_display_obj_get_height(mp_obj_t self_in) { @@ -378,9 +375,8 @@ const mp_obj_property_t displayio_display_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: rotation -//| -//| The rotation of the display as an int in degrees. +//| rotation: Any = ... +//| """The rotation of the display as an int in degrees.""" //| STATIC mp_obj_t displayio_display_obj_get_rotation(mp_obj_t self_in) { displayio_display_obj_t *self = native_display(self_in); @@ -402,9 +398,8 @@ const mp_obj_property_t displayio_display_rotation_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bus -//| -//| The bus being used by the display +//| bus: Any = ... +//| """The bus being used by the display""" //| //| STATIC mp_obj_t displayio_display_obj_get_bus(mp_obj_t self_in) { @@ -421,12 +416,13 @@ const mp_obj_property_t displayio_display_bus_obj = { }; -//| .. method:: fill_row(y, buffer) +//| def fill_row(self, y: int, buffer: bytearray) -> Any: +//| """Extract the pixels from a single row //| -//| Extract the pixels from a single row +//| :param int y: The top edge of the area +//| :param bytearray buffer: The buffer in which to place the pixel data""" +//| ... //| -//| :param int y: The top edge of the area -//| :param bytearray buffer: The buffer in which to place the pixel data STATIC mp_obj_t displayio_display_obj_fill_row(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_y, ARG_buffer }; static const mp_arg_t allowed_args[] = { diff --git a/shared-bindings/displayio/EPaperDisplay.c b/shared-bindings/displayio/EPaperDisplay.c index 1459c16809..8b03ddc067 100644 --- a/shared-bindings/displayio/EPaperDisplay.c +++ b/shared-bindings/displayio/EPaperDisplay.c @@ -39,55 +39,56 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class EPaperDisplay: +//| """.. currentmodule:: displayio //| -//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus -//| ============================================================================== +//| :class:`EPaperDisplay` -- Manage updating an epaper display over a display bus +//| ============================================================================== //| -//| This initializes an epaper display and connects it into CircuitPython. Unlike other -//| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` -//| is called. This is done so that CircuitPython can use the display itself. +//| This initializes an epaper display and connects it into CircuitPython. Unlike other +//| objects in CircuitPython, EPaperDisplay objects live until `displayio.release_displays()` +//| is called. This is done so that CircuitPython can use the display itself. //| -//| Most people should not use this class directly. Use a specific display driver instead that will -//| contain the startup and shutdown sequences at minimum. +//| Most people should not use this class directly. Use a specific display driver instead that will +//| contain the startup and shutdown sequences at minimum.""" //| -//| .. class:: EPaperDisplay(display_bus, start_sequence, stop_sequence, *, width, height, ram_width, ram_height, colstart=0, rowstart=0, rotation=0, set_column_window_command=None, set_row_window_command=None, single_byte_bounds=False, write_black_ram_command, black_bits_inverted=False, write_color_ram_command=None, color_bits_inverted=False, highlight_color=0x000000, refresh_display_command, refresh_time=40, busy_pin=None, busy_state=True, seconds_per_frame=180, always_toggle_chip_select=False) +//| def __init__(self, display_bus: Any, start_sequence: buffer, stop_sequence: buffer, *, width: int, height: int, ram_width: int, ram_height: int, colstart: int = 0, rowstart: int = 0, rotation: int = 0, set_column_window_command: int = None, set_row_window_command: int = None, single_byte_bounds: Any = False, write_black_ram_command: int, black_bits_inverted: bool = False, write_color_ram_command: int = None, color_bits_inverted: bool = False, highlight_color: int = 0x000000, refresh_display_command: int, refresh_time: float = 40, busy_pin: microcontroller.Pin = None, busy_state: bool = True, seconds_per_frame: float = 180, always_toggle_chip_select: bool = False): +//| """Create a EPaperDisplay object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). //| -//| Create a EPaperDisplay object on the given display bus (`displayio.FourWire` or `displayio.ParallelBus`). +//| The ``start_sequence`` and ``stop_sequence`` are bitpacked to minimize the ram impact. Every +//| command begins with a command byte followed by a byte to determine the parameter count and if +//| a delay is need after. When the top bit of the second byte is 1, the next byte will be the +//| delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay +//| byte. The third through final bytes are the remaining command parameters. The next byte will +//| begin a new command definition. //| -//| The ``start_sequence`` and ``stop_sequence`` are bitpacked to minimize the ram impact. Every -//| command begins with a command byte followed by a byte to determine the parameter count and if -//| a delay is need after. When the top bit of the second byte is 1, the next byte will be the -//| delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay -//| byte. The third through final bytes are the remaining command parameters. The next byte will -//| begin a new command definition. -//| -//| :param display_bus: The bus that the display is connected to -//| :type display_bus: displayio.FourWire or displayio.ParallelBus -//| :param buffer start_sequence: Byte-packed initialization sequence. -//| :param buffer stop_sequence: Byte-packed initialization sequence. -//| :param int width: Width in pixels -//| :param int height: Height in pixels -//| :param int ram_width: RAM width in pixels -//| :param int ram_height: RAM height in pixels -//| :param int colstart: The index if the first visible column -//| :param int rowstart: The index if the first visible row -//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) -//| :param int set_column_window_command: Command used to set the start and end columns to update -//| :param int set_row_window_command: Command used so set the start and end rows to update -//| :param int set_current_column_command: Command used to set the current column location -//| :param int set_current_row_command: Command used to set the current row location -//| :param int write_black_ram_command: Command used to write pixels values into the update region -//| :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise, 1 means to show black. -//| :param int write_color_ram_command: Command used to write pixels values into the update region -//| :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1 means to show color. -//| :param int highlight_color: RGB888 of source color to highlight with third ePaper color. -//| :param int refresh_display_command: Command used to start a display refresh -//| :param float refresh_time: Time it takes to refresh the display before the stop_sequence should be sent. Ignored when busy_pin is provided. -//| :param microcontroller.Pin busy_pin: Pin used to signify the display is busy -//| :param bool busy_state: State of the busy pin when the display is busy -//| :param float seconds_per_frame: Minimum number of seconds between screen refreshes -//| :param bool always_toggle_chip_select: When True, chip select is toggled every byte +//| :param display_bus: The bus that the display is connected to +//| :type display_bus: displayio.FourWire or displayio.ParallelBus +//| :param buffer start_sequence: Byte-packed initialization sequence. +//| :param buffer stop_sequence: Byte-packed initialization sequence. +//| :param int width: Width in pixels +//| :param int height: Height in pixels +//| :param int ram_width: RAM width in pixels +//| :param int ram_height: RAM height in pixels +//| :param int colstart: The index if the first visible column +//| :param int rowstart: The index if the first visible row +//| :param int rotation: The rotation of the display in degrees clockwise. Must be in 90 degree increments (0, 90, 180, 270) +//| :param int set_column_window_command: Command used to set the start and end columns to update +//| :param int set_row_window_command: Command used so set the start and end rows to update +//| :param int set_current_column_command: Command used to set the current column location +//| :param int set_current_row_command: Command used to set the current row location +//| :param int write_black_ram_command: Command used to write pixels values into the update region +//| :param bool black_bits_inverted: True if 0 bits are used to show black pixels. Otherwise, 1 means to show black. +//| :param int write_color_ram_command: Command used to write pixels values into the update region +//| :param bool color_bits_inverted: True if 0 bits are used to show the color. Otherwise, 1 means to show color. +//| :param int highlight_color: RGB888 of source color to highlight with third ePaper color. +//| :param int refresh_display_command: Command used to start a display refresh +//| :param float refresh_time: Time it takes to refresh the display before the stop_sequence should be sent. Ignored when busy_pin is provided. +//| :param microcontroller.Pin busy_pin: Pin used to signify the display is busy +//| :param bool busy_state: State of the busy pin when the display is busy +//| :param float seconds_per_frame: Minimum number of seconds between screen refreshes +//| :param bool always_toggle_chip_select: When True, chip select is toggled every byte""" +//| ... //| STATIC mp_obj_t displayio_epaperdisplay_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_display_bus, ARG_start_sequence, ARG_stop_sequence, ARG_width, ARG_height, ARG_ram_width, ARG_ram_height, ARG_colstart, ARG_rowstart, ARG_rotation, ARG_set_column_window_command, ARG_set_row_window_command, ARG_set_current_column_command, ARG_set_current_row_command, ARG_write_black_ram_command, ARG_black_bits_inverted, ARG_write_color_ram_command, ARG_color_bits_inverted, ARG_highlight_color, ARG_refresh_display_command, ARG_refresh_time, ARG_busy_pin, ARG_busy_state, ARG_seconds_per_frame, ARG_always_toggle_chip_select }; @@ -170,12 +171,13 @@ static displayio_epaperdisplay_obj_t* native_display(mp_obj_t display_obj) { return MP_OBJ_TO_PTR(native_display); } -//| .. method:: show(group) +//| def show(self, group: Group) -> Any: +//| """Switches to displaying the given group of layers. When group is None, the default +//| CircuitPython terminal will be shown. //| -//| Switches to displaying the given group of layers. When group is None, the default -//| CircuitPython terminal will be shown. +//| :param Group group: The group to show.""" +//| ... //| -//| :param Group group: The group to show. STATIC mp_obj_t displayio_epaperdisplay_obj_show(mp_obj_t self_in, mp_obj_t group_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); displayio_group_t* group = NULL; @@ -191,10 +193,10 @@ STATIC mp_obj_t displayio_epaperdisplay_obj_show(mp_obj_t self_in, mp_obj_t grou } MP_DEFINE_CONST_FUN_OBJ_2(displayio_epaperdisplay_show_obj, displayio_epaperdisplay_obj_show); -//| .. method:: refresh() -//| -//| Refreshes the display immediately or raises an exception if too soon. Use -//| ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur. +//| def refresh(self, ) -> Any: +//| """Refreshes the display immediately or raises an exception if too soon. Use +//| ``time.sleep(display.time_to_refresh)`` to sleep until a refresh can occur.""" +//| ... //| STATIC mp_obj_t displayio_epaperdisplay_obj_refresh(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -206,10 +208,8 @@ STATIC mp_obj_t displayio_epaperdisplay_obj_refresh(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_epaperdisplay_refresh_obj, displayio_epaperdisplay_obj_refresh); -//| .. attribute:: time_to_refresh -//| -//| Time, in fractional seconds, until the ePaper display can be refreshed. -//| +//| time_to_refresh: Any = ... +//| """Time, in fractional seconds, until the ePaper display can be refreshed.""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_time_to_refresh(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -224,10 +224,8 @@ const mp_obj_property_t displayio_epaperdisplay_time_to_refresh_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: width -//| -//| Gets the width of the display in pixels -//| +//| width: Any = ... +//| """Gets the width of the display in pixels""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_width(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -242,10 +240,8 @@ const mp_obj_property_t displayio_epaperdisplay_width_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: height -//| -//| Gets the height of the display in pixels -//| +//| height: Any = ... +//| """Gets the height of the display in pixels""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_height(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); @@ -260,10 +256,8 @@ const mp_obj_property_t displayio_epaperdisplay_height_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: bus -//| -//| The bus being used by the display -//| +//| bus: Any = ... +//| """The bus being used by the display""" //| STATIC mp_obj_t displayio_epaperdisplay_obj_get_bus(mp_obj_t self_in) { displayio_epaperdisplay_obj_t *self = native_display(self_in); diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c index 6ad1624114..649045039e 100644 --- a/shared-bindings/displayio/FourWire.c +++ b/shared-bindings/displayio/FourWire.c @@ -38,31 +38,32 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class FourWire: +//| """.. currentmodule:: displayio //| -//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol -//| ========================================================================== +//| :class:`FourWire` -- Manage updating a display over SPI four wire protocol +//| ========================================================================== //| -//| Manage updating a display over SPI four wire protocol in the background while Python code runs. -//| It doesn't handle display initialization. +//| Manage updating a display over SPI four wire protocol in the background while Python code runs. +//| It doesn't handle display initialization.""" //| -//| .. class:: FourWire(spi_bus, *, command, chip_select, reset=None, baudrate=24000000, polarity=0, phase=0) +//| def __init__(self, spi_bus: busio.SPI, *, command: microcontroller.Pin, chip_select: microcontroller.Pin, reset: microcontroller.Pin = None, baudrate: int = 24000000, polarity: int = 0, phase: int = 0): +//| """Create a FourWire object associated with the given pins. //| -//| Create a FourWire object associated with the given pins. +//| The SPI bus and pins are then in use by the display until `displayio.release_displays()` is +//| called even after a reload. (It does this so CircuitPython can use the display after your code +//| is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The SPI bus and pins are then in use by the display until `displayio.release_displays()` is -//| called even after a reload. (It does this so CircuitPython can use the display after your code -//| is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param busio.SPI spi_bus: The SPI bus that make up the clock and data lines -//| :param microcontroller.Pin command: Data or command pin -//| :param microcontroller.Pin chip_select: Chip select pin -//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used -//| :param int baudrate: Maximum baudrate in Hz for the display on the bus -//| :param int polarity: the base state of the clock line (0 or 1) -//| :param int phase: the edge of the clock that data is captured. First (0) -//| or second (1). Rising or falling depends on clock polarity. +//| :param busio.SPI spi_bus: The SPI bus that make up the clock and data lines +//| :param microcontroller.Pin command: Data or command pin +//| :param microcontroller.Pin chip_select: Chip select pin +//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used +//| :param int baudrate: Maximum baudrate in Hz for the display on the bus +//| :param int polarity: the base state of the clock line (0 or 1) +//| :param int phase: the edge of the clock that data is captured. First (0) +//| or second (1). Rising or falling depends on clock polarity.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_spi_bus, ARG_command, ARG_chip_select, ARG_reset, ARG_baudrate, ARG_polarity, ARG_phase }; @@ -100,10 +101,10 @@ STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_ return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_obj_reset(mp_obj_t self_in) { displayio_fourwire_obj_t *self = self_in; @@ -115,10 +116,10 @@ STATIC mp_obj_t displayio_fourwire_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_fourwire_reset_obj, displayio_fourwire_obj_reset); -//| .. method:: send(command, data, *, toggle_every_byte=False) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any, *, toggle_every_byte: Any = False) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_fourwire_obj_send(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_command, ARG_data, ARG_toggle_every_byte }; diff --git a/shared-bindings/displayio/Group.c b/shared-bindings/displayio/Group.c index dd7600eb9c..36e137dc9b 100644 --- a/shared-bindings/displayio/Group.c +++ b/shared-bindings/displayio/Group.c @@ -35,22 +35,23 @@ #include "py/runtime.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Group: +//| """.. currentmodule:: displayio //| -//| :class:`Group` -- Group together sprites and subgroups -//| ========================================================================== +//| :class:`Group` -- Group together sprites and subgroups +//| ========================================================================== //| -//| Manage a group of sprites and groups and how they are inter-related. +//| Manage a group of sprites and groups and how they are inter-related.""" //| -//| .. class:: Group(*, max_size=4, scale=1, x=0, y=0) +//| def __init__(self, *, max_size: int = 4, scale: int = 1, x: int = 0, y: int = 0): +//| """Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 +//| leads to a layer's pixel being 2x2 pixels when in the group. //| -//| Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 -//| leads to a layer's pixel being 2x2 pixels when in the group. -//| -//| :param int max_size: The maximum group size. -//| :param int scale: Scale of layer pixels in one dimension. -//| :param int x: Initial x position within the parent. -//| :param int y: Initial y position within the parent. +//| :param int max_size: The maximum group size. +//| :param int scale: Scale of layer pixels in one dimension. +//| :param int x: Initial x position within the parent. +//| :param int y: Initial y position within the parent.""" +//| ... //| STATIC mp_obj_t displayio_group_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_max_size, ARG_scale, ARG_x, ARG_y }; @@ -90,10 +91,9 @@ displayio_group_t* native_group(mp_obj_t group_obj) { return MP_OBJ_TO_PTR(native_group); } -//| .. attribute:: hidden -//| -//| True when the Group and all of it's layers are not visible. When False, the Group's layers -//| are visible if they haven't been hidden. +//| hidden: Any = ... +//| """True when the Group and all of it's layers are not visible. When False, the Group's layers +//| are visible if they haven't been hidden.""" //| STATIC mp_obj_t displayio_group_obj_get_hidden(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -116,10 +116,9 @@ const mp_obj_property_t displayio_group_hidden_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: scale -//| -//| Scales each pixel within the Group in both directions. For example, when scale=2 each pixel -//| will be represented by 2x2 pixels. +//| scale: Any = ... +//| """Scales each pixel within the Group in both directions. For example, when scale=2 each pixel +//| will be represented by 2x2 pixels.""" //| STATIC mp_obj_t displayio_group_obj_get_scale(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -146,9 +145,8 @@ const mp_obj_property_t displayio_group_scale_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: x -//| -//| X position of the Group in the parent. +//| x: Any = ... +//| """X position of the Group in the parent.""" //| STATIC mp_obj_t displayio_group_obj_get_x(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -172,9 +170,8 @@ const mp_obj_property_t displayio_group_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: y -//| -//| Y position of the Group in the parent. +//| y: Any = ... +//| """Y position of the Group in the parent.""" //| STATIC mp_obj_t displayio_group_obj_get_y(mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -198,9 +195,9 @@ const mp_obj_property_t displayio_group_y_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: append(layer) -//| -//| Append a layer to the group. It will be drawn above other layers. +//| def append(self, layer: Any) -> Any: +//| """Append a layer to the group. It will be drawn above other layers.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_append(mp_obj_t self_in, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -209,9 +206,9 @@ STATIC mp_obj_t displayio_group_obj_append(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_append_obj, displayio_group_obj_append); -//| .. method:: insert(index, layer) -//| -//| Insert a layer into the group. +//| def insert(self, index: Any, layer: Any) -> Any: +//| """Insert a layer into the group.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_insert(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -222,9 +219,9 @@ STATIC mp_obj_t displayio_group_obj_insert(mp_obj_t self_in, mp_obj_t index_obj, MP_DEFINE_CONST_FUN_OBJ_3(displayio_group_insert_obj, displayio_group_obj_insert); -//| .. method:: index(layer) -//| -//| Returns the index of the first copy of layer. Raises ValueError if not found. +//| def index(self, layer: Any) -> Any: +//| """Returns the index of the first copy of layer. Raises ValueError if not found.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_index(mp_obj_t self_in, mp_obj_t layer) { displayio_group_t *self = native_group(self_in); @@ -236,9 +233,9 @@ STATIC mp_obj_t displayio_group_obj_index(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_index_obj, displayio_group_obj_index); -//| .. method:: pop(i=-1) -//| -//| Remove the ith item and return it. +//| def pop(self, i: Any = -1) -> Any: +//| """Remove the ith item and return it.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_pop(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_i }; @@ -259,9 +256,9 @@ STATIC mp_obj_t displayio_group_obj_pop(size_t n_args, const mp_obj_t *pos_args, MP_DEFINE_CONST_FUN_OBJ_KW(displayio_group_pop_obj, 1, displayio_group_obj_pop); -//| .. method:: remove(layer) -//| -//| Remove the first copy of layer. Raises ValueError if it is not present. +//| def remove(self, layer: Any) -> Any: +//| """Remove the first copy of layer. Raises ValueError if it is not present.""" +//| ... //| STATIC mp_obj_t displayio_group_obj_remove(mp_obj_t self_in, mp_obj_t layer) { mp_obj_t index = displayio_group_obj_index(self_in, layer); @@ -272,9 +269,9 @@ STATIC mp_obj_t displayio_group_obj_remove(mp_obj_t self_in, mp_obj_t layer) { } MP_DEFINE_CONST_FUN_OBJ_2(displayio_group_remove_obj, displayio_group_obj_remove); -//| .. method:: __len__() -//| -//| Returns the number of layers in a Group +//| def __len__(self, ) -> Any: +//| """Returns the number of layers in a Group""" +//| ... //| STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { displayio_group_t *self = native_group(self_in); @@ -286,29 +283,29 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: __getitem__(index) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the value at the given index. //| -//| Returns the value at the given index. +//| This allows you to:: //| -//| This allows you to:: +//| print(group[0])""" +//| ... //| -//| print(group[0]) +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the value at the given index. //| -//| .. method:: __setitem__(index, value) +//| This allows you to:: //| -//| Sets the value at the given index. +//| group[0] = sprite""" +//| ... //| -//| This allows you to:: +//| def __delitem__(self, index: Any) -> Any: +//| """Deletes the value at the given index. //| -//| group[0] = sprite +//| This allows you to:: //| -//| .. method:: __delitem__(index) -//| -//| Deletes the value at the given index. -//| -//| This allows you to:: -//| -//| del group[0] +//| del group[0]""" +//| ... //| STATIC mp_obj_t group_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value) { displayio_group_t *self = native_group(self_in); diff --git a/shared-bindings/displayio/I2CDisplay.c b/shared-bindings/displayio/I2CDisplay.c index 963e8377c5..e2402dc49b 100644 --- a/shared-bindings/displayio/I2CDisplay.c +++ b/shared-bindings/displayio/I2CDisplay.c @@ -38,26 +38,27 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class I2CDisplay: +//| """.. currentmodule:: displayio //| -//| :class:`I2CDisplay` -- Manage updating a display over I2C -//| ========================================================================== +//| :class:`I2CDisplay` -- Manage updating a display over I2C +//| ========================================================================== //| -//| Manage updating a display over I2C in the background while Python code runs. -//| It doesn't handle display initialization. +//| Manage updating a display over I2C in the background while Python code runs. +//| It doesn't handle display initialization.""" //| -//| .. class:: I2CDisplay(i2c_bus, *, device_address, reset=None) +//| def __init__(self, i2c_bus: busio.I2C, *, device_address: int, reset: microcontroller.Pin = None): +//| """Create a I2CDisplay object associated with the given I2C bus and reset pin. //| -//| Create a I2CDisplay object associated with the given I2C bus and reset pin. +//| The I2C bus and pins are then in use by the display until `displayio.release_displays()` is +//| called even after a reload. (It does this so CircuitPython can use the display after your code +//| is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The I2C bus and pins are then in use by the display until `displayio.release_displays()` is -//| called even after a reload. (It does this so CircuitPython can use the display after your code -//| is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param busio.I2C i2c_bus: The I2C bus that make up the clock and data lines -//| :param int device_address: The I2C address of the device -//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used +//| :param busio.I2C i2c_bus: The I2C bus that make up the clock and data lines +//| :param int device_address: The I2C address of the device +//| :param microcontroller.Pin reset: Reset pin. When None only software reset can be used""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_i2c_bus, ARG_device_address, ARG_reset }; @@ -80,10 +81,10 @@ STATIC mp_obj_t displayio_i2cdisplay_make_new(const mp_obj_type_t *type, size_t return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_obj_reset(mp_obj_t self_in) { displayio_i2cdisplay_obj_t *self = self_in; @@ -95,10 +96,10 @@ STATIC mp_obj_t displayio_i2cdisplay_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_i2cdisplay_reset_obj, displayio_i2cdisplay_obj_reset); -//| .. method:: send(command, data) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_i2cdisplay_obj_send(mp_obj_t self, mp_obj_t command_obj, mp_obj_t data_obj) { mp_int_t command_int = MP_OBJ_SMALL_INT_VALUE(command_obj); diff --git a/shared-bindings/displayio/OnDiskBitmap.c b/shared-bindings/displayio/OnDiskBitmap.c index 57179947ed..95c890c3b9 100644 --- a/shared-bindings/displayio/OnDiskBitmap.c +++ b/shared-bindings/displayio/OnDiskBitmap.c @@ -33,51 +33,52 @@ #include "supervisor/shared/translate.h" #include "shared-bindings/displayio/OnDiskBitmap.h" -//| .. currentmodule:: displayio +//| class OnDiskBitmap: +//| """.. currentmodule:: displayio //| -//| :class:`OnDiskBitmap` -- Loads pixels straight from disk -//| ========================================================================== +//| :class:`OnDiskBitmap` -- Loads pixels straight from disk +//| ========================================================================== //| -//| Loads values straight from disk. This minimizes memory use but can lead to -//| much slower pixel load times. These load times may result in frame tearing where only part of -//| the image is visible. +//| Loads values straight from disk. This minimizes memory use but can lead to +//| much slower pixel load times. These load times may result in frame tearing where only part of +//| the image is visible. //| -//| It's easiest to use on a board with a built in display such as the `Hallowing M0 Express -//| `_. +//| It's easiest to use on a board with a built in display such as the `Hallowing M0 Express +//| `_. //| -//| .. code-block:: Python +//| .. code-block:: Python //| -//| import board -//| import displayio -//| import time -//| import pulseio +//| import board +//| import displayio +//| import time +//| import pulseio //| -//| board.DISPLAY.auto_brightness = False -//| board.DISPLAY.brightness = 0 -//| splash = displayio.Group() -//| board.DISPLAY.show(splash) +//| board.DISPLAY.auto_brightness = False +//| board.DISPLAY.brightness = 0 +//| splash = displayio.Group() +//| board.DISPLAY.show(splash) //| -//| with open("/sample.bmp", "rb") as f: -//| odb = displayio.OnDiskBitmap(f) -//| face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter()) -//| splash.append(face) -//| # Wait for the image to load. -//| board.DISPLAY.refresh(target_frames_per_second=60) +//| with open("/sample.bmp", "rb") as f: +//| odb = displayio.OnDiskBitmap(f) +//| face = displayio.TileGrid(odb, pixel_shader=displayio.ColorConverter()) +//| splash.append(face) +//| # Wait for the image to load. +//| board.DISPLAY.refresh(target_frames_per_second=60) //| -//| # Fade up the backlight -//| for i in range(100): -//| board.DISPLAY.brightness = 0.01 * i -//| time.sleep(0.05) +//| # Fade up the backlight +//| for i in range(100): +//| board.DISPLAY.brightness = 0.01 * i +//| time.sleep(0.05) //| -//| # Wait forever -//| while True: -//| pass +//| # Wait forever +//| while True: +//| pass""" //| -//| .. class:: OnDiskBitmap(file) +//| def __init__(self, file: file): +//| """Create an OnDiskBitmap object with the given file. //| -//| Create an OnDiskBitmap object with the given file. -//| -//| :param file file: The open bitmap file +//| :param file file: The open bitmap file""" +//| ... //| STATIC mp_obj_t displayio_ondiskbitmap_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -93,9 +94,8 @@ STATIC mp_obj_t displayio_ondiskbitmap_make_new(const mp_obj_type_t *type, size_ return MP_OBJ_FROM_PTR(self); } -//| .. attribute:: width -//| -//| Width of the bitmap. (read only) +//| width: Any = ... +//| """Width of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_ondiskbitmap_obj_get_width(mp_obj_t self_in) { displayio_ondiskbitmap_t *self = MP_OBJ_TO_PTR(self_in); @@ -113,9 +113,8 @@ const mp_obj_property_t displayio_ondiskbitmap_width_obj = { }; -//| .. attribute:: height -//| -//| Height of the bitmap. (read only) +//| height: Any = ... +//| """Height of the bitmap. (read only)""" //| STATIC mp_obj_t displayio_ondiskbitmap_obj_get_height(mp_obj_t self_in) { displayio_ondiskbitmap_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/Palette.c b/shared-bindings/displayio/Palette.c index 67a7db85b8..5df11d2b10 100644 --- a/shared-bindings/displayio/Palette.c +++ b/shared-bindings/displayio/Palette.c @@ -36,19 +36,27 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio + + + + + + +//| class Palette: +//| """.. currentmodule:: displayio //| -//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors -//| ========================================================================================= +//| :class:`Palette` -- Stores a mapping from bitmap pixel palette_indexes to display colors +//| ========================================================================================= //| -//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to -//| save memory. +//| Map a pixel palette_index to a full color. Colors are transformed to the display's format internally to +//| save memory.""" //| -//| .. class:: Palette(color_count) +//| def __init__(self, color_count: int): +//| """Create a Palette object to store a set number of colors. //| -//| Create a Palette object to store a set number of colors. +//| :param int color_count: The number of colors in the Palette""" +//| ... //| -//| :param int color_count: The number of colors in the Palette // TODO(tannewt): Add support for other color formats. // TODO(tannewt): Add support for 8-bit alpha blending. //| @@ -67,9 +75,9 @@ STATIC mp_obj_t displayio_palette_make_new(const mp_obj_type_t *type, size_t n_a return MP_OBJ_FROM_PTR(self); } -//| .. method:: __len__() -//| -//| Returns the number of colors in a Palette +//| def __len__(self, ) -> Any: +//| """Returns the number of colors in a Palette""" +//| ... //| STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); @@ -81,21 +89,21 @@ STATIC mp_obj_t group_unary_op(mp_unary_op_t op, mp_obj_t self_in) { } } -//| .. method:: __setitem__(index, value) +//| def __setitem__(self, index: Any, value: Any) -> Any: +//| """Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1. //| -//| Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1. +//| The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). +//| Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, +//| or a tuple or list of 3 integers. //| -//| The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). -//| Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, -//| or a tuple or list of 3 integers. +//| This allows you to:: //| -//| This allows you to:: -//| -//| palette[0] = 0xFFFFFF # set using an integer -//| palette[1] = b'\xff\xff\x00' # set using 3 bytes -//| palette[2] = b'\xff\xff\x00\x00' # set using 4 bytes -//| palette[3] = bytearray(b'\x00\x00\xFF') # set using a bytearay of 3 or 4 bytes -//| palette[4] = (10, 20, 30) # set using a tuple of 3 integers +//| palette[0] = 0xFFFFFF # set using an integer +//| palette[1] = b'\xff\xff\x00' # set using 3 bytes +//| palette[2] = b'\xff\xff\x00\x00' # set using 4 bytes +//| palette[3] = bytearray(b'\x00\x00\xFF') # set using a bytearay of 3 or 4 bytes +//| palette[4] = (10, 20, 30) # set using a tuple of 3 integers""" +//| ... //| STATIC mp_obj_t palette_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) { if (value == MP_OBJ_NULL) { @@ -144,7 +152,7 @@ STATIC mp_obj_t palette_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t val return mp_const_none; } -//| .. method:: make_transparent(palette_index) +//| def make_transparent(self, palette_index: Any) -> Any: ... //| STATIC mp_obj_t displayio_palette_obj_make_transparent(mp_obj_t self_in, mp_obj_t palette_index_obj) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); @@ -158,7 +166,7 @@ STATIC mp_obj_t displayio_palette_obj_make_transparent(mp_obj_t self_in, mp_obj_ } MP_DEFINE_CONST_FUN_OBJ_2(displayio_palette_make_transparent_obj, displayio_palette_obj_make_transparent); -//| .. method:: make_opaque(palette_index) +//| def make_opaque(self, palette_index: Any) -> Any: ... //| STATIC mp_obj_t displayio_palette_obj_make_opaque(mp_obj_t self_in, mp_obj_t palette_index_obj) { displayio_palette_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c index bdafdaef6d..cedcf1de52 100644 --- a/shared-bindings/displayio/ParallelBus.c +++ b/shared-bindings/displayio/ParallelBus.c @@ -37,31 +37,32 @@ #include "shared-module/displayio/__init__.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class ParallelBus: +//| """.. currentmodule:: displayio //| -//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus -//| ============================================================================== +//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus +//| ============================================================================== //| -//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This -//| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle -//| display initialization. +//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This +//| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle +//| display initialization.""" //| -//| .. class:: ParallelBus(*, data0, command, chip_select, write, read, reset) +//| def __init__(self, *, data0: microcontroller.Pin, command: microcontroller.Pin, chip_select: microcontroller.Pin, write: microcontroller.Pin, read: microcontroller.Pin, reset: microcontroller.Pin): +//| """Create a ParallelBus object associated with the given pins. The bus is inferred from data0 +//| by implying the next 7 additional pins on a given GPIO port. //| -//| Create a ParallelBus object associated with the given pins. The bus is inferred from data0 -//| by implying the next 7 additional pins on a given GPIO port. +//| The parallel bus and pins are then in use by the display until `displayio.release_displays()` +//| is called even after a reload. (It does this so CircuitPython can use the display after your +//| code is done.) So, the first time you initialize a display bus in code.py you should call +//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. //| -//| The parallel bus and pins are then in use by the display until `displayio.release_displays()` -//| is called even after a reload. (It does this so CircuitPython can use the display after your -//| code is done.) So, the first time you initialize a display bus in code.py you should call -//| :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run. -//| -//| :param microcontroller.Pin data0: The first data pin. The rest are implied -//| :param microcontroller.Pin command: Data or command pin -//| :param microcontroller.Pin chip_select: Chip select pin -//| :param microcontroller.Pin write: Write pin -//| :param microcontroller.Pin read: Read pin -//| :param microcontroller.Pin reset: Reset pin +//| :param microcontroller.Pin data0: The first data pin. The rest are implied +//| :param microcontroller.Pin command: Data or command pin +//| :param microcontroller.Pin chip_select: Chip select pin +//| :param microcontroller.Pin write: Write pin +//| :param microcontroller.Pin read: Read pin +//| :param microcontroller.Pin reset: Reset pin""" +//| ... //| STATIC mp_obj_t displayio_parallelbus_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_data0, ARG_command, ARG_chip_select, ARG_write, ARG_read, ARG_reset }; @@ -90,11 +91,12 @@ STATIC mp_obj_t displayio_parallelbus_make_new(const mp_obj_type_t *type, size_t return self; } -//| .. method:: reset() -//| -//| Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin -//| is available. +//| def reset(self, ) -> Any: +//| """Performs a hardware reset via the reset pin. Raises an exception if called when no reset pin +//| is available.""" +//| ... //| + STATIC mp_obj_t displayio_parallelbus_obj_reset(mp_obj_t self_in) { displayio_parallelbus_obj_t *self = self_in; @@ -105,10 +107,10 @@ STATIC mp_obj_t displayio_parallelbus_obj_reset(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(displayio_parallelbus_reset_obj, displayio_parallelbus_obj_reset); -//| .. method:: send(command, data) -//| -//| Sends the given command value followed by the full set of data. Display state, such as -//| vertical scroll, set via ``send`` may or may not be reset once the code is done. +//| def send(self, command: Any, data: Any) -> Any: +//| """Sends the given command value followed by the full set of data. Display state, such as +//| vertical scroll, set via ``send`` may or may not be reset once the code is done.""" +//| ... //| STATIC mp_obj_t displayio_parallelbus_obj_send(mp_obj_t self, mp_obj_t command_obj, mp_obj_t data_obj) { mp_int_t command_int = MP_OBJ_SMALL_INT_VALUE(command_obj); diff --git a/shared-bindings/displayio/Shape.c b/shared-bindings/displayio/Shape.c index 7c7b105015..0f22bb2a3e 100644 --- a/shared-bindings/displayio/Shape.c +++ b/shared-bindings/displayio/Shape.c @@ -34,22 +34,23 @@ #include "shared-bindings/util.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class Shape: +//| """.. currentmodule:: displayio //| -//| :class:`Shape` -- Represents a shape by defining its bounds on each row -//| ========================================================================== +//| :class:`Shape` -- Represents a shape by defining its bounds on each row +//| ========================================================================== //| -//| Represents any shape made by defining boundaries that may be mirrored. +//| Represents any shape made by defining boundaries that may be mirrored.""" //| -//| .. class:: Shape(width, height, *, mirror_x=False, mirror_y=False) +//| def __init__(self, width: int, height: int, *, mirror_x: bool = False, mirror_y: bool = False): +//| """Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the +//| column boundaries of the shape on each row. Each row's boundary defaults to the full row. //| -//| Create a Shape object with the given fixed size. Each pixel is one bit and is stored by the -//| column boundaries of the shape on each row. Each row's boundary defaults to the full row. -//| -//| :param int width: The number of pixels wide -//| :param int height: The number of pixels high -//| :param bool mirror_x: When true the left boundary is mirrored to the right. -//| :param bool mirror_y: When true the top boundary is mirrored to the bottom. +//| :param int width: The number of pixels wide +//| :param int height: The number of pixels high +//| :param bool mirror_x: When true the left boundary is mirrored to the right. +//| :param bool mirror_y: When true the top boundary is mirrored to the bottom.""" +//| ... //| STATIC mp_obj_t displayio_shape_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_width, ARG_height, ARG_mirror_x, ARG_mirror_y }; @@ -83,9 +84,9 @@ STATIC mp_obj_t displayio_shape_make_new(const mp_obj_type_t *type, size_t n_arg } -//| .. method:: set_boundary(y, start_x, end_x) -//| -//| Loads pre-packed data into the given row. +//| def set_boundary(self, y: Any, start_x: Any, end_x: Any) -> Any: +//| """Loads pre-packed data into the given row.""" +//| ... //| STATIC mp_obj_t displayio_shape_obj_set_boundary(size_t n_args, const mp_obj_t *args) { (void) n_args; diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index 288eb4b236..e7410e4b67 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -40,33 +40,33 @@ #include "shared-bindings/displayio/Shape.h" #include "supervisor/shared/translate.h" -//| .. currentmodule:: displayio +//| class TileGrid: +//| """.. currentmodule:: displayio //| -//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap -//| ========================================================================== +//| :class:`TileGrid` -- A grid of tiles sourced out of one bitmap +//| ========================================================================== //| -//| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids -//| can share bitmaps and pixel shaders. +//| Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids +//| can share bitmaps and pixel shaders. //| -//| A single tile grid is also known as a Sprite. +//| A single tile grid is also known as a Sprite.""" //| -//| .. class:: TileGrid(bitmap, *, pixel_shader, width=1, height=1, tile_width=None, tile_height=None, default_tile=0, x=0, y=0) +//| def __init__(self, bitmap: displayio.Bitmap, *, pixel_shader: displayio.Palette, width: int = 1, height: int = 1, tile_width: int = None, tile_height: int = None, default_tile: int = 0, x: int = 0, y: int = 0): +//| """Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to +//| convert the value and its location to a display native pixel color. This may be a simple color +//| palette lookup, a gradient, a pattern or a color transformer. //| -//| Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to -//| convert the value and its location to a display native pixel color. This may be a simple color -//| palette lookup, a gradient, a pattern or a color transformer. +//| tile_width and tile_height match the height of the bitmap by default. //| -//| tile_width and tile_height match the height of the bitmap by default. -//| -//| :param displayio.Bitmap bitmap: The bitmap storing one or more tiles. -//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values -//| :param int width: Width of the grid in tiles. -//| :param int height: Height of the grid in tiles. -//| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param int default_tile: Default tile index to show. -//| :param int x: Initial x position of the left edge within the parent. -//| :param int y: Initial y position of the top edge within the parent. +//| :param displayio.Bitmap bitmap: The bitmap storing one or more tiles. +//| :param displayio.Palette pixel_shader: The pixel shader that produces colors from values +//| :param int width: Width of the grid in tiles. +//| :param int height: Height of the grid in tiles. +//| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. +//| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. +//| :param int default_tile: Default tile index to show. +//| :param int x: Initial x position of the left edge within the parent. +//| :param int y: Initial y position of the top edge within the parent.""" //| STATIC mp_obj_t displayio_tilegrid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_bitmap, ARG_pixel_shader, ARG_width, ARG_height, ARG_tile_width, ARG_tile_height, ARG_default_tile, ARG_x, ARG_y }; @@ -144,9 +144,8 @@ static displayio_tilegrid_t* native_tilegrid(mp_obj_t tilegrid_obj) { mp_obj_assert_native_inited(native_tilegrid); return MP_OBJ_TO_PTR(native_tilegrid); } -//| .. attribute:: hidden -//| -//| True when the TileGrid is hidden. This may be False even when a part of a hidden Group. +//| hidden: Any = ... +//| """True when the TileGrid is hidden. This may be False even when a part of a hidden Group.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_hidden(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -169,9 +168,8 @@ const mp_obj_property_t displayio_tilegrid_hidden_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: x -//| -//| X position of the left edge in the parent. +//| x: Any = ... +//| """X position of the left edge in the parent.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_x(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -195,9 +193,8 @@ const mp_obj_property_t displayio_tilegrid_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: y -//| -//| Y position of the top edge in the parent. +//| y: Any = ... +//| """Y position of the top edge in the parent.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_y(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -221,9 +218,8 @@ const mp_obj_property_t displayio_tilegrid_y_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: flip_x -//| -//| If true, the left edge rendered will be the right edge of the right-most tile. +//| flip_x: Any = ... +//| """If true, the left edge rendered will be the right edge of the right-most tile.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_flip_x(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -246,9 +242,8 @@ const mp_obj_property_t displayio_tilegrid_flip_x_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: flip_y -//| -//| If true, the top edge rendered will be the bottom edge of the bottom-most tile. +//| flip_y: Any = ... +//| """If true, the top edge rendered will be the bottom edge of the bottom-most tile.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_flip_y(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -272,10 +267,9 @@ const mp_obj_property_t displayio_tilegrid_flip_y_obj = { }; -//| .. attribute:: transpose_xy -//| -//| If true, the TileGrid's axis will be swapped. When combined with mirroring, any 90 degree -//| rotation can be achieved along with the corresponding mirrored version. +//| transpose_xy: Any = ... +//| """If true, the TileGrid's axis will be swapped. When combined with mirroring, any 90 degree +//| rotation can be achieved along with the corresponding mirrored version.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_transpose_xy(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -298,9 +292,8 @@ const mp_obj_property_t displayio_tilegrid_transpose_xy_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. attribute:: pixel_shader -//| -//| The pixel shader of the tilegrid. +//| pixel_shader: Any = ... +//| """The pixel shader of the tilegrid.""" //| STATIC mp_obj_t displayio_tilegrid_obj_get_pixel_shader(mp_obj_t self_in) { displayio_tilegrid_t *self = native_tilegrid(self_in); @@ -327,27 +320,27 @@ const mp_obj_property_t displayio_tilegrid_pixel_shader_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: __getitem__(index) +//| def __getitem__(self, index: Any) -> Any: +//| """Returns the tile index at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| Returns the tile index at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. +//| This allows you to:: //| -//| This allows you to:: +//| print(grid[0])""" +//| ... //| -//| print(grid[0]) +//| def __setitem__(self, index: Any, tile_index: Any) -> Any: +//| """Sets the tile index at the given index. The index can either be an x,y tuple or an int equal +//| to ``y * width + x``. //| -//| .. method:: __setitem__(index, tile_index) +//| This allows you to:: //| -//| Sets the tile index at the given index. The index can either be an x,y tuple or an int equal -//| to ``y * width + x``. +//| grid[0] = 10 //| -//| This allows you to:: +//| or:: //| -//| grid[0] = 10 -//| -//| or:: -//| -//| grid[0,0] = 10 +//| grid[0,0] = 10""" +//| ... //| STATIC mp_obj_t tilegrid_subscr(mp_obj_t self_in, mp_obj_t index_obj, mp_obj_t value_obj) { displayio_tilegrid_t *self = native_tilegrid(self_in); diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index f783255930..37c0253292 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -43,7 +43,7 @@ #include "shared-bindings/displayio/Shape.h" #include "shared-bindings/displayio/TileGrid.h" -//| :mod:`displayio` --- Native display driving +//| """:mod:`displayio` --- Native display driving //| ========================================================================= //| //| .. module:: displayio @@ -69,18 +69,18 @@ //| Palette //| ParallelBus //| Shape -//| TileGrid +//| TileGrid""" //| -//| .. function:: release_displays() +//| def release_displays() -> Any: +//| """Releases any actively used displays so their busses and pins can be used again. This will also +//| release the builtin display on boards that have one. You will need to reinitialize it yourself +//| afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing. //| -//| Releases any actively used displays so their busses and pins can be used again. This will also -//| release the builtin display on boards that have one. You will need to reinitialize it yourself -//| afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing. -//| -//| Use this once in your code.py if you initialize a display. Place it right before the -//| initialization so the display is active as long as possible. +//| Use this once in your code.py if you initialize a display. Place it right before the +//| initialization so the display is active as long as possible.""" +//| ... //| STATIC mp_obj_t displayio_release_displays(void) { common_hal_displayio_release_displays();