Scheduler Time Zones

• Feb 22, 2023
• 6 minutes to read

The Scheduler Control can recalculate appointment start and end time depending on the currently used time zone. This article explains how the control calculates these time spans for both regular and ‘floating’ appointments. The topic consists of the following sections.

• Time Zone Information
• Daylight Saving Time
• Floating Appointments
• Time Ruler
• TimeZoneEdit Control
• Reminders

Time Zone Information

Appointment data is saved in a scheduler storage object. The SchedulerStorageBase.TimeZoneId property is the associated time zone for the stored appointments. SchedulerControl displays these stored appointments in its own SchedulerOptionsBehaviorBase.ClientTimeZoneId. By default, both properties are set to the time zone of the host system (i.e., TimeZoneInfo.Local.Id). This may lead to a mismatch among end-users from different time zones referencing the same appointments. To account for varied time zones among end-users, set the scheduler storage TimeZoneId to an appropriate value for the source data and set the ClientTimeZoneId for the client’s local time. For example, if the appointment data is with respect to EST (Eastern Standard Time) and the application is run from a region in KST (Korean Standard Time), the SchedulerStorageBase.TimeZoneId can be set to “Eastern Standard Time” while the SchedulerOptionsBehaviorBase.ClientTimeZoneId remains TimeZoneInfo.Local.Id. In this case, the application will dynamically adjust for the time zone of the host environment (e.g., Korea Standard Time), and DateTimes will be displayed properly.

The scheduler control uses the standard .NET Framework System.TimeZoneInfo class to specify its time zone and, as a result, will always use Microsoft Time Zone Index Values.

Note

It is not possible to create a custom time zone by calling the standard TimeZoneInfo.CreateCustomTimeZone method since the SchedulerControl is not able to read it.

You can allow end-user customization of appointment time zones via the SchedulerStorageBase.EnableTimeZones property. If set to true, a Time Zones button will appear on the Appointment form. Clicking the Time Zones button invokes a drop-down list of available time zones the appointment can be set in.

Important

Before allowing end-user modification of appointment time zones, be sure to establish mappings for appointments and resources.

Daylight Saving Time

Daylight saving time (DST) is a region-specific practice of setting clocks one hour ahead of standard time for a period of the year to make better use of natural daylight.

System.TimeZoneInfo includes information about daylight saving adjustments where applicable, so if the scheduler’s SchedulerOptionsBehaviorBase.ClientTimeZoneId property is set for the client’s region, and the SchedulerStorageBase.TimeZoneId is set to the time zone in which the storage maintains the DateTime information, the time will be properly displayed.

A recurring appointment loaded from data will be adjusted if it lies between the start and end of the DST period. On the first day of daylight savings, when the local standard time is about to reach 02:00:00, clocks are advanced forward by an hour to 03:00:00. A recurring appointment from the database falling during DST will advance forward one hour as well.

Floating Appointments

The Scheduler supports the “floating” time zone for all-day appointments. “Floating” means that the time is independent of the client time zone. A typical example of a “floating” all-day appointment would be New Year’s Day. It starts at midnight on January 1st in any time zone. Therefore, it does not start simultaneously throughout the world - it starts at different times, according to the time zone where the client is located.

All-day appointments (appointments with the Appointment.AllDay property set to true) are always interpreted as belonging to a “floating” time zone.

To record a simultaneous event from multiple time zones an appointment should only occur once, at a different time in each time zone. In this case, a regular appointment should be used and not a “floating” appointment.

Note

When programmatically assigning Appointment.Start and Appointment.End , do not use the DateTime object specifying a System.DateTimeKind enumeration parameter value. System.DateTimeKind enumeration parameter value. Although in .NET it is helpful to indicate whether a DateTime object is in local or UTC time, XtraScheduler will ignore this flag and interpret the appointment incorrectly..

Time Ruler

Multiple time rulers can be added to distinguish different time zones more clearly. Time rulers can be added for Day, Work Week and Full Week views in one of the following ways.

1. From the SchedulerControl properties window, click the ellipsis button of the TimeRulers property (located in the SchedulerControl - Views - DayView/FullWeekView/WorkWeekView group) to invoke the TimeRuler Collection Editor. The collection editor supports adding a time ruler, adjusting its properties or removing it.

   

2. Add a new time ruler to the TimeRulerCollection in code. Use the DayView.TimeRulers property to access the collection.

   C#

   schedulerControl1.DayView.TimeRulers.Add(new TimeRuler());
   schedulerControl1.DayView.TimeRulers[1].AdjustForDaylightSavingTime = false;
   schedulerControl1.DayView.TimeRulers[1].TimeZoneId = "Tokyo Standard Time";
   schedulerControl1.DayView.TimeRulers[1].Caption = "Tokyo";
   

   VB.NET

   schedulerControl1.DayView.TimeRulers.Add(New TimeRuler())
   schedulerControl1.DayView.TimeRulers(1).AdjustForDaylightSavingTime = False
   schedulerControl1.DayView.TimeRulers(1).TimeZoneId = "Tokyo Standard Time"
   schedulerControl1.DayView.TimeRulers(1).Caption = "Tokyo"
   

To have a time ruler display the local time, set its TimeRuler.UseClientTimeZone property to true: then the TimeRuler.TimeZoneId property will be automatically set to the local time zone. To set any other time zone, simply set the UseClientTimeZone property to false and set the required TimeZoneId property. If it’s necessary to switch off the DST, toggle the TimeRuler.AdjustForDaylightSavingTime property. Note that with AdjustForDaylightSavingTime set to false, the time may be displayed incorrectly.

Customization options for time rulers are also available to end-users at runtime. Right-clicking the time ruler and selecting Customize Time Ruler… in the context menu invokes an end-user dialog to change the time zone, define a label text, decide whether to adjust for daylight saving time and to preview the current time for these settings.

TimeZoneEdit Control

The TimeZoneEdit control is a combo box that displays a list of all available time zones. You can use this editor to set the Scheduler control’s ClientTimeZoneId property value, or to display different time zones in scheduler time rulers. To do so, handle the TimeZoneEdit.EditValueChanged event, as illustrated below.

C#

private void timeZoneEdit1_EditValueChanged(object sender, EventArgs e) {
    // changing the scheduler client time zone
    schedulerControl1.OptionsBehavior.ClientTimeZoneId = timeZoneEdit1.TimeZoneId;
    // customizing the time ruler
    schedulerControl1.DayView.TimeRulers[2].TimeZoneId = timeZoneEdit1.TimeZoneId;
}

VB.NET

Private Sub timeZoneEdit1_EditValueChanged(sender As Object, e As EventArgs)
    ' changing the scheduler client time zone
    schedulerControl1.OptionsBehavior.ClientTimeZoneId = timeZoneEdit1.TimeZoneId
    ' customizing the time ruler
    schedulerControl1.DayView.TimeRulers(2).TimeZoneId = timeZoneEdit1.TimeZoneId
End Sub

Reminders

Reminder alert times are not translated when reminders are loaded into the SchedulerStorage from the data source. The reminder alerts are triggered by the SchedulerStorage using the SchedulerStorage time zone.

If daylight savings is in use, the reminder and its appointment time will be recalculated for DST. If the reminder is shifted to an undefined DST time (e.g., between 2:00:00 and 3:00:00 on the first day of Daylight Saving Time), the alert will be triggered in the first valid second (i.e., 3:00:00):

To circumvent this reminder behavior while in DST, specify the ReminderDstBehaviorType property to DstBehaviorType.Update. To dismiss the reminder, set the property to DstBehaviorType.Dismiss.