VkCmd(3x)VkCmd(3x)NAMEVkCmd - the simplest command class
INHERITS FROM
VkBase
HEADER FILE
#include <Vk/VkCmd.h>
CLASS DESCRIPTIONVkCmd is the simplest element in the set of ViewKit objects that
support undoable commands. VkCmd can be subclassed to support
commands that can be executed directly, or via a VkCmdManager
object. Subclasses can override the doit() method to define how a
command should be performed, and undoit() to define how it should be
reversed. An optional redoit() method allows commands that need to
perform an action differently if the command is repeated to do so.
If not defined, this method defaults to calling doit().
In the simplest usage, applications would subclass VkCmd to define
doit() and undoit(), instantiate a Cmd object and call doit(), or
undoit() as desired:
VkCmd *cmd = new MyCmd();
cmd->doit();
UNDO SUPPORT
The main benefit of Cmd objects comes from the ability to undo
commands. VkCmd can be used with the VkCmdManager to achieve this.
One can ask the VkCmdManager to execute a cmd object:
VkCmdManager *cmdManager = new VkCmdManager();
cmdManager->run(new MyCmd());
This places the cmd on an undo history list, if the cmd can be
undone. Whether a command can be undone depends on the return value
of the doit() method, which must be one of:
VkCmdUndoable:
The cmd is undoable, and is added to the undo stack. if any
cmds are currently available for redo, the VkCmdManager
flushes them.
Page 1
VkCmd(3x)VkCmd(3x)
VkCmdNotUndoable:
This cmd is not undoable. The VkCmdManager flushes all cmds
on the undo and redo stack.
VkCmdTransparent:
The command does not affect the undo/redo stack.
When used in conjunction with the VkCmdManager and VkMenu
addUndoAction() and addRedoAction() methods, a VkCmd object should
override the getLabel() method, to supply a label to appear in the
Undo and Redo menu commands.
COMMAND REGISTRY
Commands can also be executed by name, provided the command
registers itself with the VkCmdRegistry, a globally available list
that links unique names to a mechanism for creating command objects.
Once registered, a command can be invoked by the VkCmdManager by
name:
cmdManager->run("CutCommand");
To participate in this scheme, commands must register themselves.
This is made easy by two macros. The class record should include the
line:
VK_CMD_DECLARE;
in the public portion of the class record, and also include the
line:
VK_CMD_IMPLEMENT(ClassName, "ClassName");
somewhere in the source file. The first argument is the class name,
while the second is a unique identifier for this command, which is
usually the class name as well.
Before the first time the class is used, the program must call:
Page 2
VkCmd(3x)VkCmd(3x)ClassName::initClass();
where ClassName is the same of the class. In the future, the should
be a class that is able to extract and invoke the initClass() method
from a DSO, allowing for "plugin" commands.
SAMPLE CODE
/usr/share/src/ViewKit/Commands/ByName/
/usr/share/src/ViewKit/Commands/Factories/
/usr/share/src/ViewKit/Commands/Factory2/
/usr/share/src/ViewKit/Commands/Simple/
/usr/share/src/ViewKit/Commands/Undo/
SEE ALSO
VkCmdManager, VkCmdRegistry, VkCmdFactory
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Sheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 3
