add canvas docs

docs/pages/conf.py

@@ -56,3 +56,5 @@ html_favicon = 'assets/favicon.png'
 autodoc_default_options = {
     'member-order': 'bysource',
 }
+
+add_module_names = False

docs/pages/reference.rst

@@ -3,5 +3,32 @@ Reference
 
 This page contains the API documentation of the ``flipperzero`` module.
 
-.. automodule:: flipperzero
+Vibration
+---------
+
+.. automodule:: flipperzero._vibro
+   :members:
+
+Light
+-----
+
+.. automodule:: flipperzero._light
+   :members:
+
+Speaker
+-------
+
+.. automodule:: flipperzero._speaker
+   :members:
+
+Input
+-----
+
+.. automodule:: flipperzero._input
+   :members:
+
+Canvas
+------
+
+.. automodule:: flipperzero._canvas
    :members:

flipperzero/__init__.py

@@ -1,226 +1,5 @@
-from typing import Callable
-
-LIGHT_RED: int
-'''
-Constant value for the red LED light.
-'''
-
-LIGHT_GREEN: int
-'''
-Constant value for the green LED light.
-'''
-
-LIGHT_BLUE: int
-'''
-Constant value for the blue LED light.
-'''
-
-LIGHT_BACKLIGHT: int
-'''
-Constant value for the display backlight.
-'''
-
-def light_set(light: int, brightness: int) -> None:
-    '''
-    Control the RGB LED on your Flipper. You can also set the brightness of multiple channels at once using bitwise operations.
-    The ``brightness`` parameter accepts values from 0 (light off) to 255 (very bright).
-
-    :param light: The RGB channels to set.
-    :param brightness: The brightness to use.
-
-    :Example:
-    
-    .. code-block::
-    
-        import flipperzero as f0
-        
-        f0.light_set(f0.LIGHT_RED | f0.LIGHT_GREEN, 250)
-
-    .. tip::
-
-        You can use  up to seven colors using `additive mixing <https://en.wikipedia.org/wiki/Additive_color>`_.
-    '''
-    pass
-
-def light_blink_start(light: int, brightness: int, on_time: int, period: int) -> None:
-    '''
-    Let the RGB LED blink. You can define the total duration of a blink period and the duration, the LED is active during a blink period.
-    Hence, ``on_time`` must be smaller than ``period``. This is a non-blocking operation. The LED will continue to blink until you call :func:`light_blink_stop`.
-
-    :param light: The RGB channels to set.
-    :param brightness: The brightness to use.
-    :param on_time: The LED's active duration in milliseconds.
-    :param period: Total duration of a blink period in milliseconds.
-
-    :Example:
-
-    .. code-block::
-    
-        import flipperzero as f0
-        
-        f0.light_blink_start(f0.LIGHT_RED, 150, 100, 200)
-    '''
-    pass
-
-def light_blink_set_color(light: int) -> None:
-    '''
-    Change the RGB LED's color while blinking. This is a non-blocking operation.
-    Be aware, that you must start the blinking procedure first by using the :func:`light_blink_start` function.
-    Call the :func:`light_blink_stop` function to stop the blinking LED.
-
-    :param light: The RGB channels to set.
-    '''
-    pass
-
-def light_blink_stop() -> None:
-    '''
-    Stop the blinking LED.
-    '''
-    pass
-
-def vibro_set(state: bool) -> bool:
-    '''
-    Turn vibration on or off. This is a non-blocking operation. The vibration motor will continue to run until you stop it.
-
-    :param state: :const:`True` to turn on vibration.
-    :returns: :const:`True` if vibration is on.
-    '''
-    pass
-
-def speaker_start(frequency: float, volume: float) -> bool:
-    '''
-    Output a steady tone of a defined frequency and volume on the Flipper's speaker.
-    This is a non-blocking operation. The tone will continue until you call :func:`speaker_stop`.
-    The ``volume`` parameter accepts values from 0.0 (silent) up to 1.0 (very loud).
-
-    :param frequency: The frequency to play in `hertz <https://en.wikipedia.org/wiki/Hertz>`_.
-    :param volume: The volume to use.
-    :returns: :const:`True` if the speaker was acquired.
-
-    :Example:
-
-    .. code-block::
-        
-        import flipperzero as f0
-        
-        f0.speaker_start(50.0, 0.8)
-    '''
-    pass
-
-def speaker_set_volume(volume: float) -> bool:
-    '''
-    Set the speaker's volume while playing a tone. This is a non-blocking operation.
-    The tone will continue until you call :func:`speaker_stop`.
-    The ``volume`` parameter accepts values from 0.0 (silent) up to 1.0 (very loud).
-    
-    :param volume: The volume to use.
-    :returns: :const:`True` if the speaker was acquired.
-
-    :Example:
-
-    This function can be used to play `nice` sounds:
-
-    .. code-block::
-
-        import time
-        import flipperzero as f0
-        
-        volume = 0.8
-
-        f0.speaker_start(100.0, volume)
-
-        for _ in range(0, 150):
-            volume *= 0.9945679
-
-            f0.speaker_set_volume(volume)
-
-            time.sleep_ms(1)
-        
-        f0.speaker_stop()
-    '''
-    pass
-
-def speaker_stop() -> bool:
-    '''
-    Stop the speaker output.
-
-    :returns: :const:`True` if the speaker was successfully released.
-    '''
-    pass
-
-INPUT_BUTTON_UP: int
-'''
-Constant value for the `up` button.
-'''
-
-INPUT_BUTTON_DOWN: int
-'''
-Constant value for the `down` button.
-'''
-
-INPUT_BUTTON_RIGHT: int
-'''
-Constant value for the `right` button.
-'''
-
-INPUT_BUTTON_LEFT: int
-'''
-Constant value for the `left` button.
-'''
-
-INPUT_BUTTON_OK: int
-'''
-Constant value for the `ok` button.
-'''
-
-INPUT_BUTTON_BACK: int
-'''
-Constant value for the `back` button.
-'''
-
-INPUT_TYPE_PRESS: int
-'''
-Constant value for the `press` event of a button.
-'''
-
-INPUT_TYPE_RELEASE: int
-'''
-Constant value for the `release` event of a button.
-'''
-
-INPUT_TYPE_SHORT: int
-'''
-Constant value for the `short` press event of a button.
-'''
-
-INPUT_TYPE_LONG: int
-'''
-Constant value for the `long` press event of a button.
-'''
-
-INPUT_TYPE_REPEAT: int
-'''
-Constant value for the `repeat` press event of a button.
-'''
-
-def on_input() -> Callable[[int, int], None]:
-    '''
-    Decorate a function to be used as input handler. The decorated function will be invoked upon interaction with one of the buttons on the Flipper.
-
-    :Example:
-
-    .. code-block::
-
-        import flipperzero as f0
-
-        @f0.on_input
-        def input_handler(button, type):
-            if button == f0.INPUT_BUTTON_BACK:
-                if type == f0.INPUT_TYPE_LONG:
-                    ...
-    
-    .. warning::
-
-        You can only decorate one function per application.
-    '''
-    pass
+from ._canvas import *
+from ._input import *
+from ._light import *
+from ._speaker import *
+from ._vibro import *

flipperzero/_canvas.py

@@ -0,0 +1,184 @@
+def canvas_update() -> None:
+    '''
+    Updates the display buffer with your drawings from the canvas.
+
+    .. note::
+
+        Your drawings will only appear on the display after this function call.
+    '''
+    pass
+
+def canvas_clear() -> None:
+    '''
+    Clear the whole canvas. This does not affect the current display buffer.
+    You need to call :func:`canvas_update` to reveal your changes.
+    '''
+    pass
+
+def canvas_width() -> int:
+    '''
+    Get the canvas width in pixels.
+
+    :returns: The canvas width.
+    '''
+    pass
+
+def canvas_height() -> int:
+    '''
+    Get the canvas height in pixels.
+
+    :returns: The canvas height.
+    '''
+    pass
+
+COLOR_BLACK: int
+'''
+Constant value for the color `black`.
+'''
+
+COLOR_WHITE: int
+'''
+Constant value for the color `white`.
+'''
+
+def canvas_set_color(color: int) -> None:
+    '''
+    Set the color to use when drawing or writing on the canvas.
+
+    :param color: The color to use.
+    '''
+    pass
+
+ALIGN_BEGIN: int
+'''
+Align element at `begin` (horizontal or vertical, depends on the context).
+'''
+
+ALIGN_END: int
+'''
+Align element at `end` (horizontal or vertical, depends on the context).
+'''
+
+ALIGN_CENTER: int
+'''
+Align element at `center` (horizontal or vertical, depends on the context).
+'''
+
+def canvas_set_text_align(x: int, y: int) -> None:
+    '''
+    Define how the text should be aligned in relation to the ``x`` and ``y`` coordinates 
+    when writing on the canvas, using the :func:`canvas_set_text` function.
+
+    :param x: The horizontal alignment.
+    :param y: The vertical alignment.
+    '''
+    pass
+
+FONT_PRIMARY: int
+'''
+Constant value for the primary font.
+'''
+
+FONT_SECONDARY: int
+'''
+Constant value for the secondary font.
+'''
+
+def canvas_set_font(font: int) -> None:
+    '''
+    Change the font to use when writing on the canvas using the :func:`canvas_set_text` function.
+
+    :param font: The font to use.
+    '''
+    pass
+
+def canvas_set_text(x: int, y: int, text: str) -> None:
+    '''
+    Write text on the canvas at the position of ``x`` and ``y`` by using the currently active color, font and alignment settings.
+    
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    :param text: The text to write.
+    
+    .. code-block::
+
+        import flipperzero as f0
+
+        f0.canvas_set_color(f0.COLOR_BLACK)
+        f0.canvas_set_text_align(f0.ALIGN_CENTER, f0.ALIGN_BEGIN)
+        f0.canvas_set_text(64, 32, 'Hello World!')
+        f0.canvas_update()
+
+    .. seealso::
+
+        * :func:`canvas_set_color` to change the canvas color.
+        * :func:`canvas_set_text_align` to change the alignment settings.
+        * :func:`canvas_set_font` to change the current font.
+    '''
+    pass
+
+def canvas_draw_dot(x: int, y: int) -> None:
+    '''
+    Draw a dot on the canvas by using the currently active color settings.
+
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    '''
+    pass
+
+def canvas_draw_box(x: int, y: int, w: int, h: int, r: int) -> None:
+    '''
+    Draw a box on the canvas. The fill color is defined by the currently active color settings.
+    Set the corner radius to zero to draw a rectangle without rounded corners.
+
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    :param w: The width of the box.
+    :param h: The height of the box.
+    :param r: The corner radius to use.
+    '''
+    pass
+
+def canvas_draw_frame(x: int, y: int, w: int, h: int, r: int) -> None:
+    '''
+    Draw a frame on the canvas. The border color is defined by the currently active color settings.
+    Set the corner radius to zero to draw a rectangle without rounded corners.
+
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    :param w: The width of the box.
+    :param h: The height of the box.
+    :param r: The corner radius to use.
+    '''
+    pass
+
+def canvas_draw_line(x0: int, y0: int, x1: int, y1: int) -> None:
+    '''
+    Draw a line on the canvas. The color is defined by the currently active color settings.
+
+    :param x0: The horizontal start position.
+    :param y0: The vertical start position.
+    :param x1: The horizontal end position.
+    :param y1: The vertical end sposition.
+    '''
+    pass
+
+def canvas_draw_circle(x: int, y: int, r: int) -> None:
+    '''
+    Draw a circle on the canvas. The border color is defined by the currently active color settings.
+
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    :param r: The radius to use.
+    '''
+    pass
+
+def canvas_draw_disc(x: int, y: int, r: int) -> None:
+    '''
+    Draw a disc on the canvas. The fill color is defined by the currently active color settings.
+
+    :param x: The horizontal position.
+    :param y: The vertical position.
+    :param r: The radius to use.
+    '''
+    pass

flipperzero/_input.py

@@ -0,0 +1,76 @@
+from typing import Callable
+
+INPUT_BUTTON_UP: int
+'''
+Constant value for the `up` button.
+'''
+
+INPUT_BUTTON_DOWN: int
+'''
+Constant value for the `down` button.
+'''
+
+INPUT_BUTTON_RIGHT: int
+'''
+Constant value for the `right` button.
+'''
+
+INPUT_BUTTON_LEFT: int
+'''
+Constant value for the `left` button.
+'''
+
+INPUT_BUTTON_OK: int
+'''
+Constant value for the `ok` button.
+'''
+
+INPUT_BUTTON_BACK: int
+'''
+Constant value for the `back` button.
+'''
+
+INPUT_TYPE_PRESS: int
+'''
+Constant value for the `press` event of a button.
+'''
+
+INPUT_TYPE_RELEASE: int
+'''
+Constant value for the `release` event of a button.
+'''
+
+INPUT_TYPE_SHORT: int
+'''
+Constant value for the `short` press event of a button.
+'''
+
+INPUT_TYPE_LONG: int
+'''
+Constant value for the `long` press event of a button.
+'''
+
+INPUT_TYPE_REPEAT: int
+'''
+Constant value for the `repeat` press event of a button.
+'''
+
+def on_input() -> Callable[[int, int], None]:
+    '''
+    Decorate a function to be used as input handler. The decorated function will be invoked upon interaction with one of the buttons on the Flipper.
+
+    .. code-block::
+
+        import flipperzero as f0
+
+        @f0.on_input
+        def input_handler(button, type):
+            if button == f0.INPUT_BUTTON_BACK:
+                if type == f0.INPUT_TYPE_LONG:
+                    ...
+    
+    .. warning::
+
+        You can only decorate one function per application.
+    '''
+    pass

flipperzero/_light.py

@@ -0,0 +1,75 @@
+from typing import Callable
+
+LIGHT_RED: int
+'''
+Constant value for the red LED light.
+'''
+
+LIGHT_GREEN: int
+'''
+Constant value for the green LED light.
+'''
+
+LIGHT_BLUE: int
+'''
+Constant value for the blue LED light.
+'''
+
+LIGHT_BACKLIGHT: int
+'''
+Constant value for the display backlight.
+'''
+
+def light_set(light: int, brightness: int) -> None:
+    '''
+    Control the RGB LED on your Flipper. You can also set the brightness of multiple channels at once using bitwise operations.
+    The ``brightness`` parameter accepts values from 0 (light off) to 255 (very bright).
+
+    :param light: The RGB channels to set.
+    :param brightness: The brightness to use.
+
+    .. code-block::
+    
+        import flipperzero as f0
+        
+        f0.light_set(f0.LIGHT_RED | f0.LIGHT_GREEN, 250)
+
+    .. tip::
+
+        You can use  up to seven colors using `additive mixing <https://en.wikipedia.org/wiki/Additive_color>`_.
+    '''
+    pass
+
+def light_blink_start(light: int, brightness: int, on_time: int, period: int) -> None:
+    '''
+    Let the RGB LED blink. You can define the total duration of a blink period and the duration, the LED is active during a blink period.
+    Hence, ``on_time`` must be smaller than ``period``. This is a non-blocking operation. The LED will continue to blink until you call :func:`light_blink_stop`.
+
+    :param light: The RGB channels to set.
+    :param brightness: The brightness to use.
+    :param on_time: The LED's active duration in milliseconds.
+    :param period: Total duration of a blink period in milliseconds.
+
+    .. code-block::
+    
+        import flipperzero as f0
+        
+        f0.light_blink_start(f0.LIGHT_RED, 150, 100, 200)
+    '''
+    pass
+
+def light_blink_set_color(light: int) -> None:
+    '''
+    Change the RGB LED's color while blinking. This is a non-blocking operation.
+    Be aware, that you must start the blinking procedure first by using the :func:`light_blink_start` function.
+    Call the :func:`light_blink_stop` function to stop the blinking LED.
+
+    :param light: The RGB channels to set.
+    '''
+    pass
+
+def light_blink_stop() -> None:
+    '''
+    Stop the blinking LED.
+    '''
+    pass

flipperzero/_speaker.py

@@ -0,0 +1,56 @@
+def speaker_start(frequency: float, volume: float) -> bool:
+    '''
+    Output a steady tone of a defined frequency and volume on the Flipper's speaker.
+    This is a non-blocking operation. The tone will continue until you call :func:`speaker_stop`.
+    The ``volume`` parameter accepts values from 0.0 (silent) up to 1.0 (very loud).
+
+    :param frequency: The frequency to play in `hertz <https://en.wikipedia.org/wiki/Hertz>`_.
+    :param volume: The volume to use.
+    :returns: :const:`True` if the speaker was acquired.
+
+    .. code-block::
+        
+        import flipperzero as f0
+        
+        f0.speaker_start(50.0, 0.8)
+    '''
+    pass
+
+def speaker_set_volume(volume: float) -> bool:
+    '''
+    Set the speaker's volume while playing a tone. This is a non-blocking operation.
+    The tone will continue until you call :func:`speaker_stop`.
+    The ``volume`` parameter accepts values from 0.0 (silent) up to 1.0 (very loud).
+    
+    :param volume: The volume to use.
+    :returns: :const:`True` if the speaker was acquired.
+
+    This function can be used to play `nice` sounds:
+
+    .. code-block::
+
+        import time
+        import flipperzero as f0
+        
+        volume = 0.8
+
+        f0.speaker_start(100.0, volume)
+
+        for _ in range(0, 150):
+            volume *= 0.9945679
+
+            f0.speaker_set_volume(volume)
+
+            time.sleep_ms(1)
+        
+        f0.speaker_stop()
+    '''
+    pass
+
+def speaker_stop() -> bool:
+    '''
+    Stop the speaker output.
+
+    :returns: :const:`True` if the speaker was successfully released.
+    '''
+    pass

flipperzero/_vibro.py

@@ -0,0 +1,8 @@
+def vibro_set(state: bool) -> bool:
+    '''
+    Turn vibration on or off. This is a non-blocking operation. The vibration motor will continue to run until you stop it.
+
+    :param state: :const:`True` to turn on vibration.
+    :returns: :const:`True` if vibration is on.
+    '''
+    pass