libcalendareka2.tex

python s60 1.4.5版本的源代码

% Copyright (c) 2006 Nokia Corporation
%
% Licensed under the Apache License, Version 2.0 (the "License");
% you may not use this file except in compliance with the License.
% You may obtain a copy of the License at
%
%     http://www.apache.org/licenses/LICENSE-2.0
%
% Unless required by applicable law or agreed to in writing, software
% distributed under the License is distributed on an "AS IS" BASIS,
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
% See the License for the specific language governing permissions and
% limitations under the License.

\section{\module{calendar for EKA2} ---
  Access to calendar related services}
\label{sec:calendareka2}

\declaremodule{extension}{calendar}
\platform{S60}
\modulesynopsis{A calendar related services package.}

The \module{calendar} module offers an API to calendar services. The 
\module{calendar} module represents a Symbian agenda database as a 
dictionary-like \class{CalendarDb} object, which contains \class{Entry}
objects and which is indexed using the unique IDs of those objects. There 
are five types of entry objects: \class{AppointmentEntry}, 
\class{EventEntry}, \class{AnniversaryEntry}, \class{ReminderEntry},
 and \class{TodoEntry}. 

\class{CalendarDb} objects represent a live view into the database. If an 
entry is changed outside your Python application, the changes are visible 
immediately, and conversely any changes you commit into the database are 
visible immediately to other applications. 

All time parameters use Unix time unless stated otherwise. For more 
information on Unix time, see Section \ref{subsec:datetime}, 
Date and Time.

\subsection{Module Level Functions}
\label{subsec:calendarmodule}
The following free functions - functions that do not belong to any class 
- are defined in the \code{calendar} module:

\begin{funcdesc}{open}{\optional{filename=None, mode=None}}

Opens a calendar database and returns a new \class{CalendarDb} object.

If filename is \code{None}, the default database is opened.

If \var{filename} is given, it should contain drive letter, colon and file's name, 
but no absolute path.

\var{mode} can be:

\begin{itemize}
\item \code{None}: Opens an existing calendar database.
\item \code{'c'}: Opens an existing calendar database, or creates it if it doesn't exist.
\item \code{'n'}: Creates a new, empty calendar database. If \var{filename} exists, the previous contents are erased.
\end{itemize}

\end{funcdesc}

\subsection{CalendarDb Objects}
\label{subsec:calendardb}

Calendar entries are stored in a calendar database. There is 
one default calendar database but more calendar databases can be created by 
invoking \code{open} with parameters \code{'n' }or \code{'c'}. 

\begin{classdesc*}{CalendarDb}
\class{CalendarDb} objects have the following methods:

\begin{methoddesc}[CalendarDb]{add_appointment}{}

Creates and returns a new appointment entry \class{AppointmentEntry}. The 
entry is not added and saved into the database until \code{Entry.commit} is 
called.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{add_event}{}

Creates and returns a new event entry \class{EventEntry}. The entry is not added 
and saved into the database until \code{Entry.commit} is called.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{add_anniversary}{}

Creates and returns a new anniversary entry \class{AnniversaryEntry}. The entry 
is not added and saved into the database until \code{Entry.commit} is called.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{add_todo}{}

Creates and returns new todo entry \class{TodoEntry}. The entry is not added and 
saved into the database until \code{Entry.commit} is called.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{add_reminder}{}

Creates and returns new reminder entry \class{ReminderEntry}. The entry is not added and 
saved into the database until \code{Entry.commit} is called.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{find_instances}{start_date, end_date, search_str=u''\optional{ ,appointments=0,events=0,anniversaries=0,todos=0,reminders=0}}

The parameters for this function include the start date, end date, search 
string, and optional parameters. The optional parameters define the entry 
types to be included into the search. By default all entry types are 
included. Returns a list that contains \class{Entry} instances found in the 
search. An instance is a dictionary that contains the entry ID and the 
datetime value. An entry may have several instances if it is repeated, for 
example once every week, etc. 

In some Nokia models the \code{search\_str} needs to be less or equal to 32 
characters, otherwise an error \code{KErrArgument} or a premature application 
exit (i.e. a panic) might occur.
\end{methoddesc}

\begin{methoddesc}[CalendarDb]{monthly_instances}{month, appointments=0, events=0, anniversaries=0, todos=0, reminders=0}

The parameters for this function include \var{month} (float) and 
optional parameters. The optional parameters define the entry types to be 
returned. Returns a list that contains entry instances occurring during the 
specified calendar month.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{daily_instances}{day, appointments=0, events=0, anniversaries=0, todos=0}

The parameters for this function include \var{day} (float) and 
optional parameters. The optional parameters define the entry types to be 
returned. Returns a list that contains entry instances occurring on the 
specified day.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{export_vcalendars}{(int,...)}

Returns a \code{vcalendar} string that contains the specified entries in 
vCalendar format. The parameter for this function is a tuple that contains 
the entry IDs of the exported entries.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{import_vcalendars}{string}

Imports \code{vcalendar} entries, given in the string parameter, to the 
database. Returns a list that contains the unique IDs of the imported 
entries.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{__delitem__}{id}

Deletes the given calendar \code{Entry} from the database. \code{id} is the 
unique ID of the calendar \code{Entry}.

\end{methoddesc}

\begin{methoddesc}[CalendarDb]{__getitem__}{id}

Returns a calendar \code{Entry} object indicated by the unique ID. The returned 
object can be one of the following: \class{AppointmentEntry}, 
\class{EventEntry}, \class{AnniversaryEntry}, \class{ReminderEntry}, 
or \class{TodoEntry}. \code{id} is the unique ID of the calendar \code{Entry}. 

\end{methoddesc}

\end{classdesc*}

\subsection{Entry Objects}
\label{subsec:entry}

An \class{Entry} object represents a live view into the state of a single 
entry in the database. You can access the entries with an entry's unique ID. 
If you create a new entry using \code{db.add_appointment} etc., it is 
saved into the database only if you call the entry's \code{commit} method. 
In case an entry is already saved into the database, the autocommit mode is 
on by default and all the changes are automatically saved into the database, 
unless you call the entry's \code{begin} method. If you call the entry's 
\code{begin} method, the changes are not saved into the database until you 
call the entry's \code{commit} method. 

Database entries cannot be locked. In other words, other applications are 
able to make changes to the database entries you are using (not directly to 
the \class{EntryObjects} you are using, but to their representation in the 
database) at the same time you are modifying them, even if you use 
\code{begin} and \code{commit} methods. 

\begin{classdesc*}{Entry}
\class{Entry} objects have the following methods and properties:

\begin{memberdesc}[Entry]{content}

Sets or returns the entry's content text (Unicode).

\end{memberdesc}

\begin{methoddesc}[Entry]{commit}{}

Saves the entry or in case of a new entry adds the entry into the database. 
Note that this can be called only in case of a new entry, created with 
\code{db.add_appointment} etc., or after \code{begin} is called. 

\end{methoddesc}

\begin{methoddesc}[Entry]{rollback}{}

Undoes the changes made after last \code{commit}.

\end{methoddesc}

\begin{methoddesc}[Entry]{set_repeat}{dictionary}

Sets the repeat data of the entry. \var{dictionary} is a repeat data dictionary 
that contains all the repeat rules. For more information on repeat rules, see 
Section \ref{subsec:repeat}, Repeat Rules.

\end{methoddesc}

\begin{methoddesc}[Entry]{get_repeat}{}

Returns the repeat data dictionary of the entry.

\end{methoddesc}

\begin{memberdesc}[Entry]{location}

Sets or returns the entry's location data (Unicode), for example meeting 
room information. 

\end{memberdesc}

\begin{methoddesc}[Entry]{set_time}{start\optional{, end}}

Sets the start and end datetime values of the entry (floats). If only one 
parameter is given, the other will have the same value.