Working with the mmMoverControl

The mmMoverControl provides standard mover box functionality for your WPF applications. This control is used in MM .NET's mmUsersWindow as shown here:

To implement an instance of mmMoverControl in your application, read the information outlined below. The mover control on the Users window is used as an example throughout these steps to give you ideas on how to implement the control in your applications.

Adding a Mover Control to a Window

To add an instance of mmMoverControl to a window, simply drag an mmMoverControl from the Visual Studio Toolbox and drop it on your window:

Setting the Binding Properties

There are two main sets of properties on the mover control. One set pertains to the "Available" list:

• AvailableLabelText
  
• AvailableListDisplayMemberPath
  
• AvailableListSelectedValuePath

And the other pertains to the "Selected" list.

• SelectedLabelText
  
• SelectedListDisplayMemberPath
  
• SelectedListBindingValuePath
  

The AvailableLabelText and SelectedLabelText properties specify the text for the Available list and the Selected list labels. All other properties are binding properties for list controls.

In mmUsersWindow, entities retreived from a Role business object are used to fill both the Available and Selected lists. The mmMoverControl properties are set to the following values:

• AvailableListDisplayMemberPath = Description
  
• AvailableListSelectedValuePath = RolePK

• SelectedListDisplayMemberPath = Description
  
• SelectedListBindingValuePath = RolePK

Specifying a Parent Business Object

You can specify a parent business object for the mover control. Whenever this parent business object does something "interesting", the mover control can respond accordingly. For example, in the Framework's Users Window, the User business object is specified as the parent business object. So whenever the user business object navigates to a different user, the mover control responds by displaying roles for the current user.

To specify a parent business object, select the mover control in design mode, then go to the Properties Window and select the ParentBusinessObject property. Specify the class name of the parent buiiness object.

Plugging into Mover Control Events

mmMoverControl has a few events you can plug into that allow you to execute custom code when important events occur in the control.

• RefreshLists
  
• AddItem
  
• DeleteItem
  
• Delete
  
• ParentStateChange
  

The RefreshLists Event

The RefreshLists event is automatically raised when:

1. The Added, Bind, Canceled, Navigated, and Retrieved events are raised on its parent business object

2. After the Save event of the mover control is fired

Here is the code in the event handler of the Roles mover control in the Users window:

private void mvrRoles_RefreshLists(mmBaseBusinessObject bizObj, mmBusinessStateChangeEventArgs e)
{
	if (this.grdUsers.SelectedItem != null)
	{
		UserEntity user = (UserEntity)this.grdUsers.SelectedItem;
		this.mvrRoles.AvailableList = this.Role.GetUserNonMemberRoles(user.UserPK);
		this.mvrRoles.SelectedList = this.Role.GetUserRoles(user.UserPK);
	}
}

The call to GetUserNonMemberRoles retrieves all roles the user does NOT belong to and are stored in the AvailableList collection. Behind the scenes, this list gets bound to the Available list box. The call to GetUserRoles retrieves all roles to which the user belongs and are stored in the mover control's SelectedList collection. Behind the scenes, this list gets bound to the Selected list box.

The AddItem Event

The AddItem event is raised from within the mover control's OnSave() method once for each item that has been newly added to the Selected list. Here is the code in the event handler of the Roles mover control in the Users window:

private void mvrRoles_AddItem(object sender, mmMoverEventArgs e)
{
	this.Role.AddUserToRole((int)e.ParentPrimaryKeyValue, (int)e.PrimaryKeyValue);
}

The DeleteItem Event

The DeleteItem event is raised from within the mover control's OnSave() method once for each item that has been removed from the Selected list. Here is the code in the event handler of the Roles mover control in the Users window:

private void mvrRoles_DeleteItem(object sender, mmMoverEventArgs e)
{
	this.Role.RemoveUserFromRole((int)e.ParentPrimaryKeyValue, (int)e.PrimaryKeyValue);
}

The Delete Event

The Delete event is automatically raised when the mover control's parent business object raises a Deleted event (indicating a parent business object entity has been deleted)

Here is the code in the event handler of the Roles mover control in the Users window:

protected virtual void mvrRoles_Delete(OakLeaf.MM.Main.Business.mmBusinessObject bizObj, OakLeaf.MM.Main.Business.mmBusinessStateChangeEventArgs e)
{
	this.Role.DeleteUserRoles(e.PrimaryKeyValue);
}

The call to DeleteUserRoles deletes all roles for the user record being deleted in the parent business object.

The Save Event

The Save event is automatically raised when the parent business object raises a Saved event. There is no code necessary in the Users window to handle this event.

The ParentStateChange Event

The ParentStateChange event is fired whenever the parent business object raises a state change event.

The following code exists in the mmMoverControl class at the Framework level, responding to parent business object changes:

private void mmMoverControl_ParentStateChange(OakLeaf.MM.Main.Business.mmBaseBusinessObject bizObj, OakLeaf.MM.Main.Business.mmBusinessStateChangeEventArgs e)
{
	switch (e.State)
	{
		case mmBusinessState.Saved:
			// Raise the Save event
			this.OnSave(bizObj, e);
			break;
		case mmBusinessState.Deleting:
			// Raise the Delete event
			this.OnDelete(bizObj, e);
			break;
		case mmBusinessState.Added:
		case mmBusinessState.Bind:
		case mmBusinessState.Canceled:
		case mmBusinessState.Navigated:
		case mmBusinessState.Retrieved:
			// Raise the Refresh event
			this.OnRefreshLists(bizObj, e);
			break;
	}
}

As you can see in this code, if the parent business object raises a Saved event, the mover's Save event is automatically fired. If the parent business object raises a Deleting event, the mover's Delete event is raised. And if the parent business object raises an Added, Bind, Canceled, Navigated, or Retrieved event, the mover's Refresh event is fired.