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 license
   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           transactioning). 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         Deletes all commands in the list and sets the current command pointer
 131         to @NULL.
 132     */
 133     virtual void ClearCommands();
 134
 135     /**
 136         Returns the list of commands.
 137     */
 138     wxList& GetCommands();
 139
 140     /**
 141         Returns the edit menu associated with the command processor.
 142     */
 143     wxMenu* GetEditMenu() const;
 144
 145     /**
 146         Returns the maximum number of commands that the command processor
 147         stores.
 148     */
 149     int GetMaxCommands() const;
 150
 151     /**
 152         Returns the string that will be appended to the Redo menu item.
 153     */
 154     const wxString& GetRedoAccelerator() const;
 155
 156     /**
 157         Returns the string that will be shown for the redo menu item.
 158     */
 159     wxString GetRedoMenuLabel() const;
 160
 161     /**
 162         Returns the string that will be appended to the Undo menu item.
 163     */
 164     const wxString& GetUndoAccelerator() const;
 165
 166     /**
 167         Returns the string that will be shown for the undo menu item.
 168     */
 169     wxString GetUndoMenuLabel() const;
 170
 171     /**
 172         Initializes the command processor, setting the current command to the
 173         last in the list (if any), and updating the edit menu (if one has been
 174         specified).
 175     */
 176     virtual void Initialize();
 177
 178     /**
 179         Returns a boolean value that indicates if changes have been made since
 180         the last save operation. This only works if MarkAsSaved() is called
 181         whenever the project is saved.
 182     */
 183     virtual bool IsDirty() const;
 184
 185     /**
 186         You must call this method whenever the project is saved if you plan to
 187         use IsDirty().
 188     */
 189     void MarkAsSaved();
 190
 191     /**
 192         Executes (redoes) the current command (the command that has just been
 193         undone if any).
 194     */
 195     virtual bool Redo();
 196
 197     /**
 198         Tells the command processor to update the Undo and Redo items on this
 199         menu as appropriate. Set this to @NULL if the menu is about to be
 200         destroyed and command operations may still be performed, or the command
 201         processor may try to access an invalid pointer.
 202     */
 203     void SetEditMenu(wxMenu* menu);
 204
 205     /**
 206         Sets the menu labels according to the currently set menu and the
 207         current command state.
 208     */
 209     virtual void SetMenuStrings();
 210
 211     /**
 212         Sets the string that will be appended to the Redo menu item.
 213     */
 214     void SetRedoAccelerator(const wxString& accel);
 215
 216     /**
 217         Sets the string that will be appended to the Undo menu item.
 218     */
 219     void SetUndoAccelerator(const wxString& accel);
 220
 221     /**
 222         Submits a new command to the command processor.
 223
 224         The command processor calls wxCommand::Do() to execute the command;
 225         if it succeeds, the command is stored in the history list, and the
 226         associated edit menu (if any) updated appropriately.
 227         If it fails, the command is deleted immediately. Once Submit() has been
 228         called, the passed command should not be deleted directly by the application.
 229
 230         @param command
 231             The command to submit
 232         @param storeIt
 233             Indicates whether the successful command should be stored in the
 234             history list.
 235     */
 236     virtual bool Submit(wxCommand* command, bool storeIt = true);
 237
 238     /**
 239         Undoes the last command executed.
 240     */
 241     virtual bool Undo();
 242 };
 243