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.v24.1.dll

NuGet Package: DevExpress.Win.Scheduler

Declaration

C#

public class TimeRegion :
    INotifyPropertyChanged

VB.NET

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.

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.

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.

C#

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);

VB.NET

Dim baseDate As Date = DateTimeHelper.GetStartOfWeek(Date.Today)
baseDate = baseDate.AddDays(-15)

'Region #1 - 1p.m. to 2p.m., repeats every work day
Dim timeRegion1 As 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
Dim timeRegion2 As 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.

C#

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;
};

VB.NET

Imports System

Dim svgImage As SvgImage = DemoUtils.GetResourceSvgImage("Images.Dinner.svg")
AddHandler scheduler.CustomDrawTimeRegion, Sub(s, e)
    If e.TimeRegion = timeRegion2 Then
        Return
    End If
    e.DrawDefault()
    Dim bounds As New Rectangle(e.Bounds.X, e.Bounds.Y, e.Bounds.Width, e.Bounds.Height)
    Dim scaleFactor As Double = bounds.Height \ svgImage.Height
    Dim img As Image = svgImage.Render(Nothing, Math.Min(scaleFactor, 1))
    Dim x As Integer = e.Bounds.Location.X + (e.Bounds.Width \ 2 - img.Width \ 2)
    Dim y As Integer = e.Bounds.Location.Y + (e.Bounds.Height \ 2 - img.Height \ 2)
    e.Cache.DrawImage(img, New Point(x, y))
    e.Handled = True
End Sub

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.

C#

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

VB.NET

AddHandler scheduler.TimeRegionCustomize, Sub(s, e)
    If e.Appointment Is Nothing Then
        Return
    End If
    If e.Appointment.StatusKey.Equals(3) Then
        e.Editable = True
    End If
End Sub

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.

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.

C#

//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;
    }
    //. . .
}

VB.NET

'OutlookAppointmentForm.vb
Private Sub bvbSave_ItemClick(ByVal sender As Object, ByVal e As BackstageViewItemEventArgs)
    OnSaveButton()
End Sub

Private Sub btnSave_ItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs)
    OnSaveButton()
End Sub

Protected Overridable Sub OnSaveButton()
    Save(False)
End Sub
Private Sub Save(ByVal closeAfterSave As Boolean)
    '. . .
    If Not Controller.IsTimeValid() Then
        ShowMessageBox(SchedulerLocalizer.GetString(SchedulerStringId.Msg_InvalidAppointmentTime), Controller.GetMessageBoxCaption(SchedulerStringId.Msg_InvalidAppointmentTime), MessageBoxButtons.OK, MessageBoxIcon.Exclamation)
        Return
    End If
    '. . .
End Sub

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

Inheritance

Object

TimeRegion