interface/cmdproc.h

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