Class CAgnModel

CAgnModel

Support

Supported from 5.0

Description

The instance agenda model.

This should be used by applications which have a user interface because of repeating entries. In the entry model, a repeating entry is represented as a single entry with a set of repeat details, but for a user interface this representation is insufficient: a repeating entry needs to be presented to the user as if it consists of individual entries, one on each date on which a repeat occurs. In the instance model, a repeating entry is represented by a number of instances, one for each date and time on which a repeat occurs.

A view should generally deal with instances not entries. It should never call UpdateEntryL() or DeleteEntryL() and will very rarely (if at all) call FetchEntryL(). Instead, it should use the instance model and call UpdateInstanceL(), DeleteInstanceL() or FetchInstanceL(). An exception to this is when a new entry is added to the agenda model. Because it does not have an instance date at this point, the function to use is CAgnModel::AddEntryL().

Derivation

CAgnEntryModel Provides the interface through which the data stored in an agenda file can be accessed CAgnIndexedModel Indexed agenda model CAgnModel The instance agenda model CBase Base class for all classes to be instantiated on the heap MAgnActiveStep Base class used in the derivation of CAgnEntryModel

Defined in CAgnModel:
AddEntryL(), AddTodoListL(), CutInstanceL(), DeleteInstanceL(), DeleteTodoListL(), FetchInstanceL(), FetchInstanceLC(), FindNextInstanceL(), FindPreviousInstanceL(), NewL(), NextDayWithInstance(), PopulateDayDateTimeInstanceListL(), PopulateDayInstanceListL(), PopulateMonthInstanceListL(), PopulateSymbolInstanceListL(), PopulateTodoInstanceListL(), PreviousDayWithInstance(), UpdateInstanceL(), UpdateTodoListL()

Inherited from CAgnEntryModel:
Anonymous, BufferedDeleting(), BufferedStoring(), Cancel(), ChangeTodoListOrderL(), ChangeTodoOrderL(), CharFormatLayer(), CheckNotifier(), CommitL(), CreateL(), CutEntryL(), DefaultAnnivDisplayTime(), DefaultDayNoteDisplayTime(), DefaultDisplayTime(), DefaultEventDisplayTime(), DeleteEntryL(), DeleteLiteEntry(), EAddTodoListAtEnd, EBlocked, EClient, ENoFile, ENormal, EOk, ESaveAsCallBackHigh, ESaveAsCallBackLow, ESaveAsCallBackMedium, EServer, ExportVCalL(), FetchEntryL(), FetchTodoListL(), FileVersion(), FlushAndCommitL(), GetDayListFromExtractorL(), GetEmbeddedStore(), GetInstanceExtractorL(), GetReadStreamL(), GetSymbolInstanceList(), GetSymbolInstanceListL(), ImportVCalL(), IsClient(), IsInUseObserverController(), IsValidL(), LastSynchronizedDateL(), ModelVersion(), NumberOfObserversLoaded(), NumberOfObserversRegistered(), ObserverController(), ParaFormatLayer(), PasteEntryL(), PeekAtDeletedTodoListList(), PeekAtTodoListList(), PictureFactory(), PopulateTodoListNamesL(), RegisterAlarm(), RegisterObserverL(), RegisteredAlarm(), RegisteredIndex(), RollbackL(), SaveAsL(), SaveTodoListsL(), Server(), SetDefaultAnnivDisplayTime(), SetDefaultDayNoteDisplayTime(), SetDefaultEventDisplayTime(), SetEntryServer(), SetLastSynchronizedDateL(), SetMode(), SetParaAndCharFormatLayersL(), SetPictureFactory(), SetServer(), State(), StreamId(), StreamStore(), TModelMode, TSaveAsCallBackFrequency, TState, TodoListCount(), TodoListIdsL(), UnregisterObserverL(), UpdateDefaultEntryTimes(), UpdateEntryL()

Inherited from CAgnIndexedModel:
EAll, ECopy, ECopyAndDelete, ECrossedOut, EDelete, EDontMergeTodoListSettings, EExceptCrossedOut, EMergeCallBackHigh, EMergeCallBackLow, EMergeCallBackMedium, EMergeTodoListSettings, EOpenCallBackHigh, EOpenCallBackLow, EOpenCallBackMedium, ETidyByDateCallBackHigh, ETidyByDateCallBackLow, ETidyByDateCallBackMedium, ETidyByTodoListCallBachHigh, ETidyByTodoListCallBackHow, ETidyByTodoListCallBackMedium, EntryCount(), GetLiteEntryL(), IndexCount(), Indexes(), MergeL(), OpenL(), TMergeCallBackFrequency, TMergeTodoListSettings, TOpenCallBackFrequency, TTidyByDateCallBackFrequency, TTidyByTodoListCallBackFrequency, TTidyDirective, TTidyTodoListHow, TidyByDateL(), TidyByTodoListL()

Inherited from CBase:
operator new()

static CAgnModel* NewL(MAgnModelStateCallBack* aStateCallBack);

Description

Allocates and constructs an instance model, optionally with a pointer to a state callback object.

Parameters

MAgnModelStateCallBack* aStateCallBack If not NULL, provides a callback function which notifies the user that the model is about to change state.

Return value

CAgnModel* Pointer to the newly created instance model.

CAgnEntry* FetchInstanceL(const TAgnInstanceId& aInstanceId) const;

Description

Fetches an instance identified by aInstanceId from the model.

Parameters

const TAgnInstanceId& aInstanceId The ID of the instance.

Return value

CAgnEntry* Pointer to the instance.

Leave codes

KErrNotFound The instance cannot be found, or the instance date falls on a repeat exception.

CAgnEntry* FetchInstanceLC(const TAgnInstanceId& aInstanceId) const;

Description

Fetches an instance identified by aInstanceId from the model. The instance is left on the clean-up stack.

Parameters

const TAgnInstanceId& aInstanceId The ID of the instance.

Return value

CAgnEntry* Pointer to the instance.

Leave codes

KErrNotFound The instance cannot be found, or the instance date falls on a repeat exception.

TAgnEntryId AddEntryL(CAgnEntry* aEntry,TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId());

Description

Adds an entry to the model. If the entry is alarmed, the next due alarm is queued with the alarm server. The date/time of the entry's creation is set to the current date/time.

Notes

If the entry is a to-do, it must specify a to-do list ID to identify the to-do list to which it should be added.

The function notifies the model's observer controller that an entry has been added.

Parameters

CAgnEntry* aEntry Pointer to the entry to add. TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId() If the new entry is a to-do, this argument is used to specify the position in the to-do list at which aEntry is added.aEntry is inserted at the position immediately before the entry with the ID specified. If this ID is null, (the default),aEntryis added at the end of the to-do list. The value is ignored if the entry is not a to-do.

Return value

TAgnEntryId The entry ID for aEntry.

TAgnEntryId UpdateInstanceL(CAgnEntry* aInstance,TAgnWhichInstances aWhichInstances=EAllInstances,TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId());

Description

Updates one or more instances of an entry in the model.

If aInstance was originally repeating, aTAgnWhichInstances value should be supplied. PassingECurrentInstance, ECurrentAndFutureInstancesorECurrentAndPastInstances will result in the creation of a new entry.

If during the update process, the original entry's ID is changed, the new ID is returned by this function. Otherwise, the function returns a NULL entry ID.

If aInstance was originally repeating and still is then:

• if aWhichInstances is ECurrentInstance then the user has edited one instance of a repeating entry, therefore the changes will only apply to this instance, which becomes a new exception entry.

• if aWhichInstances isECurrentAndFutureInstancesorECurrentAndPastInstances then the changes apply to a subset of the instances. In this case, a new repeating entry is created. A new entry may also be created if the changes apply to all of a repeating entry's instances except one, which will become a new non-repeating entry.

• if aWhichInstances is EAllInstances then the entry's new details are written to the store.

If aInstance was originally repeating but no longer is then its new details replace the existing details in the store.

If aInstance was originally non-repeating theaWhichInstances value is redundant. In this case, the new details simply replace the existing details.

Should this function leave (e.g. out of memory) then the contents ofaInstance should be considered to be in an unknown state and the entry should be discarded.

Parameters

CAgnEntry* aInstance Pointer to the instance to update. TAgnWhichInstances aWhichInstances=EAllInstances If aInstance is repeating, indicates which instances of the entry are to be affected by the update. TAgnEntryId aTodoPositionReferenceId = AgnModel::NullId() If aInstance is a to-do which is being moved from one to-do list to another then this specifies its position in the new list.aInstance is inserted at the position immediately before the entry with the ID specified. If this ID is NULL, (the default),aInstance is appended to the to-do list. The value is ignored ifaInstance is not a to-do, or if it is not being moved to another to-do list.

Return value

TAgnEntryId The new entry ID of aInstance if it was changed during the update. Otherwise, a NULL entry ID.

TAgnEntryId DeleteInstanceL(CAgnEntry* aInstance,TAgnWhichInstances aWhichInstances=EAllInstances);
TAgnEntryId DeleteInstanceL(const TAgnInstanceId& aInstanceId,TAgnWhichInstances aWhichInstances=EAllInstances);

Description

Deletes one or more instances of an entry from the model. The instance can either be passed to the function as a pointer, or can be identified by its instance ID.

If the instance is not repeating then it is simply removed from the store.

If the instance is repeating, an enumeration (TAgnWhichInstances) should be specified to indicate which instances are to be deleted. The entry's repeat definition may need to be changed.

• if aWhichInstances is EAllInstances then the entry is deleted from the store.

• if aWhichInstances is ECurrentInstance then before the instance can be deleted from the store an exception must first be added to the entry's list of exceptions.

• if aWhichInstances isECurrentAndFutureInstancesthen the entry's repeat end date is set to be that of the previous instance to the one being deleted.

• if aWhichInstances isECurrentAndPastInstancesthen the entry's repeat start date is set to be that of the next instance after the one being deleted.

If after this function is called, the entry has only one instance remaining, the instance is converted into a non-repeating entry. If this is the case, its ID is changed and the new ID is returned by the function. If not, the function returns a NULL ID.

Parameters

CAgnEntry* aInstance If specified, a pointer to the instance to delete. const TAgnInstanceId& aInstanceId If specified, the ID of the instance to delete. TAgnWhichInstances aWhichInstances=EAllInstances If the entry is repeating, indicates which instances of the entry are to be affected by the delete.

Return value

TAgnEntryId The entry's ID (this may have been changed by the function).

Leave codes

KErrNotFound When using the variant of the function which takes an instance ID parameter, no entry instance can be found which matches the ID.

TAgnEntryId CutInstanceL(CAgnEntry* aInstance,TAgnWhichInstances aWhichInstances=EAllInstances);
TAgnEntryId CutInstanceL(const TAgnInstanceId& aInstanceId,TAgnWhichInstances aWhichInstances=EAllInstances);

Description

Cuts one or more instances of an entry from the model. The instance can either be passed to the function as a pointer, or can be identified by its instance ID.

If the entry is repeating, andaWhichInstancesisEAllInstances, or if the entry is not repeating, after calling this function, no residue of the original entry will remain. In this case,CutEntryL() is called (defined in the base classCAgnEntryModel). Otherwise, this function is the same asDeleteInstanceL().

Parameters

CAgnEntry* aInstance If specified, a pointer to the instance to cut. const TAgnInstanceId& aInstanceId If specified, the ID of the instance to cut. TAgnWhichInstances aWhichInstances=EAllInstances If the entry is repeating, indicates which instances of the entry are to be affected by the cut.

Return value

TAgnEntryId The entry's ID (this may have been changed by the function).

virtual TAgnTodoListId AddTodoListL(CAgnTodoList* aTodoList,TInt aPosition=EAddTodoListAtEnd);

Description

Adds a to-do list to the model and sets the to-do list's position in the model's list of to-do lists.

Parameters

CAgnTodoList* aTodoList Pointer to the to-do list to add. TInt aPosition=EAddTodoListAtEnd Position within the model's list of to-do lists at which to insert the to-do list.

Return value

TAgnTodoListId The to-do list ID.

virtual void DeleteTodoListL(CAgnTodoList* aTodoList);
virtual void DeleteTodoListL(TAgnTodoListId aTodoListId);

Description

Deletes all the to-do entries which belong to a to-do list, then deletes the to-do list itself from the model. The to-do list can either be passed to the function as a pointer, or can be identified by its to-do list ID.

If the model has only one to-do list, this function has no effect.

Notes

The function notifies the model's observer controller that the to-do list has been deleted.

If the to-do list, or any to-do entry in the list, has a positive synchronisation count, the list or entry is marked as having been deleted but is not removed from the store. It is removed from the model's indexes, so is not visible to views, and is added to the model's deleted to-do list.

Parameters

CAgnTodoList* aTodoList If specified, a pointer to the to-do list to delete. TAgnTodoListId aTodoListId If specified, the ID of the to-do list to delete.

virtual void UpdateTodoListL(CAgnTodoList* aTodoList);

Description

Updates a to-do list. A to-do list with the same to-do list ID asaTodoList must already exist in the model, and if so, it is replaced by aTodoList.

Notes

The model's observer controller is notified that the to-do list has been updated.

When a todo list which has previously been marked as deleted is passed to this function, but its synchronisation count is now zero, then it is physically removed from the store and its ID removed from the model's list of deleted to-do lists.

Parameters

CAgnTodoList* aTodoList Pointer to a to-do list object containing the new details.

Leave codes

KErrNotFound aTodoList does not already exist in the model.

void PopulateDayInstanceListL(CAgnDayList<TAgnInstanceId>* aList,const TAgnFilter& aFilter,const TTime& aTodaysDate) const;

Description

Populates a list with instance IDs for a particular day. The entry types of interest may be specified using a filter.

Instances which start on the previous day may be included in the day list if they span midnight.

If the date specified in the day list is invalid, i.e. outside the model's valid range, the function returns with an empty list.

Notes

Instances are sorted by display time. Instances with equal display times are sorted in the following order:

1) to-do entries. Multiple to-do entries with the same display time are ordered by due date, priority then start date

2) anniversaries

3) day notes

4) appointments. Appointments are ordered by start time then end time

Finally if two instances are still the same, then crossed out ones appear after un-crossed out ones.

Parameters

CAgnDayList<TAgnInstanceId>* aList An empty list. Should specify a valid date. On return, contains a list of instance IDs for instances which occur on the specified date. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aTodaysDate Today's date as a TTime. Should be specified to include undated to-do entries in the list.

void PopulateDayDateTimeInstanceListL(CAgnDayDateTimeInstanceList* aList,const TAgnFilter& aFilter,const TTime& aTodaysDate) const;

Description

Populates a list with instance IDs for a particular day. The list also includes the start and end date/time for each instance. The entry types of interest may be specified using a filter.

Instances which start on the previous day may be included in the day list if they span midnight.

If the date specified in the day list is invalid, i.e. outside the model's valid range, the function returns with an empty list.

The instances are sorted according to the same criteria as forPopulateDayInstanceListL().

Parameters

CAgnDayDateTimeInstanceList* aList An empty list. Should specify a valid date. On return, contains a list of instance IDs and start and end dates/times for instances which occur on the specified date. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aTodaysDate Today's date as a TTime. Should be specified to include undated to-do entries in the list.

void PopulateMonthInstanceListL(CAgnMonthInstanceList* aList,const TAgnFilter& aFilter,const TTime& aTodaysDate) const;

Description

Populates a list with instances IDs for a particular month. The entry types of interest may be specified using a filter.

If the year specified in the month list is invalid, i.e. outside the model's valid range, the function returns with an empty list.

The instances are sorted in chronological order.

Parameters

CAgnMonthInstanceList* aList An empty list. Should specify a valid month and year. On return, contains a list of instance IDs for instances which occur in the specified month. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aTodaysDate Today's date as a TTime. Should be specified to include undated to-do entries in the list.

void PopulateTodoInstanceListL(CAgnTodoInstanceList* aList,const TTime& aTodaysDate) const;

Description

Populates a list with instance IDs for a given to-do list. The to-do list of interest is identified by a to-do list ID specified in aList. If aList does not specify a to-do list ID, the function returns with an empty list.

The sort order and whether or not crossed out entries should be included in the list are both specified in the to-do list identified inaList.

Parameters

CAgnTodoInstanceList* aList A to-do instance list. Specifies a to-do list ID. On return, contains a sorted list of to-do instance IDs that match the filter criteria specified in the to-do list. It therefore holds the to-dos that are to be displayed from a particular to-do list at any given time. const TTime& aTodaysDate Today's date as a TTime.

void PopulateSymbolInstanceListL(CAgnSymbolList* aList,const TAgnFilter& aFilter,const TTime& aTodaysDate) const;

Description

Populates a filtered symbol list for the instances which occur within a given month. The year and month of interest should be specified inaList.

A symbol list is a list of the days in a month which have entry symbols. The day is stored as a number (0 to 30) and each day can have a maximum of two symbols. The list is ordered by day number. The symbol list also specifies the month and the year.

If the year specified in the symbol list is invalid, i.e. outside the model's valid range, the function returns with an empty list.

Parameters

CAgnSymbolList* aList Pointer to an existing CAgnSymbolList object. Should specify the year and month of interest. On return, the list contains the entry symbols which belong to instances occuring within the specified month. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aTodaysDate Today's date. Used to determine if undated to-do items should be included in the list.

TTime NextDayWithInstance(const TTime& aToday, const TAgnFilter& aFilter,const TTime& aStartDate) const;

Description

Returns the next date after the date specified on which an instance occurs. The entry types of interest are specified using a filter.

Returns a NULL time if there are no more instances.

Parameters

const TTime& aToday Today's date as a TTime. Used to identify whether or not undated to-dos should be included. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aStartDate The date at which to begin the search.

Return value

TTime The date on which the next instance occurs.

TTime PreviousDayWithInstance(const TTime& aToday, const TAgnFilter& aFilter,const TTime& aStartDate) const;

Description

Returns the nearest preceding date to the date specified on which an instance occurs. The entry types of interest are specified using a filter.

Returns a NULL time if there are no previous instances.

Parameters

const TTime& aToday Today's date as a TTime. Used to identify whether or not undated to-dos should be included. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aStartDate The date at which to begin the search.

Return value

TTime The date on which the previous instance occurs.

void FindNextInstanceL(CAgnDayList<TAgnInstanceId>* aMatchedInstanceList, const TDesC& aSearchText, const TTime& aStartDate, const TTime& aEndDate, const TAgnFilter& aFilter, const TTime& aToday) const;

Description

Populates a day list with instance IDs for instances whose rich text matches a search string. A match is made if the instance's rich text is an exact match for the search string, or is a subset of it.

After a match is made, other instances on that day are searched. When there are no more instances on that day to search, the function returns.

Only dates within the date range specified are searched, and the entry types to be used in the search are specified using a filter.

Parameters

CAgnDayList<TAgnInstanceId>* aMatchedInstanceList Pointer to a day list. On return contains the IDs for all instances matching the search string for a single day. If no matching instances were found, the list returns empty. const TDesC& aSearchText The search string. Has a maximum of 32 characters. const TTime& aStartDate The date at which to begin the search. const TTime& aEndDate The date at which to end the search. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aToday Today's date as a TTime. Used to identify whether or not undated to-dos should be included.

void FindPreviousInstanceL(CAgnDayList<TAgnInstanceId>* aMatchedInstanceList, const TDesC& aSearchText, const TTime& aStartDate, const TTime& aEndDate, const TAgnFilter& aFilter, const TTime& aToday) const;

Description

Populates a day list with instance IDs for instances whose rich text matches a search string. A match is made if the instance's rich text is an exact match for the search string, or is a subset of it.

After a match is made, other instances on that day are searched. When there are no more instances on that day to search, the function returns.

Only dates within the date range specified are searched, and the entry types to be used in the search are specified using a filter.

The search starts at the start date and works backwards, so the start date should be after the end date.

Parameters

CAgnDayList<TAgnInstanceId>* aMatchedInstanceList Pointer to a day list. On return contains the IDs for all instances matching the search string for a single day. If no matching instances were found, the list returns empty. const TDesC& aSearchText The search string. Has a maximum of 32 characters. const TTime& aStartDate The date at which to begin the search. Should be after the end date. const TTime& aEndDate The date at which to end the search. Should be before the start date. const TAgnFilter& aFilter Filters the entry types of interest. const TTime& aToday Today's date as a TTime. Used to identify whether or not undated to-dos should be included.