]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/cmdproc.h
Removed private wxGetLocalTimeUsec() function from Unix code.
[wxWidgets.git] / 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 licence
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 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.
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