Diffstat (limited to 'development/pim/pim_howto/pim_howto.lyx') (more/less context) (ignore whitespace changes)
-rw-r--r-- | development/pim/pim_howto/pim_howto.lyx | 238 |
1 files changed, 218 insertions, 20 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx index 2b08be8..4571996 100644 --- a/development/pim/pim_howto/pim_howto.lyx +++ b/development/pim/pim_howto/pim_howto.lyx | |||
@@ -109,6 +109,6 @@ While starting to read the automatically generated API-documentation, the | |||
109 | user may be confused by a lot of unneccessary classes and details which | 109 | user may be confused by a lot of unneccessary classes and details which |
110 | makes the quick start not as easy as expected. | 110 | makes the quick start not as easy as possible. |
111 | Due to the fact that a user who just want to access data will not need | 111 | Due to the fact that a user will not need most of the details, this paper |
112 | most of the details, this paper should help to start to be confortable | 112 | should help to start to become confortable with those details he need to |
113 | with the details he need to solve his problems. | 113 | solve his problems. |
114 | \layout Standard | 114 | \layout Standard |
@@ -127,3 +127,3 @@ Introduction | |||
127 | Before starting to jump into the work, we should introduce some specialities | 127 | Before starting to jump into the work, we should introduce some specialities |
128 | of the PIM API first. | 128 | of the PIM API, first. |
129 | To know these facts should help to avoid possible irritations and misunderstand | 129 | To know these facts should help to avoid possible irritations and misunderstand |
@@ -135,3 +135,3 @@ The PIM-API heavily uses C++ templates (as known as generic classes), but | |||
135 | they work! Most of the API works without even seeing the templates. | 135 | they work! Most of the API works without even seeing the templates. |
136 | In some cases whe have to use them (for instance to use the factory classes) | 136 | In some cases whe 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 | 137 | but this guide will provide examples which should help to find the path |
@@ -153,3 +153,3 @@ backend. | |||
153 | how to access the databases and what to do with the data. | 153 | how to access the databases and what to do with the data. |
154 | This paper just focusses the frontend as we just want to access data. | 154 | As we just want to access data, this paper just focusses the frontend. |
155 | Thus, you should ignore all classes which contains something like | 155 | Thus, you should ignore all classes which contains something like |
@@ -326,3 +326,3 @@ delete sourceDB; | |||
326 | 326 | ||
327 | Accessing the access-object | 327 | Accessing the Access-Object |
328 | \begin_inset LatexCommand \label{sec:Accessing-the-access-object} | 328 | \begin_inset LatexCommand \label{sec:Accessing-the-access-object} |
@@ -425,4 +425,4 @@ bool replace (const T& t); | |||
425 | 425 | ||
426 | After receiving an access-object, we have to load the existing dataset, | 426 | After receiving an access-object, we have to load the existing dataset into |
427 | which is done by the | 427 | the backend, which is done by the |
428 | \begin_inset Quotes gld | 428 | \begin_inset Quotes gld |
@@ -501,3 +501,3 @@ List allRecords (); | |||
501 | 501 | ||
502 | In fact this | 502 | In fact, this |
503 | \emph on | 503 | \emph on |
@@ -585,3 +585,3 @@ defaultAccess() | |||
585 | Whether this default backend will access the XML, VCard or SQLite database | 585 | Whether this default backend will access the XML, VCard or SQLite database |
586 | type, this is defined by the configuration file | 586 | type, is defined by the configuration file |
587 | \begin_inset Quotes gld | 587 | \begin_inset Quotes gld |
@@ -617,4 +617,4 @@ defaultAccess() | |||
617 | 617 | ||
618 | If the developer wants to select a special database type for sure, he has | 618 | If the developer wants to select a special database type for sure without |
619 | to use the oparation | 619 | unnecessary side effects, he has to use the oparation |
620 | \emph on | 620 | \emph on |
@@ -761,3 +761,3 @@ FIXME: matchRegexp() does take a list of uid's. | |||
761 | . | 761 | . |
762 | Therfore it is possible to research a | 762 | Therefore it is possible to research a |
763 | \begin_inset Quotes gld | 763 | \begin_inset Quotes gld |
@@ -920,3 +920,3 @@ searchQuery.setHomeZip( | |||
920 | 920 | ||
921 | We use a usual | 921 | We use an usual |
922 | \begin_inset Quotes gld | 922 | \begin_inset Quotes gld |
@@ -928,3 +928,12 @@ OPimContact | |||
928 | 928 | ||
929 | and fill into two fields the search information. | 929 | and fill into two fields the query information. |
930 | All filled fields are taken for the search operation (using an | ||
931 | \begin_inset Quotes gld | ||
932 | \end_inset | ||
933 | |||
934 | AND | ||
935 | \begin_inset Quotes grd | ||
936 | \end_inset | ||
937 | |||
938 | operation), the unused ones are simply ignored. | ||
930 | As we just want to search for entries which zip number starts with a | 939 | As we just want to search for entries which zip number starts with a |
@@ -945,3 +954,3 @@ OPimContact | |||
945 | 954 | ||
946 | as we would do for finding files in a filesystem. | 955 | as we would do to find files in a filesystem. |
947 | \layout Standard | 956 | \layout Standard |
@@ -1021,3 +1030,3 @@ eIlers | |||
1021 | , ...). | 1030 | , ...). |
1022 | Thus we have to use the | 1031 | Thus, we have to use the |
1023 | \begin_inset Quotes gld | 1032 | \begin_inset Quotes gld |
@@ -1059,3 +1068,3 @@ IgnoreCase ); | |||
1059 | 1068 | ||
1060 | This operation may return a list of entries which can be accesses as usual, | 1069 | This operation may return a list of entries which can be accessed as above, |
1061 | using the | 1070 | using the |
@@ -1175,2 +1184,191 @@ end | |||
1175 | Therefore, it is possible to set a time frame for all searched entries. | 1184 | Therefore, it is possible to set a time frame for all searched entries. |
1185 | \layout Standard | ||
1186 | |||
1187 | If you want to do incremental search operations, you may use the special | ||
1188 | |||
1189 | \begin_inset Quotes gld | ||
1190 | \end_inset | ||
1191 | |||
1192 | queryByExample() | ||
1193 | \begin_inset Quotes grd | ||
1194 | \end_inset | ||
1195 | |||
1196 | which takes a | ||
1197 | \begin_inset Quotes gld | ||
1198 | \end_inset | ||
1199 | |||
1200 | List | ||
1201 | \begin_inset Quotes grd | ||
1202 | \end_inset | ||
1203 | |||
1204 | as the first parameter. | ||
1205 | The search operation will just occure on this set of uid's! | ||
1206 | \layout Subsection | ||
1207 | |||
1208 | Sorting | ||
1209 | \layout Standard | ||
1210 | |||
1211 | To sort a given dataset, you should use the following operation (or one | ||
1212 | of the others which behave slightly differently): | ||
1213 | \layout LyX-Code | ||
1214 | |||
1215 | List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, | ||
1216 | const QArray< UID >& cats); | ||
1217 | \layout Standard | ||
1218 | |||
1219 | This sort operation takes a list of uid's as returned for instance from | ||
1220 | a search query. | ||
1221 | The parameter | ||
1222 | \begin_inset Quotes gld | ||
1223 | \end_inset | ||
1224 | |||
1225 | ascending | ||
1226 | \begin_inset Quotes grd | ||
1227 | \end_inset | ||
1228 | |||
1229 | defines whether the sort should be in an ascending order or not. | ||
1230 | |||
1231 | \begin_inset Quotes gld | ||
1232 | \end_inset | ||
1233 | |||
1234 | sortOrder | ||
1235 | \begin_inset Quotes grd | ||
1236 | \end_inset | ||
1237 | |||
1238 | is defined by the enumerations | ||
1239 | \begin_inset Quotes gld | ||
1240 | \end_inset | ||
1241 | |||
1242 | SortOrder | ||
1243 | \begin_inset Quotes grd | ||
1244 | \end_inset | ||
1245 | |||
1246 | and | ||
1247 | \begin_inset Quotes gld | ||
1248 | \end_inset | ||
1249 | |||
1250 | SortOrderBase | ||
1251 | \begin_inset Quotes grd | ||
1252 | \end_inset | ||
1253 | |||
1254 | and defines which field should be used to sort (see for | ||
1255 | \series bold | ||
1256 | OPimContactAccess | ||
1257 | \series default | ||
1258 | : | ||
1259 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html} | ||
1260 | |||
1261 | \end_inset | ||
1262 | |||
1263 | , for | ||
1264 | \series bold | ||
1265 | ODateBookAccess | ||
1266 | \series default | ||
1267 | : | ||
1268 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html} | ||
1269 | |||
1270 | \end_inset | ||
1271 | |||
1272 | and for | ||
1273 | \series bold | ||
1274 | OPimTodoAccess | ||
1275 | \series default | ||
1276 | : | ||
1277 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html} | ||
1278 | |||
1279 | \end_inset | ||
1280 | |||
1281 | and for common settings | ||
1282 | \begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21} | ||
1283 | |||
1284 | \end_inset | ||
1285 | |||
1286 | ). | ||
1287 | \layout Standard | ||
1288 | |||
1289 | The | ||
1290 | \begin_inset Quotes gld | ||
1291 | \end_inset | ||
1292 | |||
1293 | sortFilter | ||
1294 | \begin_inset Quotes grd | ||
1295 | \end_inset | ||
1296 | |||
1297 | parameter allows to remove some entries which are not interesting for the | ||
1298 | result and is defined in the same classes as | ||
1299 | \begin_inset Quotes gld | ||
1300 | \end_inset | ||
1301 | |||
1302 | sortOrder | ||
1303 | \begin_inset Quotes grd | ||
1304 | \end_inset | ||
1305 | |||
1306 | by the enumeration | ||
1307 | \begin_inset Quotes gld | ||
1308 | \end_inset | ||
1309 | |||
1310 | SortFilter | ||
1311 | \begin_inset Quotes grd | ||
1312 | \end_inset | ||
1313 | |||
1314 | and | ||
1315 | \begin_inset Quotes gld | ||
1316 | \end_inset | ||
1317 | |||
1318 | SortFilterBase | ||
1319 | \begin_inset Quotes grd | ||
1320 | \end_inset | ||
1321 | |||
1322 | . | ||
1323 | The list of id's in | ||
1324 | \begin_inset Quotes gld | ||
1325 | \end_inset | ||
1326 | |||
1327 | cats | ||
1328 | \begin_inset Quotes grd | ||
1329 | \end_inset | ||
1330 | |||
1331 | allows to remain just these entries which are included in the list of categorie | ||
1332 | s. | ||
1333 | \layout Standard | ||
1334 | |||
1335 | The returned list contains the same uid's as given via | ||
1336 | \begin_inset Quotes gld | ||
1337 | \end_inset | ||
1338 | |||
1339 | list | ||
1340 | \begin_inset Quotes grd | ||
1341 | \end_inset | ||
1342 | |||
1343 | (or a subset of it, as the sortFilter and category list removes some entries) | ||
1344 | with a modified order as | ||
1345 | \begin_inset Quotes gld | ||
1346 | \end_inset | ||
1347 | |||
1348 | sortOrder | ||
1349 | \begin_inset Quotes grd | ||
1350 | \end_inset | ||
1351 | |||
1352 | and | ||
1353 | \begin_inset Quotes gld | ||
1354 | \end_inset | ||
1355 | |||
1356 | ascending | ||
1357 | \begin_inset Quotes grd | ||
1358 | \end_inset | ||
1359 | |||
1360 | dictates. | ||
1361 | \layout Standard | ||
1362 | |||
1363 | Therefore | ||
1364 | \begin_inset Quotes gld | ||
1365 | \end_inset | ||
1366 | |||
1367 | sorted() | ||
1368 | \begin_inset Quotes grd | ||
1369 | \end_inset | ||
1370 | |||
1371 | is more a combination of search and sort, as just a sort command. | ||
1372 | But this combination is exactly what the developer needs in most situations. | ||
1373 | |||
1176 | \layout Section | 1374 | \layout Section |