Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Collapse]Scheduler
   [Expand]Product Information
   [Expand]Getting Started
   [Collapse]Fundamentals
    [Expand]Scheduler Elements
    [Expand]Scheduler Structure
    [Expand]Appointments
     Resources for Appointments
    [Expand]Views
     Pop-up Menus
    [Expand]Data Binding
    [Expand]Mappings
    [Expand]Supported Formats
    [Expand]Services
    [Collapse]Time Zones
      Scheduler Time Zones
      Appointment Time Zones
     Printing
    [Expand]Scheduler Reporting
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End-User Capabilities
   [Expand]Member Tables
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Appointment Time Zones

Expanded Time Zone Support

The Scheduler allows you to select the time zone of an appointment and store it in the Appointment.TimeZoneId property. To switch on time zone support, set the SchedulerStorageBase.EnableTimeZones property to true and provide mapping of the Appointment.TimeZoneId property to a data field.

When time zones for appointment are enabled, the default appointment editing form displays the Time Zone button.

You can click the button to display the time zone editor (an instance of the TimeZoneEdit class), which allows you to select a time zone. If the button is not pressed, the time zone of the appointment equals the SchedulerOptionsBehaviorBase.ClientTimeZoneId property value.

Expanded An Example of Appointment Data

Consider the following scenario.

The Scheduler Storage is located in Los-Angeles (Pacific Time, UTC-08). By default, the SchedulerStorageBase.TimeZoneId equals the host time zone. So, it has the value "Pacific Standard Time".

The client application that employs the SchedulerControl runs in New York City (Eastern Time, UTC-04). By default, the SchedulerOptionsBehaviorBase.ClientTimeZoneId equals the time zone in which the application operates. So, it has the value "Eastern Standard Time".

A recurring appointment is created on March,1 (when no DST shift occurs) at 1AM with one hour duration and a weekly recurrence rule according to which an appointment in a series is repeated each Tuesday and ends after 10 occurrences.

The appointment record has the following fields.

Field

Value

Start 3/1/2016 1:00:00
End 3/1/2016 2:00:00
TimeZoneId Eastern Standard Time
RecurrenceInfo <RecurrenceInfo Start="03/01/2016 01:00:00" End="05/03/2016 01:00:00" WeekDays="4" Id="0077a5f2-775f-4984-8ecd-6736c46bbb93" Range="1" Type="1" FirstDayOfWeek="0" Version="1" />

Expanded DateTime Saving Mode

The datetime value listed in the appointment record is the same as the time of the appointment displayed in the Eastern Standard Time zone. An appointment saved from clients with different time zones will have Start and End times that cannot be compared independently without the time zone information. This is the default behavior that is specified by the SchedulerStorageBase.DateTimeSavingMode set to the DateTimeSavingMode.Appointment value.

However, you can "normalize" the Start and End times to make them comparable for clients in different time zones. This will help you in make your data queries more effective. If you set the SchedulerStorageBase.DateTimeSavingMode to the DateTimeSavingMode.Storage value, the dates are converted to the Storage time zone and subsequently written to the data record. Thus, all datetime values will be in the same time zone and can be easily compared. The following table is an appointment data record created after the Storage datetime saving mode is switched on.

Field

Value

Start 2/29/2016 22:00:00
End 2/29/2016 23:00:00
TimeZoneId Eastern Standard Time
RecurrenceInfo <RecurrenceInfo Start="02/29/2016 22:00:00" End="05/02/2016 22:00:00" WeekDays="4" Id="0077a5f2-775f-4984-8ecd-6736c46bbb93" Range="1" Type="1" FirstDayOfWeek="0" Version="1" />

This data record can be interpreted correctly only if the following conditions are met.,

Important

A Storage in default ("Appointment") datetime saving mode assumes that the datetime values are for the time zone specified in the TimeZoneId field of an appointment, i.e., Eastern Standard Time in our example, and will display them converted from Eastern time to the Storage time zone. Therefore, the data will be displayed incorrectly. Thus, you should not switch from one mode to another when working with the same data table.

Expanded Time Zones and Recurring Appointments

When you are working with recurring appointments, you have to set the time zone in the recurrence dialog, not on the appointment form.

When you click the Time Zone button, the time zone editor is displayed on the appointment form. However, if you have recurrence selected, the time zone editor is disabled on the appointment form and enabled in the recurrence dialog.

Time Zone support should be enabled when working with recurring appointments. If time zones are disabled, the recurring series is calculated using the Storage time zone. This may result in a behavior that confuses the end-user, as illustrated in the following scenario.

Suppose you have the Storage and SchedulerControl client application with time zones set as mentioned in the beginning of this article. However, TimeZone mapping is null or the SchedulerStorageBase.EnableTimeZones property is set to false, so an appointment does not have a time zone. Invoke a recurrence editing form and create a recurring appointment on March,1 (when no DST shift occurs) at 1AM with a one-hour duration and a weekly recurrence rule. You may notice that when the form is displayed, the Monday check box on the form is checked instead of Tuesday. But the March, 1 is Tuesday, so you check Tuesday instead, close the form and save changes. Now, take a closer look at the created appointment in the Scheduler view.

The recurring appointment is shown every Wednesday, instead of Tuesday. Its recurrence form shows the Tuesday weekly rule. The reason is that in the Pacific Time Zone, the recurrence pattern starts on 2/29/2016 22:00:00, which is Monday. The recurrence engine finds the first Tuesday, which is 3/1/2016 22:00:00, and calculates the client appointment Start time for display by using a conversion from Pacific to Eastern resulting in 3/2/2016 01:00:00 time which is Wednesday.

The appointment data record is shown below.

Field

Value

Start 2/29/2016 22:00:00
End 2/29/2016 23:00:00
TimeZoneId
RecurrenceInfo <RecurrenceInfo Start="02/29/2016 22:00:00" End="05/03/2016 22:00:00" WeekDays="4" Id="0077a5f2-775f-4984-8ecd-6736c46bbb93" Range="1" Type="1" FirstDayOfWeek="0" Version="1" />

How would you rate this topic?​​​​​​​