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().

Installation:

To use this API in your project, add the calendar plugin:

webworks plugin add com.blackberry.pim.calendar
Properties:
Boolean allDay
Attendee[] attendees
Boolean birthday
String description
Date end
CalendarFolder folder
String id
String location
Date originalStartTime
String parentId
CalendarRepeatRule recurrence
Number reminder
Number sensitivity
Date start
Number status
String summary
String timezone
Number transparency
String url

createExceptionEvent()

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.

Synopsis:

CalendarEvent blackberry.pim.calendar.createExceptionEvent(originalStartTime)

Parameters:

originalStartTime {Date}

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.

Returns:

blackberry.pim.calendar.CalendarEvent

The calendar event object

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);
}
            

remove()

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

Synopsis:

void CalendarEvent.remove(onRemoveSuccess, onRemoveError, [removeAll])

Parameters:

onRemoveSuccess {Function}

The callback function that will be invoked when the event is removed successfully.

onRemoveError {Function} optional

The callback function that will be invoked when the event cannot be removed.

error {CalendarError}

The 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 {Boolean}

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.

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);
    });
}
            

save()

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

Synopsis:

void CalendarEvent.save(onSaveSuccess, onSaveError)

Parameters:

onSaveSuccess {Function}

The callback function that will be invoked when the event is saved successfully.

events {CalendarEvent}

The 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 {Function} optional

The callback function that will be invoked when the event cannot be saved.

error {CalendarError}
The CalendarError object which contains the error code. Possible errors:

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);
});
            

allDay

True if the event is an all-day event.

Synopsis:

Boolean CalendarEvent.allDay

attendees

The list of attendees in the event.

Synopsis:

{Attendee[]} CalendarEvent.attendees

birthday

True if the event represents a birthday.

Synopsis:

Boolean CalendarEvent.birthday

description

A description of the event.

Synopsis:

String CalendarEvent.description

end

The end time of the event.

Synopsis:

Date CalendarEvent.end

folder

The CalendarFolder that contains this event.

Synopsis:

read-only
CalendarFolder CalendarEvent.folder

id

An identifier for the event.

Synopsis:

read-only
String CalendarEvent.id

location

A plain text description of the location of the event.

Synopsis:

String CalendarEvent.location

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.

Synopsis:

Date CalendarEvent.originalStartTime

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.

Synopsis:

read-only
String CalendarEvent.parentId

recurrence

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

Synopsis:

CalendarRepeatRule CalendarEvent.recurrence

reminder

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

Synopsis:

Number CalendarEvent.reminder

sensitivity

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

Synopsis:

Number CalendarEvent.sensitivity

start

The start time of the event

Synopsis:

Date CalendarEvent.start

status

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

Synopsis:

Number CalendarEvent.status

summary

A summary of the event.

Synopsis:

String CalendarEvent.summary

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() .

Synopsis:

String CalendarEvent.timezone

transparency

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

Synopsis:

Number CalendarEvent.transparency

url

A URL associated with the event.

Synopsis:

String CalendarEvent.url

SENSITIVITY_NORMAL

Sensitivity level for unrestricted events.

Synopsis:

constant
Number CalendarEvent.SENSITIVITY_NORMAL = 0

SENSITIVITY_PERSONAL

Sensitivity level for personal events.

Synopsis:

constant
Number CalendarEvent.SENSITIVITY_PERSONAL = 1

SENSITIVITY_PRIVATE

Sensitivity level for private events.

Synopsis:

constant {Number}
blackberry.pim.calendar.CalendarEvent.SENSITIVITY_PRIVATE = 2;

SENSITIVITY_CONFIDENTIAL

Sensitivity level for confidential events.

Synopsis:

constant
Number CalendarEvent.SENSITIVITY_CONFIDENTIAL = 3

TRANSPARENCY_FREE

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

Synopsis:

constant
Number CalendarEvent.TRANSPARENCY_FREE = 0

TRANSPARENCY_TENTATIVE

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

Synopsis:

constant
Number CalendarEvent.TRANSPARENCY_TENTATIVE = 1

TRANSPARENCY_BUSY

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

Synopsis:

constant
Number CalendarEvent.TRANSPARENCY_BUSY = 2

TRANSPARENCY_OUT_OF_OFFICE

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

Synopsis:

constant
Number CalendarEvent.TRANSPARENCY_OUT_OF_OFFICE = 3

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus