Updated documentation for ControlPanel

Source/AccessClass.h

@@ -42,7 +42,7 @@ class AudioComponent;
   
   Allows subclasses to access important pointers within the application.
 
-  When an object inherits from AccessClass, it's much more convenient to get and
+  When an object inherits from AccessClass, it makes it much more convenient to get and
   set pointers to other objects, such as the EditorViewport, ProcessorList, and
   ProcessorGraph that are used throughout the application. In addition, every subclass 
   of AccessClass automatically adds the MessageCenter as an ActionListener, which means

Source/MainWindow.h

@@ -32,8 +32,6 @@
 #include "Audio/AudioComponent.h"
 #include "Processors/ProcessorGraph.h"
 
-//-----------------------------------------------------------------------
-
 /**
   The main window for the GUI application.
 
@@ -48,21 +46,36 @@
 class MainWindow   : public DocumentWindow
 {
 public:
-    //=======================================================================
+
+    /** Initializes the MainWindow, creates the AudioComponent, ProcessorGraph,
+        and UIComponent, and sets the window boundaries. */
     MainWindow();
+
+    /** Destroys the AudioComponent, ProcessorGraph, and UIComponent, and saves the window boundaries. */
     ~MainWindow();
 
+    /** Called when the user hits the close button of the MainWindow. This destroys
+        the MainWindow and closes the application. */
     void closeButtonPressed();
 
+     /** A JUCE class that allows the MainWindow to respond to keyboard and menubar
+         commands. */
     ApplicationCommandManager commandManager;
 
 private:
-    //========================================================================
   
+    /** Saves the MainWindow's boundaries into the file "windowState.xml", located in the directory
+        from which the GUI is run. */
     void saveWindowBounds();
+
+    /** Loads the MainWindow's boundaries into the file "windowState.xml", located in the directory
+        from which the GUI is run. */
     void loadWindowBounds();
 
+    /** A pointer to the application's AudioComponent (owned by the MainWindow). */
    AudioComponent* audioComponent;
+
+   /** A pointer to the application's ProcessorGraph (owned by the MainWindow). */
    ProcessorGraph* processorGraph;
 
     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MainWindow)

Source/UI/ControlPanel.h

@@ -44,7 +44,14 @@
   
   Toggles data acquisition on and off.
 
-  @see ControlPanel
+  The PlayButton is located in the ControlPanel. Clicking it toggles the state
+  of the ProcessorGraph to either begin the callbacks that drive data through
+  the graph (acquisition on) or end these callbacks (acquisition off). 
+
+  Acquisition can also be started by pressing the RecordButton
+  (assuming callbacks are not already active).
+
+  @see ControlPanel, ProcessorGraph
 
 */
 
@@ -60,7 +67,14 @@ class PlayButton : public DrawableButton
   
   Toggles recording on and off.
 
-  @see ControlPanel
+  The RecordButton is located in the ControlPanel. Clicking it toggles the 
+  state of the RecordNode to either begin saving data (recording on) or 
+  stop saving data (recording off).
+
+  If the RecordButton is pressed while data acquisition is inactive, it 
+  will automatically start data acquisition before recording.
+
+  @see ControlPanel, RecordNode
 
 */
 
@@ -75,6 +89,14 @@ class RecordButton : public DrawableButton
   
   Displays the CPU load used up by the data processing callbacks.
 
+  The CPUMeter is located in the ControlPanel. Whenever acquisition is active,
+  it uses a built-in JUCE method to display the CPU load required to run the ProcessorGraph.
+
+  It's not clear how accurate the meter is, nor how it deals with CPUs using multiple cores.
+
+  For a more accurate measurement of CPU load, it's recommended to use a graphical
+  interface or type 'top' inside a terminal. 
+
   @see ControlPanel
 
 */
@@ -85,8 +107,11 @@ class CPUMeter : public Label
 		CPUMeter();
 		~CPUMeter();
 
+		/** Updates the load level displayed by the CPUMeter. Called by
+		     the ControlPanel. */
 		void updateCPU(float usage);
 
+		/** Draws the CPUMeter. */
 		void paint (Graphics& g);
 	
 	private:
@@ -102,6 +127,11 @@ class CPUMeter : public Label
   
   Displays the amount of disk space left in the current data directory.
 
+  The DiskSpaceMeter is located in the ControlPanel. When the GUI is launched (or the data directory
+  is changed), a built-in JUCE method is used to find the amount of free space.
+
+  Note that the DiskSpaceMeter currently displays only relative, not absolute disk space.
+
   @see ControlPanel
 
 */
@@ -112,8 +142,11 @@ public:
 	DiskSpaceMeter();
 	~DiskSpaceMeter();
 
+	/** Updates the free disk space displayed by the DiskSpaceMeter. Called by
+		the ControlPanel. */
 	void updateDiskSpace(float percent);
 
+	/** Draws the DiskSpaceMeter. */
 	void paint (Graphics& g);
 
 private:
@@ -121,7 +154,6 @@ private:
 	Font font;
 
 	float diskFree;
-	ProcessorGraph* graph;
 	
 };
 
@@ -129,6 +161,16 @@ private:
   
   Displays the time.
 
+  The Clock is located in the ControlPanel. If acquisition (but not recording) is 
+  active, it displays (in yellow) the cumulative amount of time that the GUI has been acquiring data since
+  the application was launched. If recording is active, the Clock displays (in red) the 
+  cumulative amount of time that recording has been active.
+
+  The Clock uses built-in JUCE functions for getting the system time. It does not
+  currently interact with timestamps from ProcessorGraph sources.
+
+  The Clock draws the time using OpenGL (and the FTGL font library).
+
   @see ControlPanel
 
 */
@@ -139,19 +181,30 @@ class Clock : public OpenGLCanvas
 		Clock();
 		~Clock();
 
+		/** Initializes an OpenGL context in which drawing occurs.*/
 		void newOpenGLContextCreated();
+
+		/** Draws the current time.*/
 		void renderOpenGL();
 
+		/** Starts the acquisition (yellow) clock.*/
 		void start();
+
+		/** Stops the acquisition (yellow) clock.*/
 		void stop();
 
+		/** Starts the recording (red) clock.*/
 		void startRecording();
+
+		/** Stops the recording (red) clock.*/
 		void stopRecording();
 
+		/** Sets the cumulative recording time to zero.*/
 		void resetRecordTime();
 
 	private:
 
+		/** Draws the current time.*/
 		void drawTime();
 
 		int64 lastTime;
@@ -169,6 +222,10 @@ class Clock : public OpenGLCanvas
   
   Used to show and hide the file browser within the ControlPanel.
 
+  The ControlPanel contains a JUCE FilenameComponent used to change the 
+  data directory. When not in use, this component can be hidden using
+  the ControlPanelButton.
+
   @see ControlPanel
 
 */
@@ -179,14 +236,22 @@ public:
 	ControlPanelButton(ControlPanel* cp_);
 	~ControlPanelButton();
 
+	/** Returns the open/closed state of the ControlPanelButton.*/
 	bool isOpen() {return open;}
+
+	/** Toggles the open/closed state of the ControlPanelButton.*/
 	void toggleState();
 
+	/** Initializes an OpenGL context in which drawing occurs.*/
 	void newOpenGLContextCreated();
+
+	/** Draws the button. */
 	void renderOpenGL();
 
+	/** Draws the button. */
 	void drawButton();
 
+	/** Responds to mouse clicks within the button. */
 	void mouseDown(const MouseEvent& e);
 
 private:	
@@ -201,11 +266,13 @@ class UtilityButton;
 
 /**
   
-  Provides general application controls.
+  Provides general application controls along the top of the MainWindow.
 
   Displays useful information and provides buttons to control acquistion and recording.
 
-  The ControlPanel is located along the top of the application window.
+  The ControlPanel contains the PlayButton, the RecordButton, the CPUMeter,
+  the DiskSpaceMeter, the Clock, the AudioEditor, and a FilenameComponent for switching the
+  current data directory.
 
   @see UIComponent
 
@@ -213,7 +280,6 @@ class UtilityButton;
 
 class ControlPanel : public Component, 
 					 public Button::Listener,
-					// public ActionListener,
 					 public Timer,
 					 public AccessClass
 
@@ -222,15 +288,24 @@ public:
 	ControlPanel(ProcessorGraph* graph, AudioComponent* audio);
 	~ControlPanel();
 
+	/** Disables the callbacks of the ProcessorGraph (used to
+	    drive data acquisition).*/
 	void disableCallbacks();
 
+	/** Returns a pointer to the AudioEditor.*/
 	AccessClass* getAudioEditor() {return (AccessClass*) audioEditor;}
 
+	/** Sets whether or not the FilenameComponent is visible.*/
 	void openState(bool);
 	
+	/** Toggles the visibility of the FilenameComponent.*/
 	void toggleState();
+
+	/** Used to manually turn recording on and off.*/
 	void setRecordState(bool t);
 
+	/** Returns a boolean that indicates whether or not the FilenameComponet
+	    is visible. */
 	bool isOpen() {return open;}
  
 private:	
@@ -250,15 +325,18 @@ private:
 	void paint(Graphics& g);
 
 	void resized();
+
 	void buttonClicked(Button* button);
 
 	bool initialize;
 
-	//void actionListenerCallback(const String& msg);
-
+	/** Adds the RecordNode as a listener of the FilenameComponent
+	(so it knows when the data directory has changed).*/
 	void updateChildComponents();
 
 	void timerCallback();
+
+	/** Updates the values displayed by the CPUMeter and DiskSpaceMeter.*/
 	void refreshMeters();
 
 	bool keyPressed(const KeyPress &key);
@@ -269,6 +347,7 @@ private:
 
 	Path p1, p2;
 
+	/** Draws the boundaries around the FilenameComponent.*/
 	void createPaths();
 
 };