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
@@ -11,2 +11,3 @@
 % \usepackage{ae}
+\usepackage[T1]{fontenc} 
 \usepackage[bookmarksopen,colorlinks]{hyperref}
@@ -21,34 +22,2 @@
 % }
-\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
@@ -84,3 +53,3 @@ How to use the Opie-Pim API without getting tired!
 \newline 
-(Pre V 0.1)
+(V 0.2)
 \layout Author
@@ -89,3 +58,3 @@ How to use the Opie-Pim API without getting tired!
 \family sans 
-Stefan Eilers
+Stefan Eilers (stefan@eilers-online.net)
 \layout Section*
@@ -116,2 +85,12 @@ While starting to read the automatically generated API-documentation, the
 
+\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{}
@@ -219,3 +198,7 @@ OPimAccessFactory
 
-T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
+T* defaultAccess ( 
+\newline 
+typename OPimGlobal::PimType type,
+\newline 
+const QString &appName)
 \layout Standard
@@ -226,2 +209,4 @@ You just have to add the following lines to your source code to use it (this
 
+\layout LyX-Code
+
 #include <opie2/opimaccessfactory.h>
@@ -235,4 +220,11 @@ use namespace Opie;
 
-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
@@ -254,4 +246,9 @@ The API will be changed in the future: ODateBookAccess will be renamed to
 
-ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
- OPimGlobal::DATEBOOK, "my-app" );
+ODateBookAccess* sourceDB = 
+\newline 
+OPimAccessFactory<ODatebookAccess>::defaultAccess(
+\newline 
+OPimGlobal::DATEBOOK,
+\newline 
+"my-app" );
 \layout Standard
@@ -261,4 +258,9 @@ And the same for todo:
 
-OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
- OPimGlobal::TODOLIST, "my-app" );
+OPimTodoAccess* sourceDB = 
+\newline 
+OPimAccessFactory<OPimTodoAccess>::defaultAccess(
+\newline 
+OPimGlobal::TODOLIST,
+\newline 
+"my-app" );
 \layout Standard
@@ -487,3 +489,3 @@ allRecords()
 \series bold 
-OPimRecordList
+OPimRecordList<T>
 \series default 
@@ -495,6 +497,15 @@ OPimRecordList
 ).
- 
+ 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
@@ -502,10 +513,14 @@ List allRecords();
 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
@@ -523,2 +538,72 @@ T find (UID uid);
 
+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
@@ -755,3 +840,3 @@ collapsed false
 
-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!
@@ -761,11 +846,4 @@ FIXME: matchRegexp() does take a list of uid's.
 .
- 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.
@@ -842,3 +920,3 @@ The function is defined like this:
 
-List matchRegexp (const QRegExp& r);
+OPimRecordList<T> matchRegexp (const QRegExp& r);
 \layout Standard
@@ -849,3 +927,3 @@ The
 
-List
+OPimRecordList<T>
 \begin_inset Quotes grd
@@ -853,3 +931,3 @@ List
 
- 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 
@@ -898,22 +976,6 @@ OPimContact searchQuery;
 
-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
@@ -961,4 +1023,5 @@ The next step is to put this query into the operation which is defined like
 
-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
@@ -1072,4 +1135,7 @@ use namespace Opie;
 
-List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
-IgnoreCase );
+OPimRecordList<OPimContact> found_items = 
+\newline 
+sourceDB->queryByExample( searchQuery, 
+\newline 
+OPimBase::WildCards | OpimBase::IgnoreCase );
 \layout Standard
@@ -1219,7 +1285,15 @@ Sorting
 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