library: libCore #include "TQCommand.h"

# TQCommand

class description - source file - inheritance tree (.pdf)

## class TQCommand : public TList, public TQObject

| Inheritance Chart:
`TObject`
| <- | `TCollection`
| <- | `TSeqCollection`
| <- | `TList`
`TQObject`
| <- | `TQCommand` |
<- |
`TQUndoManager` |

        protected:

          virtual void Init(const char* cl, void* object, const char* redo, const char* undo)

        public:

                              TQCommand(const char* cl = "0", void* object = 0, const char* redo = "0", const char* undo = "0")
                              TQCommand(TObject* obj, const char* redo = "0", const char* undo = "0")
                              TQCommand(const TQCommand& com)
                      virtual ~TQCommand()
                 virtual void Add(TObject* obj, Option_t* opt)
                 virtual void Add(TObject* obj)
               virtual Bool_t CanCompress(TQCommand* c) const
               virtual Bool_t CanMerge(TQCommand* c) const
               virtual Bool_t CanRedo() const
               virtual Bool_t CanUndo() const
               static TClass* Class()
                 virtual void Compress(TQCommand* c)
                 virtual void Delete(Option_t* option = "")
            static TQCommand* gCommand()
          virtual const char* GetName() const
                        Int_t GetNRargs() const
                        Int_t GetNUargs() const
                        void* GetObject() const
                TQConnection* GetRedo() const
                      Long_t* GetRedoArgs() const
                  const char* GetRedoName() const
                        Int_t GetStatus() const
          virtual const char* GetTitle() const
                TQConnection* GetUndo() const
                      Long_t* GetUndoArgs() const
                  const char* GetUndoName() const
              virtual TClass* IsA() const
               virtual Bool_t IsEqual(const TObject* obj) const
                       Bool_t IsExecuting() const
                       Bool_t IsMacro() const
                       Bool_t IsRedoing() const
               virtual Bool_t IsSetter() const
                       Bool_t IsUndoing() const
                 virtual void ls(Option_t* option = "") const
                 virtual void Merge(TQCommand* c)
                 virtual void Print(Option_t* option = "") const
                 virtual void Print(Option_t*, Option_t* option) const
                 virtual void Redo(Option_t* option = "")
                 virtual void SetArgs(Int_t nargs)
                 virtual void SetName(const char* name)
                 virtual void SetRedoArgs(Int_t nargs)
                 virtual void SetTitle(const char* title)
                 virtual void SetUndoArgs(Int_t nargs)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)
                 virtual void Undo(Option_t* option = "")

### Data Members

        protected:

          TQConnection* fRedo       do/redo action
          TQConnection* fUndo       undo action
                Long_t* fRedoArgs   redo values
                Long_t* fUndoArgs   undo values
                  Int_t fNRargs     number of redo arguments
                  Int_t fNUargs     number of undo arguments
                  Int_t fState      -1 undoing on, 1 redoing on, 0 nothing in progress
                  Int_t fStatus     fStatus++ after Redo(), fStatus-- after Undo()
                 Bool_t fNewDelete  kTRUE if Redo/Undo methods are new/delete
                TString fName       command name. Default is "ClassName::RedoName(args)"
                TString fTitle      command description
                  void* fObject     object to which undo/redo actions applied

## Class Description

     The Command design pattern is based on the idea, that all editing
     in an application is done by creating instances of command objects.
     Command objects apply changes to the edited object and then are
     stored  on a command stack. Furthermore, each command knows how to
     undo its changes to bring the edited object back to its previous
     state. As long as the application only uses command objects to
     change the state of the edited object, it is possible to undo
     a sequence of commands by traversing the command stack downwards and
     calling the "undo" method of each command in turn. It is also
     possible to redo a sequence of commands by traversing the command
     stack upwards and calling the "redo" method of each command.

     Examples:

     1. Create a new command

     TQCommand *com = new TQCommand("TH1", hpx, "SetFillColor(Color_t)"
                                    "SetFillColor(Color_t)");

     1st parameter - the name of class
     2nd parameter - object
     3rd parameter - the name of do/redo method
     4th parameter - the name of undo method

     Since redo,undo methods are the same, undo name can be omitted, e.g.

     TQCommand *com = new TQCommand("TH1", hpx, "SetFillColor(Color_t)");

     For objects derived from TObject class name can be omitted, e.g.

        TQCommand *com = new TQCommand(hpx, "SetFillColor(Color_t)");

     2. Setting undo, redo parameters.

        Color_t old_color = hpx->GetFillColor();
        Color_t new_color = 4;  // blue color

        com->SetRedoArgs(1, new_color);
        com->SetUndoArgs(1, old_color);

     1st argument - the number of undo, redo parameters
     the other arguments - undo, redo values

     Since the number of undo,redo parameters is the same one can use

        com->SetArgs(1, new_color, old_color);

     3. Undo, redo method execution

        com->Redo(); // execute redo method
        com->Undo(); // execute undo method

     4. Merged commands

     It possible to group several commands together so an end user
     can undo and redo them with one command.

        TQCommand *update = new TQCommand(gPad, "Modified()");
        com->Add(update);

     5. Macro commands

     "Merging" allows to create macro commands, e.g.

        TQCommand *macro = new TQCommand("my macro");
        macro->Add(com1);
        macro->Add(com2);
        ...

     During Redo operation commands composing macro command are executed
     sequentially in direct  order (first in first out). During Undo,
     they are executed in reverse order (last in first out).

     6. Undo manager.

     TQUndoManager is recorder of undo and redo operations. This is
     command history list which can be traversed backwards and upwards
     performing undo and redo operations.
     To register command TQUndoManager::Add(TObject*) method is used.

        TQUndoManager *history = new TQUndoManager();
        history->Add(com);

     TQUndoManager::Add automatically invokes execution of command's
     Redo method.

     Use TQUndoManager::Undo to undo commands in  history list.
     Redo is Undo for undo action. Use TQUndoManager::Redo method for that

void Init(const char *clname, void *obj, const char *redo, const char *undo)

     common protected method used in several constructors

TQCommand(const char *clname, void *obj, const char *redo, const char *undo) : TList(), TQObject()

     Constructor.

       Input parameters:
         1. clname - class name.
         2. obj - an object
         3. redo - method or function to do/redo operation
         4. undo - method or function to undo operation

     Comments:
        - if either clname or obj is NULL that means that redo/undo is function
        - to specify default arguments for redo/undo method/function
           '=' must precede to argument value.

      Example:
        TQCommand("TPad", gPad, "SetEditable(=kTRUE)", "SetEditable(=kFALSE)");

        - undo method can be same as redo one. In that case undo parameter
           can be omitted.

      Example:
        TQCommand("TPad", gPad, "SetFillStyle(Style_t)");

TQCommand(TObject *obj, const char *redo, const char *undo) : TList(), TQObject()

     Constructor.

       Input parameters:
         1. obj - an object
         2. redo - method or function to do/redo operation
         3. undo - method or function to undo operation

     Comments:
        - to specify default arguments for redo/undo method/function
           '=' must precede to argument value.

      Example:
        TQCommand(gPad, "SetEditable(=kTRUE)", "SetEditable(=kFALSE)");

        - undo method can be same as redo one. In that case "undo"
           can parameter be omitted.

      Example:
        TQCommand(gPad, "SetFillStyle(Style_t)");

TQCommand(const TQCommand &com) : TList(), TQObject()

     Copy constructor.

~TQCommand()

     dtor.

TQCommand* gCommand()

     Return a command which is doing redo/undo action

     This static method allows to set undo parameters dynamically, i.e.
     during execution of Redo function.

     Example:
        For redo actions like TGTextEdit::DelChar() it is not possible to
        know ahead what character will be deleted.
        To set arguments for undo action ( e.g. TGTextEdit::InsChar(char)),
        one needs to call TQCommand::SetUndoArgs(1, character) from
        inside of TGTextEdit::DelChar() method, i.e.

        TQCommand::gCommand()->SetUndoArgs(1, somechar);

void Delete(Option_t *opt)

     If "opt" is not zero delete every merged command which option string is
     equal to "opt". If "opt" is zero - delete all merged commands.

Bool_t CanMerge(TQCommand *) const

     Two commands can be merged if they can be composed into
     a single command (Macro command).

     To allow merging commands user might override this function.

void Merge(TQCommand *c)

     Add command to the list of merged commands.
     This make it possible to group complex actions together so an end user
     can undo and redo them with one command. Execution of TQUndoManager::Undo(),
     TQUndoManager::Redo() methods only invokes the top level command as a whole.

     Merge method is analogous to logical join operation.

     Note:  Merge method invokes redo action.

void Add(TObject *obj, Option_t *opt)

     Add command to the list of merged commands.

     Option string can contain substrings:
      "compress" - try to compress input command
      "radd" - execute redo action of input command
      "uadd" - execute undo action of input command

Bool_t CanCompress(TQCommand *c) const

     By default, commands can be compressed if they are:

      - equal
      - setter commands

     More complicated commands might want to override this function.

void Compress(TQCommand *c)

     Compress command. Compression is analogous to arithmetic "addition operation".

     Note:
        - The compressed command will be deleted.
        - Execution Compress method invokes Redo action with new redo arguments
          inheritied from compressed command.

     More complicated commands might want to override this function.

Bool_t IsEqual(const TObject* obj) const

     Equal comparison. The commands are equal if they are
     applied to the same object and have the same Redo/Undo actions

     More complicated commands might want to override this function.

Bool_t IsSetter() const

     Returns kTRUE is command if Redo is the same as Undo function
     and is the setter action.

     By default, all functions with names like "SetXXX" or "setXXX"
     considered as setters. Another type of setters are Move, Resize operations

     More complicated commands might want to override this function.

void SetArgs(Int_t narg, ...)

     Set do/redo and undo parameters. The format is
        SetArgs(number_of_params, redo_params, undo_params)

     Example:
         move_command->SetArgs(2, 100, 100, 200, 200);
          2 params, (100,100) - do/redo position, (200,200) - undo position

void SetRedoArgs(Int_t narg, ...)

     Set redo parameters. The format is
        SetRedoArgs(number_of_params, params)

     Example:
         move_command->SetRedoArgs(2, 100, 100);

void SetUndoArgs(Int_t narg, ...)

     Set undo parameters. The format is
        SetUndoArgs(number_of_params, params)

     Example:
         move_command->SetUndoArgs(2, 200, 200);

Bool_t CanRedo() const

     Returns kTRUE if Redo action is possible, kFALSE if it's not.
     By default, only single sequential redo action is possible.

Bool_t CanUndo() const

     Returns kTRUE if Undo action is possible, kFALSE if it's not.
     By default, only single tial undo action is possible.

void Redo(Option_t *)

     Execute command and then smerged commands

void Undo(Option_t *)

     Unexecute all merged commands and the command.
     Merged commands are executed in reverse order.

const char* GetName() const

     Returns the command name. Default name is "ClassName::RedoName(args)"
     If list of merged commands is not empty the name is
     "ClassName::RedoName(args):cname1:cname2 ..."

const char* GetTitle() const

     Returns command description.
     By default, "ClassName::RedoName(args)_ClassName::UndoName(args)"

const char* GetRedoName() const

     Returns the name of redo command

const char* GetUndoName() const

     Returns the name of undo command

Long_t* GetRedoArgs() const

     Returns a pointer to array of redo arguments

Long_t* GetUndoArgs() const

     Returns a pointer to array of undo arguments

Int_t GetNRargs() const

     Returns a number of redo arguments

Int_t GetNUargs() const

     Returns a number of undo arguments

void* GetObject() const

     Returns an object for which undo redo acions are applied

Int_t GetStatus() const

     Returns a number of sequential undo or redo operations

Bool_t IsMacro() const

     Returns kTRUE if neither redo nor undo action specified

Bool_t IsUndoing() const

     Undo action is in progress

Bool_t IsRedoing() const

     Redo action is in progress

Bool_t IsExecuting() const

     Returns kTRUE if command execution is in progress

void SetName(const char *name)

     Sets name of the command

void SetTitle(const char *title)

     Sets description of the command

void ls(Option_t *) const

     ls this command and merged commands

void Print(Option_t *option) const

     print this command and all merged commands

### Inline Functions

            TQConnection* GetRedo() const
            TQConnection* GetUndo() const
                     void Print(Option_t*, Option_t* option) const
                     void Add(TObject* obj)
                  TClass* Class()
                  TClass* IsA() const
                     void ShowMembers(TMemberInspector& insp, char* parent)
                     void Streamer(TBuffer& b)
                     void StreamerNVirtual(TBuffer& b)

Author: Valeriy Onuchin 04/27/2004
Last update: root/base:$Name: $:$Id: TQCommand.cxx,v 1.4 2005/02/11 18:40:08 rdm Exp $
Copyright (C) 1995-2001, Rene Brun and Fons Rademakers. *