sheets/doc/Commands.dox

0001 /**
0002 \page commands Commands
0003
0004 To implement undo and redo functionality, every possible action
0005 by the user for editing and manipulating the document is encapsulated
0006 in a command (based on QUndoCommand).
0007 There is one command class (which will be instantiated) for every unique
0008 action. You need to reimplement the redo() and undo() methods
0009 of QUndoCommand.
0010
0011 Each command is created from the user interface.
0012 The commands working on cell ranges, i.e. derivatives of KSpread::AbstractRegionCommand,
0013 have to check whether the operation is allowed before execution. Cells may be
0014 protected or locked as elements of matrices. KSpread::AbstractRegionCommand::execute
0015 takes care of that. If the operation is not allowed, the command will neither
0016 get executed nor added to the undo stack.
0017 All other commands can be added directly to the undo stack by using
0018 KoDocument::addCommand or KoCanvasBase::addCommand, which executes the operation immediately.
0019
0020 This is an example of typical use of a command NOT processing cell ranges:
0021 \code
0022     QUndoCommand* command = new KSpread::RenameSheetCommand( sheet, name );
0023     doc->addCommand( command );
0024 \endcode
0025 This is an example of typical use of a command, which works on a cell range:
0026 \code
0027     KSpread::CommentCommand* command = new KSpread::CommentCommand();
0028     command->setSheet( sheet );
0029     command->setName( i18n( "Add Comment" ) );
0030     command->setComment( comment );
0031     command->add( cellRegion );
0032     command->execute();
0033 \endcode
0034
0035 Then whenever the user triggers an "undo", the corresponding
0036 undo() method of the command is called by the undo action,
0037 thereby reverting the previously executed command. Similar thing
0038 happens for the "redo".
0039
0040 All command classes reside in the subdirectory commands/.
0041
0042 \sa KoDocument::addCommand
0043 */