Tutorial 4: Creating Custom Appointment Classes

This tutorial shows how to create a custom schedule item class. For simplicity, the sample demonstrates that by inheriting a class from Appointment.

1. Create and initialize a new WPF application project

Follow steps 1 through 3 from Tutorial 1: Getting Started.

2. Create new class for the custom item

Select Project -> Add Class... from the menu, type the name of the custom item class in the dialog that appears (for example MyApp) and click 'OK'. Include the MindFusion.Scheduling namespace at the beginning of the file.

C#

using MindFusion.Scheduling;

Visual Basic

Imports MindFusion.Scheduling

The custom class will expose a new property of type Boolean (called Kept) that will indicate whether the appointment has been kept or cancelled. The implementation of the property is trivial. Simply add a private field of type Boolean and make the property getter setter to return the field and to set the field respectively. The following sample code illustrates this:

C#

public class MyApp : Appointment
{
    public MyApp()
    {
        _kept = true;
    }

    public bool Kept
    {
        get { return _kept; }
        set { _kept = value; }
    }

    private bool _kept;
}

Visual Basic

Class MyApp
    Inherits Appointment

    Public Sub New()

        _kept = True

    End Sub


    Public Property Kept() As Boolean

        Get
            Return _kept
        End Get

        Set(ByVal Value As Boolean)
            _kept = Value
        End Set

    End Property


    Private _kept As Boolean

End Class

Note
You must provide constructor that takes no argument with your custom item class. MindFusion.Scheduling for WPF creates item class instances using reflection and an exception will be thrown if there isn't such constructor available.

3. Set the custom item as default

By default the Calendar control instantiates items of type Appointment when the user creates items interactively (by typing). To make the calendar create items of the new class, add the following line of code in the window's constructor.

C#

calendar.InteractiveItemType = typeof(MyApp);

Visual Basic

calendar.InteractiveItemType = GetType(MyApp)

Now all items created by the user at runtime will be instances of MyApp.

4. Test

To test whether the calendar actually creates MyApp instances, add an event handler to the control's ItemClick event. Add the following as a body of the event handler:

C#

if (e.Item is MyApp)
{
    calendar.ResetDrag();
    MessageBox.Show("This is our item.");
}

Visual Basic

If TypeOf e.Item Is MyApp Then

    calendar.ResetDrag()
    MessageBox.Show("This is our item.")

End If

Clicking on an item now should display the message box.

5. Serialization

Serialization of custom items requires additional efforts. Attempts to save a schedule containing items of type MyApp will result in an InvalidOperationException exception. In order to support serialization, we have to register MyApp with the schedule. For this purpose, add the following line of code somewhere in the window's constructor:

C#

Schedule.RegisterItemClass(typeof(MyApp), "myapp", 1);

Visual Basic

Schedule.RegisterItemClass(GetType(MyApp), "myapp", 1)

Now the exception won't be thrown, but you still need to override the SaveTo and LoadFrom methods of the Appointment class in order to serialize the custom property Kept. The code below illustrates how this is done.

C#

public override void SaveTo(XmlElement element, XmlSerializationContext context)
{
    base.SaveTo(element, context);
    context.WriteBool(kept, "Kept", element);
}

public override void LoadFrom(XmlElement element, XmlSerializationContext context)
{
    base.LoadFrom(element, context);
    kept = context.ReadBool("Kept", element);
}

Visual Basic

Public Overrides Sub SaveTo(ByVal element As XmlElement, ByVal context As XmlSerializationContext)

    MyBase.SaveTo(element, context)
    context.WriteBool(_kept, "Kept", element)

End Sub

Public Overrides Sub LoadFrom(ByVal element As XmlElement, ByVal context As XmlSerializationContext)

    MyBase.LoadFrom(element, context)
    _kept = context.ReadBool("Kept", element)

End Sub

6. Recurrence

Recurrence of items from a custom class is not handled wholly automatically. Let's take a closer look at how recurrence works in MindFusion.Scheduling for WPF. When a recurrence pattern is associated with an existing item, the item is said to become the master of the recurrence. Every time the occurrences of a master item must be displayed in a given time range, they are generated by instantiating new objects of the same type as that of the master. This is necessary in order to support infinite recurrences, where the generation of all recurrence instances is not possible. When the occurrences are generated, their properties are copied from the master item. This is done automatically for the built-in item properties, but not for those added by a derived item class. In order to copy the custom properties from the master item to a particular occurrence, you need to override the CopyOccurrence method. The following code sample shows how to do this.

C#

protected override void CopyOccurrence(Item master)
{
    base.CopyOccurrence(master);
    _kept = (master as MyApp).Kept;
}

Visual Basic

Protected Overloads Overrides Sub CopyOccurrence(ByVal master As Item)

    MyBase.CopyOccurrence(master)
    _kept = CType(master, MyApp).Kept

End Sub

In addition, it is recommended to mark an item from a recurrent series as an exception when the value of a custom property changes. Otherwise, the change will be lost the next time the instance is generated.

C#

//...
public bool Kept
{
    get { return _kept; }
    set
    {
        _kept = value;

        if (Recurrence != null)
            Recurrence.MarkException(this, false);
    }
}
//...

Visual Basic

' ...
Public Property Kept() As Boolean

    Get
        Return _kept
    End Get

    Set(ByVal Value As Boolean)

        _kept = Value

        If Not Recurrence Is Nothing Then
            Recurrence.MarkException(Me, False)
        End If

    End Set

End Property
' ...

7. Interactive cloning

The users can clone items by holding down a particular key (the SHIFT key by default). To enable your custom items for interactive cloning, you have to override the Clone method, create a new object from your custom type and duplicate the fields of the prototype item. If you do not override the Clone method, MindFusion.Scheduling for WPF will still create copies of the item, but they will be of type Appointment instead of the custom item type. Here is a sample implementation of the Clone method.

C#

//...
public override object Clone()
{
    MyApp clone = new MyApp();

    // The following code replicates the code used in
    // the Appointment's Clone method
    clone.AllDayEvent = this.AllDayEvent;
    clone.DescriptionText = this.DescriptionText;
    clone.EndTime = this.EndTime;
    clone.HeaderText = this.HeaderText;
    clone.Location = this.Location;
    clone.Locked = this.Locked;
    clone.Priority = this.Priority;
    clone.Reminder = this.Reminder;
    clone.SelectedStyle = this.SelectedStyle.Clone() as Style;
    clone.StartTime = this.StartTime;
    clone.Style = this.Style.Clone() as Style;
    clone.Tag = this.Tag;
    clone.Task = this.Task;
    clone.Visible = this.Visible;

    foreach (Resource resource in this.Resources)
        clone.Resources.Add(resource);

    foreach (Contact contact in this.Contacts)
        clone.Contacts.Add(contact);

    // Now copy the custom fields
    clone.Kept = this.Kept;

    return clone;
}
//...

Visual Basic

'...
Public Overloads Overrides Function Clone() As Object

    Dim aClone As New MyApp

    ' The following code replicates the code used in
    ' the Appointment's Clone method
    aClone.AllDayEvent = Me.AllDayEvent
    aClone.DescriptionText = Me.DescriptionText
    aClone.EndTime = Me.EndTime
    aClone.HeaderText = Me.HeaderText
    aClone.Location = Me.Location
    aClone.Locked = Me.Locked
    aClone.Priority = Me.Priority
    aClone.Reminder = Me.Reminder
    aClone.StartTime = Me.StartTime
    aClone.Tag = Me.Tag
    aClone.Task = Me.Task
    aClone.Visible = Me.Visible

    Dim resource As Resource
    For Each resource In Me.Resources
        aClone.Resources.Add(resource)
    Next resource

    Dim contact As Contact
    For Each contact In Me.Contacts
        aClone.Contacts.Add(contact)
    Next contact

    ' Now copy the custom fields
    aClone.Kept = Me.Kept

    Return aClone

End Function
'...