interface/cmdproc.h

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