AddRemove Class Reference

Historably add/remove objects into the audio processing path without using locks. More...

Inheritance diagram for AddRemove:

List of all members.

Public Member Functions

AddRemove (ContextItem *parent, void *arg, const QString &des)

AddRemove (ContextItem *parent, void *arg, bool historable, Sheet *sheet, const char *doActionSlot, const char *doSignal, const char *undoActionSlot, const char *undoSignal, const QString &des)

int prepare_actions ()

int do_action ()

int undo_action ()

void set_instantanious (bool instant)

Detailed Description

Historably add/remove objects into the audio processing path without using locks.

AddRemove is a flexible class that let's you insert/remove objects into the audio
processing execution path without using locks.
It can also be used with objects that aren't in the audio processing chain, and don't
need the thread safety. Use set_instantanious() to let the created AddRemove object
know that it can bypass the thread save logic, and call the add/remove functions directly.

The example below is typical how this Command class should be used.

One for example creates the function (slot) Command* add_track() in SheetView. and add
an entry in the keymap file to define which keyfact will be used to call this function.
One also can create a CommandPlugin, and point the keyfact in the keymap file to the
plugin name, this way you don't need to add a function (slot) to the SheetView class.

When using the first approach, you create a new Track object in the GUI object SheetView
and return the Command object returned by m_sheet->add_track(track);, see example code below.

Using a CommandPlugin for this kind of action doesn't make much sense, you most likely
want to use plugins to manipulate existing objects.

        class Sheet : public ContextItem
        {
                Q_OBJECT
                Sheet() {};
                ~Sheet() {};

        private:
                list<Track*> m_tracks;

        public slots:
                Command* add_track(Track* track);
                Command* remove_track(Track* track);
        
        private slots:
                void private_add_track(Track*);
                void private_remove_track(Track*);
        }

        
        Command* Sheet::add_track(Track* track)
        {
                // first this:  The object to which the track has to be added/removed too
                // track:       the argument that will be used by the signal/slots as specified in the second and third line.
                // true:        this command should be considered historable
                // this:        A pointer to Sheet, which in this case is this, which will be used in the AddRemove 
                //              Command logic to detect if the private_add/remove slots can be called directly or 
                //              thread save via Tsar's thread save logic.
                // tr("Add Track")      The (tranlated) description of this action as it will show up in the HistoryView
                return new AddRemove(this, track, true, this,
                        "private_add_track(Track*)", "trackAdded(Track*)",
                        "private_remove_track(Track*)", "trackRemoved(Track*)",
                        tr("Add Track"));
        }

        Command* Sheet::remove_track(Track* track)
        {
                // Same applies as in add_track(), however, the second and third line are switched :-)
                return new AddRemove(this, track, true, this,
                        "private_remove_track(Track*)", "trackRemoved(Track*)",
                        "private_add_track(Track*)", "trackAdded(Track*)",
                        tr("Remove Track"));
        }

        void Sheet::private_add_track(Track* track)
        {
                m_tracks.append(track);
        }
        
        void Sheet::private_remove_track(Track* track)
        {
                m_tracks.removeAll(track);
        }


        // Example usage in a GUI object.
        Command* SheetView::add_track()
        {
                Track* track = new Track(m_sheet);
                return m_sheet->add_track(track);
        }

Constructor & Destructor Documentation

AddRemove::AddRemove	(	ContextItem *	parent,
		void *	arg,
		bool	historable,
		Sheet *	sheet,
		const char *	doActionSlot,
		const char *	doSignal,
		const char *	undoActionSlot,
		const char *	undoSignal,
		const QString &	des
	)

Constructor with all the paramaters needed for proper operation.

Parameters:

	parent	The object (which need to inherit ContextItem) where the arg will be added or removed.
	arg	The object that will be added/removed
	historable	Makes the command historable if set to true, else it will be deleted after the do_action call. Only works when the command was requested from the InputEngine. If not, you are responsible yourself to call the do_action, and pushing it to the correct history stack.
	sheet	If a related Sheet object is available you can use it, else supply a 0
	doActionSlot	(private) slot signature which will be called on do_action()
	doSignal	If supplied, the signal with this signature will be emited in the GUI thread AFTER the actuall adding/removing action in do_action() has happened!
	undoActionSlot	(private) slot signature which will be called in undo_action();
	undoSignal	If supplied, the signal with this signature will be emited in the GUI thread AFTER the actuall adding/removing in undo_action has happened!
	des	Short description that will show up in the history view.

Member Function Documentation

int AddRemove::prepare_actions ( ) [virtual]

Virtual function, needs to be reimplemented for all type of Commands

Use this function to do any kind of calculation or information gathering to be able to perform the actual action in do_action()

Returns:: Return value must != -1 on success, -1 on failure

Reimplemented from Command.

References Tsar::create_event().

int AddRemove::do_action ( ) [virtual]

Virtual function, needs to be reimplemented for all type of Commands

This function is called after the action is finished and each time the historystack 'redoes' an action.
Normally the data created in prepare_actions() will be used here to do the actuall action, which most of the case will be one or a few functions calls.

In case of a Single fact type of Command, you should also retrieve
the 'old' state here to be able to restore it in undo_action()

Reimplemented from Command.

References Tsar::add_event(), Sheet::is_transport_rolling(), and Tsar::process_event_slot_signal().

int AddRemove::undo_action ( ) [virtual]

Virtual function, needs to be reimplemented for all type of Commands

This function is called each time the historystack 'undoes' an action,
use prepare_actions(), or in case of a hold type command begin_hold() to
store the old value(s), your command will change in do_action(), and use
those here to restore the old state.

Reimplemented from Command.

References Tsar::add_event(), Sheet::is_transport_rolling(), and Tsar::process_event_slot_signal().

void AddRemove::set_instantanious ( bool instant )

Set's the command as instantanious

The do/undo actions will call the slot and emit the signal (if they exist) directly, and thus bypassing the RT thread save nature of Tsar.

The documentation for this class was generated from the following files:

Traverso/cvs/traverso/src/commands/AddRemove.h
Traverso/cvs/traverso/src/commands/AddRemove.cpp


Public Member Functions
	AddRemove (ContextItem parent, void arg, const QString &des)
	AddRemove (ContextItem parent, void arg, bool historable, Sheet sheet, const char doActionSlot, const char doSignal, const char undoActionSlot, const char *undoSignal, const QString &des)
int	prepare_actions ()
int	do_action ()
int	undo_action ()
void	set_instantanious (bool instant)