VkCmd(3x)							     VkCmd(3x)

NAME    [Toc]    [Back]

     VkCmd - the simplest command class

INHERITS FROM    [Toc]    [Back]

     VkBase

HEADER FILE    [Toc]    [Back]

     #include <Vk/VkCmd.h>

CLASS DESCRIPTION    [Toc]    [Back]

	  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    [Toc]    [Back]

	  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    [Toc]    [Back]

     /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    [Toc]    [Back]

     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


									PPPPaaaaggggeeee 3333