summaryrefslogtreecommitdiff
authorzecke <zecke>2002-09-22 19:25:33 (UTC)
committer zecke <zecke>2002-09-22 19:25:33 (UTC)
commit3f194c85b5b9243ff30f1067361ef9fa5bb85a1e (patch) (side-by-side diff)
tree909eae5d629918d579424a8ca644d6795b43faaf
parent4904161b6b043e1397db4affd7930fd999ff742e (diff)
downloadopie-3f194c85b5b9243ff30f1067361ef9fa5bb85a1e.zip
opie-3f194c85b5b9243ff30f1067361ef9fa5bb85a1e.tar.gz
opie-3f194c85b5b9243ff30f1067361ef9fa5bb85a1e.tar.bz2
Some documentation
and addition to OTodoAccess overDue and effectiveTodos
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--libopie/pim/opimaccessbackend.h53
-rw-r--r--libopie/pim/opimaccesstemplate.h81
-rw-r--r--libopie/pim/opimrecord.h19
-rw-r--r--libopie/pim/orecordlist.h40
-rw-r--r--libopie/pim/otemplatebase.h3
-rw-r--r--libopie2/opiepim/backend/opimaccessbackend.h53
-rw-r--r--libopie2/opiepim/core/opimaccesstemplate.h81
-rw-r--r--libopie2/opiepim/core/opimrecord.h19
-rw-r--r--libopie2/opiepim/core/otemplatebase.h3
-rw-r--r--libopie2/opiepim/orecordlist.h40
10 files changed, 374 insertions, 18 deletions
diff --git a/libopie/pim/opimaccessbackend.h b/libopie/pim/opimaccessbackend.h
index 8e744e7..5707b58 100644
--- a/libopie/pim/opimaccessbackend.h
+++ b/libopie/pim/opimaccessbackend.h
@@ -1,33 +1,86 @@
#ifndef OPIE_PIM_ACCESS_BACKEND
#define OPIE_PIM_ACCESS_BACKEND
#include <qarray.h>
#include <opie/opimrecord.h>
+
+/**
+ * OPimAccessBackend is the base class
+ * for all private backends
+ * it operates on OPimRecord as the base class
+ * and it's responsible for fast manipulating
+ * the resource the implementation takes care
+ * of
+ */
template <class T = OPimRecord>
class OPimAccessBackend {
public:
OPimAccessBackend();
virtual ~OPimAccessBackend();
+
+ /**
+ * load the resource
+ */
virtual void load() = 0;
+
+ /**
+ * reload the resource
+ */
virtual void reload() = 0;
+
+ /**
+ * save the resource and
+ * all it's changes
+ */
virtual void save() = 0;
+
+ /**
+ * return an array of
+ * all available uids
+ */
virtual QArray<int> allRecords()const = 0;
+
+ /**
+ * queryByExample for T with the SortOrder
+ * sort
+ */
virtual QArray<int> queryByExample( const T& t, int sort ) = 0;
+
+ /**
+ * find the OPimRecord with uid @param uid
+ * returns T and T.isEmpty() if nothing was found
+ */
virtual T find(int uid ) = 0;
+
+ /**
+ * clear the back end
+ */
virtual void clear() = 0;
+
+ /**
+ * add T
+ */
virtual bool add( const T& t ) = 0;
+
+ /**
+ * remove
+ */
virtual bool remove( int uid ) = 0;
+
+ /**
+ * replace a record with T.uid()
+ */
virtual bool replace( const T& t ) = 0;
};
template <class T>
OPimAccessBackend<T>::OPimAccessBackend() {
}
template <class T>
OPimAccessBackend<T>::~OPimAccessBackend() {
diff --git a/libopie/pim/opimaccesstemplate.h b/libopie/pim/opimaccesstemplate.h
index e0708e1..36f5a99 100644
--- a/libopie/pim/opimaccesstemplate.h
+++ b/libopie/pim/opimaccesstemplate.h
@@ -1,52 +1,122 @@
#ifndef OPIE_PIM_ACCESS_TEMPLATE_H
#define OPIE_PIM_ACCESS_TEMPLATE_H
#include <qarray.h>
#include <opie/opimrecord.h>
#include <opie/opimaccessbackend.h>
#include <opie/orecordlist.h>
#include "otemplatebase.h"
+/**
+ * Thats the frontend to our OPIE PIM
+ * Library. Either you want to use it's
+ * interface or you want to implement
+ * your own Access lib
+ * Just create a OPimRecord and inherit from
+ * the plugins
+ */
+
template <class T = OPimRecord >
class OPimAccessTemplate : public OTemplateBase<T> {
public:
typedef ORecordList<T> List;
typedef OPimAccessBackend<T> BackEnd;
+
+ /**
+ * our sort order
+ * should be safe explaining
+ */
+ enum SortOrder { WildCards = 0, IgnoreCase = 1,
+ RegExp = 2, ExactMatch = 4 };
+
+ /**
+ * c'tor BackEnd
+ */
OPimAccessTemplate( BackEnd* end);
virtual ~OPimAccessTemplate();
+
+ /**
+ * load from the backend
+ */
virtual void load();
+
+ /**
+ * reload from the backend
+ */
virtual void reload();
+
+ /**
+ * save to the backend
+ */
virtual void save();
- /*
- *do array to Records conversion
- * QArray<int> ids
+ /**
+ * if the resource was changed externally
+ */
+ bool wasChangedExternally()const;
+
+ /**
+ * return a List of records
+ * you can iterate over them
*/
virtual List allRecords()const;
+
+ /**
+ * queryByExample
+ */
virtual List queryByExample( const T& t, int sortOrder );
+
+ /**
+ * find the OPimRecord uid
+ */
virtual T find( int uid );
/* invalidate cache here */
+ /**
+ * clears the backend and invalidates the backend
+ */
virtual void clear() ;
+
+ /**
+ * add T to the backend
+ */
virtual bool add( const T& t ) ;
/* only the uid matters */
+ /**
+ * remove T from the backend
+ */
virtual bool remove( const T& t );
+
+ /**
+ * remove the OPimRecord with uid
+ */
virtual bool remove( int uid );
+
+ /**
+ * replace T from backend
+ */
virtual bool replace( const T& t) ;
protected:
+ /**
+ * invalidate the cache
+ */
void invalidateCache();
+
+ /**
+ * returns the backend
+ */
BackEnd* backEnd();
BackEnd* m_backEnd;
};
template <class T>
OPimAccessTemplate<T>::OPimAccessTemplate( BackEnd* end )
: OTemplateBase<T>(), m_backEnd( end )
{
}
template <class T>
@@ -105,14 +175,17 @@ bool OPimAccessTemplate<T>::remove( int uid ) {
template <class T>
bool OPimAccessTemplate<T>::replace( const T& t ) {
return m_backEnd->replace( t );
}
template <class T>
void OPimAccessTemplate<T>::invalidateCache() {
}
template <class T>
OPimAccessTemplate<T>::BackEnd* OPimAccessTemplate<T>::backEnd() {
return m_backEnd;
}
-
+template <class T>
+bool OPimAccessTemplate<T>::wasChangedExternally()const {
+ return false;
+}
#endif
diff --git a/libopie/pim/opimrecord.h b/libopie/pim/opimrecord.h
index e4d33d6..dbb94ed 100644
--- a/libopie/pim/opimrecord.h
+++ b/libopie/pim/opimrecord.h
@@ -1,24 +1,31 @@
#ifndef OPIE_PIM_RECORD_H
#define OPIE_PIM_RECORD_H
#include <qmap.h>
#include <qstring.h>
#include <qstringlist.h>
#include <qpe/palmtoprecord.h>
+
+/**
+ * This is the base class for
+ * all PIM Records
+ *
+ */
class OPimRecord : public Qtopia::Record {
public:
/**
+ * c'tor
* uid of 0 isEmpty
* uid of 1 will be assigned a new one
*/
OPimRecord(int uid = 0);
~OPimRecord();
/**
* copy c'tor
*/
OPimRecord( const OPimRecord& rec );
/**
@@ -35,24 +42,25 @@ public:
* set category names they will be resolved
*/
void setCategoryNames( const QStringList& );
/**
* addCategoryName adds a name
* to the internal category list
*/
void addCategoryName( const QString& );
/**
* if a Record isEmpty
+ * it's empty if it's 0
*/
virtual bool isEmpty()const;
/**
* toRichText summary
*/
virtual QString toRichText()const = 0;
/**
* a small one line summary
*/
virtual QString toShortText()const = 0;
@@ -79,37 +87,42 @@ public:
/**
* the related apps names
*/
QStringList relatedApps()const;
/**
* the realtions between an app
*/
QArray<int> relations( const QString& app )const;
/**
- *
+ * clear the relations for all relations
+ * with app
*/
void clearRelation( const QString& app );
/**
- *
+ * add a relation
*/
void addRelation( const QString& app, int id );
/**
- *
+ * set the relations for an app
*/
void setRelations( const QString&, QArray<int> ids );
+
+ /**
+ * set the uid
+ */
virtual void setUid( int uid );
protected:
Qtopia::UidGen &uidGen();
QString crossToString()const;
private:
class OPimRecordPrivate;
OPimRecordPrivate *d;
QMap<QString, QArray<int> > m_relations;
static Qtopia::UidGen m_uidGen;
diff --git a/libopie/pim/orecordlist.h b/libopie/pim/orecordlist.h
index a3955b0..3b30a73 100644
--- a/libopie/pim/orecordlist.h
+++ b/libopie/pim/orecordlist.h
@@ -1,59 +1,95 @@
#ifndef OPIE_RECORD_LIST_H
#define OPIE_RECORD_LIST_H
#include <qarray.h>
#include "otemplatebase.h"
#include "opimrecord.h"
-
+/**
+ * Our List Iterator
+ * it behaves like STL or Qt
+ *
+ * for(it = list.begin(); it != list.end(); ++it )
+ * doSomeCoolStuff( (*it) );
+ */
template <class T = OPimRecord>
class ORecordListIterator {
public:
typedef OTemplateBase<T> Base;
+
+ /**
+ * The c'tor used internally from
+ * ORecordList
+ */
ORecordListIterator( const QArray<int>, const Base* );
+
+ /**
+ * The standard c'tor
+ */
ORecordListIterator();
~ORecordListIterator();
+
ORecordListIterator( const ORecordListIterator& );
ORecordListIterator &operator=(const ORecordListIterator& );
+
+ /**
+ * a * operator ;)
+ * use it like this T = (*it);
+ */
T &operator*();
ORecordListIterator &operator++();
ORecordListIterator &operator--();
bool operator==( const ORecordListIterator& it );
bool operator!=( const ORecordListIterator& it );
private:
QArray<int> m_uids;
int m_current;
const Base* m_temp;
bool m_end : 1;
T m_record;
/* d pointer for future versions */
class IteratorPrivate;
IteratorPrivate *d;
};
-
+/**
+ * The recordlist used as a return type
+ * from OPimAccessTemplate
+ */
template <class T = OPimRecord >
class ORecordList {
public:
typedef OTemplateBase<T> Base;
typedef ORecordListIterator<T> Iterator;
+
+ /**
+ * c'tor
+ */
ORecordList( const QArray<int>& ids,
const Base* );
~ORecordList();
+
+ /**
+ * the first iterator
+ */
Iterator begin();
+
+ /**
+ * the end
+ */
Iterator end();
/*
ConstIterator begin()const;
ConstIterator end()const;
*/
private:
QArray<int> m_ids;
const Base* m_acc;
};
/* ok now implement it */
template <class T>
diff --git a/libopie/pim/otemplatebase.h b/libopie/pim/otemplatebase.h
index 41cc934..add1de4 100644
--- a/libopie/pim/otemplatebase.h
+++ b/libopie/pim/otemplatebase.h
@@ -1,17 +1,20 @@
#ifndef OPIE_TEMPLATE_BASE_H
#define OPIE_TEMPLATE_BASE_H
#include "opimrecord.h"
+/**
+ * internal template base
+ */
template <class T = OPimRecord>
class OTemplateBase {
public:
OTemplateBase() {
};
virtual ~OTemplateBase() {
}
virtual T find( int uid ) = 0;
};
diff --git a/libopie2/opiepim/backend/opimaccessbackend.h b/libopie2/opiepim/backend/opimaccessbackend.h
index 8e744e7..5707b58 100644
--- a/libopie2/opiepim/backend/opimaccessbackend.h
+++ b/libopie2/opiepim/backend/opimaccessbackend.h
@@ -1,33 +1,86 @@
#ifndef OPIE_PIM_ACCESS_BACKEND
#define OPIE_PIM_ACCESS_BACKEND
#include <qarray.h>
#include <opie/opimrecord.h>
+
+/**
+ * OPimAccessBackend is the base class
+ * for all private backends
+ * it operates on OPimRecord as the base class
+ * and it's responsible for fast manipulating
+ * the resource the implementation takes care
+ * of
+ */
template <class T = OPimRecord>
class OPimAccessBackend {
public:
OPimAccessBackend();
virtual ~OPimAccessBackend();
+
+ /**
+ * load the resource
+ */
virtual void load() = 0;
+
+ /**
+ * reload the resource
+ */
virtual void reload() = 0;
+
+ /**
+ * save the resource and
+ * all it's changes
+ */
virtual void save() = 0;
+
+ /**
+ * return an array of
+ * all available uids
+ */
virtual QArray<int> allRecords()const = 0;
+
+ /**
+ * queryByExample for T with the SortOrder
+ * sort
+ */
virtual QArray<int> queryByExample( const T& t, int sort ) = 0;
+
+ /**
+ * find the OPimRecord with uid @param uid
+ * returns T and T.isEmpty() if nothing was found
+ */
virtual T find(int uid ) = 0;
+
+ /**
+ * clear the back end
+ */
virtual void clear() = 0;
+
+ /**
+ * add T
+ */
virtual bool add( const T& t ) = 0;
+
+ /**
+ * remove
+ */
virtual bool remove( int uid ) = 0;
+
+ /**
+ * replace a record with T.uid()
+ */
virtual bool replace( const T& t ) = 0;
};
template <class T>
OPimAccessBackend<T>::OPimAccessBackend() {
}
template <class T>
OPimAccessBackend<T>::~OPimAccessBackend() {
diff --git a/libopie2/opiepim/core/opimaccesstemplate.h b/libopie2/opiepim/core/opimaccesstemplate.h
index e0708e1..36f5a99 100644
--- a/libopie2/opiepim/core/opimaccesstemplate.h
+++ b/libopie2/opiepim/core/opimaccesstemplate.h
@@ -1,52 +1,122 @@
#ifndef OPIE_PIM_ACCESS_TEMPLATE_H
#define OPIE_PIM_ACCESS_TEMPLATE_H
#include <qarray.h>
#include <opie/opimrecord.h>
#include <opie/opimaccessbackend.h>
#include <opie/orecordlist.h>
#include "otemplatebase.h"
+/**
+ * Thats the frontend to our OPIE PIM
+ * Library. Either you want to use it's
+ * interface or you want to implement
+ * your own Access lib
+ * Just create a OPimRecord and inherit from
+ * the plugins
+ */
+
template <class T = OPimRecord >
class OPimAccessTemplate : public OTemplateBase<T> {
public:
typedef ORecordList<T> List;
typedef OPimAccessBackend<T> BackEnd;
+
+ /**
+ * our sort order
+ * should be safe explaining
+ */
+ enum SortOrder { WildCards = 0, IgnoreCase = 1,
+ RegExp = 2, ExactMatch = 4 };
+
+ /**
+ * c'tor BackEnd
+ */
OPimAccessTemplate( BackEnd* end);
virtual ~OPimAccessTemplate();
+
+ /**
+ * load from the backend
+ */
virtual void load();
+
+ /**
+ * reload from the backend
+ */
virtual void reload();
+
+ /**
+ * save to the backend
+ */
virtual void save();
- /*
- *do array to Records conversion
- * QArray<int> ids
+ /**
+ * if the resource was changed externally
+ */
+ bool wasChangedExternally()const;
+
+ /**
+ * return a List of records
+ * you can iterate over them
*/
virtual List allRecords()const;
+
+ /**
+ * queryByExample
+ */
virtual List queryByExample( const T& t, int sortOrder );
+
+ /**
+ * find the OPimRecord uid
+ */
virtual T find( int uid );
/* invalidate cache here */
+ /**
+ * clears the backend and invalidates the backend
+ */
virtual void clear() ;
+
+ /**
+ * add T to the backend
+ */
virtual bool add( const T& t ) ;
/* only the uid matters */
+ /**
+ * remove T from the backend
+ */
virtual bool remove( const T& t );
+
+ /**
+ * remove the OPimRecord with uid
+ */
virtual bool remove( int uid );
+
+ /**
+ * replace T from backend
+ */
virtual bool replace( const T& t) ;
protected:
+ /**
+ * invalidate the cache
+ */
void invalidateCache();
+
+ /**
+ * returns the backend
+ */
BackEnd* backEnd();
BackEnd* m_backEnd;
};
template <class T>
OPimAccessTemplate<T>::OPimAccessTemplate( BackEnd* end )
: OTemplateBase<T>(), m_backEnd( end )
{
}
template <class T>
@@ -105,14 +175,17 @@ bool OPimAccessTemplate<T>::remove( int uid ) {
template <class T>
bool OPimAccessTemplate<T>::replace( const T& t ) {
return m_backEnd->replace( t );
}
template <class T>
void OPimAccessTemplate<T>::invalidateCache() {
}
template <class T>
OPimAccessTemplate<T>::BackEnd* OPimAccessTemplate<T>::backEnd() {
return m_backEnd;
}
-
+template <class T>
+bool OPimAccessTemplate<T>::wasChangedExternally()const {
+ return false;
+}
#endif
diff --git a/libopie2/opiepim/core/opimrecord.h b/libopie2/opiepim/core/opimrecord.h
index e4d33d6..dbb94ed 100644
--- a/libopie2/opiepim/core/opimrecord.h
+++ b/libopie2/opiepim/core/opimrecord.h
@@ -1,24 +1,31 @@
#ifndef OPIE_PIM_RECORD_H
#define OPIE_PIM_RECORD_H
#include <qmap.h>
#include <qstring.h>
#include <qstringlist.h>
#include <qpe/palmtoprecord.h>
+
+/**
+ * This is the base class for
+ * all PIM Records
+ *
+ */
class OPimRecord : public Qtopia::Record {
public:
/**
+ * c'tor
* uid of 0 isEmpty
* uid of 1 will be assigned a new one
*/
OPimRecord(int uid = 0);
~OPimRecord();
/**
* copy c'tor
*/
OPimRecord( const OPimRecord& rec );
/**
@@ -35,24 +42,25 @@ public:
* set category names they will be resolved
*/
void setCategoryNames( const QStringList& );
/**
* addCategoryName adds a name
* to the internal category list
*/
void addCategoryName( const QString& );
/**
* if a Record isEmpty
+ * it's empty if it's 0
*/
virtual bool isEmpty()const;
/**
* toRichText summary
*/
virtual QString toRichText()const = 0;
/**
* a small one line summary
*/
virtual QString toShortText()const = 0;
@@ -79,37 +87,42 @@ public:
/**
* the related apps names
*/
QStringList relatedApps()const;
/**
* the realtions between an app
*/
QArray<int> relations( const QString& app )const;
/**
- *
+ * clear the relations for all relations
+ * with app
*/
void clearRelation( const QString& app );
/**
- *
+ * add a relation
*/
void addRelation( const QString& app, int id );
/**
- *
+ * set the relations for an app
*/
void setRelations( const QString&, QArray<int> ids );
+
+ /**
+ * set the uid
+ */
virtual void setUid( int uid );
protected:
Qtopia::UidGen &uidGen();
QString crossToString()const;
private:
class OPimRecordPrivate;
OPimRecordPrivate *d;
QMap<QString, QArray<int> > m_relations;
static Qtopia::UidGen m_uidGen;
diff --git a/libopie2/opiepim/core/otemplatebase.h b/libopie2/opiepim/core/otemplatebase.h
index 41cc934..add1de4 100644
--- a/libopie2/opiepim/core/otemplatebase.h
+++ b/libopie2/opiepim/core/otemplatebase.h
@@ -1,17 +1,20 @@
#ifndef OPIE_TEMPLATE_BASE_H
#define OPIE_TEMPLATE_BASE_H
#include "opimrecord.h"
+/**
+ * internal template base
+ */
template <class T = OPimRecord>
class OTemplateBase {
public:
OTemplateBase() {
};
virtual ~OTemplateBase() {
}
virtual T find( int uid ) = 0;
};
diff --git a/libopie2/opiepim/orecordlist.h b/libopie2/opiepim/orecordlist.h
index a3955b0..3b30a73 100644
--- a/libopie2/opiepim/orecordlist.h
+++ b/libopie2/opiepim/orecordlist.h
@@ -1,59 +1,95 @@
#ifndef OPIE_RECORD_LIST_H
#define OPIE_RECORD_LIST_H
#include <qarray.h>
#include "otemplatebase.h"
#include "opimrecord.h"
-
+/**
+ * Our List Iterator
+ * it behaves like STL or Qt
+ *
+ * for(it = list.begin(); it != list.end(); ++it )
+ * doSomeCoolStuff( (*it) );
+ */
template <class T = OPimRecord>
class ORecordListIterator {
public:
typedef OTemplateBase<T> Base;
+
+ /**
+ * The c'tor used internally from
+ * ORecordList
+ */
ORecordListIterator( const QArray<int>, const Base* );
+
+ /**
+ * The standard c'tor
+ */
ORecordListIterator();
~ORecordListIterator();
+
ORecordListIterator( const ORecordListIterator& );
ORecordListIterator &operator=(const ORecordListIterator& );
+
+ /**
+ * a * operator ;)
+ * use it like this T = (*it);
+ */
T &operator*();
ORecordListIterator &operator++();
ORecordListIterator &operator--();
bool operator==( const ORecordListIterator& it );
bool operator!=( const ORecordListIterator& it );
private:
QArray<int> m_uids;
int m_current;
const Base* m_temp;
bool m_end : 1;
T m_record;
/* d pointer for future versions */
class IteratorPrivate;
IteratorPrivate *d;
};
-
+/**
+ * The recordlist used as a return type
+ * from OPimAccessTemplate
+ */
template <class T = OPimRecord >
class ORecordList {
public:
typedef OTemplateBase<T> Base;
typedef ORecordListIterator<T> Iterator;
+
+ /**
+ * c'tor
+ */
ORecordList( const QArray<int>& ids,
const Base* );
~ORecordList();
+
+ /**
+ * the first iterator
+ */
Iterator begin();
+
+ /**
+ * the end
+ */
Iterator end();
/*
ConstIterator begin()const;
ConstIterator end()const;
*/
private:
QArray<int> m_ids;
const Base* m_acc;
};
/* ok now implement it */
template <class T>