]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/cmdproc.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxCommandProcessor and wxCommand
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
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
20 @see @ref overview_docview_wxcommand
22 class wxCommand
: public wxObject
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.
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
35 Must be supplied for the command processor to display the command
36 name in the application's edit menu.
38 wxCommand(bool canUndo
= false, const wxString
& name
= wxEmptyString
);
46 Returns @true if the command can be undone, @false otherwise.
48 virtual bool CanUndo() const;
51 Override this member function to execute the appropriate action when
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.
59 virtual bool Do() = 0;
62 Returns the command name.
64 virtual wxString
GetName() const;
67 Override this member function to un-execute a previous Do.
69 How you implement this command is totally application dependent, but
70 typical strategies include:
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.
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.
88 virtual bool Undo() = 0;
94 @class wxCommandProcessor
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
103 @see @ref overview_docview_wxcommandproc, wxCommand
105 class wxCommandProcessor
: public wxObject
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
116 wxCommandProcessor(int maxCommands
= -1);
121 virtual ~wxCommandProcessor();
124 Returns @true if the currently-active command can be undone, @false
127 virtual bool CanUndo() const;
130 Deletes all commands in the list and sets the current command pointer
133 virtual void ClearCommands();
136 Returns the list of commands.
138 wxList
& GetCommands();
141 Returns the edit menu associated with the command processor.
143 wxMenu
* GetEditMenu() const;
146 Returns the maximum number of commands that the command processor
149 int GetMaxCommands() const;
152 Returns the string that will be appended to the Redo menu item.
154 const wxString
& GetRedoAccelerator() const;
157 Returns the string that will be shown for the redo menu item.
159 wxString
GetRedoMenuLabel() const;
162 Returns the string that will be appended to the Undo menu item.
164 const wxString
& GetUndoAccelerator() const;
167 Returns the string that will be shown for the undo menu item.
169 wxString
GetUndoMenuLabel() const;
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
176 virtual void Initialize();
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.
183 virtual bool IsDirty() const;
186 You must call this method whenever the project is saved if you plan to
192 Executes (redoes) the current command (the command that has just been
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.
203 void SetEditMenu(wxMenu
* menu
);
206 Sets the menu labels according to the currently set menu and the
207 current command state.
209 virtual void SetMenuStrings();
212 Sets the string that will be appended to the Redo menu item.
214 void SetRedoAccelerator(const wxString
& accel
);
217 Sets the string that will be appended to the Undo menu item.
219 void SetUndoAccelerator(const wxString
& accel
);
222 Submits a new command to the command processor.
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.
231 The command to submit
233 Indicates whether the successful command should be stored in the
236 virtual bool Submit(wxCommand
* command
, bool storeIt
= true);
239 Undoes the last command executed.