| -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 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 |