summaryrefslogtreecommitdiff
path: root/development/pim
Unidiff
Diffstat (limited to 'development/pim') (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
@@ -6,54 +6,23 @@
6\fancyfoot{} 6\fancyfoot{}
7\fancyhead[LE,RO]{\slshape \leftmark} 7\fancyhead[LE,RO]{\slshape \leftmark}
8\fancyhead[LO,RE]{\slshape \leftmark} 8\fancyhead[LO,RE]{\slshape \leftmark}
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
15% \pdfinfo{ 16% \pdfinfo{
16% /Title ClearSim-RealtTime und Andere 17% /Title ClearSim-RealtTime und Andere
17% /Creator (Tex) 18% /Creator (Tex)
18% /Author (Stefan Eilers) 19% /Author (Stefan Eilers)
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
57\fontscheme ae 26\fontscheme ae
58\graphics default 27\graphics default
59\float_placement htbp 28\float_placement htbp
@@ -79,18 +48,18 @@
79\layout Title 48\layout Title
80 49
81How to use the Opie-Pim API without getting tired! 50How 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
94\family sans 63\family sans
95Abstract 64Abstract
96\layout Standard 65\layout Standard
@@ -111,12 +80,22 @@ While starting to read the automatically generated API-documentation, the
111 Due to the fact that a user will not need most of the details, this paper 80 Due to the fact that a user will not need most of the details, this paper
112 should help to start to become confortable with those details he need to 81 should help to start to become confortable with those details he need to
113 solve his problems. 82 solve his problems.
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
120 99
121 100
122\layout Chapter 101\layout Chapter
@@ -214,30 +193,43 @@ OPimAccessFactory
214\end_inset 193\end_inset
215 194
216). 195).
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
230use namespace Opie; 215use namespace Opie;
231\layout Standard 216\layout Standard
232 217
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
241 access-class which has to be used for accessing the database. 233 access-class which has to be used for accessing the database.
242 Accessing the datebook database works equally 234 Accessing the datebook database works equally
243\begin_inset Foot 235\begin_inset Foot
@@ -249,21 +241,31 @@ The API will be changed in the future: ODateBookAccess will be renamed to
249 OPimEventAccess. 241 OPimEventAccess.
250\end_inset 242\end_inset
251 243
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
267\emph on 269\emph on
268 270
269\begin_inset Quotes gld 271\begin_inset Quotes gld
@@ -482,35 +484,48 @@ If you want to work with the existing dataset, you need to get a list of
482allRecords() 484allRecords()
483\begin_inset Quotes grd 485\begin_inset Quotes grd
484\end_inset 486\end_inset
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}
492 494
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
514find() 529find()
515\begin_inset Quotes grd 530\begin_inset Quotes grd
516\end_inset 531\end_inset
@@ -518,12 +533,82 @@ find()
518 with a valid UID as parameter: 533 with a valid UID as parameter:
519\layout LyX-Code 534\layout LyX-Code
520 535
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
527 612
528How to Access PIM-Data: Detailed View 613How to Access PIM-Data: Detailed View
529\layout Standard 614\layout Standard
@@ -750,27 +835,20 @@ In most cases it is not sufficient to receive just a list of all information
750 searching and sorting in an incremental manner 835 searching and sorting in an incremental manner
751\begin_inset Foot 836\begin_inset Foot
752collapsed false 837collapsed 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
774 852
775Search a complete database for a special regular expression, using 853Search a complete database for a special regular expression, using
776\begin_inset Quotes gld 854\begin_inset Quotes gld
@@ -837,24 +915,24 @@ matchRegexp()
837 915
838\layout Standard 916\layout Standard
839 917
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
858\end_inset 936\end_inset
859 937
860 you have to use the 938 you have to use the
@@ -893,32 +971,16 @@ Eilers
893 you have to do the following: 971 you have to do the following:
894\layout LyX-Code 972\layout LyX-Code
895 973
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
922\begin_inset Quotes gld 984\begin_inset Quotes gld
923\end_inset 985\end_inset
924 986
@@ -956,14 +1018,15 @@ AND
956\layout Standard 1018\layout Standard
957 1019
958The next step is to put this query into the operation which is defined like 1020The 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
967\begin_inset Quotes gld 1030\begin_inset Quotes gld
968\end_inset 1031\end_inset
969 1032
@@ -1067,14 +1130,17 @@ endperiod
1067use namespace Opie; 1130use namespace Opie;
1068\layout LyX-Code 1131\layout LyX-Code
1069 1132
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,
1078 using the 1144 using the
1079\begin_inset Quotes gld 1145\begin_inset Quotes gld
1080\end_inset 1146\end_inset
@@ -1214,17 +1280,25 @@ List
1214\layout Subsection 1280\layout Subsection
1215 1281
1216Sorting 1282Sorting
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
1228 a search query. 1302 a search query.
1229 The parameter 1303 The parameter
1230\begin_inset Quotes gld 1304\begin_inset Quotes gld