SchedulerControl.InitAppointmentImages Event

Enables custom images to be displayed within appointments.

Namespace: DevExpress.XtraScheduler

Assembly: DevExpress.XtraScheduler.v24.1.dll

NuGet Package: DevExpress.Win.Scheduler

Declaration

C#

public event AppointmentImagesEventHandler InitAppointmentImages

VB.NET

Public Event InitAppointmentImages As AppointmentImagesEventHandler

Event Data

The InitAppointmentImages event's data class is AppointmentImagesEventArgs. The following properties provide information specific to this event:

Property	Description
Appointment	Provides access to the appointment for which the SchedulerControl.InitAppointmentImages event is fired.
ImageInfoList	Gets a collection of AppointmentImageInfo objects.
ViewInfo	Provides access to the characteristics of the appointment prepared for display.

Remarks

The InitAppointmentImages event occurs before an appointment is painted when its images are initialized. This event lets you display custom images within appointments. The event parameter’s AppointmentEventArgs.Appointment property allows the currently processed appointment to be identified. The AppointmentImagesEventArgs.ImageInfoList property specifies the images to be displayed within the appointment.

Scheduler layout calculation is split into several threads to improve the scheduler performance. The InitAppointmentImages event could be raised from a thread other than the thread where the SchedulerControl instance has been created. Accessing the SchedulerControl (SchedulerStorage) instance directly in the InitAppointmentImages event when the SchedulerOptionsBehavior.UseAsyncMode property is true may result in “cross-thread” exceptions.

Important

Do not modify appointment properties, and do not add or remove appointments within this event handler. An attempt to do so may result in an unhandled exception. Also, if the UseAsyncMode property is enabled, the InitAppointmentImages event raises in the non-UI thread. In this case, performing non-thread-safe operations may cause a deadlock.

To avoid the “cross-thread” issues, do not access the SchedulerControl or SchedulerStorage instance in the event handler. In most common scenarios, the SchedulerControl or SchedulerStorage instances are used to obtain the content of the underlying source object. In this situation you have to store all the required information within the current appointment instance so that accessing the source object becomes unnecessary. A recommended solution is mapping the required data field to a custom appointment property.

Images for the InitAppointmentImages event handler are provided by specifying appointment mappings:

View Example

Form1.cs

private void InitAppointments() {
    AppointmentMappingInfo mappings = this.schedulerStorage1.Appointments.Mappings;
    mappings.Start = "StartTime";
    mappings.End = "EndTime";
    mappings.Subject = "Subject";
    mappings.AllDay = "AllDay";
    mappings.Description = "Description";
    mappings.Label = "Label";
    mappings.Location = "Location";
    mappings.RecurrenceInfo = "RecurrenceInfo";
    mappings.ReminderInfo = "ReminderInfo";
    mappings.ResourceId = "OwnerId";
    mappings.Status = "Status";
    mappings.Type = "EventType";            

    schedulerStorage1.Appointments.CustomFieldMappings.Add(new AppointmentCustomFieldMapping("ApptImage1", "Icon1", FieldValueType.Object));
    schedulerStorage1.Appointments.CustomFieldMappings.Add(new AppointmentCustomFieldMapping("ApptImage2", "Icon2", FieldValueType.Object));
    schedulerStorage1.Appointments.CustomFieldMappings.Add(new AppointmentCustomFieldMapping("ApptAddInfo", "AdditionalInfo", FieldValueType.String));

    GenerateEvents(CustomEventList, 3);
}

Form1.vb

Private Sub InitAppointments()
    Dim mappings As AppointmentMappingInfo = Me.schedulerStorage1.Appointments.Mappings
    mappings.Start = "StartTime"
    mappings.End = "EndTime"
    mappings.Subject = "Subject"
    mappings.AllDay = "AllDay"
    mappings.Description = "Description"
    mappings.Label = "Label"
    mappings.Location = "Location"
    mappings.RecurrenceInfo = "RecurrenceInfo"
    mappings.ReminderInfo = "ReminderInfo"
    mappings.ResourceId = "OwnerId"
    mappings.Status = "Status"
    mappings.Type = "EventType"

    schedulerStorage1.Appointments.CustomFieldMappings.Add(New AppointmentCustomFieldMapping("ApptImage1", "Icon1", FieldValueType.Object))
    schedulerStorage1.Appointments.CustomFieldMappings.Add(New AppointmentCustomFieldMapping("ApptImage2", "Icon2", FieldValueType.Object))
    schedulerStorage1.Appointments.CustomFieldMappings.Add(New AppointmentCustomFieldMapping("ApptAddInfo", "AdditionalInfo", FieldValueType.String))

    GenerateEvents(CustomEventList, 3)
End Sub

An appointment custom field is used to retrieve the images as byte arrays within the event handler:

View Example

Form1.cs

private void schedulerControl1_InitAppointmentImages(object sender, AppointmentImagesEventArgs e) {
    if (e.Appointment.CustomFields["ApptImage1"] != null) {
        byte[] imageBytes = (byte[])e.Appointment.CustomFields["ApptImage1"];
        if (imageBytes != null) {
            AppointmentImageInfo info = new AppointmentImageInfo();
            using (MemoryStream ms = new MemoryStream(imageBytes)) {
                info.Image = Image.FromStream(ms);
                e.ImageInfoList.Add(info);
            }
        }
    }

    if (e.Appointment.CustomFields["ApptImage2"] != null) {
        byte[] imageBytes = (byte[])e.Appointment.CustomFields["ApptImage2"];
        if (imageBytes != null) {
            AppointmentImageInfo info = new AppointmentImageInfo();
            using (MemoryStream ms = new MemoryStream(imageBytes)) {
                info.Image = Image.FromStream(ms);
                e.ImageInfoList.Add(info);
            }
        }
    }
}

Form1.vb

Private Sub schedulerControl1_InitAppointmentImages(ByVal sender As Object, ByVal e As AppointmentImagesEventArgs)
    If e.Appointment.CustomFields("ApptImage1") IsNot Nothing Then
        Dim imageBytes() As Byte = CType(e.Appointment.CustomFields("ApptImage1"), Byte())
        If imageBytes IsNot Nothing Then
            Dim info As New AppointmentImageInfo()
            Using ms As New MemoryStream(imageBytes)
                info.Image = Image.FromStream(ms)
                e.ImageInfoList.Add(info)
            End Using
        End If
    End If

    If e.Appointment.CustomFields("ApptImage2") IsNot Nothing Then
        Dim imageBytes() As Byte = CType(e.Appointment.CustomFields("ApptImage2"), Byte())
        If imageBytes IsNot Nothing Then
            Dim info As New AppointmentImageInfo()
            Using ms As New MemoryStream(imageBytes)
                info.Image = Image.FromStream(ms)
                e.ImageInfoList.Add(info)
            End Using
        End If
    End If
End Sub

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the InitAppointmentImages event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

how-to-initialize-appointment-images-and-display-text-using-the-custom-field-values-t328320/CS/CustomAppointmentImageAndText/Form1.cs#L20

    schedulerControl1.InitAppointmentDisplayText += schedulerControl1_InitAppointmentDisplayText;
    schedulerControl1.InitAppointmentImages += schedulerControl1_InitAppointmentImages;
}

VB.NET

how-to-initialize-appointment-images-and-display-text-using-the-custom-field-values-t328320/VB/CustomAppointmentImageAndText/Form1.vb#L22

    AddHandler schedulerControl1.InitAppointmentDisplayText, AddressOf schedulerControl1_InitAppointmentDisplayText
    AddHandler schedulerControl1.InitAppointmentImages, AddressOf schedulerControl1_InitAppointmentImages
End Sub