Time Zones

• May 19, 2021
• 5 minutes to read

The SchedulerControl converts appointment start and end time to the specified time zone.

Scheduler Time Zone

Specify the SchedulerControl.TimeZone property to define the time zone the Scheduler uses to display appointments. When this property is set to null, the Scheduler uses the time zone of the host machine (the computer where the code is executed). This time zone is identified by the TimeZoneInfo.Local property. To find out the time zone with which the Scheduler currently operates, use the SchedulerControl.ActualTimeZone property.

The SchedulerControl uses the standard .NET Framework System.TimeZoneInfo objects to specify the time zone information. The System.TimeZoneInfo class does not expose a public constructor, but you can use the System.TimeZoneInfo.FindSystemTimeZoneById method to access the desired time zone by its identifier. Refer to the following topic for the full list of available time zones: Microsoft Time Zone Index Values.

Note

The Scheduler cannot read the TimeZoneInfo instances created using the CreateCustomTimeZone method.

The code sample below shows how to specify the Scheduler’s time zone in XAML:

XAML

<!--The "Pacific Standard Time" string value
identifies the (GMT-08:00) Pacific Time (US and Canada) time zone-->
<dxsch:Scheduler x:Name="scheduler" 
                 TimeZone="Pacific Standard Time"
                 ActiveViewIndex="0" 
                 FirstDayOfWeek="Monday" 
                 GroupType="Resource" 
                 >
</dxsch:Scheduler>

Daylight Saving Time (DST)

The System.TimeZoneInfo objects include information about daylight saving adjustments where applicable. If the scheduler’s SchedulerControl.TimeZone property is set to the client’s region, the scheduler always displays the correct time.

Both recurring and non-recurring appointments’ start and end times are adjusted according to Daylight Saving Time. Scheduler Views do not allow discontinuous time scales, so if the appointment interval spans a DST change, its visual appearance is based on UTC.

Appointment Time Zone

You can specify a particular appointment‘s time zone. Set the SchedulerItemBase.TimeZoneId property to the time zone identifier.

The Scheduler displays time values converted to the current time zone. The SchedulerControl.ActualTimeZone property value identifies the Scheduler’s time zone.

The image below illustrates an appointment created in the (GMT-06:00) Central Time (US and Canada) time zone. The appointment is displayed relative to the following time zones:

• GMT (GMT) Greenwich Mean Time: Dublin, Edinburgh, Lisbon, London
• Local (GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna

The two hour time difference is due to active daylight saving time offset.

When a user creates an appointment, the TimeZoneId is set to the SchedulerControl.ActualTimeZone.Id property value.

If a recurring appointment is converted to another time zone, the Scheduler recalculates the whole sequence according to the new time zone information.

The Scheduler converts the reminder alert times to the Scheduler’s current time zone.

All-Day Appointments

An all-day appointment is an appointment with the SchedulerItemBase.AllDay property set to true. The Scheduler calculates all-day appointments as if they belong to a “floating” time zone. “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. New Year’s Day starts at midnight on January 1st in any time zone, but it does not start simultaneously throughout the world - it starts at different times, according to the client’s time zone.

When an appointment should occur simultaneously across different time zones, use a regular appointment instead of an all-day one.

Data Source Time Zone

When a user creates an appointment, the appointment’s TimeZoneId value corresponds to the SchedulerControl.ActualTimeZone.Id property value. Use the DataSource.DateTimeSavingMode property to define what time zone information to use when saving the appointments to the data source:

DateTimeSavingMode	Time Zone
Appointment	TimeZoneId of each individual appointment
Storage	DataSource.TimeZone
Utc	UTC time zone

Time Zones in the User Interface

Specify the SchedulerItemBaseMappings.TimeZoneId mapping to allow users to change the time zone of appointments. Users can click the Time Zones button on the Edit Appointment form to invoke a drop-down list of available time zones.

Users can specify the time zone for recurring appointments in the Appointment Recurrence form. The time zone editor is disabled on the appointment form and enabled in the recurrence dialog when the user selects a recurrence:

Time Rulers

Add multiple TimeRuler instances to distinguish between different time zones. You can add time rulers for Day View, Work Week View and Week View. The code sample below shows how to add a new time ruler to the Day View:

XAML

<dxsch:DayView.TimeRulers>
    <dxsch:TimeRuler Caption="LA Time"
                    ShowMinutes="False"
                    TimeZone="Pacific Standard Time"/>
</dxsch:DayView.TimeRulers>

Users can change the time ruler caption (TimeRuler.Caption) and displayed time zone (TimeRuler.TimeZone) using the Time Ruler dialog. To invoke the dialog, users can right-click the target time ruler and select Customize Time Ruler…:

Tip

To add custom time rulers, use the DayViewBase.TimeRulersSource and DayViewBase.TimeRulerTemplate properties.

TimeZoneEdit

The TimeZoneEdit control is a combo box that displays a list of available time zones. Users can use this editor to set the Scheduler control’s SchedulerControl.TimeZone property value, or to display different time zones in scheduler time rulers. The code sample below shows how to bind the TimeZoneEdit to the TimeRuler:

XAML

<dxsch:TimeZoneEdit x:Name="timeZoneEdit" EditValue="{Binding ElementName=timeRuler1,
    Path=TimeZone, UpdateSourceTrigger=PropertyChanged, Mode=TwoWay}"/>