VkCmd(3x)

NAME
     VkCmd - the simplest command class

INHERITS FROM
     VkBase

HEADER FILE
     #include <Vk/VkCmd.h>

CLASS DESCRIPTION
          VkCmd 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.
              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:

             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