jdxi_editor.ui.widgets.pitch.pwm_plot
=====================================

.. py:module:: jdxi_editor.ui.widgets.pitch.pwm_plot

.. autoapi-nested-parse::

   Pitch Envelope Plot
   ===================

   This module defines the `ADSRPlot` class, address QWidget subclass that visualizes an ADSR (Attack,
   Decay, Sustain, Release) envelope using Matplotlib. The plot displays the envelope's progression
   over time, with adjustable parameters for attack, decay, sustain, and release times, as well as
   initial, peak, and sustain amplitudes.

   The plot is rendered in address QWidget, and the background and text colors are customized for better
   visibility, with the envelope plotted in orange on address dark gray background.

   Classes:
   --------
   - `ADSRPlot`: A QWidget subclass that generates and displays an ADSR envelope plot.

   Methods:
   --------
   - `__init__(self)`: Initializes the widget and sets up the figure and layout for the plot.
   - `plot_envelope(self)`: Generates and plots the ADSR envelope based on the current envelope parameters.
   - `set_values(self, envelope)`: Updates the envelope parameters and refreshes the plot.

   Customization:
   -------------
   - The plot background is dark gray (`#333333`), with all plot elements (ticks, labels, title) in
     orange for better visibility against the dark background.
   - The time is represented in seconds, and the amplitude in address range from 0 to 1.



Classes
-------

.. autoapisummary::

   jdxi_editor.ui.widgets.pitch.pwm_plot.PWMPlot


Functions
---------

.. autoapisummary::

   jdxi_editor.ui.widgets.pitch.pwm_plot.generate_square_wave


Module Contents
---------------

.. py:function:: generate_square_wave(width: float, mod_depth: float, sample_rate: int, duration: float) -> numpy.ndarray

   Generates a square wave with a given duty cycle (width ∈ [0, 1]).


.. py:class:: PWMPlot(width: int = JDXi.UI.Style.ADSR_PLOT_WIDTH, height: int = JDXi.UI.Style.ADSR_PLOT_HEIGHT, envelope: dict = None, parent: PySide6.QtWidgets.QWidget = None)

   Bases: :py:obj:`jdxi_editor.ui.widgets.plot.base.BasePlotWidget`


   Base class for plot widgets that provides common shading functionality.


   .. py:attribute:: point_moved
      :value: None



   .. py:attribute:: parent
      :value: None



   .. py:attribute:: enabled
      :value: True



   .. py:attribute:: envelope
      :value: None



   .. py:attribute:: sample_rate
      :value: 256



   .. py:attribute:: attack_x
      :value: 0.1



   .. py:attribute:: decay_x
      :value: 0.3



   .. py:attribute:: peak_level
      :value: 0.5



   .. py:attribute:: release_x
      :value: 0.7



   .. py:attribute:: dragging
      :value: None



   .. py:method:: set_values(envelope: dict) -> None

      Update envelope values and trigger address redraw

      :param envelope: dict
      :return: None



   .. py:method:: mousePressEvent(event)


   .. py:method:: mouseMoveEvent(event)


   .. py:method:: mouseReleaseEvent(event)


   .. py:method:: setEnabled(enabled)


   .. py:method:: draw_custom_ticks(ctx: jdxi_editor.ui.widgets.plot.base.PlotContext, config: jdxi_editor.ui.widgets.plot.base.PlotConfig) -> None

      Draw custom tick marks for PWMPlot.



   .. py:method:: draw_grid_hook(ctx: jdxi_editor.ui.widgets.plot.base.PlotContext, config: jdxi_editor.ui.widgets.plot.base.PlotConfig) -> None

      Draw grid for PWMPlot with custom Y callback.



   .. py:method:: envelope_parameters()

      Generate pulse width envelope



   .. py:method:: get_plot_config() -> jdxi_editor.ui.widgets.plot.base.PlotConfig

      Get plot configuration with PWMPlot-specific settings.



   .. py:method:: get_y_range() -> tuple[float, float]

      Get Y range for PWMPlot (-0.2 to 1.2).



   .. py:method:: zero_at_bottom() -> bool

      PWMPlot does not have zero at bottom (uses y_max/y_min scaling).



   .. py:method:: get_title() -> str

      Get plot title.



   .. py:method:: get_x_label() -> str

      Get X-axis label.



   .. py:method:: get_y_label() -> str

      Get Y-axis label.



   .. py:method:: draw_data(ctx: jdxi_editor.ui.widgets.plot.base.PlotContext, config: jdxi_editor.ui.widgets.plot.base.PlotConfig) -> None

      Draw PWMPlot envelope data.