com.distriqt.extension.calendar.Calendar

Package	com.distriqt.extension.calendar
Class	public class Calendar
Inheritance	Calendar flash.events.EventDispatcher

This class represents the calendar extension providing access to the user's calendar on the device.

Note: This extension contains references to "Events" that refer to calendar events or calendar entries and not normal actionscript event objects. The normal actionscript event objects are all contained in the com.distriqt.extension.calendar.events package.

Requesting access

Before an attempt is made to retrieve or add events you must request access to the user's calendars. Depending on the platform this may do different things. Under Android < v23 you will simply get a granted response immediately as the user should have agreed to access when they installed the application with the READ_CALENDAR permission. On iOS and Android v23+ the user may get a permissions dialog asking for the application to use the calendar which the user can then deny or grant.

     Calendar.service.addEventListener( AuthorisationEvent.CHANGED, calendar_authorisationChangedHandler );
     
     switch (Calendar.service.authorisationStatus())
     {
         case AuthorisationStatus.AUTHORISED:
             trace( "AUTHORISED" );
             break;
         
         case AuthorisationStatus.SHOULD_EXPLAIN:
         case AuthorisationStatus.NOT_DETERMINED:
             trace( "REQUEST ACCESS" );
             Calendar.service.requestAccess();
             return;
     
         case AuthorisationStatus.RESTRICTED:    
         case AuthorisationStatus.DENIED:
         default:
             trace( "ACCESS DENIED" );
     }
     
     ...
     
     private function calendar_authorisationChangedHandler( event:AuthorisationEvent ):void
     {
         trace( Calendar.service.authorisationStatus() );
     }

Retrieve calendars

You can retrieve a list of the available calendars that the user has on their device by calling the getCalendars function.

     var calendars:Array = Calendar.service.getCalendars();
     for each (var calendar:CalendarObject in calendars)
     {
             trace( "CALENDAR: ["+calendar.id+"] "+calendar.name );
     }

This functionality is mainly used to retrieve a list of calender IDs which can be used in the event creation calls to place an event in a specific calendar. If you don't specify a calendar, the user's default calendar will always be used for event addition.

Retrieve events

Retrieving events is as simple as calling the getEvents function, with your required start and end date. You can simply pass new Date() if you wish to retrieve all events.

     var events:Array = Calendar.service.getEvents( new Date(), new Date() );
     for each (var evt:EventObject in events)
     {
         trace( evt.title );
         for each (var alarm:CalendarEventAlarm in evt.alarms)
         {
             trace( "\tALARM: "+alarm.offset );
         }
     }

Adding an event

There are two main methods to add an event:

adding an event directly with addEvent
displaying a dialog to allow a user to change properties of the event with addEventWithUI

The first step to either method is to create an event object populated with all the information about the calendar event you require.

     var e:EventObject = new EventObject();
     e.title = "Test title now";
     e.startDate = new Date();
     e.endDate = new Date();
     e.endDate.hours = e.endDate.hours+1;

You can add an alarm to an event by adding a CalendarEventAlarm to the alarms array of the event. Please note that alarms may not be automatically added to an event if you use the addEventWithUI function to add an event. The user has the control to add their own events in this case.

     var a:CalendarEventAlarm = new CalendarEventAlarm();
     a.offset = 5;
     
     e.alarms.push( a );

You can add recurrence to an event by adding a recurrence rule to the recurrenceRules array of the event. See the Recurrence class documentation for more details on the recurrence properties.

     var r:Recurrence = new Recurrence();
     r.endCount = 5;
     r.interval = 1;
     r.frequency = Recurrence.FREQUENCY_DAILY;
     
     e.recurrenceRules.push( r );

The addEvent function allows you to add an event directly to the calendar without any user interaction.

     Calendar.service.addEvent( e );

The addEventWithUI function is a user friendly way of adding an entry to a calendar. It presents the user with a dialog allowing them to modify the contents of the event before the event is saved to the selected users calendar. The user may also cancel the event allowing them the ability to override the event addition.

     Calendar.service.addEventListener( CalendarStatusEvent.UI_SAVE,   calendar_uiHandler, false, 0, true );
     Calendar.service.addEventListener( CalendarStatusEvent.UI_CANCEL, calendar_uiHandler, false, 0, true );
     
     Calendar.service.addEventWithUI( e );
     
     private function calendar_uiHandler( event:CalendarStatusEvent ):void
     {
         switch (event.type)
         {
             case CalendarStatusEvent.UI_SAVE:
                 // Handle a save event
                 break;
                  
             case CalendarStatusEvent.UI_CANCEL:
                  // Handle a cancel event
                 break;
         }
     }

We suggest you use the addEventWithUI version of the function to allow the user any personalisation of the event, and you'll receive UI events informing whether the event was saved or cancelled.

iOS

Once the user has denied your application access to the calendar you can direct them to the following location to get them to allow access for your application.

	 Settings / Privacy / Calendars / YOUR APPLICATION Toggle

During testing it is useful to clear the current user's calendar permissions and make the security request dialog appear again you can clear the settings by going to:

	 Settings / General / Reset / Reset Location & Privacy

Android

On Android, the extension uses the new Android 4.0 Calendar API, which means that it will only work on on devices that support the Android SDK v14 or higher. The isSupported flag represents this requirement.

You need to ensure you have the following permissions in your manifest node of your manifest additions in your application descriptor.

 
     <manifestAdditions><![CDATA[
         <manifest android:installLocation="auto">
             <uses-permission android:name="android.permission.READ_CALENDAR"/>
             <uses-permission android:name="android.permission.WRITE_CALENDAR"/>
         </manifest>
     ]]></manifestAdditions>

If you need to receive UI events (save and cancel) from the UI facilities then you additionally need to add the following application node and activity to the manifest.

 
     <manifestAdditions><![CDATA[
         <manifest android:installLocation="auto">
             <uses-permission android:name="android.permission.READ_CALENDAR"/>
             <uses-permission android:name="android.permission.WRITE_CALENDAR"/>
             <application>
                 <activity android:name="com.distriqt.extension.calendar.activities.CalendarAddEventWithUIActivity" android:theme="&android:style/Theme.Translucent.NoTitleBar"></activity>
                 <activity android:name="com.distriqt.extension.calendar.activities.CalendarEditEventWithUIActivity" android:theme="&android:style/Theme.Translucent.NoTitleBar"></activity>
             </application>
         </manifest>
     ]]></manifestAdditions>

	Property	Defined By
		implementation : String [read-only] The implementation currently in use.	Calendar
		isSupported : Boolean [static] [read-only] Whether the current device supports the extensions functionality	Calendar
		nativeVersion : String [read-only] The native version string of the native extension.	Calendar
		service : Calendar [static] [read-only] The singleton instance of the Extension class.	Calendar
		version : String [read-only] The version of this extension.	Calendar

	Method	Defined By
		Calendar() Constructor You should not call this directly, but instead use the singleton access	Calendar
		addEvent(event:EventObject):int Adds an event to the default calendar without presenting any form of UI.	Calendar
		addEventWithUI(event:EventObject):void This function will create an event in the user's calendar and show a UI element to allow them to edit it before saving Any of the elements you set on the EventObject will be prepopulated in the UI presented to the user.	Calendar
		authorisationStatus():String Retrieves the current authorisation status of this application.	Calendar
		dispose():void Disposes the extension and releases any allocated resources.	Calendar
		editEventWithUI(eventId:String, editable:Boolean = true):Boolean Displays a dialog to allow the user to edit the specified event.	Calendar
		getCalendars():Array Retrieves an array of the available user calendars on the device in the form of an Array of CalendarObject.	Calendar
		getEvents(from:Date = null, to:Date = null, calendarId:String):Array Returns an array of calendar events within the date range.	Calendar
		hasAccess():Boolean Helper method to determine if the current application has access to the user's photo library	Calendar
		init(key:String):void Deprecated: You no longer need to use an application key [static] Initialises the extension class for use with the provided key.	Calendar
		removeEvent(event:EventObject):Boolean Removes the specified event.	Calendar
		requestAccess():Boolean Initialises and requests access to the calendar.	Calendar
		updateEvent(event:EventObject):Boolean Allows you to update the details of an event.	Calendar

Summary	Defined By
authorisation:changed	Dispatched when the user changes the authorisation status.	Calendar
calendar:ui:cancel	Dispatched when the user presses Cancel on a UI element, i.e.	Calendar
calendar:ui:delete		Calendar
calendar:ui:save	Dispatched when the user presses Save on a UI element, i.e.	Calendar

	Constant	Defined By
		EXT_CONTEXT_ID : String = com.distriqt.Calendar [static]	Calendar
		VERSION : String = 5.1.0 [static]	Calendar

Property Detail

implementation

property

implementation:String [read-only]

The implementation currently in use. This should be one of the following depending on the platform in use and the functionality supported by this extension:

Android
iOS
default
unknown

Implementation
public function get implementation():String

isSupported

property

isSupported:Boolean [read-only]

Whether the current device supports the extensions functionality

Implementation
public static function get isSupported():Boolean

nativeVersion

property

nativeVersion:String [read-only]

The native version string of the native extension.

Implementation
public function get nativeVersion():String

service

property

service:Calendar [read-only]

The singleton instance of the Extension class.

Implementation
public static function get service():Calendar

version

property

version:String [read-only]

The version of this extension.

This should be of the format, MAJOR.MINOR.BUILD

Implementation
public function get version():String

Constructor Detail

Calendar

()

Constructor

public function Calendar()

Constructor You should not call this directly, but instead use the singleton access

Method Detail

addEvent

()

method

public function addEvent(event:EventObject):int

Adds an event to the default calendar without presenting any form of UI.

All of the elements of the event must already be set before passing to this function.

Parameters

event:EventObject — The EventObject to add to the calendar

Returns

int

addEventWithUI

()

method

public function addEventWithUI(event:EventObject):void

This function will create an event in the user's calendar and show a UI element to allow them to edit it before saving

Any of the elements you set on the EventObject will be prepopulated in the UI presented to the user.

Android

Please note that under Android alarms cannot be automatically set when using the UI to create an event. They can only be set when using the #addEvent function directly.

If you wish to receive UI events from this process you need to have added the manifest additions specified in the main documentation.

Parameters

event:EventObject — The initial values to populate the UI with

authorisationStatus

()

method

public function authorisationStatus():String

Retrieves the current authorisation status of this application.

There are several possible values as defined in the AuthorisationStatus class.

Returns

String — The AuthorisationStatus string

dispose

()

method

public function dispose():void

Disposes the extension and releases any allocated resources. Once this function has been called, a call to init is neccesary again before any of the extensions functionality will work.

editEventWithUI

()

method

public function editEventWithUI(eventId:String, editable:Boolean = true):Boolean

Displays a dialog to allow the user to edit the specified event.

You'll receive the same events as with an add event UI, i.e. CalendarStatusEvent.UI_SAVE etc. Note though that you may receive the UI cancel event even when a user presses save/done if they didn't make any changes to the event.

Parameters

	`eventId:String` — The ID of the event to edit

	`editable:Boolean` (default = `true`) — [Unused]

Returns

Boolean — true if successful and false otherwise

See also

getEvents

getCalendars

()

method

public function getCalendars():Array

Retrieves an array of the available user calendars on the device in the form of an Array of CalendarObject.

Returns

Array — An array of CalendarObject

getEvents

()

method

public function getEvents(from:Date = null, to:Date = null, calendarId:String):Array

Returns an array of calendar events within the date range.

Note: The calendar ID function is currently not implemented on iOS

Parameters

	`from:Date` (default = `null`) — The date to start the event search from

	`to:Date` (default = `null`) — The date to perform the event search to

	`calendarId:String` — The calendar ID to query, if empty all calendars available are queried

Returns

Array — An array of EventObject instances

hasAccess

()

method

public function hasAccess():Boolean

Helper method to determine if the current application has access to the user's photo library

Returns

Boolean

init

()

method

public static function init(key:String):void

Deprecated: You no longer need to use an application key

Initialises the extension class for use with the provided key.

Parameters

key:String

removeEvent

()

method

public function removeEvent(event:EventObject):Boolean

Removes the specified event. You'll need to ensure the event is valid for this function to work correctly. These can be retrieved by a call to getEvents.

Parameters

event:EventObject

Returns

Boolean — true if the event was successfully removed and false otherwise

requestAccess

()

method

public function requestAccess():Boolean

Initialises and requests access to the calendar. This may display a security box under iOS and Android v23+

iOS: On first call (or if the privacy has been reset) this will cause the display of a dialog requesting the user authorise your application to have access to the user's calendar.

This will always dispatch one of the access status events, indicating if your application has access to the calendar. You should implement listeners for the access events and respond accordingly.

Returns

Boolean

updateEvent

()

method

public function updateEvent(event:EventObject):Boolean

Allows you to update the details of an event. You should have previously retrieved the event using getEvents and have a valid system event ID for the event before this call will work.

Important: If your app modifies a user's Calendar database, it must get confirmation from the user before doing so. An app should never modify the Calendar database without specific instruction from the user.

Parameters

event:EventObject — The updated event to save

Returns

Boolean — true if successful and false otherwise

See also

getEvents

Event Detail

authorisation:changed

Event

Event Object Type: com.distriqt.extension.calendar.events.AuthorisationEvent
AuthorisationEvent.type property = com.distriqt.extension.calendar.events.AuthorisationEvent.CHANGED

Dispatched when the user changes the authorisation status. The status will indicate the new authorisation status.

calendar:ui:cancel

Event

Event Object Type: com.distriqt.extension.calendar.events.CalendarStatusEvent
CalendarStatusEvent.type property = com.distriqt.extension.calendar.events.CalendarStatusEvent.UI_CANCEL

Dispatched when the user presses Cancel on a UI element, i.e. the addEventWithUI functionality.

The event will not be saved or appear in the calendar

calendar:ui:delete

Event

Event Object Type: com.distriqt.extension.calendar.events.CalendarStatusEvent
CalendarStatusEvent.type property = com.distriqt.extension.calendar.events.CalendarStatusEvent.UI_DELETE

calendar:ui:save

Event

Event Object Type: com.distriqt.extension.calendar.events.CalendarStatusEvent
CalendarStatusEvent.type property = com.distriqt.extension.calendar.events.CalendarStatusEvent.UI_SAVE

Dispatched when the user presses Save on a UI element, i.e. the addEventWithUI functionality.

If this event is receieved the previous event should now be in the users calendar

This event is not functioning with recent updates to the Android calendar application due to a bug in the activity process. We're working on a solution but currently do not rely on this event.

Constant Detail

EXT_CONTEXT_ID

Constant

public static const EXT_CONTEXT_ID:String = com.distriqt.Calendar

VERSION

Constant

public static const VERSION:String = 5.1.0

Mon Jan 16 2023, 03:32 PM +10:00

distriqt // Calendar Native Extension Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Calendar	Properties \| Methods \| Events \| Constants