execute the usual cleanup code from EVT_END_SESSION handler under MSW, otherwise...

[wxWidgets.git] / interface / cmdproc.h

diff --git a/interface/cmdproc.h b/interface/cmdproc.h
index 21b5adc151b415156abc3d95c69bb97abcb5f910..76c0577b07f3c2c82a77bebd105f39f309f13f43 100644 (file)
--- a/interface/cmdproc.h
+++ b/interface/cmdproc.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        cmdproc.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        cmdproc.h

-// Purpose:     interface of wxCommand
+// Purpose:     interface of wxCommandProcessor and wxCommand

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,15 +10,15 @@
     @class wxCommand
     @wxheader{cmdproc.h}
 
     @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}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{docview}

 
 

-    @see Overview()
+    @see @ref overview_docview_wxcommand

 */
 class wxCommand : public wxObject
 {
 */
 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.
     /**
         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);
 
     */
     wxCommand(bool canUndo = false, const wxString& name = NULL);
 


@@ -46,10 +49,13 @@ public:
     bool CanUndo();
 
     /**
     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();
 
     */
     bool Do();
 


@@ -60,21 +66,25 @@ public:
 
     /**
         Override this member function to un-execute a previous Do.
 
     /**
         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();
 };
     */
     bool Undo();
 };


@@ -85,24 +95,25 @@ public:
     @class wxCommandProcessor
     @wxheader{cmdproc.h}
 
     @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}
 
     @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.
 */
 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);
 
     */
     wxCommandProcessor(int maxCommands = -1);
 


@@ -112,20 +123,21 @@ public:
     ~wxCommandProcessor();
 
     /**
     ~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();
 
     /**
     */
     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.
     */
     */
     virtual void ClearCommands();
 
     /**
         Returns the list of commands.
     */

-    wxList GetCommands() const;
+    wxList& GetCommands() const;

 
     /**
         Returns the edit menu associated with the command processor.
 
     /**
         Returns the edit menu associated with the command processor.


@@ -133,14 +145,15 @@ public:
     wxMenu* GetEditMenu() const;
 
     /**
     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.
     */
     */
     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.
 
     /**
         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.
     */
     /**
         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.
 
     /**
         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
 
     /**
         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();
 
     /**
     */
     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();
 
     /**
     */
     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();
 
     */
     virtual bool Redo();
 


@@ -193,8 +205,8 @@ public:
     void SetEditMenu(wxMenu* menu);
 
     /**
     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();
 
     */
     void SetMenuStrings();
 


@@ -210,18 +222,20 @@ public:
 
     /**
         Submits a new command to the command processor. The command processor
 
     /**
         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);
 
     /**
     */
     virtual bool Submit(wxCommand* command, bool storeIt = true);
 
     /**

-        Undoes the command just executed.
+        Undoes the last command executed.

     */
     virtual bool Undo();
 };
     */
     virtual bool Undo();
 };