Class ChangedEvent
A ChangedEvent represents a change to an object, typically a GraphObject, but also for model data, a Model<TNodeData, TNodeKey, TSharedData>, or a Diagram. The most common case is for remembering the name of a property and the before-and-after values for that property.
Namespace: Northwoods.Go.Models
Assembly: Northwoods.GoDiagram.WinForms.dll
Syntax
public class ChangedEventRemarks
You can listen for changed events on the model using Changed or ModelChanged, and on the Diagram using Changed.
There are four kinds of changes, represented by enumerated values: Property (the most common), Insert and Remove (to represent inserting or removing objects from collections), and Transaction (to notify about beginning or ending transactions or undo or redo).
The most common kind of ChangedEvent is a Property change. The name of the property is given by PropertyName. The modified object is given by Object. Use the OldValue and NewValue properties for the before and after property values.
For an Insert ChangedEvent, the modified collection (often an Array) is a property value on the Object. The PropertyName helps distinguish between different collections on the object. Use the NewValue property to indicate the value that was inserted. Use the NewParam property to indicate where or how, such as an array index or dictionary key.
For a Remove ChangedEvent, the modified collection is a property value on the Object. The PropertyName helps distinguish between different collections on the object. Use the OldValue property to indicate the value that was removed. Use the OldParam property to indicate where or how, such as an array index or dictionary key.
Transaction ChangedEvents are generated by the UndoManager. The PropertyName names the nature of the ChangeType. For the very first transaction, the property name is "StartingFirstTransaction". This ChangedEvent precedes a ChangedEvent whose property name is "StartedTransaction", which occurs for every top-level transaction.
When ending a transaction, there is first a ChangedEvent whose name is "ComittingTransaction". This is followed by one with either "CommittedTransaction" or "RolledBackTransaction", depending on how the transaction is ending. The OldValue provides the transaction name and the Object is the Transaction being finished. (Note that the Transaction value may be null if no Transaction is available at that time, perhaps because there were no changes made during the transaction.) That Transaction can be scanned to look for ChangedEvents that you may wish to record in a database, all within a single database transaction.
There are also Transaction ChangedEvents corresponding to "StartingUndo", "FinishedUndo", "StartingRedo", and "FinishedRedo". The Object property provides the Transaction that is about-to-be or just-was undone or redone.
Non-Transaction ChangedEvents are remembered by the UndoManager, if IsEnabled, and held in the History as Transactions which hold lists of ChangedEvents. That is why ChangedEvent implements Undo() and Redo() of the change that it remembers.
When the ChangedEvent represents a change to a Model<TNodeData, TNodeKey, TSharedData>, the value of Model is non-null and the value of Diagram is meaningless. If the change is a structural change to the model, the value of ModelChange indicates the kind of change, a ModelChangeType value.
The value of PropertyName indicates the actual name of the property that was modified. ModelChange is not None only when there is a known structural change to the model, not just the setting of some property on some object.
When the ChangedEvent represents a change to a Diagram or a GraphObject within a diagram, the value of Diagram is non-null and the values of Model and ModelChange are meaningless.
Please note that ChangedEvents can be raised for many different causes. You may not be interested in changes to temporary objects -- in that case ignore the ChangedEvent when SkipsUndoManager or SkipsUndoManager is true.
Constructors
ChangedEvent()
The ChangedEvent class constructor produces an empty ChangedEvent object.
Declaration
public ChangedEvent()Properties
Change
Gets or sets the nature of change that occurred.
Declaration
public ChangeType Change { get; set; }Property Value
| Type | Description |
|---|---|
| ChangeType |
Remarks
The default is Property. Other values are Insert, Remove, and Transaction.
Diagram
Gets or sets the Diagram that was modified.
Declaration
public Diagram Diagram { get; set; }Property Value
| Type | Description |
|---|---|
| Diagram |
Remarks
When this property is non-null, the Model property will be null. However this property and the Model property may both be null simultaneously, when no particular model or diagram applies.
IsTransactionFinished
This read-only property is true when this ChangedEvent is of type Transaction and represents the end of a transactional change.
Declaration
public bool IsTransactionFinished { get; }Property Value
| Type | Description |
|---|---|
| bool |
Remarks
It is implemented as:
return (Change == ChangeType.Transaction && (PropertyName == "CommittedTransaction" || PropertyName == "FinishedUndo" || PropertyName == "FinishedRedo"));Model
Gets or sets the IModel that was modified.
Declaration
public IModel Model { get; set; }Property Value
| Type | Description |
|---|---|
| IModel |
Remarks
When this property is non-null, the Diagram property will be null. However this property and the Diagram property may both be null simultaneously, when no particular model or diagram applies.
ModelChange
Gets or sets the type of the model change, reflecting a change to model data in addition to a change to the model itself.
Declaration
public ModelChangeType ModelChange { get; set; }Property Value
| Type | Description |
|---|---|
| ModelChangeType |
Remarks
The default is None, which indicates that this is just a regular change to some object's state, probably its property.
NewParam
Gets or sets an optional value associated with the new value.
Declaration
public object NewParam { get; set; }Property Value
| Type | Description |
|---|---|
| object |
Remarks
Most properties do not require any parameter to describe the change. This is typically a value that helps distinguish the new value, such as an index into an array. It is null if it is not used. The default is null.
NewValue
Gets or sets the next or current value that the property has.
Declaration
public object NewValue { get; set; }Property Value
| Type | Description |
|---|---|
| object |
Remarks
The default is null.
Object
Gets or sets the object that was modified.
Declaration
public object Object { get; set; }Property Value
| Type | Description |
|---|---|
| object |
Remarks
The default is null.
For Transaction changes, this may be the Transaction.
OldParam
Gets or sets an optional value associated with the old value.
Declaration
public object OldParam { get; set; }Property Value
| Type | Description |
|---|---|
| object |
Remarks
Most properties do not require any parameter to describe the change. This is typically a value that helps distinguish the old value, such as an index into an array. It is null if it is not used. The default is null.
OldValue
Gets or sets the previous or old value that the property had.
Declaration
public object OldValue { get; set; }Property Value
| Type | Description |
|---|---|
| object |
Remarks
The default is null.
PropertyName
Gets or sets the name of the property change.
Declaration
public string PropertyName { get; set; }Property Value
| Type | Description |
|---|---|
| string |
Remarks
The default is an empty string, which is not a valid property name. This property can be useful even when the type of change is not Property, because it can help identify the collection in the Object that was modified (for Insert or Remove) or the stage of the current transaction (for Transaction).
Methods
CanRedo()
This predicate returns true if you can call Redo().
Declaration
public bool CanRedo()Returns
| Type | Description |
|---|---|
| bool | True if ready for Redo() to be called. |
CanUndo()
This predicate returns true if you can call Undo().
Declaration
public bool CanUndo()Returns
| Type | Description |
|---|---|
| bool | True if ready for Undo() to be called. |
Clear()
Forget any object references that this ChangedEvent may have.
Declaration
public void Clear()Copy()
Make a copy of this ChangedEvent.
Declaration
public ChangedEvent Copy()Returns
| Type | Description |
|---|---|
| ChangedEvent |
Remarks
ChangedEvents are copied when the UndoManager adds to a Transaction.
GetParam(bool)
This is a convenient method to get the right parameter value, depending on the value of undo, when implementing a state change as part of an undo or a redo.
Declaration
public object GetParam(bool undo)Parameters
| Type | Name | Description |
|---|---|---|
| bool | undo | If true, returns the OldParam, otherwise returns the NewParam. |
Returns
| Type | Description |
|---|---|
| object | Either the OldParam or the NewParam. |
GetValue(bool)
This is a convenient method to get the right value, depending on the value of undo, when implementing a state change as part of an undo or a redo.
Declaration
public object GetValue(bool undo)Parameters
| Type | Name | Description |
|---|---|---|
| bool | undo | If true, returns the OldValue, otherwise returns the NewValue. |
Returns
| Type | Description |
|---|---|
| object | Either the OldValue or the NewValue. |
Redo()
Re-perform this object change after an Undo().
Declaration
public void Redo()Remarks
CanRedo() must be true for this method to have any effect.
Undo()
Reverse the effects of this object change.
Declaration
public void Undo()Remarks
CanUndo() must be true for this method to have any effect.