TimeRegion Class

An area with unique user restrictions. Limits the appointments that can be placed inside this time interval and/or users that can add these appointments.

Namespace: DevExpress.XtraScheduler

Assembly: DevExpress.XtraScheduler.v20.1.dll

Declaration

public class TimeRegion :
    INotifyPropertyChanged
Public Class TimeRegion
    Implements INotifyPropertyChanged

Remarks

Appointment time regions are time slots with unique user restrictions that override global Scheduler settings. In the "Full Week" Scheduler demo time regions, disable the following time intervals for every week:

  • work days: 1p.m. - 2p.m;
  • weekends - disabled entirely.

Time Regions

In this demo users cannot create new appointments or change existing ones, so that they belong to these time regions. Appointments that already intersect these intervals cannot be edited either. These restrictions apply to all appointments except those with the "Out of Office" status.

Time Regions

Common Time Region Settings

Time Regions are objects of the TimeRegion class that are stored in the SchedulerControl.TimeRegions collection.

When it comes to settings, TimeRegion objects are similar to Appointments: they have start and end dates, and can recur according to the given pattern.

API

Description

TimeRegion.Start
TimeRegion.End

Date time values that specify the time region duration.

TimeRegion.Recurrence

Stores the DevExpress.XtraScheduler.RecurrenceInfo object that specifies a recurrence rule (pattern) for this time region.

TimeRegion.Editable

Specifies whether users can add, modify or remove appointments that belong (partially or completely) to this region.

You can use this boolean setting not only to "ban" a required date interval, but also to implement an editable region outside of which users cannot modify events. In the later case, disable the SchedulerOptionsCustomization.AllowAppointmentCreate, SchedulerOptionsCustomization.AllowAppointmentEdit and/or other global Scheduler settings, and set the Editable property to true.

TimeRegion.ResourceIds

IDs of resources associated with this region.
Regions with resource IDs are displayed only for these resources when the SchedulerViewBase.GroupType is set to Resource.

TimeRegion.ExceptionDates

A list of DateTime objects that allow you to remove a recurring time region instance for a specific date. Time portions of these DateTime objects must match the time of the TimeRegion.Start value.

The code below illustrates how to create two above-mentioned time regions from the "Full Week" Scheduler demo.

DateTime baseDate = DateTimeHelper.GetStartOfWeek(DateTime.Today);
baseDate = baseDate.AddDays(-15);

//Region #1 - 1p.m. to 2p.m., repeats every work day
TimeRegion timeRegion1 = new TimeRegion();
timeRegion1.Start = baseDate.AddHours(13);
timeRegion1.End = baseDate.AddHours(14);
timeRegion1.Editable = false;
timeRegion1.Recurrence = new RecurrenceInfo();
timeRegion1.Recurrence.Start = timeRegion1.Start;
timeRegion1.Recurrence.Type = RecurrenceType.Weekly;
timeRegion1.Recurrence.WeekDays = WeekDays.WorkDays;
scheduler.TimeRegions.Add(timeRegion1);

//Region #2 - all day long, repeats every weekend
TimeRegion timeRegion2 = new TimeRegion();
timeRegion2.Start = baseDate;
timeRegion2.End = baseDate.AddDays(1);
timeRegion2.Editable = false;
timeRegion2.Recurrence = new RecurrenceInfo();
timeRegion2.Recurrence.Start = timeRegion2.Start;
timeRegion2.Recurrence.Type = RecurrenceType.Weekly;
timeRegion2.Recurrence.WeekDays = WeekDays.WeekendDays;
scheduler.TimeRegions.Add(timeRegion2);

Appearance

Time regions' appearance depends on the currently applied skin (and skin palette, if you use vector skins).

Handle the SchedulerControl.CustomDrawTimeRegion event to manually re-paint time regions. In the DevExpress demo this event is handled to draw a "lunch" icon on top of the 1p.m.~2p.m. region.

Time Regions

SvgImage svgImage = DemoUtils.GetResourceSvgImage("Images.Dinner.svg");
scheduler.CustomDrawTimeRegion += (s, e) => {
    if (e.TimeRegion == timeRegion2)
        return;
    e.DrawDefault();
    Rectangle bounds = new Rectangle(e.Bounds.X, e.Bounds.Y, e.Bounds.Width, e.Bounds.Height);
    double scaleFactor = bounds.Height / svgImage.Height;
    Image img = svgImage.Render(null, Math.Min(scaleFactor, 1));
    int x = e.Bounds.Location.X + (e.Bounds.Width / 2 - img.Width / 2);
    int y = e.Bounds.Location.Y + (e.Bounds.Height / 2 - img.Height / 2);
    e.Cache.DrawImage(img, new Point(x, y));
    e.Handled = true;
};

Custom Restrictions

When you disable the TimeRegion.Editable setting, users are unable to create or modify existing appointments so that they belong to this region. Handle the SchedulerControl.TimeRegionCustomize event and override its e.Editable parameter to remove restrictions for specific appointments and/or users.

The code below is taken from the Scheduler Demo, where the "Lunch" time region (1p.m.~2p.m.) does not accept any appointments unless they have the "Out of Office" status.

Time Regions

scheduler.TimeRegionCustomize += (s, e) => {
    if (e.Appointment == null)
        return;
    if (e.Appointment.StatusKey.Equals(3))
        e.Editable = true;
};

Custom Appointment Edit Forms

The standard Appointment Edit Form does not allow you to set start/end appointment dates that belong to restricted time regions.

Time Regions

When you use a custom Appointment Edit Form and implement custom methods that save appointments, check the boolean DevExpress.XtraScheduler.UI.AppointmentFormController.IsTimeValid method's return value to prevent users from saving invalid appointments.

//OutlookAppointmentForm.cs
private void bvbSave_ItemClick(object sender, BackstageViewItemEventArgs e) {
    OnSaveButton();
}

private void btnSave_ItemClick(object sender, ItemClickEventArgs e) {
    OnSaveButton();
}

protected virtual void OnSaveButton() {
    Save(false);
}
private void Save(bool closeAfterSave) {
    //. . .
    if (!Controller.IsTimeValid()) {
        ShowMessageBox(SchedulerLocalizer.GetString(SchedulerStringId.Msg_InvalidAppointmentTime), Controller.GetMessageBoxCaption(SchedulerStringId.Msg_InvalidAppointmentTime), MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
        return;
    }
    //. . .
}

Change the SchedulerStringId.Msg_InvalidAppointmentTime field to replace the standard "Invalid appointment time" message.

Inheritance

Object
TimeRegion
See Also