Appointment
- 5 minutes to read
This document introduces the Appointment concept, and describes the types of appointments and their interaction with the Appointment Storage.
Appointment Overview
An appointment represents a time interval and the end-user’s activity scheduled for that time interval. An activity is characterized by its subject, location, indicators (status and labels), 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 time intervals that repeat.
A single appointment is an object which implements the Appointment interface. The appearance of an appointment depends on the active View, which is used to display Scheduler data. The image below illustrates an appointment viewed using the Day View of a Scheduler control.
Appointments are stored in the AppointmentStorage, which is a part of the Scheduler Storage and can be accessed via the SchedulerStorage.Appointments property. The collection of all appointments is accessible via the AppointmentStorageBase.Items property.
The Appointment Storage allows appointment data to persist in the data source and control the assignment of resources. See the Scheduler Storage and Assigning Appointments to Resources topics to learn more on how to do this.
Types of Appointments
Each appointment is of a particular type, which can be accessed via its Appointment.Type property. For example, a simple non-recurring appointment type is AppointmentType.Normal. All appointment types are listed by the AppointmentType enumeration 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.
Appointment Categories
Appointments can be identified with Labels and Statuses. To extend appointment classification and enable tracking by different criteria, you can store additional information in appointment’s custom fields. To start using the custom fields, review the How to: Create Appointments with Custom Fields document.
Creating Appointments
Appointments can be created by the end-user via keyboard or mouse input, as described in the Create Appointments topic. The actions available to the user can be restricted by specifying the SchedulerControl.OptionsCustomization setting.
| Method | Description |
|---|---|
| SchedulerControl.CreateAppointment | Invokes the dialog for editing a newly created appointment. Allows you to initialize the editors as the Appointment.AllDay option suggests and show the Appointment Recurrence Form for a recurring appointment. |
| SchedulerStorageBase.CreateAppointment | Creates an appointment of the specified type. A newly created appointment should be added to the SchedulerStorage.Appointments storage using the AppointmentStorageBase.Add method. |
| SchedulerControl.CreateNewAppointment | Invokes the dialog for editing a newly created appointment. |
| SchedulerControl.CreateNewAllDayEvent | Invokes the dialog for editing a newly created all-day appointment. |
| SchedulerControl.CreateNewRecurringAppointment | Invokes the dialog for editing a newly created appointment and a child dialog for editing the recurrence information. |
| SchedulerControl.CreateNewRecurringEvent | Invokes the dialog for editing a newly created all-day appointment and a child dialog for editing the recurrence information. |
To specify the default appointment properties that should be applied to all newly created appointments, handle the SchedulerControl.InitNewAppointment event.
Modifying Appointments
End-users can modify appointments as described in the Edit Appointments topic.
End-user capabilities for appointment modifications can be restricted by specifying the corresponding properties of the SchedulerOptionsCustomization class.
To control the changes applied to the appointment, you should use the SchedulerStorageBase.AppointmentChanging event, which is fired before the changed appointment is saved to the storage, and the SchedulerStorageBase.AppointmentsChanged and SchedulerStorageBase.AppointmentsInserted events, raised after modifications, are applied.
Appointment attributes can be changed via the corresponding properties of the Appointment interface. 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.
Deleting Appointments
End-users can delete appointments as described in the Delete Appointments document. Note that non-recurring appointments are deleted without confirmation, so you should handle the SchedulerStorageBase.AppointmentDeleting event to prevent accidental deletion.
To delete an appointment in code, use either the PersistentObject.Delete or SchedulerControl.DeleteAppointment methods. To delete currently selected appointments, use the SchedulerControl.DeleteSelectedAppointments method.
Before an appointment is actually deleted, the SchedulerStorageBase.AppointmentDeleting event is raised for each object being deleted. You can handle the event to decide about a specific appointment. After an appointment is deleted, the SchedulerStorageBase.AppointmentsDeleted event occurs.
Displaying Appointments
You can change the text displayed within the appointment via the SchedulerControl.InitAppointmentDisplayText event and images via the SchedulerControl.InitAppointmentImages event. The SchedulerControl.AppointmentViewInfoCustomizing event enables you to modify appointment style elements.
The appointment rectangle and its background can be drawn manually in the SchedulerControl.CustomDrawAppointment and SchedulerControl.CustomDrawAppointmentBackground event handlers respectively.
The standard appointment editing form is invoked by the SchedulerControl.ShowEditAppointmentForm method. Use the SchedulerControl.EditAppointmentFormShowing event to substitute a default form with your own.
User Restrictions
You can restrict certain appointment operations via a set of properties and events called AllowAppointment*, which include the SchedulerOptionsCustomization.AllowAppointmentDelete property and the SchedulerControl.AllowAppointmentDelete event. The corresponding event (e.g., the SchedulerControl.AllowAppointmentDelete event) is fired only if the corresponding option (the SchedulerOptionsCustomization.AllowAppointmentDelete property) is set to the UsedAppointmentType.Custom value. All AllowAppointment* events behave the same way. For more information, refer to the How to: Prevent End-Users from Editing Appointments.