windowsforms-1753-controls-and-libraries-scheduler-appointments.md
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.
Depending on the Scheduler.AppointmentDisplayOptions.TimeDisplayType property value, start and end dates can be displayed as text strings or clock icons.
| |
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.
| |
|
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.).
| |
|
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 recurrence rules are stored in the Appointment.RecurrenceInfo property. Use it to access and modify rule settings. For example, you can modify the Start and End properties to change the series duration.
| |
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.
|
There are five appointment types available. The appointment type is stored in the Appointment.Type property.
Regular appointments (Type: 0)
Pattern (Type: 1)
Occurrences (Type: 2)
Changed Occurrence (Type: 3)
Deleted Occurrence (Type: 4)
Refer to the following help topic for more information on available recurrence types: Create Appointments with Various Recurrence Types.
Use the following ways to populate a SchedulerControl with appointments (the Scheduler control requires an associated SchedulerDataStorage):
Tip
AI-powered SmartPaste
SmartPaste allows you to create appointments in the WinForms Scheduler by pasting text content directly from the clipboard. SmartPaste recognizes common appointment-specific data (subject, dates, times, location, agenda) and fills corresponding fields in the Scheduler’s appointment editor.
SmartPaste can detect and configure the following settings:
See the following help topic for more information: Smart Paste AI-powered Extension.
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. |
To find required appointments in code, use the SchedulerDataStorage.GetAppointments method that returns all events that belong to the given time interval.
TimeInterval interval = new TimeInterval(new DateTime(2018, 12, 24), TimeSpan.FromDays(1));
Appointment target = schedulerControl.DataStorage.GetAppointments(interval)
.Find(x => x.Subject.Contains("Dinner"));
Dim interval As New TimeInterval(New Date(2018, 12, 24), TimeSpan.FromDays(1))
Dim target As Appointment = schedulerControl.DataStorage.GetAppointments(interval).Find(Function(x) x.Subject.Contains("Dinner"))
You can also use the AppointmentDataStorage.GetAppointmentById method if you know the appointment’s ID, or retrieve appointments directly from the storage.
//retrieve an appointment by its ID
Appointment appt1 = schedulerControl.DataStorage.Appointments.GetAppointmentById("PK_0021");
//retrieve an appointment by its index in the Appointments collection
Appointment appt2 = schedulerControl.DataStorage.Appointments[25];
'retrieve an appointment by its ID
Dim appt1 As Appointment = schedulerControl.DataStorage.Appointments.GetAppointmentById("PK_0021")
'retrieve an appointment by its index in the Appointments collection
Dim appt2 As Appointment = schedulerControl.DataStorage.Appointments(25)
For pattern appointments, call the Appointment.GetOccurrence method to retrieve the N-th occurrence in the series.
//find a today's appointment that has "meet" in its subject
Appointment todayAppt = schedulerControl.DataStorage.GetAppointments(new TimeInterval(DateTime.Now.Date, TimeSpan.FromDays(1)))
.Find(x => x.IsRecurring == true && x.Subject.Contains("meet"));
//retrieve this appointment's pattern, find its 3rd occurrence and remove it
if (todayAppt != null) schedulerControl.DeleteAppointment(todayAppt.RecurrencePattern.GetOccurrence(2));
//suppress the confirmation dialog that asks users whether this single occurrence or the entire series should be removed
SchedulerControl.DeleteRecurrentAppointmentFormShowing += SchedulerControl_DeleteRecurrentAppointmentFormShowing;
private void SchedulerControl_DeleteRecurrentAppointmentFormShowing(object sender, DeleteRecurrentAppointmentFormEventArgs e) {
e.Appointment.Delete();
e.Handled = true;
}
'find a today's appointment that has "meet" in its subject
Dim todayAppt As Appointment = schedulerControl.DataStorage.GetAppointments(New TimeInterval(Date.Now.Date, TimeSpan.FromDays(1))).Find(Function(x) x.IsRecurring = True AndAlso x.Subject.Contains("meet"))
'retrieve this appointment's pattern, get its 3rd occurrence and remove it
If todayAppt IsNot Nothing Then
schedulerControl.DeleteAppointment(todayAppt.RecurrencePattern.GetOccurrence(2))
End If
'suppress the confirmation dialog that asks users whether this single occurrence or the entire series should be removed
SchedulerControl.DeleteRecurrentAppointmentFormShowing += SchedulerControl_DeleteRecurrentAppointmentFormShowing
private void SchedulerControl_DeleteRecurrentAppointmentFormShowing(Object sender, DeleteRecurrentAppointmentFormEventArgs e)
e.Appointment.Delete()
e.Handled = True
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.
//find a today's recurring appointment labeled as "Vacation"
Appointment pattern = schedulerControl.DataStorage.GetAppointments(new TimeInterval(DateTime.Now.Date, TimeSpan.FromDays(1)))
.Find(x => x.IsOccurrence == true && (int)x.LabelKey == 4).RecurrencePattern;
//restore the recurring info for all appointments that belong to the same series
foreach (Appointment appt in pattern.GetExceptions()) appt.RestoreOccurrence();
'find a today's recurring appointment labeled as "Vacation"
Dim pattern As Appointment = schedulerControl.DataStorage.GetAppointments(New TimeInterval(Date.Now.Date, TimeSpan.FromDays(1))).Find(Function(x) x.IsOccurrence = True AndAlso CInt(Math.Truncate(x.LabelKey)) = 4).RecurrencePattern
'restore the recurring info for all appointments that belong to the same series
For Each appt As Appointment In pattern.GetExceptions()
appt.RestoreOccurrence()
Next appt
View Example: Obtain appointments by an object in the data source
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.
private void SchedulerControl_InitAppointmentDisplayText(object sender, AppointmentDisplayTextEventArgs e) {
SchedulerControl sc = sender as SchedulerControl;
if (sc.ActiveViewType == SchedulerViewType.FullWeek \|| sc.ActiveViewType == SchedulerViewType.Week) {
e.Text += Environment.NewLine + Environment.NewLine + e.Description;
e.Description = String.Empty;
}
}
Private Sub SchedulerControl_InitAppointmentDisplayText(ByVal sender As Object, ByVal e As AppointmentDisplayTextEventArgs)
Dim sc As SchedulerControl = TryCast(sender, SchedulerControl)
If sc.ActiveViewType = SchedulerViewType.FullWeek OrElse sc.ActiveViewType = SchedulerViewType.Week Then
e.Text += Environment.NewLine & Environment.NewLine & e.Description
e.Description = String.Empty
End If
End Sub
| |
SchedulerControl.CustomDrawAppointment
|
Grants access to paint methods that allow you to manually draw appointments.
| |
CustomDrawAppointmentBackground
|
Grants access to paint methods that allow you to manually draw appointment backgrounds.
| |
View.Appearance.Appointment.ForeColor
|
Specifies the appointment text color
| |
SchedulerControl.AppointmentViewInfoCustomizing
|
Enables you to customize visual parameters of Appointments like display text and Appearance settings. Refer to the following help topic for more information on how to customize the appearance of the entire application and/or individual UI elements: Application Appearance and Skin Colors.
|
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.
To limit the date range available to users, specify the LimitInterval property. Users are unable to browse dates outside this interval.
When an appointment is about to be modified, the Scheduler fires the following events. You can set the e.Cancel property to true to cancel these upcoming modifications.
If you do not cancel appointment edits and they are applied, the following events occur. Call required data source methods inside these events’ handlers to push modified appointment data to an underlying source.
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.
void SchedulerControl1_CustomAppointmentGroup(object sender, CustomAppointmentGroupEventArgs e) {
e.GroupKey = (int)e.AppointmentLayoutInfo.Appointment.LabelKey;
}
Private Sub SchedulerControl1_CustomAppointmentGroup(ByVal sender As Object, ByVal e As CustomAppointmentGroupEventArgs)
e.GroupKey = CInt(Math.Truncate(e.AppointmentLayoutInfo.Appointment.LabelKey))
End Sub
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:
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.
void SchedulerControl1_CustomAppointmentSort(object sender, CustomAppointmentSortEventArgs e) {
Appointment apt1 = e.AppointmentLayoutInfo1.Appointment;
Appointment apt2 = e.AppointmentLayoutInfo2.Appointment;
//compare by statuses
e.Result = ((int)apt1.StatusKey).CompareTo((int)apt2.StatusKey);
if (e.Result != 0)
return;
//if statuses are the same, compare by dates
e.Result = apt1.Start.CompareTo(apt2.Start);
if (e.Result != 0)
return;
e.Result = -apt1.End.CompareTo(apt2.End);
}
Private Sub SchedulerControl1_CustomAppointmentSort(ByVal sender As Object, ByVal e As CustomAppointmentSortEventArgs)
Dim apt1 As Appointment = e.AppointmentLayoutInfo1.Appointment
Dim apt2 As Appointment = e.AppointmentLayoutInfo2.Appointment
'compare by statuses
e.Result = CInt(Math.Truncate(apt1.StatusKey)).CompareTo(CInt(Math.Truncate(apt2.StatusKey)))
If e.Result <> 0 Then
Return
End If
'if statuses are the same, compare by dates
e.Result = apt1.Start.CompareTo(apt2.Start)
If e.Result <> 0 Then
Return
End If
e.Result = -apt1.End.CompareTo(apt2.End)
End Sub
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.