interface/wx/cmdproc.h

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