pbsw-Undo

A REALbasic framework for assisting with the implementation of multiple undo/redo.

Requirements:

REALbasic 5.5.5

Usage Notes:

Initialization

Create a pbsw_UndoCenter at the appropriate level (application, window, whatever makes sense for your situation)
Classes that need their state changes undone must implement the interface: pbsw_CopyableObject

Preparation for undo

Prior to performing an action on one or more objects that will need to be undone:
1. Create a pbsw_UndoAction object
2. For each of your objects whose state changes will need to be undone, create a pbsw_UndoObject passing it your object
3. Add each pbsw_UndoObject from #2 to the pbsw_UndoAction from #1
4. Add the pbsw_UndoAction from #1 to the appropriate pbsw_UndoCenter

Updating the Undo/Redo menu

In the EnableMenuItems event of the appropriate object, check to see if there is anything that can be undone, by calling your pbsw_UndoCenter's UndoStackCount and RedoStackCount methods and enable the Undo/Redo menus as appropriate based on the results.
Use your pbsw_UndoCenter's GetUndoMenuText and GetRedoMenuText methods and append the results to "Undo " and "Redo " for the appropriate menu text

Undo

Call your pbsw_UndoCenter's Undo method which will return a pbsw_UndoAction (or nil will be returned, if there is nothing to undo)
If you received a pbsw_UndoAction from #1 above, loop through each of the pbsw_UndoObjects contained within, using the CountObjects and GetObject methods.
Perform the actions appropriate for your application, using the information from each pbsw_UndoObject from #2 above:

Use pbsw_UndoObject.GetType to get the type of action that was performed on the object, needing undoing
Use pbsw_UndoObject.GetObject to get a copy of the object before it was changed or deleted
Use pbsw_UndoObject.GetReference to get a reference to the existing (changed) object, in the case of a change

Redo

Call your pbsw_UndoCenter's Redo method which will return a pbsw_UndoAction (or nil will be returned, if there is nothing to redo)
If you received a pbsw_UndoAction from #1 above, loop through each of the pbsw_UndoObjects contained within, using the CountObjects and GetObject methods.
Perform the actions appropriate for your application, using the information from each pbsw_UndoObject from #2 above:

Use pbsw_UndoObject.GetType to get the type of action that was performed on the object, needing redoing
Use pbsw_UndoObject.GetObject to get a copy of the object after it was changed or created
Use pbsw_UndoObject.GetReference to get a reference to the existing (changed) object, in the case of a change, or object creation

Classes
Interfaces
Modules

Class: pbsw_UndoCenter

Superclass: None

Interfaces: None

An instance of this class will hold all the multiple undo / redo information.
The Undo Center maintains stacks of undoable and redoable actions and keeps track of which ones are next to be undone / redone.

Methods

AddAction(theAction as pbsw_UndoAction) [Public]
	adds theAction as a new undoable action if the UndoCenter is already holding the maximum levels of undo that it can, the oldest one will be bumped

AddToLastUndoableAction(theObjectActionType as integer, theObject as pbsw_CopyableObject) [Public]
	adds another object (theObject) to the last added action theObjectActionType is the type of action the object needs undone (see the constants for pbsw_UndoObject for the description of supported types)

Constructor(theMaxUndo as integer) [Public]
	creates a new undo center with the maximum number of undos/redos equal to "theMaxUndo"

GetRedoMenuText() as string [Public]
	returns the text for the "Redo" menu for the next action to be redone

GetUndoMenuText() as string [Public]
	returns the text for the "Undo" menu for the next action to be undone

NewUndoableAction(theObjectActionType as integer, theObject as pbsw_CopyableObject, theMenuText as string, undoReversed as boolean = false, redoReversed as boolean = false) [Public]

(This is a convenience function that performs the creation of the pbsw_UndoObject and pbsw_UndoAction for a single object and action all in one fell swoop.)

creates a new undoable action
theObjectActionType is the type of action the object needs undone
(see the constants for pbsw_UndoObject for the description of supported types)
theObject is the object needing undo information stored
theMenuText is the text that will be added to the "Undo" and "Redo" menus to describe the action
set undoReversed to true if the objects should be undone in reverse order
set redoReversed to true if the objects should be redone in reverse order
NOTE: undoReversed and redoReversed are flags for your own informational purposes - internal operation is not changed with the setting of these flags

Redo() as pbsw_UndoAction [Public]
	returns the next action to be redone, and adjusts the undo / redo stack appropriately for the next actions

RedoStackCount() as integer [Public]
	returns the number of actions in the redo stack

SetMaxUndo(theMaxUndo as integer) [Public]
	sets the maximum number of steps that can be undone/redone

Undo() as pbsw_UndoAction [Public]
	'] returns the next action to be undone, and adjusts the undo / redo stack appropriately for the next actions

UndoStackCount() as integer [Public]
	returns the number of actions in the undo stack

Class: pbsw_UndoObject

Superclass: None

Interfaces: None

A container object for an object that needs its state to be saved for undoing.

Each pbsw_UndoObject instance will hold one saved state of an undoable object (one that implements the pbsw_CopyableObject interface)

(NOTE: negative values of the class constants are reserved for future use)

Constants
Name	Type	Value	Scope	Description
Change	Integer	-2	Public	the object has changed
ChangeAndForget	Integer	-4	Public	the object has changed, but we don't care about it (??)
Create	Integer	-1	Public	the object was created
Delete	Integer	-3	Public	the object was deleted

Methods

Constructor(theType as integer, theObject as pbsw_CopyableObject) [Public]
	creates a new container for theObject to have its state stored for undoing theType is the type of action that is going to be performed on the object that needs to be undone (see the constants for pbsw_UndoObject for the description of supported types)

GetObject() as pbsw_CopyableObject [Public]
	return the stored version of the object (a copy of the object before it was changed)

GetReference() as pbsw_CopyableObject [Public]
	return the reference to the existing object (if it exists) that has changed

GetType() as integer [Public]
	return the type of action that was performed on this object that will be undone/redone (see the constants for pbsw_UndoObject for the description of supported types)

Class: pbsw_UndoAction

Superclass: None

Interfaces: None

An object encapsulating a single undoable/redoable "action" which involves one or more objects

Methods

AddObject(theObject as pbsw_UndoObject) [Public]
	Add theObject to the action

Constructor(theMenuText as string, undoReversed as boolean = false, redoReversed as boolean = false) [Public]

Creates a new undoable/redoable action
theMenuText is the text that will be added to the "Undo" and "Redo" menus to describe the action
set undoReversed to true if the objects should be undone in reverse order
set redoReversed to true if the objects should be redone in reverse order
NOTE: undoReversed and redoReversed are flags for your own informational purposes - internal operation is not changed with the setting of these flags

CountObjects() as integer [Public]
	returns the number of objects affected by this action

GetMenuText() as string [Public]
	returns the menu text that should be added to the "Undo" and "Redo" menus as appropriate

GetObject(index as integer) as pbsw_UndoObject [Public]
	return the object indicated by the 1-based index

IsRedoReversed() as boolean [Public]
	returns true if the objects should be redone in reverse order NOTE: reversed setting is for your own informational purposes - internal operation is not changed based on this value

IsUndoReversed() as boolean [Public]
	returns true if the objects should be undone in reverse order NOTE: reversed setting is for your own informational purposes - internal operation is not changed based on this value

Interface: pbsw_CopyableObject

This interface is required for any classes that will be able to undo / redo their state
Requires 2 methods: Copy and CopyFrom

Methods

Copy() as Object [Public]
	Your objects that implement this interface must return a new copy of the object (most appropriately using CopyFrom to do the copy)

CopyFrom(theObject as Object) [Public]
	Your objects that implement this interface should copy all properties from the passed object.

Module: pbsw_DictionaryCopyable

A convenience module that extends the built in Dictionary class with the ability to copy itself, similar to the pbsw_CopyableObject interface.
Note: A dictionary copied this way will only copy the references to the contained objects, it will not make copies of them.

Methods

Copy(extends theDictionary as Dictionary) as Object [Global]
	Returns a copy of the dictionary

CopyFrom(extends theDictionary as Dictionary, theObject as Object) [Global]
	Copies the dictionary from theObject (which must be a dictionary)

Module: pbsw_O2D_Copyable

A convenience module that extends the built in Object2D class(es) with the ability to copy their basic properties, similar to the pbsw_CopyableObject interface.

Methods

Copy(extends theShape as Object2D) as Object [Global]
	returns a copy of the Object2D

CopyFrom(extends theShape as Object2D, theObject as Object) [Global]
	copies the Object2D from theObject (which must be an Object2D)

pbsw-code.net : pbsw-Undo

This page created by RB-ADoc by Park Bench Software