Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

RhoEvent API

Access a device’s calendar and events.

Note: In Android Device’s, Calendar event will only be created if the calendar is synced with atleast one mail account.

For examples on how to use the RhoEvent API, see the view and controller in the /app/Calendar folder in the System API Samples application.

Enabling the Calendar

To use the RhoEvent API, you need to enable read and write for the calendar on the device. Do this by adding that capability to the build.yml file:

capabilities:
  - calendar

Check if the device has a calendar:

System.get_property('has_calendar')

find

Returns events in the device calendar.

Return a hash of hashes: a hash of all the events in the calendar (each event is stored in a hash).

Rho::RhoEvent.find(:all)

Return a hash of all the properties of the calendar event identified by this id.

Rho::RhoEvent.find(@params['id'])

Return a hash of hashes: a hash of the events in the calendar (each event is stored in a hash) in the device calendar within a specified range.

Rho::RhoEvent.find(:all, :start_date, :end_date, :find_type, :include_repeating)
:all Search all the events.
:start_date The start date of the range to search.
:end_date The end date of the range to search.
:find_type 'starting' - searches for events starting between start_date and end_date. 'ending' - searches for events ending between start_date and end_date. 'occurring' - searches for events that have any part of the event occurring during the period specified by start_date and end_date.
:include_repeating true - include repeating occurrences of an event in the search; false - do not include repeating occurrences, only search on the event start and end values.

Code sample:

start = Time.utc(2010, 'jan', 1, 0, 0, 0)
finish = Time.utc(2012, 'dec', 31, 23, 59, 59)
@@events = Rho::RhoEvent.find(:all, :start_date => start, 
    :end_date => finish, :find_type => 'starting', 
    :include_repeating => true)

create!

Create a new event in the calendar, setting the properties of the event (excluding id, which is generated) from the passed parameter hash, and save the created calendar event (create). Return a hash of all the properties of the created event, including the id property.

Rho::RhoEvent.create!(event_hash)
event_hash a hash of the properties for the new event.

update_attributes

Find the event in the calendar (the event id is passed in the event_hash), update the properties for that event, and save the event to the calendar.

Rho::RhoEvent.update_attributes(event_hash)
event_hash a hash of the updated properties for the event.

destroy

Remove this event from the calendar.

Rho::RhoEvent.destroy(id)
id remove the event identified by this id from the calendar.

get_authorization_status

Get the authorization status.

Rho::RhoEvent.get_authorization_status

Event Hash Properties

The event properties for the calendar are stored in a hash. The event hash (or a hash of event hashes) is returned by the find and create methods.

id id for this event.
title String. The event title.
location String. The event location.
notes String. Notes added to this event.
start_date Start date for this event in Time.utc format.
end_date End date for this event in Time.utc format.
recurrence (Blackberry, Windows, iOS, Android) hash of recurrence properties. See listings below.
reminder (Blackberry and Windows only) int. event reminder in minutes.
privacy (Blackberry and Windows only) 'public', 'private', or 'confidential'.
canceled (iPhone and Android only). True if the event is canceled.
organizer (iPhone and Android only) String. The event organizer.
attendees (iPhone and Android only) String. The attendees.
last_modified (iPhone and Android only) Datetime when the event was last modified.

Recurrence Hash Properties

Recurrence properties are grouped in a separate hash stored as a single property in the event hash (event[Rho::RhoEvent::RECURRENCE]).

Recurrence Properties Hash for Blackberry and Windows

For Blackberry and Windows, the recurrance hash has these properties.

recurrence true if this event recurs; false otherwise.
frequency 'daily', 'weekly', 'monthly', 'yearly'
interval Used with frequency. The number of intervals in this frequency. {'frequency'=>'daily', "interval"=>2 } means that event will be 1, 4, 7, etc.
end_date End date for this recurrence in Time.utc format.
days Array of 7 items, representing Mon-Sun. Value of 1 means event is triggered.
months Array of 12 items, representing Jan-Dec.
weeks Array of 5 items, representing first-fifth.
count he number of times this event will occur.
day_of_month Integer. 1-31.

Recurrence Properties Hash for iOS and Android

For iOS and Android, the recurrance hash has these properties.

recurrence true if this event recurs; false otherwise.
frequency 'daily', 'weekly', 'monthly', 'yearly'
interval
end_date End date for this recurrence in Time.utc format.
count The number of times this event will occur.
end date/time in Time.utc format beyond the last event occurrence but within the same day.

Event Property Names

Here is a list of helper constants defined in Rho::RhoEvent which can be used to address event values, and used as a predefined set of frequency values.

  • ID
  • TITLE
  • CANCELED
  • ORGANIZER
  • START_DATE
  • END_DATE
  • LAST_MODIFIED
  • LOCATION
  • NOTES
  • PRIVACY
  • REMINDER
  • RECURRENCE
  • RECURRENCE_FREQUENCY
  • RECURRENCE_FREQUENCY_DAILY
  • RECURRENCE_FREQUENCY_WEEKLY
  • RECURRENCE_FREQUENCY_MONTHLY
  • RECURRENCE_FREQUENCY_YEARLY
  • RECURRENCE_INTERVAL
  • RECURRENCE_COUNT
  • RECURRENCE_END
  • RECURRENCE_DAYOFMONTH
  • RECURRENCE_MONTHS
  • RECURRENCE_DAYS
Back to Top