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