]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/cmdproc.h
Correct wxString:Append docs
[wxWidgets.git] / interface / cmdproc.h
index 89cd956dfdf9085423d9386ecc490b1636fb1948..a0bd1d0a2f0c94968ce5ede21232fbfb70c93d1b 100644 (file)
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        cmdproc.h
-// Purpose:     documentation for wxCommand class
+// Purpose:     interface of wxCommandProcessor and wxCommand
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
     @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}
 
-    @seealso
-    Overview
+    @see @ref overview_docview_wxcommand
 */
 class wxCommand : public wxObject
 {
@@ -27,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);
 
@@ -47,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.
+
+        @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.
     */
     bool Do();
 
@@ -61,49 +66,54 @@ 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.
+
+        @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.
     */
     bool Undo();
 };
 
 
+
 /**
     @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}
 
-    @seealso
-    @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);
 
@@ -113,50 +123,52 @@ 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();
+    wxList& GetCommands() const;
 
     /**
         Returns the edit menu associated with the command processor.
     */
-    wxMenu* GetEditMenu();
+    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();
+    int GetMaxCommands() const;
 
     /**
         Returns the string that will be appended to the Redo menu item.
     */
-    const wxString GetRedoAccelerator();
+    const wxString& GetRedoAccelerator() const;
 
     /**
         Returns the string that will be shown for the redo menu item.
     */
-    wxString GetRedoMenuLabel();
+    wxString GetRedoMenuLabel() const;
 
     /**
         Returns the string that will be appended to the Undo menu item.
     */
-    const wxString GetUndoAccelerator();
+    const wxString& GetUndoAccelerator() const;
 
     /**
         Returns the string that will be shown for the undo menu item.
     */
-    wxString GetUndoMenuLabel();
+    wxString GetUndoMenuLabel() const;
 
     /**
         Initializes the command processor, setting the current command to the
@@ -167,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();
 
@@ -194,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();
 
@@ -211,18 +222,21 @@ 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();
 };
+