Displaying Broken Rules and Warnings in Windows Forms

There are two ways you can display your broken rules and warnings in a Windows Forms application, controlled by two form-level properties: DisplayErrorProvider and DisplayErrorDialog.

Displaying Broken Rules and Warnings with the .NET Error Provider

The default method for displaying broken rules and warnings is by means of the .NET Windows Forms Error Provider. When using the Error Provider, if the user encounters broken rules when saving data at run time, they will first see the following dialog:

When the user clicks OK, the Error Provider displays a warning icon next to each user interface control associated with a broken rule:

If the user corrects the problem and saves the data, the warning icons automatically disappear. They also disappear if the user cancels pending changes. If the user encounters a warning when saving data at run time, they will first see the following dialog:

When the user clicks OK, the Error Provider again displays a warning icon next to the user interface:

If you want to turn off the display of error provider icons, set the form's DisplayErrorProvider property to false (it's true by default).

Displaying Broken Rules in a Simple Dialog

You can display broken rules in a simple dialog instead of or in addition to displaying error icons by setting the form's DisplayErrorDialog property to true (it's false by default).

This dialog tells the user that data could not be saved because they must specify a ship name. If only warnings are encountered when saving data, these are displayed similarly (without the message that data could not be saved). If both broken rules and warnings are encountered when saving data, the dialog looks like this:

If you want to display broken rules and warnings this way, then set the form's DisplayErrorDialog property to true. If you want this as the default behavior of all your forms, then create a subclass of mmBusinessForm and/or mmMaintenanceForm and set the property to true.

Displaying Broken Rules When Leaving a User Interface Control

If you prefer to display broken rules as soon as a user tries to leave a particular user interface control, the businiess rule methods are designed in such a way that they can be called directly from the user interface.

For example, in C#:

private void txtCustID_Validating(object sender, CancelEventArgs e)
{
	this.oOrder.Rules.ClearAll();
	if (this.oOrder.Rules.ValidateCustomerID(this.txtCustID.Text) != null)
	{
		mmAppDesktop.MessageBox.Show(this.oOrder.Rules.GetAllBrokenRules(), "Data Entry Error", MessageBoxButtons.OK, MessageBoxIcon.Warning);
		e.Cancel = true;
	}
}

And in VB .NET:

Private Sub txtCustID_Validating(ByVal sender As System.Object, ByVal e As System.ComponentModel.CancelEventArgs) Handles txtCustID.Validating

    Me.oOrder.Rules.ClearAll()
    If Me.oOrder.Rules.ValidateCustomerID(Me.txtCustID.Text) <> Nothing Then
        mmAppDesktop.MessageBox.Show(Me.oOrder.Rules.GetAllBrokenRules(), "Data Entry Error", MessageBoxButtons.OK, MessageBoxIcon.Warning)
        e.Cancel = True
    End If

End Sub

Changing How Broken Rules and Warnings are Displayed

Whether you are displaying broken rules and warnings in a simple dialog or you are using the .NET Error Provider, you can easily change the way these error messages are displayed to the user.

Broken Rules and Warnings in a Simple Dialog

If you are using a simple dialog to display your broken rules and warnings, you can change how they are displayed by overriding the DisplayBrokenRules method in your form.

This method receives the business rule object as a parameter. You can create your own custom broken rules form (or subclass and change the existing mmBrokenRulesForm class) then instantiate and call it from the DisplayBrokenRuleDialog method.

For example, in C#:

protected virtual void DisplayBrokenRuleDialog (mmBusinessRule bizRule)
{
	MyBrokenRulesForm form = new MyBrokenRulesForm(bizRule);
	form.Show();
}

And in VB .NET:

Protected Overridable  Sub DisplayBrokenRuleDialog (ByVal bizRule As mmBusinessRule)
	Dim form As MyBrokenRulesForm =  New MyBrokenRulesForm(bizRule) 
	form.Show()
End Sub

Broken Rules and Warnings with the Error Provider

If you are displaying broken rules and warnings with the .NET Error Provider, you can change the initial message dialog display by overriding your form's DisplayErrorProviderBrokenRuleDialog and DisplayErrorProviderWarningsDialog methods.

For example, in C#:

protected override void DisplayErrorProviderBrokenRuleDialog()
{
	MessageBox.Show("My alternate broken rule message", "My alternate title");
}

protected override void DisplayErrorProviderWarningsDialog()
{
	MessageBox.Show("My alternate warnings message", "My alternate title");
}

And in VB .NET:

Protected Overrides Sub DisplayErrorProviderBrokenRuleDialog()
   MessageBox.Show("My alternate broken rule message", "My alternate title")
End Sub

Protected Overrides Sub DisplayErrorProviderWarningsDialog()
   MessageBox.Show("My alternate warnings message", "My alternate title")
End Sub

Changing the BlinkStyle and BlinkRate of Error Provider Icons

You can easily change the BlinkStyle and/or BlinkRate properties of Error Provider icons by overriding the factory method that creates ErrorProvider objects. To do this, just go to your Factory.cs or Factory.vb file, override the CreateErrorProvider() method and set the properties before returning the new ErrorProvider object.

For example, in C#:

public override ErrorProvider CreateErrorProvider()
{
	ErrorProvider EP = base.CreateErrorProvider();
	EP.BlinkStyle = ErrorBlinkStyle.NeverBlink;
	return EP;
}

And in VB .NET:

Public Overrides Function CreateErrorProvider() As ErrorProvider
   Dim EP As ErrorProvider = MyBase.CreateErrorProvider()
   EP.BlinkStyle = ErrorBlinkStyle.NeverBlink
   Return EP
End Function

Displaying Broken Rules by Changing the Color of UI Controls

This section demonstrates the extensibility of the mechanism for displaying broken rules in MM .NET. You can change the color of user interface controls that have associated broken rules by subclassing MM .NET UI controls. For example, the following subclass of mmTextBox plugs into the business object's BrokenRuleWarnings state change event and changes the background color of the text box to red. When you tab out of the control, the ValidatingHandler method resets the background color of the text box.

using System;
using System.Drawing;

using OakLeaf.MM.Main.Windows.Forms;
using OakLeaf.MM.Main.Business;
using OakLeaf.MM.Main;

namespace OakLeaf.MM.Main.Windows.Forms
{
	/// <summary>
	/// Summary description for sdTextBox.
	/// </summary>
	public class sdTextBox : mmTextBox
	{
		public sdTextBox()
		{
			this.Validating += new System.ComponentModel.CancelEventHandler(this.ValidatingHandler);
		}

		public override void StateChangeHandler(OakLeaf.MM.Main.Business.mmBaseBusinessObject bizObj, OakLeaf.MM.Main.Business.mmBusinessStateChangeEventArgs e)
		{
			if (e.State == mmBusinessState.BrokenRulesWarnings)
			{
				if (e.PrimaryKeyValue is mmErrorProviderArgs)
				{
					mmErrorProviderArgs epArgs = (mmErrorProviderArgs)e.PrimaryKeyValue;
					// See if the broken rule applies to this control
					if (epArgs.ColumnName.ToLower() == this.BindingSourceMember.ToLower())
					{
						this.BackColor = Color.Red;
					}
				}
			}
			else
			{
				base.StateChangeHandler(bizObj, e);
			}
		}

		private void ValidatingHandler(object sender, System.ComponentModel.CancelEventArgs e)
		{
			this.BackColor = SystemColors.Window;
		}
	}
}

Under the Hood: Displaying Broken Rules and Warnings

The following UML sequence diagram demonstrates how the user interface interacts with the business object and business rule object to display simple text business rules:

There are really five main things that happen in this sequence:

1. The form's Save method calls the business object's SaveDataSet method.

2. The business object calls the rule object's CheckRules method, and passes the value back to the form (if any rules are broken, the business object doesn't save the data, otherwise the data gets saved).

3. The form checks the value returned from SaveDataSet. If it's anything other than mmSaveDataResult.RulesPassed, the form calls its DisplayBrokenRules method, passing a reference to the business rule object.

4. The DisplayBrokenRules method of the form instantiates an instance of the mmBrokenRulesForm, passing a reference to the business rule object.

5. The mmBrokenRulesForm calls the rule object's GetAllBrokenRules and GetAllWarnings methods, then displays them to the user.

See also:
Understanding Business Rule Objects | Using the MM .NET Business Layer Generator