[Traverso-devel] Adding a new command to Traverso -> criticism?

[Peter Hoppe]

Hello!

I had some success with adding a new Command to Traverso. I'm sharing this so 
that others may benefit, and I would
appreciate some criticism whether the methodology employed can be improved.

I wanted to implement a command which gets invoked when I hold the CTRL key and 
horizontally drag the mouse over the
Traverso sheet view whilst holding the left mouse button. I actually got it to 
work! This is how I proceeded:

First I needed to register the new command with the all powerfull key map. I 
added an entry in the file
resources/keymap.xml, section 
keymap/Keyfacts/keyfact(type="HKEY",key1="MouseButtonLeft")/Objects:

> <Object
>        objectname="SheetView"
>        mousehint="LR"
>        modifierkeys="CTRL"
>        modes="All"
>        pluginname="TraversoCommands"
>        commandname="TestCmd" />

So, my new command is called TestCmd.


I then had to let Traverso know about this command by registering it with the 
TraversoCommands class. In the source file
src/commands/plugins/TraversoCommands/TraversoCommands.h I added a Q_CLASSINFO 
directive (which, afaik, is for the
context menu in traverso, when the user right clicks over the sheet view):

>    Q_CLASSINFO("Gain", tr("Gain"))
>    Q_CLASSINFO("ResetGain", tr("Gain: Reset"))
>    [...]
>    Q_CLASSINFO("ZzTest", tr("zztest"))


and I also added a new value to the Commands enumerator:
        
> private:
>     enum Commands {
>         GainCommand,
>         [...]
>         ScrollCommand,
>         Zztest
>    };


After that I needed to change the source file 
src/commands/plugins/TraversoCommands/TraversoCommands.cpp by adding
another entry to the m_dict data field, in the cTor. The m_dict field is 
actually a dictionary which maps the
aforementioned TestCmd command (keymap) to the enumerator value Zztest 
(internal traverso representation):

> TraversoCommands::TraversoCommands()
> {
>     m_dict.insert("Gain", GainCommand);
>     [...]
>     m_dict.insert("TestCmd", Zztest);
> }


I then had to add a handler for the new command by adding another case 
construct to the method
Command* TraversoCommands::create(QObject*, const QString&, QVariantList)

>         case Zztest:
>         {
>             SheetView* view = qobject_cast<SheetView*>(obj);
>             if (!view) {
>                 PERROR("TraversoCommands: Supplied QObject was not an 
> SheetView! "
>                         "ArmTracksCommand needs an SheetView as argument");
>                 return 0;
>             }
>             return new ZzTestCommand (view);
>         }


This registers the new command with the TraversoCommands plugin of Traverso.

Of course I didn't have the command itself yet. I still needed to implement it. 
I made a new class, ZzTestCommand which
inherits from the Command class by creating the new header file 
src/commands/ZzTestCommand.h:

> //
> // C++ Interface: ZzTestCommand
> //
> // Description: 
> //
> //
> // Author: Remon Sijrier <>, (C) 2008
> //
> // Copyright: See COPYING file that comes with this distribution
> //
> //
> #ifndef ZZTESTCOMMAND_H
> #define ZZTESTCOMMAND_H
> 
> #include "Command.h"
> 
> class SheetView;
> class QPoint;
> 
> /**
>       @author Remon Sijrier
> */
> class ZzTestCommand : public Command
> {
> public:
>     ZzTestCommand (SheetView* sv);
> 
>     ~ZzTestCommand();
> 
>     int begin_hold();
>     int do_action();
>     int finish_hold();
>     int jog();
>     int prepare_actions();
>     int undo_action();
>     void cancel_action();
>     void set_collected_number(const QString& collected);
>     void set_cursor_shape(int useX, int useY);
> 
> private :
>         SheetView* m_sv;
> };
> 
> #endif


And then I also created a new definition file src/commands/ZzTestCommand.cpp 
which contains the definition for the new
ZzTestCommand class:

> //
> // C++ Implementation: ZzTestCommand
> //
> // Description: 
> //
> //
> // Author: Remon Sijrier <>, (C) 2008
> //
> // Copyright: See COPYING file that comes with this distribution
> //
> //
> #include "ZzTestCommand.h"
> 
> #include "SheetView.h"
> #include "Sheet.h"
> #include "ClipsViewPort.h"
> #include "ContextPointer.h"
> #include <QPoint>
> 
> 
> // Always put me below _all_ includes, this is needed
> // in case we run with memory leak detection enabled!
> #include "Debugger.h"
> 
> ZzTestCommand::ZzTestCommand(SheetView* sv)
>  : Command()
> {
>     PENTERCONS;
> }
> 
> 
> ZzTestCommand::~ZzTestCommand()
> {
>     PENTERDES;
> }
> 
> 
> int ZzTestCommand::begin_hold()
> {
>     PENTER;
>     return 0;
> }
> 
> int ZzTestCommand::do_action()
> {
>     PENTER;
>     return 0;
> }
> 
> int ZzTestCommand::finish_hold()
> {
>     PENTER;
>     return 0;
> }
> 
> int ZzTestCommand::jog()
> {
>     PENTER;
>     return 0;
> }
> 
> int ZzTestCommand::prepare_actions()
> {
>     PENTER;
>     return 0;
> }
> 
> int ZzTestCommand::undo_action()
> {
>     PENTER;
>     return 0;
> }
> 
> void ZzTestCommand::cancel_action()
> {
>     PENTER;
> }
> 
> void ZzTestCommand::set_collected_number(const QString& collected)
> {
>     PENTER;
> }
> 
> void ZzTestCommand::set_cursor_shape(int useX, int useY)
> {
>     PENTER;
> }
> 

I then had to include ZzTestCommand.h in the file src/commands/commands.h

> #include "SplitClip.h"
> #include "MoveClip.h"
> [...]
> #include "ZzTestCommand.h"


That was all on the source code side.  When compiling I had some fun with 
linker errors. The linker swore blind that the
reference to the ZzTestCommand::ZzTestCommand(SheetView* sv) cTor was 
undefined, even though I had included all files
properly. I suspected that the new ZzTestCommand class was somehow not properly 
announced to the cmake system yet. This
proved right; the fix for this was manually adding an entry to the file 
src/commands/CMakeLists.txt


> SET(TRAVERSO_COMMANDS_SOURCES
> AudioClipExternalProcessing.cpp
> AddRemove.cpp
> [...]
> ZzTestCommand.cpp
> )

Finally - the proof - build the project. I had to do a complete rebuild of the 
project with Traverso debug support. For
this, I had to delete the file CMakeCache.txt from the project's root 
directory. Then, in a console, cd into project's
directory

cd {project-dir}

and run 'make clean'

Then run 'cmake .' (with the dot)

Then run 'ccmake .' and switch want_traverso_debug ON.

Finally run 'make'

This built the entire project from scratch.

Finally, in the console, I start Traverso with the --d1 commandline option - 
and now, when I hover the mouse over an
empty part of the sheet (i.e. outside a track), hold the CTRL key and the left 
mouse button and drag the mouse
horizontally I get some interesting output:

> |   [ Trying to find IEAction for key sequence [ MouseButtonLeft ] ]
> |   [ found match in objectUsingModierKeys ]
> |   [ Data found for SheetView! ]
> |   [ setting slotsignature to  ]
> |   [ setting pluginname to TraversoCommands ]
> |   [ setting plugincommand to TestCmd ]
> |   [ InputEngine:: Using plugin TraversoCommands for command TestCmd ]
> |   ENTERING ZzTestCommand (CONSTRUCTOR)
> |   LEAVING ZzTestCommand (CONSTRUCTOR)
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::begin_hold
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::begin_hold
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::set_cursor_shape
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::set_cursor_shape
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::jog
> |   [ release event for hold action detected! ]
> |   [ Finishing hold action 60 ]
> |   ENTERING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::finish_hold
> |   LEAVING 
> /home/peter/Documents/programming/traverso/0.42.0/dev/02_cvs/traverso_0.42.0-003/src/commands/ZzTestCommand.cpp::finish_hold
> |   [ holdingCommand->finish_hold() returned <= 0, so either it failed, or 
> nothing happened! ]
> |   ENTERING ~ZzTestCommand (DESTRUCTOR)
> |   LEAVING ~ZzTestCommand (DESTRUCTOR)


So - success. But - is that maybe all too complicated? Is there another way to 
add a new command class or other classes?
BTW, I'm not looking for help regards the command itself - this was just a test 
to come to know Traverso better. It's
just to know whether my methodology of adding new source files is correct. And 
if so - others can hopefully learn from
this and save a few hours of work.

Thanks very much!


P
-- 
Fame is probably the second most dangerous occupation after working in a coal 
mine
 - Moby