Remove some things which makes it hard to understand this paper by a beginner..

1 files changed, 163 insertions, 89 deletions

diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
index 1e43d63..a99b0df 100644
--- a/development/pim/pim_howto/pim_howto.lyx
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -4,58 +4,27 @@
 \begin_preamble
 \fancyhead{}
 \fancyfoot{}
 \fancyhead[LE,RO]{\slshape \leftmark}
 \fancyhead[LO,RE]{\slshape \leftmark}
 \fancyhead[RE,LO]{\thepage}
 %\fancyhead[LO,RE]{}
 % \usepackage{ae}
+\usepackage[T1]{fontenc} 
 \usepackage[bookmarksopen,colorlinks]{hyperref}
 % \pdfoutput=1
 % \pdfcompresslevel=8
 % \pdfinfo{
 % /Title   ClearSim-RealtTime und Andere
 %  /Creator (Tex)
 %  /Author  (Stefan Eilers)
 %  /Subject ()
 %  /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
 % }
-\renewcommand\familydefault{\sfdefault}
-
-\usepackage{multicol}
-\newcommand\NrCol{3}
-\renewenvironment{theindex}
-               {\columnseprule \z@
-                \columnsep 35\p@
-                \section*{\indexname}%
-                \@mkboth{\MakeUppercase\indexname}%
-                        {\MakeUppercase\indexname}%
-                \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
-                \parskip\z@ \@plus .3\p@\relax
-                \let\item\@idxitem}
-               {\clearpage %
-                \end{multicols}}
-
-\renewenvironment{theindex}
-               {\if@twocolumn
-                  \@restonecolfalse
-                \else
-                  \@restonecoltrue
-                \fi
-                \columnseprule \z@
-                \columnsep 35\p@
-                \twocolumn[\refstepcounter{section}%
-                  \section{\indexname}]%
-                \@mkboth{\MakeUppercase\indexname}%
-                        {\MakeUppercase\indexname}%
-                \thispagestyle{plain}\parindent\z@
-                \parskip\z@ \@plus .3\p@\relax
-                \let\item\@idxitem}
-               {\if@restonecol\onecolumn\else\clearpage\fi}
 \end_preamble
 \language american
 \inputencoding default
 \fontscheme ae
 \graphics default
 \float_placement htbp
 \paperfontsize default
 \spacing single 
@@ -77,22 +46,22 @@
 \paperpagestyle fancy
 
 \layout Title
 
 How to use the Opie-Pim API without getting tired!
 \newline 
 (Aka: Hitchhikers Guide Through the Opie-Pim API)
 \newline 
-(Pre V 0.1)
+(V 0.2)
 \layout Author
 
 
 \family sans 
-Stefan Eilers
+Stefan Eilers (stefan@eilers-online.net)
 \layout Section*
 
 
 \family sans 
 Abstract
 \layout Standard
 
 The Opie-Pim API provides a powerfull access interface to the PIM (Personal
@@ -109,16 +78,26 @@ While starting to read the automatically generated API-documentation, the
  user may be confused by a lot of unnecessary classes and details which
  makes the quick start not as easy as possible.
  Due to the fact that a user will not need most of the details, this paper
  should help to start to become confortable with those details he need to
  solve his problems.
 \layout Standard
 
 
+\series bold 
+You will find a more recent version at: 
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apihowto/pim_howto.pdf}
+
+\end_inset 
+
+
+\layout Standard
+
+
 \begin_inset LatexCommand \tableofcontents{}
 
 \end_inset 
 
 
 \layout Chapter
 
 Introduction
@@ -212,34 +191,47 @@ OPimAccessFactory
 \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}
 
 \end_inset 
 
 ).
  This operation is defined like this:
 \layout LyX-Code
 
-T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
+T* defaultAccess ( 
+\newline 
+typename OPimGlobal::PimType type,
+\newline 
+const QString &appName)
 \layout Standard
 
 You just have to add the following lines to your source code to use it (this
  example is for accessing the contact database):
 \layout LyX-Code
 
+\layout LyX-Code
+
 #include <opie2/opimaccessfactory.h>
 \layout LyX-Code
 
 use namespace Opie;
 \layout Standard
 
 [...]
 \layout LyX-Code
 
-OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces
-s( OPimGlobal::CONTACTLIST, "my-app" );
+OPimContactAccess* sourceDB = 
+\newline 
+OPimAccessFactory<OPimContactAccess>::defaultAccess(
+\newline 
+OPimGlobal::CONTACTLIST,
+\newline 
+"my-app" );
+\layout LyX-Code
+
 \layout Standard
 
 If everything works as expected, you will receive a pointer to the contact
  access-class which has to be used for accessing the database.
  Accessing the datebook database works equally
 \begin_inset Foot
 collapsed false
 
@@ -247,25 +239,35 @@ collapsed false
 
 The API will be changed in the future: ODateBookAccess will be renamed to
  OPimEventAccess.
 \end_inset 
 
 :
 \layout LyX-Code
 
-ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
- OPimGlobal::DATEBOOK, "my-app" );
+ODateBookAccess* sourceDB = 
+\newline 
+OPimAccessFactory<ODatebookAccess>::defaultAccess(
+\newline 
+OPimGlobal::DATEBOOK,
+\newline 
+"my-app" );
 \layout Standard
 
 And the same for todo:
 \layout LyX-Code
 
-OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
- OPimGlobal::TODOLIST, "my-app" );
+OPimTodoAccess* sourceDB = 
+\newline 
+OPimAccessFactory<OPimTodoAccess>::defaultAccess(
+\newline 
+OPimGlobal::TODOLIST,
+\newline 
+"my-app" );
 \layout Standard
 
 Using 
 \emph on 
 
 \begin_inset Quotes gld
 \end_inset 
 
@@ -480,52 +482,135 @@ If you want to work with the existing dataset, you need to get a list of
 \end_inset 
 
 allRecords()
 \begin_inset Quotes grd
 \end_inset 
 
  which returns a list of all available records as an 
 \series bold 
-OPimRecordList
+OPimRecordList<T>
 \series default 
  (see 
 \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
 
 \end_inset 
 
 ).
- 
+ This OPimRecordList is a template and should be used with the right class
+ parameter 
+\begin_inset Quotes eld
+\end_inset 
+
+T
+\begin_inset Quotes erd
+\end_inset 
+
+ which is currently one of the following: OPimContact, OPimTodo and OPimEvent.
 \layout LyX-Code
 
-List allRecords();
+OPimRecordList<T> allRecords();
 \layout Standard
 
 In fact, this 
-\emph on 
-List
-\emph default 
+\begin_inset Quotes eld
+\end_inset 
+
+OPimRecordList<T>
+\begin_inset Quotes erd
+\end_inset 
+
  just contains a list of uid's to take care of memory space.
- As every record is identified by an unique identification number which
- is called UID (Unique Identification), these numbers just exists once in
- the database which is currently on access! To receive the real record,
- you have to use the operation 
+ Every record is identified by an unique identification number which is
+ called UID (Unique Identification).
+ These numbers just exists once in the database which is currently on access!
+ To receive the real record, you have to use the operation 
 \begin_inset Quotes gld
 \end_inset 
 
 find()
 \begin_inset Quotes grd
 \end_inset 
 
  with a valid UID as parameter:
 \layout LyX-Code
 
 T find (UID uid);
 \layout Standard
 
+The remaining question is, how to get a valid UID out of a list to use the
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+find()
+\begin_inset Quotes erd
+\end_inset 
+
+ in a correct manner.
+ This could be done by requesting a special element of the list, using the
+ operator[] or by using iterators.
+ The first one would be like this
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+
+Please do not forget to use 
+\begin_inset Quotes eld
+\end_inset 
+
+use namespace Opie;
+\begin_inset Quotes erd
+\end_inset 
+
+ to enable the namespace 
+\begin_inset Quotes eld
+\end_inset 
+
+Opie
+\begin_inset Quotes erd
+\end_inset 
+
+!!
+\end_inset 
+
+:
+\layout LyX-Code
+
+OPimRecordList<OPimContact> list = allRecords();
+\layout LyX-Code
+
+for ( int i = 0; i < list.count(); i++ ){
+\layout LyX-Code
+
+    cout << "The UID is: " << list[i] << endl;
+\layout LyX-Code
+
+}
+\layout Standard
+
+Using the iterator is as easy as the previous one:
+\layout LyX-Code
+
+OPimRecordList<OPimContact> list = allRecords();
+\layout LyX-Code
+
+OPimRecordList<OPimContact>::iterator it;
+\layout LyX-Code
+
+for ( it = list.begin(); it != list.end(); ++it ){
+\layout LyX-Code
+
+    count << "The UID is: " << (*it) << endl;
+\layout LyX-Code
+
+}
+\layout Standard
+
 This is all you need to realize a basic access to the PIM-Databases! The
  next chapter will guide you into more details of the PIM-API.
 \layout Chapter
 
 How to Access PIM-Data: Detailed View
 \layout Standard
 
 As shown in the previous chapter, all we need to access the PIM-Database
@@ -748,31 +833,24 @@ In most cases it is not sufficient to receive just a list of all information
  able to sort it.
  For this kind of exercise we provide some special operations which provide
  searching and sorting in an incremental manner
 \begin_inset Foot
 collapsed false
 
 \layout Standard
 
-FIXME: matchRegexp() does take a list of uid's.
+FIXME: matchRegexp() does not take a list of uid's.
  Therefore it is currently not possible to use it in an incremental manner!
  (se)
 \end_inset 
 
 .
- Therefore it is possible to research a 
-\begin_inset Quotes gld
-\end_inset 
-
-List
-\begin_inset Quotes grd
-\end_inset 
-
- which was returned by a previous search query and to sort it afterwards.
+ Therefore it is possible to use a list which was returned by a previous
+ search query and to sort it afterwards.
  Before we will take a close look into sorting, we will start with searching.
  There exist two different ways of searching:
 \layout Enumerate
 
 Search a complete database for a special regular expression, using 
 \begin_inset Quotes gld
 \end_inset 
 
@@ -835,28 +913,28 @@ matchRegexp()
 \end_inset 
 
 
 \layout Standard
 
 The function is defined like this:
 \layout LyX-Code
 
-List matchRegexp (const QRegExp& r);
+OPimRecordList<T> matchRegexp (const QRegExp& r);
 \layout Standard
 
 The 
 \begin_inset Quotes gld
 \end_inset 
 
-List
+OPimRecordList<T>
 \begin_inset Quotes grd
 \end_inset 
 
- is still a OPimRecordList which contains 0 or more uid's of matching records.
+ is still a list which contains 0 or more uid's of matching records.
  As already discussed in section 
 \begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
 
 \end_inset 
 
  you have to use the 
 \begin_inset Quotes gld
 \end_inset 
@@ -891,36 +969,20 @@ Eilers
 \end_inset 
 
  you have to do the following:
 \layout LyX-Code
 
 OPimContact searchQuery;
 \layout LyX-Code
 
-searchQuery.setLastName( 
-\begin_inset Quotes eld
-\end_inset 
-
-Eilers
-\begin_inset Quotes erd
-\end_inset 
-
- );
+searchQuery.setLastName( "Eilers" );
 \layout LyX-Code
 
-searchQuery.setHomeZip( 
-\begin_inset Quotes eld
-\end_inset 
-
-3*
-\begin_inset Quotes srd
-\end_inset 
-
- );
+searchQuery.setHomeZip( "3*" );
 \layout Standard
 
 We use an usual 
 \begin_inset Quotes gld
 \end_inset 
 
 OPimContact
 \begin_inset Quotes grd
@@ -954,18 +1016,19 @@ AND
 
  as we would do to find files in a filesystem.
 \layout Standard
 
 The next step is to put this query into the operation which is defined like
  this:
 \layout LyX-Code
 
-List queryByExample (const T& query, int querySettings, const QDateTime&
- startperiod=QDateTime())
+OPimRecordList<T> queryByExample (const T& query,
+\newline 
+int querySettings, const QDateTime& startperiod=QDateTime())
 \layout Standard
 
 The first parameter 
 \begin_inset Quotes gld
 \end_inset 
 
 query
 \begin_inset Quotes grd
@@ -1065,18 +1128,21 @@ endperiod
 \layout LyX-Code
 
 use namespace Opie;
 \layout LyX-Code
 
 [...]
 \layout LyX-Code
 
-List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
-IgnoreCase );
+OPimRecordList<OPimContact> found_items = 
+\newline 
+sourceDB->queryByExample( searchQuery, 
+\newline 
+OPimBase::WildCards | OpimBase::IgnoreCase );
 \layout Standard
 
 This operation may return a list of entries which can be accessed as above,
  using the 
 \begin_inset Quotes gld
 \end_inset 
 
 find()
@@ -1212,21 +1278,29 @@ List
  as the first parameter.
  The search operation will just occur on this set of uid's!
 \layout Subsection
 
 Sorting
 \layout Standard
 
 To sort a given dataset, you should use the following operation (or one
- of the others which behave slightly differently):
+ of the others which behave slightly differently, see 
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
+
+\end_inset 
+
+):
 \layout LyX-Code
 
-List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
- const QArray< UID >& cats);
+OPimRecordList<T> sorted (const List& list, 
+\newline 
+bool ascending, int sortOrder, int sortFilter, 
+\newline 
+const QArray< UID >& cats);
 \layout Standard
 
 This sort operation takes a list of uid's as returned for instance from
  a search query.
  The parameter 
 \begin_inset Quotes gld
 \end_inset