Appointment Labels and Statuses
- 4 minutes to read
This document describes appointment marks (labels and statuses) end-users can use to graphically identify appointments in their schedules. By default, labels and statuses collections contain items that are similar to the corresponding marks of Microsoft Outlook, and can be used to bring the Outlook style to your scheduling application. However, you can create your own custom labels and statuses.
Appointment Labels
A label is one of the basic visual characteristics of an appointment. It is used for at-a-glance appointment identification. In a scheduler, a label is displayed as a background color that fills the rectangle that represents an appointment.
The following picture illustrates what appointments with different labels look like. The label information is displayed as the appointment’s description.
Labels are stored in the SchedulerDataStorage.Labels collection that you can bind to an external data source. An individual label is represented by the AppointmentLabel object. To access a label’s display name and color use its UserInterfaceObject.DisplayName and AppointmentLabel.Color properties.
By default the Labels collection is filled with the following labels.
| Color | ARGB Color Value | Display Name | LabelId |
|---|---|---|---|
 |
System.Drawing.SystemColors.Window | None | 0 |
 |
#FFFFC2BE | Important | 1 |
 |
#FFA8D5FF | Business | 2 |
 |
#FFC1F49C | Personal | 3 |
 |
#FFF3E4C7 | Vacation | 4 |
 |
#FFF4CE93 | Must Attend | 5 |
 |
#FFC7F4FF | Travel Required | 6 |
 |
#FFCFDB98 | Needs Preparation | 7 |
 |
#FFE0CFE9 | Birthday | 8 |
 |
#FF8DE9DF | Anniversary | 9 |
 |
#FFFFF7A5 | Phone Call | 10 |
Tip
To restore the default items of the collection, call the AppointmentLabelCollection.LoadDefaults method.
Label colors can be specified in the following manner:
| Method | Description |
|---|---|
| Skin Elements | Use skin editor to change label colors. This method is currently available only in Office2016 skins. Use the AppointmentLabel.GetSkinElementName method to obtain a label color defined in a skin. |
| Legacy Default Colors | Colors are assigned when default appointment label set is created. Colors are determined by the AppointmentLabel.ColorId property and correspond to the SchedulerColorId values. Use the AppointmentLabel.GetDefaultColorByStringId method to obtain colors in code. |
| Arbitrary Colors | The AppointmentLabel.Color property assigns an arbitrary color to the label. In this situation the AppointmentLabel.ColorId property is SchedulerColorId.Nothing. |
You can edit the Label collection and customize existing labels, remove them or add your own. To create a new label, call the AppointmentLabelCollection.CreateNewLabel method
To mark an appointment with the specified label in code, use the Appointment.LabelKey property.
Tip
Instead of using labels for appointments, you can paint the appointment’s background in the SchedulerControl.CustomDrawAppointmentBackground event handler.
Tip
You can handle the SchedulerControl.InitNewAppointment event to initialize all newly created appointments with a certain label.
Appointment Statuses
Availability status is one of an appointment’s visual characteristics (marks). It is used for at-a-glance appointment identification. The status can be indicated as a strip painted with a particular brush and displayed in the appointment’s rectangle - on the left side or at the top. The status brush can also be used to paint the time cell background for all-day appointments if the SchedulerViewBase.StatusDisplayType property is set to the SchedulerViewStatusDisplayType.TimeCell value, as illustrated in the following picture:
Statuses are stored in the SchedulerDataStorage.Statuses collection. An individual status is represented by the AppointmentStatus objects. To specify the status’s display name and appearance use its DisplayName and AppointmentStatus.Brush properties.
The Statuses collection contains the following predefined items:
| Standard Brush | Standard ARGB Color Value | Display Name | StatusId |
|---|---|---|---|
 |
#FFFFFFFF | Free | 0 |
 |
#FF4A87E2 | Tentative | 1 |
 |
#FF4A87E2 | Busy | 2 |
 |
#FF800080 | Out Of Office | 3 |
 |
#FF937BD1 | Working Elsewhere | 4 |
Note
To restore the default items of the collection call the AppointmentStatusCollection.LoadDefaults method.
The color of status brushes used to paint the time cell background for an appointment with the AppointmentStatusType.Busy, AppointmentStatusType.Tentative and AppointmentStatusType.WorkingElsewhere statuses is the color of the appointment label. The time cell background for an appointment with the AppointmentStatusType.OutOfOffice status always has the standard color of this status. If the appointment has the label ‘None’ with ID=0 (e.g. a newly created appointment), the status uses standard colors listed in the table above.
Note
The color of the AppointmentStatusType.OutOfOffice status has been changed in v2017 vol.1 to make it the same as in Microsoft Outlook. Use the SchedulerCompatibility.StatusOutOfOfficeColor property to change it back to its former value.
The default values for the Statuses collection items are the same as availability statuses in MS Outlook. However you can edit this collection and customize the existing statuses, remove them, or add your own custom ones. This can be done both at design time and runtime.
To mark an appointment with the specified availability status in code, use the Appointment.StatusKey property.
Tip
You can handle the SchedulerControl.InitNewAppointment event to initialize all newly created appointments with a certain specified availability status.
Bind to Data (Mappings)
Read the following topics for detailed information, examples, and APIs: