summaryrefslogtreecommitdiff
authoreilers <eilers>2005-01-04 14:22:12 (UTC)
committer eilers <eilers>2005-01-04 14:22:12 (UTC)
commita63d6d1896bcb6f1ac3b041e3d46edf0ec9e8082 (patch) (unidiff)
treec5125a96d16685cb49eecb479e761e6b3e9375b3
parentff93c49af890b2b03f729a848be36b77a6e2454b (diff)
downloadopie-a63d6d1896bcb6f1ac3b041e3d46edf0ec9e8082.zip
opie-a63d6d1896bcb6f1ac3b041e3d46edf0ec9e8082.tar.gz
opie-a63d6d1896bcb6f1ac3b041e3d46edf0ec9e8082.tar.bz2
Add section for sorting
Diffstat (more/less context) (show whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx238
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
@@ -107,10 +107,10 @@ The Opie-Pim API provides a powerfull access interface to the PIM (Personal
107 107
108While starting to read the automatically generated API-documentation, the 108While 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
115 115
116 116
@@ -125,7 +125,7 @@ Introduction
125\layout Standard 125\layout Standard
126 126
127Before starting to jump into the work, we should introduce some specialities 127Before 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
130ings: 130ings:
131\layout Enumerate 131\layout Enumerate
@@ -133,7 +133,7 @@ ings:
133The PIM-API heavily uses C++ templates (as known as generic classes), but 133The 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 134 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. 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
138 through. 138 through.
139 But it is a good idea to read some short introduction of templates to avoid 139 But it is a good idea to read some short introduction of templates to avoid
@@ -151,7 +151,7 @@ backend.
151\emph default 151\emph default
152 While the frontend provides the API for the user, the backend implements 152 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. 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
156\begin_inset Quotes gld 156\begin_inset Quotes gld
157\end_inset 157\end_inset
@@ -324,7 +324,7 @@ delete
324delete sourceDB; 324delete sourceDB;
325\layout Section 325\layout Section
326 326
327Accessing the access-object 327Accessing the Access-Object
328\begin_inset LatexCommand \label{sec:Accessing-the-access-object} 328\begin_inset LatexCommand \label{sec:Accessing-the-access-object}
329 329
330\end_inset 330\end_inset
@@ -423,8 +423,8 @@ bool remove (const T& t);
423bool replace (const T& t); 423bool replace (const T& t);
424\layout Standard 424\layout Standard
425 425
426After receiving an access-object, we have to load the existing dataset, 426After 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
429\end_inset 429\end_inset
430 430
@@ -499,7 +499,7 @@ OPimRecordList
499List allRecords (); 499List allRecords ();
500\layout Standard 500\layout Standard
501 501
502In fact this 502In fact, this
503\emph on 503\emph on
504List 504List
505\emph default 505\emph default
@@ -583,7 +583,7 @@ defaultAccess()
583 583
584 to request an access-object to the dafault backend. 584 to request an access-object to the dafault backend.
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
588\end_inset 588\end_inset
589 589
@@ -615,8 +615,8 @@ defaultAccess()
615 615
616\layout Standard 616\layout Standard
617 617
618If the developer wants to select a special database type for sure, he has 618If 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
621create() 621create()
622\emph default 622\emph default
@@ -759,7 +759,7 @@ FIXME: matchRegexp() does take a list of uid's.
759\end_inset 759\end_inset
760 760
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
764\end_inset 764\end_inset
765 765
@@ -918,7 +918,7 @@ searchQuery.setHomeZip(
918 ); 918 );
919\layout Standard 919\layout Standard
920 920
921We use a usual 921We use an usual
922\begin_inset Quotes gld 922\begin_inset Quotes gld
923\end_inset 923\end_inset
924 924
@@ -926,7 +926,16 @@ OPimContact
926\begin_inset Quotes grd 926\begin_inset Quotes grd
927\end_inset 927\end_inset
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
934AND
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
931\begin_inset Quotes gld 940\begin_inset Quotes gld
932\end_inset 941\end_inset
@@ -943,7 +952,7 @@ OPimContact
943\begin_inset Quotes grd 952\begin_inset Quotes grd
944\end_inset 953\end_inset
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
948 957
949The next step is to put this query into the operation which is defined like 958The next step is to put this query into the operation which is defined like
@@ -1019,7 +1028,7 @@ eIlers
1019\end_inset 1028\end_inset
1020 1029
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
1024\end_inset 1033\end_inset
1025 1034
@@ -1057,7 +1066,7 @@ List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
1057IgnoreCase ); 1066IgnoreCase );
1058\layout Standard 1067\layout Standard
1059 1068
1060This operation may return a list of entries which can be accesses as usual, 1069This operation may return a list of entries which can be accessed as above,
1061 using the 1070 using the
1062\begin_inset Quotes gld 1071\begin_inset Quotes gld
1063\end_inset 1072\end_inset
@@ -1173,6 +1182,195 @@ end
1173 The start will be defined by the last parameter (if nothing is set, the 1182 The start will be defined by the last parameter (if nothing is set, the
1174 current date will be taken!). 1183 current date will be taken!).
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
1187If you want to do incremental search operations, you may use the special
1188
1189\begin_inset Quotes gld
1190\end_inset
1191
1192queryByExample()
1193\begin_inset Quotes grd
1194\end_inset
1195
1196 which takes a
1197\begin_inset Quotes gld
1198\end_inset
1199
1200List
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
1208Sorting
1209\layout Standard
1210
1211To 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
1215List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
1216 const QArray< UID >& cats);
1217\layout Standard
1218
1219This 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
1225ascending
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
1234sortOrder
1235\begin_inset Quotes grd
1236\end_inset
1237
1238 is defined by the enumerations
1239\begin_inset Quotes gld
1240\end_inset
1241
1242SortOrder
1243\begin_inset Quotes grd
1244\end_inset
1245
1246 and
1247\begin_inset Quotes gld
1248\end_inset
1249
1250SortOrderBase
1251\begin_inset Quotes grd
1252\end_inset
1253
1254 and defines which field should be used to sort (see for
1255\series bold
1256OPimContactAccess
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
1265ODateBookAccess
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
1274OPimTodoAccess
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
1289The
1290\begin_inset Quotes gld
1291\end_inset
1292
1293sortFilter
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
1302sortOrder
1303\begin_inset Quotes grd
1304\end_inset
1305
1306 by the enumeration
1307\begin_inset Quotes gld
1308\end_inset
1309
1310SortFilter
1311\begin_inset Quotes grd
1312\end_inset
1313
1314 and
1315\begin_inset Quotes gld
1316\end_inset
1317
1318SortFilterBase
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
1327cats
1328\begin_inset Quotes grd
1329\end_inset
1330
1331 allows to remain just these entries which are included in the list of categorie
1332s.
1333\layout Standard
1334
1335The returned list contains the same uid's as given via
1336\begin_inset Quotes gld
1337\end_inset
1338
1339list
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
1348sortOrder
1349\begin_inset Quotes grd
1350\end_inset
1351
1352 and
1353\begin_inset Quotes gld
1354\end_inset
1355
1356ascending
1357\begin_inset Quotes grd
1358\end_inset
1359
1360 dictates.
1361\layout Standard
1362
1363Therefore
1364\begin_inset Quotes gld
1365\end_inset
1366
1367sorted()
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
1177 1375
1178Generic Access: OPimBase and OPimRecord 1376Generic Access: OPimBase and OPimRecord