What Is an Appointment
- 4 minutes to read
Note
You are viewing documentation for the legacy WPF Scheduler control. If you’re starting a new project, we strongly recommend that you use a new control declared in the DevExpress.Xpf.Scheduling namespace. If you decide to upgrade an existing project in order to switch to the updated scheduler control, see the Migration Guidelines document.
This document introduces the Appointment concept, describes the types of appointments and their interaction with the Appointment Storage:
Appointment Overview
An appointment represents a time interval and the end-user activity scheduled for this time interval. An activity is characterized by its subject, location, indicators (labels and statuses), and description. Any number of custom properties can also be defined for an appointment. Appointments can be recurring, which means that an activity can be scheduled for repetitive time intervals.
A single appointment is an object which exposes the Appointment inteface. What an appointment looks like depends upon the active View, which is used to show the Scheduler’s data. The picture below illustrates an appointment viewed using the Day View of a Scheduler control.
Appointments are stored in the AppointmentStorage, which is part of the Scheduler Storage and can be accessed via the SchedulerStorage.AppointmentStorage property. The collection of all appointments is accessible via the AppointmentStorage.Items property.
The Appointment Storage allows the appointment data to persist in a data source, and appointments to be assigned to particular resources.
Types of Appointments
Every appointment is of a particular type, which can be accessed via its Appointment.Type property. For example, a simple non-recurring appointment’s type is AppointmentType.Normal. All appointment types are listed by the AppointmentType enumeration’s members.
The following diagram illustrates the difference between recurring and non-recurring appointment types.
To learn more about recurring appointments and their types, see the Recurring Appointments and Exceptions document.
Manage Appointments
Create Appointments
To create an appointment in code, use the SchedulerStorage.CreateAppointment method. This method creates an appointment with default attribute settings and custom fields. You should specify them via code, and add an appointment to the AppointmentStorage using the AppointmentStorage.Add method. To get an example on how to programmatically create recurring appointments with different periodicity and number of occurrences, refer to How to: Create Appointments with Various Recurrence Types Programmatically (legacy).
To specify default appointment properties which should be applied to all newly created appointments, handle the SchedulerControl.InitNewAppointment event. To get an example of using this event, see the How to: Set Default Values for a New Appointment (legacy) document.
Modify Appointments
To control the changes applied to the appointment, use the SchedulerStorage.AppointmentChanging event, which is fired before the changed appointment is saved to the storage, and the SchedulerStorage.AppointmentsChanged and SchedulerStorage.AppointmentsInserted events raised after modifications are applied.
An appointment’s attributes can be changed via the corresponding Appointment properties. Custom properties are accessible via the PersistentObject.CustomFields property using index notation.
To change the data record in the underlying data source that corresponds to the Appointment object, use the IPersistentObject.GetSourceObject method. An explicit cast is required for the returned object (e.g. to the DataRowView or XPBaseObject).
Selected appointments are contained within the SchedulerControl.SelectedAppointments collection. To track the selection changes, you can subscribe to the NotificationCollection<T>.CollectionChanged event. The How to: Obtain the Selected Appointments (legacy) document demonstrates how to get access to the selected appointments.
Delete Appointments
Non-recurring appointments can be deleted without confirmation, so handle the SchedulerStorage.AppointmentDeleting event to prevent accidental deletion.
To delete an appointment in code, use the PersistentObject.Delete method.
Before the actual deletion is accomplished, the SchedulerStorage.AppointmentDeleting event is raised for each object being deleted. You can handle the event to specify the desired disposition of each appointment. After an appointment is deleted, the SchedulerStorage.AppointmentsDeleted event occurs.
Display Appointments
To change the visual representation of appointments, you can use custom templates. To get an example on how to apply a template that defines appointment appearance, see How to: Apply a Custom Template to Vertical Appointments in the Day or Work-Week View (legacy).
End-User Restrictions
By default, all appointment operations (copying, deleting, dragging, etc.) are enabled for end-users. But in some cases, it may be necessary to prevent end-users from modifying appointments shown within the Scheduler Control.
You can restrict certain appointment operations using the set of properties (named AlowAppointment*) of the OptionsCustomization object accessed via SchedulerControl.OptionsCustomization. The UsedAppointmentType enumeration’s members are used by the OptionsCustomization.AlowAppointment* properties to specify the types of appointments that can be used in end-user restrictions.
If you set one of the OptionsCustomization.Allow* properties to UsedAppointmentType.Custom, a related SchedulerControl.Allow* event will fire, in which you can decide how to handle a particular case.
For example, to restrict appointment creation, the OptionsCustomization.AllowAppointmentDelete property and SchedulerControl.AllowAppointmentDelete event can be used.
For more information, see the How to: Set End-User Restrictions (legacy) document.