bug fix: add some comments

Author: shimpe

midicontroller/getinstallpath.py

@@ -18,6 +18,9 @@
 import os.path
 import sys
 def getInstallPath():
+    """
+    function that returns the directory where the script is located
+    """
     thePath = os.path.dirname(sys.argv[0])
     if thePath:
         thePath += os.sep

midicontroller/main.py

@@ -68,7 +68,7 @@ def __init__(self, MainWindow):
         ]
     for i,cb in enumerate(self.midiDeviceComboBoxes):
       cb.currentIndexChanged.connect(self.choose_midi_device_for_channel(i))
-
+    # reset midi channel buttons
     self.resetButtons = [
         self.resetChannel0Button,
         self.resetChannel1Button,
@@ -92,7 +92,6 @@ def __init__(self, MainWindow):
 
     # provide storage to remember the last 512 raw eeg data points
     self.last_512_raw_waves = deque([0]*RAW_VAL_WIN_SIZE, RAW_VAL_WIN_SIZE)
-
     self.counter = 0
 
     # reserve a notequeue to remember 3 notes on each channel
@@ -111,23 +110,29 @@ def __init__(self, MainWindow):
     self.signal_quality = "unknown signal quality"
     self.update_statusbar()
 
+    # instantiate an object that can transform note names to midi numbers
     self.notelookup = notelookup.NoteLookup()
 
-    # more signals
+    # more signals: what to do if a checkbox is clicked
     self.attentionCheckBox.clicked.connect(self.attentionCheckBoxClicked)
     self.meditationCheckBox.clicked.connect(self.meditationCheckBoxClicked)
     self.eyeBlinkCheckBox.clicked.connect(self.eyeBlinkCheckBoxClicked)
 
+    # make sure the menu entries do something
     self.actionQuit.triggered.connect(QtGui.qApp.quit)
     self.actionSave_state.triggered.connect(self.save_state)
     self.actionLoad_state.triggered.connect(self.load_state)
 
+    # determine which ui elements should be saved/loaded
     self.setup_serialization()
 
+    # discover the plugins and display in the ui as needed
     self.setup_plugins()
 
   def setup_serialization(self):
-
+    """
+    function that collects all information required for saving ui state to model file
+    """
     def lineedit_getter(lineedit):
       return "{0}".format(lineedit.text())
 
@@ -168,6 +173,10 @@ def combobox_setter(combobox, value):
     self.serializer.register("eyeBlinkPluginComboBox",self.eyeBlinkPluginComboBox, combobox_getter, combobox_setter)
 
   def setup_plugins(self):
+    """
+    discover all plugins and populate the plugin combo boxes
+    setup signals so that selecting a plugin has some effect
+    """
     self.prevAttentionPluginIndex = 0
     self.prevMeditationPluginIndex = 0
     self.prevEyeBlinkPluginIndex = 0
@@ -196,6 +205,9 @@ def setup_plugins(self):
     self.eyeBlinkPluginSelected(0)
 
   def suspend_plugin(self, plugin_object, section):
+    """
+    define how to suspend a running plugin without deleting it, e.g. when the checkbox is unchecked
+    """
     plugin_object.suspend(section)
     midichan = plugin_object.get_midi_channel_list(section)
     for m in midichan:
@@ -204,6 +216,9 @@ def suspend_plugin(self, plugin_object, section):
           self.midiOut[m].send_message(msg)
 
   def attentionCheckBoxClicked(self):
+    """
+    what to do if the attention check box is clicked
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevAttentionPluginIndex]
@@ -213,6 +228,9 @@ def attentionCheckBoxClicked(self):
       plugin.plugin_object.resume('attention')
 
   def attentionPluginSelected(self, index):
+    """
+    what to do if an attention plugin is selected
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevAttentionPluginIndex]
@@ -225,6 +243,9 @@ def attentionPluginSelected(self, index):
     self.attentionCheckBoxClicked()
 
   def meditationCheckBoxClicked(self):
+    """
+    what to do if meditation checkbox is clicked
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevMeditationPluginIndex]
@@ -235,6 +256,9 @@ def meditationCheckBoxClicked(self):
 
 
   def meditationPluginSelected(self, index):
+    """
+    what to do if a meditation plugin is selected
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevMeditationPluginIndex]
@@ -248,6 +272,9 @@ def meditationPluginSelected(self, index):
 
 
   def eyeBlinkCheckBoxClicked(self):
+    """
+    what to do if the eye blink check box is clicked
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevEyeBlinkPluginIndex]
@@ -257,6 +284,9 @@ def eyeBlinkCheckBoxClicked(self):
       plugin.plugin_object.resume('eyeBlink')
 
   def eyeBlinkPluginSelected(self, index):
+    """
+    what to do if an eye blink plugin is selected
+    """
     from yapsy.PluginManager import PluginManagerSingleton
     manager = PluginManagerSingleton.get()
     plugin = manager.getAllPlugins()[self.prevEyeBlinkPluginIndex]
@@ -269,6 +299,9 @@ def eyeBlinkPluginSelected(self, index):
     self.eyeBlinkCheckBoxClicked()
 
   def save_state(self):
+    """
+    get state of ui and all plugins, and save to file
+    """
     model = self.serializer.ui_to_model()
     plugin_model = {}
     from yapsy.PluginManager import PluginManagerSingleton
@@ -284,6 +317,9 @@ def save_state(self):
       f.write(modelstring)
 
   def load_state(self):
+    """
+    get state of ui and all plugins from file, and set to the ui
+    """
     with open("midicontroller-state.json", "r") as f:
       modelstring = f.read()
     import json
@@ -304,6 +340,9 @@ def load_state(self):
 
 
   def quit_gracefully(self):
+    """
+    switch off all playing notes and delete all plugins
+    """
     for i,mo in enumerate(self.midiOut):
       bytemsg = self.notequeue.clear_notes(i)
       for msg in bytemsg:
@@ -316,7 +355,7 @@ def quit_gracefully(self):
 
   def monitor(self):
     """
-    start/stop button
+    start/stop button pressed
     """
     print "monitor"
     if self.running:
@@ -354,10 +393,16 @@ def monitor(self):
     self.update_statusbar()
 
   def handle_poor_signal(self, headset, value):
+    """
+    react to a poor signal event
+    """
     self.signal_quality = "poor signal quality {0}%".format(value)
     self.MainWindow.update_statusbar_signal.emit()
 
   def handle_good_signal(self, headset, value):
+    """
+    handle to a good signal event
+    """
     self.signal_quality = "good signal quality"
     self.MainWindow.update_statusbar_signal.emit()
 

midicontroller/notelookup.py

@@ -44,6 +44,10 @@ def __init__(self):
             self.lookup_table[string.lower("{0}".format(notename))] = notenumber
 
   def lookup(self, note):
+    """
+    transform midi number string to integer;
+    if that fails, try to convert from note name to midi number
+    """
     try:
       return int(note)
     except ValueError:

midicontroller/notequeue.py

@@ -46,6 +46,9 @@ def play_note(self, channel, note, velocity):
     return msgbytes
 
   def clear_notes(self, channel):
+    """
+    create note off midi msgs for all notes in the channel
+    """
     msgbytes = []
     q = self.qs[channel]
     while q:
@@ -58,6 +61,9 @@ def clear_notes(self, channel):
     return msgbytes
 
   def clear_all_notes(self):
+    """
+    create note off midi msgs for all notes in all channels
+    """
     msgbytes = []
     for i,q in enumerate(self.qs):
       msgbytes.extend(self.clear_notes(i))

midicontroller/plugins/scoregenerators/simplegenerator/notelookup.py

@@ -15,6 +15,8 @@
 #      along with mindwave-python.  If not, see <http://www.gnu.org/licenses/>.  #
 ##################################################################################
 
+# NOTE: duplicated from ../../.. -> need to find out how to use code from parent folders together with yapsy
+
 import string
 
 class NoteLookup(object):

midicontroller/plugins/scoregenerators/simplegenerator/parseutils.py

@@ -15,6 +15,8 @@
 #      along with mindwave-python.  If not, see <http://www.gnu.org/licenses/>.  #
 ##################################################################################
 
+# NOTE: duplicated from ../../.. -> need to find out how to use code from parent folders with yapsy
+
 import notelookup
 
 class ParseUtil(object):

midicontroller/plugins/scoregenerators/simplegenerator/simplegenerator.py

@@ -16,7 +16,6 @@
 ##################################################################################
 
 from yapsy.IPlugin import IPlugin
-from yapsy.PluginManager import PluginManagerSingleton
 import parseutils
 
 from PyQt4 import QtGui
@@ -27,12 +26,19 @@ class SimpleGenerator(IPlugin):
   name = "Simple Generator"
 
   def __init__(self):
+    """
+    set up simple generator plugin
+    """
     super(SimpleGenerator, self).__init__()
     self.parseutil = parseutils.ParseUtil()
     self.instances = {}
     self.playing_suspended = {} 
 
   def get_ui(self, parent, name):
+    """
+    create the ui for embedding in main ui
+    keep a reference for later usage
+    """
     if name in self.instances:
       return self.instances[name][1]
 
@@ -43,6 +49,10 @@ def get_ui(self, parent, name):
     return Panel
 
   def get_state_as_dict(self, parent):
+    """
+    return internal state of the plugin as a dictionary;
+    used during save state to file
+    """
     result = {}
     for name in self.instances:
       if name not in self.instances:
@@ -55,6 +65,10 @@ def get_state_as_dict(self, parent):
     return result
 
   def set_state_from_dict(self, parent, dct):
+    """
+    set internal state of the plugin from a dictionary;
+    used during load state from file
+    """
     for name in dct:
       if name not in self.instances:
         self.get_ui(parent, name)
@@ -64,6 +78,9 @@ def set_state_from_dict(self, parent, dct):
       ui.allowedNotesEdit.setText("{0}".format(dct[name]["allowedNotesEdit"]))
 
   def trigger(self, name, midiOuts, notequeue, value):
+    """
+    method called by the main program to ask the plugin to do something
+    """
     if name not in self.instances:
       return
 
@@ -99,24 +116,37 @@ def trigger(self, name, midiOuts, notequeue, value):
       midiOuts[chan].send_message(msg)
 
   def suspend(self, name):
+    """
+    suspend generating music while not deleting the plugin
+    """
     self.playing_suspended[name] = True
 
   def resume(self, name):
+    """
+    resume generating music
+    """
     self.playing_suspended[name] = False
 
   def is_suspended(self, name):
+    """
+    true if plugin is currently suspended
+    """
     return name in self.playing_suspended and self.playing_suspended[name]
 
   def stop(self, name):
+    """
+    stop and delete plugin
+    """
     if name in self.instances:
       del self.instances[name]
 
   def get_midi_channel_list(self, name):
+    """
+    return a list of all channels this plugin can write midi msgs to
+    """
     if name in self.instances:
       ui = self.instances[name][0]
       midichan = self.parseutil.parse_midi_channel_list(ui.midiChannelEdit.text())
       return midichan
     return []
 
-
-

midicontroller/plugins/scoregenerators/spraycangenerator/notelookup.py

@@ -15,6 +15,8 @@
 #      along with mindwave-python.  If not, see <http://www.gnu.org/licenses/>.  #
 ##################################################################################
 
+# NOTE: duplicated from ../../.. -> need to find out how to use code from parent folder using yapsy
+
 import string
 
 class NoteLookup(object):

midicontroller/plugins/scoregenerators/spraycangenerator/parseutils.py

@@ -15,6 +15,8 @@
 #      along with mindwave-python.  If not, see <http://www.gnu.org/licenses/>.  #
 ##################################################################################
 
+# NOTE: almost duplicated from ../../.. -> need to find out how to use code from parent folder with yapsy
+
 import notelookup
 
 class ParseUtil(object):