[Clam-devel] Adding Monitors + LPC on Prototyper

[David García Garzón]

I did a document sumarizing what you have to do currently in order to have a 
new Monitor properly working. Beside being useful for a developer to do it, 
it is also a comprehension exercise for me in order to start  a refactor to 
simplify the process.

The wiki and cvs are not working so i email it here until it is up again.

I wrote the document while implementing LPC integration in NetworkEditor. 
Screenshot attatched.


-- 
David García Garzón
(Work) dgarcia at iua dot upf anotherdot es
(Home) vokimon at telefonica adot net
http://www.iua.upf.edu/~dgarcia
-------------- next part --------------
This document describes the steps to having a new graphical monitor.
I wrote it with a double aim, to have a reference for people adding monitors,
and to have an overall view of the process which is very complex now,
in order to reduce the number of steps.

== Getting the monitor working on the NetworkEditor ==

Create a Monitor class (MyViewMonitor) with double derivation from:
	- PortMonitor templated by the port data, which gives the class:
		- input ports of the proper class, and
		- thread safe access to the data from the GUI thread.
	- XXXXAudioSource which gives the class:
		- abstract interface to be used by the visualization to get data
	- The implementation should implement XXXXAudioSource interface to
	  to map DSP data to visualization, and metadata (units, sizes, limits...)
	- Such implementation should access the data using the PortMonitor
	  thread safe interface.
	- TODO: The policy to remove PortMonitor freeze is not well defined among DataSources.
		- Copy and release
		- Explicit release from the widget
	- See examples at chordWidgets

Create a view widget (MyView) attached to the audio source
	- The widget should freeze the Monitor and use/copy the data
	- (see ChordWidgets).
	- Use QDESIGNER_WIDGET_EXPORT macro after 'class' keyword:
		#include <QtDesigner/QDesignerExportWidget>
		class QDESIGNER_WIDGET_EXPORT Oscilloscope : public QWidget
	- Don't forget the Q_OBJECT macro for the widget.
	- Define as Q_PROPERTY the editable attributes from designer
		http://doc.trolltech.com/latest/properties.html
	- If you use the QGLWidget remember to undefine GetClassName for Windows(tm) glory
	- Define two constructors
		- One passing a data source
		- Other not to be called by Designer to have a dummy data source.
Register in the factory the monitor with the name of the view (Why?)
	- The GetClassName for the PortMonitor should match the view name too. (Why?)
Add the PortMonitor to the ProcessingTree (indeed the view name).

Add an entry on the embededWidgetFor() function at ProcessingBox.cxx
which on the given name creates the view and relates to the monitor.

    if (className=="MyView")
        return new MyView(canvas, dynamic_cast<MyViewMonitor*>(processing));


== Getting the Monitor working on Qt Designer ==

Create a plugin file such the ones in src/clamWidgetsPlugins
	- Copy an example in src/clamWidgetsPlugins and adapt the class names
      to the one of the Widget
	- If the view has a namespace you should use it as part of the name (why?)
	- Don't forget to change the example name on the doXml and the icon which are lowercase
	- Add an icon on the images.qrc file and refer it on the icon() method and change it

Include the plugin on the aggregated plugin at CLAMWidgets.cxx.

Add the widget source into the plugin sources on the SConstruct
	pluginsources.append(os.path.join('src','chordWidgets','MyView.cxx'))

== Getting the Monitor working on Prototyper ==

On PrototypeLoader::ConnectWithNetwork() add a line with:
    ConnectWidgetsWithPorts<CLAM::VM::MyView,MyViewMonitor>
        ("OutPort__.*", "CLAM::VM::MyView");
And of course the needed includes






-------------- next part --------------
A non-text attachment was scrubbed...
Name: lpc-prototyper.png
Type: image/png
Size: 14103 bytes
Desc: not available
URL: <http://lists.clam-project.org/pipermail/clam-devel-clam-project.org/attachments/20070404/750239a7/attachment-0002.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.clam-project.org/pipermail/clam-devel-clam-project.org/attachments/20070404/750239a7/attachment-0002.pgp>