WPF Elements: Custom Schedule Items

One of the new additions to WPF Elements 3.0 as the WPF Scheduler control. This control is similar to the calendar seen in Microsoft Office Outlook and is used to display and manage schedule items. The Scheduler control comes with a standard schedule item that is made up of a start time, end time and a title. In this blog post we look into implementing a custom schedule item for the Scheduler control to display. Before we start writing any code, we need to revise the various ways that a user can add an item to the Scheduler:

  • Click the “Add Appointment” button in the top right corner of the Scheduler.
  • Double click the mouse over a time slot in any of the views.
  • Select some time slots and then start typing the appointment title with the keyboard.
  • Hover the mouse over a time slot and click the “Add item here” button that shortly appears.

Once an item has been added to the Scheduler, it can be displayed in 3 different ways: In the time slot area of day view and week view, items that are less than 24 hours long are displayed as large rectangles with the title showing at the top.

Schedule Item

Along the top of day view and week view, and also throughout month view, items can be seen as long flat rectangles displaying the start time, end time and title.

Long schedule item

And finally, items in month view that are less than 24 hours long are displayed differently to items that cross multiple days. For example, the Office Blue theme displays short schedule items with no border as seen below.

Short schedule item

Adding custom schedule items

The custom schedule item that we will implement will represent a meeting. When creating schedule items, we extend the ScheduleItem class which gives it a start time, end time and a title. Our meeting item will also store the name of the main speaker at the meeting, and a boolean to specify whether or not free pizza will be provided. Any class that extends ScheduleItem can be added to the Scheduler control using the Scheduler.Schedule.AddItem method. However, you are most likely going to want to override the behavior of some of the add item features mentioned above in order to add instances of your own items instead. This is achieved by implementing the IScheduleItemBuilder interface and then setting the Scheduler.Schedule.ScheduleItemBuilder property. This interface has a single method to implement called CreateScheduleItem. The parameter of this method contains information about the action that the user performed, and the method returns the created item along with some other information which we will see later. To keep things simple, we will just look at adding a meeting item in the case where the user selects some time slots and starts typing on the keyboard. Here is what the method implementation would look like:

public CreateScheduleItemResult CreateScheduleItem(CreateScheduleItemArgs args)
{
    ScheduleItem item = null;
    DateTime start = args.StartTime;
    DateTime end = args.EndTime;
    switch (args.CreationType)
    {
        case ScheduleItemCreationType.TextInput:
            item = new TaskScheduleItem();
            break;
        case ScheduleItemCreationType.CreateHereButton:
            ...
            break;
        case ScheduleItemCreationType.DoubleClick:
            ...
            break;
        case ScheduleItemCreationType.AddItemToolBarButton:
            ...
            break;
    }
    if (item != null)
    {
        item.StartTime = start;
        item.EndTime = end;
        item.Name = args.ScheduleItemName;
        args.Schedule.AddItem(item);
    }
    return new CreateScheduleItemResult(item, false);
}

We start by gathering the start and end time from the parameter which has been generated based on the users interaction with the control. Next we use a switch on the ScheduleItemCreationType which is where we can create an instance of our meeting item. If we created an item within the switch, we then set the start time, end time and name properties, and finally add it to the schedule. Other things you may want to do in this method include modifying the start time, end time or name values, setting properties specific to your item implementations, or displaying a custom schedule item dialog for editing the item before it gets added. At the end of this method, we need to return a new CreateScheduleItemResult which takes the item that we created and a boolean indicating if we want the Scheduler to add a default item instead. If we use null and true as the parameters here, then we can allow the standard operation to take place for any of the ‘add item’ features. Alternatively, we can use null and false to disable one of the standard ‘add item’ features.

Styling custom schedule items

Now that we can add custom schedule items to the scheduler, we need to define how they should look. Defining the appearance of a schedule item is split into 2 parts. The item style and the item template. The template is used to provide the item with a shape, some color and also the placement of the title and any other information we want it to display. The style is used to include controls for dragging the item to different places in the scheduler, changing the start or end times and changing the look when the item is selected. These such styles and templates can be applied to each of the 3 display scenarios mentioned in the beginning of this blog post. That means that for each type of custom schedule item, there can be up to 6 parts that we need to create. Fortunately, you don’t need to worry about the 3 item styles if you like the look and feel that the standard styles provided when an item is selected. Once you’ve created the 3 templates for a custom schedule item, they can be given to the Scheduler control by creating template selectors and setting the appropriate properties of a SchedulerFormatter object. The ScheduleItemTemplateSelector property is used for the main schedule item template seen in the body of week view and day view. LongItemTemplateSelector is used for items that are 24 hours or longer. And finally, ShortItemTemplateSelector is used for items displayed in month view that are less than 24 hours. If you happen to want to provide your own item styles as well. Then you can use the 3 similar properties on the SchedulerFormatter for setting style selectors. After setting the Scheduler.Formatter property to be a SchedulerFormatter containing our custom templates, the meeting item can be made to look as follows.

Meeting Item

Creating your own custom schedule items will allow you to customize the Scheduler control based on the requirements of you applications. A sample demonstrating the concepts outlined in this blog post can be found here. It includes the meeting item I have used as an example here as well as another custom schedule item representing a task. The sample shows how to provide both custom item templates and custom item styles, as well as examples of simple editing dialogs. To run the sample, make sure you include a reference to your copy of WPF Elements 3.0. You can download a free trial copy here, or purchase a retail copy from the store.

If you have any questions about the sample or need any help creating your own custom schedule items then put a comment on this blog post or let us know in the forum.

Tagged as WPF Elements

Leave a Reply

Archives

Join our mailer

You should join our newsletter! Sent monthly:

Back to Top