Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finished initial review of [cl*-cm*] interface headers.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53086 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-04-08 05:34:11 +00:00
parent 4a36036eb2
commit d18d9f6047
10 changed files with 915 additions and 496 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
interface/cmdproc.h
View File

@@ -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();
};