interface/cmdproc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cmdproc.h
   3 // Purpose:     interface of wxCommandProcessor and wxCommand
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCommand
  11     @wxheader{cmdproc.h}
  12
  13     wxCommand is a base class for modelling an application command, which is an
  14     action usually performed by selecting a menu item, pressing a toolbar
  15     button or any other means provided by the application to change the data or
  16     view.
  17
  18     @library{wxcore}
  19     @category{docview}
  20
  21     @see @ref overview_docview_wxcommand
  22 */
  23 class wxCommand : public wxObject
  24 {
  25 public:
  26     /**
  27         Constructor. wxCommand is an abstract class, so you will need to derive
  28         a new class and call this constructor from your own constructor.
  29
  30         @param canUndo
  31             Tells the command processor whether this command is undo-able. You
  32             can achieve the same functionality by overriding the CanUndo()
  33             member function (if for example the criteria for undoability is
  34             context-dependent).
  35         @param name
  36             Must be supplied for the command processor to display the command
  37             name in the application's edit menu.
  38     */
  39     wxCommand(bool canUndo = false, const wxString& name = NULL);
  40
  41     /**
  42         Destructor.
  43     */
  44     ~wxCommand();
  45
  46     /**
  47         Returns @true if the command can be undone, @false otherwise.
  48     */
  49     bool CanUndo();
  50
  51     /**
  52         Override this member function to execute the appropriate action when
  53         called.
  54
  55         @returns @true to indicate that the action has taken place, @false
  56                  otherwise. Returning @false will indicate to the command
  57                  processor that the action is not undoable and should not be
  58                  added to the command history.
  59     */
  60     bool Do();
  61
  62     /**
  63         Returns the command name.
  64     */
  65     wxString GetName();
  66
  67     /**
  68         Override this member function to un-execute a previous Do.
  69
  70         How you implement this command is totally application dependent, but
  71         typical strategies include:
  72
  73         - Perform an inverse operation on the last modified piece of data in
  74           the document. When redone, a copy of data stored in command is pasted
  75           back or some operation reapplied. This relies on the fact that you
  76           know the ordering of Undos; the user can never Undo at an arbitrary
  77           position in the command history.
  78         - Restore the entire document state (perhaps using document
  79           transactioning). Potentially very inefficient, but possibly easier to
  80           code if the user interface and data are complex, and an "inverse
  81           execute" operation is hard to write. The docview sample uses the
  82           first method, to remove or restore segments in the drawing.
  83
  84         @returns @true to indicate that the action has taken place, @false
  85                  otherwise. Returning @false will indicate to the command
  86                  processor that the action is not redoable and no change should
  87                  be made to the command history.
  88     */
  89     bool Undo();
  90 };
  91
  92
  93
  94 /**
  95     @class wxCommandProcessor
  96     @wxheader{cmdproc.h}
  97
  98     wxCommandProcessor is a class that maintains a history of wxCommands, with
  99     undo/redo functionality built-in. Derive a new class from this if you want
 100     different behaviour.
 101
 102     @library{wxcore}
 103     @category{docview}
 104
 105     @see @ref overview_docview_wxcommandproc, wxCommand
 106 */
 107 class wxCommandProcessor : public wxObject
 108 {
 109 public:
 110     /**
 111         Constructor.
 112
 113         @param maxCommands
 114             May be set to a positive integer to limit the number of commands
 115             stored to it, otherwise (and by default) the list of commands can
 116             grow arbitrarily.
 117     */
 118     wxCommandProcessor(int maxCommands = -1);
 119
 120     /**
 121         Destructor.
 122     */
 123     ~wxCommandProcessor();
 124
 125     /**
 126         Returns @true if the currently-active command can be undone, @false
 127         otherwise.
 128     */
 129     virtual bool CanUndo();
 130
 131     /**
 132         Deletes all commands in the list and sets the current command pointer
 133         to @NULL.
 134     */
 135     virtual void ClearCommands();
 136
 137     /**
 138         Returns the list of commands.
 139     */
 140     wxList& GetCommands() const;
 141
 142     /**
 143         Returns the edit menu associated with the command processor.
 144     */
 145     wxMenu* GetEditMenu() const;
 146
 147     /**
 148         Returns the maximum number of commands that the command processor
 149         stores.
 150     */
 151     int GetMaxCommands() const;
 152
 153     /**
 154         Returns the string that will be appended to the Redo menu item.
 155     */
 156     const wxString& GetRedoAccelerator() const;
 157
 158     /**
 159         Returns the string that will be shown for the redo menu item.
 160     */
 161     wxString GetRedoMenuLabel() const;
 162
 163     /**
 164         Returns the string that will be appended to the Undo menu item.
 165     */
 166     const wxString& GetUndoAccelerator() const;
 167
 168     /**
 169         Returns the string that will be shown for the undo menu item.
 170     */
 171     wxString GetUndoMenuLabel() const;
 172
 173     /**
 174         Initializes the command processor, setting the current command to the
 175         last in the list (if any), and updating the edit menu (if one has been
 176         specified).
 177     */
 178     virtual void Initialize();
 179
 180     /**
 181         Returns a boolean value that indicates if changes have been made since
 182         the last save operation. This only works if MarkAsSaved() is called
 183         whenever the project is saved.
 184     */
 185     virtual bool IsDirty();
 186
 187     /**
 188         You must call this method whenever the project is saved if you plan to
 189         use IsDirty().
 190     */
 191     virtual void MarkAsSaved();
 192
 193     /**
 194         Executes (redoes) the current command (the command that has just been
 195         undone if any).
 196     */
 197     virtual bool Redo();
 198
 199     /**
 200         Tells the command processor to update the Undo and Redo items on this
 201         menu as appropriate. Set this to @NULL if the menu is about to be
 202         destroyed and command operations may still be performed, or the command
 203         processor may try to access an invalid pointer.
 204     */
 205     void SetEditMenu(wxMenu* menu);
 206
 207     /**
 208         Sets the menu labels according to the currently set menu and the
 209         current command state.
 210     */
 211     void SetMenuStrings();
 212
 213     /**
 214         Sets the string that will be appended to the Redo menu item.
 215     */
 216     void SetRedoAccelerator(const wxString& accel);
 217
 218     /**
 219         Sets the string that will be appended to the Undo menu item.
 220     */
 221     void SetUndoAccelerator(const wxString& accel);
 222
 223     /**
 224         Submits a new command to the command processor. The command processor
 225         calls wxCommand::Do() to execute the command; if it succeeds, the
 226         command is stored in the history list, and the associated edit menu (if
 227         any) updated appropriately. If it fails, the command is deleted
 228         immediately. Once Submit() has been called, the passed command should
 229         not be deleted directly by the application.
 230
 231         @param storeIt
 232             Indicates whether the successful command should be stored in the
 233             history list.
 234     */
 235     virtual bool Submit(wxCommand* command, bool storeIt = true);
 236
 237     /**
 238         Undoes the last command executed.
 239     */
 240     virtual bool Undo();
 241 };
 242