author | eilers <eilers> | 2005-03-25 18:05:34 (UTC) |
---|---|---|
committer | eilers <eilers> | 2005-03-25 18:05:34 (UTC) |
commit | 28ad1605bc23bda70b4af757ddac7c252732e8d0 (patch) (unidiff) | |
tree | 6862f32d7dcfa12791c8df1eeb40b88b57a4cb7b | |
parent | d5415bbb5918ba26882108ba710373d85a112327 (diff) | |
download | opie-28ad1605bc23bda70b4af757ddac7c252732e8d0.zip opie-28ad1605bc23bda70b4af757ddac7c252732e8d0.tar.gz opie-28ad1605bc23bda70b4af757ddac7c252732e8d0.tar.bz2 |
Remove some things which makes it hard to understand this paper by a beginner..
-rw-r--r-- | development/pim/pim_howto/pim_howto.lyx | 248 |
1 files changed, 161 insertions, 87 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 |
90 | Stefan Eilers | 59 | Stefan 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 | ||
87 | You 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 | ||
220 | T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) | 199 | T* defaultAccess ( |
200 | \newline | ||
201 | typename OPimGlobal::PimType type, | ||
202 | \newline | ||
203 | const QString &appName) | ||
221 | \layout Standard | 204 | \layout Standard |
222 | 205 | ||
223 | You just have to add the following lines to your source code to use it (this | 206 | You 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 | ||
236 | OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces | 221 | OPimContactAccess* sourceDB = |
237 | s( OPimGlobal::CONTACTLIST, "my-app" ); | 222 | \newline |
223 | OPimAccessFactory<OPimContactAccess>::defaultAccess( | ||
224 | \newline | ||
225 | OPimGlobal::CONTACTLIST, | ||
226 | \newline | ||
227 | "my-app" ); | ||
228 | \layout LyX-Code | ||
229 | |||
238 | \layout Standard | 230 | \layout Standard |
239 | 231 | ||
240 | If everything works as expected, you will receive a pointer to the contact | 232 | If 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 | ||
255 | ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( | 247 | ODateBookAccess* sourceDB = |
256 | OPimGlobal::DATEBOOK, "my-app" ); | 248 | \newline |
249 | OPimAccessFactory<ODatebookAccess>::defaultAccess( | ||
250 | \newline | ||
251 | OPimGlobal::DATEBOOK, | ||
252 | \newline | ||
253 | "my-app" ); | ||
257 | \layout Standard | 254 | \layout Standard |
258 | 255 | ||
259 | And the same for todo: | 256 | And the same for todo: |
260 | \layout LyX-Code | 257 | \layout LyX-Code |
261 | 258 | ||
262 | OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess( | 259 | OPimTodoAccess* sourceDB = |
263 | OPimGlobal::TODOLIST, "my-app" ); | 260 | \newline |
261 | OPimAccessFactory<OPimTodoAccess>::defaultAccess( | ||
262 | \newline | ||
263 | OPimGlobal::TODOLIST, | ||
264 | \newline | ||
265 | "my-app" ); | ||
264 | \layout Standard | 266 | \layout Standard |
265 | 267 | ||
266 | Using | 268 | Using |
@@ -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 |
488 | OPimRecordList | 490 | OPimRecordList<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 | ). |
498 | This OPimRecordList is a template and should be used with the right class | ||
499 | parameter | ||
500 | \begin_inset Quotes eld | ||
501 | \end_inset | ||
496 | 502 | ||
503 | T | ||
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 | ||
499 | List allRecords(); | 510 | OPimRecordList<T> allRecords(); |
500 | \layout Standard | 511 | \layout Standard |
501 | 512 | ||
502 | In fact, this | 513 | In fact, this |
503 | \emph on | 514 | \begin_inset Quotes eld |
504 | List | 515 | \end_inset |
505 | \emph default | 516 | |
517 | OPimRecordList<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() | |||
521 | T find (UID uid); | 536 | T find (UID uid); |
522 | \layout Standard | 537 | \layout Standard |
523 | 538 | ||
539 | The 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 | |||
544 | find() | ||
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 | ||
553 | collapsed true | ||
554 | |||
555 | \layout Standard | ||
556 | |||
557 | Please do not forget to use | ||
558 | \begin_inset Quotes eld | ||
559 | \end_inset | ||
560 | |||
561 | use 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 | |||
569 | Opie | ||
570 | \begin_inset Quotes erd | ||
571 | \end_inset | ||
572 | |||
573 | !! | ||
574 | \end_inset | ||
575 | |||
576 | : | ||
577 | \layout LyX-Code | ||
578 | |||
579 | OPimRecordList<OPimContact> list = allRecords(); | ||
580 | \layout LyX-Code | ||
581 | |||
582 | for ( 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 | |||
591 | Using the iterator is as easy as the previous one: | ||
592 | \layout LyX-Code | ||
593 | |||
594 | OPimRecordList<OPimContact> list = allRecords(); | ||
595 | \layout LyX-Code | ||
596 | |||
597 | OPimRecordList<OPimContact>::iterator it; | ||
598 | \layout LyX-Code | ||
599 | |||
600 | for ( 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 | |||
524 | This is all you need to realize a basic access to the PIM-Databases! The | 609 | This 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 | ||
756 | FIXME: matchRegexp() does take a list of uid's. | 841 | FIXME: 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 | |||
766 | List | ||
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() | |||
840 | The function is defined like this: | 918 | The function is defined like this: |
841 | \layout LyX-Code | 919 | \layout LyX-Code |
842 | 920 | ||
843 | List matchRegexp (const QRegExp& r); | 921 | OPimRecordList<T> matchRegexp (const QRegExp& r); |
844 | \layout Standard | 922 | \layout Standard |
845 | 923 | ||
846 | The | 924 | The |
847 | \begin_inset Quotes gld | 925 | \begin_inset Quotes gld |
848 | \end_inset | 926 | \end_inset |
849 | 927 | ||
850 | List | 928 | OPimRecordList<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 | |||
896 | OPimContact searchQuery; | 974 | OPimContact searchQuery; |
897 | \layout LyX-Code | 975 | \layout LyX-Code |
898 | 976 | ||
899 | searchQuery.setLastName( | 977 | searchQuery.setLastName( "Eilers" ); |
900 | \begin_inset Quotes eld | ||
901 | \end_inset | ||
902 | |||
903 | Eilers | ||
904 | \begin_inset Quotes erd | ||
905 | \end_inset | ||
906 | |||
907 | ); | ||
908 | \layout LyX-Code | 978 | \layout LyX-Code |
909 | 979 | ||
910 | searchQuery.setHomeZip( | 980 | searchQuery.setHomeZip( "3*" ); |
911 | \begin_inset Quotes eld | ||
912 | \end_inset | ||
913 | |||
914 | 3* | ||
915 | \begin_inset Quotes srd | ||
916 | \end_inset | ||
917 | |||
918 | ); | ||
919 | \layout Standard | 981 | \layout Standard |
920 | 982 | ||
921 | We use an usual | 983 | We 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 | ||
962 | List queryByExample (const T& query, int querySettings, const QDateTime& | 1024 | OPimRecordList<T> queryByExample (const T& query, |
963 | startperiod=QDateTime()) | 1025 | \newline |
1026 | int querySettings, const QDateTime& startperiod=QDateTime()) | ||
964 | \layout Standard | 1027 | \layout Standard |
965 | 1028 | ||
966 | The first parameter | 1029 | The first parameter |
@@ -1070,8 +1133,11 @@ use namespace Opie; | |||
1070 | [...] | 1133 | [...] |
1071 | \layout LyX-Code | 1134 | \layout LyX-Code |
1072 | 1135 | ||
1073 | List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase:: | 1136 | OPimRecordList<OPimContact> found_items = |
1074 | IgnoreCase ); | 1137 | \newline |
1138 | sourceDB->queryByExample( searchQuery, | ||
1139 | \newline | ||
1140 | OPimBase::WildCards | OpimBase::IgnoreCase ); | ||
1075 | \layout Standard | 1141 | \layout Standard |
1076 | 1142 | ||
1077 | This operation may return a list of entries which can be accessed as above, | 1143 | This operation may return a list of entries which can be accessed as above, |
@@ -1217,10 +1283,18 @@ Sorting | |||
1217 | \layout Standard | 1283 | \layout Standard |
1218 | 1284 | ||
1219 | To sort a given dataset, you should use the following operation (or one | 1285 | To 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 | ||
1223 | List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, | 1294 | OPimRecordList<T> sorted (const List& list, |
1295 | \newline | ||
1296 | bool ascending, int sortOrder, int sortFilter, | ||
1297 | \newline | ||
1224 | const QArray< UID >& cats); | 1298 | const QArray< UID >& cats); |
1225 | \layout Standard | 1299 | \layout Standard |
1226 | 1300 | ||