S60 Platform: Calendar Interim API Example v1.1
--------------------------------------------------

This C++ application demonstrates the usage of the Calendar Interim API (also known as the CalInterim API) by adding and modifying anniversary entries. The example has been updated to be compatible with S60 5th Edition and Touch UI.



--------------------------------------------------------------------------------

PREREQUISITES

Symbian C++ basics

--------------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

CCalendarAPIexampleEngine class contains the logic of the application for 
creating, modifying, and deleting calendar entries (in this case, anniversaries).

Important Symbian OS classes: CCalEntry, CCalEntryView, CCalInstance, CCalInstanceView, CCalAlarm, CCalSession, 
MCalProgressCallBack.


--------------------------------------------------------------------------------

KNOWN ISSUES

Note that you cannot save the event if either the anniversary itself or the alarm
is marked to occur in the past.

If the gap between the anniversary in the future and the alarm is more than one
month, the alarm is not played (this applies to the preinstalled calendar, too).

Alarms do not work properly in the emulator.

    
--------------------------------------------------------------------------------

TOUCH UI SUPPORT
 
The EEventItemDoubleClicked pointer event must be handled in the 
MEikListBoxObserver::HandleListBoxEventL() method. In this example application, the event listening has been added into the CCalendarAPIexampleSearchContainer::HandleListBoxEventL() and CCalendarAPIexampleEntriesContainer::HandleListBoxEventL() methods. Note that you can also keep the EEventEnterKeyPressed event listening to support devices with a keypad.

CAknSettingItemList handles its listbox events in 
CAknSettingItemList::HandleListBoxEventL() and you should not override it.

Note that while no S60 5th Edition-specific APIs are used, the same build of the application installs and runs in S60 3rd Edition and S60 5th Edition devices. The installation package delivered in this example package has been created with S60 3d Edition, MR SDK.


--------------------------------------------------------------------------------

RUNNING THE EXAMPLE

When the application is started, choose the time frame for which you want to search
anniversaries. If you want to add an anniversary, choose it from the Options menu.

The alarm must be after the current time 
(check your emulator date/time settings) and
before the actual anniversary (during the same day or before).

When changing the date of the anniversary, the alarm offset will not be recalculated 
so the time between the alarm and the anniversary remains the same.

--------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

Steps for building and installing the application to a device depend on the S60 platform version:

--Mobile device 
    cd to /CalendarExample/group
    bldmake bldfiles
    abld build gcce urel
    cd to /CalendarExample/sis
	--- for (S60 3rd Edition)
    Edit CalendarExample_3_0_v1_1.pkg's paths to match those on your system.
    makesis CalendarExample_3_0_v1_1.pkg
	--- for (S60 5.2 Edition)
    Edit CalendarExample_S60_5_2_v_1_2.pkg's paths to match those on your system.
    makesis CalendarExample_S60_5_2_v_1_2.pkg CalendarExample_S60_5_2_v_1_2.sis
    
    Sign the SIS package 
      - See the SDK Help for information about self-signed .sis packages, or
        www.symbiansigned.com for information about Developer Certificates.

    Install the signed .sis file to an S60 3rd Edition device or S60 5.2 edition device.

    If you get a "Certificate error" during the installation of a self-signed 
    package, check that App.Manager -> Settings -> Software Installation is 
    set to "All". 
    
--Emulator (WINSCW)
    cd to /CalendarExample/group
    bldmake bldfiles
    abld build winscw udeb
    Start the emulator.
    
--------------------------------------------------------------------------------

COMPATIBILITY
S60 5.2 Edition 
S60 5th Edition
S60 3rd Edition, Feature Pack 2
S60 3rd Edition, Feature Pack 1
S60 3rd Edition

TESTED WITH Nokia 5800 XpressMusic, Nokia E61i, Nokia E90 Communicator, and Nokia N95.

Created / tested with S60 3rd Edition MR SDK and S60 5th Edition SDK.

--------------------------------------------------------------------------------

IMPROVEMENT IDEAS

The examples flow of execution may be a bit hard to follow. It would be a good idea
to fully split the engine from the GUI codes. Also to better demonstrate the Calendar Interim API,
the helper class (CCalHelperEntry) should be removed and the CCalEntry and
CCalInstance classes should be used directly.

--------------------------------------------------------------------------------

VERSION HISTORY     

1.2 Supoort single click feature added.
1.1 Support for S60 5th Edition and Touch UI added.
1.0 First release. The functionality of the S60 1st/2nd Edition: Calendar API Example published 
earlier is recoded to S60 3rd Edition using the Calendar Interim API.

Note that a separate example on the usage of the Agenda Model for S60 1st and 2nd Edition 
(S60 1st/2nd Edition: Agenda Model API Example) is also available at www.forum.nokia.com.

--------------------------------------------------------------------------------
ADDITIONAL DOCUMENTATION

Further information on the usage of Calendar Interim API is provided in the document Migration Guide for 
Symbian OS v9.1 Group Scheduling Interim APIs. It is available in the S60 3rd Edition MR SDK 
(...\S60Doc\symbianos_interim_api_migration.pdf).

--------------------------------------------------------------------------------
EVALUATE THIS RESOURCE

Please spare a moment to help us improve documentation quality and recognize the examples you find most valuable, 
by rating this resource at 
http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=18bc940d-2f0f-420d-b658-a50d2b860242/S60_Platform_Calendar_Interim_API_Example_v1_1_en.zip.




