3 files changed, 109 insertions, 38 deletions

diff --git a/libopie2/opiepim/core/ocontactaccess.h b/libopie2/opiepim/core/ocontactaccess.h
index 691ece2..bd85b4e 100644
--- a/libopie2/opiepim/core/ocontactaccess.h
+++ b/libopie2/opiepim/core/ocontactaccess.h
@@ -57,27 +57,44 @@ namespace Opie {
  */
 class OPimContactAccess: public QObject, public OPimAccessTemplate<OPimContact>
 {
     Q_OBJECT
 
  public:
+    /**
+     * Filter for sorted()
+     * @see SortFilterBase in OPimBase
+     */
     enum SortFilter {
-        DoNotShowNoneChildren      = FilterCustom<<1,
-        DoNotShowNoneAnniversary   = FilterCustom<<2,
-        DoNotShowNoneBirthday      = FilterCustom<<3,
-        DoNotShowNoHomeAddress     = FilterCustom<<4,
-        DoNotShowNoBusinessAddress = FilterCustom<<5
+        /** Don't return entries who don't have children */
+        DoNotShowWithoutChildren        = FilterCustom<<1,
+        /** Don't return entries who don't have an anniversary */
+        DoNotShowWithoutAnniversary     = FilterCustom<<2,
+         /** Don't return entries who don't have a birthday */
+        DoNotShowWithoutBirthday        = FilterCustom<<3,
+         /** Don't return entries who don't have a home address */
+        DoNotShowWithoutHomeAddress     = FilterCustom<<4,
+        /** Don't return entries who don't have a business address */
+        DoNotShowWithoutBusinessAddress = FilterCustom<<5,
+        /** Don't return entries which hava any category */
+        DoNotShowWithCategory = FilterCustom << 6
     };
 
+    /**
+     * Sort order for sorted()
+     * @see SortOrderBase in OPimBase
+     */
     enum SortOrder {
         SortTitle = SortCustom,
         SortFirstName,
         SortMiddleName,
+        SortLastName,
         SortSuffix,
         SortEmail,
         SortNickname,
+        SortFileAsName,
         SortAnniversary,
         SortBirthday,
         SortGender
     };
 
         /**
@@ -96,20 +113,24 @@ class OPimContactAccess: public QObject, public OPimAccessTemplate<OPimContact>
          */
         OPimContactAccess (const QString appname, const QString filename = 0l,
                            OPimContactAccessBackend* backend = 0l, bool handlesync = true);
         ~OPimContactAccess ();
 
 
-        /** Return all possible settings.
+        /** 
+         * Return all possible settings for queryByExample().
          *  @return All settings provided by the current backend
-         * (i.e.: query_WildCards & query_IgnoreCase)
+         * (i.e.: WildCards & IgnoreCase)
+         * @see QuerySettings in OPimBase for details of the parameter
          */
         const uint querySettings();
 
-        /** Check whether settings are correct.
+        /** 
+         * Check whether settings are correct for queryByExample().
          * @return <i>true</i> if the given settings are correct and possible.
+         * @see QuerySettings in OPimBase for details of the parameter
          */
         bool hasQuerySettings ( int querySettings ) const;
 
         /**
          * if the resource was changed externally.
          * You should use the signal instead of polling possible changes !
diff --git a/libopie2/opiepim/core/opimaccesstemplate.h b/libopie2/opiepim/core/opimaccesstemplate.h
index 2deb92a..073d5f9 100644
--- a/libopie2/opiepim/core/opimaccesstemplate.h
+++ b/libopie2/opiepim/core/opimaccesstemplate.h
@@ -87,21 +87,58 @@ public:
     virtual List allRecords()const;
     virtual List matchRegexp(  const QRegExp &r ) const;
     virtual List queryByExample( const T& t, int querySettings, const QDateTime& d = QDateTime() );
     virtual T find( UID uid )const;
     virtual T find( UID uid, const QArray<int>&,
                     uint current, typename OTemplateBase<T>::CacheDirection dir = OTemplateBase<T>::Forward )const;
-    virtual List sorted( const List&, bool ascending, int sortOrder,
+    //@}
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param list of UID's received by allRecords() or others...
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cat number of category.
+     */
+    virtual List sorted( const List& list, bool ascending, int sortOrder,
                          int sortFilter, int cat )const;
-    virtual List sorted( const List&, bool ascending, int sortOrder,
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param list of UID's received by allRecords() or others...
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cats List of categories.
+     */
+    virtual List sorted( const List& list, bool ascending, int sortOrder,
                          int sortFilter, const QArray<UID>& cats )const;
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cat number of category.
+     */
     virtual List sorted( bool ascending, int sortOrder, int sortFilter, int cat )const;
-    virtual List sorted( bool ascending, int sortOrder, int sortOrder,
-                         const QArray<UID>& cats )const;
-    //@}
 
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cats List of categories.
+     */
+    virtual List sorted( bool ascending, int sortOrder, int sortFilter,
+                         const QArray<UID>& cats )const;
     /**
      * (Re)Implementation
      */
     //@{
     UIDArray matchRegexpSimple( const QRegExp& r )const;
     UIDArray queryByExampleSimple( const OPimRecord*, int, const QDateTime& )const;
@@ -126,13 +163,12 @@ public:
     bool remove( const OPimRecord& );
     virtual bool replace( const T& t) ;
 
     //@}
 
     void setReadAhead( uint count );
-    virtual T cacheFind( int uid )const;
     void cache( const T& )const;
     void setSaneCacheSize( int );
 
     QArray<UID> records()const;
 protected:
     /**
@@ -255,17 +291,12 @@ T OPimAccessTemplate<T>::find( UID uid ) const{
     T t = m_backEnd->find( uid );
     cache( t );
 
     return t;
 }
 
-template <class T>
-T OPimAccessTemplate<T>::cacheFind( int uid ) const
-{
-        return m_cache.find( uid );
-}
 
 /**
  * read ahead cache find method ;)
  */
 template <class T>
 T OPimAccessTemplate<T>::find( UID uid, const QArray<int>& ar,
diff --git a/libopie2/opiepim/core/opimtemplatebase.h b/libopie2/opiepim/core/opimtemplatebase.h
index b238a68..c8abab4 100644
--- a/libopie2/opiepim/core/opimtemplatebase.h
+++ b/libopie2/opiepim/core/opimtemplatebase.h
@@ -77,53 +77,72 @@ struct OPimBase {
     virtual bool load() = 0;
     virtual bool save() = 0;
     //@}
 
     //@{
     virtual QArray<UID> records()const = 0;
+    //@}
 
     /** Constants for query.
      * Use this constants to set the query parameters.
      * Note: <i>query_IgnoreCase</i> just make sense with one of the other attributes !
      * @see queryByExample()
      */
     enum QuerySettings {
-        WildCards  = 0x0001, /** Use Wildcards */
-        IgnoreCase = 0x0002, /** Ignore the Case  */
-        RegExp     = 0x0004, /** Do a Regular Expression match */
-        ExactMatch = 0x0008, /** It needs to exactly match     */
-        MatchOne   = 0x0010, /** Only one Entry must match */
-        DateDiff   = 0x0020, /** Find all entries from today until given date */
-        DateYear   = 0x0040, /** The year matches */
-        DateMonth  = 0x0080, /** The month matches */
-        DateDay    = 0x0100, /** The day matches */
-        LastItem   = 0xffff  /** the last possible name */
+        /** Use Wildcards */
+        WildCards  = 0x0001,
+        /** Ignore the Case  */
+        IgnoreCase = 0x0002,
+        /** Do a Regular Expression match */
+        RegExp     = 0x0004, 
+        /** It needs to exactly match     */
+        ExactMatch = 0x0008, 
+        /** Only one Entry must match */
+        MatchOne   = 0x0010, 
+        /** Find all entries from today until given date */
+        DateDiff   = 0x0020, 
+        /** The year matches */
+        DateYear   = 0x0040, 
+        /** The month matches */
+        DateMonth  = 0x0080, 
+        /** The day matches */
+        DateDay    = 0x0100, 
+        /** The last possible name matches */
+        LastItem   = 0xffff  
     };
 
     /**
      * Common Attributes for the Sort Order
      */
     enum SortOrderBase {
-        SortSummary = 0,       /** Sort by a Summary of the records */
-        SortByCategory = 1,    /** Sort by Category */
-        SortByDate = 2,        /** Sort by Date */
-        SortCustom  = 10,      /** The First available sort number for the OPimAccessTemplates */
-        LastSortOrderBase = 0xffff /** make this enum 16bit large */
+        /** Sort by a Summary of the records */
+        SortSummary = 0,
+        /** Sort by Category */
+        SortByCategory = 1,
+        /** Sort by Date */
+        SortByDate = 2, 
+        /** The First available sort number for the OPimAccessTemplates */
+        SortCustom  = 10,
+        /** make this enum 16bit large */
+        LastSortOrderBase = 0xffff 
     };
 
     /**
-     * Sort with the help of the \sa sorted function
-     * a list of Items.
+     * Sort a list of Items with the help of the sorted() function.
      * The Item you provide in SortOrder will be used
      * for sorting.
      *
-     * @see sorted
+     * @see OPimAccessTemplate<>::sorted()
      */
     enum SortFilterBase {
+            /** Do not filter anything. */
+        FilterOff = 0,
+        /** Use given Categories for filter */
         FilterCategory = 1,
-        FilterCustom = 1024,
+        /** The first available custom filter defined in the specialized frontends */
+        FilterCustom = 1024, 
         LastSortFilterBase = 0xffffffff
     };
 
     virtual UIDArray matchRegexpSimple( const QRegExp& r )const = 0;
     virtual UIDArray queryByExampleSimple( const OPimRecord*, int settings,
                                            const QDateTime& d = QDateTime() )const  = 0;