CalendarEvent

The CalendarEvent object represents an event in the device calendar. It can be obtained by calling blackberry.pim.calendar.createEvent() or blackberry.pim.calendar.findEvents()


Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
createExceptionEvent           Y 
remove           Y 
save           Y 
allDay           Y 
attendees           Y 
birthday           Y 
description           Y 
end           Y 
folder           Y 
id           Y 
location           Y 
originalStartTime           Y 
parentId           Y 
recurrence           Y 
reminder           Y 
sensitivity           Y 
start           Y 
status           Y 
summary           Y 
timezone           Y 
transparency           Y 
url           Y 
SENSITIVITY_NORMAL           Y 
SENSITIVITY_PERSONAL           Y 
SENSITIVITY_PRIVATE           Y 
SENSITIVITY_CONFIDENTIAL           Y 
TRANSPARENCY_FREE           Y 
TRANSPARENCY_TENTATIVE           Y 
TRANSPARENCY_BUSY           Y 
TRANSPARENCY_OUT_OF_OFFICE           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.pim.calendar" />           Y 
Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>access_pimdomain_calendars</rim:permit>
Permits your app to access calendar.



Functions

blackberry.pim.calendar.CalendarEvent createExceptionEvent (originalStartTime : Date)


Creates a new CalendarEvent object for a recurrence exception of the calling event. This is a deep copy of the object, with the id property set to null, the parentId property set to the id of the calling event, and the originalStartTime property set to the parameter value.


Supported Platforms
 - BlackBerry 10


Parameters
originalStartTime The date of the original recurrence instance that this event replaces. This date will be added to the calling event's exceptionDates array within the recurrence field.

Code Example:
var evt,
    exceptionEvt,
    calendar = blackberry.pim.calendar,
    CalendarRepeatRule = calendar.CalendarRepeatRule;

function onExceptionSaveSuccess(exceptionEvtCreated) {
   // Exception event created successcully, now the recurring event
   // has the following occurences:
   // Jan 22, 2013, 12:00
   // Jan 25, 2013, 12:00
   // Jan 29, 2013, 12:00
   // Feb  1, 2013, 12:00
   // Feb  5, 2013, 12:00
   // Feb  8, 2013, 12:00
   // Feb 12, 2013, 12:00
   // Feb 16, 2013, 12:00
   exceptionEvt = exceptionEvtCreated;
   // exception event has a different id than the original event
   alert("Exception event created successfully: " + exceptionEvt.id);

   // get a fresh copy of the recurring event which contains the
   // updated recurrence
   evt = calendar.getEvent(evt.id, evt.folder);
}

function onSaveSuccess(created) {
   // Recurring event created successcully, with the following occurences:
   // Jan 22, 2013, 12:00
   // Jan 25, 2013, 12:00
   // Jan 29, 2013, 12:00
   // Feb  1, 2013, 12:00
   // Feb  5, 2013, 12:00
   // Feb  8, 2013, 12:00
   // Feb 12, 2013, 12:00
   // Feb 15, 2013, 12:00
   evt = created;

   // The following code replaces the last occurence with an exception
   // occurence on the day after
   exceptionEvt = evt.createExceptionEvent(new Date("Feb 15, 2013, 12:00"));
   exceptionEvt.start = new Date("Feb 16, 2013, 12:00");
   exceptionEvt.end = new Date("Feb 16, 2013, 12:30");
   exceptionEvt.save(onExceptionSaveSuccess, onSaveError);
}

function onSaveError(error) {
   alert("Error saving event to device: " + error.code);
}

function createRecurringEvent() {
   var start = new Date("Jan 21, 2013, 12:00");
   var end = new Date("Jan 21, 2013, 12:30");
   var location = "some location";
   var summary = "My recurring event";
   var repeatRule = new CalendarRepeatRule({
      "frequency": CalendarRepeatRule.FREQUENCY_WEEKLY,
      "expires": new Date("Feb 18, 2013, 12:00"),
      "dayInWeek": CalendarRepeatRule.TUESDAY | CalendarRepeatRule.FRIDAY
   });
   evt = calendar.createEvent({
      "summary": summary,
      "location": location,
      "start": start,
      "end": end,
      "recurrence": repeatRule
   });
   evt.save(onSaveSuccess, onSaveError);
}

void remove (onRemoveSuccess : function, onRemoveError : function, [removeAll : Boolean])


Removes the event from the calendar. An error callback is called with a blackberry.pim.calendar.CalendarError object if the removal is unsuccessful.


Supported Platforms
 - BlackBerry 10


Parameters
onRemoveSuccess The callback function that will be invoked when the event is removed successfully.
onRemoveError The callback function that will be invoked when the event cannot be removed.

error: The blackberry.pim.calendar.CalendarError object which contains the error code. A possible error is to remove an event before it was saved, this would result in INVALID_ARGUMENT_ERROR.
removeAll Optional flag that only applies to recurring events. If removeAll is set to true, all occurrences of the recurring event will be removed; otherwise, only the single occurrence represented by this event object will be removed. This parameter defaults to true if not specified.

Code Example:
var calendar = blackberry.pim.calendar,
    evt;

function testRemove() {
   // omitting optional folder parameter in createEvent(), calling save()
   // will save event to default calendar folder
   evt = calendar.createEvent({
       "summary": "Picnic",
       "location": "South Park",
       "start": new Date("Jan 1, 2013, 13:00"),
       "end": new Date("Jan 1, 2013, 16:00"),
       "transparency": calendar.CalendarEvent.SENSITIVITY_PERSONAL,
       "reminder": 2 * 24 * 60 // 2 days before start
   });

   // will result in error, since the event has not been saved to the
   // calendar folder yet
   evt.remove(onSuccess, onError);

   // save event to default calendar folder
   evt.save(function (saved) {
      evt = saved; // replace original evt object
      alert("Event saved: " + evt.id);
   }, function (error) {
      alert("Error saving event, error code: " + error.code);
   });

   // this will remove the event from the calendar folder
   setTimeout("evt.remove(onSuccess, onError)", 1000);
}

function onSuccess() {
   alert("Event removed!");
}

function onError(error) {
   alert("Failed to remove event, error code: " + error.code);
}

function removeSingleOccurrence(keyword, dateToRemove) {
   // find all instances of the recurring event
   calendar.findEvents({
      "filter": {
          "substring": keyword,
          "expandRecurring": true
      }
   }, function (events) {
      alert("Found " + events.length + " events that matches filter!");
      events.forEach(function (evt) {
         if (evt.start.toISOString() === dateToRemove.toISOString()) {
            evt.remove(function () {
               alert(dateToRemove + " instance removed successfully!");
            }, function (error) {
               alert(dateToRemove + " instance not removed, error code: " + error.code);
            },
            false); // pass false to remove only this single occurrence
         }
      });
   }, function (error) {
      alert("Failed to find events, error code: " + error.code);
   });
}

void save (onSaveSuccess : function, onSaveError : function)


Saves a new event to the calendar, or updates an existing event if an event with the same id already exists.


Supported Platforms
 - BlackBerry 10


Parameters
onSaveSuccess The callback function that will be invoked when the contact is saved successfully.

event: The blackberry.pim.calendar.CalendarEvent object. You should save this object for further operations on the event and use it to replace the original event object prior to save.
onSaveError The callback function that will be invoked when the event cannot be saved.

error: The blackberry.pim.calendar.CalendarError object which contains the error code. Possible errors:

Code Example:
var calendar = blackberry.pim.calendar,
    // omitting optional folder parameter in createEvent(), calling save() will
    // save event to default calendar folder
    evt = calendar.createEvent({
        "summary": "Picnic",
        "location": "South Park",
        "start": new Date("Jan 1, 2013, 13:00"),
        "end": new Date("Jan 1, 2013, 16:00"),
        "transparency": calendar.CalendarEvent.SENSITIVITY_PERSONAL,
        "reminder": 2 * 24 * 60 // 2 days before start
    });

// save event to default calendar folder
evt.save(function (saved) {
    evt = saved; // replace original evt object
    alert("Event saved: " + evt.id);
}, function (error) {
    alert("Error saving event, error code: " + error.code);
});

// edit event description
evt.description = "This is going to be fun!";
// save changes to event
evt.save(function (saved) {
    evt = saved; // replace original evt object
    alert("Event description: " + evt.description);
}, function (error) {
    alert("Error saving event, error code: " + error.code);
});

Properties

Boolean allDay


True if the event is an all-day event.


Supported Platforms
 - BlackBerry 10

blackberry.pim.calendar.Attendee[] attendees


The list of attendees in the event.


Supported Platforms
 - BlackBerry 10

Boolean birthday


True if the event represents a birthday.


Supported Platforms
 - BlackBerry 10

String description


A description of the event.


Supported Platforms
 - BlackBerry 10

Date end


The end date and time of the event.


Supported Platforms
 - BlackBerry 10

readonly blackberry.pim.calendar.CalendarFolder folder


The CalendarFolder that contains this event.


Supported Platforms
 - BlackBerry 10

readonly String id


An identifier for the event.


Supported Platforms
 - BlackBerry 10

String location


A plain text description of the location of the event.


Supported Platforms
 - BlackBerry 10

Date originalStartTime


This attribute is only meaningful in events that are recurrence exceptions.
A recurrence exception is a differing instance of a recurring event. The originalStartTime property stores the time and date of the recurrence instance that is replaced by this event. For example: a daily meeting at 2:00 PM that is rescheduled to 3:00 PM on a given day would have an originalStartTime of 2:00 PM.


Supported Platforms
 - BlackBerry 10

readonly String parentId


This attribute is only meaningful in events that are recurrence exceptions.
A recurrence exception is a differing instance of a recurring event. An example: a daily meeting at 2:00 PM that is rescheduled to 3:00 PM on a given day. This rescheduled occurrence is represented as an exception. It is stored in the database as a separate event and it references the original recurring event by means of the parent id.


Supported Platforms
 - BlackBerry 10

blackberry.pim.calendar.CalendarRepeatRule recurrence


The recurrence or repetition rule for this event. This is used for creating a recurring event.


Supported Platforms
 - BlackBerry 10

Number reminder


A reminder for the event, specified as the number of minutes between the alert and the start time.


Supported Platforms
 - BlackBerry 10

Number sensitivity


Sensitivity level of the event: SENSITIVITY_NORMAL, SENSITIVITY_PERSONAL, SENSITIVITY_PRIVATE or SENSITIVITY_CONFIDENTIAL


Supported Platforms
 - BlackBerry 10

Date start


The start date and time of the event.


Supported Platforms
 - BlackBerry 10

Number status


An indication of the user's status of the event.


Supported Platforms
 - BlackBerry 10

String summary


A summary of the event.


Supported Platforms
 - BlackBerry 10

String timezone


Name of the timezone where the event was created. To get the current device timezone, see blackberry.system.getCurrentTimezone(). To get the list of all possible timezones, see blackberry.system.getTimezones()


Supported Platforms
 - BlackBerry 10

Number transparency


An indication of the display status to set for the event. Its value can be one of: TRANSPARENCY_FREE, TRANSPARENCY_TENTATIVE, TRANSPARENCY_BUSY, or TRANSPARENCY_OUT_OF_OFFICE


Supported Platforms
 - BlackBerry 10

String url


A URL associated with the event.


Supported Platforms
 - BlackBerry 10

Constants

static Number SENSITIVITY_NORMAL


Sensitivity level for unrestricted events.


Supported Platforms
 - BlackBerry 10

static Number SENSITIVITY_PERSONAL


Sensitivity level for personal events.


Supported Platforms
 - BlackBerry 10

static Number SENSITIVITY_PRIVATE


Sensitivity level for private events.


Supported Platforms
 - BlackBerry 10

static Number SENSITIVITY_CONFIDENTIAL


Sensitivity level for confidential events.


Supported Platforms
 - BlackBerry 10

static Number TRANSPARENCY_FREE


Transparency constant. Used to inform that the event represents free time (the event's owner is available).


Supported Platforms
 - BlackBerry 10

static Number TRANSPARENCY_TENTATIVE


Transparency constant. Used to inform that an event may or may not happen (the owner may be available).


Supported Platforms
 - BlackBerry 10

static Number TRANSPARENCY_BUSY


Transparency constant. Used to inform that an event is confirmed (the owner is busy).


Supported Platforms
 - BlackBerry 10

static Number TRANSPARENCY_OUT_OF_OFFICE


Transparency constant. Used to inform that the event owner is out of office.


Supported Platforms
 - BlackBerry 10

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:03 GMT-0500 (EST)