DevComponents Windows Forms Schedule Quick Start Guide

Windows Forms Schedule control provides Outlook style scheduling functionality for your Windows Forms applications.

The Schedule control is built on a Model/View paradigm.

The Model represents the actual schedule, i.e. appointments and recurrence.  The model objects can be found in DevComponents.DotNetBar.Schedule.Model namespace.

Using the model as the Appointment store, the Schedule control displays Appointment data via separate Day, Week, Month, Year, and TimeLine Views. The View objects can be found in DevComponents.DotNetBar.Schedule namespace.

This paradigm provides a clear separation between UI and data and allows us to present the same data in a number of different views, even if the views are visible at the same time and present the exact same underlining data.

Creating Model and Appointments

Usually you would have one Calendar model in your application that you work with, but this is not mandatory by any means. You would for example store it as member variable of your main Window and you would use it to add new appointments, remove them, etc.

Here is an example of how to create a Calendar model with one appointment:

C# Example:

// Create our Model 
CalendarModel _Model = new CalendarModel();
// Create new appointment and add it to the model. 
// Appointment will show up in all views attached to model automatically. 
 
Appointment appointment = new Appointment(); 
appointment.Subject = "Create Demo Application"; 
appointment.StartTime = DateTime.Now; 
appointment.EndTime = appointment.StartTime.AddMinutes(45); appointment.CategoryColor = Appointment.CategoryGreen; appointment.TimeMarkedAs = Appointment.TimerMarkerBusy;  
// Add appointment to the model   
_Model.Appointments.Add(appointment);

(The above code, as well as most included code examples in this document, can be found in the ScheduleControl sample project that is included with DotNetBar for WinForms install.  Make sure to review this project since it provides a great reference on how to use the control.)

Appointment Category Colors

Note how the appointment Category Color is specified through the CategoryColor property. CategoryColor is a string type which is used to  identify the Appointment view background and border brushes. We provide the default colors through static members on the Appointment class, like Appointment.CategoryGreen, Appointment.CategoryYellow etc.

You also have at your disposal a CalendarView property called CategoryColors.  Using this property you can create any number of uniquely defined CategoryColors that can be assigned to your Calendar Appointments, just like the built-in default Appointment.CategoryColors.

CalendarView.CategoryColors is a collection of AppointmentCategoryColor objects, which contains the following members:

string ColorName        (Corresponds to Appointment.CategoryColors)
Color TextColor
Color BorderColor
ColorDef BackColor

CalendarView.CategoryColors let’s you Add, Remove, Clear, and change AppointmentCategoryColor items as you need.

Here are a few examples of how to define your own CategoryColors and add them to the CalendarView.CategoryColors collection:

C# Example:

CalendarView.CategoryColors.Add(new AppointmentCategoryColor("MyNavyColor", Color.SkyBlue, Color.Blue, new ColorDef(Color.Navy)));
CalendarView.CategoryColors.Add(new AppointmentCategoryColor("MyOrangeColor", Color.Black, Color.Red, new ColorDef(Color.Orange, Color.OrangeRed)));
 
CalendarView.CategoryColors.Add(new AppointmentCategoryColor("MyPurpleColor", Color.MediumOrchid, Color.MediumSpringGreen, new ColorDef(new Color[] { Color.White, Color.DarkRed, Color.DarkRed, Color.DarkOrchid }, new float[] { 0, .5f, .5f, 1f })));

Note that adding a CategoryColor that already exists does not throw an error, but rather will cause the new definition to be used in place of the old one.  Redefining a  built-in CategoryColor (as shown next) is no exception to this.  When a redefined built-in CategoryColor is removed, the built-in color will then again be used.

C# Example:

CalendarView.CategoryColors.Add(new AppointmentCategoryColor("<strong>Yellow</strong>", Color.Purple, Color.DarkGray, new ColorDef(Color.Yellow)));

You use your newly defined CategoryColors just as you would the built-in Appointment.CategoryColors.  For example, given the above definitions:

C# Example:

Appointment ap = new Appointment();
 
ap.CategoryColor = "MyOrangeColor";

If you assign a non-existent CategoryColor to an appointment, or you clear or remove its definition at some point, then the default CategoryColor will be used (Appointment.CategoryDefault).

Using a CategoryColor that does not exist (e.g. Appointment.CategoryColor = “Foobar”) will not throw an error, but attempting to access nonexistant ones will (e.g. CalendarView.CategoryColors[“Foobar”].TextColor = Color.Red).

You can also set CategoryColor to an ARGB hexadecimal color that you want to use as appointment background.  For example, the following code will render an appointment with a red background:

C# Example:

Appointment ap = new Appointment();
 
ap.CategoryColor = "#FFFF0000";

Dim ap As New Appointment()   ap.CategoryColor = “#FFFF0000”

Appointment Time Markers

The same principal applies to the Appointment time marker.  The time-marker is the small vertical strip on the left hand side of appointment, as shown in image below:

You can also set TimeMarkedAs to an ARGB hexadecimal color that you want to use as appointment background. For example, the following code will render an appointment with a green background:

C# Example:

Appointment ap = new Appointment();
 
ap.TimeMarkedAs= "#FF00FF00";

Working with Appointments

Appointments are stored in the CalendarModel.Appointments collection. However, if you are using recurring appointments then only the original appointment instance will be found in Appointment collection. To get all appointments on a certain day you would use CalendarModel.GetDay method which returns a reference to Day object with all appointments, including recurring ones on that day.

Reminders and Notifications

Appointments provide two types of notifications:

1. Start Time reached notification through Appointment.StartTimeReached and CalendarModel.  You must set Appointment.StartTimeAction= StartTimeReachedEvent for AppointmentStartTime events to occur.
2. Reminders added to appointment’s Reminders collection.

CalendarModel.ReminderNotification event is fired when reminder time has been reached.   For example to create appointment with reminder in 2 minutes from now you would do following:

C# Example:

Appointment ap = new Appointment(); 
 
ap.Reminders.Add(new Reminder(DateTime.Now.AddMinutes(2)));

It is worth noting on notifications that each notification is being fired from a background thread. That means that if you plan to interact with the User Interface you must marshal the calls from the notification event handler so they execute on the UI thread. You would use: this.Dispatcher.BeginInvoke method to do so inside of your Window.

CalendarView already provides you with the AppointmentReminder event which does all work for you. Marshaling calls is only necessary if you handle notifications directly on CalendarModel or Appointment.

Once a reminder is triggered you can snooze it using Reminder.Snoozemethod.

Recurring Appointments

WinForms Schedule control provides a powerful recurring appointments engine. The following recurrence types are supported:

• Daily for appointments that recur every day
• Weekly for appointments that recur weekly or on certain days of week
• Monthly for appointments that recur every month
• Yearly for appointments that recur yearly

To set appointment recurrence you first need to set appointment.Recurrence.RecurrenceType to the recurrence pattern you want to use i.e. Daily, Weekly, Monthly or Yearly. Then you set recurrence pattern properties through corresponding property i.e.:

• Daily recurrence use: Appointment.Recurrence.Daily
• Weekly recurrence use: Appointment.Recurrence.Weekly
• Monthly recurrence use: Appointment.Recurrence.Monthly
• Yearly recurrence use: Appointment.Recurrence.Yearly

For example to create daily appointment recurrence that repeats appointment every 3^rd day and ends in 30 days you would set properties as follow:

C# Example:

Appointment ap = new Appointment(); 
 
// Set recurrence type to dail 
 
ap.Recurrence.RecurrenceType = eRecurrencePatternType.Daily;
 
// Recurrence properties are changed then on respective object Daily, Weekly, Monthly, Yearly 
 
ap.Recurrence.Daily.RepeatOnDaysOfWeek = eDailyRecurrenceRepeat.All;
 
// Repeate every 3 days 
 
ap.Recurrence.Daily.RepeatInterval = 3;
 
// End recurrence 30 days from today 
 
ap.Recurrence.RangeEndDate = DateTime.Today.AddDays(30);

VB Example:

Dim ap As New Appointment()
 
' Set recurrence type to dail

ap.Recurrence.RecurrenceType = eRecurrencePatternType.Daily
 
' Recurrence properties are changed then on respective object Daily, Weekly, Monthly, Yearly

ap.Recurrence.Daily.RepeatOnDaysOfWeek = eDailyRecurrenceRepeat.All
 
' Repeate every 3 days

ap.Recurrence.Daily.RepeatInterval = 3
 
' End recurrence 30 days from today

ap.Recurrence.RangeEndDate = DateTime.Today.AddDays(30)

To create an appointment that repeats on last Friday every month you would set properties as follows:

C# Example:

Appointment ap = new Appointment(); 
 
ap.Recurrence.RecurrenceType = eRecurrencePatternType.Monthly;
ap.Recurrence.Monthly.RelativeDayOfWeek = DayOfWeek.Friday;
ap.Recurrence.Monthly.RepeatOnRelativeDayInMonth = eRelativeDayInMonth.Last;

Dim ap As New Appointment()   ap.Recurrence.RecurrenceType = eRecurrencePatternType.Monthly ap.Recurrence.Monthly.RelativeDayOfWeek = DayOfWeek.Friday ap.Recurrence.Monthly.RepeatOnRelativeDayInMonth = eRelativeDayInMonth.Last

If you want to remove single or multiple recurring appointments from the series you can add the date you want recurring appointment not generated to appointment.Recurrence.SkippedRecurrences collection.
Recurring appointments inherit the Visible property from its root appointment meaning that if root appointment is hidden the recurring appointments will be hidden as well. In case that you want to hide root appointment but keep recurring appointments visible and control their visibility by yourself, set appointment.Recurrence.IndependentVisibility=true.

Changing Working Hours

Day and week views render working hours and working days in a different color to indicates working hours in the calendar view. To change working hours you would modify members of CalendarModel.WorkDays collection. The WorkDays collection contains instancess of WorkDay objects that describe a single working day. By default you will find 5 instances of WorkDay objects in CalendarModel.WorkDays collection: Monday, Tuesday, Wednesday, Thursday and Friday. To change working hours you would access the day you want to change and set new working times. Here is sample code to do that for Monday:

C# Example:

WorkDay workDay = _Model.WorkDays[DayOfWeek.Monday];
 
WorkTime workStartTime = new WorkTime();
 
workStartTime.Hour = 10;
workStartTime.Minute = 30;
workDay.WorkStartTime = workStartTime;
 
// Set working day end time
// 8:00 PM, 24 hour format is used
 
WorkTime workEndTime = new WorkTime();
 
workEndTime.Hour = 20;
workEndTime.Minute = 0;
workDay.WorkEndTime = workEndTime;

Using Views

To view a CalendarModel  we provide the CalendarView control which shows Day, Week and Month views for the given model. All that is needed to get started is to connect the model to a view using following statements:

C# Example:

CalendarModel _Model = new CalendarModel();
 
CalendarView.CalendarModel = _Model;

Calendar view by default shows the Single-user Daily view.

You can get the current view or change it by using the SelectedView property.

Single-User and Multi-User Views

Single-user view display is the default CalendarView display.  In this display, only one view is displayed at a time (either Day, Week, Month, Year, or TimeLine).  Also, in this mode all CalendarModel appointments will be displayed, irrespective of their Owner (see description under Multi-User topic).  To access the single-user views, use the CalendarView properties DayView, WeekView, and MonthView.

If you set the CalendarView properties DayViewDate, WeekViewDate, MonthViewDate, etc then it will effect both single-user and multi-user views.

Single User Day View

Here is an example of what the Schedule control’s DayView looks like.

Date Navigation

End-user can navigate the view dates using the DateNavigator control at the top of the view.  You can also change each view visible date range using following properties:

• DayViewDate to get/set current date in Day view
• WeekViewStartDate, WeekViewEndDate to get/set the date range visible in Week view
• MonthViewStartDate, MonthViewEndDate to get/set the date range visible in Month view
• YearViewStartDate, YearkViewEndDate to get/set the date range visible in Year view
• TimeLineViewStartDate, TimeLineViewEndDate to get/set the date range visible in TimeLine view

TimeRulerPanel and Time Slot Control

By default the Day and Week views use 30 minute time slot values. You can customize the time slot size by setting CalendarView.TimeSlotDuration property. Note that this value must be less or equal to 30 and greater than 0. In the image below the TimeSlotDuration was set to 6 so each time slot in view is 6 minutes long.

Notice in the image above that the time ruler displays the time slot labels with slot time. This is specified by CalendarView.LabelTimeSlots property which has been set to true to get the result you see. The Time Ruler uses 24 hour (military) time format by default. To switch to AM/PM use CalendarView.Is24HourFormat property. Each hour and minute value displayed in time ruler is formatted using numeric format specified by static properties ScheduleSettings.TimeRulerHourFormatString and ScheduleSettings.TimeRulerMinuteFormatString.

All Day Panel Area

The AllDayPanel area is an area displayed to the user in both the Day and Week views.  This area displays those appointments that are a day in length (or greater) or extend across day boundaries. The size of this area is determined by several factors.

If the _CalendarView.FixedAllDayPanelHeight property is set to -1, then the size of this area is permitted to float as needed to display the view’s extended appointments. In this configuration the height of the panel can range from 0 (if there are no appointments that match this criteria) to _CalendarView.MaxAllDayPanelHeight. If the area needed to fully display all extended appointments is larger than the MaxAllDayPanelHeight, then a scrollbar will appear to permit the user to scroll through any additional appointments.

If the _CalendarView.FixedAllDayPanelHeight property is set to a positive value, then the All Day Panel height will be fixed at this value, overriding the _CalendarView.MaxAllDayPanelHeight setting.

Week View

Here is an example of what the Schedule control’s WeekView looks like.

The Week View is identical to the Day View, except that it (by default) contains each day of the week (this is totally configurable, as all one needs to do to change this is to set _CalendarView.WeekViewStartDate and CalendarView.WeekViewEndDate to contain as few or as many days as desired).

Month View

Here is an example of what the Schedule control’s MonthView looks like.

This view displays appointments on a monthly basis, with appointments potentially extending across days, weeks, or months.

Year View

Here is an example of  what the Schedule control’s YearView looks like.

Setting the CalendarView.YearViewStartDate and CalendarView.YearViewEndDate will determine the number of months displayed in the calendar. The maximum number of displayable months is currently set to 120.

There are two types of day cells displayed in the calendar months – those that have associated CalendarItems (Appointments or CustomCalendarItems), and those that do not.

Day cells that have CalendarItems associated with them will, by default, have their date text displayed in Bold.  The background coloring of these items can be set to several different built-in styles (via the CalendarView.YearViewAppointmentLinkStyle property).  Day cells that do not have associated CalendarItems are, by default, displayed in the normal text and background, color and style.

In the above example, cells with associated CalendarItems are being displayed in the grey-blue diagonal gradient with bolded text.  All others, displayed in their normal defaults, signify no associated CalendarItems.

Both Appointment and Non-Appointment day cells can be “linked” to activate an alternate Calendar display view upon selection.  Here are the properties that control this behavior.

CalendarView.YearViewAppointmentLink – This property establishes how the user interacts with those cells that contain Appointments (or CalendarItems in general).  The possible settings for this property are defined in the eYearViewDayLink enum, and are as follows:  “None”, “Click”, “CtrlClick”, and “DoubleClick”.  You can combine these such that, for instance, a Click or a DoubleClick will cause the link to be activated.   The default is eYearViewDayLink.Click. This can be done like the following:

C# Example:

CalendarView.YearViewAppointmentLink = (eYearViewDayLink.CtrlClick | eYearViewDayLink.DoubleClick);

VB Example:

CalendarView.YearViewAppointmentLink = (eYearViewDayLink.CtrlClick Or eYearViewDayLink.DoubleClick)

CalendarView.YearViewNonAppointmentLink – This property establishes how the user interacts with those cells that do not contain Appointments (or CalendarItems in general).  The possible settings for this property are, again, defined in the eYearViewDayLink enum, and may be combined to give the desired interaction.  The default is eYearViewDayLink.DoubleClick.

When a selection link is established (via the means established in the above YearViewApplintmentLink and YearViewNonAppointmentLink properties), you can have any Calendar display view activated by default when the corresponding day cell is selected.  This can be accomplished via the CalendarView.YearViewLinkView property.

The CalendarView.YearViewLinkView property sets which view (None, Day, Week, Month, or TimeLine) is “linked” to the calendar day cell selection. When enabled, clicking (or hitting enter or the Spacebar) on a cell will cause the LinkView to be activated and positioned at the day/time previously selected in the YearView.  The default is eCalendarView.Day.

So, for instance, if you have the following defined, then when the user single-clicks on a day cell that has appointments on that day (or double clicks on non-appointment associated days), the system will activate the Calendar’s TimeLineView and select the current associated YearView date.

C# Example:

CalendarView.YearViewAppointmentLink = eYearViewDayLink.Click;
CalendarView.YearViewNonAppointmentLink = eYearViewDayLink.DoubleClick;
CalendarView.YearViewLinkView = eCalendarView.TimeLine;

VB Example:

CalendarView.YearViewAppointmentLink = eYearViewDayLink.Click
CalendarView.YearViewNonAppointmentLink = eYearViewDayLink.DoubleClick
CalendarView.YearViewLinkView = eCalendarView.TimeLine

The CalendarView.YearViewLinkAction property can be set to tell the system how to position within the activated YearViewLinkView view.  This is defined via the eYearViewLinkAction enum, and can be one of the two following values:  “GoToDate” or “GoToFirstCalendarItem”.  When set to “GoToDate” the activated view will be positioned at the start of the day.  If set to “GoToFirstCalendarItem”, the view (if appropriate for the chosen view) will ensure the given date/time is visible.  For more specific control, you can hook onto the CalendarView.YearViewLinkSelected property and cancel the operation, redefine the display dates for the given selection, or even redefine which Calendar view to activate for that instance.

The CalendarView.YearViewAppointmentLinkStyle property sets the display style of the AppointmentLink cells .  This property has 6 built-in link display styles – they are defined via the eYearViewLinkStyle enumeration, and range from “None” to “Style1” through “Style5”.  The default, as displayed in the above example, is eYearViewLinkStyle.Style1.

Here is another style example of a YearViewLinkStyle (“Style2”):

The background of each day cell can also be individually defined and painted.  This can be accomplished by hooking onto the CalendarView.YearViewDrawDayBackground event.  By hooking onto this event, you can  draw the background to anything you like, based on whatever you choose – type of associated appointments, day of the week, etc. Here is an example where this event has been hooked, and the background simply set to varying solid colors based upon the day of the week – for all  day cells with associated CalendarItems.

You can also draw the day cell text according to your needs as well.  This can be accomplished by hooking onto the CalendarView.YearViewDrawDayText event.  By hooking onto this event you can draw the text anyway you like, again, based upon your criteria.  Here is an example where Saturday and Sunday day cell text is drawn in Red, and the 23rd of the month is drawn in a slightly larger font, bolded and in Red.

The CalendarView.YearViewShowGridLines property can be set to either show or hide the GridLines.

The CalendarView.YearViewAllowDateSelection property enables or disables the ability to select cells in the calendar.  Cell selection follows the same mechanism as is present in the MonthView, namely the up/down/left/right/home and end keys (with the accompanying shift and control key modifiers) all permit you to select and traverse the calendar.  The mouse (with the shift key) will permit you to select a single (or a range) or dates. When disabled, no date selection is permitted, and no date selection is displayed.  Here is a look at a range of selected dates (from 6/24/2010 to 7/26/2010):

TimeLine View

Here is an example of what the Schedule Control’s TimeLineView looks like.

This view displays appointments from a TimeLine perspective. The TimeLine Period can range from minutes to years.

The basic component areas of the TimeLineView are as follows:

• Time Period Header
• Time Interval Header
• Appointments
• Condensed View
• PageNavigator
• Horizontal Scroll

The TimeLine Period Header

The TimeLineView PeriodHeader is a reflection of the setting of the _CalendarView.TimeLinePeriod property, and it’s display will change based upon the setting of this property.  The TimeLinePeriod property can be one of the following eTimeLinePeriod values:

• Minutes
• Hours
• Days
• Years

The Period header visibility can be controlled through the _CalendarView.TimeLineShowPeriodHeader property.

The TimeLine Interval Header

The TimeLineView Interval Header displays the column intervals for the given timeline period.  The following are examples of TimeLine headers that will be displayed if you define them accordingly:

C# Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Minutes;
CalendarView.TimeLineInterval = 15;

VB Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Minutes
CalendarView.TimeLineInterval = 15

C# Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Hours;
CalendarView.TimeLineInterval = 8;

VB Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Hours
CalendarView.TimeLineInterval = 8

C# Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Days;
CalendarView.TimeLineInterval = 3;

VB Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Days
CalendarView.TimeLineInterval = 3

C# Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Years;
CalendarView.TimeLineInterval = 2;

VB Example:

CalendarView.TimeLinePeriod = eTimeLinePeriod.Years
CalendarView.TimeLineInterval = 2

TimeLine TimeLineStretchRowHeight

By default, the RowHeight of each TimeLine appointment is set to a precalculated height to display one line of Appointment text.  The CalendarView.TimeLineStretchHeight property can be used to tell the system that each appointment is to be “stretched” vertically to fill the entire content area. By default this property is set to false.

C# Example:

CalendarView.TimeLineStretchRowHeight = true;

VB Example:

CalendarView.TimeLineStretchRowHeight = True

The above will result in the following:

Note:  If the appointments do not overlap, then they will be stretched to fill the entire content area. If they do overlap, then the content area will be evenly divided among the overlapping appointments.

TimeLine TimeLineGetRowHeight Event

If you need to be able to specify an alternate row height for every TimeLine appointment, or specify a row height for a specific subset of appointments, you can do so through the provided TimeLineGetRowHeight event. When the Schedule control needs to know an appointment row height in the TimeLineView, it will (if the event has been hooked) call out via this event to obtain the height of the given appointment row.

C# Example:

// Hook onto the callout event.
 
CalendarView.TimeLineGetRowHeight += CalendarViewTimeLineGetRowHeight;
 
// Process the GetRowHeight event
 
void CalendarViewTimeLineGetRowHeight(object sender, TimeLineGetRowHeightEventArgs e)
{
    Appointment ap = e.CalendarItem.ModelItem as Appointment;
 
    if (ap != null)
    {
        // Just for an example, let's make all default color appointments 140 pixels high,
        // all Blue appointments 70 high, and everything else we will keep the default value.
 
        if (ap.CategoryColor == null || ap.CategoryColor.Equals("Default"))
            e.Height = 140;
 
        else if (ap.CategoryColor.Equals(Appointment.CategoryBlue))
            e.Height = 70;
    }
}

VB Example:

' Hook onto the callout event.

CalendarView.TimeLineGetRowHeight += CalendarViewTimeLineGetRowHeight
 
' Process the GetRowHeight event

Private Sub CalendarViewTimeLineGetRowHeight(sender As Object, e As TimeLineGetRowHeightEventArgs)
    Dim ap As Appointment = TryCast(e.CalendarItem.ModelItem, Appointment)
 
    If ap IsNot Nothing Then
        ' Just for an example, let's make all default color appointments 140 pixels high,
        ' all Blue appointments 70 high, and everything else we will keep the default value.

        If ap.CategoryColor Is Nothing OrElse ap.CategoryColor.Equals("Default") Then
            e.Height = 140
 
        ElseIf ap.CategoryColor.Equals(Appointment.CategoryBlue) Then
            e.Height = 70
        End If
    End If
End Sub

The above will result in the following display:

Multi-User Views

Every view (Day, Week, or Month) can be displayed in a multi-user display setting.  In order to have the CalendarView display in multi-user mode, all you need to do is tell the CalendarView about the Owners that you want it to display.  This is accomplished by settng the CalendarView.DisplayedOwners property.

C# Example:

CalendarView.DisplayedOwners.Add("Brian");
 
// Or
 
CalendarView.DisplayedOwners.AddRange(new string[] {"Fred", "Sue", "Bob"});

VB Example:

CalendarView.DisplayedOwners.Add("Brian")
 
' Or

CalendarView.DisplayedOwners.AddRange(New String() {"Fred", "Sue", "Bob"})

Once this is done, you no longer access the single user properties (DayView, etc).  You will now access 3 separate Readonly collections for each view type – MultiCalendarDayViews, MultiCalendarWeekViews, and MultiCalendarMonthViews.  The entries in these lists directly correspond (in both Count and order) to the DisplayedOwners list provided to the system.  For example, performing the above DisplayedOwners.AddRange call would yield the following CalendarView.

Each view display is identical to the Single user view displays except for a few significant changes.

As you will notice from the above image, each view has a tab at the top or side of the view. This tab designates the “Owner” of the view.

Only appointments from the current CalendarModel whose OwnerKey matches the DisplayedOwners value for this view will be displayed.  So, if DisplayedOwners[0] equals “Fred”, then only Fred’s appointments (appointment.OwnerKey equals “Fred”) will be displayed in the MultiCalendar{Day, Week, Month}Views[0] view.

To determine whether you are in Multi-User mode or not, you can check the ReadOnly _CalendarView.IsMultiCalendar property.

If the user wants to reorder the views visually, the user can mouse-down in any of the view tabs and drag it left or right to it’s new position.  The ability to do this can be controlled by setting _CalendarView.AllowTabReorder to true or false – by default it is true.

All Day Panel Area

The AllDayPanel area is an area displayed to the user in both the Day and Week views.  This area displays those appointments that are a day in length (or greater) or extend across day boundaries. In Multi-User mode, the size of this area is determined solely by the setting of the FixedAllDayPanelHeight property..

If the _CalendarView.FixedAllDayPanelHeight property is set to -1, then the size of this area is reset back to it’s default of 50.  If the _CalendarView.FixedAllDayPanelHeight property is set to a positive value, then the AllDay Panel height will be fixed at this value.

In Multi-user mode the user is permitted to, via selecting the lower edge of the AllDayPanel, resize the panel.

Day / Week WorkDay display

The Day/Week View hours, by default, encompasses the entire day.  You can configure these views to display only those hours established as “Work Day” hours (see previous “Changing Working Hours” section). This is accomplished through the CalendarView.ShowOnlyWorkDayHours property in conjunction with the CalendarView.CalendarModel.WorkDays collection.
Setting the CalendarView.ShowOnlyWorkDayHours property to true will cause the system to examine the current CalendarView.CalendarModel.WorkDays collection and set the View hours to encompass the defined work range.  If no WorkDays are defined, then the entire day hours will be displayed.

Here is an example of a single user Week display utilizing the default CalendarModel.WorkDays collection with CalendarView.ShowOnlyWorkDayHours set to false:

Here is an example of the same time range with CalendarView.ShowOnlyWorkDayHours set to true:

Here is an example of a Multi-User display with CalendarView.ShowOnlyWorkDayHours set to true:

Changing Time Slot Colors

You can customize Time Slot background and border colors for the Day/Week views.  This can be done for specific dates and/or for specific days of the week.  The following is a screen shot of a calendar with a defined set of display customizations:

The above cell coloring can be accomplished by the following code:

C# Example:

// Mark time slots every Sunday from 12:00 to 17:00
 
DaySlotAppearance dsa = new DaySlotAppearance(new WorkTime(12, 0), new WorkTime(17, 0), Color.LightCyan, Color.SkyBlue, Color.LightBlue);
DaySlotBackground dsb = new DaySlotBackground(DayOfWeek.Sunday, dsa);
 
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Add(dsb);
 
// Mark time slots for today from 9:00 to 13:30
 
dsa = new DaySlotAppearance(new WorkTime(9, 0), new WorkTime(13, 30), Color.LightYellow, Color.Orange, Color.Yellow);
dsb = new DaySlotBackground(DateTime.Today, dsa);
 
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Add(dsb);

VB Example:

' Mark time slots every Sunday from 12:00 to 17:00

Dim dsa As New DaySlotAppearance(New WorkTime(12, 0), New WorkTime(17, 0), Color.LightCyan, Color.SkyBlue, Color.LightBlue)
Dim dsb As New DaySlotBackground(DayOfWeek.Sunday, dsa)
 
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Add(dsb)
 
' Mark time slots for today from 9:00 to 13:30

dsa = New DaySlotAppearance(New WorkTime(9, 0), New WorkTime(13, 30), Color.LightYellow, Color.Orange, Color.Yellow)
dsb = New DaySlotBackground(DateTime.Today, dsa)
 
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Add(dsb)

To remove the customizations, you can do the following:

C# Example:

CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Remove(DateTime.Today);
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Remove(DayOfWeek.Sunday);

VB Example:

CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Remove(DateTime.Today)
CalendarView.ViewDisplayCustomizations.DaySlotBackgrounds.Remove(DayOfWeek.Sunday)

For multi-user situations, you can also specify which user/OwnerKey is to be associated with each DaySlotBackground.  This can be accomplished like the following:

C# Example:

DaySlotAppearance dsa = new DaySlotAppearance(new WorkTime(12, 0), new WorkTime(17, 0), Color.LightCyan, Color.SkyBlue, Color.LightBlue);
DaySlotBackground dsb = new DaySlotBackground(DayOfWeek.Sunday, dsa);
 
dsb.OwnerKeys.Add("John");
dsb.OwnerKeys.Add("Sue");
dsb.OwnerKeys.Add("Charlie");

VB Example:

Dim dsa As New DaySlotAppearance(New WorkTime(12, 0), New WorkTime(17, 0), Color.LightCyan, Color.SkyBlue, Color.LightBlue)
Dim dsb As New DaySlotBackground(DayOfWeek.Sunday, dsa)
 
dsb.OwnerKeys.Add("John")
dsb.OwnerKeys.Add("Sue")
dsb.OwnerKeys.Add("Charlie")

By default, no OwnerKeys are initially defined for newly allocated DaySlotBackground objects – this will result in the DaySlotBackground being applied to all users. If any OwnerKeys are defined for the DaySlotBackground then the DaySlotBackground will only apply to those defined OwnerKeys. Adding the OwnerKey “” will result in the DaySlotBackground being applied to all users – no matter how many other unique OwnerKeys are currently defined.

To remove an OwnerKey from a DaySlotBackground you need only to do the following:

C# Example:

dsb.OwnerKeys.Remove("Sue");

VB Example:

dsb.OwnerKeys.Remove("Sue")

View TimeIndicator

The CalendarView control has the ability to display any number of TimeIndicators in the Day, Week, and TimeLine views.  TimeIndicators are used to give feedback to the user as to either the current system time, or a user designated time.  Here is an example of what a set of 3 different TimeIndicators could look like.

The CalendarView control has a default TimeIndicator object available for your configuration and use.  You can also define as many as you need and add them to the CalendarView.TimeIndicators collection.  Each TimeIndicator object has the following properties available for user configuration:

IndicatorTime: A DateTime value that signifies the root starting display time for the Indicator.
IndicatorTimeOffset: A TimeSpan value that signifies a time offset from the set IndicatorTime.  The Indicator will be displayed at IndicatorTime plus IndicatorTimeOffset.

IndicatorArea: The display area designation, as defined by eTimeIndicatorArea.

Header:  The Indicator is displayed only in the associated Time Header (green example in above figure).
Content:  The Indicator is displayed only in the view Content area (pink example in above figure).
All:  The Indicator is displayed in both the Time Header and view Content area (gold example in above figure).

IndicatorSource:  Designates the source of the IndicatorTime, as defined by eTimeIndicatorSource.

SystemTime:  IndicatorTime is updated by the System time at 1 minute intervals (if enabled, see below).
UserSpecified:  IndicatorTime is specified and maintained by the user.

Visibility:  Designates the Indicator’s visibility, as defined by eTimeIndicatorVisibility.

AllResources:  Indicator is displayed on all available views (gold example in above figure).
SelectedResources:  Indicator is displayed only on the currently selected view (pink example in above figure).
Hidden:  Indicator is hidden (default).

BorderColor:  Designates the leading edge border color.
IndicatorColor:  Designates the Gradient color of the Indicator.
Thickness:  Designates the thickness of the Indicator (default is 4).

Enabled:  Indicates whether automatic IndicatorTime updates are enabled (only utilized when IndicatorSource is SystemTime).

To utilize the default CalendarView TimeIndicator, you need only access it via CalendarView.TimeIndicator.  All you need do is to set the initial IndicatorTime and its Visibility to either AllResources or SelectedResources.

C# Example:

CalendarView.TimeIndicator.IndicatorTime = DateTime.Now;
CalendarView.TimeIndicator.Visibility = eTimeIndicatorVisibility.AllResources;

VB Example:

CalendarView.TimeIndicator.IndicatorTime =  DateTime.Now
CalendarView.TimeIndicator.Visibility =  eTimeIndicatorVisibility.AllResources

Here are code examples showing how to create the pink and green TimeIndicators as shown in the above figure:

C# Example:

// Allocate a new TimeIndicator and
// initialize it as needed
 
TimeIndicator ti = new TimeIndicator();
 
ti.Thickness  = 10;
ti.IndicatorTimeOffset = new TimeSpan(2, 15, 0);
ti.BorderColor  = Color.Green;
ti.IndicatorColor = new ColorDef(new Color[] {  Color.Empty, Color.GreenYellow, Color.Green }, new float[] { 0f, .5f, 1f  });
ti.Visibility = eTimeIndicatorVisibility.AllResource;
ti.IndicatorArea  = eTimeIndicatorArea.Header;
 
// Add indicator to the collection
 
CalendarView.TimeIndicators.Add(ti);
 
// Allocate next TimeIndicator and
// initialize it as needed
 
ti  = new TimeIndicator();
 
ti.Thickness = 20;
ti.IndicatorTimeOffset  = new TimeSpan(-2, 15, 0);
ti.BorderColor = Color.HotPink;
ti.IndicatorColor  = new ColorDef(Color.Empty, Color.Pink);
ti.Visibility =  eTimeIndicatorVisibility.SelectedResource;
ti.IndicatorArea =  eTimeIndicatorArea.Content;
 
// Add indicator to the collection
 
CalendarView.TimeIndicators.Add(ti);

VB Example:

' Allocate a new TimeIndicator and
' initialize it as needed

Dim ti As New TimeIndicator()
 
ti.Thickness = 10
ti.IndicatorTimeOffset = New TimeSpan(2, 15, 0)
ti.BorderColor = Color.Green
ti.IndicatorColor = New ColorDef(New Color() {Color.Empty, Color.GreenYellow, Color.Green}, New Single() {0F, 0.5F, 1F})
ti.Visibility = eTimeIndicatorVisibility.AllResource
ti.IndicatorArea = eTimeIndicatorArea.Header
 
' Add indicator to the collection

CalendarView.TimeIndicators.Add(ti)
 
' Allocate next TimeIndicator and
' initialize it as needed

ti = New TimeIndicator()
 
ti.Thickness = 20
ti.IndicatorTimeOffset = New TimeSpan(-2, 15, 0)
ti.BorderColor = Color.HotPink
ti.IndicatorColor = New ColorDef(Color.Empty, Color.Pink)
ti.Visibility = eTimeIndicatorVisibility.SelectedResource
ti.IndicatorArea = eTimeIndicatorArea.Content
 
' Add indicator to the collection

CalendarView.TimeIndicators.Add(ti)

TimeIndicators can be as subtle or as “daring” as you like:

The above was created with the following code:

C# Example:

TimeIndicator ti = new TimeIndicator();
 
ti.Thickness  = 40;
ti.BorderColor = Color.MidnightBlue;
ti.IndicatorColor =  new ColorDef(new Color[] { Color.Empty, Color.AliceBlue,  Color.DeepSkyBlue, Color.DarkSlateBlue },  new float[] { 0f, .15f, .55f,  1f });
ti.IndicatorArea = eTimeIndicatorArea.Content;
ti.Visibility  = eTimeIndicatorVisibility.AllResources;
 
CalendarView.TimeIndicators.Add(ti);

VB Example:

Dim ti As New TimeIndicator()
 
ti.Thickness = 40
ti.BorderColor = Color.MidnightBlue
ti.IndicatorColor = New ColorDef(New Color() {Color.Empty, Color.AliceBlue, Color.DeepSkyBlue, Color.DarkSlateBlue}, New Single() {0F, 0.15F, 0.55F, 1F})
ti.IndicatorArea = eTimeIndicatorArea.Content
ti.Visibility = eTimeIndicatorVisibility.AllResources
 
CalendarView.TimeIndicators.Add(ti)

Date Range Selection

You can both get and set the selected date range using DateSelectionStart and DateSelectionEnd properties. The user may also change these properties by selecting a range of dates on the calendar using the mouse.

Moving and resizing Appointments

Appointments can both be moved and resized. – unless they are Locked (appointment.Locked == true). When selected, each appointment that can be moved or resized, willpresent the user with appropriate feedback – resize handles and cursor changes.  To move an appointment all one needs do is mouse down on it and drag it to the desired location.  Resizing follows the same pattern – mouse doen on a resize handle and drag it’s edge to resize it.

Normally, when the user attempts to move or resize an appointment, then appointment bounds are snapped to the nearest time slot boundary.  But, if the user holds the Alt-Key down while either moving or resizing an appointment, then the appointment is changed by 1 minute increments instead.

While appointments are moved or resized following events are fired on CalendarView control: BeforeAppointmentViewChange, AppointmentViewChanging and AppointmentViewChanged. Event arguments for each event will provide all information about nature of the change.

Appointment Display Template

Each appointment can have its own Display Template.  The Appointment.DisplayTemplate property is used to establish a “template” to use when the Schedule control is displaying text for the given appointment.  The Appointment.DisplayTemplate property is a string field that can contain replaceable Text Templates, or Mini-Markup text (as controlled via the CalendarView.EnableMarkup property).  Template Text is case sensitive, and must be encapsulated in brackets.

The currently available, system defined DisplayTemplate values (derived from their associated Appointment definitions) are as follows:

[StartTime]
[StartDate]
[EndTime]
[EndDate]
[Subject]
[Description]
[Id]
[Tag]

When the Schedule Control encounters any of the above template items, it will replace the template text (including the brackets) with the appointment’s associated value.

C# Example:

Appointment ap = new Appointment(DateTime.Now, DateTime.Now.AddHours(3), "Environmental Impact Meeting");
 
ap.TimeMarkedAs = Appointment.TimerMarkerTentative;
ap.Description = "This meeting's purpose is to discuss the potential environmental impact resulting from the change in fuel source from methane to coal.";
 
ap.DisplayTemplate =
 "

[StartDate]” + “[StartTime] – [EndTime] ” + “[Subject]” + “[Description“;

VB Example:

Dim ap As New Appointment(DateTime.Now, DateTime.Now.AddHours(3), "Environmental Impact Meeting")
 
ap.TimeMarkedAs = Appointment.TimerMarkerTentative
ap.Description = "This meeting's purpose is to discuss the potential  environmental impact resulting from the change in fuel source from  methane to coal."
 
ap.DisplayTemplate =
 "

[StartDate]” &_ “[StartTime] – [EndTime] ” &_ “[Subject]” &_ “[Description“

VB Example:
The above will result in the following Appointment display:

When the Schedule Control encounters a DisplayTemplate value that it does not recognize (i.e. not one of the above system defined values), the control will call out to retrieve the DisplayText for the given DisplayTemplate via the CalendarView.GetDisplayTemplateText event.

So, for example, if you had the following Appointment.DisplayTemplate defined:

C# Example:

ap.DisplayTemplate =
 "

[StartDate]” + “[StartTime] – [EndTime]” + “([MyStartTimeTemplate] – [MyEndTimeTemplate]) ” + “[Subject]” + “[Description“;

VB Example:

ap.DisplayTemplate =
   "

[StartDate]” &_ “[StartTime] – [EndTime]” &_ “([MyStartTimeTemplate] – [MyEndTimeTemplate]) ” &_ “[Subject]” &_ “[Description“

The above [MyStartTimeTemplate] and [MyEndTimeTemplate] template values are not recognized, built-in values, so the CalendarView control will raise the GetDisplayTemplateText event to retrieve their associated DisplayText.  Here is what an example of the event handler might look like:

C# Example:

// Hook onto our callout event
 
CalendarView.GetDisplayTemplateText += CalendarViewGetDisplayTemplateText;
 
// Handle the GetDisplayTemplateTextcallout event
 
void CalendarViewGetDisplayTemplateText(object sender, GetDisplayTemplateTextEventArgs e)
{
    AppointmentView view = e.CalendarItem as AppointmentView;
 
    if (view != null)
    {
        switch (e.DisplayTemplate)
        {
            case "[MyStartTimeTemplate]":
                e.DisplayText = String.Format("{0:F}", view.Appointment.StartTime);
                break;
 
            case "[MyEndTimeTemplate]":
                e.DisplayText = String.Format("{0:T}", view.Appointment.EndTime);
                break;
        }
    }
}

VB Example:

' Hook onto our callout event

CalendarView.GetDisplayTemplateText += CalendarViewGetDisplayTemplateText
 
' Handle the GetDisplayTemplateTextcallout event

Private Sub CalendarViewGetDisplayTemplateText(sender As Object, e As GetDisplayTemplateTextEventArgs)
    Dim view As AppointmentView = TryCast(e.CalendarItem, AppointmentView)
 
    If view IsNot Nothing Then
        Select Case e.DisplayTemplate
            Case "[MyStartTimeTemplate]"
                e.DisplayText = [String].Format("{0:F}", view.Appointment.StartTime)
            Exit Select
 
            Case "[MyEndTimeTemplate]"
                e.DisplayText = [String].Format("{0:T}", view.Appointment.EndTime)
            Exit Select
        End Select
    End If
End Sub

And here is the result of the above code:

Appointment Images

Each appointment can have it’s own unique Image and alignment associated with it.  In order for images to be displayed in an appointment view, the Form must have an ImageList defined and associated with the controlling CalendarView via the CalendarView.Images property.

Images defined in the CalendarView.Images collection can then be associated with a given appointment via the Appointment.ImageKey property. The Appointment.ImageKey is a string value, specifying the Name of the image.

Appointment images can be aligned via the Appointment.ImageAlign property.  It can be set to one of the following eImageContentAlignment values:

TopLeft
TopCenter
TopRight
MiddleLeft
MiddleCenter
MiddleRight
BottomLeft
BottomCenter
BottomRight

Here is an example of each alignment setting:

Selection in Views

Appointment model objects are represented in views using instances of AppointmentView object. Each AppointmentView object will raise the Selector.SelectedEvent or Selector.UnselectedEvent events as their selection status changes in User Interface.

CalendarView.SelectedAppointments property returns the read-only collection of all selected AppointmentView objects in current view.

You can use AppointmentView.IsSelected property to get or set whether an appointment view is selected or not.

To prevent an appointment from being selected by end-user in view and its time changed set Appointment.Locked = true.

View Hit Testing

There are two methods provided for you to be able to give you more information pertaining to where, and with what, the mouse is interacting.

The first method is _CalendarView.GetDateSelectionFromPoint().  This method take a Point, and two “out” DateTime parameters.  It will return true if the Point is within a selectable date area, false if it is not. The following is an example of it’s usage.

C# Example:

DateTime startDate;
DateTime endDate;
 
if (CalendarView.GetDateSelectionFromPoint(pt, out startDate, out endDate) == true)
{
    CalendarView.DateSelectionStart = startDate;
    CalendarView.DateSelectionEnd = endDate;
}

VB Example:

Dim startDate As DateTime
Dim endDate As DateTime
 
If CalendarView.GetDateSelectionFromPoint(pt, startDate, endDate) = True Then
    CalendarView.DateSelectionStart = startDate
    CalendarView.DateSelectionEnd = endDate
End If

The second method is used to determine what area of a given view the Point is associated with.  This can be especially useful for things like determining where the user right mouse-clicked in a view so that you can present the user with an appropriate context menu for the given area clicked.  For example, in response to a right click MouseUp event, one could do the following to determine where the event actually took place:

C# Example:

eViewArea area = view.GetViewAreaFromPoint(e.Location);

VB Example:

Dim area As eViewArea = view.GetViewAreaFromPoint(e.Location)

The eViewArea defines InContent, InDayOfWeekHeader, InSideBarPanel, and InTab areas. The following is an example where the right mouse click was caught and used to present the user with an AllDayPanel area specific context menu.

Making a Specific Date or Appointment “In View”

Apart from setting a view’s start and end dates (WeekVewStartDate, etc) you can also show a specific date through 3 additional CalendarView methods.  They are ShowDate, ScrollToTime, and EnsureVisible.

ShowDate method takes a Date and causes the currently selected view to show that date in it’s display.

ScrollToTime method takes an hour and minute, and causes the current view to scroll to that time.  This method only has meaning to the Day and Week views, and does not cause the view to exceed the bounds of it’s current date range.  An example of a call to this method to cause the display to scroll to 8:15am would be as follows:

C# Example:

CalendarView.ScrollToTime(8, 15);

VB Example:

CalendarView.ScrollToTime(8, 15)

EnsureVisible method takes and appointment and ensures that it is visible in the current calendar view.

Finding an Appointment View

Using  GetAppointmentView method you can retrieve the AppointmentView for given Appointment in currently selected calendar view.

The default CalendarView implementation provides a sample Reminder Dialog which should be used as starting point for creation of your own reminder dialog. AutoPopupReminderDialog property indicates whether the internal reminder dialog is used to display appointment reminders.

ICS (Internet Calendaring and Scheduling – RFC5545) Support

Model Appointments can be Imported from, and Exported to, industry standard ICS files.

Importing:

In order to import from an existing ICS file, you will need to allocate an ICS Import object and initialize it to suit your requirements. The following code will attempt to open the file “HolidaySchedule.ics” and import all ICS “Event” and “Alarm” components (VEVENT and VALARM) into the associated CalendarModel:

C# Example:

// Allocate and initialize our importer object
 
IcsImporter ics = new IcsImporter(_CalendarView.CalendarModel);
ics.IncludeComponent = IcsImporter.IcsComponent.Event | IcsImporter.IcsComponent.Alarm;
 
// Perform the actual import into our CalendarModel
 
ics.Import("HolidaySchedule.ics");

VB Example:

 Allocate and initialize our importer object
 
Dim ics As New IcsImporter(_CalendarView.CalendarModel)
ics.IncludeComponent = IcsImporter.IcsComponent.Event Or IcsImporter.IcsComponent.Alarm
 
' Perform the actual import into our CalendarModel

ics.Import("HolidaySchedule.ics")

Each ICS file can contain multiple “Calendar” components (VCALENDAR).  Each ICS encountered Calendar entry has a given name.  The following is an example of an ICS file that contains 2 Calendar entries, whose calendar names (X-WR-CALNAME) are “Salaried” and NonSalaried”:

BEGIN:VCALENDAR

PRODID:-//DotNetBar\, Inc//iCal 1.0//EN
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Salaried

BEGIN:VEVENT
DTSTAMP:20020917T175455Z
UID:1574C48A-74F0-11D7-9029-000A2789940A
SUMMARY:New Year’s Day
RRULE:FREQ=YEARLY;BYMONTH=1
DTSTART;VALUE=DATE:20020101
DTEND;VALUE=DATE:20020102
END:VEVENT
END:VCALENDAR

BEGIN:VCALENDAR
PRODID:-//DotNetBar\, Inc//iCal 1.0//EN
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:NonSalaried

BEGIN:VEVENT
DTSTAMP:20020917T175456Z
UID:1574E702-74F0-11D7-9029-000A2789940A
SUMMARY:Remembrance Day
RRULE:FREQ=YEARLY;BYMONTH=11
DTSTART;VALUE=DATE:20021111
DTEND;VALUE=DATE:20021112
END:VEVENT
END:VCALENDAR

By default, the ICS file specified Calendar names (X-WR-CALNAMEs) are used to specify the Appointment OwnerKey when adding new appointments generated via the processing of VCalendar event components (VEVENTS, VTODO, VALARM, etc).  So, for example, letting the ICS importer perform the import with it’s default import specification, you will get the foillowing results (given the above sample ICS file contents):

ics.Import(“HolidaySchedule.ics”):

Appointment #1:
OwnerKey = “Salaried”;
StartDate = 01/01/2002
EndDate = 01/02/2002

Subject = “New Year’s Day”

Appointment #2:
OwnerKey = “NonSalaried”;
StartDate = 11/11/2002
EndDate = 01/02/2002

Subject = “New Year’s Day”

If you only want to import a single Calendar component from the given ICS file (for example, the “NonSalaried” Calendar component in our above case), you can do the following:

C# Example:

ics.Import("HolidaySchedule.ics", "NonSalaried");

VB Example:

ics.Import("HolidaySchedule.ics", "NonSalaried")

If a provided Calendar Name is set to null or the null string, then all imported appointments will be added with the OwnerKey set to “”.

You can also designate that a given ICS file calendar entry is to be associated with a given Appointment OwnerKey.  So, for instance, if you wanted to have the above “Salaried” calendar entries added as appointemts, with each appointment’s OwnerKet set to “Richard”, you could do the following:

C# Example:

ics.Import("HolidaySchedule.ics", "Salaried", "Richard");

VB Example:

ics.Import("HolidaySchedule.ics", "Salaried", "Richard")

If you want to remap several Calendar entries into associated OwnerKey values, you can do the following:

C# Example:

string[] calNames = new {"Salaried", "NonSalaried"};
string[] ownerKeys = new {"Bob", "Sally"};
 
ics.Import("HolidaySchedule.ics", calNames, ownerKeys);

VB Example:

Dim calNames As String() = New From { "Salaried", "NonSalaried" }
Dim ownerKeys As String() = New From { "Bob", "Sally" }
 
ics.Import("HolidaySchedule.ics", calNames, ownerKeys)

The above array parameters specify a one-to-one mapping between ICS Calendar Names and Appointment OwnerKeys.  All “Salaried” Calendar added appointments will have their OwnerKey set to “Bob”, and all “NonSalaried” Calendar added appointments will have their OwnerKey set to “Sally”.

If, when calendar names are specified, the ICS importer encounters Calendar Names not contained in the provided list, then they will be bypassed and no appointments will be generated from them.

If a specified Calendar Name does not have a corresponding OwnerKey entry, then all imported appointments for the specified Calendar will be added with the associated OwnerKey set to the name of the Calendar.

Exporting:

In order to export to an ICS file, you will need to allocate an ICS Export object and initialize it to suit your requirements. The following code will export all CalendarModel appointments to the file “MySchedule.ics”:

C# Example:

// Allocate our exporter object
 
IcsExporter ics= new IcsExporter(_CalendarView.CalendarModel);
 
// Perform the actual export of our CalendarModel Appointments
 
ics.Export("MySchedule.ics");

VB Example:

' Allocate our exporter object

Dim ics As New IcsExporter(_CalendarView.CalendarModel)
 
' Perform the actual export of our CalendarModel Appointments

ics.Export("MySchedule.ics")

If you want to only export appointments with a specific OwnerKey (for example, “Charlie”), you can do the following:

C# Example:

ics.Export("MySchedule.ics", "Charlie", "Salaried");

VB Example:

ics.Export("MySchedule.ics", "Charlie", "Salaried")

As with imported ICS files, exported ICS files can also contain multiple “Calendar” components (VCALENDAR), with each Appointment OwnerKey being associated with a given Calendar entry.   The following is an example where Appointments whose OwnerKey is “Sue” will be exported as CalendarName “Salaried”, and appointments with OwnerKey “Benton” will be exported as CalendarName “NonSalaried” :

C# Example:

string[] ownerKeys = new {"Sue", "Benton"};
string[] calNames = new {"Salaried", "NonSalaried"};
 
ics.Export("MySchedule.ics", ownerKeys, calNames);

VB Example:

Dim calNames As String() = New From { "Salaried", "NonSalaried" }
Dim ownerKeys As String() = New From { "Bob", "Sally" }
 
ics.Export("MySchedule.ics", ownerKeys, calNames);

Related posts:

1. How to show custom Tooltip for Schedule Appointments
2. How to enumerate all Appointments between two dates in Schedule control
3. Micro-Charts for WinForms Quick Start Guide
4. Tabbed User Interface Quick Start Guide
5. ComboTree Quick Start Guide