Time Zones

• May 22, 2020
• 4 minutes to read

This document describes the time zone support implemented in the Scheduler. It explains how the Scheduler calculates appointment start and end values for display and indicates the difference between the regular and "floating" appointments.

Time zone information is used to calculate start and end times for an appointment. The AppointmentStorage.DateSaving property specifies how to determine the time zone of the appointment start and end values contained in the appointment storage. According to that property, the time zone either takes the time zone of the host system (the DateSavingType.LocalTime value), or Coordinated Universal Time (UTC) (the DateSavingType.UTC value). After recognizing the time zone based on the AppointmentStorage.DateSaving property, the Scheduler displays an appointment using the start and end values converted to the time zone specified by the OptionsBehavior.ClientTimeZoneId setting. By default, it is the same as the time zone of the host system.

You can display multiple Time Rulers to show time in different time zones. The Time Ruler exposes two properties for the time zone support. Use the TimeRuler.TimeZone property to specify the time zone for which time is displayed. The TimeRuler.UseClientTimeZone property specifies that the time zone of the Time ruler follows the time zone of the Scheduler.

The SchedulerStorage maintains its data using the local machine time. When the AppointmentStorage.DateSaving property is set to DateSavingType.UTC, the database stores the time-relative data translated to UTC. This is to prevent possible discrepancies. The reminder alert time is processed similarly to the appointment time.

Let's see how it works. Consider a scheduler application with the following prerequisites:

1. A machine local Time Zone is set to Eastern Time (GMT -05:00)
2. The OptionsBehavior.ClientTimeZoneId property is set to Korean [Seoul] (GMT +09:00)
3. The AppointmentStorage.DateSaving property is set to DateSavingType.UTC

Action I

1. Set the local machine time to 06:00 AM
2. Note that the SchedulerControl current time is updated to 07:00 PM if DST in the Eastern Time zone is in effect, or to 08:00 PM if DST is not in effect. Currently, Korea does not observe daylight saving time.
3. Create a new appointment from 10:00 PM to 11:00 PM (three hours in advance), and then set a reminder to fire at 9:30 PM
4. Notice that the appointment start time is saved as 01:00 PM (UTC). However, internally (in the SchedulerStorage) the appointment start time is 09:00 AM

Action II

1. Adjust your local machine time to 08:30 AM (two and a half hours in advance)
2. Notice the SchedulerControl current time is updated to 09:30 PM
3. A Reminder window appears.

When the SchedulerStorage is used without its visual counterpart and you are subscribed to the SchedulerStorage.ReminderAlert event, the data is interpreted as UTC, provided that the corresponding flag remains set. Hence, the event fires at UTC time. For display purposes, you can easily convert the internal appointment start time in your code using client time zone settings. The DevExpress.XtraScheduler.TimeZoneHelper class provides the corresponding properties and methods.

The Scheduler supports "floating" time zone (time zone independent) all-day appointments. "Floating" means that their time is independent of the client time zone. Let's take a typical example of a "floating" all-day appointment - it is the New Year's Day. It starts at midnight January 1 in any time zone. Therefore, it does not start simultaneously throughout the world - it starts at different moments according to the time zone where the client is located.

If the AppointmentStorage.AllDayEventDateTimeMode is set to the AllDayEventDateTimeMode.Floating value, all-day appointments are treated as if they belong to a "floating" time zone.

However, to perform a centralized action (for example, to restart a server at a pilot factory, resulting in a break in connectivity between departments ), the appointment should occur only once, at a different time in each applicable time zone. In this case, a regular appointment is used, not a “floating” appointment.

NOTE

When you programmatically assign Appointment.Start and Appointment.End times to an appointment, do not create the DateTime object via the constructor that specifies the System.DateTimeKind enumeration value. Although it helps to indicate whether the DateTime object specifies a local time or UTC in .NET, XtraScheduler does not support this flag, and interprets the time incorrectly.