Time Zones

• Mar 12, 2021
• 4 minutes to read

The SchedulerControl allows you to define the time zone information to display the appointment start and end time correctly.

The sections below describe the Scheduler time zone implementation in greater detail:

• Scheduler Time Zone
• Appointment Time Zone
• Managing Time Zones in the User Interface

Scheduler Time Zone

Specify the SchedulerControl.TimeZone property to define which time zone the Scheduler uses when displaying appointments. This property is set to the host machine’s time zone (or TimeZoneInfo.Id.Local) by default. The SchedulerControl uses the standard .NET Framework TimeZoneInfo objects to specify the time zone information. The System.TimeZoneInfo class does not expose a public constructor, but you can access the desired time zone using its index or name. Refer to the Microsoft Time Zone Index Values topic for the full list of available time zones.

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

<dxsch:Scheduler x:Name="scheduler" 
                 ActiveViewIndex="0" 
                 FirstDayOfWeek="Monday" 
                 GroupType="Resource" 
                 TimeZone="Pacific Standard Time">
</dxsch:Scheduler>

Daylight Saving Time (DST)

The System.TimeZoneInfo objects include information about daylight saving adjustments where applicable, so if the scheduler’s SchedulerControl.TimeZone property is set to the client’s region it 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

Use the AppointmentItem.TimeZoneId property to specify a particular appointment‘s time zone. When displaying, When an appointment is displayed, the Scheduler recalculates appointments to its time zone considering the TimeZoneId property value.

Reminder alert times are triggered using the Scheduler’s time zone as well.

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

When appointments with different time zones are saved to the data source, their DateTime values cannot be converted correctly compared independently without the time zone information. Use the DataSource.DateTimeSavingMode property to define what time zone information to use when saving the appointments to the data source.

All-Day Appointments

All-day appointments (appointments with the AppointmentItem.AllDay property set to true) are always treated like 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 the New Year’s Day. It 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.

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

Time Zones in the User Interface

Specify the AppointmentMappings.TimeZoneId mapping to enable end-users to change the appointment’s time zone and enable the Time Zones button on the Edit Appointment form. Clicking the Time Zones button invokes a drop-down list of available time zones.

Recurring appointments’ time zone is specified in the Appointment Recurrence form. The time zone editor is disabled on the appointment form and enabled in the recurrence dialog when a recurrence is selected:

Time Rulers

Add multiple TimeRuler instances to distinguish between different time zones. Time rulers can be added 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>

End-users can change the time ruler caption (TimeRuler.Caption) and displayed time zone (TimeRuler.TimeZone) using the Time Ruler dialog. Right-click the target time ruler and select Customize Time Ruler… in the context menu to invoke the dialog:

Tip

Use the DayViewBase.TimeRulersSource and DayViewBase.TimeRulerTemplate properties to provide the Scheduler with custom time rulers.

TimeZoneEdit

The TimeZoneEdit control is a combo box that displays a list of the available time zones. You 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}"/>