Resources for Appointments

  • 8 minutes to read

An appointment is typically associated with a resource. A resource is an abstraction and its actual interpretation depends on a particular application. In a project schedule, a resource is an employee, in a car sharing service — a vehicle, etc. This document explains how to assign resources to appointments and provides examples.

Overview

The SchedulerControl.DataStorage property provides access to a SchedulerDataStorage object that represents a storage for appointments and resources. The SchedulerDataStorage.Resources property provides access to a ResourceStorage object that represents a storage for resources. Use its Items property to access the collection of resources. A resource is an object that implements the Resource interface:

  • Id — gets or sets an object that uniquely identifies the resource.
  • Caption — gets or sets the caption displayed in the resource header.

Assign Resources to Appointments

To assign a resource to an appointment, assign the resource's Id property value to the appointment's ResourceId property.

ResourceNotSharedDiagram

Note that the resource should be contained in the resource storage. Otherwise, the appointment is not loaded into the appointment storage. In particular, it means that appointments with associated resources are not displayed in a scheduler with empty resource storage.

If an appointment has no associated resource, it belongs to all resources. Enable the SchedulerControl.OptionsView.ShowOnlyResourceAppointments option to display appointments only with associated resources.

An appointment can be associated with multiple resources. For example, a single task can be assigned to multiple employees. To associate an appointment with multiple resources, use the appointment's ResourceIds collection.

ResourceSharedDiagram

Note that the appointment storage's ResourceSharing property should be set to true to allow resources to share appointments.

In the image below, you can see how users can assign multiple resources to an appointment.

Resource Assignment with Appointment Form

NOTE

When multiple resources are associated with an appointment, resource identifiers are serialized in the XML format. Starting from version 15.2, the control uses Base64 encoding for XML serialization. Set the static (Shared in VB) SchedulerCompatibility.Base64XmlObjectSerialization property to false to revert to the previous serialization format. For more information, see the Data Sources topic.

Appointment Groups

Each appointment has a date and can have an associated resource. Dates are displayed at the top of the view.

Resources are only displayed if appointments are grouped. To group the appointments, set the SchedulerControl.GroupType property to one of the following values:

  • Date — appointments are grouped by date

  • Resource — appointments are grouped by resource

The Timeline View displays resources vertically on the left and dates horizontally at the top, regardless of the group type.

The Agenda View does not support groups.

Options

The options below are only in effect when appointments are grouped.

Resource Navigator

The Resource Navigator is automatically displayed when appointments are grouped. The navigator allows users to do the following:

To hide the navigator, set the SchedulerControl.ResourceNavigator.Visibility property to Never.

Resource Visibility

If a resource's Visible property is set to false, the resource's appointments are hidden.

Resource Categories

You can arrange resources in separate categories. For example, you can create a business and personal category.

The ResourceCategory class represents a category where you can place resources. Use the ResourceCategory.Resources collection to add resources to the category. When categories are created and populated with resources, add them to the SchedulerControl.ResourceCategories collection.

In the code below, resources are arranged into categories according to the ParentId field.

using DevExpress.XtraScheduler;

Scheduler.GroupType = SchedulerGroupType.Resource;

var categories = this.schedulerDataStorage1.Resources.Items
    .GroupBy(x => x.ParentId ?? x.Id)
    .Select(x => new ResourceCategory(x));
foreach (ResourceCategory category in categories)
    Scheduler.ResourceCategories.Add(category);
NOTE

Run the XtraScheduler demo and click Open Solution for the complete example.

Options

The SchedulerControl.OptionsView.ResourceCategories property provides access to options that are only applied when resources are organized into categories.

Resource Display Style

The ResourceDisplayStyle property specifies how to display resources in categories:

  • Tabs — each resource in a category is displayed as a separate tab and users can select a resource (tab) in a category. The ResourceCategory.SelectedResource property specifies the selected resource.

  • Headers — all resources in a category are displayed as a single category header and users cannot select a resource in a category (you can select a resource in code).

    If resources are displayed as category headers, you can use the ResourceCategory.Caption property to provide a custom caption for the category.

    If appointments are grouped by dates, resources are always displayed as category headers.

Appointment Display Mode

The AppointmentDisplayMode property specifies how to display appointments in a category depending on the selected resource:

  • AllResources — a category displays appointments for all resources, regardless of the selected resource.

  • SelectedResource — a category displays appointments for the selected resource only.

Buttons to Show and Hide a Resource in a Category

Users can click the Close button in a resource header to hide the resource. The Add button invokes a pop-up menu that contains all resources available in the control. Resources that are visible in the current category are checked. Resources that are hidden or belong to other categories are unchecked.

The user can click a check box to show or hide the corresponding resource. If a resource is hidden, the control shows the resource. If a resource is displayed in another category, the control moves the resource to the current category.

To hide these buttons, disable the ShowCloseButton and ShowAddButton options.

NOTE

The control shows only resources that meet the current filter criteria. To filter the resources, use the FilterResource event.

Resource Appearance

Appointment Color Schemas

The SchedulerControl.ResourceColorSchemas property provides access to color schemas used to paint appointments associated with a resource. The code below shows how to specify the background color.

schedulerControl1.ResourceColorSchemas[0].Cell = Color.Green;

You can also specify color schemas in the Visual Studio Designer.

TIP

You can use the WinForms Skin Editor to modify color schemas.

Appointment Background Color

Use a resource's extension SetColor(Resource, Color) method, to specify the background color for appointments associated with the resource. The code below shows how to specify the background color for appointments associated with the Work resource.

schedulerControl1.DataStorage.Resources.Items.FirstOrDefault(x => x.Caption == "Work").SetColor(Color.Orange);

Resource Image

Use a resource's extension SetImage(Resource, Image) method to assign an image to the resource. The image is displayed in the resource header. You can also use the ImageBytes property to specify the image.

Resource Headers

The SchedulerControl.OptionsView.ResourceHeaders property provides access to options that specify resource headers.

Orientation

In the Timeline View, resources are displayed vertically. Disable the SchedulerControl.OptionsView.ResourceHeaders.RotateCaption property to display captions horizontally.

Scheduler.OptionsView.ResourceHeaders.RotateCaption = false;

Appearance and Alignment

The Scheduler.Appearance.ResourceHeaderCaption property provides access to appearance settings applied to resource headers. For example, you can use the HAlignment property to align resource captions. Captions are aligned at the far edge in the following picture.

Scheduler.Appearance.ResourceHeaderCaption.TextOptions.HAlignment = DevExpress.Utils.HorzAlignment.Far;

Filter Resources

To filter resources in code, handle the SchedulerDataStorage.FilterResource event.

The example below shows how to filter resources in a scheduler. The filter shows the first three resources only.

using DevExpress.XtraScheduler;

private void schedulerDataStorage1_FilterResource(object sender, PersistentObjectCancelEventArgs e) {
    SchedulerDataStorage storage = (SchedulerDataStorage) sender;
    Resource res = (Resource) e.Object;
    // Shows the first three resources in the collection.
    e.Cancel = storage.Resources.Items.IndexOf(res) > 2 ;
}

Filter Controls

The ResourcesCheckedListBoxControl, ResourcesComboBoxControl, and ResourcesPopupCheckedListBoxControl controls can be attached to a scheduler to allow users filter resources.

Resource Tree

You can organize resources in a tree. A resource's Id property specifies the resource's identifier. Use the ParentId property to specify the identifier of the parent resource. If this property is set to null (Nothing in VB), the resource is at the root level.

See the Hierarchical Resource Specifics topic to learn how to use data source fields to organize resources in a tree.

Tree Control

The ResourcesTree control displays resources organized in a tree. The ResourcesTree.SchedulerControl property specifies the bound scheduler. You can use this control to display resources in the Timeline or Gantt view.

GanttView_ResourcesTree

See Resources Tree for more information.

See Also