-rw-r--r-- | development/pim/pim_howto/pim_howto.lyx | 252 |
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 | |||
@@ -1,1352 +1,1426 @@ | |||
1 | #LyX 1.3 created this file. For more info see http://www.lyx.org/ | 1 | #LyX 1.3 created this file. For more info see http://www.lyx.org/ |
2 | \lyxformat 221 | 2 | \lyxformat 221 |
3 | \textclass scrbook | 3 | \textclass scrbook |
4 | \begin_preamble | 4 | \begin_preamble |
5 | \fancyhead{} | 5 | \fancyhead{} |
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 |
60 | \paperfontsize default | 29 | \paperfontsize default |
61 | \spacing single | 30 | \spacing single |
62 | \papersize a4paper | 31 | \papersize a4paper |
63 | \paperpackage widemarginsa4 | 32 | \paperpackage widemarginsa4 |
64 | \use_geometry 0 | 33 | \use_geometry 0 |
65 | \use_amsmath 0 | 34 | \use_amsmath 0 |
66 | \use_natbib 0 | 35 | \use_natbib 0 |
67 | \use_numerical_citations 0 | 36 | \use_numerical_citations 0 |
68 | \paperorientation portrait | 37 | \paperorientation portrait |
69 | \secnumdepth 3 | 38 | \secnumdepth 3 |
70 | \tocdepth 3 | 39 | \tocdepth 3 |
71 | \paragraph_separation skip | 40 | \paragraph_separation skip |
72 | \defskip medskip | 41 | \defskip medskip |
73 | \quotes_language english | 42 | \quotes_language english |
74 | \quotes_times 2 | 43 | \quotes_times 2 |
75 | \papercolumns 1 | 44 | \papercolumns 1 |
76 | \papersides 2 | 45 | \papersides 2 |
77 | \paperpagestyle fancy | 46 | \paperpagestyle fancy |
78 | 47 | ||
79 | \layout Title | 48 | \layout Title |
80 | 49 | ||
81 | How to use the Opie-Pim API without getting tired! | 50 | 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 | ||
94 | \family sans | 63 | \family sans |
95 | Abstract | 64 | Abstract |
96 | \layout Standard | 65 | \layout Standard |
97 | 66 | ||
98 | The Opie-Pim API provides a powerfull access interface to the PIM (Personal | 67 | The Opie-Pim API provides a powerfull access interface to the PIM (Personal |
99 | Information Management) data which contains your contact information, the | 68 | Information Management) data which contains your contact information, the |
100 | dates in your calendar tool (in this paper called datebook events) and | 69 | dates in your calendar tool (in this paper called datebook events) and |
101 | your todo events. | 70 | your todo events. |
102 | Beside providing full featured access to this information, it covers the | 71 | Beside providing full featured access to this information, it covers the |
103 | real management of this informantion - the access of the databases - from | 72 | real management of this informantion - the access of the databases - from |
104 | the user. | 73 | the user. |
105 | 74 | ||
106 | \layout Standard | 75 | \layout Standard |
107 | 76 | ||
108 | While starting to read the automatically generated API-documentation, the | 77 | While starting to read the automatically generated API-documentation, the |
109 | user may be confused by a lot of unnecessary classes and details which | 78 | user may be confused by a lot of unnecessary classes and details which |
110 | makes the quick start not as easy as possible. | 79 | makes the quick start not as easy as possible. |
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 | ||
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 |
120 | 99 | ||
121 | 100 | ||
122 | \layout Chapter | 101 | \layout Chapter |
123 | 102 | ||
124 | Introduction | 103 | Introduction |
125 | \layout Standard | 104 | \layout Standard |
126 | 105 | ||
127 | Before starting to jump into the work, we should introduce some specialties | 106 | Before starting to jump into the work, we should introduce some specialties |
128 | of the PIM API, first. | 107 | of the PIM API, first. |
129 | To know these facts should help to avoid possible irritations and misunderstand | 108 | To know these facts should help to avoid possible irritations and misunderstand |
130 | ings: | 109 | ings: |
131 | \layout Enumerate | 110 | \layout Enumerate |
132 | 111 | ||
133 | The PIM-API heavily uses C++ templates (as known as generic classes), but | 112 | The PIM-API heavily uses C++ templates (as known as generic classes), but |
134 | you don't have to understand very deeple what templates are doing and how | 113 | you don't have to understand very deeple what templates are doing and how |
135 | they work! Most of the API works without even seeing the templates. | 114 | they work! Most of the API works without even seeing the templates. |
136 | In some cases we have to use them (for instance to use the factory classes), | 115 | In some cases we have to use them (for instance to use the factory classes), |
137 | but this guide will provide examples which should help to find the path | 116 | but this guide will provide examples which should help to find the path |
138 | through. | 117 | through. |
139 | But it is a good idea to read some short introduction of templates to avoid | 118 | But it is a good idea to read some short introduction of templates to avoid |
140 | unnecessary mistakes. | 119 | unnecessary mistakes. |
141 | \layout Enumerate | 120 | \layout Enumerate |
142 | 121 | ||
143 | The PIM-API is split into two parts: The | 122 | The PIM-API is split into two parts: The |
144 | \emph on | 123 | \emph on |
145 | frontend | 124 | frontend |
146 | \emph default | 125 | \emph default |
147 | and the | 126 | and the |
148 | \emph on | 127 | \emph on |
149 | backend. | 128 | backend. |
150 | 129 | ||
151 | \emph default | 130 | \emph default |
152 | While the frontend provides the API for the user, the backend implements | 131 | While the frontend provides the API for the user, the backend implements |
153 | how to access the databases and what to do with the data. | 132 | how to access the databases and what to do with the data. |
154 | As we just want to access data, this paper just focuses the frontend. | 133 | As we just want to access data, this paper just focuses the frontend. |
155 | Thus, you should ignore all classes which contains something like | 134 | Thus, you should ignore all classes which contains something like |
156 | \begin_inset Quotes gld | 135 | \begin_inset Quotes gld |
157 | \end_inset | 136 | \end_inset |
158 | 137 | ||
159 | backend | 138 | backend |
160 | \begin_inset Quotes grd | 139 | \begin_inset Quotes grd |
161 | \end_inset | 140 | \end_inset |
162 | 141 | ||
163 | in its name! Backends are just interesting for people who want to extend | 142 | in its name! Backends are just interesting for people who want to extend |
164 | or implement new possibilities about how to access databases, which will | 143 | or implement new possibilities about how to access databases, which will |
165 | be discussed at the end of this paper. | 144 | be discussed at the end of this paper. |
166 | Currently, you just have to understand that there do exist several backends | 145 | Currently, you just have to understand that there do exist several backends |
167 | for every type of PIM data (Contact, Todo, Datebook) which controls whether | 146 | for every type of PIM data (Contact, Todo, Datebook) which controls whether |
168 | you want to access an XML, SQL (SQLite) or VCard style database. | 147 | you want to access an XML, SQL (SQLite) or VCard style database. |
169 | If you just want to use the default database, you even don't have to think | 148 | If you just want to use the default database, you even don't have to think |
170 | about this! | 149 | about this! |
171 | \layout Standard | 150 | \layout Standard |
172 | 151 | ||
173 | In the next chapter, we will show how to access the default database as | 152 | In the next chapter, we will show how to access the default database as |
174 | easy as possible. | 153 | easy as possible. |
175 | This will be the solution for most of the problems you may face while accessing | 154 | This will be the solution for most of the problems you may face while accessing |
176 | the PIM data. | 155 | the PIM data. |
177 | \layout Chapter | 156 | \layout Chapter |
178 | 157 | ||
179 | Quick Guide to access the Database | 158 | Quick Guide to access the Database |
180 | \layout Standard | 159 | \layout Standard |
181 | 160 | ||
182 | In this chapter we will introduce very quickly how to get access to the | 161 | In this chapter we will introduce very quickly how to get access to the |
183 | database and how to access data. | 162 | database and how to access data. |
184 | It should help to find the right directions. | 163 | It should help to find the right directions. |
185 | If it is too short for you, you should read the next chapter afterwards | 164 | If it is too short for you, you should read the next chapter afterwards |
186 | to find a more complete and detailed view into the system. | 165 | to find a more complete and detailed view into the system. |
187 | \layout Section | 166 | \layout Section |
188 | 167 | ||
189 | Instantiate the access-object | 168 | Instantiate the access-object |
190 | \begin_inset LatexCommand \label{sec:Instantiate-the-Access} | 169 | \begin_inset LatexCommand \label{sec:Instantiate-the-Access} |
191 | 170 | ||
192 | \end_inset | 171 | \end_inset |
193 | 172 | ||
194 | 173 | ||
195 | \layout Standard | 174 | \layout Standard |
196 | 175 | ||
197 | To gain access to the database you need something we will call | 176 | To gain access to the database you need something we will call |
198 | \emph on | 177 | \emph on |
199 | access-object | 178 | access-object |
200 | \emph default | 179 | \emph default |
201 | (an instance of the access-class for the database) which handles the database | 180 | (an instance of the access-class for the database) which handles the database |
202 | access. | 181 | access. |
203 | Requesting such an object is very easy by using the operation | 182 | Requesting such an object is very easy by using the operation |
204 | \emph on | 183 | \emph on |
205 | defaultAccess() | 184 | defaultAccess() |
206 | \emph default | 185 | \emph default |
207 | of the factory class | 186 | of the factory class |
208 | \series bold | 187 | \series bold |
209 | OPimAccessFactory | 188 | OPimAccessFactory |
210 | \series default | 189 | \series default |
211 | (see | 190 | (see |
212 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html} | 191 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html} |
213 | 192 | ||
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 | ||
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 | ||
230 | use namespace Opie; | 215 | use namespace Opie; |
231 | \layout Standard | 216 | \layout Standard |
232 | 217 | ||
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 |
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 |
244 | collapsed false | 236 | collapsed false |
245 | 237 | ||
246 | \layout Standard | 238 | \layout Standard |
247 | 239 | ||
248 | The API will be changed in the future: ODateBookAccess will be renamed to | 240 | 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 | ||
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 |
267 | \emph on | 269 | \emph on |
268 | 270 | ||
269 | \begin_inset Quotes gld | 271 | \begin_inset Quotes gld |
270 | \end_inset | 272 | \end_inset |
271 | 273 | ||
272 | defaultAccess() | 274 | defaultAccess() |
273 | \begin_inset Quotes grd | 275 | \begin_inset Quotes grd |
274 | \end_inset | 276 | \end_inset |
275 | 277 | ||
276 | 278 | ||
277 | \emph default | 279 | \emph default |
278 | , the default database is accessed automatically | 280 | , the default database is accessed automatically |
279 | \begin_inset Foot | 281 | \begin_inset Foot |
280 | collapsed false | 282 | collapsed false |
281 | 283 | ||
282 | \layout Standard | 284 | \layout Standard |
283 | 285 | ||
284 | The configuration file | 286 | The configuration file |
285 | \begin_inset Quotes gld | 287 | \begin_inset Quotes gld |
286 | \end_inset | 288 | \end_inset |
287 | 289 | ||
288 | pimaccess.conf | 290 | pimaccess.conf |
289 | \begin_inset Quotes grd | 291 | \begin_inset Quotes grd |
290 | \end_inset | 292 | \end_inset |
291 | 293 | ||
292 | defines which backend is selected as default! | 294 | defines which backend is selected as default! |
293 | \end_inset | 295 | \end_inset |
294 | 296 | ||
295 | . | 297 | . |
296 | If you want to use anything else, you have to read the next chapter to | 298 | If you want to use anything else, you have to read the next chapter to |
297 | get the information how to do this. | 299 | get the information how to do this. |
298 | 300 | ||
299 | \layout Standard | 301 | \layout Standard |
300 | 302 | ||
301 | The last parameter | 303 | The last parameter |
302 | \begin_inset Quotes gld | 304 | \begin_inset Quotes gld |
303 | \end_inset | 305 | \end_inset |
304 | 306 | ||
305 | my-app | 307 | my-app |
306 | \begin_inset Quotes grd | 308 | \begin_inset Quotes grd |
307 | \end_inset | 309 | \end_inset |
308 | 310 | ||
309 | is very importand and should be equal for every instance of an application. | 311 | is very importand and should be equal for every instance of an application. |
310 | Some database backends (like the XML backend) uses this string as an unique | 312 | Some database backends (like the XML backend) uses this string as an unique |
311 | filename to create a journal file. | 313 | filename to create a journal file. |
312 | If your application should run in several instances independently you will | 314 | If your application should run in several instances independently you will |
313 | need multiple journal files and therefore several name strings! | 315 | need multiple journal files and therefore several name strings! |
314 | \layout Standard | 316 | \layout Standard |
315 | 317 | ||
316 | If the database access-object is is not needed anymore, you have to remove | 318 | If the database access-object is is not needed anymore, you have to remove |
317 | it by calling | 319 | it by calling |
318 | \emph on | 320 | \emph on |
319 | delete | 321 | delete |
320 | \emph default | 322 | \emph default |
321 | : | 323 | : |
322 | \layout LyX-Code | 324 | \layout LyX-Code |
323 | 325 | ||
324 | delete sourceDB; | 326 | delete sourceDB; |
325 | \layout Section | 327 | \layout Section |
326 | 328 | ||
327 | Accessing the Access-Object | 329 | Accessing the Access-Object |
328 | \begin_inset LatexCommand \label{sec:Accessing-the-access-object} | 330 | \begin_inset LatexCommand \label{sec:Accessing-the-access-object} |
329 | 331 | ||
330 | \end_inset | 332 | \end_inset |
331 | 333 | ||
332 | 334 | ||
333 | \layout Standard | 335 | \layout Standard |
334 | 336 | ||
335 | After receiving the access-object, we just have to use its API which is | 337 | After receiving the access-object, we just have to use its API which is |
336 | mainly defined by the common base class | 338 | mainly defined by the common base class |
337 | \series bold | 339 | \series bold |
338 | OPimAccessTemplate | 340 | OPimAccessTemplate |
339 | \series default | 341 | \series default |
340 | (see | 342 | (see |
341 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html} | 343 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html} |
342 | 344 | ||
343 | \end_inset | 345 | \end_inset |
344 | 346 | ||
345 | ). | 347 | ). |
346 | This API is inherited by all access-classes and therefore common to all | 348 | This API is inherited by all access-classes and therefore common to all |
347 | access-objects. | 349 | access-objects. |
348 | We will show the most important operations of it first (please replace | 350 | We will show the most important operations of it first (please replace |
349 | 351 | ||
350 | \begin_inset Quotes gld | 352 | \begin_inset Quotes gld |
351 | \end_inset | 353 | \end_inset |
352 | 354 | ||
353 | T | 355 | T |
354 | \begin_inset Quotes grd | 356 | \begin_inset Quotes grd |
355 | \end_inset | 357 | \end_inset |
356 | 358 | ||
357 | below with the corresponding | 359 | below with the corresponding |
358 | \emph on | 360 | \emph on |
359 | data-class | 361 | data-class |
360 | \emph default | 362 | \emph default |
361 | for the selected access-class: OPimContact | 363 | for the selected access-class: OPimContact |
362 | \begin_inset Foot | 364 | \begin_inset Foot |
363 | collapsed false | 365 | collapsed false |
364 | 366 | ||
365 | \layout Standard | 367 | \layout Standard |
366 | 368 | ||
367 | see | 369 | see |
368 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html} | 370 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html} |
369 | 371 | ||
370 | \end_inset | 372 | \end_inset |
371 | 373 | ||
372 | 374 | ||
373 | \end_inset | 375 | \end_inset |
374 | 376 | ||
375 | for OPimContactAccess, OPimEvent | 377 | for OPimContactAccess, OPimEvent |
376 | \begin_inset Foot | 378 | \begin_inset Foot |
377 | collapsed false | 379 | collapsed false |
378 | 380 | ||
379 | \layout Standard | 381 | \layout Standard |
380 | 382 | ||
381 | see | 383 | see |
382 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html} | 384 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html} |
383 | 385 | ||
384 | \end_inset | 386 | \end_inset |
385 | 387 | ||
386 | 388 | ||
387 | \end_inset | 389 | \end_inset |
388 | 390 | ||
389 | for ODateBookAccess and OPimTodo | 391 | for ODateBookAccess and OPimTodo |
390 | \begin_inset Foot | 392 | \begin_inset Foot |
391 | collapsed false | 393 | collapsed false |
392 | 394 | ||
393 | \layout Standard | 395 | \layout Standard |
394 | 396 | ||
395 | see | 397 | see |
396 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html} | 398 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html} |
397 | 399 | ||
398 | \end_inset | 400 | \end_inset |
399 | 401 | ||
400 | 402 | ||
401 | \end_inset | 403 | \end_inset |
402 | 404 | ||
403 | for OPimTodoAccess): | 405 | for OPimTodoAccess): |
404 | \layout LyX-Code | 406 | \layout LyX-Code |
405 | 407 | ||
406 | bool load (); | 408 | bool load (); |
407 | \layout LyX-Code | 409 | \layout LyX-Code |
408 | 410 | ||
409 | bool reload (); | 411 | bool reload (); |
410 | \layout LyX-Code | 412 | \layout LyX-Code |
411 | 413 | ||
412 | bool save (); | 414 | bool save (); |
413 | \layout LyX-Code | 415 | \layout LyX-Code |
414 | 416 | ||
415 | \layout LyX-Code | 417 | \layout LyX-Code |
416 | 418 | ||
417 | bool add (const T& t); | 419 | bool add (const T& t); |
418 | \layout LyX-Code | 420 | \layout LyX-Code |
419 | 421 | ||
420 | bool remove (const T& t); | 422 | bool remove (const T& t); |
421 | \layout LyX-Code | 423 | \layout LyX-Code |
422 | 424 | ||
423 | bool replace (const T& t); | 425 | bool replace (const T& t); |
424 | \layout Standard | 426 | \layout Standard |
425 | 427 | ||
426 | After receiving an access-object, we have to load the existing dataset into | 428 | After receiving an access-object, we have to load the existing dataset into |
427 | the backend, which is done by the | 429 | the backend, which is done by the |
428 | \begin_inset Quotes gld | 430 | \begin_inset Quotes gld |
429 | \end_inset | 431 | \end_inset |
430 | 432 | ||
431 | load() | 433 | load() |
432 | \begin_inset Quotes grd | 434 | \begin_inset Quotes grd |
433 | \end_inset | 435 | \end_inset |
434 | 436 | ||
435 | operation. | 437 | operation. |
436 | The | 438 | The |
437 | \begin_inset Quotes gld | 439 | \begin_inset Quotes gld |
438 | \end_inset | 440 | \end_inset |
439 | 441 | ||
440 | save() | 442 | save() |
441 | \begin_inset Quotes grd | 443 | \begin_inset Quotes grd |
442 | \end_inset | 444 | \end_inset |
443 | 445 | ||
444 | operation is important to write back (or | 446 | operation is important to write back (or |
445 | \emph on | 447 | \emph on |
446 | commit | 448 | commit |
447 | \emph default | 449 | \emph default |
448 | ) local changes into the global database. | 450 | ) local changes into the global database. |
449 | After doing this, the changes are globally accessable! The | 451 | After doing this, the changes are globally accessable! The |
450 | \begin_inset Quotes gld | 452 | \begin_inset Quotes gld |
451 | \end_inset | 453 | \end_inset |
452 | 454 | ||
453 | reload() | 455 | reload() |
454 | \begin_inset Quotes grd | 456 | \begin_inset Quotes grd |
455 | \end_inset | 457 | \end_inset |
456 | 458 | ||
457 | operation loads changes of the global database into the local set | 459 | operation loads changes of the global database into the local set |
458 | \series bold | 460 | \series bold |
459 | without | 461 | without |
460 | \series default | 462 | \series default |
461 | removing any local changes | 463 | removing any local changes |
462 | \begin_inset Foot | 464 | \begin_inset Foot |
463 | collapsed false | 465 | collapsed false |
464 | 466 | ||
465 | \layout Standard | 467 | \layout Standard |
466 | 468 | ||
467 | We should check whether all databases behave like this! (se) | 469 | We should check whether all databases behave like this! (se) |
468 | \end_inset | 470 | \end_inset |
469 | 471 | ||
470 | . | 472 | . |
471 | This may be done after receiving information about any change by an other | 473 | This may be done after receiving information about any change by an other |
472 | application which is not in scope of this chapter. | 474 | application which is not in scope of this chapter. |
473 | The other operations are self explaining and should work as expected. | 475 | The other operations are self explaining and should work as expected. |
474 | \layout Standard | 476 | \layout Standard |
475 | 477 | ||
476 | If you want to work with the existing dataset, you need to get a list of | 478 | If you want to work with the existing dataset, you need to get a list of |
477 | all available information. | 479 | all available information. |
478 | This list is returned by the call | 480 | This list is returned by the call |
479 | \begin_inset Quotes gld | 481 | \begin_inset Quotes gld |
480 | \end_inset | 482 | \end_inset |
481 | 483 | ||
482 | allRecords() | 484 | allRecords() |
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 |
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} |
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 | |||
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 | ||
514 | find() | 529 | find() |
515 | \begin_inset Quotes grd | 530 | \begin_inset Quotes grd |
516 | \end_inset | 531 | \end_inset |
517 | 532 | ||
518 | with a valid UID as parameter: | 533 | with a valid UID as parameter: |
519 | \layout LyX-Code | 534 | \layout LyX-Code |
520 | 535 | ||
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 |
527 | 612 | ||
528 | How to Access PIM-Data: Detailed View | 613 | How to Access PIM-Data: Detailed View |
529 | \layout Standard | 614 | \layout Standard |
530 | 615 | ||
531 | As shown in the previous chapter, all we need to access the PIM-Database | 616 | As shown in the previous chapter, all we need to access the PIM-Database |
532 | is to request an access-object from the OPimAccessFactory and to use it. | 617 | is to request an access-object from the OPimAccessFactory and to use it. |
533 | We will now introduce some special features of this factory (see section | 618 | We will now introduce some special features of this factory (see section |
534 | 619 | ||
535 | \begin_inset LatexCommand \ref{sec:Advanced-Factory-Features} | 620 | \begin_inset LatexCommand \ref{sec:Advanced-Factory-Features} |
536 | 621 | ||
537 | \end_inset | 622 | \end_inset |
538 | 623 | ||
539 | ), followed by some very important features like searching and sorting in | 624 | ), followed by some very important features like searching and sorting in |
540 | section | 625 | section |
541 | \begin_inset LatexCommand \ref{sec:Special-Features:-Searching} | 626 | \begin_inset LatexCommand \ref{sec:Special-Features:-Searching} |
542 | 627 | ||
543 | \end_inset | 628 | \end_inset |
544 | 629 | ||
545 | . | 630 | . |
546 | If you are interested in accessing data without take care about their types, | 631 | If you are interested in accessing data without take care about their types, |
547 | section | 632 | section |
548 | \begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase} | 633 | \begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase} |
549 | 634 | ||
550 | \end_inset | 635 | \end_inset |
551 | 636 | ||
552 | will show how to do this, followed by a short introduction about delayed | 637 | will show how to do this, followed by a short introduction about delayed |
553 | loading in section | 638 | loading in section |
554 | \begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:} | 639 | \begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:} |
555 | 640 | ||
556 | \end_inset | 641 | \end_inset |
557 | 642 | ||
558 | . | 643 | . |
559 | \layout Standard | 644 | \layout Standard |
560 | 645 | ||
561 | But first we will start with introducing some features of the | 646 | But first we will start with introducing some features of the |
562 | \series bold | 647 | \series bold |
563 | OPimAccessFactory | 648 | OPimAccessFactory |
564 | \series default | 649 | \series default |
565 | . | 650 | . |
566 | \layout Section | 651 | \layout Section |
567 | 652 | ||
568 | Advanced Factory Features | 653 | Advanced Factory Features |
569 | \begin_inset LatexCommand \label{sec:Advanced-Factory-Features} | 654 | \begin_inset LatexCommand \label{sec:Advanced-Factory-Features} |
570 | 655 | ||
571 | \end_inset | 656 | \end_inset |
572 | 657 | ||
573 | 658 | ||
574 | \layout Standard | 659 | \layout Standard |
575 | 660 | ||
576 | In the previous chapter we used the operation | 661 | In the previous chapter we used the operation |
577 | \begin_inset Quotes gld | 662 | \begin_inset Quotes gld |
578 | \end_inset | 663 | \end_inset |
579 | 664 | ||
580 | defaultAccess() | 665 | defaultAccess() |
581 | \begin_inset Quotes grd | 666 | \begin_inset Quotes grd |
582 | \end_inset | 667 | \end_inset |
583 | 668 | ||
584 | to request an access-object to the default backend. | 669 | to request an access-object to the default backend. |
585 | Whether this default backend will access the XML, VCard or SQLite database | 670 | Whether this default backend will access the XML, VCard or SQLite database |
586 | type, is defined by the configuration file | 671 | type, is defined by the configuration file |
587 | \begin_inset Quotes gld | 672 | \begin_inset Quotes gld |
588 | \end_inset | 673 | \end_inset |
589 | 674 | ||
590 | pimaccess.conf | 675 | pimaccess.conf |
591 | \begin_inset Quotes grd | 676 | \begin_inset Quotes grd |
592 | \end_inset | 677 | \end_inset |
593 | 678 | ||
594 | which is stored in the directory | 679 | which is stored in the directory |
595 | \begin_inset Quotes gld | 680 | \begin_inset Quotes gld |
596 | \end_inset | 681 | \end_inset |
597 | 682 | ||
598 | Settings | 683 | Settings |
599 | \begin_inset Quotes grd | 684 | \begin_inset Quotes grd |
600 | \end_inset | 685 | \end_inset |
601 | 686 | ||
602 | , stored in the user home directory. | 687 | , stored in the user home directory. |
603 | Changing this setting will take effect to all applications using | 688 | Changing this setting will take effect to all applications using |
604 | \begin_inset Quotes gld | 689 | \begin_inset Quotes gld |
605 | \end_inset | 690 | \end_inset |
606 | 691 | ||
607 | defaultAccess() | 692 | defaultAccess() |
608 | \begin_inset Quotes grd | 693 | \begin_inset Quotes grd |
609 | \end_inset | 694 | \end_inset |
610 | 695 | ||
611 | . | 696 | . |
612 | Therefore it is not a good idea to modify a global setting, if an application | 697 | Therefore it is not a good idea to modify a global setting, if an application |
613 | should access a special database type, for instance to move data from one | 698 | should access a special database type, for instance to move data from one |
614 | database to an other. | 699 | database to an other. |
615 | 700 | ||
616 | \layout Standard | 701 | \layout Standard |
617 | 702 | ||
618 | If the developer wants to select a special database type for sure without | 703 | If the developer wants to select a special database type for sure without |
619 | unnecessary side effects, he has to use the operation | 704 | unnecessary side effects, he has to use the operation |
620 | \emph on | 705 | \emph on |
621 | create() | 706 | create() |
622 | \emph default | 707 | \emph default |
623 | which has the following parameters: | 708 | which has the following parameters: |
624 | \layout LyX-Code | 709 | \layout LyX-Code |
625 | 710 | ||
626 | T* create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle, | 711 | T* create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle, |
627 | const QString &appName, const QString &fileName=QString::null) | 712 | const QString &appName, const QString &fileName=QString::null) |
628 | \layout Standard | 713 | \layout Standard |
629 | 714 | ||
630 | Some parameters are already known, like type and appName (see section | 715 | Some parameters are already known, like type and appName (see section |
631 | \begin_inset LatexCommand \ref{sec:Instantiate-the-Access} | 716 | \begin_inset LatexCommand \ref{sec:Instantiate-the-Access} |
632 | 717 | ||
633 | \end_inset | 718 | \end_inset |
634 | 719 | ||
635 | ). | 720 | ). |
636 | The new parameter | 721 | The new parameter |
637 | \begin_inset Quotes gld | 722 | \begin_inset Quotes gld |
638 | \end_inset | 723 | \end_inset |
639 | 724 | ||
640 | dbStyle | 725 | dbStyle |
641 | \begin_inset Quotes grd | 726 | \begin_inset Quotes grd |
642 | \end_inset | 727 | \end_inset |
643 | 728 | ||
644 | defines which database type should be selected. | 729 | defines which database type should be selected. |
645 | Possible values could be found in the enumeration | 730 | Possible values could be found in the enumeration |
646 | \emph on | 731 | \emph on |
647 | DataBaseStyle | 732 | DataBaseStyle |
648 | \emph default | 733 | \emph default |
649 | in the class | 734 | in the class |
650 | \series bold | 735 | \series bold |
651 | OPimGlobal | 736 | OPimGlobal |
652 | \series default | 737 | \series default |
653 | (see | 738 | (see |
654 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html} | 739 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html} |
655 | 740 | ||
656 | \end_inset | 741 | \end_inset |
657 | 742 | ||
658 | ). | 743 | ). |
659 | 744 | ||
660 | \begin_inset Quotes gld | 745 | \begin_inset Quotes gld |
661 | \end_inset | 746 | \end_inset |
662 | 747 | ||
663 | DEFAULT | 748 | DEFAULT |
664 | \begin_inset Quotes grd | 749 | \begin_inset Quotes grd |
665 | \end_inset | 750 | \end_inset |
666 | 751 | ||
667 | selects the default database and therefore behaves exactly as the operation | 752 | selects the default database and therefore behaves exactly as the operation |
668 | 753 | ||
669 | \begin_inset Quotes gld | 754 | \begin_inset Quotes gld |
670 | \end_inset | 755 | \end_inset |
671 | 756 | ||
672 | defaultAccess() | 757 | defaultAccess() |
673 | \begin_inset Quotes grd | 758 | \begin_inset Quotes grd |
674 | \end_inset | 759 | \end_inset |
675 | 760 | ||
676 | above. | 761 | above. |
677 | 762 | ||
678 | \begin_inset Quotes gld | 763 | \begin_inset Quotes gld |
679 | \end_inset | 764 | \end_inset |
680 | 765 | ||
681 | UNKOWN | 766 | UNKOWN |
682 | \begin_inset Quotes grd | 767 | \begin_inset Quotes grd |
683 | \end_inset | 768 | \end_inset |
684 | 769 | ||
685 | is just defined for internal reasons and should not be used be the developer. | 770 | is just defined for internal reasons and should not be used be the developer. |
686 | The remaining values ( | 771 | The remaining values ( |
687 | \begin_inset Quotes gld | 772 | \begin_inset Quotes gld |
688 | \end_inset | 773 | \end_inset |
689 | 774 | ||
690 | XML | 775 | XML |
691 | \begin_inset Quotes grd | 776 | \begin_inset Quotes grd |
692 | \end_inset | 777 | \end_inset |
693 | 778 | ||
694 | , | 779 | , |
695 | \begin_inset Quotes gld | 780 | \begin_inset Quotes gld |
696 | \end_inset | 781 | \end_inset |
697 | 782 | ||
698 | SQL | 783 | SQL |
699 | \begin_inset Quotes grd | 784 | \begin_inset Quotes grd |
700 | \end_inset | 785 | \end_inset |
701 | 786 | ||
702 | , | 787 | , |
703 | \begin_inset Quotes gld | 788 | \begin_inset Quotes gld |
704 | \end_inset | 789 | \end_inset |
705 | 790 | ||
706 | VCARD | 791 | VCARD |
707 | \begin_inset Quotes grd | 792 | \begin_inset Quotes grd |
708 | \end_inset | 793 | \end_inset |
709 | 794 | ||
710 | ) should be used to select the desired database backend. | 795 | ) should be used to select the desired database backend. |
711 | The last parameter | 796 | The last parameter |
712 | \begin_inset Quotes gld | 797 | \begin_inset Quotes gld |
713 | \end_inset | 798 | \end_inset |
714 | 799 | ||
715 | fileName | 800 | fileName |
716 | \begin_inset Quotes grd | 801 | \begin_inset Quotes grd |
717 | \end_inset | 802 | \end_inset |
718 | 803 | ||
719 | is used to select a special file name and path to the database file. | 804 | is used to select a special file name and path to the database file. |
720 | Thus, you can use it to access database files which don't reside on the | 805 | Thus, you can use it to access database files which don't reside on the |
721 | default path or have other filenames as it is defined by the platform as | 806 | default path or have other filenames as it is defined by the platform as |
722 | default (in normal cases | 807 | default (in normal cases |
723 | \begin_inset Quotes gld | 808 | \begin_inset Quotes gld |
724 | \end_inset | 809 | \end_inset |
725 | 810 | ||
726 | ~/Applications/<name of application>/ | 811 | ~/Applications/<name of application>/ |
727 | \begin_inset Quotes grd | 812 | \begin_inset Quotes grd |
728 | \end_inset | 813 | \end_inset |
729 | 814 | ||
730 | ). | 815 | ). |
731 | \layout Standard | 816 | \layout Standard |
732 | 817 | ||
733 | In the next section we will discuss how searching and sorting take place | 818 | In the next section we will discuss how searching and sorting take place |
734 | with this API. | 819 | with this API. |
735 | \layout Section | 820 | \layout Section |
736 | 821 | ||
737 | Special Features: Searching and Sorting | 822 | Special Features: Searching and Sorting |
738 | \begin_inset LatexCommand \label{sec:Special-Features:-Searching} | 823 | \begin_inset LatexCommand \label{sec:Special-Features:-Searching} |
739 | 824 | ||
740 | \end_inset | 825 | \end_inset |
741 | 826 | ||
742 | 827 | ||
743 | \layout Standard | 828 | \layout Standard |
744 | 829 | ||
745 | In most cases it is not sufficient to receive just a list of all information | 830 | In most cases it is not sufficient to receive just a list of all information |
746 | in a database. | 831 | in a database. |
747 | It is essential to get a subset of the information available and to be | 832 | It is essential to get a subset of the information available and to be |
748 | able to sort it. | 833 | able to sort it. |
749 | For this kind of exercise we provide some special operations which provide | 834 | For this kind of exercise we provide some special operations which provide |
750 | searching and sorting in an incremental manner | 835 | searching and sorting in an incremental manner |
751 | \begin_inset Foot | 836 | \begin_inset Foot |
752 | collapsed false | 837 | 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 |
774 | 852 | ||
775 | Search a complete database for a special regular expression, using | 853 | Search a complete database for a special regular expression, using |
776 | \begin_inset Quotes gld | 854 | \begin_inset Quotes gld |
777 | \end_inset | 855 | \end_inset |
778 | 856 | ||
779 | matchRegexp () | 857 | matchRegexp () |
780 | \begin_inset Quotes grd | 858 | \begin_inset Quotes grd |
781 | \end_inset | 859 | \end_inset |
782 | 860 | ||
783 | . | 861 | . |
784 | This search type returns all records which contains the given regular expressio | 862 | This search type returns all records which contains the given regular expressio |
785 | n | 863 | n |
786 | \emph on | 864 | \emph on |
787 | anywhere | 865 | anywhere |
788 | \emph default | 866 | \emph default |
789 | in the dataset. | 867 | in the dataset. |
790 | This search type is used for example by the opie search tool (OSearch) | 868 | This search type is used for example by the opie search tool (OSearch) |
791 | (see | 869 | (see |
792 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/} | 870 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/} |
793 | 871 | ||
794 | \end_inset | 872 | \end_inset |
795 | 873 | ||
796 | and | 874 | and |
797 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/adresssearch.cpp?rev=1.12&content-type=text/x-cvsweb-markup} | 875 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/adresssearch.cpp?rev=1.12&content-type=text/x-cvsweb-markup} |
798 | 876 | ||
799 | \end_inset | 877 | \end_inset |
800 | 878 | ||
801 | ). | 879 | ). |
802 | \layout Enumerate | 880 | \layout Enumerate |
803 | 881 | ||
804 | Define a so called | 882 | Define a so called |
805 | \begin_inset Quotes gld | 883 | \begin_inset Quotes gld |
806 | \end_inset | 884 | \end_inset |
807 | 885 | ||
808 | Query By Example | 886 | Query By Example |
809 | \begin_inset Quotes grd | 887 | \begin_inset Quotes grd |
810 | \end_inset | 888 | \end_inset |
811 | 889 | ||
812 | search query which allows to define what should be searched and which internal | 890 | search query which allows to define what should be searched and which internal |
813 | data fields should be taken into account. | 891 | data fields should be taken into account. |
814 | This is a very advanced search function which allows to search in a very | 892 | This is a very advanced search function which allows to search in a very |
815 | fine granular manner. | 893 | fine granular manner. |
816 | \layout Standard | 894 | \layout Standard |
817 | 895 | ||
818 | We will start with the first and very simple | 896 | We will start with the first and very simple |
819 | \begin_inset Quotes grd | 897 | \begin_inset Quotes grd |
820 | \end_inset | 898 | \end_inset |
821 | 899 | ||
822 | matchRegexp() | 900 | matchRegexp() |
823 | \begin_inset Quotes grd | 901 | \begin_inset Quotes grd |
824 | \end_inset | 902 | \end_inset |
825 | 903 | ||
826 | , followed by the query by example search query. | 904 | , followed by the query by example search query. |
827 | \layout Subsection | 905 | \layout Subsection |
828 | 906 | ||
829 | Searching with | 907 | Searching with |
830 | \begin_inset Quotes gld | 908 | \begin_inset Quotes gld |
831 | \end_inset | 909 | \end_inset |
832 | 910 | ||
833 | matchRegexp() | 911 | matchRegexp() |
834 | \begin_inset Quotes grd | 912 | \begin_inset Quotes grd |
835 | \end_inset | 913 | \end_inset |
836 | 914 | ||
837 | 915 | ||
838 | \layout Standard | 916 | \layout Standard |
839 | 917 | ||
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 | ||
858 | \end_inset | 936 | \end_inset |
859 | 937 | ||
860 | you have to use the | 938 | you have to use the |
861 | \begin_inset Quotes gld | 939 | \begin_inset Quotes gld |
862 | \end_inset | 940 | \end_inset |
863 | 941 | ||
864 | find() | 942 | find() |
865 | \begin_inset Quotes grd | 943 | \begin_inset Quotes grd |
866 | \end_inset | 944 | \end_inset |
867 | 945 | ||
868 | operation to request the real records. | 946 | operation to request the real records. |
869 | \layout Subsection | 947 | \layout Subsection |
870 | 948 | ||
871 | Searching with Query By Example | 949 | Searching with Query By Example |
872 | \layout Standard | 950 | \layout Standard |
873 | 951 | ||
874 | The query by example search style is working is using a data object (for | 952 | The query by example search style is working is using a data object (for |
875 | instance an OPimContact) to store the search query. | 953 | instance an OPimContact) to store the search query. |
876 | For instance, if you want to request all entries which contains the last | 954 | For instance, if you want to request all entries which contains the last |
877 | name | 955 | name |
878 | \begin_inset Quotes gld | 956 | \begin_inset Quotes gld |
879 | \end_inset | 957 | \end_inset |
880 | 958 | ||
881 | Eilers | 959 | Eilers |
882 | \begin_inset Quotes grd | 960 | \begin_inset Quotes grd |
883 | \end_inset | 961 | \end_inset |
884 | 962 | ||
885 | and the home zip number should start with | 963 | and the home zip number should start with |
886 | \begin_inset Quotes gld | 964 | \begin_inset Quotes gld |
887 | \end_inset | 965 | \end_inset |
888 | 966 | ||
889 | 3 | 967 | 3 |
890 | \begin_inset Quotes grd | 968 | \begin_inset Quotes grd |
891 | \end_inset | 969 | \end_inset |
892 | 970 | ||
893 | you have to do the following: | 971 | you have to do the following: |
894 | \layout LyX-Code | 972 | \layout LyX-Code |
895 | 973 | ||
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 |
922 | \begin_inset Quotes gld | 984 | \begin_inset Quotes gld |
923 | \end_inset | 985 | \end_inset |
924 | 986 | ||
925 | OPimContact | 987 | OPimContact |
926 | \begin_inset Quotes grd | 988 | \begin_inset Quotes grd |
927 | \end_inset | 989 | \end_inset |
928 | 990 | ||
929 | and fill into two fields the query information. | 991 | and fill into two fields the query information. |
930 | All filled fields are taken for the search operation (using an | 992 | All filled fields are taken for the search operation (using an |
931 | \begin_inset Quotes gld | 993 | \begin_inset Quotes gld |
932 | \end_inset | 994 | \end_inset |
933 | 995 | ||
934 | AND | 996 | AND |
935 | \begin_inset Quotes grd | 997 | \begin_inset Quotes grd |
936 | \end_inset | 998 | \end_inset |
937 | 999 | ||
938 | operation), the unused ones are simply ignored. | 1000 | operation), the unused ones are simply ignored. |
939 | As we just want to search for entries which zip number starts with a | 1001 | As we just want to search for entries which zip number starts with a |
940 | \begin_inset Quotes gld | 1002 | \begin_inset Quotes gld |
941 | \end_inset | 1003 | \end_inset |
942 | 1004 | ||
943 | 3 | 1005 | 3 |
944 | \begin_inset Quotes grd | 1006 | \begin_inset Quotes grd |
945 | \end_inset | 1007 | \end_inset |
946 | 1008 | ||
947 | we use the Wildcard | 1009 | we use the Wildcard |
948 | \begin_inset Quotes gld | 1010 | \begin_inset Quotes gld |
949 | \end_inset | 1011 | \end_inset |
950 | 1012 | ||
951 | * | 1013 | * |
952 | \begin_inset Quotes grd | 1014 | \begin_inset Quotes grd |
953 | \end_inset | 1015 | \end_inset |
954 | 1016 | ||
955 | as we would do to find files in a filesystem. | 1017 | as we would do to find files in a filesystem. |
956 | \layout Standard | 1018 | \layout Standard |
957 | 1019 | ||
958 | The next step is to put this query into the operation which is defined like | 1020 | 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 |
967 | \begin_inset Quotes gld | 1030 | \begin_inset Quotes gld |
968 | \end_inset | 1031 | \end_inset |
969 | 1032 | ||
970 | query | 1033 | query |
971 | \begin_inset Quotes grd | 1034 | \begin_inset Quotes grd |
972 | \end_inset | 1035 | \end_inset |
973 | 1036 | ||
974 | should used to set our query, but we have to set the parameter | 1037 | should used to set our query, but we have to set the parameter |
975 | \begin_inset Quotes gld | 1038 | \begin_inset Quotes gld |
976 | \end_inset | 1039 | \end_inset |
977 | 1040 | ||
978 | querySettings | 1041 | querySettings |
979 | \begin_inset Quotes grd | 1042 | \begin_inset Quotes grd |
980 | \end_inset | 1043 | \end_inset |
981 | 1044 | ||
982 | to configure the search properly. | 1045 | to configure the search properly. |
983 | This settings are defined by the enumeration | 1046 | This settings are defined by the enumeration |
984 | \begin_inset Quotes gld | 1047 | \begin_inset Quotes gld |
985 | \end_inset | 1048 | \end_inset |
986 | 1049 | ||
987 | QuerySettings | 1050 | QuerySettings |
988 | \begin_inset Quotes grd | 1051 | \begin_inset Quotes grd |
989 | \end_inset | 1052 | \end_inset |
990 | 1053 | ||
991 | in the class | 1054 | in the class |
992 | \series bold | 1055 | \series bold |
993 | OPimBase | 1056 | OPimBase |
994 | \series default | 1057 | \series default |
995 | (see | 1058 | (see |
996 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19} | 1059 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19} |
997 | 1060 | ||
998 | \end_inset | 1061 | \end_inset |
999 | 1062 | ||
1000 | ). | 1063 | ). |
1001 | The meaning of all settings will be discussed later. | 1064 | The meaning of all settings will be discussed later. |
1002 | For the first turn we will just concentrate on the things we need in this | 1065 | For the first turn we will just concentrate on the things we need in this |
1003 | case. | 1066 | case. |
1004 | As we use Wildcards in | 1067 | As we use Wildcards in |
1005 | \begin_inset Quotes gld | 1068 | \begin_inset Quotes gld |
1006 | \end_inset | 1069 | \end_inset |
1007 | 1070 | ||
1008 | setHomeZip | 1071 | setHomeZip |
1009 | \begin_inset Quotes grd | 1072 | \begin_inset Quotes grd |
1010 | \end_inset | 1073 | \end_inset |
1011 | 1074 | ||
1012 | we have to use | 1075 | we have to use |
1013 | \begin_inset Quotes gld | 1076 | \begin_inset Quotes gld |
1014 | \end_inset | 1077 | \end_inset |
1015 | 1078 | ||
1016 | WildCards | 1079 | WildCards |
1017 | \begin_inset Quotes grd | 1080 | \begin_inset Quotes grd |
1018 | \end_inset | 1081 | \end_inset |
1019 | 1082 | ||
1020 | . | 1083 | . |
1021 | And we want to be sure to find lower case names, too, which may be mistyped | 1084 | And we want to be sure to find lower case names, too, which may be mistyped |
1022 | (like | 1085 | (like |
1023 | \begin_inset Quotes gld | 1086 | \begin_inset Quotes gld |
1024 | \end_inset | 1087 | \end_inset |
1025 | 1088 | ||
1026 | eilers | 1089 | eilers |
1027 | \begin_inset Quotes grd | 1090 | \begin_inset Quotes grd |
1028 | \end_inset | 1091 | \end_inset |
1029 | 1092 | ||
1030 | , | 1093 | , |
1031 | \begin_inset Quotes gld | 1094 | \begin_inset Quotes gld |
1032 | \end_inset | 1095 | \end_inset |
1033 | 1096 | ||
1034 | eIlers | 1097 | eIlers |
1035 | \begin_inset Quotes grd | 1098 | \begin_inset Quotes grd |
1036 | \end_inset | 1099 | \end_inset |
1037 | 1100 | ||
1038 | , ...). | 1101 | , ...). |
1039 | Thus, we have to use the | 1102 | Thus, we have to use the |
1040 | \begin_inset Quotes gld | 1103 | \begin_inset Quotes gld |
1041 | \end_inset | 1104 | \end_inset |
1042 | 1105 | ||
1043 | IgnoreCase | 1106 | IgnoreCase |
1044 | \begin_inset Quotes grd | 1107 | \begin_inset Quotes grd |
1045 | \end_inset | 1108 | \end_inset |
1046 | 1109 | ||
1047 | setting which is to combine with the other using an | 1110 | setting which is to combine with the other using an |
1048 | \begin_inset Quotes gld | 1111 | \begin_inset Quotes gld |
1049 | \end_inset | 1112 | \end_inset |
1050 | 1113 | ||
1051 | or | 1114 | or |
1052 | \begin_inset Quotes grd | 1115 | \begin_inset Quotes grd |
1053 | \end_inset | 1116 | \end_inset |
1054 | 1117 | ||
1055 | operator. | 1118 | operator. |
1056 | The last parameter | 1119 | The last parameter |
1057 | \begin_inset Quotes gld | 1120 | \begin_inset Quotes gld |
1058 | \end_inset | 1121 | \end_inset |
1059 | 1122 | ||
1060 | endperiod | 1123 | endperiod |
1061 | \begin_inset Quotes grd | 1124 | \begin_inset Quotes grd |
1062 | \end_inset | 1125 | \end_inset |
1063 | 1126 | ||
1064 | will be ignored for this case which will look like this: | 1127 | will be ignored for this case which will look like this: |
1065 | \layout LyX-Code | 1128 | \layout LyX-Code |
1066 | 1129 | ||
1067 | use namespace Opie; | 1130 | use namespace Opie; |
1068 | \layout LyX-Code | 1131 | \layout LyX-Code |
1069 | 1132 | ||
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, |
1078 | using the | 1144 | using the |
1079 | \begin_inset Quotes gld | 1145 | \begin_inset Quotes gld |
1080 | \end_inset | 1146 | \end_inset |
1081 | 1147 | ||
1082 | find() | 1148 | find() |
1083 | \begin_inset Quotes grd | 1149 | \begin_inset Quotes grd |
1084 | \end_inset | 1150 | \end_inset |
1085 | 1151 | ||
1086 | operation. | 1152 | operation. |
1087 | \layout Standard | 1153 | \layout Standard |
1088 | 1154 | ||
1089 | It should be clear at this stage, that this query is very powerful and - | 1155 | It should be clear at this stage, that this query is very powerful and - |
1090 | depending to the querySettings - could be very complicated to implement. | 1156 | depending to the querySettings - could be very complicated to implement. |
1091 | Thus, not all backends do support all features defined by querySettings | 1157 | Thus, not all backends do support all features defined by querySettings |
1092 | \begin_inset Foot | 1158 | \begin_inset Foot |
1093 | collapsed false | 1159 | collapsed false |
1094 | 1160 | ||
1095 | \layout Standard | 1161 | \layout Standard |
1096 | 1162 | ||
1097 | At this time, just the contact database for XML and VCard is supporting | 1163 | At this time, just the contact database for XML and VCard is supporting |
1098 | all queries and combination of them. | 1164 | all queries and combination of them. |
1099 | All others just support subsets. | 1165 | All others just support subsets. |
1100 | \end_inset | 1166 | \end_inset |
1101 | 1167 | ||
1102 | . | 1168 | . |
1103 | To check which settings are supported and to be able to react dynamically | 1169 | To check which settings are supported and to be able to react dynamically |
1104 | on missing features (for instance to disable some search features in the | 1170 | on missing features (for instance to disable some search features in the |
1105 | application) we provide the following operations: | 1171 | application) we provide the following operations: |
1106 | \layout LyX-Code | 1172 | \layout LyX-Code |
1107 | 1173 | ||
1108 | bool hasQuerySettings( uint querySettings ); | 1174 | bool hasQuerySettings( uint querySettings ); |
1109 | \layout LyX-Code | 1175 | \layout LyX-Code |
1110 | 1176 | ||
1111 | uint querySettings(); | 1177 | uint querySettings(); |
1112 | \layout Standard | 1178 | \layout Standard |
1113 | 1179 | ||
1114 | The first operation | 1180 | The first operation |
1115 | \begin_inset Quotes gld | 1181 | \begin_inset Quotes gld |
1116 | \end_inset | 1182 | \end_inset |
1117 | 1183 | ||
1118 | hasQuerySettings() | 1184 | hasQuerySettings() |
1119 | \begin_inset Quotes grd | 1185 | \begin_inset Quotes grd |
1120 | \end_inset | 1186 | \end_inset |
1121 | 1187 | ||
1122 | may be used to ask whether the database can handle the given query settings. | 1188 | may be used to ask whether the database can handle the given query settings. |
1123 | In this example a call to | 1189 | In this example a call to |
1124 | \layout LyX-Code | 1190 | \layout LyX-Code |
1125 | 1191 | ||
1126 | hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase ); | 1192 | hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase ); |
1127 | \layout Standard | 1193 | \layout Standard |
1128 | 1194 | ||
1129 | should be answered with | 1195 | should be answered with |
1130 | \begin_inset Quotes gld | 1196 | \begin_inset Quotes gld |
1131 | \end_inset | 1197 | \end_inset |
1132 | 1198 | ||
1133 | true | 1199 | true |
1134 | \begin_inset Quotes grd | 1200 | \begin_inset Quotes grd |
1135 | \end_inset | 1201 | \end_inset |
1136 | 1202 | ||
1137 | . | 1203 | . |
1138 | If you need to ask which kind of queries are supported, the operation | 1204 | If you need to ask which kind of queries are supported, the operation |
1139 | \begin_inset Quotes gld | 1205 | \begin_inset Quotes gld |
1140 | \end_inset | 1206 | \end_inset |
1141 | 1207 | ||
1142 | querySettings() | 1208 | querySettings() |
1143 | \begin_inset Quotes grd | 1209 | \begin_inset Quotes grd |
1144 | \end_inset | 1210 | \end_inset |
1145 | 1211 | ||
1146 | will be your friend. | 1212 | will be your friend. |
1147 | It will return an unsigned integer value where a | 1213 | It will return an unsigned integer value where a |
1148 | \begin_inset Quotes gld | 1214 | \begin_inset Quotes gld |
1149 | \end_inset | 1215 | \end_inset |
1150 | 1216 | ||
1151 | 1 | 1217 | 1 |
1152 | \begin_inset Quotes grd | 1218 | \begin_inset Quotes grd |
1153 | \end_inset | 1219 | \end_inset |
1154 | 1220 | ||
1155 | is set for every available feature. | 1221 | is set for every available feature. |
1156 | \layout Standard | 1222 | \layout Standard |
1157 | 1223 | ||
1158 | The last parameter is called | 1224 | The last parameter is called |
1159 | \begin_inset Quotes gld | 1225 | \begin_inset Quotes gld |
1160 | \end_inset | 1226 | \end_inset |
1161 | 1227 | ||
1162 | startperiod | 1228 | startperiod |
1163 | \begin_inset Quotes grd | 1229 | \begin_inset Quotes grd |
1164 | \end_inset | 1230 | \end_inset |
1165 | 1231 | ||
1166 | which is used to set a time interval: | 1232 | which is used to set a time interval: |
1167 | \layout Standard | 1233 | \layout Standard |
1168 | 1234 | ||
1169 | In some cases, a time interval should be set to find for instance all entries | 1235 | In some cases, a time interval should be set to find for instance all entries |
1170 | between two dates (used for example by the birthday reminder for today | 1236 | between two dates (used for example by the birthday reminder for today |
1171 | (see here: | 1237 | (see here: |
1172 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/today/plugins/addressbook/addresspluginwidget.cpp?rev=1.14&content-type=text/x-cvsweb-markup} | 1238 | \begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/today/plugins/addressbook/addresspluginwidget.cpp?rev=1.14&content-type=text/x-cvsweb-markup} |
1173 | 1239 | ||
1174 | \end_inset | 1240 | \end_inset |
1175 | 1241 | ||
1176 | )) as requested by the setting | 1242 | )) as requested by the setting |
1177 | \begin_inset Quotes gld | 1243 | \begin_inset Quotes gld |
1178 | \end_inset | 1244 | \end_inset |
1179 | 1245 | ||
1180 | OPimBase::DateDiff | 1246 | OPimBase::DateDiff |
1181 | \begin_inset Quotes grd | 1247 | \begin_inset Quotes grd |
1182 | \end_inset | 1248 | \end_inset |
1183 | 1249 | ||
1184 | . | 1250 | . |
1185 | The date and time in the query object is used as the | 1251 | The date and time in the query object is used as the |
1186 | \series bold | 1252 | \series bold |
1187 | end | 1253 | end |
1188 | \series default | 1254 | \series default |
1189 | of the interval. | 1255 | of the interval. |
1190 | The start will be defined by the last parameter (if nothing is set, the | 1256 | The start will be defined by the last parameter (if nothing is set, the |
1191 | current date will be taken!). | 1257 | current date will be taken!). |
1192 | Therefore, it is possible to set a time frame for all searched entries. | 1258 | Therefore, it is possible to set a time frame for all searched entries. |
1193 | \layout Standard | 1259 | \layout Standard |
1194 | 1260 | ||
1195 | If you want to do incremental search operations, you may use the special | 1261 | If you want to do incremental search operations, you may use the special |
1196 | 1262 | ||
1197 | \begin_inset Quotes gld | 1263 | \begin_inset Quotes gld |
1198 | \end_inset | 1264 | \end_inset |
1199 | 1265 | ||
1200 | queryByExample() | 1266 | queryByExample() |
1201 | \begin_inset Quotes grd | 1267 | \begin_inset Quotes grd |
1202 | \end_inset | 1268 | \end_inset |
1203 | 1269 | ||
1204 | which takes a | 1270 | which takes a |
1205 | \begin_inset Quotes gld | 1271 | \begin_inset Quotes gld |
1206 | \end_inset | 1272 | \end_inset |
1207 | 1273 | ||
1208 | List | 1274 | List |
1209 | \begin_inset Quotes grd | 1275 | \begin_inset Quotes grd |
1210 | \end_inset | 1276 | \end_inset |
1211 | 1277 | ||
1212 | as the first parameter. | 1278 | as the first parameter. |
1213 | The search operation will just occur on this set of uid's! | 1279 | The search operation will just occur on this set of uid's! |
1214 | \layout Subsection | 1280 | \layout Subsection |
1215 | 1281 | ||
1216 | Sorting | 1282 | 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, |
1224 | const QArray< UID >& cats); | 1295 | \newline |
1296 | bool ascending, int sortOrder, int sortFilter, | ||
1297 | \newline | ||
1298 | const QArray< UID >& cats); | ||
1225 | \layout Standard | 1299 | \layout Standard |
1226 | 1300 | ||
1227 | This sort operation takes a list of uid's as returned for instance from | 1301 | This 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 |
1231 | \end_inset | 1305 | \end_inset |
1232 | 1306 | ||
1233 | ascending | 1307 | ascending |
1234 | \begin_inset Quotes grd | 1308 | \begin_inset Quotes grd |
1235 | \end_inset | 1309 | \end_inset |
1236 | 1310 | ||
1237 | defines whether the sort should be in an ascending order or not. | 1311 | defines whether the sort should be in an ascending order or not. |
1238 | 1312 | ||
1239 | \begin_inset Quotes gld | 1313 | \begin_inset Quotes gld |
1240 | \end_inset | 1314 | \end_inset |
1241 | 1315 | ||
1242 | sortOrder | 1316 | sortOrder |
1243 | \begin_inset Quotes grd | 1317 | \begin_inset Quotes grd |
1244 | \end_inset | 1318 | \end_inset |
1245 | 1319 | ||
1246 | is defined by the enumerations | 1320 | is defined by the enumerations |
1247 | \begin_inset Quotes gld | 1321 | \begin_inset Quotes gld |
1248 | \end_inset | 1322 | \end_inset |
1249 | 1323 | ||
1250 | SortOrder | 1324 | SortOrder |
1251 | \begin_inset Quotes grd | 1325 | \begin_inset Quotes grd |
1252 | \end_inset | 1326 | \end_inset |
1253 | 1327 | ||
1254 | and | 1328 | and |
1255 | \begin_inset Quotes gld | 1329 | \begin_inset Quotes gld |
1256 | \end_inset | 1330 | \end_inset |
1257 | 1331 | ||
1258 | SortOrderBase | 1332 | SortOrderBase |
1259 | \begin_inset Quotes grd | 1333 | \begin_inset Quotes grd |
1260 | \end_inset | 1334 | \end_inset |
1261 | 1335 | ||
1262 | and defines which field should be used to sort (see for | 1336 | and defines which field should be used to sort (see for |
1263 | \series bold | 1337 | \series bold |
1264 | OPimContactAccess | 1338 | OPimContactAccess |
1265 | \series default | 1339 | \series default |
1266 | : | 1340 | : |
1267 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html} | 1341 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html} |
1268 | 1342 | ||
1269 | \end_inset | 1343 | \end_inset |
1270 | 1344 | ||
1271 | , for | 1345 | , for |
1272 | \series bold | 1346 | \series bold |
1273 | ODateBookAccess | 1347 | ODateBookAccess |
1274 | \series default | 1348 | \series default |
1275 | : | 1349 | : |
1276 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html} | 1350 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html} |
1277 | 1351 | ||
1278 | \end_inset | 1352 | \end_inset |
1279 | 1353 | ||
1280 | and for | 1354 | and for |
1281 | \series bold | 1355 | \series bold |
1282 | OPimTodoAccess | 1356 | OPimTodoAccess |
1283 | \series default | 1357 | \series default |
1284 | : | 1358 | : |
1285 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html} | 1359 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html} |
1286 | 1360 | ||
1287 | \end_inset | 1361 | \end_inset |
1288 | 1362 | ||
1289 | and for common settings | 1363 | and for common settings |
1290 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21} | 1364 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21} |
1291 | 1365 | ||
1292 | \end_inset | 1366 | \end_inset |
1293 | 1367 | ||
1294 | ). | 1368 | ). |
1295 | \layout Standard | 1369 | \layout Standard |
1296 | 1370 | ||
1297 | The | 1371 | The |
1298 | \begin_inset Quotes gld | 1372 | \begin_inset Quotes gld |
1299 | \end_inset | 1373 | \end_inset |
1300 | 1374 | ||
1301 | sortFilter | 1375 | sortFilter |
1302 | \begin_inset Quotes grd | 1376 | \begin_inset Quotes grd |
1303 | \end_inset | 1377 | \end_inset |
1304 | 1378 | ||
1305 | parameter allows to remove some entries which are not interesting for the | 1379 | parameter allows to remove some entries which are not interesting for the |
1306 | result and is defined in the same classes as | 1380 | result and is defined in the same classes as |
1307 | \begin_inset Quotes gld | 1381 | \begin_inset Quotes gld |
1308 | \end_inset | 1382 | \end_inset |
1309 | 1383 | ||
1310 | sortOrder | 1384 | sortOrder |
1311 | \begin_inset Quotes grd | 1385 | \begin_inset Quotes grd |
1312 | \end_inset | 1386 | \end_inset |
1313 | 1387 | ||
1314 | by the enumeration | 1388 | by the enumeration |
1315 | \begin_inset Quotes gld | 1389 | \begin_inset Quotes gld |
1316 | \end_inset | 1390 | \end_inset |
1317 | 1391 | ||
1318 | SortFilter | 1392 | SortFilter |
1319 | \begin_inset Quotes grd | 1393 | \begin_inset Quotes grd |
1320 | \end_inset | 1394 | \end_inset |
1321 | 1395 | ||
1322 | and | 1396 | and |
1323 | \begin_inset Quotes gld | 1397 | \begin_inset Quotes gld |
1324 | \end_inset | 1398 | \end_inset |
1325 | 1399 | ||
1326 | SortFilterBase | 1400 | SortFilterBase |
1327 | \begin_inset Quotes grd | 1401 | \begin_inset Quotes grd |
1328 | \end_inset | 1402 | \end_inset |
1329 | 1403 | ||
1330 | . | 1404 | . |
1331 | The list of id's in | 1405 | The list of id's in |
1332 | \begin_inset Quotes gld | 1406 | \begin_inset Quotes gld |
1333 | \end_inset | 1407 | \end_inset |
1334 | 1408 | ||
1335 | cats | 1409 | cats |
1336 | \begin_inset Quotes grd | 1410 | \begin_inset Quotes grd |
1337 | \end_inset | 1411 | \end_inset |
1338 | 1412 | ||
1339 | allows to remain just these entries which are included in the list of categorie | 1413 | allows to remain just these entries which are included in the list of categorie |
1340 | s. | 1414 | s. |
1341 | \layout Standard | 1415 | \layout Standard |
1342 | 1416 | ||
1343 | The returned list contains the same uid's as given via | 1417 | The returned list contains the same uid's as given via |
1344 | \begin_inset Quotes gld | 1418 | \begin_inset Quotes gld |
1345 | \end_inset | 1419 | \end_inset |
1346 | 1420 | ||
1347 | list | 1421 | list |
1348 | \begin_inset Quotes grd | 1422 | \begin_inset Quotes grd |
1349 | \end_inset | 1423 | \end_inset |
1350 | 1424 | ||
1351 | (or a subset of it, as the sortFilter and category list removes some entries) | 1425 | (or a subset of it, as the sortFilter and category list removes some entries) |
1352 | with a modified order as | 1426 | with a modified order as |