Document Param and index classes

src/common/param.py

@@ -1,10 +1,74 @@
+"""
+common > param
+
+Code for interacting with plugin parameters.
+
+Authors:
+* Miguel Guthridge [[email protected], HDSQ#2154]
+
+This code is licensed under the GPL v3 license. Refer to the LICENSE file for
+more details.
+"""
 import plugins
 
 from common.plug_indexes import PluginIndex
+from abc import abstractmethod
+
+
+class PluginParameter:
+ """
+ This is an abstract class used to provide type safety when modifying plugin
+ parameters.
+ """
+
+ @abstractmethod
+ def __init__(self, index: PluginIndex) -> None:
+ """
+ Associate the parameter with a plugin instance. This allows the
+ parameter properties to be modified.
+ """
+ ...
+
+ @abstractmethod
+ @property
+ def value(self) -> float:
+ """
+ The value of the parameter (read/write)
+ """
+ ...
+
+ @value.setter
+ @abstractmethod
+ def value(self, newValue: float):
+ ...
+
+ @abstractmethod
+ @property
+ def name(self) -> str:
+ """
+ The name of the parameter
+ """
+ ...
+
+
+def Param(paramIndex: int) -> type[PluginParameter]:
+ """
+ A `Param` represents a parameter for a plugin. This function generates a
+ `PluginParameter` class that can be used to access the parameter given a
+ plugin instance.
+
+ ```py
+ # Create a parameter definition
+ SustainParam = Param(5)
 
+ # ...
 
-def Param(paramIndex: int):
- class PluginParameter:
+ def eFader1(control: ControlShadowEvent, plugin: GeneratorIndex):
+ # Associate the parameter with the given plugin, then set its value
+ SustainParam(plugin).value = control.value
+ ```
+ """
+ class IndexedPluginParameter(PluginParameter):
  def __init__(self, index: PluginIndex) -> None:
  self.__plug = index
 
@@ -36,4 +100,4 @@ def name(self) -> str:
  True
  )
 
- return PluginParameter
+ return IndexedPluginParameter

src/common/plug_indexes.py

@@ -19,29 +19,60 @@
 
 class FlIndex:
  """
- Represents an index to a plugin or window
+ Represents an index to a plugin or window in FL Studio
  """
  @abstractmethod
  def getName(self) -> str:
+ """
+ Returns the name of the plugin/window at the given index
+ """
  ...
 
  def asWindowIndex(self) -> 'WindowIndex':
+ """
+ Cast this to a WindowIndex
+
+ Raises an error if the index was not a WindowIndex
+
+ ### Raises:
+ * `TypeError`: type cast failed
+
+ ### Returns:
+ * `WindowIndex`: this index, but now guaranteed to be a WindowIndex
+ """
  if isinstance(self, WindowIndex):
  return self
  raise TypeError(f'Cannot cast to WindowIndex, type is {self}')
 
  def asPluginIndex(self) -> 'PluginIndex':
+ """
+ Cast this to a PluginIndex
+
+ Raises an error if the index was not a PluginIndex
+
+ ### Raises:
+ * `TypeError`: type cast failed
+
+ ### Returns:
+ * `PluginIndex`: this index, but now guaranteed to be a PluginIndex
+ """
  if isinstance(self, PluginIndex):
  return self
  raise TypeError(f'Cannot cast to PluginIndex, type is {self}')
 
 
 class WindowIndex(FlIndex):
+ """
+ Represents a window in FL Studio
+ """
  def __init__(self, windowIndex: int) -> None:
  self.__index = windowIndex
 
  @property
  def index(self) -> int:
+ """
+ The index of the window.
+ """
  return self.__index
 
  def __repr__(self) -> str:
@@ -66,19 +97,34 @@ class PluginIndex(FlIndex):
  @abstractmethod
  @property
  def index(self) -> int:
+ """
+ The primary index of this plugin.
+
+ * Global index on the channel rack for generators.
+ * Mixer track for effects.
+ """
  ...
 
  @abstractmethod
  @property
  def slotIndex(self) -> int:
+ """
+ The slot index for effects. `-1` for generators.
+ """
  ...
 
  @property
  def isValid(self) -> bool:
+ """
+ `True` when the plugin is valid.
+ """
  return plugins.isValid(self.index, self.slotIndex, True)
 
  @property
  def isVst(self) -> bool:
+ """
+ `True` when the plugin is a VST.
+ """
  if self.isValid:
  paramCount = plugins.getParamCount(
  self.index,
@@ -90,6 +136,9 @@ def isVst(self) -> bool:
  else:
  return False
 
+ def getName(self) -> str:
+ return plugins.getPluginName(self.index, self.slotIndex, False, True)
+
 
 class GeneratorIndex(PluginIndex):
  def __init__(self, index: int) -> None:
@@ -100,15 +149,18 @@ def __repr__(self) -> str:
 
  @property
  def index(self) -> int:
+ """
+ The global index of the channel rack slot that contains the plugin.
+ """
  return self.__index
 
  @property
  def slotIndex(self) -> Literal[-1]:
+ """
+ This value is always `-1` for generator plugins.
+ """
  return -1
 
- def getName(self) -> str:
- return plugins.getPluginName(self.index, -1, False, True)
-
 
 class EffectIndex(PluginIndex):
  def __init__(self, index: int, slotIndex: int) -> None:
@@ -121,11 +173,14 @@ def __repr__(self) -> str:
 
  @property
  def index(self) -> int:
+ """
+ The mixer track that contains the plugin.
+ """
  return self.__index
 
  @property
  def slotIndex(self) -> int:
+ """
+ The mixer slot that contains the plugin.
+ """
  return self.__slot
-
- def getName(self) -> str:
- return plugins.getPluginName(self.index, -1, False, True)