Command Class Reference

An Interface class for creating ('analog', or holding command type) un/redoable actions. More...

Inheritance diagram for Command:

List of all members.

Public Member Functions
	Command (ContextItem *item, const QString &des="No description set!")
	Command (const QString &des="No description set!")
virtual int	begin_hold ()
virtual int	finish_hold ()
virtual int	prepare_actions ()
virtual int	do_action ()
virtual int	undo_action ()
virtual int	jog ()
virtual void	set_cursor_shape (int useX, int useY)
virtual void	cancel_action ()
virtual void	set_collected_number (const QString &collected)
void	undo ()
void	redo ()
void	set_valid (bool valid)
void	set_historable (bool historible)
int	push_to_history_stack ()
Static Public Member Functions
static void	process_command (Command *cmd)
Protected Attributes
bool	m_isValid
bool	m_isHistorable
QString	m_description

---

Detailed Description

An Interface class for creating ('analog', or holding command type) un/redoable actions.

Traverso uses the Command pattern for 2 purposes: Creating historable actions and the so called 'hold actions', providing an easy way to create 'analog' user interface interactions.

There are 2 types of Commands possible, the 'Single fact' type, which only needs to reimplement the do_action(), undo_action() and prepare_actions() functions, and the "Hold fact' type, which also reimplements the jog() function, together with the begin_hold() and finish_hold() functions.

Single Fact type function call order:

• prepare_actions(), if it returns -1, the InputEngine will recognise it as a failed command, and delete it.
  
• do_action(), the actuall action to be performed will happen here

Hold Fact type function call order:

• begin_hold(), if it returns -1, the InputEngine will recognise it as a failed command, and delete it.
  
• set_cursor_shape(), the default mouse gesture cursor is used, reimplement to set a custom one, or to use the advanced HoldCursor of the ViewPort
  
• jog(), as long as the hold action remains true (the key(s) remain pressed) jog() is called during mouse movement, here you can do the calculations for analog type of actions.
  
• finish_hold(), the return value isn't used at the moment.
  
• prepare_actions(),if it returns -1, the InputEngine will recognise it as a failed command, and delete it.
  
• do_action(), the actual action will happen here.

For detailed information on how to use Command objects in Traverso, see InputEngine

---

Constructor & Destructor Documentation

Command::Command	(	ContextItem *	item,
		const QString &	des = "No description set!"
	)

Constructor with a ContextItem as parameter, which will be used to retrieve the historystack from. This Command tries to put itself on the ContextItem's history stack after the action is finished.

Parameters:

	item	The ContextItem this Command operates on
	des	The description as will show up in the HistoryView

References ContextItem::get_history_stack().

Command::Command

(

const QString &

des = "No description set!"

)

Command constructor that only takes a description string. This type of Command doesn't know about a historystack So won't be un/redoable.

Parameters:

des

The description of the action

---

Member Function Documentation

int Command::begin_hold

(

)

[virtual]

Virtual function, only needs to be reimplemented when making a hold type of Command

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

Returns:

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

Reimplemented in Gain, MoveClip, PCommand, and TrackPan.

int Command::finish_hold

(

)

[virtual]

Virtual function, only needs to be reimplemented when making a hold type of Command

Returns:

Return value not used right now

Reimplemented in Gain, MoveClip, PCommand, and TrackPan.

int Command::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 in AddRemove, CommandGroup, Gain, MoveClip, PCommand, and TrackPan.

Referenced by CommandGroup::prepare_actions().

int Command::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 in AddRemove, CommandGroup, Gain, MoveClip, PCommand, and TrackPan.

Referenced by CommandGroup::do_action().

int Command::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 in AddRemove, CommandGroup, Gain, MoveClip, PCommand, and TrackPan.

Referenced by CommandGroup::undo_action().

int Command::jog

(

)

[virtual]

Virtual function, only needs to be reimplemented when making a hold type of Command

This function makes it possible to create 'analog' type of actions possible.
Use the convenience functions of ContextPointer to get scene x and y coordinates
to move or adjust canvas items positions/parameters.

Returns:

Return value not used right now

Reimplemented in Gain, MoveClip, and TrackPan.

void Command::set_cursor_shape	(	int	useX,
		int	useY
	)			[virtual]

Uses the mouse hints specified in the keymap.xml file to set a cursor to hint the user which movement has to be made on hold type of commands

Reimplement if you want a different type of cursor, or want to use the more advanced HoldCursor supplied by ViewPort

Parameters:

	useX	If 1, suggests horizontal mouse movement
	useY	If 1, suggests vertical mouse movement

Reimplemented in Gain, MoveClip, and TrackPan.

References ContextPointer::get_viewport(), and ViewPort::reset_cursor().

void Command::cancel_action

(

)

[virtual]

Cancels the action (makes only sense for hold type of actions). Reimplement to undo any changes allready made, either be it data from the core that has changed, or e.g. gui items who moved in the jog() function.

Reimplemented in Gain, MoveClip, and TrackPan.

void Command::set_collected_number

(

const QString &

collected

)

[virtual]

Reimplement this function to receive the so called 'collected number' of the InputEngine

The number collection is active during Hold Actions. A Hold type of command can use it to let the user type in a numerical value, which is then parsed by the (derived) Command class to set the variable it controls, like the position of an AudioClip, or the gain value of a Track

Parameters:

collected

The QString of the collected number so far. Note that it can include a . (period) and a , (comma), hence the number is supplied as a string, and not a numerical value.

Reimplemented in Gain.

void Command::set_valid

(

bool

valid

)

Used by the InputEngine to set a Command valid or not, which is detected by the return values of begin_hold(), prepare_actions()

Only valid commands will be pushed upon the historystack.

Parameters:

valid

---

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

• Traverso/cvs/traverso/src/core/Command.h
• Traverso/cvs/traverso/src/core/Command.cpp