Skip to content

Commit 0f7e8a2

Browse files
ericpearsonericpearson
committed
Merge pull request blackberry#222 from blackberry-webworks/next-BB10-pim-calendar
Docs for blackberry.pim.calendar
2 parents 9f107e4 + 551c0f9 commit 0f7e8a2

9 files changed

+1620
-0
lines changed

‎api/blackberry_pim_calendar.js‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
/*
2+
* Copyright 2012 Research In Motion Limited.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/**
18+
* @namespace The <code>Calendar</code> object provides functions for creating and finding contacts.
19+
* @toc {PIM} Calendar
20+
* @featureID blackberry.pim.calendar
21+
* @permission access_pimdomain_calendars Permits your app to access calendar.
22+
*/
23+
blackberry.pim.calendar = {
24+
/**
25+
* @name blackberry.pim.calendar.createEvent
26+
* @function
27+
* @description Returns a new {@link blackberry.pim.calendar.CalendarEvent} object. This method does not persist the CalendarEvent object to the device. To persist the CalendarEvent object to the device, invoke {@link blackberry.pim.calendar.CalendarEvent#save}().
28+
* @param {Object} properties Optional object literal that specifies the field values for the CalendarEvent object. The object should be in the following form (with any number of properties):
29+
* @param {blackberry.pim.calendar.CalendarFolder} [folder] Optional CalendarFolder object that contains the event. If no folder is specified, the event will be created in the default calendar.
30+
* @returns {blackberry.pim.calendar.CalendarEvent}
31+
* @example
32+
* var evt,
33+
* calendar = blackberry.pim.calendar;
34+
*
35+
* function onSaveSuccess(created) {
36+
* // set evt to the object returned in save success callback, which
37+
* // contains the persisted event id
38+
* evt = created;
39+
* alert("Event saved to device: " + evt.id);
40+
* }
41+
*
42+
* function onSaveError(error) {
43+
* alert("Error saving event to device: " + error.code);
44+
* }
45+
*
46+
* function createEventInDefaultCalendarFolder(summary, location) {
47+
* evt = calendar.createEvent({
48+
* "summary": summary,
49+
* "location": location,
50+
* "start": new Date("Jan 01, 2015, 12:00"),
51+
* "end": new Date("Jan 01, 2015, 12:30"),
52+
* // if timezone is specified explicitly, then the times will be
53+
* // for that particular timezone; otherwise, the times will be
54+
* // for the current device timezone
55+
* "timezone": "America/New_York"
56+
* });
57+
* evt.save(onSaveSuccess, onSaveError);
58+
* }
59+
* @BB10X
60+
*/
61+
createEvent: function (properties, folder) {},
62+
63+
/**
64+
* @name blackberry.pim.calendar.findEvents
65+
* @function
66+
* @description Find calendar event(s) in the calendar based on some criteria. This function can be used to look up events based on start/end time, location, or summary.
67+
* @param {blackberry.pim.calendar.CalendarFindOptions} findOptions Options to be applied to the search.
68+
* @param {function} onFindSuccess Success callback function that is invoked with the events returned from the calendar.
69+
* @callback {blackberry.pim.calendar.CalendarEvent[]} onFindSuccess.events The array of CalendarEvent objects from the search.
70+
* @param {function} [onFindError] Optional error callback function. Invoked when error occurs.
71+
* @callback {blackberry.pim.calendar.CalendarError} onFindError.error The CalendarError object which contains the error code.
72+
* @returns {void}
73+
* @example
74+
* var calendar = blackberry.pim.calendar,
75+
* CalendarFindOptions = calendar.CalendarFindOptions;
76+
*
77+
* function onFindSuccess(events) {
78+
* alert("Found " + events.length + " events!");
79+
* events.forEach(function (evt) {
80+
* alert("Event summary: " + evt.summary);
81+
* alert("Event location: " + evt.location);
82+
* });
83+
* }
84+
*
85+
* function onFindError(error) {
86+
* alert("Error: " + error.code);
87+
* }
88+
*
89+
* // Find any events by keyword in any of the following fields:
90+
* // -location
91+
* // -summary
92+
* // -attendees' names or emails
93+
* function findEventsByKeyword(keyword) {
94+
* var filter = { "substring" : keyword };
95+
* var findOptions = {
96+
* "filter" : filter,
97+
* "detail" : CalendarFindOptions.DETAIL_FULL
98+
* };
99+
*
100+
* // Find all events that has the specified keyword in summary,
101+
* // location or attendees' name/email
102+
* calendar.findEvents(findOptions, onFindSuccess, onFindError);
103+
* }
104+
*
105+
* function findEventsSortSummaryDescending(keyword) {
106+
* var filter = { "substring" : keyword };
107+
* var findOptions = {
108+
* "filter" : filter,
109+
* "sort": [{
110+
* "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
111+
* "desc": true
112+
* }],
113+
* "detail" : CalendarFindOptions.DETAIL_FULL
114+
* };
115+
*
116+
* calendar.findEvents(findOptions, onFindSuccess, onFindError);
117+
* }
118+
*
119+
* // Only events in the specified folder will be returned in search results
120+
* function findEventsInCalendarFolder(keyword, folder, limit) {
121+
* var filter = {
122+
* "substring": keyword,
123+
* "folders": [folder]
124+
* };
125+
* var findOptions = {
126+
* "filter": filter,
127+
* "sort": [{
128+
* "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
129+
* "desc": false
130+
* }],
131+
* "detail": CalendarFindOptions.DETAIL_AGENDA,
132+
* "limit": limit
133+
* };
134+
*
135+
* calendar.findEvents(findOptions, onFindSuccess, onFindError);
136+
* }
137+
*
138+
* // Filter is optional in search
139+
* function listAllEvents(limit) {
140+
* var findOptions = {
141+
* "sort": [{
142+
* "fieldName": CalendarFindOptions.SORT_FIELD_SUMMARY,
143+
* "desc": false
144+
* }],
145+
* "detail": CalendarFindOptions.DETAIL_AGENDA,
146+
* "limit": limit
147+
* };
148+
*
149+
* calendar.findEvents(findOptions, onFindSuccess, onFindError);
150+
* }
151+
*
152+
* @BB10X
153+
*/
154+
findEvents: function (findOptions, onFindSuccess, onFindError) {},
155+
156+
/**
157+
* @name blackberry.pim.calendar.getDefaultCalendarFolder
158+
* @function
159+
* @description Retrieves the default calendar folder.
160+
* @returns {blackberry.pim.calendar.CalendarFolder}
161+
* @BB10X
162+
*/
163+
getDefaultCalendarFolder: function () {}
164+
165+
/**
166+
* @name blackberry.pim.calendar.getCalendarAccounts
167+
* @function
168+
* @description Retrieves all calendar accounts.
169+
* @returns {blackberry.pim.calendar.CalendarAccount[]}
170+
* @BB10X
171+
*/
172+
getCalendarAccounts: function () {},
173+
174+
/**
175+
* @name blackberry.pim.calendar.getDefaultCalendarAccount
176+
* @function
177+
* @description Retrieves the default calendar account.
178+
* @returns {blackberry.pim.calendar.CalendarAccount}
179+
* @BB10X
180+
*/
181+
getDefaultCalendarAccount: function () {}
182+
183+
/**
184+
* @name blackberry.pim.calendar.getEvent
185+
* @function
186+
* @description Retrieves the event with specified eventId and folder. This function is especially useful if you have
187+
* previously obtained an event object, and you want to get a fresh copy from the backend to make sure all its properties
188+
* are up-to-date.
189+
* @param {String} eventId The identifier of the event
190+
* @param {blackberry.pim.calendar.Folder} folder the folder that contains this event
191+
* @returns {blackberry.pim.calendar.CalendarEvent}
192+
* @BB10X
193+
*/
194+
getEvent: function (eventId, folder) {}
195+
};

‎api/blackberry_pim_calendar_Attendee.js‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
/*
2+
* Copyright 2012 Research In Motion Limited.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/**
18+
* @class The <code>Attendee</code> object represents an attendee of a calendar event item.
19+
* @toc {PIM} Attendee
20+
* @featureID blackberry.pim.calendar
21+
*/
22+
blackberry.pim.calendar.Attendee = {};
23+
24+
/**
25+
* @description The attendee's email address.
26+
* @type String
27+
* @BB10X
28+
*/
29+
blackberry.pim.calendar.Attendee.prototype.email = "";
30+
31+
/**
32+
* @description The attendee's name.
33+
* @type String
34+
* @BB10X
35+
*/
36+
blackberry.pim.calendar.Attendee.prototype.name = "";
37+
38+
/**
39+
* @description The attendee's type: {@link blackberry.pim.calendar.Attendee.TYPE_HOST} or {@link blackberry.pim.calendar.Attendee.TYPE_PARTICIPANT}
40+
* @type Number
41+
* @BB10X
42+
*/
43+
blackberry.pim.calendar.Attendee.prototype.type = 0;
44+
45+
/**
46+
* @description The attendee's role: {@link blackberry.pim.calendar.Attendee.ROLE_CHAIR}, {@link blackberry.pim.calendar.Attendee.ROLE_REQUIRED_PARTICIPANT}, {@link blackberry.pim.calendar.Attendee.ROLE_OPTIONAL_PARTICIPANT} or {@link blackberry.pim.calendar.Attendee.ROLE_NON_PARTICIPANT}
47+
* @type Number
48+
* @BB10X
49+
*/
50+
blackberry.pim.calendar.Attendee.prototype.role = 0;
51+
52+
/**
53+
* @description Acceptance status of the attendee: {@link blackberry.pim.calendar.Attendee.STATUS_UNKNOWN}, {@link blackberry.pim.calendar.Attendee.STATUS_TENTATIVE}, {@link blackberry.pim.calendar.Attendee.STATUS_ACCEPTED}, {@link blackberry.pim.calendar.Attendee.STATUS_DECLINED}, or {@link blackberry.pim.calendar.Attendee.STATUS_NOT_RESPONDED}
54+
* @type Number
55+
* @BB10X
56+
*/
57+
blackberry.pim.calendar.Attendee.prototype.status = 0;
58+
59+
/**
60+
* @description True when the attendee represents the user.
61+
* @type Boolean
62+
* @BB10X
63+
*/
64+
blackberry.pim.calendar.Attendee.prototype.owner = false;
65+
66+
/**
67+
* @description Identifier for the event in which this attendee participates.
68+
* @type String
69+
* @BB10X
70+
*/
71+
blackberry.pim.calendar.Attendee.prototype.eventId = "";
72+
73+
/**
74+
* @description Identifier for the contact that the attendee object represents.
75+
* @type String
76+
* @BB10X
77+
*/
78+
blackberry.pim.calendar.Attendee.prototype.contactId = "";
79+
80+
/**
81+
* @description Indicates the attendee is hosting the meeting.
82+
* @constant
83+
* @type Number
84+
* @BB10X
85+
*/
86+
blackberry.pim.calendar.Attendee.TYPE_HOST = 1;
87+
88+
/**
89+
* @description Indicates the attendee is a participant in the meeting.
90+
* @constant
91+
* @type Number
92+
* @BB10X
93+
*/
94+
blackberry.pim.calendar.Attendee.TYPE_PARTICIPANT = 1;
95+
96+
/**
97+
* @description Indicates that the attendee is the meeting's organizer.
98+
* @constant
99+
* @type Number
100+
* @BB10X
101+
*/
102+
blackberry.pim.calendar.Attendee.ROLE_CHAIR = 1;
103+
104+
/**
105+
* @description Indicates that the attendee is a required participant.
106+
* @constant
107+
* @type Number
108+
* @BB10X
109+
*/
110+
blackberry.pim.calendar.Attendee.ROLE_REQUIRED_PARTICIPANT = 2;
111+
112+
/**
113+
* @description Used on attendees whose participation is optional.
114+
* @constant
115+
* @type Number
116+
* @BB10X
117+
*/
118+
blackberry.pim.calendar.Attendee.ROLE_OPTIONAL_PARTICIPANT = 3;
119+
120+
/**
121+
* @description Indicates that an attendee is listed for information purposes only.
122+
* @constant
123+
* @type Number
124+
* @BB10X
125+
*/
126+
blackberry.pim.calendar.Attendee.ROLE_NON_PARTICIPANT = 4;
127+
128+
/**
129+
* @description Unknown acceptance status.
130+
* @constant
131+
* @type Number
132+
* @BB10X
133+
*/
134+
blackberry.pim.calendar.Attendee.STATUS_UNKNOWN = 0;
135+
136+
/**
137+
* @description Indicates the attendee will attempt to be in the meeting.
138+
* @constant
139+
* @type Number
140+
* @BB10X
141+
*/
142+
blackberry.pim.calendar.Attendee.STATUS_TENTATIVE = 2;
143+
144+
/**
145+
* @description Indicates the attendee has agreed to participate in the meeting.
146+
* @constant
147+
* @type Number
148+
* @BB10X
149+
*/
150+
blackberry.pim.calendar.Attendee.STATUS_ACCEPTED = 3;
151+
152+
/**
153+
* @description Used for an attendee that refused to participate in an event.
154+
* @constant
155+
* @type Number
156+
* @BB10X
157+
*/
158+
blackberry.pim.calendar.Attendee.STATUS_DECLINED = 4;
159+
160+
/**
161+
* @description Used when an attendee has not yet responded to the meeting request.
162+
* @constant
163+
* @type Number
164+
* @BB10X
165+
*/
166+
blackberry.pim.calendar.Attendee.STATUS_NOT_RESPONDED = 4;

0 commit comments

Comments
 (0)