calICalendarViewController

Summary

A calICalendarViewController provides a way for a calICalendarView to create, modify, and delete items. Implementing a calICalendarViewController allows for these actions to be performed in a manner consistent with the rest of the application in which the calICalendarView is included.

Interface Code

[scriptable, uuid(1f783898-f4c2-4b2d-972e-360e0de38237)]
interface calICalendarViewController : nsISupports
{
  void createNewEvent (in calICalendar aCalendar,
           in calIDateTime aStartTime,
           in calIDateTime aEndTime);
 
  void modifyOccurrence (in calIItemOccurrence aOccurrence,
       in calIDateTime aNewStartTime,
       in calIDateTime aNewEndTime);

  void deleteOccurrence (in calIItemOccurrence aOccurrence);
};

Methods

createNewEvent

  void createNewEvent (in calICalendar aCalendar,
           in calIDateTime aStartTime,
           in calIDateTime aEndTime);

The createNewEvent method is used for creating a new calIEvent in the calICalendar specified by the aCalendar parameter. In many cases, aCalendar will be the defaultCalendar of the displayCalendar of the calICalendarView. The calIDateTime parameters are optional, but aEndTime cannot be included without aStartTime. If aStartTime is specified, then the calIEvent is meant to be created 'silently', that is, without a more detailed dialog appearing. The calIEvent should have its endDate set to aEndTime, if this parameter is specified. Otherwise, it should be set to a default value, as determined by the application. The other values of the calIEvent (title, summary, alarm, etc) should likewise be set to defaults. If no aStartTime is specified, then an event-creation dialog should be displayed.

modifyOccurrence

  void modifyOccurrence (in calIItemOccurrence aOccurrence,
       in calIDateTime aNewStartTime,
       in calIDateTime aNewEndTime);

The modifyOccurrence method is used to change the attributes of an already existing calIItem. The calIDateTime parameters must either both be specified, or neither. If they are both specified, aOccurrence should be modified 'silently', that is, without a more detailed dialog appearing. Otherwise, a dialog should be display allowing the user to modify the fields. Implementations of calICalendarViewController should be careful to provide clearly defined behavior to the user regarding the modification of recurring calIItems.

deleteOccurrence

  void deleteOccurrence (in calIItemOccurrence aOccurrence);

The deleteOccurrence method is called when by the calICalendarView when calIItem should be deleted. Implementations of calICalendarViewController should be careful to provide clearly defined behavior to the user regarding the deleting of recurring calIItems, in the case where aOccurrence is a single occurrence of a recurring calIItem.

Related Interfaces

calICalendarView calIDecoratedView

Example Code

var myViewController = {
    QueryInterface: function(aIID) {
        if (!aIID.equals(Components.interfaces.calICalendarViewController) &&
            !aIID.equals(Components.interfaces.nsISupports)) {
            throw Components.results.NS_ERROR_NO_INTERFACE;
        }
        return this;
    },

    createNewEvent: function (aCalendar, aStartTime, aEndTime) {
        // if we're given both times, skip the dialog
        if (aStartTime && aEndTime && !aStartTime.isDate && !aEndTime.isDate) {
            var event = createEvent();
            event.startDate = aStartTime;
            event.endDate = aEndTime;
            event.title = "New Event";
            aCalendar.addItem(event, null);
        } else if (aStartTime && aStartTime.isDate) {
            var event = createEvent();
            event.startDate = aStartTime;
            aCalendar.addItem(event, null);
        } else {
            createEventWithDialog(aCalendar, aStartTime, aEndTime);
        }
    },

    modifyOccurrence: function (aOccurrence, aNewStartTime, aNewEndTime) {
        // if we can modify this thing directly (e.g. just the time changed),
        // then do so; otherwise pop up the dialog
        if (aNewStartTime && aNewEndTime && !aNewStartTime.isDate && !aNewEndTime.isDate) {
            var instance = aOccurrence.clone();
            instance.startDate = aNewStartTime;
            instance.endDate = aNewEndTime;
            instance.calendar.modifyItem(instance, aOccurrence, null);
        } else {
            modifyEventWithDialog(aOccurrence);
        }
    },

    deleteOccurrence: function (aOccurrence) {
        if (aOccurrence.parentItem != aOccurrence) {
            var event = aOccurrence.parentItem.clone();
            event.recurrenceInfo.removeOccurrenceAt(aOccurrence.recurrenceId);
            event.calendar.modifyItem(event, aOccurrence, null);
         } else {
            aOccurrence.calendar.deleteItem(aOccurrence, null);
         }
    }
};

History

calICalendarViewController 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.