X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..9fb99466b5b43589f477783ca65bf17714ff8615:/interface/cmdproc.h diff --git a/interface/cmdproc.h b/interface/cmdproc.h index 21b5adc151..76c0577b07 100644 --- a/interface/cmdproc.h +++ b/interface/cmdproc.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: cmdproc.h -// Purpose: interface of wxCommand +// Purpose: interface of wxCommandProcessor and wxCommand // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,15 +10,15 @@ @class wxCommand @wxheader{cmdproc.h} - wxCommand is a base class for modelling an application command, - which is an action usually performed by selecting a menu item, pressing - a toolbar button or any other means provided by the application to - change the data or view. + wxCommand is a base class for modelling an application command, which is an + action usually performed by selecting a menu item, pressing a toolbar + button or any other means provided by the application to change the data or + view. @library{wxcore} - @category{FIXME} + @category{docview} - @see Overview() + @see @ref overview_docview_wxcommand */ class wxCommand : public wxObject { @@ -26,12 +26,15 @@ public: /** Constructor. wxCommand is an abstract class, so you will need to derive a new class and call this constructor from your own constructor. - @a canUndo tells the command processor whether this command is undo-able. You - can achieve the same functionality by overriding the CanUndo member function - (if for example - the criteria for undoability is context-dependent). - @a name must be supplied for the command processor to display the command name - in the application's edit menu. + + @param canUndo + Tells the command processor whether this command is undo-able. You + can achieve the same functionality by overriding the CanUndo() + member function (if for example the criteria for undoability is + context-dependent). + @param name + Must be supplied for the command processor to display the command + name in the application's edit menu. */ wxCommand(bool canUndo = false, const wxString& name = NULL); @@ -46,10 +49,13 @@ public: bool CanUndo(); /** - Override this member function to execute the appropriate action when called. - Return @true to indicate that the action has taken place, @false otherwise. - Returning @false will indicate to the command processor that the action is - not undoable and should not be added to the command history. + Override this member function to execute the appropriate action when + called. + + @returns @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not undoable and should not be + added to the command history. */ bool Do(); @@ -60,21 +66,25 @@ public: /** Override this member function to un-execute a previous Do. - Return @true to indicate that the action has taken place, @false otherwise. - Returning @false will indicate to the command processor that the action is - not redoable and no change should be made to the command history. - How you implement this command is totally application dependent, but typical - strategies include: - Perform an inverse operation on the last modified piece of - data in the document. When redone, a copy of data stored in command - is pasted back or some operation reapplied. This relies on the fact that - you know the ordering of Undos; the user can never Undo at an arbitrary position - in the command history. - Restore the entire document state (perhaps using document transactioning). - Potentially very inefficient, but possibly easier to code if the user interface - and data are complex, and an 'inverse execute' operation is hard to write. - The docview sample uses the first method, to remove or restore segments - in the drawing. + + How you implement this command is totally application dependent, but + typical strategies include: + + - Perform an inverse operation on the last modified piece of data in + the document. When redone, a copy of data stored in command is pasted + back or some operation reapplied. This relies on the fact that you + know the ordering of Undos; the user can never Undo at an arbitrary + position in the command history. + - Restore the entire document state (perhaps using document + transactioning). Potentially very inefficient, but possibly easier to + code if the user interface and data are complex, and an "inverse + execute" operation is hard to write. The docview sample uses the + first method, to remove or restore segments in the drawing. + + @returns @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not redoable and no change should + be made to the command history. */ bool Undo(); }; @@ -85,24 +95,25 @@ public: @class wxCommandProcessor @wxheader{cmdproc.h} - wxCommandProcessor is a class that maintains a history of wxCommands, - with undo/redo functionality built-in. Derive a new class from this - if you want different behaviour. + wxCommandProcessor is a class that maintains a history of wxCommands, with + undo/redo functionality built-in. Derive a new class from this if you want + different behaviour. @library{wxcore} - @category{FIXME} + @category{docview} - @see @ref overview_wxcommandprocessoroverview "wxCommandProcessor overview", - wxCommand + @see @ref overview_docview_wxcommandproc, wxCommand */ class wxCommandProcessor : public wxObject { public: /** Constructor. - @a maxCommands may be set to a positive integer to limit the number of - commands stored to it, otherwise (and by default) the list of commands can grow - arbitrarily. + + @param maxCommands + May be set to a positive integer to limit the number of commands + stored to it, otherwise (and by default) the list of commands can + grow arbitrarily. */ wxCommandProcessor(int maxCommands = -1); @@ -112,20 +123,21 @@ public: ~wxCommandProcessor(); /** - Returns @true if the currently-active command can be undone, @false otherwise. + Returns @true if the currently-active command can be undone, @false + otherwise. */ virtual bool CanUndo(); /** - Deletes all commands in the list and sets the current command pointer to @c - @NULL. + Deletes all commands in the list and sets the current command pointer + to @NULL. */ virtual void ClearCommands(); /** Returns the list of commands. */ - wxList GetCommands() const; + wxList& GetCommands() const; /** Returns the edit menu associated with the command processor. @@ -133,14 +145,15 @@ public: wxMenu* GetEditMenu() const; /** - Returns the maximum number of commands that the command processor stores. + Returns the maximum number of commands that the command processor + stores. */ int GetMaxCommands() const; /** Returns the string that will be appended to the Redo menu item. */ - const wxString GetRedoAccelerator() const; + const wxString& GetRedoAccelerator() const; /** Returns the string that will be shown for the redo menu item. @@ -150,7 +163,7 @@ public: /** Returns the string that will be appended to the Undo menu item. */ - const wxString GetUndoAccelerator() const; + const wxString& GetUndoAccelerator() const; /** Returns the string that will be shown for the undo menu item. @@ -166,21 +179,20 @@ public: /** Returns a boolean value that indicates if changes have been made since - the last save operation. This only works if - MarkAsSaved() - is called whenever the project is saved. + the last save operation. This only works if MarkAsSaved() is called + whenever the project is saved. */ virtual bool IsDirty(); /** - You must call this method whenever the project is saved if you plan to use - IsDirty(). + You must call this method whenever the project is saved if you plan to + use IsDirty(). */ virtual void MarkAsSaved(); /** - Executes (redoes) the current command (the command that has just been undone if - any). + Executes (redoes) the current command (the command that has just been + undone if any). */ virtual bool Redo(); @@ -193,8 +205,8 @@ public: void SetEditMenu(wxMenu* menu); /** - Sets the menu labels according to the currently set menu and the current - command state. + Sets the menu labels according to the currently set menu and the + current command state. */ void SetMenuStrings(); @@ -210,18 +222,20 @@ public: /** Submits a new command to the command processor. The command processor - calls wxCommand::Do to execute the command; if it succeeds, the command - is stored in the history list, and the associated edit menu (if any) updated - appropriately. If it fails, the command is deleted - immediately. Once Submit has been called, the passed command should not - be deleted directly by the application. - @a storeIt indicates whether the successful command should be stored - in the history list. + calls wxCommand::Do() to execute the command; if it succeeds, the + command is stored in the history list, and the associated edit menu (if + any) updated appropriately. If it fails, the command is deleted + immediately. Once Submit() has been called, the passed command should + not be deleted directly by the application. + + @param storeIt + Indicates whether the successful command should be stored in the + history list. */ virtual bool Submit(wxCommand* command, bool storeIt = true); /** - Undoes the command just executed. + Undoes the last command executed. */ virtual bool Undo(); };