Today we feature a new XtraScheduler helper function, which enables you to find free time slots within the specified time interval.
One of our customers asked whether it is possible to find free time periods suitable for a new meeting arrangement. The time interval should be queried based on a specific resource.Our developers appreciated this functionality and decided that it is essential for real-life calendar applications. So the FreeTimeCalculator class was born.
This class resides within the DevExpress.XtraScheduler.Tools namespace, starting with the 7.3.6 version of DevExpress Suite. It enables you to find all available free intervals within the specified period of time. Also, it can be used to find the nearest free slot with the specified duration. The search technique calculates the time in use based on the appointments currently contained within the Scheduler Storage.
The FreeTimeCalculator class provides the following methods and properties:
1. CalculateFreeTime method - finds all intervals that are not in use.
public TimeIntervalCollection CalculateFreeTime(TimeInterval interval) - performs a search within the specified interval.
public TimeIntervalCollection CalculateFreeTime(TimeInterval interval, Resource resource) - performs a search within the specified interval for the specified resource only.
The method returns a collection of intervals or the empty collection, if free intervals are not found.
The following code sample illustrates the implementation of the method used to search the visible interval for free slots associated with the specified resource.
TimeIntervalCollection CalculateFreeTime(Resource resource) {
FreeTimeCalculator calculator = new FreeTimeCalculator(schedulerControl1.Storage);
TimeInterval interval = schedulerControl1.ActiveView.GetVisibleIntervals().Interval;
return calculator.CalculateFreeTime(interval, resource);
}
2. FindFreeTimeInterval method searches for the nearest free interval with a specified constant duration. It has two overrides:
public TimeInterval FindFreeTimeInterval(TimeInterval interval, TimeSpan duration, bool forward) - performs a search for the slot with the specified duration within the specified interval.
public TimeInterval FindFreeTimeInterval(TimeInterval interval, Resource resource, TimeSpan duration, bool forward) - performs a search for the slot with the specified duration within the specified interval, and assigned to the specified resource.
The forward flag sets the search direction. If "forward" is set to true, the search starts at the interval.Start and continues forward in time. If "forward" is set to false, it starts at interval.End, and continues backwards.
The method returns an interval which meets the conditions or the TimeInterval.Empty value, if such an interval is not found.
The following code sample illustrates the implementation of the method used to find a free slot with specified duration before the end of the current work week.
TimeInterval FindFreeTimeInterval(TimeSpan duration) {
FreeTimeCalculator calculator = new FreeTimeCalculator(schedulerControl1.Storage);
DateTime startOfWeek = DevExpress.XtraScheduler.Native.DateTimeHelper.GetStartOfWeek(DateTime.Now);
TimeInterval interval = new TimeInterval(DateTime.Now, startOfWeek.AddDays(5));
return calculator.FindFreeTimeInterval(interval, duration, true);
}
3. ApplyAppointmentFilters property.
This property enables selection of the appointments to use when the search is performed. If ApplyAppointmentFilters is set to true, the filter is applied to the appointment collection within the storage before the search starts. Otherwise, all appointments contained within the storage are used in the free time calculations. Default value is true.
4. IntervalFound event.
Enables you to change a free interval after it is found. This event is raised for each interval before it is added to the collection.
The FreeIntervals property of IntervalFoundEventArgs object provides access to a TimeIntervalCollectionEx collection, which contains a single element - the located time interval. You can edit this interval by modifying its start, end and duration. The Add method of the TimeIntervalCollectionEx class allows intersecting time intervals to be joined and represented within the collection as a single time interval item. The Remove method excludes the specified time interval from the existing time interval, so the original interval is changed or split into two parts.
The following example illustrates how the IntervalFound event can be used to find the spare time periods in work time only within the work week.
To accomplish this, subscribe to the event and then call the FindFreeTimeInterval method.
private TimeInterval FindInterval(TimeInterval interval, TimeSpan duration) {
FreeTimeCalculator calculator = new FreeTimeCalculator(schedulerControl1.Storage);
calculator.IntervalFound += new IntervalFoundEventHandler(OnIntervalFound);
TimeInterval freeInterval = calculator.FindFreeTimeInterval(interval, duration, true);
return freeInterval;
}
The event handler filters the discovered free time intervals.
private void OnIntervalFound(object sender, IntervalFoundEventArgs args)
{ TimeIntervalCollectionEx freeIntervals = args.FreeIntervals;
DateTime start = freeIntervals.Start.Date.AddDays(-1);
DateTime end = freeIntervals.End;
while (start < end) {
RemoveSpareTime(freeIntervals, start);
RemoveNonworkingDays(freeIntervals, start);
start += TimeSpan.FromDays(1);
}
}
private void RemoveSpareTime(TimeIntervalCollectionEx freeIntervals, DateTime date) {
TimeInterval spareTime = new TimeInterval(date.AddHours(18), TimeSpan.FromHours(15));
freeIntervals.Remove(spareTime);
}
private void RemoveNonworkingDays(TimeIntervalCollectionEx freeIntervals, DateTime date) {
bool isWorkDay = schedulerControl1.WorkDays.IsWorkDay(date);
if (!isWorkDay)
freeIntervals.Remove(new TimeInterval(date, TimeSpan.FromDays(1)));
}
In a busy schedule, shown in the picture below, we have to find a free one-hour interval in work time. The search starts at the selected time cell and goes forward.
The following screen shot displays the result. A time for a new one hour meeting is found in the next day's work time. It is indicated by a time cell selection, the message box provides information on the time interval.
You can find the source code of the sample project in the Knowledge Base article How to find free time intervals for a meeting arrangement.