Summary
An object implementing calICalendarView is generally intended to serve as a way of manipulating a set of DOM nodes corresonding to a visual representation of calIEvent and calITodo objects. Because of this close association between methods and attributes on the one hand, and content on the other, calICalendarView implementations are particularly well suited to XBL. There is, however, no practical obstacle to the interface being implemented by any javascript object associated with a group of DOM nodes, even non-anonymous XUL nodes.
In the vast majority of cases, the DOM corresponding to an implementation of calICalendarView will be rather complex. This explains the need for the fairly large list off attributes and methods that must be implemented, so that outside code can be able to gain a decent picture of the current state of those nodes. It should be noted, however, that the methods and attributes implemented by a calICalendarView need not behave in any predictable fashion. For instance, when the showDate method of the the calendar-multiday-view (an implementation of this interface) will sometimes show an entire week of dates, and sometimes show only the single date passed in. This allows lack of required predictability allows calICalendarView implementations to be re-used in a variety of sitatuations. It also fueled the development, however, of the more predictable, but less flexible calIDecoratedView, which usually contains an embedded calICalendarView.
Interface Code
[scriptable, uuid(3e567ccb-2ecf-4f59-b7ca-bf42b0fbf24a)]
interface calICalendarView : nsISupports
{
attribute calICalendar displayCalender;
attribute calICalendarViewController controller;
void showDate(in calIDateTime aDate);
void setDateRange(in calIDateTime aStartDate, in calIDateTime aEndDate);
readonly attribute calIDateTime startDate;
readonly attribute calIDateTime endDate;
readonly attribute boolean supportsDisjointDates;
readonly attribute boolean hasDisjointDates;
void setDateList(in unsigned long aCount, [array,size_is(aCount)] in calIDateTime aDates);
void getDateList(out unsigned long aCount, [array,size_is(aCount),retval] out calIDateTime aDates);
attribute calIItemBase selectedItem;
attribute calIDateTime selectedDay;
Attributes
displayCalendar
The displayCalendar is an implementation of the calICalendar interface. As implemented here, it corresponds to the calendar containing all of the calIEvents and calITodos that shoud be shown in the view. In the vast majority of cases, this is calICompositeCalendar. Notice that a calICalendarView does not contain any addItem or refresh methods. Therefore, it makes sense for an implementation of calICalendarView to add a calIObserver to the its displayCalendar in order to be notified of additions, modifications, and deletions of items it may be displaying. Note that in most cases, this attribute will be set by the consumers of calICalendarView very early in an application/extension's loading process.
controller
The controller for a calICalendarView is an implementation of calICalendarViewController and provides an integral link with the code in which a calICalendarView may be used. This link allows the calICalendarView to have a way of creating, modifying, and deleting events based on user interaction with the DOM nodes it controls, often without requiring any other user interaction. In general, therefore, a calICalendarView will not provide its own controller, but rather rely on other code to set this attribute. Implementations should therefore be wary to check whether a controller has been assigned to the view, before calling any of the methods it implements.Note that in most cases, this attribute will be set by the consumers of calICalendarView very early in an application/extension's loading process.
startDate
Returns a calIDateTime corresponding to the first date shown by the view
endDate
Returns a calIDateTime corresponding to the last date shown by the view. Note that this date is typically not immediately useful for querying for the events and tasks shown in the calICalendarView. Typically, one more day must be added to it, in order to make it exclusive.
supportsDisjointDates
Consumers of calICalendarView should check this attribute to determine whether or not the implementation allows for calls to setDateList. If an implementation returns true for this attribute, it must allow for any arbitrary set of dates to be displayed.
hasDisjointDates
Returns false if the dates being displayed represent a continuous list, and true if certain dates in between startDate and endDate may not be displayed.
selectedItem
Returns a calIItemBase corresponding to the currently active item in the view. Other areas of the code may use this attribute for setting selection, editing purposes, or any other purpose.
NOTE: This will likely change to selectedItems and return an array of calIItemBases in order to support selecting multiple items at once.
selectedDay
The currently selected day in the display. Other areas of the code will often use this as a basis for default values for new calIEvents and calITodos.
Methods
showDate
void showDate(in calIDateTime aDate);
Ensures that the passed in aDate is visible in the view. The view is free to show other days as well.
setDateRange
void setDateRange(in calIDateTime aStartDate, in calIDateTime aEndDate);
Ensures that the entire range of dates from aStartDate to aEndDate is visible. The view is free to show other dates as well, although this should be kept to a minimum. (For instance, calendar-month-view will show all dates from the start of the week of aStartDate to the end of the week of aEndDate.)
setDateList
void setDateList(in unsigned long aCount, [array,size_is(aCount)] in calIDateTime aDates);
This function can only be called if supportsDisjointDates is true and will throw an error if it is not. If supported, the dates in the aDates array will become the only dates shown in the view.
getDateList
void getDateList(out unsigned long aCount, [array,size_is(aCount),retval] out calIDateTime aDates); This function returns a list of all dates currently being shown in the view.
History
calICalendarView was introduced as part of the 'backend rewrite' that occurred prior to Lightning 0.1 and between Sunbird 0.2 and Sunbird 0.3. It remains unfrozen today.
Related Interfaces
calICalendarViewController calIDecoratedView
Example Code
Both calendar-multiday-view and calendar-month-view show examples, albeit complex, of implementations of this interface.