Calendar Model (ICalendarModel)
A calendar model is used to manage things like weekends and holidays. The information returned by the model will be visualized by the calendar layer and the dateline. In the calendar layer calendar entries will by default be shown as filled rectangles reaching all the way from the timeline down to the bottom of the layer container. Calendar entries that represent weekend days will for example be shown as filled gray rectangles. The dateline uses the calendar information to control the foreground and background color of time spans shown in the lower half (minor time).
Calendar Layer
Dateline
Related API
void CalendarLayer.setCalendarEntryRenderer(Class entryClass, ICalendarEntryRenderer renderer);
void AbstractDatelineRenderer.setCalendarEntryForeground(Class entryClass, Color color);
void AbstractDatelineRenderer.setCalendarEntryBackground(Class entryClass, Color color);
Each Gantt chart keeps a reference to a single calendar model. The default calendar model is called TimeGranularityCalendarModel and and it supports calendar entries of type WeekendCalendarEntry and HolidayCalendarEntry.
void AbstractGanttChart.setCalendarModel(ICalendarModel model);
Calendar models are intended to compute their information on-the-fly. This means that a calendar model should not manage a list of all weekends but instead calculates weekend entries whenever it gets asked for them, which happens quite frequently. Whenever the user scrolls the timeline a new time span becomes visible. If for example the user scrolls 10 pixels to the right then these pixels represent a time span. The calendar layer will query the calendar model for all calendar entries within that time span. Seeing that the model gets queried often and that the model computes its entries on-the-fly it becomes clear that the model's implementation needs to be as efficient as possible. The calculations can not take a long time as this would reduce the rendering performance of the entire layer container.
The most important methods of a calendar model are the following two:
Iterator<S> getCalendarEntries(IDatelineModel model, ITimeSpan span);
Iterator<S> getCalendarEntries(IDatelineModel model, T node, ITimeSpan span);
The first one is used for retrieving calendar entries that are relevant for all nodes of the object hierarchy (e.g. weekends, company holidays). The second one should only return entries that are related to the given node. Shift plans are a good example where the second method comes in handy. Based on the description of a shift the method could return entries for those time spans where an employee is supposed to work and where he can take a break.
It might come as a surprise that a dateline model gets passed to the calendar model's methods but it is important input for deciding whether certain calendar entries are returned or not. If the dateline model indicates that it currently shows months as its minor time and years as its major time, then the calendar model can decide to not calculate weekend days at all, because otherwise the calendar layer would be cluttered with gray rectangles.