DpChangeTracker 1.1.1

DpChangeTracker

Overview

DpChangeTracker is a class which allows tracking of changes within a Windows Form when its controls are bound to a data object.

It does this by saving a string representation of the value of a control at the time it is bound, attaching a change event to the control and, on every change, comparing the new value against the old. One advantage of this methodology is that, should a user change a control's value and subsequently change it back to its original value, that change is cancelled and not considered dirty.

Its simplest output is by means of an IsDirty property (true if one or more of the tracked controls has changed). However, it can also produce a list of dirty controls or the number of dirty controls at any point. Two other facilities provided are the ability to reset all controls on the form to their original 'clean' values (cancel all inputs) or to register the current status of controls as 'clean' (eg following a Save).

A downside of this arrangement is that it is restricted to a limited set of the most commonly-used controls. Further controls can be added relatively easily however.

One of the excluded controls is the RadioButton, due to WinForms quirks. However, a custom RadioGroup Box control is available which returns an integer value, reflecting the value (placed by the developer) in the Tag property of the selected RadioButton.

Controls That Can Be Tracked

TextBox, MaskedTextBox, RichTextBox, ComboBox, ListBox, CheckedListBox,
CheckBox, DpRadioGroupBox, ListView

Note that the implementation of ListView is somewhat simplistic.

Control Information Class - TrackedControlInfo

DpChangeTracker maintains a dictionary containing an entry for each control tracked. The parent form can request a list of this data (GetAllControls()), the subset of controls that have changed (GetChangedControls()) or the individual control that has changed (ValueChanged event). The structure of this class TrackedControlInfo is:

`Control ControlRef` - A reference to the control being tracked

`string Name` - The name of the control

`CtrlTypes Type` - An enumeration (`CtrlTypes`) of the control type (for greater efficiency)

`string CleanValue` - A string representation of the 'clean' value of the control

`string CurrentValue` - A corresponding string representation of the control's current value

The CtrlTypes enumeration is simply the names of the control types that can be tracked:

	public enum CtrlTypes {
		NotSupported, ToBeIgnored,
		TextBox, MaskedTextBox, RichTextBox, ComboBox, ListBox, CheckedListBox,
		CheckBox, RadioGroupBox, ListView
	}

Package & Namespace

The package name is DpChangeTracker

The namespace name is DpWinForms

The package is dependent on packages DpRadioGroupBox and DpUtilities

Using the Class

1. Define a Form-level variable to hold the tracker's reference: private DpChangeTracker Tracker;

2. In the form Load event, instantiate an instance of the class, eg:

   Tracker = new (this, Binder, new string [] { nameof (InfoBox) });

   where Binder is the BindingSource (if any) and "InfoBox" is the name of a control that is to be excluded from tracking (if any).

3. Optionally, immediately following this, subscribe to the tracker's ValueChanged event:

   Tracker.ValueChanged += MyValueChangedHandler;

Constructor

public DpChangeTracker (Form form, BindingSource bindSrc = null, string [] toIgnore = null)

Form form: A reference to the host form being tracked.

BindingSource bindSrc: A reference to the binding source for the tracked controls, if any.

string [] toIgnore: An array of the names of any controls on the form that are not to be tracked. Controls of types which are not included in form tracking will be ignored anyway and need not be listed.

Property

IsDirty

public bool IsDirty { get; }

Returns true if any of the tracked controls has a different value from its original (or since either `CancelAndRestore()' or 'ResetAsClean()' were last called - seew below).

Methods

CancelAndRestore

public void CancelAndRestore ()

Restores the value of each tracked control to its 'clean' value. Sets the IsDirty property to false. This would typically be called when the user wished to cancel all changes or when the user exits a form without saving.

ResetAsClean

public void ResetAsClean ()

Copies the current values of all tracked controls into the 'clean' value and sets the IsDirty property to false. Typically called following a 'Save' operation.

GetAllControls

public List<TrackedControlInfo> GetAllControls ()

Returns a list of all controls being tracked by the class, together with a string representation of their current and 'clean' values.

The following methods all perform the same basic task. They scan all tracked controls to compare current and 'clean' values, setting the IsDirty property as appropriate. They differ fundamentally only in whether or not a list of changed controls is compiled and returned.

RecheckAll

public bool RecheckAll ()

Returns: true if the form is 'dirty', ie at least one control has changed value.

Re-checks the current values of all controls being tracked against their 'clean' value. Resets the value of IsDirty and returns it.

GetChangedControls

public int GetChangedControls (out List<TrackedControlInfo> list)

Returns: The number of controls that have changed. Outputs a list of the controls that have changed, including their current and 'clean' values.

GetChangedControls

public List<TrackedControlInfo> GetChangedControls ()

Returns: A list of the controls that have changed, including their current and 'clean' values.

GetNumberChanged

public int GetNumberChanged ()

Returns the number of controls of which the value has changed.

Events

ValueChanged

public event EventHandler<TrackingEventArgs> ValueChanged;

The parent form may subscribe to the ValueChanged event, which fires every time one of the tracked controls fires.

To handle the event, the calling program should call Tracker.ValueChanged += MyValueChangedHandler; immediately after constructing an instance of the tracker. It should then implement the handler as

private void MyValueChangedHandler (object sender, TrackingEventArgs e) {}.

The single member of TrackingEventArgs is TrackedControlInfo Info, representing the information for the changed control, including (new) current and 'clean' values.