summaryrefslogtreecommitdiff
Unidiff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx252
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
@@ -9,6 +9,7 @@
9\fancyhead[RE,LO]{\thepage} 9\fancyhead[RE,LO]{\thepage}
10%\fancyhead[LO,RE]{} 10%\fancyhead[LO,RE]{}
11% \usepackage{ae} 11% \usepackage{ae}
12\usepackage[T1]{fontenc}
12\usepackage[bookmarksopen,colorlinks]{hyperref} 13\usepackage[bookmarksopen,colorlinks]{hyperref}
13% \pdfoutput=1 14% \pdfoutput=1
14% \pdfcompresslevel=8 15% \pdfcompresslevel=8
@@ -19,38 +20,6 @@
19% /Subject () 20% /Subject ()
20% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm) 21% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
21% } 22% }
22\renewcommand\familydefault{\sfdefault}
23
24\usepackage{multicol}
25\newcommand\NrCol{3}
26\renewenvironment{theindex}
27 {\columnseprule \z@
28 \columnsep 35\p@
29 \section*{\indexname}%
30 \@mkboth{\MakeUppercase\indexname}%
31 {\MakeUppercase\indexname}%
32 \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
33 \parskip\z@ \@plus .3\p@\relax
34 \let\item\@idxitem}
35 {\clearpage %
36 \end{multicols}}
37
38\renewenvironment{theindex}
39 {\if@twocolumn
40 \@restonecolfalse
41 \else
42 \@restonecoltrue
43 \fi
44 \columnseprule \z@
45 \columnsep 35\p@
46 \twocolumn[\refstepcounter{section}%
47 \section{\indexname}]%
48 \@mkboth{\MakeUppercase\indexname}%
49 {\MakeUppercase\indexname}%
50 \thispagestyle{plain}\parindent\z@
51 \parskip\z@ \@plus .3\p@\relax
52 \let\item\@idxitem}
53 {\if@restonecol\onecolumn\else\clearpage\fi}
54\end_preamble 23\end_preamble
55\language american 24\language american
56\inputencoding default 25\inputencoding default
@@ -82,12 +51,12 @@ How to use the Opie-Pim API without getting tired!
82\newline 51\newline
83(Aka: Hitchhikers Guide Through the Opie-Pim API) 52(Aka: Hitchhikers Guide Through the Opie-Pim API)
84\newline 53\newline
85(Pre V 0.1) 54(V 0.2)
86\layout Author 55\layout Author
87 56
88 57
89\family sans 58\family sans
90Stefan Eilers 59Stefan Eilers (stefan@eilers-online.net)
91\layout Section* 60\layout Section*
92 61
93 62
@@ -114,6 +83,16 @@ While starting to read the automatically generated API-documentation, the
114\layout Standard 83\layout Standard
115 84
116 85
86\series bold
87You will find a more recent version at:
88\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apihowto/pim_howto.pdf}
89
90\end_inset
91
92
93\layout Standard
94
95
117\begin_inset LatexCommand \tableofcontents{} 96\begin_inset LatexCommand \tableofcontents{}
118 97
119\end_inset 98\end_inset
@@ -217,13 +196,19 @@ OPimAccessFactory
217 This operation is defined like this: 196 This operation is defined like this:
218\layout LyX-Code 197\layout LyX-Code
219 198
220T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) 199T* defaultAccess (
200\newline
201typename OPimGlobal::PimType type,
202\newline
203const QString &appName)
221\layout Standard 204\layout Standard
222 205
223You just have to add the following lines to your source code to use it (this 206You just have to add the following lines to your source code to use it (this
224 example is for accessing the contact database): 207 example is for accessing the contact database):
225\layout LyX-Code 208\layout LyX-Code
226 209
210\layout LyX-Code
211
227#include <opie2/opimaccessfactory.h> 212#include <opie2/opimaccessfactory.h>
228\layout LyX-Code 213\layout LyX-Code
229 214
@@ -233,8 +218,15 @@ use namespace Opie;
233[...] 218[...]
234\layout LyX-Code 219\layout LyX-Code
235 220
236OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces 221OPimContactAccess* sourceDB =
237s( OPimGlobal::CONTACTLIST, "my-app" ); 222\newline
223OPimAccessFactory<OPimContactAccess>::defaultAccess(
224\newline
225OPimGlobal::CONTACTLIST,
226\newline
227"my-app" );
228\layout LyX-Code
229
238\layout Standard 230\layout Standard
239 231
240If everything works as expected, you will receive a pointer to the contact 232If everything works as expected, you will receive a pointer to the contact
@@ -252,15 +244,25 @@ The API will be changed in the future: ODateBookAccess will be renamed to
252: 244:
253\layout LyX-Code 245\layout LyX-Code
254 246
255ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( 247ODateBookAccess* sourceDB =
256 OPimGlobal::DATEBOOK, "my-app" ); 248\newline
249OPimAccessFactory<ODatebookAccess>::defaultAccess(
250\newline
251OPimGlobal::DATEBOOK,
252\newline
253"my-app" );
257\layout Standard 254\layout Standard
258 255
259And the same for todo: 256And the same for todo:
260\layout LyX-Code 257\layout LyX-Code
261 258
262OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess( 259OPimTodoAccess* sourceDB =
263 OPimGlobal::TODOLIST, "my-app" ); 260\newline
261OPimAccessFactory<OPimTodoAccess>::defaultAccess(
262\newline
263OPimGlobal::TODOLIST,
264\newline
265"my-app" );
264\layout Standard 266\layout Standard
265 267
266Using 268Using
@@ -485,7 +487,7 @@ allRecords()
485 487
486 which returns a list of all available records as an 488 which returns a list of all available records as an
487\series bold 489\series bold
488OPimRecordList 490OPimRecordList<T>
489\series default 491\series default
490 (see 492 (see
491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html} 493\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
@@ -493,21 +495,34 @@ OPimRecordList
493\end_inset 495\end_inset
494 496
495). 497).
496 498 This OPimRecordList is a template and should be used with the right class
499 parameter
500\begin_inset Quotes eld
501\end_inset
502
503T
504\begin_inset Quotes erd
505\end_inset
506
507 which is currently one of the following: OPimContact, OPimTodo and OPimEvent.
497\layout LyX-Code 508\layout LyX-Code
498 509
499List allRecords(); 510OPimRecordList<T> allRecords();
500\layout Standard 511\layout Standard
501 512
502In fact, this 513In fact, this
503\emph on 514\begin_inset Quotes eld
504List 515\end_inset
505\emph default 516
517OPimRecordList<T>
518\begin_inset Quotes erd
519\end_inset
520
506 just contains a list of uid's to take care of memory space. 521 just contains a list of uid's to take care of memory space.
507 As every record is identified by an unique identification number which 522 Every record is identified by an unique identification number which is
508 is called UID (Unique Identification), these numbers just exists once in 523 called UID (Unique Identification).
509 the database which is currently on access! To receive the real record, 524 These numbers just exists once in the database which is currently on access!
510 you have to use the operation 525 To receive the real record, you have to use the operation
511\begin_inset Quotes gld 526\begin_inset Quotes gld
512\end_inset 527\end_inset
513 528
@@ -521,6 +536,76 @@ find()
521T find (UID uid); 536T find (UID uid);
522\layout Standard 537\layout Standard
523 538
539The remaining question is, how to get a valid UID out of a list to use the
540
541\begin_inset Quotes eld
542\end_inset
543
544find()
545\begin_inset Quotes erd
546\end_inset
547
548 in a correct manner.
549 This could be done by requesting a special element of the list, using the
550 operator[] or by using iterators.
551 The first one would be like this
552\begin_inset Foot
553collapsed true
554
555\layout Standard
556
557Please do not forget to use
558\begin_inset Quotes eld
559\end_inset
560
561use namespace Opie;
562\begin_inset Quotes erd
563\end_inset
564
565 to enable the namespace
566\begin_inset Quotes eld
567\end_inset
568
569Opie
570\begin_inset Quotes erd
571\end_inset
572
573!!
574\end_inset
575
576:
577\layout LyX-Code
578
579OPimRecordList<OPimContact> list = allRecords();
580\layout LyX-Code
581
582for ( int i = 0; i < list.count(); i++ ){
583\layout LyX-Code
584
585 cout << "The UID is: " << list[i] << endl;
586\layout LyX-Code
587
588}
589\layout Standard
590
591Using the iterator is as easy as the previous one:
592\layout LyX-Code
593
594OPimRecordList<OPimContact> list = allRecords();
595\layout LyX-Code
596
597OPimRecordList<OPimContact>::iterator it;
598\layout LyX-Code
599
600for ( it = list.begin(); it != list.end(); ++it ){
601\layout LyX-Code
602
603 count << "The UID is: " << (*it) << endl;
604\layout LyX-Code
605
606}
607\layout Standard
608
524This is all you need to realize a basic access to the PIM-Databases! The 609This is all you need to realize a basic access to the PIM-Databases! The
525 next chapter will guide you into more details of the PIM-API. 610 next chapter will guide you into more details of the PIM-API.
526\layout Chapter 611\layout Chapter
@@ -753,21 +838,14 @@ collapsed false
753 838
754\layout Standard 839\layout Standard
755 840
756FIXME: matchRegexp() does take a list of uid's. 841FIXME: matchRegexp() does not take a list of uid's.
757 Therefore it is currently not possible to use it in an incremental manner! 842 Therefore it is currently not possible to use it in an incremental manner!
758 (se) 843 (se)
759\end_inset 844\end_inset
760 845
761. 846.
762 Therefore it is possible to research a 847 Therefore it is possible to use a list which was returned by a previous
763\begin_inset Quotes gld 848 search query and to sort it afterwards.
764\end_inset
765
766List
767\begin_inset Quotes grd
768\end_inset
769
770 which was returned by a previous search query and to sort it afterwards.
771 Before we will take a close look into sorting, we will start with searching. 849 Before we will take a close look into sorting, we will start with searching.
772 There exist two different ways of searching: 850 There exist two different ways of searching:
773\layout Enumerate 851\layout Enumerate
@@ -840,18 +918,18 @@ matchRegexp()
840The function is defined like this: 918The function is defined like this:
841\layout LyX-Code 919\layout LyX-Code
842 920
843List matchRegexp (const QRegExp& r); 921OPimRecordList<T> matchRegexp (const QRegExp& r);
844\layout Standard 922\layout Standard
845 923
846The 924The
847\begin_inset Quotes gld 925\begin_inset Quotes gld
848\end_inset 926\end_inset
849 927
850List 928OPimRecordList<T>
851\begin_inset Quotes grd 929\begin_inset Quotes grd
852\end_inset 930\end_inset
853 931
854 is still a OPimRecordList which contains 0 or more uid's of matching records. 932 is still a list which contains 0 or more uid's of matching records.
855 As already discussed in section 933 As already discussed in section
856\begin_inset LatexCommand \ref{sec:Accessing-the-access-object} 934\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
857 935
@@ -896,26 +974,10 @@ Eilers
896OPimContact searchQuery; 974OPimContact searchQuery;
897\layout LyX-Code 975\layout LyX-Code
898 976
899searchQuery.setLastName( 977searchQuery.setLastName( "Eilers" );
900\begin_inset Quotes eld
901\end_inset
902
903Eilers
904\begin_inset Quotes erd
905\end_inset
906
907 );
908\layout LyX-Code 978\layout LyX-Code
909 979
910searchQuery.setHomeZip( 980searchQuery.setHomeZip( "3*" );
911\begin_inset Quotes eld
912\end_inset
913
9143*
915\begin_inset Quotes srd
916\end_inset
917
918 );
919\layout Standard 981\layout Standard
920 982
921We use an usual 983We use an usual
@@ -959,8 +1021,9 @@ The next step is to put this query into the operation which is defined like
959 this: 1021 this:
960\layout LyX-Code 1022\layout LyX-Code
961 1023
962List queryByExample (const T& query, int querySettings, const QDateTime& 1024OPimRecordList<T> queryByExample (const T& query,
963 startperiod=QDateTime()) 1025\newline
1026int querySettings, const QDateTime& startperiod=QDateTime())
964\layout Standard 1027\layout Standard
965 1028
966The first parameter 1029The first parameter
@@ -1070,8 +1133,11 @@ use namespace Opie;
1070[...] 1133[...]
1071\layout LyX-Code 1134\layout LyX-Code
1072 1135
1073List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase:: 1136OPimRecordList<OPimContact> found_items =
1074IgnoreCase ); 1137\newline
1138sourceDB->queryByExample( searchQuery,
1139\newline
1140OPimBase::WildCards | OpimBase::IgnoreCase );
1075\layout Standard 1141\layout Standard
1076 1142
1077This operation may return a list of entries which can be accessed as above, 1143This operation may return a list of entries which can be accessed as above,
@@ -1217,11 +1283,19 @@ Sorting
1217\layout Standard 1283\layout Standard
1218 1284
1219To sort a given dataset, you should use the following operation (or one 1285To sort a given dataset, you should use the following operation (or one
1220 of the others which behave slightly differently): 1286 of the others which behave slightly differently, see
1287\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
1288
1289\end_inset
1290
1291):
1221\layout LyX-Code 1292\layout LyX-Code
1222 1293
1223List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, 1294OPimRecordList<T> sorted (const List& list,
1224 const QArray< UID >& cats); 1295\newline
1296bool ascending, int sortOrder, int sortFilter,
1297\newline
1298const QArray< UID >& cats);
1225\layout Standard 1299\layout Standard
1226 1300
1227This sort operation takes a list of uid's as returned for instance from 1301This sort operation takes a list of uid's as returned for instance from