summaryrefslogtreecommitdiff
path: root/development
Side-by-side diff
Diffstat (limited to 'development') (more/less context) (ignore 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
@@ -109,6 +109,6 @@ While starting to read the automatically generated API-documentation, the
user may be confused by a lot of unneccessary classes and details which
- makes the quick start not as easy as expected.
- Due to the fact that a user who just want to access data will not need
- most of the details, this paper should help to start to be confortable
- with the details he need to solve his problems.
+ makes the quick start not as easy as possible.
+ Due to the fact that a user will not need most of the details, this paper
+ should help to start to become confortable with those details he need to
+ solve his problems.
\layout Standard
@@ -127,3 +127,3 @@ Introduction
Before starting to jump into the work, we should introduce some specialities
- of the PIM API first.
+ of the PIM API, first.
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
they work! Most of the API works without even seeing the templates.
- In some cases whe have to use them (for instance to use the factory classes)
+ In some cases whe have to use them (for instance to use the factory classes),
but this guide will provide examples which should help to find the path
@@ -153,3 +153,3 @@ backend.
how to access the databases and what to do with the data.
- This paper just focusses the frontend as we just want to access data.
+ As we just want to access data, this paper just focusses the frontend.
Thus, you should ignore all classes which contains something like
@@ -326,3 +326,3 @@ delete sourceDB;
-Accessing the access-object
+Accessing the Access-Object
\begin_inset LatexCommand \label{sec:Accessing-the-access-object}
@@ -425,4 +425,4 @@ bool replace (const T& t);
-After receiving an access-object, we have to load the existing dataset,
- which is done by the
+After receiving an access-object, we have to load the existing dataset into
+ the backend, which is done by the
\begin_inset Quotes gld
@@ -501,3 +501,3 @@ List allRecords ();
-In fact this
+In fact, this
\emph on
@@ -585,3 +585,3 @@ defaultAccess()
Whether this default backend will access the XML, VCard or SQLite database
- type, this is defined by the configuration file
+ type, is defined by the configuration file
\begin_inset Quotes gld
@@ -617,4 +617,4 @@ defaultAccess()
-If the developer wants to select a special database type for sure, he has
- to use the oparation
+If the developer wants to select a special database type for sure without
+ unnecessary side effects, he has to use the oparation
\emph on
@@ -761,3 +761,3 @@ FIXME: matchRegexp() does take a list of uid's.
.
- Therfore it is possible to research a
+ Therefore it is possible to research a
\begin_inset Quotes gld
@@ -920,3 +920,3 @@ searchQuery.setHomeZip(
-We use a usual
+We use an usual
\begin_inset Quotes gld
@@ -928,3 +928,12 @@ OPimContact
- and fill into two fields the search information.
+ and fill into two fields the query information.
+ All filled fields are taken for the search operation (using an
+\begin_inset Quotes gld
+\end_inset
+
+AND
+\begin_inset Quotes grd
+\end_inset
+
+ operation), the unused ones are simply ignored.
As we just want to search for entries which zip number starts with a
@@ -945,3 +954,3 @@ OPimContact
- as we would do for finding files in a filesystem.
+ as we would do to find files in a filesystem.
\layout Standard
@@ -1021,3 +1030,3 @@ eIlers
, ...).
- Thus we have to use the
+ Thus, we have to use the
\begin_inset Quotes gld
@@ -1059,3 +1068,3 @@ IgnoreCase );
-This operation may return a list of entries which can be accesses as usual,
+This operation may return a list of entries which can be accessed as above,
using the
@@ -1175,2 +1184,191 @@ end
Therefore, it is possible to set a time frame for all searched entries.
+\layout Standard
+
+If you want to do incremental search operations, you may use the special
+
+\begin_inset Quotes gld
+\end_inset
+
+queryByExample()
+\begin_inset Quotes grd
+\end_inset
+
+ which takes a
+\begin_inset Quotes gld
+\end_inset
+
+List
+\begin_inset Quotes grd
+\end_inset
+
+ as the first parameter.
+ The search operation will just occure on this set of uid's!
+\layout Subsection
+
+Sorting
+\layout Standard
+
+To sort a given dataset, you should use the following operation (or one
+ of the others which behave slightly differently):
+\layout LyX-Code
+
+List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
+ const QArray< UID >& cats);
+\layout Standard
+
+This sort operation takes a list of uid's as returned for instance from
+ a search query.
+ The parameter
+\begin_inset Quotes gld
+\end_inset
+
+ascending
+\begin_inset Quotes grd
+\end_inset
+
+ defines whether the sort should be in an ascending order or not.
+
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ is defined by the enumerations
+\begin_inset Quotes gld
+\end_inset
+
+SortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+SortOrderBase
+\begin_inset Quotes grd
+\end_inset
+
+ and defines which field should be used to sort (see for
+\series bold
+OPimContactAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html}
+
+\end_inset
+
+, for
+\series bold
+ODateBookAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html}
+
+\end_inset
+
+ and for
+\series bold
+OPimTodoAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html}
+
+\end_inset
+
+ and for common settings
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21}
+
+\end_inset
+
+).
+\layout Standard
+
+The
+\begin_inset Quotes gld
+\end_inset
+
+sortFilter
+\begin_inset Quotes grd
+\end_inset
+
+ parameter allows to remove some entries which are not interesting for the
+ result and is defined in the same classes as
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ by the enumeration
+\begin_inset Quotes gld
+\end_inset
+
+SortFilter
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+SortFilterBase
+\begin_inset Quotes grd
+\end_inset
+
+.
+ The list of id's in
+\begin_inset Quotes gld
+\end_inset
+
+cats
+\begin_inset Quotes grd
+\end_inset
+
+ allows to remain just these entries which are included in the list of categorie
+s.
+\layout Standard
+
+The returned list contains the same uid's as given via
+\begin_inset Quotes gld
+\end_inset
+
+list
+\begin_inset Quotes grd
+\end_inset
+
+ (or a subset of it, as the sortFilter and category list removes some entries)
+ with a modified order as
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+ascending
+\begin_inset Quotes grd
+\end_inset
+
+ dictates.
+\layout Standard
+
+Therefore
+\begin_inset Quotes gld
+\end_inset
+
+sorted()
+\begin_inset Quotes grd
+\end_inset
+
+ is more a combination of search and sort, as just a sort command.
+ But this combination is exactly what the developer needs in most situations.
+
\layout Section