[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
  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]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Collapse]Scheduler
   [Expand]Product Information
    Getting Started
   [Expand]Scheduler Elements and Structure
   [Expand]Data Binding
   [Collapse]Appointments
     Appointment Labels and Statuses
     Reminders for Appointments
     Resources for Appointments
   [Expand]Views
   [Expand]Import and Export
    Printing
   [Expand]Reports
   [Expand]Time Zones
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
   [Expand]Services
   [Expand]Member Tables
   [Expand]Visual Elements
   [Expand]Examples
  [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]Sunburst 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]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Appointments

Expanded Basic Appointment Information

Scheduler appointments are objects of the Appointment class. Appointments store the following data:

Stored Data

Description

Start and end dates

DateTime values assigned to the Appointment.Start and Appointment.End properties. When you bind a Scheduler Control to a data source, these two mappings are mandatory. Ignored if the Appointment.AllDay property equals true.

Title and description

String values stored in the Appointment.Subject and Appointment.Description properties.

Location

String Appointment.Location property value displayed beneath the appointment subject.

Label

An object assigned to the Appointment.LabelKey property that specifies the appointment color and the related name (i.e., "Important" for red, "Business" for blue, etc.).

Status

An appointment status ("Free", "Tentative", "Out Of Office", etc.) represented as a thin stripe along an appointment edge. Assigned to the Appointment.StatusKey property.

Resource that owns this appointment

Stored as an ID in the Appointment.ResourceId property.

Important

If you do not plan on using resources, make sure the AppointmentMappingInfo.ResourceId mapping is empty when you bind the Scheduler to an appointment data source.

Appointment Time Zone

Specified by a string ID stored in the Appointment.TimeZoneId property. The Scheduler automatically adjusts appointments whose start and end dates are recorded in a time zone different from the current time zone. All-day appointments ignore time zones.

Related reminders

Reminders notify users when an appointment is about to occur. Stored in the Appointment.Reminders collection.

Recurrence data

Recurring appointments are appointments that occur more than once. Their occurrence rules are stored in the Appointment.RecurrenceInfo, Appointment.OriginalOccurrenceStart, and Appointment.OriginalOccurrenceEnd properties.

Custom data

Appointments can store data from data source fields that are not used by the Scheduler itself. To do this, modify the IAppointmentStorageBase.CustomFieldMappings collection to map the required data fields to custom appointment fields. Handle the SchedulerControl.InitAppointmentDisplayText to manually draw custom field data on appointment surfaces.

Expanded Appointment Types

There are five appointment types available. The appointment type is stored in the Appointment.Type property.

  • Regular appointments (Type: 0)

    Appointments that last for the specific period of time and never occur again.

  • Pattern (Type: 1)

    Stores the rule according to which visible (to users) recurring appointments are generated. Patterns themselves are not visible and stored in the SchedulerDataStorage.Appointments collection.

  • Occurrences (Type: 2)

    All appointments in a series, visible to users "clones" of a pattern appointment. Occurrences are not kept in the SchedulerDataStorage.Appointments collection. To access appointments with this type, call the Appointment.GetOccurrence method for a pattern, or call the ISchedulerStorageBase.GetAppointments method, which returns all visible appointments for a given time interval.

  • Changed Occurrence (Type: 3)

    A former series member (occurrence) whose data has been modified. Changed occurrences are marked with a crossed-out occurrence icon.

    These appointments can be accessed directly through the SchedulerDataStorage.Appointments collection.

    Call the Appointment.RestoreOccurrence method to reset changed occurence data and make it a regular occurence again.

  • Deleted Occurrence (Type: 4)

    A regular or edited occurrence that has been removed while the rest of the series still exists. Stored within the SchedulerDataStorage.Appointments collection.

Expanded Create Appointments

There are three ways to populate a SchedulerControl with appointments. Note that regardless of the approach you choose, the SchedulerControl requires an associated storage (the SchedulerDataStorage component).

  • Load appointments from a data source - see the Getting Started article for an example, and the Data Binding documentation section for more information.
  • Import appointments from an existing calendar (iCalendar, Google Calendar, etc.) - see Import and Export for a list of supported calendars.
  • Add unbound appointments in code - call methods listed in the table below.

Methods that add regular appointments

Method Additional Information
SchedulerControl.CreateNewAppointment Creates a completely blank appointment, and opens an Appointment Edit Form (see the "Edit Appointments" section below) to edit this appointment.
SchedulerControl.CreateAppointment Creates an empty appointment, and opens an Appointment Edit Form to edit this appointment. Allows you to create appointments that last for an entire day (or multiple days), and appointments that occur repeatedly
SchedulerDataStorage.CreateAppointment Five overloads accessible through the "<_schedulerControl_name>.DataStorage" property. Allow you to specify appointment start and end dates, duration, type, and subject.
AppointmentDataStorage.CreateAppointment Same overloads as above. Accessible through "<_schedulerControl_name>.DataStorage.Appointments".

Other methods that add appointments

Method Additional Information
SchedulerControl.CreateNewAllDayEvent Creates an appointment that lasts for one or multiple days.
SchedulerControl.CreateNewRecurringEvent Creates an appointment that lasts for one or multiple days, and occurs more than once.
SchedulerControl.CreateNewRecurringAppointment Creates an appointment that occurs more than once.
Appointment.CreateException Allows you to add, modify and remove occurrences in an existing series.

Expanded Locate Appointments

To find required appointments in code, use the SchedulerDataStorage.GetAppointments method that returns all events that belong to the given time interval.

You can also use the AppointmentDataStorage.GetAppointmentById method if you know the appointment's ID, or retrieve appointments directly from the storage.

For pattern appointments, call the Appointment.GetOccurrence method to retrieve the N-th occurrence in the series.

You can also call the Appointment.GetExceptions method to retrieve all changed occurrences in a series. To reset their changes and make them regular series appointments again, call the Appointment.RestoreOccurrence method.

Expanded Additional Settings and Custom Appointment Content

Scheduler Views provide multiple options that allow you to customize appointment layout and display options.

API

Description

View.AppointmentDisplayOptions

Returns the AppointmentDisplayOptions object that provides access to appointment display settings. For instance, the AppointmentDisplayOptions.ShowRecurrence setting allows you to hide the recurrence icon.

AppointmentDisplayOptions.SnapToCellsMode

Allows you to stretch appointments along the View time ruler so that they occupy one or multiple cells entirely.

MonthViewAppointmentDisplayOptionsEx.StretchAppointments

TimelineViewAppointmentDisplayOptionsEx.StretchAppointments

Specify whether appointments in Month and Timeline Views should stretch vertically to occupy entire time cells.

SchedulerOptionsCustomization.AllowAppointmentConflicts

Specifies if appointments can be scheduled at intersecting time intervals. If set to Custom, the SchedulerControl.AllowAppointmentConflicts event raises. You can handle this event to manually decide which appointments can occur simultaneously.

SchedulerControl.InitAppointmentDisplayText

SchedulerControl.InitAppointmentImages

Allow you to display custom images and/or text strings within appointments. For instance, the code below removes a separator line drawn between appointment subject and description.

SchedulerControl.CustomDrawAppointment

Grants access to paint methods that allow you to manually draw appointments.

Expanded User Restrictions

The SchedulerControl.OptionsCustomization property provides access to a set of AllowAppointment... properties that prevent users from adding new and\or modifying existing appointments.

If you set any of these settings to UsedAppointmentType.Custom, the Scheduler will fire related AllowAppointment... events. These events allow you to manually decide whether to allow or cancel a user action every time it takes place.

Expanded Group and Sort Appointments

The SchedulerControl.CustomAppointmentGroup event allows you to split appointments into groups. This event fires repeatedly for every encountered appointment; read the e.AppointmentLayoutInfo event parameter to obtain the information about the currently processed appointment, and assign the group index to the integer e.GroupIndex property. In the Timeline View module of the Scheduler Demo (available in DevExpress Demo Center), appointments are grouped by their Labels.

To sort appointments, handle SchedulerControl.CustomAppointmentSort event. This event compares appointment pairs. The e.AppointmentLayoutInfo1 and e.AppointmentLayoutInfo2 event parameters store information about both appointments. Read these parameters to compare objects, and set the integer e.Result property to one of the following values:

  • -1 if the appointment related to the e.AppointmentLayoutInfo1 parameter should go first;
  • 1 if the appointment related to the e.AppointmentLayoutInfo2 parameter should go first;
  • 0 if appointments are considered equal, and should be positioned according to default View layout rules.

The Timeline View demo module illustrates how to sort appointments by their Statuses: appointments with the "Out of Office" status are placed after appointments with no statuses. Note that you can sort appointments regardless of whether they have been grouped or not.

Expanded Block Time Cells

The Scheduler allows users to create appointments in any time cells (including intersecting appointments; see the SchedulerControl.AllowAppointmentConflicts event). You can block specific time cells, so that users are unable to add appointments to these cells, or modify appointments that are already there. For instance, you can disable lunch hours or days off.

To do that, you need to create time regions. See the TimeRegion class to learn more.

Is this topic helpful?​​​​​​​