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
@@ -10,4 +10,5 @@
 %\fancyhead[LO,RE]{}
 % \usepackage{ae}
+\usepackage[T1]{fontenc} 
 \usepackage[bookmarksopen,colorlinks]{hyperref}
 % \pdfoutput=1
@@ -20,36 +21,4 @@
 %  /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
@@ -83,10 +52,10 @@ How to use the Opie-Pim API without getting tired!
 (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*
 
@@ -115,4 +84,14 @@ 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{}
 
@@ -218,5 +197,9 @@ OPimAccessFactory
 \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
 
@@ -225,4 +208,6 @@ You just have to add the following lines to your source code to use it (this
 \layout LyX-Code
 
+\layout LyX-Code
+
 #include <opie2/opimaccessfactory.h>
 \layout LyX-Code
@@ -234,6 +219,13 @@ use namespace Opie;
 \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
 
@@ -253,6 +245,11 @@ The API will be changed in the future: ODateBookAccess will be renamed to
 \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
 
@@ -260,6 +257,11 @@ 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
 
@@ -486,5 +488,5 @@ allRecords()
  which returns a list of all available records as an 
 \series bold 
-OPimRecordList
+OPimRecordList<T>
 \series default 
  (see 
@@ -494,19 +496,32 @@ 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
 
 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 
@@ -522,4 +537,74 @@ 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.
@@ -754,5 +839,5 @@ 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)
@@ -760,13 +845,6 @@ 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.
  There exist two different ways of searching:
@@ -841,5 +919,5 @@ The function is defined like this:
 \layout LyX-Code
 
-List matchRegexp (const QRegExp& r);
+OPimRecordList<T> matchRegexp (const QRegExp& r);
 \layout Standard
 
@@ -848,9 +926,9 @@ The
 \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}
@@ -897,24 +975,8 @@ 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
 
@@ -960,6 +1022,7 @@ The next step is to put this query into the operation which is defined like
 \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
 
@@ -1071,6 +1134,9 @@ use namespace Opie;
 \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
 
@@ -1218,9 +1284,17 @@ 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